[apple/xnu.git] / iokit / DriverKit / IOService.iig

/*
 * Copyright (c) 2019-2019 Apple Inc. All rights reserved.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_START@
 *
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * unlawful or unlicensed copies of an Apple operating system, or to
 * circumvent, violate, or enable the circumvention or violation of, any
 * terms of an Apple operating system software license agreement.
 *
 * Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this file.
 *
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 *
 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
 */

#if !__IIG
#if KERNEL
#include <IOKit/IOService.h>
#endif
#endif

#ifndef _IOKIT_UIOSERVICE_H
#define _IOKIT_UIOSERVICE_H

#include <DriverKit/OSObject.iig>

class IOMemoryDescriptor;
class IOBufferMemoryDescriptor;
class IOUserClient;

typedef char IOServiceName[128];
typedef char IOPropertyName[128];
typedef char IORegistryPlaneName[128];

enum {
	kIOServiceSearchPropertyParents = 0x00000001,
};

#define kIOServiceDefaultQueueName	"Default"

enum {
	kIOServicePowerCapabilityOff = 0x00000000,
	kIOServicePowerCapabilityOn  = 0x00000002,
	kIOServicePowerCapabilityLow = 0x00010000,
};

/*!
 * @class IOService
 *
 * @abstract
 * IOService represents an device or OS service in IOKit and DriverKit.
 *
 * @discussion
 * IOKit provides driver lifecycle management through the IOService APIs. 
 * Drivers and devices are represented as subclasses of IOService.
 *

@iig implementation
#include <DriverKit/IOUserClient.h>
@iig end
*/

class KERNEL IOService : public OSObject
{
public:
	virtual bool
	init() override;

	virtual void
	free() override;

    /*!
     * @brief       First call made to a matched IOService.
     * @discussion  During matching IOKit will create an IOService object for successful matches.
     *              Start is the first call made to the new object.
     * @param       provider The IOService provider for the match. This should be OSRequiredCast to the expected class.
     *              The provider is retained by DriverKit for the duration of Start() and on successful Start() until
     *              IOService::Stop() is called.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	Start(IOService * provider) LOCAL;

    /*!
     * @brief       Terminate access to provider.
     * @discussion  During termination IOKit will teardown any IOService objects attached to a terminated provider.
     *              Stop should quiesce all activity and when complete, pass the call to super. After calling super, the
     *              provider is no longer valid and this object will likely be freed.
     * @param       provider The IOService provider for being terminated, one previously passed to Start
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	Stop(IOService * provider) LOCAL;

    /*!
     * @brief       Obtain IOKit IORegistryEntryID.
     * @param       registryEntryID IORegistryEntryID for the IOKit object.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	GetRegistryEntryID(uint64_t * registryEntryID) LOCAL;

    /*!
     * @brief       Set the IORegistryEntry name.
     * @param       name Name for the IOKit object. The c-string will be copied.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	SetName(
	const IOServiceName name);

    /*!
     * @brief       Start the matching process on the IOService object.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	RegisterService();

    /*!
     * @brief       Set the IODispatchQueue for a given name on the IOService.
     * @param       name Name for the queue. The name may be referenced by methods in the .iig class definition
     *              with the QUEUENAME() attribute to indicate the method must be invoked on that queue. If a method
     *              is invoked before the queue is set for the name, the default queue is used. A default queue is
     *              created by DriverKit for every new IOService object with the name kIOServiceDefaultQueueName.
     * @param       queue Queue to be associated with the name on this IOService.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	SetDispatchQueue(
		const IODispatchQueueName name,
		IODispatchQueue         * queue) override LOCAL;

    /*!
     * @brief       Obtain the IODispatchQueue for a given name on the IOService.
     * @param       name Name for the queue.
     * @param       queue Returned, retained queue or NULL. The caller should release this queue.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	CopyDispatchQueue(
		const IODispatchQueueName name,
		IODispatchQueue        ** queue) override;

    /*!
     * @brief       Obtain the IOKit registry properties for the IOService.
     * @param       properties Returned, retained dictionary of properties or NULL. The caller should release this dictionary.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	CopyProperties(
		OSDictionary ** properties);

    /*!
     * @brief       Obtain the an IOKit registry properties from the service or one of its parents.
     * @param       name Name of the property as a c-string.
     * @param       plane Name of the registry plane to be searched, if the option kIOServiceSearchPropertyParents
     *              is used.
     * @param       options Pass kIOServiceSearchPropertyParents to search for the property in the IOService and all
     *              its parents in the IOKit registry.
     * @param       property Returned, retained property object or NULL. The caller should release this property.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	SearchProperty(
		const IOPropertyName name,
		const IORegistryPlaneName plane,
		uint64_t options,
		OSContainer ** property);

    /*!
     * @brief       Send a dictionary of properties to an IOService.
     * @discussion  By default the method will fail. A DriverKit subclass or kernel class may implement this method.
     * @param       properties Dictionary of properties.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	SetProperties(
		OSDictionary * properties);

    /*!
     * @brief       Notification of change in power state of a provider.
     * @discussion  DriverKit notifies of changes in power of a provider. The driver should make itself safe for
     *              the new state before passing the call to super. 
     * @param       powerFlags The power capabilities of the new state. The values possible are:
	 *	kIOServicePowerCapabilityOff the system will be entering sleep state
	 *	kIOServicePowerCapabilityOn  the device and system are fully powered
	 *  kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	SetPowerState(
		uint32_t powerFlags) LOCAL;

    /*!
     * @brief       Allow provider to enter a low power state.
     * @discussion  A driver may allow a device to enter a lower power state. 
     * @param       powerFlags The power capabilities of the new state. The values possible are:
	 *  kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	ChangePowerState(
		uint32_t powerFlags);

    /*!
     * @brief       Request create a new user client for a client process.
     * @discussion  An application may request an IOUserClient be opened with the IOKit framework
     *              IOServiceOpen() call. The type parameter of that call is passed here. The driver should respond to
     *              the call by calling IOService::Create() with a plist entry describing the new user client object.
     * @param       type The type passed to IOServiceOpen().
     * @param       userClient The object created by IOService::Create()
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	NewUserClient(
		uint32_t type,
		IOUserClient ** userClient);

    /*!
     * @brief       Request to create an IOService object from a plist property.
     * @discussion  An IOService interface or IOUserClient subclass may be created from a plist property of the driver.
     *              The plist should contain the following IOKit matching keys:
     *              IOClass - kernel class of IOUserUserClient
     *              IOUserClass - DriverKit class to be instantiated
     *              IOServiceDEXTEntitlements - Array of entitlements to be checked against a user client owning task
     * @param       provider The provider of the new object.
     * @param       propertiesKey The name of the properties dictionary in this IOService
     * @param       result The created object retained, to be released by the caller.
     * @return      kIOReturnSuccess on success. See IOReturn.h for error codes.
     */
	virtual kern_return_t
	Create(
		IOService          * provider,
		const IOPropertyName propertiesKey,
		IOService         ** result);
};

