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 _IOMEMORYDESCRIPTOR_H
29 #define _IOMEMORYDESCRIPTOR_H
30
31 #include <sys/cdefs.h>
32
33 #include <IOKit/IOTypes.h>
34 #include <IOKit/IOLocks.h>
35 #include <libkern/c++/OSContainers.h>
36
37 __BEGIN_DECLS
38 #include <mach/memory_object_types.h>
39 __END_DECLS
40
41 struct IOPhysicalRange
42 {
43 IOPhysicalAddress address;
44 IOByteCount length;
45 };
46
47 class IOMemoryMap;
48 class IOMapper;
49
50 /*
51 * Direction of transfer, with respect to the described memory.
52 */
53 enum IODirection
54 {
55 kIODirectionNone = 0x0, // same as VM_PROT_NONE
56 kIODirectionIn = 0x1, // User land 'read', same as VM_PROT_READ
57 kIODirectionOut = 0x2, // User land 'write', same as VM_PROT_WRITE
58 kIODirectionOutIn = kIODirectionOut | kIODirectionIn,
59 kIODirectionInOut = kIODirectionIn | kIODirectionOut
60 };
61
62 /*
63 * IOOptionBits used in the withOptions variant
64 */
65 enum {
66 kIOMemoryDirectionMask = 0x00000007,
67 kIOMemoryAutoPrepare = 0x00000008, // Shared with Buffer MD
68
69 kIOMemoryTypeVirtual = 0x00000010,
70 kIOMemoryTypePhysical = 0x00000020,
71 kIOMemoryTypeUPL = 0x00000030,
72 kIOMemoryTypePersistentMD = 0x00000040, // Persistent Memory Descriptor
73 kIOMemoryTypeUIO = 0x00000050,
74 kIOMemoryTypeVirtual64 = 0x00000060,
75 kIOMemoryTypePhysical64 = 0x00000070,
76 kIOMemoryTypeMask = 0x000000f0,
77
78 kIOMemoryAsReference = 0x00000100,
79 kIOMemoryBufferPageable = 0x00000400,
80 kIOMemoryDontMap = 0x00000800,
81 kIOMemoryPersistent = 0x00010000,
82 kIOMemoryThreadSafe = 0x00020000
83 };
84
85 #define kIOMapperNone ((IOMapper *) -1)
86 #define kIOMapperSystem ((IOMapper *) 0)
87
88 enum
89 {
90 kIOMemoryPurgeableKeepCurrent = 1,
91 kIOMemoryPurgeableNonVolatile = 2,
92 kIOMemoryPurgeableVolatile = 3,
93 kIOMemoryPurgeableEmpty = 4
94 };
95 enum
96 {
97 kIOMemoryIncoherentIOFlush = 1,
98 kIOMemoryIncoherentIOStore = 2,
99 };
100
101 #define IOMEMORYDESCRIPTOR_SUPPORTS_DMACOMMAND 1
102
103
104 /*! @class IOMemoryDescriptor : public OSObject
105 @abstract An abstract base class defining common methods for describing physical or virtual memory.
106 @discussion The IOMemoryDescriptor object represents a buffer or range of memory, specified as one or more physical or virtual address ranges. It contains methods to return the memory's physically contiguous segments (fragments), for use with the IOMemoryCursor, and methods to map the memory into any address space with caching and placed mapping options. */
107
108 class IOMemoryDescriptor : public OSObject
109 {
110 friend class _IOMemoryMap;
111 friend class IOSubMemoryDescriptor;
112
113 OSDeclareDefaultStructors(IOMemoryDescriptor);
114
115 protected:
116 /*! @struct ExpansionData
117 @discussion This structure will be used to expand the capablilties of this class in the future.
118 */
119 struct ExpansionData {
120 void * devicePager;
121 unsigned int pagerContig:1;
122 unsigned int unused:31;
123 IOMemoryDescriptor * memory;
124 };
125
126 /*! @var reserved
127 Reserved for future use. (Internal use only) */
128 ExpansionData * reserved;
129
130 protected:
131 OSSet * _mappings;
132 IOOptionBits _flags;
133 void * _memEntry;
134
135 IODirection _direction; /* DEPRECATED: use _flags instead. direction of transfer */
136 IOByteCount _length; /* length of all ranges */
137 IOOptionBits _tag;
138
139 public:
140 typedef IOOptionBits DMACommandOps;
141 virtual IOPhysicalAddress getSourceSegment( IOByteCount offset,
142 IOByteCount * length );
143 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 0);
144
145 /*! @function initWithOptions
146 @abstract Master initialiser for all variants of memory descriptors. For a more complete description see IOMemoryDescriptor::withOptions.
147 @discussion Note this function can be used to re-init a previously created memory descriptor.
148 @result true on success, false on failure. */
149 virtual bool initWithOptions(void * buffers,
150 UInt32 count,
151 UInt32 offset,
152 task_t task,
153 IOOptionBits options,
154 IOMapper * mapper = kIOMapperSystem);
155 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 1);
156
157 virtual addr64_t getPhysicalSegment64( IOByteCount offset,
158 IOByteCount * length );
159 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 2);
160
161
162 /*! @function setPurgeable
163 @abstract Control the purgeable status of a memory descriptors memory.
164 @discussion Buffers may be allocated with the ability to have their purgeable status changed - IOBufferMemoryDescriptor with the kIOMemoryPurgeable option, VM_FLAGS_PURGEABLE may be passed to vm_allocate() in user space to allocate such buffers. The purgeable status of such a buffer may be controlled with setPurgeable(). The process of making a purgeable memory descriptor non-volatile and determining its previous state is atomic - if a purgeable memory descriptor is made nonvolatile and the old state is returned as kIOMemoryPurgeableVolatile, then the memory's previous contents are completely intact and will remain so until the memory is made volatile again. If the old state is returned as kIOMemoryPurgeableEmpty then the memory was reclaimed while it was in a volatile state and its previous contents have been lost.
165 @param newState - the desired new purgeable state of the memory:<br>
166 kIOMemoryPurgeableKeepCurrent - make no changes to the memory's purgeable state.<br>
167 kIOMemoryPurgeableVolatile - make the memory volatile - the memory may be reclaimed by the VM system without saving its contents to backing store.<br>
168 kIOMemoryPurgeableNonVolatile - make the memory nonvolatile - the memory is treated as with usual allocations and must be saved to backing store if paged.<br>
169 kIOMemoryPurgeableEmpty - make the memory volatile, and discard any pages allocated to it.
170 @param oldState - if non-NULL, the previous purgeable state of the memory is returned here:<br>
171 kIOMemoryPurgeableNonVolatile - the memory was nonvolatile.<br>
172 kIOMemoryPurgeableVolatile - the memory was volatile but its content has not been discarded by the VM system.<br>
173 kIOMemoryPurgeableEmpty - the memory was volatile and has been discarded by the VM system.<br>
174 @result An IOReturn code. */
175
176 virtual IOReturn setPurgeable( IOOptionBits newState,
177 IOOptionBits * oldState );
178 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 3);
179
180 /*! @function performOperation
181 @abstract Perform an operation on the memory descriptor's memory.
182 @discussion This method performs some operation on a range of the memory descriptor's memory. When a memory descriptor's memory is not mapped, it should be more efficient to use this method than mapping the memory to perform the operation virtually.
183 @param options The operation to perform on the memory:<br>
184 kIOMemoryIncoherentIOFlush - pass this option to store to memory and flush any data in the processor cache for the memory range, with synchronization to ensure the data has passed through all levels of processor cache. It may not be supported on all architectures. This type of flush may be used for non-coherent I/O such as AGP - it is NOT required for PCI coherent operations. The memory descriptor must have been previously prepared.<br>
185 kIOMemoryIncoherentIOStore - pass this option to store to memory any data in the processor cache for the memory range, with synchronization to ensure the data has passed through all levels of processor cache. It may not be supported on all architectures. This type of flush may be used for non-coherent I/O such as AGP - it is NOT required for PCI coherent operations. The memory descriptor must have been previously prepared.
186 @param offset A byte offset into the memory descriptor's memory.
187 @param length The length of the data range.
188 @result An IOReturn code. */
189
190 virtual IOReturn performOperation( IOOptionBits options,
191 IOByteCount offset, IOByteCount length );
192 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 4);
193
194 // Used for dedicated communications for IODMACommand
195 virtual IOReturn dmaCommandOperation(DMACommandOps op, void *vData, UInt dataSize) const;
196 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 5);
197
198 private:
199 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 6);
200 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 7);
201 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 8);
202 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 9);
203 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 10);
204 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 11);
205 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 12);
206 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 13);
207 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 14);
208 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 15);
209
210 protected:
211 virtual void free();
212 public:
213 static void initialize( void );
214
215 public:
216 /*! @function withAddress
217 @abstract Create an IOMemoryDescriptor to describe one virtual range of the kernel task.
218 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map.
219 @param address The virtual address of the first byte in the memory.
220 @param withLength The length of memory.
221 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
222 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
223
224 static IOMemoryDescriptor * withAddress(void * address,
225 IOByteCount withLength,
226 IODirection withDirection);
227
228 /*! @function withAddress
229 @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
230 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map.
231 @param address The virtual address of the first byte in the memory.
232 @param withLength The length of memory.
233 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
234 @param withTask The task the virtual ranges are mapped into.
235 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
236
237 static IOMemoryDescriptor * withAddress(vm_address_t address,
238 IOByteCount withLength,
239 IODirection withDirection,
240 task_t withTask);
241
242 /*! @function withPhysicalAddress
243 @abstract Create an IOMemoryDescriptor to describe one physical range.
244 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.
245 @param address The physical address of the first byte in the memory.
246 @param withLength The length of memory.
247 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
248 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
249
250 static IOMemoryDescriptor * withPhysicalAddress(
251 IOPhysicalAddress address,
252 IOByteCount withLength,
253 IODirection withDirection );
254
255 /*! @function withRanges
256 @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
257 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of virtual memory ranges each mapped into a specified source task.
258 @param ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
259 @param withCount The member count of the ranges array.
260 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
261 @param withTask The task each of the virtual ranges are mapped into.
262 @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
263 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
264
265 static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges,
266 UInt32 withCount,
267 IODirection withDirection,
268 task_t withTask,
269 bool asReference = false);
270
271 /*! @function withAddressRange
272 @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
273 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map. Note that unlike IOMemoryDescriptor::withAddress(), kernel_task memory must be explicitly prepared when passed to this api.
274 @param address The virtual address of the first byte in the memory.
275 @param withLength The length of memory.
276 @param options
277 kIOMemoryDirectionMask (options:direction) This nibble indicates the I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
278 @param task The task the virtual ranges are mapped into. Note that unlike IOMemoryDescriptor::withAddress(), kernel_task memory must be explicitly prepared when passed to this api.
279 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
280
281 static IOMemoryDescriptor * withAddressRange(
282 mach_vm_address_t address,
283 mach_vm_size_t length,
284 IOOptionBits options,
285 task_t task);
286
287 /*! @function withAddressRanges
288 @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
289 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of virtual memory ranges each mapped into a specified source task. Note that unlike IOMemoryDescriptor::withAddress(), kernel_task memory must be explicitly prepared when passed to this api.
290 @param ranges An array of IOAddressRange structures which specify the virtual ranges in the specified map which make up the memory to be described. IOAddressRange is the 64bit version of IOVirtualRange.
291 @param rangeCount The member count of the ranges array.
292 @param options
293 kIOMemoryDirectionMask (options:direction) This nibble indicates the I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
294 kIOMemoryAsReference For options:type = Virtual or Physical this indicate that the memory descriptor need not copy the ranges array into local memory. This is an optimisation to try to minimise unnecessary allocations.
295 @param task The task each of the virtual ranges are mapped into. Note that unlike IOMemoryDescriptor::withAddress(), kernel_task memory must be explicitly prepared when passed to this api.
296 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
297
298 static IOMemoryDescriptor * withAddressRanges(
299 IOAddressRange * ranges,
300 UInt32 rangeCount,
301 IOOptionBits options,
302 task_t withTask);
303
304 /*! @function withOptions
305 @abstract Master initialiser for all variants of memory descriptors.
306 @discussion This method creates and initializes an IOMemoryDescriptor for memory it has three main variants: Virtual, Physical & mach UPL. These variants are selected with the options parameter, see below. This memory descriptor needs to be prepared before it can be used to extract data from the memory described. However we temporarily have setup a mechanism that automatically prepares kernel_task memory descriptors at creation time.
307
308
309 @param buffers A pointer to an array of IOVirtualRanges or IOPhysicalRanges if the options:type is Virtual or Physical. For type UPL it is a upl_t returned by the mach/memory_object_types.h apis, primarily used internally by the UBC.
310
311 @param count options:type = Virtual or Physical count contains a count of the number of entires in the buffers array. For options:type = UPL this field contains a total length.
312
313 @param offset Only used when options:type = UPL, in which case this field contains an offset for the memory within the buffers upl.
314
315 @param task Only used options:type = Virtual, The task each of the virtual ranges are mapped into.
316
317 @param options
318 kIOMemoryDirectionMask (options:direction) This nibble indicates the I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
319 kIOMemoryTypeMask (options:type) kIOMemoryTypeVirtual, kIOMemoryTypePhysical, kIOMemoryTypeUPL Indicates that what type of memory basic memory descriptor to use. This sub-field also controls the interpretation of the buffers, count, offset & task parameters.
320 kIOMemoryAsReference For options:type = Virtual or Physical this indicate that the memory descriptor need not copy the ranges array into local memory. This is an optimisation to try to minimise unnecessary allocations.
321 kIOMemoryBufferPageable Only used by the IOBufferMemoryDescriptor as an indication that the kernel virtual memory is in fact pageable and we need to use the kernel pageable submap rather than the default map.
322 kIOMemoryNoAutoPrepare Indicates that the temporary AutoPrepare of kernel_task memory should not be performed.
323
324 @param mapper Which IOMapper should be used to map the in-memory physical addresses into I/O space addresses. Defaults to 0 which indicates that the system mapper is to be used, if present.
325
326 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
327
328 static IOMemoryDescriptor *withOptions(void * buffers,
329 UInt32 count,
330 UInt32 offset,
331 task_t task,
332 IOOptionBits options,
333 IOMapper * mapper = kIOMapperSystem);
334
335 /*! @function withPhysicalRanges
336 @abstract Create an IOMemoryDescriptor to describe one or more physical ranges.
337 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges.
338 @param ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
339 @param withCount The member count of the ranges array.
340 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
341 @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
342 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
343
344 static IOMemoryDescriptor * withPhysicalRanges(
345 IOPhysicalRange * ranges,
346 UInt32 withCount,
347 IODirection withDirection,
348 bool asReference = false);
349
350 /*! @function withSubRange
351 @abstract Create an IOMemoryDescriptor to describe a subrange of an existing descriptor.
352 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a subrange of the specified memory descriptor. The parent memory descriptor is retained by the new descriptor.
353 @param of The parent IOMemoryDescriptor of which a subrange is to be used for the new descriptor, which will be retained by the subrange IOMemoryDescriptor.
354 @param offset A byte offset into the parent memory descriptor's memory.
355 @param length The length of the subrange.
356 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures. This is used over the direction of the parent descriptor.
357 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
358
359 static IOMemoryDescriptor * withSubRange(IOMemoryDescriptor *of,
360 IOByteCount offset,
361 IOByteCount length,
362 IODirection withDirection);
363
364 /*! @function withPersistentMemoryDescriptor
365 @abstract Copy constructor that generates a new memory descriptor if the backing memory for the same task's virtual address and length has changed.
366 @discussion If the original memory descriptor's address and length is still backed by the same real memory, i.e. the user hasn't deallocated and the reallocated memory at the same address then the original memory descriptor is returned with a additional reference. Otherwise we build a totally new memory descriptor with the same characteristics as the previous one but with a new view of the vm. Note not legal to call this function with anything except an IOGeneralMemoryDescriptor that was created with the kIOMemoryPersistent option.
367 @param originalMD The memory descriptor to be duplicated.
368 @result Either the original memory descriptor with an additional retain or a new memory descriptor, 0 for a bad original memory descriptor or some other resource shortage. */
369 static IOMemoryDescriptor *
370 withPersistentMemoryDescriptor(IOMemoryDescriptor *originalMD);
371
372 /*! @function initWithAddress
373 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the kernel task.
374 @discussion This method initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
375 @param address The virtual address of the first byte in the memory.
376 @param withLength The length of memory.
377 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
378 @result true on success, false on failure. */
379
380 virtual bool initWithAddress(void * address,
381 IOByteCount withLength,
382 IODirection withDirection) = 0;
383
384 /*! @function initWithAddress
385 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the specified map.
386 @discussion This method initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
387 @param address The virtual address of the first byte in the memory.
388 @param withLength The length of memory.
389 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
390 @param withTask The task the virtual ranges are mapped into.
391 @result true on success, false on failure. */
392
393 virtual bool initWithAddress(vm_address_t address,
394 IOByteCount withLength,
395 IODirection withDirection,
396 task_t withTask) = 0;
397
398 /*! @function initWithPhysicalAddress
399 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one physical range.
400 @discussion This method initializes an IOMemoryDescriptor for memory consisting of a single physical memory range. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
401 @param address The physical address of the first byte in the memory.
402 @param withLength The length of memory.
403 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
404 @result true on success, false on failure. */
405
406 virtual bool initWithPhysicalAddress(
407 IOPhysicalAddress address,
408 IOByteCount withLength,
409 IODirection withDirection ) = 0;
410
411 /*! @function initWithRanges
412 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more virtual ranges.
413 @discussion This method initializes an IOMemoryDescriptor for memory consisting of an array of virtual memory ranges each mapped into a specified source task. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
414 @param ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
415 @param withCount The member count of the ranges array.
416 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
417 @param withTask The task each of the virtual ranges are mapped into.
418 @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
419 @result true on success, false on failure. */
420
421 virtual bool initWithRanges(IOVirtualRange * ranges,
422 UInt32 withCount,
423 IODirection withDirection,
424 task_t withTask,
425 bool asReference = false) = 0;
426
427 /*! @function initWithPhysicalRanges
428 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more physical ranges.
429 @discussion This method initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
430 @param ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
431 @param withCount The member count of the ranges array.
432 @param withDirection An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
433 @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
434 @result true on success, false on failure. */
435
436 virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
437 UInt32 withCount,
438 IODirection withDirection,
439 bool asReference = false) = 0;
440
441 /*! @function getDirection
442 @abstract Accessor to get the direction the memory descriptor was created with.
443 @discussion This method returns the direction the memory descriptor was created with.
444 @result The direction. */
445
446 virtual IODirection getDirection() const;
447
448 /*! @function getLength
449 @abstract Accessor to get the length of the memory descriptor (over all its ranges).
450 @discussion This method returns the total length of the memory described by the descriptor, ie. the sum of its ranges' lengths.
451 @result The byte count. */
452
453 virtual IOByteCount getLength() const;
454
455 /*! @function setTag
456 @abstract Set the tag for the memory descriptor.
457 @discussion This method sets the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
458 @param tag The tag. */
459
460 virtual void setTag( IOOptionBits tag );
461
462 /*! @function getTag
463 @abstract Accessor to the retrieve the tag for the memory descriptor.
464 @discussion This method returns the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
465 @result The tag. */
466
467 virtual IOOptionBits getTag( void );
468
469 /*! @function readBytes
470 @abstract Copy data from the memory descriptor's buffer to the specified buffer.
471 @discussion This method copies data from the memory descriptor's memory at the given offset, to the caller's buffer. The memory descriptor MUST have the kIODirectionOut direcction bit set and be prepared. kIODirectionOut means that this memory descriptor will be output to an external device, so readBytes is used to get memory into a local buffer for a PIO transfer to the device.
472 @param offset A byte offset into the memory descriptor's memory.
473 @param bytes The caller supplied buffer to copy the data to.
474 @param withLength The length of the data to copy.
475 @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */
476
477 virtual IOByteCount readBytes(IOByteCount offset,
478 void * bytes, IOByteCount withLength);
479
480 /*! @function writeBytes
481 @abstract Copy data to the memory descriptor's buffer from the specified buffer.
482 @discussion This method copies data to the memory descriptor's memory at the given offset, from the caller's buffer. The memory descriptor MUST have the kIODirectionIn direcction bit set and be prepared. kIODirectionIn means that this memory descriptor will be input from an external device, so writeBytes is used to write memory into the descriptor for PIO drivers.
483 @param offset A byte offset into the memory descriptor's memory.
484 @param bytes The caller supplied buffer to copy the data from.
485 @param withLength The length of the data to copy.
486 @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */
487
488 virtual IOByteCount writeBytes(IOByteCount offset,
489 const void * bytes, IOByteCount withLength);
490
491 /*! @function getPhysicalSegment
492 @abstract Break a memory descriptor into its physically contiguous segments.
493 @discussion This method returns the physical address of the byte at the given offset into the memory, and optionally the length of the physically contiguous segment from that offset.
494 @param offset A byte offset into the memory whose physical address to return.
495 @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
496 @result A physical address, or zero if the offset is beyond the length of the memory. */
497
498 virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
499 IOByteCount * length) = 0;
500
501 /*! @function getPhysicalAddress
502 @abstract Return the physical address of the first byte in the memory.
503 @discussion This method returns the physical address of the first byte in the memory. It is most useful on memory known to be physically contiguous.
504 @result A physical address. */
505
506 /* inline */ IOPhysicalAddress getPhysicalAddress();
507 /* { return( getPhysicalSegment( 0, 0 )); } */
508
509 /* DEPRECATED */ /* USE INSTEAD: map(), readBytes(), writeBytes() */
510 /* DEPRECATED */ virtual void * getVirtualSegment(IOByteCount offset,
511 /* DEPRECATED */ IOByteCount * length) = 0;
512 /* DEPRECATED */ /* USE INSTEAD: map(), readBytes(), writeBytes() */
513
514 /*! @function prepare
515 @abstract Prepare the memory for an I/O transfer.
516 @discussion This involves paging in the memory, if necessary, and wiring it down for the duration of the transfer. The complete() method completes the processing of the memory after the I/O transfer finishes. Note that the prepare call is not thread safe and it is expected that the client will more easily be able to guarantee single threading a particular memory descriptor.
517 @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
518 @result An IOReturn code. */
519
520 virtual IOReturn prepare(IODirection forDirection = kIODirectionNone) = 0;
521
522 /*! @function complete
523 @abstract Complete processing of the memory after an I/O transfer finishes.
524 @discussion This method should not be called unless a prepare was previously issued; the prepare() and complete() must occur in pairs, before and after an I/O transfer involving pageable memory. In 10.3 or greater systems the direction argument to complete is not longer respected. The direction is totally determined at prepare() time.
525 @param forDirection DEPRECATED The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
526 @result An IOReturn code. */
527
528 virtual IOReturn complete(IODirection forDirection = kIODirectionNone) = 0;
529
530 /*
531 * Mapping functions.
532 */
533
534 /*! @function createMappingInTask
535 @abstract Maps a IOMemoryDescriptor into a task.
536 @discussion This is the general purpose method to map all or part of the memory described by a memory descriptor into a task at any available address, or at a fixed address if possible. Caching & read-only options may be set for the mapping. The mapping is represented as a returned reference to a IOMemoryMap object, which may be shared if the mapping is compatible with an existing mapping of the IOMemoryDescriptor. The IOMemoryMap object returned should be released only when the caller has finished accessing the mapping, as freeing the object destroys the mapping.
537 @param intoTask Sets the target task for the mapping. Pass kernel_task for the kernel address space.
538 @param atAddress If a placed mapping is requested, atAddress specifies its address, and the kIOMapAnywhere should not be set. Otherwise, atAddress is ignored.
539 @param options Mapping options are defined in IOTypes.h,<br>
540 kIOMapAnywhere should be passed if the mapping can be created anywhere. If not set, the atAddress parameter sets the location of the mapping, if it is available in the target map.<br>
541 kIOMapDefaultCache to inhibit the cache in I/O areas, kIOMapCopybackCache in general purpose RAM.<br>
542 kIOMapInhibitCache, kIOMapWriteThruCache, kIOMapCopybackCache to set the appropriate caching.<br>
543 kIOMapReadOnly to allow only read only accesses to the memory - writes will cause and access fault.<br>
544 kIOMapReference will only succeed if the mapping already exists, and the IOMemoryMap object is just an extra reference, ie. no new mapping will be created.<br>
545 kIOMapUnique allows a special kind of mapping to be created that may be used with the IOMemoryMap::redirect() API. These mappings will not be shared as is the default - there will always be a unique mapping created for the caller, not an existing mapping with an extra reference.<br>
546 @param offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
547 @param length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
548 @result A reference to an IOMemoryMap object representing the mapping, which can supply the virtual address of the mapping and other information. The mapping may be shared with multiple callers - multiple maps are avoided if a compatible one exists. The IOMemoryMap object returned should be released only when the caller has finished accessing the mapping, as freeing the object destroys the mapping. The IOMemoryMap instance also retains the IOMemoryDescriptor it maps while it exists. */
549
550 IOMemoryMap * createMappingInTask(
551 task_t intoTask,
552 mach_vm_address_t atAddress,
553 IOOptionBits options,
554 mach_vm_size_t offset = 0,
555 mach_vm_size_t length = 0 );
556
557 /*! @function map
558 @abstract Maps a IOMemoryDescriptor into a task - deprecated, only safe for 32 bit tasks. Use createMappingInTask instead.
559 @discussion This is the general purpose method to map all or part of the memory described by a memory descriptor into a task at any available address, or at a fixed address if possible. Caching & read-only options may be set for the mapping. The mapping is represented as a returned reference to a IOMemoryMap object, which may be shared if the mapping is compatible with an existing mapping of the IOMemoryDescriptor. The IOMemoryMap object returned should be released only when the caller has finished accessing the mapping, as freeing the object destroys the mapping.
560 @param intoTask Sets the target task for the mapping. Pass kernel_task for the kernel address space.
561 @param atAddress If a placed mapping is requested, atAddress specifies its address, and the kIOMapAnywhere should not be set. Otherwise, atAddress is ignored.
562 @param options Mapping options are defined in IOTypes.h,<br>
563 kIOMapAnywhere should be passed if the mapping can be created anywhere. If not set, the atAddress parameter sets the location of the mapping, if it is available in the target map.<br>
564 kIOMapDefaultCache to inhibit the cache in I/O areas, kIOMapCopybackCache in general purpose RAM.<br>
565 kIOMapInhibitCache, kIOMapWriteThruCache, kIOMapCopybackCache to set the appropriate caching.<br>
566 kIOMapReadOnly to allow only read only accesses to the memory - writes will cause and access fault.<br>
567 kIOMapReference will only succeed if the mapping already exists, and the IOMemoryMap object is just an extra reference, ie. no new mapping will be created.<br>
568 kIOMapUnique allows a special kind of mapping to be created that may be used with the IOMemoryMap::redirect() API. These mappings will not be shared as is the default - there will always be a unique mapping created for the caller, not an existing mapping with an extra reference.<br>
569 @param offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
570 @param length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
571 @result A reference to an IOMemoryMap object representing the mapping, which can supply the virtual address of the mapping and other information. The mapping may be shared with multiple callers - multiple maps are avoided if a compatible one exists. The IOMemoryMap object returned should be released only when the caller has finished accessing the mapping, as freeing the object destroys the mapping. The IOMemoryMap instance also retains the IOMemoryDescriptor it maps while it exists. */
572
573 virtual IOMemoryMap * map(
574 task_t intoTask,
575 IOVirtualAddress atAddress,
576 IOOptionBits options,
577 IOByteCount offset = 0,
578 IOByteCount length = 0 );
579
580
581 /*! @function map
582 @abstract Maps a IOMemoryDescriptor into the kernel map.
583 @discussion This is a shortcut method to map all the memory described by a memory descriptor into the kernel map at any available address. See the full version of the createMappingInTask method for further details.
584 @param options Mapping options as in the full version of the createMappingInTask method, with kIOMapAnywhere assumed.
585 @result See the full version of the createMappingInTask method. */
586
587 virtual IOMemoryMap * map(
588 IOOptionBits options = 0 );
589
590 /*! @function setMapping
591 @abstract Establishes an already existing mapping.
592 @discussion This method tells the IOMemoryDescriptor about a mapping that exists, but was created elsewhere. It allows later callers of the map method to share this externally created mapping. The IOMemoryMap object returned is created to represent it. This method is not commonly needed.
593 @param task Address space in which the mapping exists.
594 @param mapAddress Virtual address of the mapping.
595 @param options Caching and read-only attributes of the mapping.
596 @result A IOMemoryMap object created to represent the mapping. */
597
598 virtual IOMemoryMap * setMapping(
599 task_t task,
600 IOVirtualAddress mapAddress,
601 IOOptionBits options = 0 );
602
603 // Following methods are private implementation
604
605 // make virtual
606 IOReturn redirect( task_t safeTask, bool redirect );
607
608 IOReturn handleFault(
609 void * pager,
610 vm_map_t addressMap,
611 mach_vm_address_t address,
612 mach_vm_size_t sourceOffset,
613 mach_vm_size_t length,
614 IOOptionBits options );
615
616 protected:
617 virtual IOMemoryMap * makeMapping(
618 IOMemoryDescriptor * owner,
619 task_t intoTask,
620 IOVirtualAddress atAddress,
621 IOOptionBits options,
622 IOByteCount offset,
623 IOByteCount length );
624
625 virtual void addMapping(
626 IOMemoryMap * mapping );
627
628 virtual void removeMapping(
629 IOMemoryMap * mapping );
630
631 virtual IOReturn doMap(
632 vm_map_t addressMap,
633 IOVirtualAddress * atAddress,
634 IOOptionBits options,
635 IOByteCount sourceOffset = 0,
636 IOByteCount length = 0 );
637
638 virtual IOReturn doUnmap(
639 vm_map_t addressMap,
640 IOVirtualAddress logical,
641 IOByteCount length );
642 };
643
644 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
645
646 /*! @class IOMemoryMap : public OSObject
647 @abstract An abstract base class defining common methods for describing a memory mapping.
648 @discussion The IOMemoryMap object represents a mapped range of memory, described by a IOMemoryDescriptor. The mapping may be in the kernel or a non-kernel task and has processor cache mode attributes. IOMemoryMap instances are created by IOMemoryDescriptor when it creates mappings in its map method, and returned to the caller. */
649
650 class IOMemoryMap : public OSObject
651 {
652 OSDeclareAbstractStructors(IOMemoryMap)
653
654 public:
655 /*! @function getVirtualAddress
656 @abstract Accessor to the virtual address of the first byte in the mapping.
657 @discussion This method returns the virtual address of the first byte in the mapping.
658 @result A virtual address. */
659
660 virtual IOVirtualAddress getVirtualAddress() = 0;
661
662 /*! @function getPhysicalSegment
663 @abstract Break a mapping into its physically contiguous segments.
664 @discussion This method returns the physical address of the byte at the given offset into the mapping, and optionally the length of the physically contiguous segment from that offset. It functions similarly to IOMemoryDescriptor::getPhysicalSegment.
665 @param offset A byte offset into the mapping whose physical address to return.
666 @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
667 @result A physical address, or zero if the offset is beyond the length of the mapping. */
668
669 virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
670 IOByteCount * length) = 0;
671
672 /*! @function getPhysicalAddress
673 @abstract Return the physical address of the first byte in the mapping.
674 @discussion This method returns the physical address of the first byte in the mapping. It is most useful on mappings known to be physically contiguous.
675 @result A physical address. */
676
677 /* inline */ IOPhysicalAddress getPhysicalAddress();
678 /* { return( getPhysicalSegment( 0, 0 )); } */
679
680 /*! @function getLength
681 @abstract Accessor to the length of the mapping.
682 @discussion This method returns the length of the mapping.
683 @result A byte count. */
684
685 virtual IOByteCount getLength() = 0;
686
687 /*! @function getAddressTask
688 @abstract Accessor to the task of the mapping.
689 @discussion This method returns the mach task the mapping exists in.
690 @result A mach task_t. */
691
692 virtual task_t getAddressTask() = 0;
693
694 /*! @function getMemoryDescriptor
695 @abstract Accessor to the IOMemoryDescriptor the mapping was created from.
696 @discussion This method returns the IOMemoryDescriptor the mapping was created from.
697 @result An IOMemoryDescriptor reference, which is valid while the IOMemoryMap object is retained. It should not be released by the caller. */
698
699 virtual IOMemoryDescriptor * getMemoryDescriptor() = 0;
700
701 /*! @function getMapOptions
702 @abstract Accessor to the options the mapping was created with.
703 @discussion This method returns the options to IOMemoryDescriptor::map the mapping was created with.
704 @result Options for the mapping, including cache settings. */
705
706 virtual IOOptionBits getMapOptions() = 0;
707
708 /*! @function unmap
709 @abstract Force the IOMemoryMap to unmap, without destroying the object.
710 @discussion IOMemoryMap instances will unmap themselves upon free, ie. when the last client with a reference calls release. This method forces the IOMemoryMap to destroy the mapping it represents, regardless of the number of clients. It is not generally used.
711 @result An IOReturn code. */
712
713 virtual IOReturn unmap() = 0;
714
715 virtual void taskDied() = 0;
716
717 /*! @function redirect
718 @abstract Replace the memory mapped in a process with new backing memory.
719 @discussion An IOMemoryMap created with the kIOMapUnique option to IOMemoryDescriptor::map() can remapped to a new IOMemoryDescriptor backing object. If the new IOMemoryDescriptor is specified as NULL, client access to the memory map is blocked until a new backing object has been set. By blocking access and copying data, the caller can create atomic copies of the memory while the client is potentially reading or writing the memory.
720 @param newBackingMemory The IOMemoryDescriptor that represents the physical memory that is to be now mapped in the virtual range the IOMemoryMap represents. If newBackingMemory is NULL, any access to the mapping will hang (in vm_fault()) until access has been restored by a new call to redirect() with non-NULL newBackingMemory argument.
721 @param options Mapping options are defined in IOTypes.h, and are documented in IOMemoryDescriptor::map()
722 @param offset As with IOMemoryDescriptor::map(), a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default.
723 @result An IOReturn code. */
724
725 virtual IOReturn redirect(IOMemoryDescriptor * newBackingMemory,
726 IOOptionBits options,
727 IOByteCount offset = 0) = 0;
728
729 virtual IOReturn redirect(IOMemoryDescriptor * newBackingMemory,
730 IOOptionBits options,
731 mach_vm_size_t offset = 0) = 0;
732
733 virtual mach_vm_address_t getAddress() = 0;
734 virtual mach_vm_size_t getSize() = 0;
735 };
736
737 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
738
739 // The following classes are private implementation of IOMemoryDescriptor - they
740 // should not be referenced directly, just through the public API's in the
741 // IOMemoryDescriptor class. For example, an IOGeneralMemoryDescriptor instance
742 // might be created by IOMemoryDescriptor::withAddress(), but there should be
743 // no need to reference as anything but a generic IOMemoryDescriptor *.
744
745 // Also these flags should not overlap with the options to
746 // IOMemoryDescriptor::initWithRanges(... IOOptionsBits options);
747
748 enum {
749 kIOMemoryPreparedReadOnly = 0x00008000,
750 };
751
752 class IOGeneralMemoryDescriptor : public IOMemoryDescriptor
753 {
754 OSDeclareDefaultStructors(IOGeneralMemoryDescriptor);
755
756 public:
757 union Ranges {
758 IOVirtualRange *v;
759 IOAddressRange *v64;
760 IOPhysicalRange *p;
761 void *uio;
762 };
763 protected:
764 Ranges _ranges;
765 unsigned _rangesCount; /* number of address ranges in list */
766 bool _rangesIsAllocated; /* is list allocated by us? */
767
768 task_t _task; /* task where all ranges are mapped to */
769
770 union {
771 IOVirtualRange v;
772 IOPhysicalRange p;
773 } _singleRange; /* storage space for a single range */
774
775 unsigned _wireCount; /* number of outstanding wires */
776
777 /* DEPRECATED */ vm_address_t _cachedVirtualAddress; /* a cached virtual-to-physical */
778
779 /* DEPRECATED */ IOPhysicalAddress _cachedPhysicalAddress;
780
781 bool _initialized; /* has superclass been initialized? */
782
783 virtual void free();
784
785 virtual IOReturn dmaCommandOperation(DMACommandOps op, void *vData, UInt dataSize) const;
786
787 private:
788
789 /* DEPRECATED */ virtual void setPosition(IOByteCount position);
790 /* DEPRECATED */ virtual void mapIntoKernel(unsigned rangeIndex);
791 /* DEPRECATED */ virtual void unmapFromKernel();
792
793 // Internal APIs may be made virtual at some time in the future.
794 IOReturn wireVirtual(IODirection forDirection);
795 void *createNamedEntry();
796
797 // Internal
798 OSData * _memoryEntries;
799 unsigned int _pages;
800 ppnum_t _highestPage;
801 uint32_t __iomd_reservedA;
802 uint32_t __iomd_reservedB;
803
804 IOLock * _prepareLock;
805
806 public:
807 /*
808 * IOMemoryDescriptor required methods
809 */
810
811 // Master initaliser
812 virtual bool initWithOptions(void * buffers,
813 UInt32 count,
814 UInt32 offset,
815 task_t task,
816 IOOptionBits options,
817 IOMapper * mapper = kIOMapperSystem);
818
819 // Secondary initialisers
820 virtual bool initWithAddress(void * address,
821 IOByteCount withLength,
822 IODirection withDirection);
823
824 virtual bool initWithAddress(vm_address_t address,
825 IOByteCount withLength,
826 IODirection withDirection,
827 task_t withTask);
828
829 virtual bool initWithPhysicalAddress(
830 IOPhysicalAddress address,
831 IOByteCount withLength,
832 IODirection withDirection );
833
834 virtual bool initWithRanges( IOVirtualRange * ranges,
835 UInt32 withCount,
836 IODirection withDirection,
837 task_t withTask,
838 bool asReference = false);
839
840 virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
841 UInt32 withCount,
842 IODirection withDirection,
843 bool asReference = false);
844
845 virtual addr64_t getPhysicalSegment64( IOByteCount offset,
846 IOByteCount * length );
847
848 virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
849 IOByteCount * length);
850
851 virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
852 IOByteCount * length);
853
854 /* DEPRECATED */ virtual void * getVirtualSegment(IOByteCount offset,
855 /* DEPRECATED */ IOByteCount * length);
856
857 virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);
858
859 virtual IOReturn complete(IODirection forDirection = kIODirectionNone);
860
861 virtual IOReturn doMap(
862 vm_map_t addressMap,
863 IOVirtualAddress * atAddress,
864 IOOptionBits options,
865 IOByteCount sourceOffset = 0,
866 IOByteCount length = 0 );
867
868 virtual IOReturn doUnmap(
869 vm_map_t addressMap,
870 IOVirtualAddress logical,
871 IOByteCount length );
872
873 virtual bool serialize(OSSerialize *s) const;
874
875 // Factory method for cloning a persistent IOMD, see IOMemoryDescriptor
876 static IOMemoryDescriptor *
877 withPersistentMemoryDescriptor(IOGeneralMemoryDescriptor *originalMD);
878
879 };
880
881 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
882
883 class IOSubMemoryDescriptor : public IOMemoryDescriptor
884 {
885 friend class IOMemoryDescriptor;
886
887 OSDeclareDefaultStructors(IOSubMemoryDescriptor);
888
889 protected:
890 IOMemoryDescriptor * _parent;
891 IOByteCount _start;
892
893 virtual void free();
894
895 virtual bool initWithAddress(void * address,
896 IOByteCount withLength,
897 IODirection withDirection);
898
899 virtual bool initWithAddress(vm_address_t address,
900 IOByteCount withLength,
901 IODirection withDirection,
902 task_t withTask);
903
904 virtual bool initWithPhysicalAddress(
905 IOPhysicalAddress address,
906 IOByteCount withLength,
907 IODirection withDirection );
908
909 virtual bool initWithRanges( IOVirtualRange * ranges,
910 UInt32 withCount,
911 IODirection withDirection,
912 task_t withTask,
913 bool asReference = false);
914
915 virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
916 UInt32 withCount,
917 IODirection withDirection,
918 bool asReference = false);
919
920 IOMemoryDescriptor::withAddress;
921 IOMemoryDescriptor::withPhysicalAddress;
922 IOMemoryDescriptor::withPhysicalRanges;
923 IOMemoryDescriptor::withRanges;
924 IOMemoryDescriptor::withSubRange;
925
926 // used by IODMACommand
927 virtual IOReturn dmaCommandOperation(DMACommandOps op, void *vData, UInt dataSize) const;
928
929 public:
930 /*
931 * Initialize or reinitialize an IOSubMemoryDescriptor to describe
932 * a subrange of an existing descriptor.
933 *
934 * An IOSubMemoryDescriptor can be re-used by calling initSubRange
935 * again on an existing instance -- note that this behavior is not
936 * commonly supported in other IOKit classes, although it is here.
937 */
938 virtual bool initSubRange( IOMemoryDescriptor * parent,
939 IOByteCount offset, IOByteCount length,
940 IODirection withDirection );
941
942 /*
943 * IOMemoryDescriptor required methods
944 */
945
946 virtual addr64_t getPhysicalSegment64( IOByteCount offset,
947 IOByteCount * length );
948
949 virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
950 IOByteCount * length);
951
952 virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
953 IOByteCount * length);
954
955 virtual IOByteCount readBytes(IOByteCount offset,
956 void * bytes, IOByteCount withLength);
957
958 virtual IOByteCount writeBytes(IOByteCount offset,
959 const void * bytes, IOByteCount withLength);
960
961 virtual void * getVirtualSegment(IOByteCount offset,
962 IOByteCount * length);
963
964 virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);
965
966 virtual IOReturn complete(IODirection forDirection = kIODirectionNone);
967
968 // make virtual
969 IOReturn redirect( task_t safeTask, bool redirect );
970
971 virtual bool serialize(OSSerialize *s) const;
972
973 virtual IOReturn setPurgeable( IOOptionBits newState,
974 IOOptionBits * oldState );
975 virtual IOReturn performOperation( IOOptionBits options,
976 IOByteCount offset, IOByteCount length );
977
978 protected:
979 virtual IOMemoryMap * makeMapping(
980 IOMemoryDescriptor * owner,
981 task_t intoTask,
982 IOVirtualAddress atAddress,
983 IOOptionBits options,
984 IOByteCount offset,
985 IOByteCount length );
986
987 virtual IOReturn doMap(
988 vm_map_t addressMap,
989 IOVirtualAddress * atAddress,
990 IOOptionBits options,
991 IOByteCount sourceOffset = 0,
992 IOByteCount length = 0 );
993 };
994
995 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
996
997 #endif /* !_IOMEMORYDESCRIPTOR_H */
Cache object: cf561a15520bb824828b0b71b194dc41
|