1 | /* |
2 | * Copyright (c) 1998-2016 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 | #ifndef _IOBUFFERMEMORYDESCRIPTOR_H |
29 | #define _IOBUFFERMEMORYDESCRIPTOR_H |
30 | |
31 | #include <IOKit/IOMemoryDescriptor.h> |
32 | |
33 | enum { |
34 | kIOMemoryPhysicallyContiguous = 0x00000010, |
35 | kIOMemoryPageable = 0x00000020, |
36 | kIOMemoryPurgeable = 0x00000040, |
37 | kIOMemoryHostPhysicallyContiguous = 0x00000080, |
38 | kIOMemorySharingTypeMask = 0x000f0000, |
39 | kIOMemoryUnshared = 0x00000000, |
40 | kIOMemoryKernelUserShared = 0x00010000, |
41 | // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor: |
42 | kIOBufferDescriptorMemoryFlags = kIOMemoryDirectionMask |
43 | #ifdef XNU_KERNEL_PRIVATE |
44 | | kIOMemoryAutoPrepare |
45 | #endif |
46 | | kIOMemoryThreadSafe |
47 | | kIOMemoryClearEncrypt |
48 | | kIOMemoryMapperNone |
49 | | kIOMemoryUseReserve |
50 | }; |
51 | |
52 | #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1 |
53 | #define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_ 1 |
54 | /*! |
55 | @class IOBufferMemoryDescriptor |
56 | @abstract Provides a simple memory descriptor that allocates its own buffer memory. |
57 | */ |
58 | |
59 | class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor |
60 | { |
61 | OSDeclareDefaultStructors(IOBufferMemoryDescriptor); |
62 | |
63 | private: |
64 | /*! @struct ExpansionData |
65 | @discussion This structure will be used to expand the capablilties of this class in the future. |
66 | */ |
67 | struct ExpansionData { |
68 | IOMemoryMap * map; |
69 | }; |
70 | |
71 | /*! @var reserved |
72 | Reserved for future use. (Internal use only) */ |
73 | APPLE_KEXT_WSHADOW_PUSH; |
74 | ExpansionData * reserved; |
75 | |
76 | protected: |
77 | void * _buffer; |
78 | vm_size_t _capacity; |
79 | vm_offset_t _alignment; |
80 | IOOptionBits _options; |
81 | private: |
82 | uintptr_t _internalReserved; |
83 | unsigned _internalFlags; |
84 | APPLE_KEXT_WSHADOW_POP; |
85 | |
86 | private: |
87 | #ifndef __LP64__ |
88 | virtual bool initWithOptions( |
89 | IOOptionBits options, |
90 | vm_size_t capacity, |
91 | vm_offset_t alignment, |
92 | task_t inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ |
93 | #endif /* !__LP64__ */ |
94 | |
95 | public: |
96 | virtual bool initWithPhysicalMask( |
97 | task_t inTask, |
98 | IOOptionBits options, |
99 | mach_vm_size_t capacity, |
100 | mach_vm_address_t alignment, |
101 | mach_vm_address_t physicalMask); |
102 | |
103 | #ifdef __LP64__ |
104 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0); |
105 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1); |
106 | #else /* !__LP64__ */ |
107 | OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0); |
108 | OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1); |
109 | #endif /* !__LP64__ */ |
110 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2); |
111 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3); |
112 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4); |
113 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5); |
114 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6); |
115 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7); |
116 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8); |
117 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9); |
118 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10); |
119 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11); |
120 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12); |
121 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13); |
122 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14); |
123 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15); |
124 | |
125 | protected: |
126 | virtual void free() APPLE_KEXT_OVERRIDE; |
127 | |
128 | public: |
129 | |
130 | /* |
131 | * withOptions: |
132 | * |
133 | * Returns a new IOBufferMemoryDescriptor with a buffer large enough to |
134 | * hold capacity bytes. The descriptor's length is initially set to the |
135 | * capacity. |
136 | */ |
137 | #ifndef __LP64__ |
138 | virtual bool initWithOptions( IOOptionBits options, |
139 | vm_size_t capacity, |
140 | vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ |
141 | #endif /* !__LP64__ */ |
142 | |
143 | static IOBufferMemoryDescriptor * withOptions( IOOptionBits options, |
144 | vm_size_t capacity, |
145 | vm_offset_t alignment = 1); |
146 | |
147 | /*! @function inTaskWithOptions |
148 | @abstract Creates a memory buffer with memory descriptor for that buffer. |
149 | @discussion Added in Mac OS X 10.2, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. |
150 | @param inTask The task the buffer will be allocated in. |
151 | @param options Options for the allocation:<br> |
152 | kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> |
153 | kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.<br> |
154 | kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br> |
155 | kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br> |
156 | kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> |
157 | kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> |
158 | kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> |
159 | kIOMapCopybackCache - allocate memory with copyback cache setting. <br> |
160 | kIOMapWriteCombineCache - allocate memory with writecombined cache setting. |
161 | @param capacity The number of bytes to allocate. |
162 | @param alignment The minimum required alignment of the buffer in bytes - 1 is the default for no required alignment. For example, pass 256 to get memory allocated at an address with bits 0-7 zero. |
163 | @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ |
164 | |
165 | static IOBufferMemoryDescriptor * inTaskWithOptions( |
166 | task_t inTask, |
167 | IOOptionBits options, |
168 | vm_size_t capacity, |
169 | vm_offset_t alignment = 1); |
170 | |
171 | /*! @function inTaskWithPhysicalMask |
172 | @abstract Creates a memory buffer with memory descriptor for that buffer. |
173 | @discussion Added in Mac OS X 10.5, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. |
174 | @param inTask The task the buffer will be mapped in. Pass NULL to create memory unmapped in any task (eg. for use as a DMA buffer). |
175 | @param options Options for the allocation:<br> |
176 | kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> |
177 | kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.<br> |
178 | kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> |
179 | kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> |
180 | kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> |
181 | kIOMapCopybackCache - allocate memory with copyback cache setting. <br> |
182 | kIOMapWriteCombineCache - allocate memory with writecombined cache setting. |
183 | @param capacity The number of bytes to allocate. |
184 | @param physicalMask The buffer will be allocated with pages such that physical addresses will only have bits set present in physicalMask. For example, pass 0x00000000FFFFFFFFULL for a buffer to be accessed by hardware that has 32 address bits. |
185 | @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ |
186 | |
187 | static IOBufferMemoryDescriptor * inTaskWithPhysicalMask( |
188 | task_t inTask, |
189 | IOOptionBits options, |
190 | mach_vm_size_t capacity, |
191 | mach_vm_address_t physicalMask); |
192 | |
193 | /* |
194 | * withCapacity: |
195 | * |
196 | * Returns a new IOBufferMemoryDescriptor with a buffer large enough to |
197 | * hold capacity bytes. The descriptor's length is initially set to the |
198 | * capacity. |
199 | */ |
200 | static IOBufferMemoryDescriptor * withCapacity( |
201 | vm_size_t capacity, |
202 | IODirection withDirection, |
203 | bool withContiguousMemory = false); |
204 | #ifndef __LP64__ |
205 | virtual bool initWithBytes(const void * bytes, |
206 | vm_size_t withLength, |
207 | IODirection withDirection, |
208 | bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */ |
209 | #endif /* !__LP64__ */ |
210 | |
211 | /* |
212 | * withBytes: |
213 | * |
214 | * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied). |
215 | * The descriptor's length and capacity are set to the input buffer's size. |
216 | */ |
217 | static IOBufferMemoryDescriptor * withBytes( |
218 | const void * bytes, |
219 | vm_size_t withLength, |
220 | IODirection withDirection, |
221 | bool withContiguousMemory = false); |
222 | |
223 | /* |
224 | * setLength: |
225 | * |
226 | * Change the buffer length of the memory descriptor. When a new buffer |
227 | * is created, the initial length of the buffer is set to be the same as |
228 | * the capacity. The length can be adjusted via setLength for a shorter |
229 | * transfer (there is no need to create more buffer descriptors when you |
230 | * can reuse an existing one, even for different transfer sizes). Note |
231 | * that the specified length must not exceed the capacity of the buffer. |
232 | */ |
233 | virtual void setLength(vm_size_t length); |
234 | |
235 | /* |
236 | * setDirection: |
237 | * |
238 | * Change the direction of the transfer. This method allows one to redirect |
239 | * the descriptor's transfer direction. This eliminates the need to destroy |
240 | * and create new buffers when different transfer directions are needed. |
241 | */ |
242 | virtual void setDirection(IODirection direction); |
243 | |
244 | /* |
245 | * getCapacity: |
246 | * |
247 | * Get the buffer capacity |
248 | */ |
249 | virtual vm_size_t getCapacity() const; |
250 | |
251 | /* |
252 | * getBytesNoCopy: |
253 | * |
254 | * Return the virtual address of the beginning of the buffer |
255 | */ |
256 | virtual void *getBytesNoCopy(); |
257 | |
258 | /* |
259 | * getBytesNoCopy: |
260 | * |
261 | * Return the virtual address of an offset from the beginning of the buffer |
262 | */ |
263 | virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength); |
264 | |
265 | /* |
266 | * appendBytes: |
267 | * |
268 | * Add some data to the end of the buffer. This method automatically |
269 | * maintains the memory descriptor buffer length. Note that appendBytes |
270 | * will not copy past the end of the memory descriptor's current capacity. |
271 | */ |
272 | virtual bool appendBytes(const void *bytes, vm_size_t withLength); |
273 | |
274 | #ifndef __LP64__ |
275 | virtual void * getVirtualSegment(IOByteCount offset, |
276 | IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */ |
277 | #endif /* !__LP64__ */ |
278 | }; |
279 | |
280 | #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */ |
281 | |