[apple/xnu.git] / iokit / IOKit / IODataQueue.h

/*
 * Copyright (c) 1998-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@
 */

#ifndef _IOKIT_IODATAQUEUE_H
#define _IOKIT_IODATAQUEUE_H

#ifndef DISABLE_DATAQUEUE_WARNING
#warning "IODataQueue is deprecated due to security issues in its interfaces, please use IOSharedDataQueue instead"
#endif


#include <libkern/c++/OSObject.h>
#include <libkern/OSTypes.h>
#include <mach/port.h>
#include <mach/message.h>

typedef struct _IODataQueueMemory IODataQueueMemory;
class IOMemoryDescriptor;

struct _notifyMsg {
	mach_msg_header_t h;
};


#ifdef dequeue
#undef dequeue
#endif
#ifdef enqueue
#undef enqueue
#endif

/*!
 * @class IODataQueue : public OSObject
 * @abstract A generic queue designed to pass data from the kernel to a user process.
 * @discussion The IODataQueue class is designed to allow kernel code to queue data to a user process.  IODataQueue objects are designed to be used in a single producer / single consumer situation.  As such, there are no locks on the data itself.  Because the kernel enqueue and user-space dequeue methods follow a strict set of guidelines, no locks are necessary to maintain the integrity of the data struct.
 *
 * <br>Each data entry can be variable sized, but the entire size of the queue data region (including overhead for each entry) must be specified up front.
 *
 * <br>In order for the IODataQueue instance to notify the user process that data is available, a notification mach port must be set.  When the queue is empty and a new entry is added, a message is sent to the specified port.
 *
 * <br>User client code exists in the IOKit framework that facilitates the creation of the receive notification port as well as the listen process for new data available notifications.
 *
 * <br>In order to make the data queue memory available to a user process, the method getMemoryDescriptor() must be used to get an IOMemoryDescriptor instance that can be mapped into a user process.  Typically, the clientMemoryForType() method on an IOUserClient instance will be used to request the IOMemoryDescriptor and then return it to be mapped into the user process.
 */
