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 <libkern/c++/OSPtr.h> |
32 | #include <IOKit/IOMemoryDescriptor.h> |
33 | #include <DriverKit/IOBufferMemoryDescriptor.h> |
34 | |
35 | enum { |
36 | kIOMemoryPhysicallyContiguous = 0x00000010, |
37 | kIOMemoryPageable = 0x00000020, |
38 | kIOMemoryPurgeable = 0x00000040, |
39 | kIOMemoryHostPhysicallyContiguous = 0x00000080, |
40 | kIOMemorySharingTypeMask = 0x000f0000, |
41 | kIOMemoryUnshared = 0x00000000, |
42 | kIOMemoryKernelUserShared = 0x00010000, |
43 | // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor: |
44 | kIOBufferDescriptorMemoryFlags = kIOMemoryDirectionMask |
45 | #ifdef XNU_KERNEL_PRIVATE |
46 | | kIOMemoryAutoPrepare |
47 | #endif |
48 | | kIOMemoryThreadSafe |
49 | | kIOMemoryClearEncrypt |
50 | | kIOMemoryMapperNone |
51 | | kIOMemoryUseReserve |
52 | }; |
53 | |
54 | #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1 |
55 | #define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_ 1 |
56 | #define IOBUFFERMEMORYDESCRIPTOR_SUPPORTS_INTASKWITHOPTIONS_TAGS 1 |
57 | /*! |
58 | * @class IOBufferMemoryDescriptor |
59 | * @abstract Provides a simple memory descriptor that allocates its own buffer memory. |
60 | */ |
61 | |
62 | class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor |
63 | { |
64 | OSDeclareDefaultStructorsWithDispatch(IOBufferMemoryDescriptor); |
65 | |
66 | private: |
67 | /*! @struct ExpansionData |
68 | * @discussion This structure will be used to expand the capablilties of this class in the future. |
69 | */ |
70 | struct ExpansionData { |
71 | IOMemoryMap * map; |
72 | }; |
73 | |
74 | /*! @var reserved |
75 | * Reserved for future use. (Internal use only) */ |
76 | APPLE_KEXT_WSHADOW_PUSH; |
77 | ExpansionData * reserved; |
78 | |
79 | protected: |
80 | void * _buffer; |
81 | vm_size_t _capacity; |
82 | vm_offset_t _alignment; |
83 | IOOptionBits _options; |
84 | private: |
85 | uintptr_t _internalReserved; |
86 | unsigned _internalFlags; |
87 | APPLE_KEXT_WSHADOW_POP; |
88 | |
89 | private: |
90 | #ifndef __LP64__ |
91 | virtual bool initWithOptions( |
92 | IOOptionBits options, |
93 | vm_size_t capacity, |
94 | vm_offset_t alignment, |
95 | task_t inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ |
96 | #endif /* !__LP64__ */ |
97 | |
98 | public: |
99 | virtual bool initWithPhysicalMask( |
100 | task_t inTask, |
101 | IOOptionBits options, |
102 | mach_vm_size_t capacity, |
103 | mach_vm_address_t alignment, |
104 | mach_vm_address_t physicalMask); |
105 | |
106 | #ifdef XNU_KERNEL_PRIVATE |
107 | /* |
108 | * By default the buffer allocated in IOBufferMemoryDescriptor is |
109 | * considered to contain "pure data" and no kernel pointers. It |
110 | * is therefore colocated with other data buffers. |
111 | * |
112 | * This API allows to create a buffer that contains pointers and |
113 | * will not be redirected to the data heap/map. |
114 | */ |
115 | bool initControlWithPhysicalMask( |
116 | task_t inTask, |
117 | IOOptionBits options, |
118 | mach_vm_size_t capacity, |
119 | mach_vm_address_t alignment, |
120 | mach_vm_address_t physicalMask); |
121 | #endif |
122 | |
123 | #ifdef KERNEL_PRIVATE |
124 | /* |
125 | * Create an IOBufferMemoryDescriptor with guard pages on each side of the buffer allocation. |
126 | * @param inTask The task the buffer will be allocated in. |
127 | * @param options Options for the IOBufferMemoryDescriptor. See inTaskWithOptions for a description of available options. |
128 | * Some options are not available when using guard pages. Specifically, physically contiguous memory and pageable memory |
129 | * options are not supported. If these options are used, this will fail to create the memory descriptor and return NULL. |
130 | * @param capacity The number of bytes to allocate. Due to how memory with guard pages is allocated, this will be rounded up to page size. |
131 | * The buffer will also always be aligned to the page size. |
132 | * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory descriptor and associated buffer. |
133 | */ |
134 | static OSPtr<IOBufferMemoryDescriptor> inTaskWithGuardPages( |
135 | task_t inTask, |
136 | IOOptionBits options, |
137 | mach_vm_size_t capacity); |
138 | |
139 | bool initWithGuardPages( |
140 | task_t inTask, |
141 | IOOptionBits options, |
142 | mach_vm_size_t capacity); |
143 | #endif |
144 | |
145 | #ifdef __LP64__ |
146 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0); |
147 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1); |
148 | #else /* !__LP64__ */ |
149 | OSMetaClassDeclareReservedUsedX86(IOBufferMemoryDescriptor, 0); |
150 | OSMetaClassDeclareReservedUsedX86(IOBufferMemoryDescriptor, 1); |
151 | #endif /* !__LP64__ */ |
152 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2); |
153 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3); |
154 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4); |
155 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5); |
156 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6); |
157 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7); |
158 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8); |
159 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9); |
160 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10); |
161 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11); |
162 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12); |
163 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13); |
164 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14); |
165 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15); |
166 | |
167 | protected: |
168 | virtual void free() APPLE_KEXT_OVERRIDE; |
169 | |
170 | public: |
171 | |
172 | /* |
173 | * withOptions: |
174 | * |
175 | * Returns a new IOBufferMemoryDescriptor with a buffer large enough to |
176 | * hold capacity bytes. The descriptor's length is initially set to the |
177 | * capacity. |
178 | */ |
179 | #ifndef __LP64__ |
180 | virtual bool initWithOptions( IOOptionBits options, |
181 | vm_size_t capacity, |
182 | vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ |
183 | #endif /* !__LP64__ */ |
184 | |
185 | static OSPtr<IOBufferMemoryDescriptor> withCopy( |
186 | task_t inTask, |
187 | IOOptionBits options, |
188 | vm_map_t sourceMap, |
189 | mach_vm_address_t source, |
190 | mach_vm_size_t size); |
191 | |
192 | static OSPtr<IOBufferMemoryDescriptor> withOptions( IOOptionBits options, |
193 | vm_size_t capacity, |
194 | vm_offset_t alignment = 1); |
195 | |
196 | /*! @function inTaskWithOptions |
197 | * @abstract Creates a memory buffer with memory descriptor for that buffer. |
198 | * @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. |
199 | * @param inTask The task the buffer will be allocated in. |
200 | * @param options Options for the allocation:<br> |
201 | * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> |
202 | * 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> |
203 | * kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br> |
204 | * kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br> |
205 | * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> |
206 | * kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> |
207 | * kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> |
208 | * kIOMapCopybackCache - allocate memory with copyback cache setting. <br> |
209 | * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. |
210 | * @param capacity The number of bytes to allocate. |
211 | * @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. |
212 | * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ |
213 | |
214 | static OSPtr<IOBufferMemoryDescriptor> inTaskWithOptions( |
215 | task_t inTask, |
216 | IOOptionBits options, |
217 | vm_size_t capacity, |
218 | vm_offset_t alignment = 1); |
219 | |
220 | /*! @function inTaskWithOptions |
221 | * @abstract Creates a memory buffer with memory descriptor for that buffer. |
222 | * @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. |
223 | * @param inTask The task the buffer will be allocated in. |
224 | * @param options Options for the allocation:<br> |
225 | * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> |
226 | * 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> |
227 | * kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br> |
228 | * kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br> |
229 | * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> |
230 | * kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> |
231 | * kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> |
232 | * kIOMapCopybackCache - allocate memory with copyback cache setting. <br> |
233 | * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. |
234 | * @param capacity The number of bytes to allocate. |
235 | * @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. |
236 | * @param kernTag The kernel memory tag |
237 | * @param userTag The user memory tag |
238 | * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ |
239 | |
240 | static OSPtr<IOBufferMemoryDescriptor> inTaskWithOptions( |
241 | task_t inTask, |
242 | IOOptionBits options, |
243 | vm_size_t capacity, |
244 | vm_offset_t alignment, |
245 | uint32_t kernTag, |
246 | uint32_t userTag); |
247 | |
248 | /*! @function inTaskWithPhysicalMask |
249 | * @abstract Creates a memory buffer with memory descriptor for that buffer. |
250 | * @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. |
251 | * @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). |
252 | * @param options Options for the allocation:<br> |
253 | * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br> |
254 | * 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> |
255 | * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br> |
256 | * kIOMapInhibitCache - allocate memory with inhibited cache setting. <br> |
257 | * kIOMapWriteThruCache - allocate memory with writethru cache setting. <br> |
258 | * kIOMapCopybackCache - allocate memory with copyback cache setting. <br> |
259 | * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. |
260 | * @param capacity The number of bytes to allocate. |
261 | * @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. |
262 | * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ |
263 | |
264 | static OSPtr<IOBufferMemoryDescriptor> inTaskWithPhysicalMask( |
265 | task_t inTask, |
266 | IOOptionBits options, |
267 | mach_vm_size_t capacity, |
268 | mach_vm_address_t physicalMask); |
269 | |
270 | /* |
271 | * withCapacity: |
272 | * |
273 | * Returns a new IOBufferMemoryDescriptor with a buffer large enough to |
274 | * hold capacity bytes. The descriptor's length is initially set to the |
275 | * capacity. |
276 | */ |
277 | static OSPtr<IOBufferMemoryDescriptor> withCapacity( |
278 | vm_size_t capacity, |
279 | IODirection withDirection, |
280 | bool withContiguousMemory = false); |
281 | #ifndef __LP64__ |
282 | virtual bool initWithBytes(const void * bytes, |
283 | vm_size_t withLength, |
284 | IODirection withDirection, |
285 | bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */ |
286 | #endif /* !__LP64__ */ |
287 | |
288 | /* |
289 | * withBytes: |
290 | * |
291 | * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied). |
292 | * The descriptor's length and capacity are set to the input buffer's size. |
293 | */ |
294 | static OSPtr<IOBufferMemoryDescriptor> withBytes( |
295 | const void * bytes, |
296 | vm_size_t withLength, |
297 | IODirection withDirection, |
298 | bool withContiguousMemory = false); |
299 | |
300 | /* |
301 | * setLength: |
302 | * |
303 | * Change the buffer length of the memory descriptor. When a new buffer |
304 | * is created, the initial length of the buffer is set to be the same as |
305 | * the capacity. The length can be adjusted via setLength for a shorter |
306 | * transfer (there is no need to create more buffer descriptors when you |
307 | * can reuse an existing one, even for different transfer sizes). Note |
308 | * that the specified length must not exceed the capacity of the buffer. |
309 | */ |
310 | virtual void setLength(vm_size_t length); |
311 | |
312 | /* |
313 | * setDirection: |
314 | * |
315 | * Change the direction of the transfer. This method allows one to redirect |
316 | * the descriptor's transfer direction. This eliminates the need to destroy |
317 | * and create new buffers when different transfer directions are needed. |
318 | */ |
319 | virtual void setDirection(IODirection direction); |
320 | |
321 | /* |
322 | * getCapacity: |
323 | * |
324 | * Get the buffer capacity |
325 | */ |
326 | virtual vm_size_t getCapacity() const; |
327 | |
328 | /* |
329 | * getBytesNoCopy: |
330 | * |
331 | * Return the virtual address of the beginning of the buffer |
332 | */ |
333 | virtual void *getBytesNoCopy(); |
334 | |
335 | /* |
336 | * getBytesNoCopy: |
337 | * |
338 | * Return the virtual address of an offset from the beginning of the buffer |
339 | */ |
340 | virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength); |
341 | |
342 | /* |
343 | * appendBytes: |
344 | * |
345 | * Add some data to the end of the buffer. This method automatically |
346 | * maintains the memory descriptor buffer length. Note that appendBytes |
347 | * will not copy past the end of the memory descriptor's current capacity. |
348 | */ |
349 | virtual bool appendBytes(const void *bytes, vm_size_t withLength); |
350 | |
351 | #ifndef __LP64__ |
352 | virtual void * getVirtualSegment(IOByteCount offset, |
353 | IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */ |
354 | #endif /* !__LP64__ */ |
355 | }; |
356 | |
357 | #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */ |
358 | |