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
33enum {
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
59class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
60{
61 OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
62
63private:
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
76protected:
77 void * _buffer;
78 vm_size_t _capacity;
79 vm_offset_t _alignment;
80 IOOptionBits _options;
81private:
82 uintptr_t _internalReserved;
83 unsigned _internalFlags;
84 APPLE_KEXT_WSHADOW_POP;
85
86private:
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
95public:
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
125protected:
126 virtual void free() APPLE_KEXT_OVERRIDE;
127
128public:
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