#ifndef DISABLE_DATAQUEUE_WARNING
class __attribute__((deprecated)) IODataQueue: public OSObject
#else
class IODataQueue : public OSObject
#endif
{
	OSDeclareDefaultStructors(IODataQueue);

protected:
	IODataQueueMemory * dataQueue;

	void *              notifyMsg;

	virtual void free() APPLE_KEXT_OVERRIDE;

/*!
 * @function sendDataAvailableNotification
 * @abstract Sends a dataAvailableNotification message to the specified mach port.
 * @discussion This method sends a message to the mach port passed to setNotificationPort().  It is used to indicate that data is available in the queue.
 */
	virtual void sendDataAvailableNotification();

public:
/*!
 * @function withCapacity
 * @abstract Static method that creates a new IODataQueue instance with the capacity specified in the size parameter.
 * @discussion The actual size of the entire data queue memory region (to be shared into a user process) is equal to the capacity plus the IODataQueueMemory overhead.  This overhead value can be determined from the DATA_QUEUE_MEMORY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.  The size of the data queue memory region must include space for the overhead of each IODataQueueEntry.  This entry overhead can be determined from the DATA_QUEUE_ENTRY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.<br>  This method allocates a new IODataQueue instance and then calls initWithCapacity() with the given size parameter.  If the initWithCapacity() fails, the new instance is released and zero is returned.
 * @param size The size of the data queue memory region.
 * @result Returns the newly allocated IODataQueue instance.  Zero is returned on failure.
 */
	static IODataQueue *withCapacity(UInt32 size);

/*!
 * @function withEntries
 * @abstract Static method that creates a new IODataQueue instance with the specified number of entries of the given size.
 * @discussion This method will create a new IODataQueue instance with enough capacity for numEntries of entrySize.  It does account for the IODataQueueEntry overhead for each entry.  Note that the numEntries and entrySize are simply used to determine the data region size.  They do not actually restrict the size of number of entries that can be added to the queue.<br>  This method allocates a new IODataQueue instance and then calls initWithEntries() with the given numEntries and entrySize parameters.  If the initWithEntries() fails, the new instance is released and zero is returned.
 * @param numEntries Number of entries to allocate space for.
 * @param entrySize Size of each entry.
 * @result Reeturns the newly allocated IODataQueue instance.  Zero is returned on failure.
 */
	static IODataQueue *withEntries(UInt32 numEntries, UInt32 entrySize);

/*!
 * @function initWithCapacity
 * @abstract Initializes an IODataQueue instance with the capacity specified in the size parameter.
 * @discussion The actual size of the entire data queue memory region (to be shared into a user process) is equal to the capacity plus the IODataQueueMemory overhead.  This overhead value can be determined from the DATA_QUEUE_MEMORY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.  The size of the data queue memory region must include space for the overhead of each IODataQueueEntry.  This entry overhead can be determined from the DATA_QUEUE_ENTRY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.
 * @param size The size of the data queue memory region.
 * @result Returns true on success and false on failure.
 */
	virtual Boolean initWithCapacity(UInt32 size);

/*!
 * @function initWithEntries
 * @abstract Initializes an IODataQueue instance with the specified number of entries of the given size.
 * @discussion This method will initialize an IODataQueue instance with enough capacity for numEntries of entrySize.  It does account for the IODataQueueEntry overhead for each entry.  Note that the numEntries and entrySize are simply used to determine the data region size.  They do not actually restrict the size of number of entries that can be added to the queue.<br>  This method allocates a new IODataQueue instance and then calls initWithEntries() with the given numEntries and entrySize parameters.
 * @param numEntries Number of entries to allocate space for.
 * @param entrySize Size of each entry.
 * @result Reeturns true on success and false on failure.
 */
	virtual Boolean initWithEntries(UInt32 numEntries, UInt32 entrySize);

/*!
 * @function enqueue
 * @abstract Enqueues a new entry on the queue.
 * @discussion This method adds a new data entry of dataSize to the queue.  It sets the size parameter of the entry pointed to by the tail value and copies the memory pointed to by the data parameter in place in the queue.  Once that is done, it moves the tail to the next available location.  When attempting to add a new entry towards the end of the queue and there isn't enough space at the end, it wraps back to the beginning.<br>  If the queue is empty when a new entry is added, sendDataAvailableNotification() is called to send a message to the user process that data is now available.
 * @param data Pointer to the data to be added to the queue.
 * @param dataSize Size of the data pointed to by data.
 * @result Returns true on success and false on failure.  Typically failure means that the queue is full.
 */
	virtual Boolean enqueue(void *data, UInt32 dataSize);

/*!
 * @function setNotificationPort
 * @abstract Creates a simple mach message targeting the mach port specified in port.
 * @discussion This message is sent when data is added to an empty queue.  It is to notify a user process that new data has become available.
 * @param port The mach port to target with the notification message.
 */
	virtual void setNotificationPort(mach_port_t port);

/*!
 * @function getMemoryDescriptor
 * @abstract Returns a memory descriptor covering the IODataQueueMemory region.
 * @discussion The IOMemoryDescriptor instance returned by this method is intended to be mapped into a user process.  This is the memory region that the IODataQueueClient code operates on.
 * @result Returns a newly allocated IOMemoryDescriptor for the IODataQueueMemory region.  Returns zero on failure.
 */
	virtual IOMemoryDescriptor *getMemoryDescriptor();
};

#endif /* _IOKIT_IODATAQUEUE_H */
Commit	Line	Data
1c79356b	1	/*
cb323159	2	* Copyright (c) 1998-2019 Apple Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
0a7de745	5	*
2d21ac55 A	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.
0a7de745	14	*
2d21ac55 A	15	* Please obtain a copy of the License at
2d21ac55 A	16	* http://www.opensource.apple.com/apsl/ and read it before using this file.
0a7de745	17	*
2d21ac55 A	18	* The Original Code and all software distributed under the License are
2d21ac55 A	19	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	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.
0a7de745	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	27	*/
	28
	29	#ifndef _IOKIT_IODATAQUEUE_H
	30	#define _IOKIT_IODATAQUEUE_H
	31
