1/* 2 * Copyright (c) 2021 Apple Inc. All rights reserved. 3 * 4 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ 5 * 6 * This file contains Original Code and/or Modifications of Original Code 7 * as defined in and that are subject to the Apple Public Source License 8 * Version 2.0 (the 'License'). You may not use this file except in 9 * compliance with the License. The rights granted to you under the License 10 * may not be used to create, or enable the creation or redistribution of, 11 * unlawful or unlicensed copies of an Apple operating system, or to 12 * circumvent, violate, or enable the circumvention or violation of, any 13 * terms of an Apple operating system software license agreement. 14 * 15 * Please obtain a copy of the License at 16 * http://www.opensource.apple.com/apsl/ and read it before using this file. 17 * 18 * The Original Code and all software distributed under the License are 19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER 20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, 21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, 22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. 23 * Please see the License for the specific language governing rights and 24 * limitations under the License. 25 * 26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ 27 */ 28 29#ifndef _IOKIT_UIOWORKGROUP_H 30#define _IOKIT_UIOWORKGROUP_H 31 32#include <DriverKit/OSObject.iig> 33#include <DriverKit/IOUserClient.iig> 34 35enum { 36 kIOWorkGroupMaxNameLength = 64, 37}; 38 39/*! 40 * @class IOWorkGroup 41 * 42 * @abstract 43 * Workgroups allow multiple threads to coordinate activities for realtime operations. 44 * 45 * @discussion 46 * 47 * Applications that open user clients to a DriverKit driver can send a workgroup to use in the driver. 48 * 49 * The application will have to first create an workgroup object. The application then should copy the 50 * workgroup port with os_workgroup_copy_port(). To send the workgroup port to the driver, use: 51 * 52 * const char * name = "Work Group Name"; // This must match the name the driver used in IOWorkGroup::Create(). 53 * kern_return_t ret = IOConnectTrap3(connect, // user client connection (io_connect_t) 54 * 1, // specifies event link configuration trap 55 * (uintptr_t)name, 56 * (uintptr_t)strlen(name), 57 * (uintptr_t)wgPort // port from os_workgroup_copy_port 58 * ); 59 * 60 * Once the workgroup port has been sent to the driver, the driver should be notified with a user-defined external method 61 * or other existing signaling mechanism. 62 */ 63class NATIVE KERNEL IOWorkGroup : public OSObject 64{ 65public: 66 67 virtual bool 68 init() override; 69 70 virtual void 71 free() override; 72 73 /*! 74 * @brief Create an IOWorkGroup object. This object is not functional until a workgroup port has been set. 75 * @param name Name of the workgroup 76 * @param userClient Userclient to create the workgroup in. The DriverKit runtime will retain the userclient, and will 77 * release it in Invalidate() or when the IOWorkGroup is freed. 78 * @param workgroup Created IOWorkGroup with +1 retain count to be released by the caller. 79 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 80 */ 81 static kern_return_t 82 Create(OSString * name, IOUserClient * userClient, IOWorkGroup ** workgroup) LOCAL; 83 84#if DRIVERKIT_PRIVATE 85 86 /*! 87 * @brief Set the port for this workgroup. This should not be called directly. 88 * @param port Workgroup port 89 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 90 */ 91 virtual kern_return_t 92 SetWorkGroupPort(mach_port_t port PORTCOPYSEND) LOCAL; 93 94#endif /* DRIVERKIT_PRIVATE */ 95 96 /*! 97 * @brief Get the size of the workgroup token. 98 * @discussion Join() and Leave() require the caller to pass a token. This token should be allocated by the caller, and freed when 99 * no longer needed. Use this method to determine how much memory to allocate for the token. 100 * @return Workgroup token size 101 */ 102 size_t 103 GetTokenSize() LOCALONLY; 104 105 /*! 106 * @brief Join the workgroup. 107 * @discussion Before calling this method, the caller must allocate a token. This token must be passed to this method. When leaving 108 * a workgroup with Leave(), use the same token that was passed to Join(). 109 * @param token The workgroup token. 110 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 111 */ 112 kern_return_t 113 Join(void * token) LOCALONLY; 114 115 /*! 116 * @brief Leave the workgroup. 117 * @discussion The workgroup must have been joined with Join(). Use the same token in Join() for this method. 118 * @param token The workgroup token. 119 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 120 */ 121 kern_return_t 122 Leave(void * token) LOCALONLY; 123 124 /*! 125 * @brief Invalidate the IOWorkGroup. 126 * @discussion This releases the kernel reference to the IOWorkGroup, allowing the name to be used for a different 127 * IOWorkGroup. This method should be called after the client has configured the eventlink with the IOConnectTrap 128 * call. After invalidation, the IOWorkGroup can no longer be configured through the IOConnectTrap call. No other 129 * functionality is affected. 130 * @return kIOReturnSuccess on success. See IOReturn.h for error codes. 131 */ 132 kern_return_t 133 Invalidate() LOCALONLY; 134 135#if DRIVERKIT_PRIVATE 136 137 virtual kern_return_t 138 InvalidateKernel(IOUserClient * client); 139 140#endif /* DRIVERKIT_PRIVATE */ 141 142}; 143 144#endif /* ! _IOKIT_UIOWORKGROUP_H */ 145