1/*
2 * Copyright (c) 1998-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#ifndef _IOKIT_IOSHAREDDATAQUEUE_H
30#define _IOKIT_IOSHAREDDATAQUEUE_H
31
32#define DISABLE_DATAQUEUE_WARNING /* IODataQueue is deprecated, please use IOSharedDataQueue instead */
33
34#include <IOKit/IODataQueue.h>
35#include <libkern/c++/OSPtr.h>
36
37#undef DISABLE_DATAQUEUE_WARNING
38
39typedef struct _IODataQueueEntry IODataQueueEntry;
40
41/*!
42 * @class IOSharedDataQueue : public IODataQueue
43 * @abstract A generic queue designed to pass data both from the kernel to a user process and from a user process to the kernel.
44 * @discussion The IOSharedDataQueue class is designed to also allow a user process to queue data to kernel code. IOSharedDataQueue 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.
45 *
46 * <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.
47 *
48 * <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.
49 *
50 * <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.
51 */
52class IOSharedDataQueue : public IODataQueue
53{
54 OSDeclareDefaultStructors(IOSharedDataQueue);
55
56 struct ExpansionData {
57 UInt32 queueSize;
58 };
59/*! @var reserved
60 * Reserved for future use. (Internal use only) */
61 ExpansionData * _reserved;
62
63protected:
64 virtual void free() APPLE_KEXT_OVERRIDE;
65
66/*!
67 * @function getQueueSize
68 * @abstract Returns the size of the data queue.
69 * @discussion Use this method to access the size of the data queue. Do not access the value of size directly, as it can get modified from userspace and is not reliable.
70 * @result Returns the size of the data queue, or zero in case of failure.
71 */
72 UInt32 getQueueSize();
73
74/*!
75 * @function setQueueSize
76 * @abstract Stores the value of the size of the data queue.
77 * @discussion Use this method to store the value of the size of the data queue. Do not access the value of size directly, as it can get modified from userspace and is not reliable.
78 * @param size The size of the data queue.
79 * @result Returns true in case of success, false otherwise.
80 */
81 Boolean setQueueSize(UInt32 size);
82
83public:
84/*!
85 * @function withCapacity
86 * @abstract Static method that creates a new IOSharedDataQueue instance with the capacity specified in the size parameter.
87 * @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.
88 * @param size The size of the data queue memory region.
89 * @result Returns the newly allocated IOSharedDataQueue instance. Zero is returned on failure.
90 */
91 static OSPtr<IOSharedDataQueue> withCapacity(UInt32 size);
92
93/*!
94 * @function withEntries
95 * @abstract Static method that creates a new IOSharedDataQueue instance with the specified number of entries of the given size.
96 * @discussion This method will create a new IOSharedDataQueue 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.
97 * @param numEntries Number of entries to allocate space for.
98 * @param entrySize Size of each entry.
99 * @result Reeturns the newly allocated IOSharedDataQueue instance. Zero is returned on failure.
100 */
101 static OSPtr<IOSharedDataQueue> withEntries(UInt32 numEntries, UInt32 entrySize);
102
103/*!
104 * @function initWithCapacity
105 * @abstract Initializes an IOSharedDataQueue instance with the capacity specified in the size parameter.
106 * @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 and DATA_QUEUE_MEMORY_APPENDIX_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>.
107 * @param size The size of the data queue memory region.
108 * @result Returns true on success and false on failure.
109 */
110 virtual Boolean initWithCapacity(UInt32 size) APPLE_KEXT_OVERRIDE;
111
112/*!
113 * @function getMemoryDescriptor
114 * @abstract Returns a memory descriptor covering the IODataQueueMemory region.
115 * @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.
116 * @result Returns a newly allocated IOMemoryDescriptor for the IODataQueueMemory region. Returns zero on failure.
117 */
118 virtual OSPtr<IOMemoryDescriptor> getMemoryDescriptor() APPLE_KEXT_OVERRIDE;
119
120/*!
121 * @function peek
122 * @abstract Used to peek at the next entry on the queue.
123 * @discussion This function can be used to look at the next entry which allows the entry to be received without having to copy it with dequeue. In order to do this, call peek to get the entry. Then call dequeue with a NULL data pointer. That will cause the head to be moved to the next entry, but no memory to be copied.
124 * @result Returns a pointer to the next IODataQueueEntry if one is available. 0 (NULL) is returned if the queue is empty.
125 */
126 virtual IODataQueueEntry * peek();
127
128/*!
129 * @function dequeue
130 * @abstract Dequeues the next available entry on the queue and copies it into the given data pointer.
131 * @discussion This function will dequeue the next available entry on the queue. If a data pointer is provided, it will copy the data into the memory region if there is enough space available as specified in the dataSize parameter. If no data pointer is provided, it will simply move the head value past the current entry.
132 * @param data A pointer to the data memory region in which to copy the next entry data on the queue. If this parameter is 0 (NULL), it will simply move to the next entry.
133 * @param dataSize A pointer to the size of the data parameter. On return, this contains the size of the actual entry data - even if the original size was not large enough.
134 * @result Returns true on success and false on failure. Typically failure means that the queue is empty.
135 */
136 virtual Boolean dequeue(void *data, UInt32 *dataSize);
137
138/*!
139 * @function enqueue
140 * @abstract Enqueues a new entry on the queue.
141 * @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.
142 * @param data Pointer to the data to be added to the queue.
143 * @param dataSize Size of the data pointed to by data.
144 * @result Returns true on success and false on failure. Typically failure means that the queue is full.
145 */
146 virtual Boolean enqueue(void *data, UInt32 dataSize) APPLE_KEXT_OVERRIDE;
147
148#ifdef PRIVATE
149/* workaround for queue.h redefine, please do not use */
150 __inline__ Boolean
151 enqueue_tail(void *data, UInt32 dataSize)
152 {
153 return IOSharedDataQueue::enqueue(data, dataSize);
154 }
155#endif
156
157#if APPLE_KEXT_VTABLE_PADDING
158 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 0);
159 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 1);
160 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 2);
161 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 3);
162 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 4);
163 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 5);
164 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 6);
165 OSMetaClassDeclareReservedUnused(IOSharedDataQueue, 7);
166#endif
167};
168
169#endif /* _IOKIT_IOSHAREDDATAQUEUE_H */
170