Root/
Source at commit 1085 created 13 years 1 month ago. By azimutz, Runaway "min"; fixes build. | |
---|---|
1 | /*␊ |
2 | * Copyright (c) 1998-2000 Apple Computer, 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 | kIOMemorySharingTypeMask␉␉= 0x000f0000,␊ |
38 | kIOMemoryUnshared␉␉␉= 0x00000000,␊ |
39 | kIOMemoryKernelUserShared␉␉= 0x00010000,␊ |
40 | // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor:␊ |
41 | kIOBufferDescriptorMemoryFlags␉= kIOMemoryDirectionMask ␊ |
42 | ␉␉␉␉␉| kIOMemoryThreadSafe␊ |
43 | };␊ |
44 | ␊ |
45 | #define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_␉1␊ |
46 | /*!␊ |
47 | @class IOBufferMemoryDescriptor␊ |
48 | @abstract Provides a simple memory descriptor that allocates its own buffer memory.␊ |
49 | */␊ |
50 | ␊ |
51 | class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor␊ |
52 | {␊ |
53 | OSDeclareDefaultStructors(IOBufferMemoryDescriptor);␊ |
54 | ␊ |
55 | private:␊ |
56 | /*! @struct ExpansionData␊ |
57 | @discussion This structure will be used to expand the capablilties of this class in the future.␊ |
58 | */ ␊ |
59 | struct ExpansionData {␊ |
60 | ␉IOMemoryMap * map;␊ |
61 | };␊ |
62 | ␊ |
63 | /*! @var reserved␊ |
64 | Reserved for future use. (Internal use only) */␊ |
65 | ExpansionData * reserved;␊ |
66 | ␊ |
67 | protected:␊ |
68 | void * _buffer;␊ |
69 | vm_size_t _capacity;␊ |
70 | vm_offset_t␉␉ _alignment;␊ |
71 | IOOptionBits␉ _options;␊ |
72 | private:␊ |
73 | uintptr_t␉␉ _internalReserved;␊ |
74 | unsigned _internalFlags;␊ |
75 | ␊ |
76 | private:␊ |
77 | #ifndef __LP64__␊ |
78 | virtual bool initWithOptions(␊ |
79 | IOOptionBits options,␊ |
80 | vm_size_t capacity,␊ |
81 | vm_offset_t alignment,␊ |
82 | ␉␉␉ task_t␉ inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */␊ |
83 | #endif /* !__LP64__ */␊ |
84 | ␊ |
85 | virtual bool initWithPhysicalMask(␊ |
86 | ␉␉␉␉task_t␉␉ inTask,␊ |
87 | ␉␉␉␉IOOptionBits options,␊ |
88 | ␉␉␉␉mach_vm_size_t capacity,␊ |
89 | ␉␉␉␉mach_vm_address_t alignment,␊ |
90 | ␉␉␉␉mach_vm_address_t physicalMask);␊ |
91 | ␊ |
92 | #ifdef __LP64__␊ |
93 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0);␊ |
94 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);␊ |
95 | #else /* !__LP64__ */␊ |
96 | OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);␊ |
97 | OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1);␊ |
98 | #endif /* !__LP64__ */␊ |
99 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);␊ |
100 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);␊ |
101 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);␊ |
102 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5);␊ |
103 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6);␊ |
104 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7);␊ |
105 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8);␊ |
106 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9);␊ |
107 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10);␊ |
108 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11);␊ |
109 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12);␊ |
110 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13);␊ |
111 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14);␊ |
112 | OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15);␊ |
113 | ␊ |
114 | protected:␊ |
115 | virtual void free();␊ |
116 | ␊ |
117 | public:␊ |
118 | ␊ |
119 | /*␊ |
120 | * withOptions:␊ |
121 | *␊ |
122 | * Returns a new IOBufferMemoryDescriptor with a buffer large enough to␊ |
123 | * hold capacity bytes. The descriptor's length is initially set to the␊ |
124 | * capacity.␊ |
125 | */␊ |
126 | #ifndef __LP64__␊ |
127 | virtual bool initWithOptions( IOOptionBits options,␊ |
128 | vm_size_t capacity,␊ |
129 | vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */␊ |
130 | #endif /* !__LP64__ */␊ |
131 | ␊ |
132 | static IOBufferMemoryDescriptor * withOptions( IOOptionBits options,␊ |
133 | vm_size_t capacity,␊ |
134 | vm_offset_t alignment = 1);␊ |
135 | ␊ |
136 | /*! @function inTaskWithOptions␊ |
137 | @abstract Creates a memory buffer with memory descriptor for that buffer. ␊ |
138 | @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.␊ |
139 | @param inTask The task the buffer will be allocated in.␊ |
140 | @param options Options for the allocation:<br>␊ |
141 | kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>␊ |
142 | 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>␊ |
143 | kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br>␊ |
144 | kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br>␊ |
145 | kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.␊ |
146 | @param capacity The number of bytes to allocate.␊ |
147 | @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.␊ |
148 | @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */␊ |
149 | ␊ |
150 | static IOBufferMemoryDescriptor * inTaskWithOptions(␊ |
151 | ␉␉␉␉␉ task_t inTask,␊ |
152 | IOOptionBits options,␊ |
153 | vm_size_t capacity,␊ |
154 | vm_offset_t alignment = 1);␊ |
155 | ␊ |
156 | /*! @function inTaskWithPhysicalMask␊ |
157 | @abstract Creates a memory buffer with memory descriptor for that buffer. ␊ |
158 | @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.␊ |
159 | @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).␊ |
160 | @param options Options for the allocation:<br>␊ |
161 | kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>␊ |
162 | 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>␊ |
163 | kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.␊ |
164 | @param capacity The number of bytes to allocate.␊ |
165 | @param mask 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.␊ |
166 | @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */␊ |
167 | ␊ |
168 | static IOBufferMemoryDescriptor * inTaskWithPhysicalMask(␊ |
169 | ␉␉␉␉␉ task_t␉ inTask,␊ |
170 | IOOptionBits options,␊ |
171 | mach_vm_size_t capacity,␊ |
172 | mach_vm_address_t physicalMask);␊ |
173 | ␊ |
174 | /*␊ |
175 | * withCapacity:␊ |
176 | *␊ |
177 | * Returns a new IOBufferMemoryDescriptor with a buffer large enough to␊ |
178 | * hold capacity bytes. The descriptor's length is initially set to the␊ |
179 | * capacity.␊ |
180 | */␊ |
181 | static IOBufferMemoryDescriptor * withCapacity(␊ |
182 | vm_size_t capacity,␊ |
183 | IODirection withDirection,␊ |
184 | bool withContiguousMemory = false);␊ |
185 | #ifndef __LP64__␊ |
186 | virtual bool initWithBytes(const void * bytes,␊ |
187 | vm_size_t withLength,␊ |
188 | IODirection withDirection,␊ |
189 | bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */␊ |
190 | #endif /* !__LP64__ */␊ |
191 | ␊ |
192 | /*␊ |
193 | * withBytes:␊ |
194 | *␊ |
195 | * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).␊ |
196 | * The descriptor's length and capacity are set to the input buffer's size.␊ |
197 | */␊ |
198 | static IOBufferMemoryDescriptor * withBytes(␊ |
199 | const void * bytes,␊ |
200 | vm_size_t withLength,␊ |
201 | IODirection withDirection,␊ |
202 | bool withContiguousMemory = false);␊ |
203 | ␊ |
204 | /*␊ |
205 | * setLength:␊ |
206 | *␊ |
207 | * Change the buffer length of the memory descriptor. When a new buffer␊ |
208 | * is created, the initial length of the buffer is set to be the same as␊ |
209 | * the capacity. The length can be adjusted via setLength for a shorter␊ |
210 | * transfer (there is no need to create more buffer descriptors when you␊ |
211 | * can reuse an existing one, even for different transfer sizes). Note␊ |
212 | * that the specified length must not exceed the capacity of the buffer.␊ |
213 | */␊ |
214 | virtual void setLength(vm_size_t length);␊ |
215 | ␊ |
216 | /*␊ |
217 | * setDirection:␊ |
218 | *␊ |
219 | * Change the direction of the transfer. This method allows one to redirect␊ |
220 | * the descriptor's transfer direction. This eliminates the need to destroy␊ |
221 | * and create new buffers when different transfer directions are needed.␊ |
222 | */␊ |
223 | virtual void setDirection(IODirection direction);␊ |
224 | ␊ |
225 | /*␊ |
226 | * getCapacity:␊ |
227 | *␊ |
228 | * Get the buffer capacity␊ |
229 | */␊ |
230 | virtual vm_size_t getCapacity() const;␊ |
231 | ␊ |
232 | /*␊ |
233 | * getBytesNoCopy:␊ |
234 | *␊ |
235 | * Return the virtual address of the beginning of the buffer␊ |
236 | */␊ |
237 | virtual void *getBytesNoCopy();␊ |
238 | ␊ |
239 | /*␊ |
240 | * getBytesNoCopy:␊ |
241 | *␊ |
242 | * Return the virtual address of an offset from the beginning of the buffer␊ |
243 | */␊ |
244 | virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);␊ |
245 | ␊ |
246 | /*␊ |
247 | * appendBytes:␊ |
248 | *␊ |
249 | * Add some data to the end of the buffer. This method automatically␊ |
250 | * maintains the memory descriptor buffer length. Note that appendBytes␊ |
251 | * will not copy past the end of the memory descriptor's current capacity.␊ |
252 | */␊ |
253 | virtual bool appendBytes(const void *bytes, vm_size_t withLength);␊ |
254 | ␊ |
255 | #ifndef __LP64__␊ |
256 | virtual void * getVirtualSegment(IOByteCount offset,␊ |
257 | ␉␉␉␉␉IOByteCount * length) APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */␊ |
258 | #endif /* !__LP64__ */␊ |
259 | };␊ |
260 | ␊ |
261 | #endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */␊ |
262 |