#endif /* ! _IOKIT_UIOSERVICE_H */
Commit	Line	Data
cb323159 A	1	/*
	2	* Copyright (c) 2019-2019 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	#if !__IIG
	30	#if KERNEL
	31	#include <IOKit/IOService.h>
	32	#endif
	33	#endif
	34
	35	#ifndef _IOKIT_UIOSERVICE_H
	36	#define _IOKIT_UIOSERVICE_H
	37
	38	#include <DriverKit/OSObject.iig>
	39
	40	class IOMemoryDescriptor;
	41	class IOBufferMemoryDescriptor;
	42	class IOUserClient;
	43
	44	typedef char IOServiceName[128];
	45	typedef char IOPropertyName[128];
	46	typedef char IORegistryPlaneName[128];
	47
	48	enum {
	49	kIOServiceSearchPropertyParents = 0x00000001,
	50	};
	51
	52	#define kIOServiceDefaultQueueName "Default"
	53
	54	enum {
	55	kIOServicePowerCapabilityOff = 0x00000000,
	56	kIOServicePowerCapabilityOn = 0x00000002,
	57	kIOServicePowerCapabilityLow = 0x00010000,
	58	};
	59
	60	/*!
	61	* @class IOService
	62	*
	63	* @abstract
	64	* IOService represents an device or OS service in IOKit and DriverKit.
65	*
66	* @discussion
67	* IOKit provides driver lifecycle management through the IOService APIs.
68	* Drivers and devices are represented as subclasses of IOService.
69	*
70
71	@iig implementation
72	#include <DriverKit/IOUserClient.h>
73	@iig end
74	*/
75
76	class KERNEL IOService : public OSObject
77	{
78	public:
79	virtual bool
80	init() override;
81
82	virtual void
83	free() override;
84
85	/*!
86	* @brief First call made to a matched IOService.
87	* @discussion During matching IOKit will create an IOService object for successful matches.
88	* Start is the first call made to the new object.
89	* @param provider The IOService provider for the match. This should be OSRequiredCast to the expected class.
90	* The provider is retained by DriverKit for the duration of Start() and on successful Start() until
91	* IOService::Stop() is called.
92	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
93	*/
94	virtual kern_return_t
95	Start(IOService * provider) LOCAL;
96
97	/*!
98	* @brief Terminate access to provider.
99	* @discussion During termination IOKit will teardown any IOService objects attached to a terminated provider.
100	* Stop should quiesce all activity and when complete, pass the call to super. After calling super, the
101	* provider is no longer valid and this object will likely be freed.
102	* @param provider The IOService provider for being terminated, one previously passed to Start
103	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
104	*/
105	virtual kern_return_t
106	Stop(IOService * provider) LOCAL;
107
108	/*!
109	* @brief Obtain IOKit IORegistryEntryID.
110	* @param registryEntryID IORegistryEntryID for the IOKit object.
111	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
112	*/
113	virtual kern_return_t
114	GetRegistryEntryID(uint64_t * registryEntryID) LOCAL;
115
116	/*!
117	* @brief Set the IORegistryEntry name.
118	* @param name Name for the IOKit object. The c-string will be copied.
119	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
120	*/
121	virtual kern_return_t
122	SetName(
123	const IOServiceName name);
124
125	/*!
126	* @brief Start the matching process on the IOService object.
127	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
128	*/
129	virtual kern_return_t
130	RegisterService();
131
132	/*!
133	* @brief Set the IODispatchQueue for a given name on the IOService.
134	* @param name Name for the queue. The name may be referenced by methods in the .iig class definition
135	* with the QUEUENAME() attribute to indicate the method must be invoked on that queue. If a method
136	* is invoked before the queue is set for the name, the default queue is used. A default queue is
137	* created by DriverKit for every new IOService object with the name kIOServiceDefaultQueueName.
138	* @param queue Queue to be associated with the name on this IOService.
139	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
140	*/
141	virtual kern_return_t
142	SetDispatchQueue(
143	const IODispatchQueueName name,
144	IODispatchQueue * queue) override LOCAL;
145
146	/*!
147	* @brief Obtain the IODispatchQueue for a given name on the IOService.
148	* @param name Name for the queue.
149	* @param queue Returned, retained queue or NULL. The caller should release this queue.
150	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
151	*/
152	virtual kern_return_t
153	CopyDispatchQueue(
154	const IODispatchQueueName name,
155	IODispatchQueue ** queue) override;
156
157	/*!
158	* @brief Obtain the IOKit registry properties for the IOService.
159	* @param properties Returned, retained dictionary of properties or NULL. The caller should release this dictionary.
160	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
161	*/
162	virtual kern_return_t
163	CopyProperties(
164	OSDictionary ** properties);
165
166	/*!
167	* @brief Obtain the an IOKit registry properties from the service or one of its parents.
168	* @param name Name of the property as a c-string.
169	* @param plane Name of the registry plane to be searched, if the option kIOServiceSearchPropertyParents
170	* is used.
171	* @param options Pass kIOServiceSearchPropertyParents to search for the property in the IOService and all
172	* its parents in the IOKit registry.
173	* @param property Returned, retained property object or NULL. The caller should release this property.
174	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
175	*/
176	virtual kern_return_t
177	SearchProperty(
178	const IOPropertyName name,
179	const IORegistryPlaneName plane,
180	uint64_t options,
181	OSContainer ** property);
182
183	/*!
184	* @brief Send a dictionary of properties to an IOService.
185	* @discussion By default the method will fail. A DriverKit subclass or kernel class may implement this method.
186	* @param properties Dictionary of properties.
187	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
188	*/
189	virtual kern_return_t
190	SetProperties(
191	OSDictionary * properties);
192
193	/*!
194	* @brief Notification of change in power state of a provider.
195	* @discussion DriverKit notifies of changes in power of a provider. The driver should make itself safe for
196	* the new state before passing the call to super.
197	* @param powerFlags The power capabilities of the new state. The values possible are:
198	* kIOServicePowerCapabilityOff the system will be entering sleep state
199	* kIOServicePowerCapabilityOn the device and system are fully powered
200	* kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
201	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
202	*/
203	virtual kern_return_t
204	SetPowerState(
205	uint32_t powerFlags) LOCAL;
206
207	/*!
208	* @brief Allow provider to enter a low power state.
209	* @discussion A driver may allow a device to enter a lower power state.
210	* @param powerFlags The power capabilities of the new state. The values possible are:
211	* kIOServicePowerCapabilityLow the device is in a reduced power state while the system is running
212	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
213	*/
214	virtual kern_return_t
215	ChangePowerState(
216	uint32_t powerFlags);
217
218	/*!
219	* @brief Request create a new user client for a client process.
220	* @discussion An application may request an IOUserClient be opened with the IOKit framework
221	* IOServiceOpen() call. The type parameter of that call is passed here. The driver should respond to
222	* the call by calling IOService::Create() with a plist entry describing the new user client object.
223	* @param type The type passed to IOServiceOpen().
224	* @param userClient The object created by IOService::Create()
225	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
226	*/
227	virtual kern_return_t
228	NewUserClient(
229	uint32_t type,
230	IOUserClient ** userClient);
231
232	/*!
233	* @brief Request to create an IOService object from a plist property.
234	* @discussion An IOService interface or IOUserClient subclass may be created from a plist property of the driver.
235	* The plist should contain the following IOKit matching keys:
236	* IOClass - kernel class of IOUserUserClient
237	* IOUserClass - DriverKit class to be instantiated
238	* IOServiceDEXTEntitlements - Array of entitlements to be checked against a user client owning task
239	* @param provider The provider of the new object.
240	* @param propertiesKey The name of the properties dictionary in this IOService
241	* @param result The created object retained, to be released by the caller.
242	* @return kIOReturnSuccess on success. See IOReturn.h for error codes.
243	*/
244	virtual kern_return_t
245	Create(
246	IOService * provider,
247	const IOPropertyName propertiesKey,
248	IOService ** result);
249	};
250
251	#endif /* ! _IOKIT_UIOSERVICE_H */