iokit/IOKit/IOMemoryDescriptor.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_OSREFERENCE_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
  10  * License may not be used to create, or enable the creation or
  11  * redistribution of, unlawful or unlicensed copies of an Apple operating
  12  * system, or to circumvent, violate, or enable the circumvention or
  13  * violation of, any terms of an Apple operating system software license
  14  * agreement.
  15  *
  16  * Please obtain a copy of the License at
  17  * http://www.opensource.apple.com/apsl/ and read it before using this
  18  * file.
  19  *
  20  * The Original Code and all software distributed under the License are
  21  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25  * Please see the License for the specific language governing rights and
  26  * limitations under the License.
  27  *
  28  * @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29  */
  30 #ifndef _IOMEMORYDESCRIPTOR_H
  31 #define _IOMEMORYDESCRIPTOR_H
  32
  33 #include <sys/cdefs.h>
  34
  35 #include <IOKit/IOTypes.h>
  36 #include <libkern/c++/OSContainers.h>
  37
  38 __BEGIN_DECLS
  39 #include <mach/memory_object_types.h>
  40 __END_DECLS
  41
  42 struct IOPhysicalRange
  43 {
  44     IOPhysicalAddress   address;
  45     IOByteCount         length;
  46 };
  47
  48 class IOMemoryMap;
  49 class IOMapper;
  50
  51 /*
  52  * Direction of transfer, with respect to the described memory.
  53  */
  54 enum IODirection
  55 {
  56     kIODirectionNone  = 0x0,    //                    same as VM_PROT_NONE
  57     kIODirectionIn    = 0x1,    // User land 'read',  same as VM_PROT_READ
  58     kIODirectionOut   = 0x2,    // User land 'write', same as VM_PROT_WRITE
  59     kIODirectionOutIn = kIODirectionOut | kIODirectionIn,
  60     kIODirectionInOut = kIODirectionIn  | kIODirectionOut
  61 };
  62
  63 /*
  64  * IOOptionBits used in the withOptions variant
  65  */
  66 enum {
  67     kIOMemoryDirectionMask      = 0x00000007,
  68     kIOMemoryAutoPrepare        = 0x00000008,   // Shared with Buffer MD
  69
  70     kIOMemoryTypeVirtual        = 0x00000010,
  71     kIOMemoryTypePhysical       = 0x00000020,
  72     kIOMemoryTypeUPL            = 0x00000030,
  73     kIOMemoryTypePersistentMD   = 0x00000040,   // Persistent Memory Descriptor
  74     kIOMemoryTypeUIO            = 0x00000050,
  75     kIOMemoryTypeMask           = 0x000000f0,
  76
  77     kIOMemoryAsReference        = 0x00000100,
  78     kIOMemoryBufferPageable     = 0x00000400,
  79     kIOMemoryDontMap            = 0x00000800,
  80     kIOMemoryPersistent         = 0x00010000
  81 };
  82
  83 #define kIOMapperNone   ((IOMapper *) -1)
  84 #define kIOMapperSystem ((IOMapper *) 0)
  85
  86 enum
  87 {
  88     kIOMemoryPurgeableKeepCurrent = 1,
  89     kIOMemoryPurgeableNonVolatile = 2,
  90     kIOMemoryPurgeableVolatile    = 3,
  91     kIOMemoryPurgeableEmpty       = 4
  92 };
  93 enum
  94 {
  95     kIOMemoryIncoherentIOFlush   = 1,
  96     kIOMemoryIncoherentIOStore   = 2,
  97 };
  98
  99 /*! @class IOMemoryDescriptor : public OSObject
 100     @abstract An abstract base class defining common methods for describing physical or virtual memory.
 101     @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. */
 102
 103 class IOMemoryDescriptor : public OSObject
 104 {
 105     friend class _IOMemoryMap;
 106     friend class IOSubMemoryDescriptor;
 107
 108     OSDeclareDefaultStructors(IOMemoryDescriptor);
 109
 110 protected:
 111 /*! @struct ExpansionData
 112     @discussion This structure will be used to expand the capablilties of this class in the future.
 113     */
 114     struct ExpansionData {
 115         void *                          devicePager;
 116         unsigned int                    pagerContig:1;
 117         unsigned int                    unused:31;
 118         IOMemoryDescriptor *            memory;
 119     };
 120
 121 /*! @var reserved
 122     Reserved for future use.  (Internal use only)  */
 123     ExpansionData * reserved;
 124
 125 protected:
 126     OSSet *             _mappings;
 127     IOOptionBits        _flags;
 128     void *              _memEntry;
 129
 130     IODirection         _direction;        /* DEPRECATED: use _flags instead. direction of transfer */
 131     IOByteCount         _length;           /* length of all ranges */
 132     IOOptionBits        _tag;
 133
 134 public:
 135
 136     virtual IOPhysicalAddress getSourceSegment( IOByteCount offset,
 137                                                 IOByteCount * length );
 138     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 0);
 139
 140 /*! @function initWithOptions
 141     @abstract Master initialiser for all variants of memory descriptors.  For a more complete description see IOMemoryDescriptor::withOptions.
 142     @discussion Note this function can be used to re-init a previously created memory descriptor.
 143     @result true on success, false on failure. */
 144     virtual bool initWithOptions(void *         buffers,
 145                                  UInt32         count,
 146                                  UInt32         offset,
 147                                  task_t         task,
 148                                  IOOptionBits   options,
 149                                  IOMapper *     mapper = 0);
 150     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 1);
 151
 152     virtual addr64_t getPhysicalSegment64( IOByteCount offset,
 153                                             IOByteCount * length );
 154     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 2);
 155
 156
 157 /*! @function setPurgeable
 158     @abstract Control the purgeable status of a memory descriptors memory.
 159     @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.
 160     @param newState - the desired new purgeable state of the memory:<br>
 161     kIOMemoryPurgeableKeepCurrent - make no changes to the memory's purgeable state.<br>
 162     kIOMemoryPurgeableVolatile    - make the memory volatile - the memory may be reclaimed by the VM system without saving its contents to backing store.<br>
 163     kIOMemoryPurgeableNonVolatile - make the memory nonvolatile - the memory is treated as with usual allocations and must be saved to backing store if paged.<br>
 164     kIOMemoryPurgeableEmpty       - make the memory volatile, and discard any pages allocated to it.
 165     @param oldState - if non-NULL, the previous purgeable state of the memory is returned here:<br>
 166     kIOMemoryPurgeableNonVolatile - the memory was nonvolatile.<br>
 167     kIOMemoryPurgeableVolatile    - the memory was volatile but its content has not been discarded by the VM system.<br>
 168     kIOMemoryPurgeableEmpty       - the memory was volatile and has been discarded by the VM system.<br>
 169     @result An IOReturn code. */
 170
 171     virtual IOReturn setPurgeable( IOOptionBits newState,
 172                                     IOOptionBits * oldState );
 173     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 3);
 174
 175 /*! @function performOperation
 176     @abstract Perform an operation on the memory descriptor's memory.
 177     @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.
 178     @param options The operation to perform on the memory:<br>
 179     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>
 180     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.
 181     @param offset A byte offset into the memory descriptor's memory.
 182     @param length The length of the data range.
 183     @result An IOReturn code. */
 184
 185     virtual IOReturn performOperation( IOOptionBits options,
 186                                         IOByteCount offset, IOByteCount length );
 187     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 4);
 188
 189 private:
 190
 191     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 5);
 192     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 6);
 193     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 7);
 194     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 8);
 195     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 9);
 196     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 10);
 197     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 11);
 198     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 12);
 199     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 13);
 200     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 14);
 201     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 15);
 202
 203 protected:
 204     virtual void free();
 205 public:
 206     static void initialize( void );
 207
 208 public:
 209 /*! @function withAddress
 210     @abstract Create an IOMemoryDescriptor to describe one virtual range of the kernel task.
 211     @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map.
 212     @param address The virtual address of the first byte in the memory.
 213     @param withLength The length of memory.
 214     @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.
 215     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 216
 217     static IOMemoryDescriptor * withAddress(void *       address,
 218                                             IOByteCount  withLength,
 219                                             IODirection  withDirection);
 220
 221 /*! @function withAddress
 222     @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
 223     @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map.
 224     @param address The virtual address of the first byte in the memory.
 225     @param withLength The length of memory.
 226     @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.
 227     @param withTask The task the virtual ranges are mapped into.
 228     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 229
 230     static IOMemoryDescriptor * withAddress(vm_address_t address,
 231                                             IOByteCount  withLength,
 232                                             IODirection  withDirection,
 233                                             task_t       withTask);
 234
 235 /*! @function withPhysicalAddress
 236     @abstract Create an IOMemoryDescriptor to describe one physical range.
 237     @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.
 238     @param address The physical address of the first byte in the memory.
 239     @param withLength The length of memory.
 240     @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.
 241     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 242
 243     static IOMemoryDescriptor * withPhysicalAddress(
 244                                 IOPhysicalAddress       address,
 245                                 IOByteCount             withLength,
 246                                 IODirection             withDirection );
 247
 248 /*! @function withRanges
 249     @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
 250     @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.
 251     @param ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
 252     @param withCount The member count of the ranges array.
 253     @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.
 254     @param withTask The task each of the virtual ranges are mapped into.
 255     @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.
 256     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 257
 258      static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges,
 259                                             UInt32           withCount,
 260                                             IODirection      withDirection,
 261                                             task_t           withTask,
 262                                             bool             asReference = false);
 263
 264 /*! @function withOptions
 265     @abstract Master initialiser for all variants of memory descriptors.
 266     @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.
 267
 268
 269     @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.
 270
 271     @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.
 272
 273     @param offset Only used when options:type = UPL, in which case this field contains an offset for the memory within the buffers upl.
 274
 275     @param task Only used options:type = Virtual, The task each of the virtual ranges are mapped into.
 276
 277     @param options
 278         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.
 279         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.
 280         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.
 281         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.
 282         kIOMemoryNoAutoPrepare  Indicates that the temporary AutoPrepare of kernel_task memory should not be performed.
 283
 284     @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.
 285
 286     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 287
 288     static IOMemoryDescriptor *withOptions(void *       buffers,
 289                                            UInt32       count,
 290                                            UInt32       offset,
 291                                            task_t       task,
 292                                            IOOptionBits options,
 293                                            IOMapper *   mapper = 0);
 294
 295 /*! @function withPhysicalRanges
 296     @abstract Create an IOMemoryDescriptor to describe one or more physical ranges.
 297     @discussion  This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges.
 298     @param ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
 299     @param withCount The member count of the ranges array.
 300     @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.
 301     @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.
 302     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 303
 304     static IOMemoryDescriptor * withPhysicalRanges(
 305                                             IOPhysicalRange *   ranges,
 306                                             UInt32              withCount,
 307                                             IODirection         withDirection,
 308                                             bool                asReference = false);
 309
 310 /*! @function withSubRange
 311     @abstract Create an IOMemoryDescriptor to describe a subrange of an existing descriptor.
 312     @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.
 313     @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.
 314     @param offset A byte offset into the parent memory descriptor's memory.
 315     @param length The length of the subrange.
 316     @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.
 317     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 318
 319     static IOMemoryDescriptor * withSubRange(IOMemoryDescriptor *of,
 320                                              IOByteCount offset,
 321                                              IOByteCount length,
 322                                              IODirection withDirection);
 323
 324 /*! @function withPersistentMemoryDescriptor
 325     @abstract Copy constructor that generates a new memory descriptor if the backing memory for the same task's virtual address and length has changed.
 326     @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.
 327     @param originalMD The memory descriptor to be duplicated.
 328     @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. */
 329     static IOMemoryDescriptor *
 330         withPersistentMemoryDescriptor(IOMemoryDescriptor *originalMD);
 331
 332 /*! @function initWithAddress
 333     @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the kernel task.
 334     @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.
 335     @param address The virtual address of the first byte in the memory.
 336     @param withLength The length of memory.
 337     @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.
 338     @result true on success, false on failure. */
 339
 340     virtual bool initWithAddress(void *       address,
 341                                  IOByteCount  withLength,
 342                                  IODirection  withDirection) = 0;
 343
 344 /*! @function initWithAddress
 345     @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the specified map.
 346     @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.
 347     @param address The virtual address of the first byte in the memory.
 348     @param withLength The length of memory.
 349     @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.
 350     @param withTask The task the virtual ranges are mapped into.
 351     @result true on success, false on failure. */
 352
 353     virtual bool initWithAddress(vm_address_t address,
 354                                  IOByteCount  withLength,
 355                                  IODirection  withDirection,
 356                                  task_t       withTask) = 0;
 357
 358 /*! @function initWithPhysicalAddress
 359     @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one physical range.
 360     @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.
 361     @param address The physical address of the first byte in the memory.
 362     @param withLength The length of memory.
 363     @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.
 364     @result true on success, false on failure. */
 365
 366     virtual bool initWithPhysicalAddress(
 367                                  IOPhysicalAddress      address,
 368                                  IOByteCount            withLength,
 369                                  IODirection            withDirection ) = 0;
 370
 371 /*! @function initWithRanges
 372     @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more virtual ranges.
 373     @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.
 374     @param ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
 375     @param withCount The member count of the ranges array.
 376     @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.
 377     @param withTask The task each of the virtual ranges are mapped into.
 378     @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.
 379     @result true on success, false on failure. */
 380
 381     virtual bool initWithRanges(IOVirtualRange * ranges,
 382                                 UInt32           withCount,
 383                                 IODirection      withDirection,
 384                                 task_t           withTask,
 385                                 bool             asReference = false) = 0;
 386
 387 /*! @function initWithPhysicalRanges
 388     @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more physical ranges.
 389     @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.
 390     @param ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
 391     @param withCount The member count of the ranges array.
 392     @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.
 393     @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.
 394     @result true on success, false on failure. */
 395
 396     virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
 397                                         UInt32           withCount,
 398                                         IODirection      withDirection,
 399                                         bool             asReference = false) = 0;
 400
 401 /*! @function getDirection
 402     @abstract Accessor to get the direction the memory descriptor was created with.
 403     @discussion This method returns the direction the memory descriptor was created with.
 404     @result The direction. */
 405
 406     virtual IODirection getDirection() const;
 407
 408 /*! @function getLength
 409     @abstract Accessor to get the length of the memory descriptor (over all its ranges).
 410     @discussion This method returns the total length of the memory described by the descriptor, ie. the sum of its ranges' lengths.
 411     @result The byte count. */
 412
 413     virtual IOByteCount getLength() const;
 414
 415 /*! @function setTag
 416     @abstract Set the tag for the memory descriptor.
 417     @discussion This method sets the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
 418     @param tag The tag. */
 419
 420     virtual void setTag( IOOptionBits tag );
 421
 422 /*! @function getTag
 423     @abstract Accessor to the retrieve the tag for the memory descriptor.
 424     @discussion This method returns the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
 425     @result The tag. */
 426
 427     virtual IOOptionBits getTag( void );
 428
 429 /*! @function readBytes
 430     @abstract Copy data from the memory descriptor's buffer to the specified buffer.
 431     @discussion This method copies data from the memory descriptor's memory at the given offset, to the caller's buffer.
 432     @param offset A byte offset into the memory descriptor's memory.
 433     @param bytes The caller supplied buffer to copy the data to.
 434     @param withLength The length of the data to copy.
 435     @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */
 436
 437     virtual IOByteCount readBytes(IOByteCount offset,
 438                                 void * bytes, IOByteCount withLength);
 439
 440 /*! @function writeBytes
 441     @abstract Copy data to the memory descriptor's buffer from the specified buffer.
 442     @discussion This method copies data to the memory descriptor's memory at the given offset, from the caller's buffer.
 443     @param offset A byte offset into the memory descriptor's memory.
 444     @param bytes The caller supplied buffer to copy the data from.
 445     @param withLength The length of the data to copy.
 446     @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. */
 447
 448     virtual IOByteCount writeBytes(IOByteCount offset,
 449                                 const void * bytes, IOByteCount withLength);
 450
 451 /*! @function getPhysicalSegment
 452     @abstract Break a memory descriptor into its physically contiguous segments.
 453     @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.
 454     @param offset A byte offset into the memory whose physical address to return.
 455     @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
 456     @result A physical address, or zero if the offset is beyond the length of the memory. */
 457
 458     virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
 459                                                  IOByteCount * length) = 0;
 460
 461 /*! @function getPhysicalAddress
 462     @abstract Return the physical address of the first byte in the memory.
 463     @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.
 464     @result A physical address. */
 465
 466     /* inline */ IOPhysicalAddress getPhysicalAddress();
 467         /* { return( getPhysicalSegment( 0, 0 )); } */
 468
 469     /* DEPRECATED */ /* USE INSTEAD: map(), readBytes(), writeBytes() */
 470     /* DEPRECATED */ virtual void * getVirtualSegment(IOByteCount offset,
 471     /* DEPRECATED */                                    IOByteCount * length) = 0;
 472     /* DEPRECATED */ /* USE INSTEAD: map(), readBytes(), writeBytes() */
 473
 474 /*! @function prepare
 475     @abstract Prepare the memory for an I/O transfer.
 476     @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.
 477     @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
 478     @result An IOReturn code. */
 479
 480     virtual IOReturn prepare(IODirection forDirection = kIODirectionNone) = 0;
 481
 482 /*! @function complete
 483     @abstract Complete processing of the memory after an I/O transfer finishes.
 484     @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.
 485     @param forDirection DEPRECATED The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
 486     @result An IOReturn code. */
 487
 488     virtual IOReturn complete(IODirection forDirection = kIODirectionNone) = 0;
 489
 490     /*
 491      * Mapping functions.
 492      */
 493
 494 /*! @function map
 495     @abstract Maps a IOMemoryDescriptor into a task.
 496     @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.
 497     @param intoTask Sets the target task for the mapping. Pass kernel_task for the kernel address space.
 498     @param atAddress If a placed mapping is requested, atAddress specifies its address, and the kIOMapAnywhere should not be set. Otherwise, atAddress is ignored.
 499     @param options Mapping options are defined in IOTypes.h,<br>
 500         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>
 501         kIOMapDefaultCache to inhibit the cache in I/O areas, kIOMapCopybackCache in general purpose RAM.<br>
 502         kIOMapInhibitCache, kIOMapWriteThruCache, kIOMapCopybackCache to set the appropriate caching.<br>
 503         kIOMapReadOnly to allow only read only accesses to the memory - writes will cause and access fault.<br>
 504         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>
 505         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>
 506     @param offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
 507     @param length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
 508     @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. */
 509
 510     virtual IOMemoryMap *       map(
 511         task_t          intoTask,
 512         IOVirtualAddress        atAddress,
 513         IOOptionBits            options,
 514         IOByteCount             offset = 0,
 515         IOByteCount             length = 0 );
 516
 517 /*! @function map
 518     @abstract Maps a IOMemoryDescriptor into the kernel map.
 519     @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 map method for further details.
 520     @param options Mapping options as in the full version of the map method, with kIOMapAnywhere assumed.
 521     @result See the full version of the map method. */
 522
 523     virtual IOMemoryMap *       map(
 524         IOOptionBits            options = 0 );
 525
 526 /*! @function setMapping
 527     @abstract Establishes an already existing mapping.
 528     @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.
 529     @param task Address space in which the mapping exists.
 530     @param mapAddress Virtual address of the mapping.
 531     @param options Caching and read-only attributes of the mapping.
 532     @result A IOMemoryMap object created to represent the mapping. */
 533
 534     virtual IOMemoryMap *       setMapping(
 535         task_t          task,
 536         IOVirtualAddress        mapAddress,
 537         IOOptionBits            options = 0 );
 538
 539     // Following methods are private implementation
 540
 541     // make virtual
 542     IOReturn redirect( task_t safeTask, bool redirect );
 543
 544     IOReturn handleFault(
 545         void *                  pager,
 546         vm_map_t                addressMap,
 547         IOVirtualAddress        address,
 548         IOByteCount             sourceOffset,
 549         IOByteCount             length,
 550         IOOptionBits            options );
 551
 552 protected:
 553     virtual IOMemoryMap *       makeMapping(
 554         IOMemoryDescriptor *    owner,
 555         task_t          intoTask,
 556         IOVirtualAddress        atAddress,
 557         IOOptionBits            options,
 558         IOByteCount             offset,
 559         IOByteCount             length );
 560
 561     virtual void                addMapping(
 562         IOMemoryMap *           mapping );
 563
 564     virtual void                removeMapping(
 565         IOMemoryMap *           mapping );
 566
 567     virtual IOReturn doMap(
 568         vm_map_t                addressMap,
 569         IOVirtualAddress *      atAddress,
 570         IOOptionBits            options,
 571         IOByteCount             sourceOffset = 0,
 572         IOByteCount             length = 0 );
 573
 574     virtual IOReturn doUnmap(
 575         vm_map_t                addressMap,
 576         IOVirtualAddress        logical,
 577         IOByteCount             length );
 578 };
 579
 580 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 581
 582 /*! @class IOMemoryMap : public OSObject
 583     @abstract An abstract base class defining common methods for describing a memory mapping.
 584     @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. */
 585
 586 class IOMemoryMap : public OSObject
 587 {
 588     OSDeclareAbstractStructors(IOMemoryMap)
 589
 590 public:
 591 /*! @function getVirtualAddress
 592     @abstract Accessor to the virtual address of the first byte in the mapping.
 593     @discussion This method returns the virtual address of the first byte in the mapping.
 594     @result A virtual address. */
 595
 596     virtual IOVirtualAddress    getVirtualAddress() = 0;
 597
 598 /*! @function getPhysicalSegment
 599     @abstract Break a mapping into its physically contiguous segments.
 600     @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.
 601     @param offset A byte offset into the mapping whose physical address to return.
 602     @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
 603     @result A physical address, or zero if the offset is beyond the length of the mapping. */
 604
 605     virtual IOPhysicalAddress   getPhysicalSegment(IOByteCount offset,
 606                                                    IOByteCount * length) = 0;
 607
 608 /*! @function getPhysicalAddress
 609     @abstract Return the physical address of the first byte in the mapping.
 610     @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.
 611     @result A physical address. */
 612
 613     /* inline */ IOPhysicalAddress getPhysicalAddress();
 614         /* { return( getPhysicalSegment( 0, 0 )); } */
 615
 616 /*! @function getLength
 617     @abstract Accessor to the length of the mapping.
 618     @discussion This method returns the length of the mapping.
 619     @result A byte count. */
 620
 621     virtual IOByteCount         getLength() = 0;
 622
 623 /*! @function getAddressTask
 624     @abstract Accessor to the task of the mapping.
 625     @discussion This method returns the mach task the mapping exists in.
 626     @result A mach task_t. */
 627
 628     virtual task_t              getAddressTask() = 0;
 629
 630 /*! @function getMemoryDescriptor
 631     @abstract Accessor to the IOMemoryDescriptor the mapping was created from.
 632     @discussion This method returns the IOMemoryDescriptor the mapping was created from.
 633     @result An IOMemoryDescriptor reference, which is valid while the IOMemoryMap object is retained. It should not be released by the caller. */
 634
 635     virtual IOMemoryDescriptor * getMemoryDescriptor() = 0;
 636
 637 /*! @function getMapOptions
 638     @abstract Accessor to the options the mapping was created with.
 639     @discussion This method returns the options to IOMemoryDescriptor::map the mapping was created with.
 640     @result Options for the mapping, including cache settings. */
 641
 642     virtual IOOptionBits        getMapOptions() = 0;
 643
 644 /*! @function unmap
 645     @abstract Force the IOMemoryMap to unmap, without destroying the object.
 646     @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.
 647     @result An IOReturn code. */
 648
 649     virtual IOReturn            unmap() = 0;
 650
 651     virtual void                taskDied() = 0;
 652
 653 /*! @function redirect
 654     @abstract Replace the memory mapped in a process with new backing memory.
 655     @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.
 656     @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.
 657     @param options Mapping options are defined in IOTypes.h, and are documented in IOMemoryDescriptor::map()
 658     @param offset As with IOMemoryDescriptor::map(), a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default.
 659     @result An IOReturn code. */
 660
 661     virtual IOReturn            redirect(IOMemoryDescriptor * newBackingMemory,
 662                                          IOOptionBits         options,
 663                                          IOByteCount          offset = 0) = 0;
 664 };
 665
 666 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 667
 668 // The following classes are private implementation of IOMemoryDescriptor - they
 669 // should not be referenced directly, just through the public API's in the
 670 // IOMemoryDescriptor class. For example, an IOGeneralMemoryDescriptor instance
 671 // might be created by IOMemoryDescriptor::withAddress(), but there should be
 672 // no need to reference as anything but a generic IOMemoryDescriptor *.
 673
 674 // Also these flags should not overlap with the options to
 675 //      IOMemoryDescriptor::initWithRanges(... IOOptionsBits options);
 676
 677 enum {
 678     kIOMemoryPreparedReadOnly   = 0x00008000,
 679 };
 680
 681 class IOGeneralMemoryDescriptor : public IOMemoryDescriptor
 682 {
 683     OSDeclareDefaultStructors(IOGeneralMemoryDescriptor);
 684
 685 public:
 686     union Ranges {
 687         IOVirtualRange *  v;
 688         IOPhysicalRange * p;
 689         void             *uio;
 690     };
 691 protected:
 692     Ranges              _ranges;
 693     unsigned            _rangesCount;       /* number of address ranges in list */
 694     bool                _rangesIsAllocated; /* is list allocated by us? */
 695
 696     task_t              _task;               /* task where all ranges are mapped to */
 697
 698     union {
 699         IOVirtualRange  v;
 700         IOPhysicalRange p;
 701     }                   _singleRange;      /* storage space for a single range */
 702
 703     unsigned            _wireCount;        /* number of outstanding wires */
 704
 705     /* DEPRECATED */ vm_address_t _cachedVirtualAddress;  /* a cached virtual-to-physical */
 706
 707     /* DEPRECATED */ IOPhysicalAddress  _cachedPhysicalAddress;
 708
 709     bool                _initialized;      /* has superclass been initialized? */
 710
 711     virtual void free();
 712
 713
 714 private:
 715     // Internal APIs may be made virtual at some time in the future.
 716     IOReturn wireVirtual(IODirection forDirection);
 717     void *createNamedEntry();
 718
 719
 720     /* DEPRECATED */ IOByteCount _position; /* absolute position over all ranges */
 721     /* DEPRECATED */ virtual void setPosition(IOByteCount position);
 722
 723 /*
 724  * DEPRECATED IOByteCount _positionAtIndex; // relative position within range #n
 725  *
 726  * Re-use the _positionAtIndex as a count of the number of pages in
 727  * this memory descriptor.  Convieniently vm_address_t is an unsigned integer
 728  * type so I can get away without having to change the type.
 729  */
 730     unsigned int                _pages;
 731
 732 /* DEPRECATED */ unsigned    _positionAtOffset;  //range #n in which position is now
 733
 734     OSData *_memoryEntries;
 735
 736     /* DEPRECATED */ vm_offset_t _kernPtrAligned;
 737     /* DEPRECATED */ unsigned    _kernPtrAtIndex;
 738     /* DEPRECATED */ IOByteCount  _kernSize;
 739
 740     /* DEPRECATED */ virtual void mapIntoKernel(unsigned rangeIndex);
 741     /* DEPRECATED */ virtual void unmapFromKernel();
 742
 743 public:
 744     /*
 745      * IOMemoryDescriptor required methods
 746      */
 747
 748     // Master initaliser
 749     virtual bool initWithOptions(void *         buffers,
 750                                  UInt32         count,
 751                                  UInt32         offset,
 752                                  task_t         task,
 753                                  IOOptionBits   options,
 754                                  IOMapper *     mapper = 0);
 755
 756     // Secondary initialisers
 757     virtual bool initWithAddress(void *         address,
 758                                  IOByteCount    withLength,
 759                                  IODirection    withDirection);
 760
 761     virtual bool initWithAddress(vm_address_t   address,
 762                                  IOByteCount    withLength,
 763                                  IODirection    withDirection,
 764                                  task_t         withTask);
 765
 766     virtual bool initWithPhysicalAddress(
 767                                  IOPhysicalAddress      address,
 768                                  IOByteCount            withLength,
 769                                  IODirection            withDirection );
 770
 771     virtual bool initWithRanges(        IOVirtualRange * ranges,
 772                                         UInt32           withCount,
 773                                         IODirection      withDirection,
 774                                         task_t           withTask,
 775                                         bool             asReference = false);
 776
 777     virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
 778                                         UInt32           withCount,
 779                                         IODirection      withDirection,
 780                                         bool             asReference = false);
 781
 782     virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
 783                                                  IOByteCount * length);
 784
 785     virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
 786                                                IOByteCount * length);
 787
 788     /* DEPRECATED */ virtual void * getVirtualSegment(IOByteCount offset,
 789     /* DEPRECATED */                                    IOByteCount * length);
 790
 791     virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);
 792
 793     virtual IOReturn complete(IODirection forDirection = kIODirectionNone);
 794
 795     virtual IOReturn doMap(
 796         vm_map_t                addressMap,
 797         IOVirtualAddress *      atAddress,
 798         IOOptionBits            options,
 799         IOByteCount             sourceOffset = 0,
 800         IOByteCount             length = 0 );
 801
 802     virtual IOReturn doUnmap(
 803         vm_map_t                addressMap,
 804         IOVirtualAddress        logical,
 805         IOByteCount             length );
 806     virtual bool serialize(OSSerialize *s) const;
 807
 808     // Factory method for cloning a persistent IOMD, see IOMemoryDescriptor
 809     static IOMemoryDescriptor *
 810         withPersistentMemoryDescriptor(IOGeneralMemoryDescriptor *originalMD);
 811 };
 812
 813 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 814
 815 class IOSubMemoryDescriptor : public IOMemoryDescriptor
 816 {
 817     friend class IOMemoryDescriptor;
 818
 819     OSDeclareDefaultStructors(IOSubMemoryDescriptor);
 820
 821 protected:
 822     IOMemoryDescriptor * _parent;
 823     IOByteCount          _start;
 824
 825     virtual void free();
 826
 827     virtual bool initWithAddress(void *       address,
 828                                  IOByteCount    withLength,
 829                                  IODirection  withDirection);
 830
 831     virtual bool initWithAddress(vm_address_t address,
 832                                  IOByteCount    withLength,
 833                                  IODirection  withDirection,
 834                                  task_t       withTask);
 835
 836     virtual bool initWithPhysicalAddress(
 837                                  IOPhysicalAddress      address,
 838                                  IOByteCount            withLength,
 839                                  IODirection            withDirection );
 840
 841     virtual bool initWithRanges(        IOVirtualRange * ranges,
 842                                         UInt32           withCount,
 843                                         IODirection      withDirection,
 844                                         task_t           withTask,
 845                                         bool             asReference = false);
 846
 847     virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
 848                                         UInt32           withCount,
 849                                         IODirection      withDirection,
 850                                         bool             asReference = false);
 851
 852     IOMemoryDescriptor::withAddress;
 853     IOMemoryDescriptor::withPhysicalAddress;
 854     IOMemoryDescriptor::withPhysicalRanges;
 855     IOMemoryDescriptor::withRanges;
 856     IOMemoryDescriptor::withSubRange;
 857
 858 public:
 859     /*
 860      * Initialize or reinitialize an IOSubMemoryDescriptor to describe
 861      * a subrange of an existing descriptor.
 862      *
 863      * An IOSubMemoryDescriptor can be re-used by calling initSubRange
 864      * again on an existing instance -- note that this behavior is not
 865      * commonly supported in other IOKit classes, although it is here.
 866      */
 867     virtual bool initSubRange( IOMemoryDescriptor * parent,
 868                                 IOByteCount offset, IOByteCount length,
 869                                 IODirection withDirection );
 870
 871     /*
 872      * IOMemoryDescriptor required methods
 873      */
 874
 875     virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
 876                                                  IOByteCount * length);
 877
 878     virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
 879                                                IOByteCount * length);
 880
 881     virtual IOByteCount readBytes(IOByteCount offset,
 882                                 void * bytes, IOByteCount withLength);
 883
 884     virtual IOByteCount writeBytes(IOByteCount offset,
 885                                 const void * bytes, IOByteCount withLength);
 886
 887     virtual void * getVirtualSegment(IOByteCount offset,
 888                                         IOByteCount * length);
 889
 890     virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);
 891
 892     virtual IOReturn complete(IODirection forDirection = kIODirectionNone);
 893
 894     // make virtual
 895     IOReturn redirect( task_t safeTask, bool redirect );
 896
 897     virtual bool serialize(OSSerialize *s) const;
 898
 899     virtual IOReturn setPurgeable( IOOptionBits newState,
 900                                     IOOptionBits * oldState );
 901     virtual IOReturn performOperation( IOOptionBits options,
 902                                         IOByteCount offset, IOByteCount length );
 903
 904 protected:
 905     virtual IOMemoryMap *       makeMapping(
 906         IOMemoryDescriptor *    owner,
 907         task_t          intoTask,
 908         IOVirtualAddress        atAddress,
 909         IOOptionBits            options,
 910         IOByteCount             offset,
 911         IOByteCount             length );
 912
 913     virtual IOReturn doMap(
 914         vm_map_t                addressMap,
 915         IOVirtualAddress *      atAddress,
 916         IOOptionBits            options,
 917         IOByteCount             sourceOffset = 0,
 918         IOByteCount             length = 0 );
 919 };
 920
 921 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 922
 923 #endif /* !_IOMEMORYDESCRIPTOR_H */