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
35enum {
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
62class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
63{
64 OSDeclareDefaultStructorsWithDispatch(IOBufferMemoryDescriptor);
65
66private:
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
79protected:
80 void * _buffer;
81 vm_size_t _capacity;
82 vm_offset_t _alignment;
83 IOOptionBits _options;
84private:
85 uintptr_t _internalReserved;
86 unsigned _internalFlags;
87 APPLE_KEXT_WSHADOW_POP;
88
89private:
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
98public:
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
167protected:
168 virtual void free() APPLE_KEXT_OVERRIDE;
169
170public:
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