fe8ab488 A	32	#ifndef DISABLE_DATAQUEUE_WARNING
	33	#warning "IODataQueue is deprecated due to security issues in its interfaces, please use IOSharedDataQueue instead"
	34	#endif
	35
	36
1c79356b A	37	#include <libkern/c++/OSObject.h>
	38	#include <libkern/OSTypes.h>
	39	#include <mach/port.h>
	40	#include <mach/message.h>
	41
	42	typedef struct _IODataQueueMemory IODataQueueMemory;
	43	class IOMemoryDescriptor;
	44
	45	struct _notifyMsg {
0a7de745	46	mach_msg_header_t h;
1c79356b A	47	};
1c79356b A	48
cb323159 A	49
	50	#ifdef dequeue
	51	#undef dequeue
	52	#endif
	53	#ifdef enqueue
	54	#undef enqueue
	55	#endif
	56
1c79356b A	57	/*!
	58	* @class IODataQueue : public OSObject
	59	* @abstract A generic queue designed to pass data from the kernel to a user process.
	60	* @discussion The IODataQueue class is designed to allow kernel code to queue data to a user process. IODataQueue objects are designed to be used in a single producer / single consumer situation. As such, there are no locks on the data itself. Because the kernel enqueue and user-space dequeue methods follow a strict set of guidelines, no locks are necessary to maintain the integrity of the data struct.
	61	*
	62	* <br>Each data entry can be variable sized, but the entire size of the queue data region (including overhead for each entry) must be specified up front.
	63	*
	64	* <br>In order for the IODataQueue instance to notify the user process that data is available, a notification mach port must be set. When the queue is empty and a new entry is added, a message is sent to the specified port.
	65	*
	66	* <br>User client code exists in the IOKit framework that facilitates the creation of the receive notification port as well as the listen process for new data available notifications.
	67	*
	68	* <br>In order to make the data queue memory available to a user process, the method getMemoryDescriptor() must be used to get an IOMemoryDescriptor instance that can be mapped into a user process. Typically, the clientMemoryForType() method on an IOUserClient instance will be used to request the IOMemoryDescriptor and then return it to be mapped into the user process.
	69	*/
0a7de745 A	70	#ifndef DISABLE_DATAQUEUE_WARNING
	71	class __attribute__((deprecated)) IODataQueue: public OSObject
	72	#else
1c79356b	73	class IODataQueue : public OSObject
fe8ab488	74	#endif
1c79356b	75	{
cb323159	76	OSDeclareDefaultStructors(IODataQueue);
1c79356b A	77
1c79356b A	78	protected:
0a7de745	79	IODataQueueMemory * dataQueue;
1c79356b	80
0a7de745	81	void * notifyMsg;
1c79356b	82
0a7de745	83	virtual void free() APPLE_KEXT_OVERRIDE;
1c79356b	84
0a7de745 A	85	/*!
	86	* @function sendDataAvailableNotification
	87	* @abstract Sends a dataAvailableNotification message to the specified mach port.
	88	* @discussion This method sends a message to the mach port passed to setNotificationPort(). It is used to indicate that data is available in the queue.
	89	*/
	90	virtual void sendDataAvailableNotification();
1c79356b A	91
1c79356b A	92	public:
0a7de745 A	93	/*!
	94	* @function withCapacity
	95	* @abstract Static method that creates a new IODataQueue instance with the capacity specified in the size parameter.
	96	* @discussion The actual size of the entire data queue memory region (to be shared into a user process) is equal to the capacity plus the IODataQueueMemory overhead. This overhead value can be determined from the DATA_QUEUE_MEMORY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>. The size of the data queue memory region must include space for the overhead of each IODataQueueEntry. This entry overhead can be determined from the DATA_QUEUE_ENTRY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.<br> This method allocates a new IODataQueue instance and then calls initWithCapacity() with the given size parameter. If the initWithCapacity() fails, the new instance is released and zero is returned.
	97	* @param size The size of the data queue memory region.
	98	* @result Returns the newly allocated IODataQueue instance. Zero is returned on failure.
	99	*/
	100	static IODataQueue *withCapacity(UInt32 size);
	101
	102	/*!
	103	* @function withEntries
	104	* @abstract Static method that creates a new IODataQueue instance with the specified number of entries of the given size.
	105	* @discussion This method will create a new IODataQueue instance with enough capacity for numEntries of entrySize. It does account for the IODataQueueEntry overhead for each entry. Note that the numEntries and entrySize are simply used to determine the data region size. They do not actually restrict the size of number of entries that can be added to the queue.<br> This method allocates a new IODataQueue instance and then calls initWithEntries() with the given numEntries and entrySize parameters. If the initWithEntries() fails, the new instance is released and zero is returned.
	106	* @param numEntries Number of entries to allocate space for.
	107	* @param entrySize Size of each entry.
	108	* @result Reeturns the newly allocated IODataQueue instance. Zero is returned on failure.
	109	*/
	110	static IODataQueue *withEntries(UInt32 numEntries, UInt32 entrySize);
	111
	112	/*!
	113	* @function initWithCapacity
	114	* @abstract Initializes an IODataQueue instance with the capacity specified in the size parameter.
	115	* @discussion The actual size of the entire data queue memory region (to be shared into a user process) is equal to the capacity plus the IODataQueueMemory overhead. This overhead value can be determined from the DATA_QUEUE_MEMORY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>. The size of the data queue memory region must include space for the overhead of each IODataQueueEntry. This entry overhead can be determined from the DATA_QUEUE_ENTRY_HEADER_SIZE macro in <IOKit/IODataQueueShared.h>.
	116	* @param size The size of the data queue memory region.
	117	* @result Returns true on success and false on failure.
	118	*/
	119	virtual Boolean initWithCapacity(UInt32 size);
	120
	121	/*!
	122	* @function initWithEntries
	123	* @abstract Initializes an IODataQueue instance with the specified number of entries of the given size.
	124	* @discussion This method will initialize an IODataQueue instance with enough capacity for numEntries of entrySize. It does account for the IODataQueueEntry overhead for each entry. Note that the numEntries and entrySize are simply used to determine the data region size. They do not actually restrict the size of number of entries that can be added to the queue.<br> This method allocates a new IODataQueue instance and then calls initWithEntries() with the given numEntries and entrySize parameters.
	125	* @param numEntries Number of entries to allocate space for.
	126	* @param entrySize Size of each entry.
	127	* @result Reeturns true on success and false on failure.
	128	*/
	129	virtual Boolean initWithEntries(UInt32 numEntries, UInt32 entrySize);
	130
	131	/*!
	132	* @function enqueue
	133	* @abstract Enqueues a new entry on the queue.
	134	* @discussion This method adds a new data entry of dataSize to the queue. It sets the size parameter of the entry pointed to by the tail value and copies the memory pointed to by the data parameter in place in the queue. Once that is done, it moves the tail to the next available location. When attempting to add a new entry towards the end of the queue and there isn't enough space at the end, it wraps back to the beginning.<br> If the queue is empty when a new entry is added, sendDataAvailableNotification() is called to send a message to the user process that data is now available.
	135	* @param data Pointer to the data to be added to the queue.
	136	* @param dataSize Size of the data pointed to by data.
	137	* @result Returns true on success and false on failure. Typically failure means that the queue is full.
	138	*/
	139	virtual Boolean enqueue(void *data, UInt32 dataSize);
	140
	141	/*!
	142	* @function setNotificationPort
	143	* @abstract Creates a simple mach message targeting the mach port specified in port.
	144	* @discussion This message is sent when data is added to an empty queue. It is to notify a user process that new data has become available.
	145	* @param port The mach port to target with the notification message.
	146	*/
	147	virtual void setNotificationPort(mach_port_t port);
	148
	149	/*!
	150	* @function getMemoryDescriptor
	151	* @abstract Returns a memory descriptor covering the IODataQueueMemory region.
	152	* @discussion The IOMemoryDescriptor instance returned by this method is intended to be mapped into a user process. This is the memory region that the IODataQueueClient code operates on.
	153	* @result Returns a newly allocated IOMemoryDescriptor for the IODataQueueMemory region. Returns zero on failure.
	154	*/
	155	virtual IOMemoryDescriptor *getMemoryDescriptor();
1c79356b A	156	};
	157
	158	#endif /* _IOKIT_IODATAQUEUE_H */