iokit/IOKit/IOMemoryDescriptor.h

   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 #ifdef XNU_KERNEL_PRIVATE
  37 #include <IOKit/IOKitDebug.h>
  38 #endif
  39
  40 #include <mach/memory_object_types.h>
  41
  42 class IOMemoryMap;
  43 class IOMapper;
  44 class IOService;
  45 class IODMACommand;
  46
  47 /*
  48  * Direction of transfer, with respect to the described memory.
  49  */
  50 #ifdef __LP64__
  51 enum
  52 #else /* !__LP64__ */
  53 enum IODirection
  54 #endif /* !__LP64__ */
  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     // these flags are valid for the prepare() method only
  63     kIODirectionPrepareToPhys32   = 0x00000004,
  64     kIODirectionPrepareNoFault    = 0x00000008,
  65     kIODirectionPrepareReserved1  = 0x00000010,
  66 #define IODIRECTIONPREPARENONCOHERENTDEFINED    1
  67     kIODirectionPrepareNonCoherent = 0x00000020,
  68
  69      // these flags are valid for the complete() method only
  70 #define IODIRECTIONCOMPLETEWITHERRORDEFINED             1
  71      kIODirectionCompleteWithError = 0x00000040,
  72 #define IODIRECTIONCOMPLETEWITHDATAVALIDDEFINED 1
  73      kIODirectionCompleteWithDataValid = 0x00000080,
  74 };
  75 #ifdef __LP64__
  76 typedef IOOptionBits IODirection;
  77 #endif /* __LP64__ */
  78
  79 /*
  80  * IOOptionBits used in the withOptions variant
  81  */
  82 enum {
  83     kIOMemoryDirectionMask      = 0x00000007,
  84 #ifdef XNU_KERNEL_PRIVATE
  85     kIOMemoryAutoPrepare        = 0x00000008,   // Shared with Buffer MD
  86 #endif
  87
  88     kIOMemoryTypeVirtual        = 0x00000010,
  89     kIOMemoryTypePhysical       = 0x00000020,
  90     kIOMemoryTypeUPL            = 0x00000030,
  91     kIOMemoryTypePersistentMD   = 0x00000040,   // Persistent Memory Descriptor
  92     kIOMemoryTypeUIO            = 0x00000050,
  93 #ifdef __LP64__
  94     kIOMemoryTypeVirtual64      = kIOMemoryTypeVirtual,
  95     kIOMemoryTypePhysical64     = kIOMemoryTypePhysical,
  96 #else /* !__LP64__ */
  97     kIOMemoryTypeVirtual64      = 0x00000060,
  98     kIOMemoryTypePhysical64     = 0x00000070,
  99 #endif /* !__LP64__ */
 100     kIOMemoryTypeMask           = 0x000000f0,
 101
 102     kIOMemoryAsReference        = 0x00000100,
 103     kIOMemoryBufferPageable     = 0x00000400,
 104     kIOMemoryMapperNone         = 0x00000800,   // Shared with Buffer MD
 105     kIOMemoryHostOnly           = 0x00001000,   // Never DMA accessible
 106 #ifdef XNU_KERNEL_PRIVATE
 107     kIOMemoryRedirected         = 0x00004000,
 108     kIOMemoryPreparedReadOnly   = 0x00008000,
 109 #endif
 110     kIOMemoryPersistent         = 0x00010000,
 111 #ifdef XNU_KERNEL_PRIVATE
 112     kIOMemoryReserved6156215    = 0x00020000,
 113 #endif
 114     kIOMemoryThreadSafe         = 0x00100000,   // Shared with Buffer MD
 115     kIOMemoryClearEncrypt       = 0x00200000,   // Shared with Buffer MD
 116
 117 #ifdef XNU_KERNEL_PRIVATE
 118     kIOMemoryBufferPurgeable    = 0x00400000,
 119     kIOMemoryBufferCacheMask    = 0x70000000,
 120     kIOMemoryBufferCacheShift   = 28,
 121 #endif
 122 };
 123
 124 #define kIOMapperSystem ((IOMapper *) 0)
 125
 126 enum
 127 {
 128     kIOMemoryPurgeableKeepCurrent = 1,
 129
 130     kIOMemoryPurgeableNonVolatile = 2,
 131     kIOMemoryPurgeableVolatile    = 3,
 132     kIOMemoryPurgeableEmpty       = 4,
 133
 134     // modifiers for kIOMemoryPurgeableVolatile behavior
 135     kIOMemoryPurgeableVolatileGroup0           = VM_VOLATILE_GROUP_0,
 136     kIOMemoryPurgeableVolatileGroup1           = VM_VOLATILE_GROUP_1,
 137     kIOMemoryPurgeableVolatileGroup2           = VM_VOLATILE_GROUP_2,
 138     kIOMemoryPurgeableVolatileGroup3           = VM_VOLATILE_GROUP_3,
 139     kIOMemoryPurgeableVolatileGroup4           = VM_VOLATILE_GROUP_4,
 140     kIOMemoryPurgeableVolatileGroup5           = VM_VOLATILE_GROUP_5,
 141     kIOMemoryPurgeableVolatileGroup6           = VM_VOLATILE_GROUP_6,
 142     kIOMemoryPurgeableVolatileGroup7           = VM_VOLATILE_GROUP_7,
 143     kIOMemoryPurgeableVolatileBehaviorFifo     = VM_PURGABLE_BEHAVIOR_FIFO,
 144     kIOMemoryPurgeableVolatileBehaviorLifo     = VM_PURGABLE_BEHAVIOR_LIFO,
 145     kIOMemoryPurgeableVolatileOrderingObsolete = VM_PURGABLE_ORDERING_OBSOLETE,
 146     kIOMemoryPurgeableVolatileOrderingNormal   = VM_PURGABLE_ORDERING_NORMAL,
 147 };
 148 enum
 149 {
 150     kIOMemoryIncoherentIOFlush   = 1,
 151     kIOMemoryIncoherentIOStore   = 2,
 152
 153     kIOMemoryClearEncrypted      = 50,
 154     kIOMemorySetEncrypted        = 51,
 155 };
 156
 157 #define IOMEMORYDESCRIPTOR_SUPPORTS_DMACOMMAND  1
 158
 159 struct IODMAMapSpecification
 160 {
 161         uint64_t    alignment;
 162         IOService * device;
 163         uint32_t    options;
 164         uint8_t     numAddressBits;
 165         uint8_t     resvA[3];
 166         uint32_t    resvB[4];
 167 };
 168
 169 struct IODMAMapPageList
 170 {
 171     uint32_t                pageOffset;
 172     uint32_t                pageListCount;
 173     const upl_page_info_t * pageList;
 174 };
 175
 176 // mapOptions for iovmMapMemory
 177 enum
 178 {
 179     kIODMAMapReadAccess           = 0x00000001,
 180     kIODMAMapWriteAccess          = 0x00000002,
 181     kIODMAMapPhysicallyContiguous = 0x00000010,
 182     kIODMAMapDeviceMemory         = 0x00000020,
 183     kIODMAMapPagingPath           = 0x00000040,
 184     kIODMAMapIdentityMap          = 0x00000080,
 185
 186     kIODMAMapPageListFullyOccupied = 0x00000100,
 187     kIODMAMapFixedAddress          = 0x00000200,
 188 };
 189
 190 #ifdef KERNEL_PRIVATE
 191
 192 // Used for dmaCommandOperation communications for IODMACommand and mappers
 193
 194 enum  {
 195     kIOMDWalkSegments             = 0x01000000,
 196     kIOMDFirstSegment             = 1 | kIOMDWalkSegments,
 197     kIOMDGetCharacteristics       = 0x02000000,
 198     kIOMDGetCharacteristicsMapped = 1 | kIOMDGetCharacteristics,
 199     kIOMDDMAActive                = 0x03000000,
 200     kIOMDSetDMAActive             = 1 | kIOMDDMAActive,
 201     kIOMDSetDMAInactive           = kIOMDDMAActive,
 202     kIOMDAddDMAMapSpec            = 0x04000000,
 203     kIOMDDMAMap                   = 0x05000000,
 204     kIOMDDMACommandOperationMask  = 0xFF000000,
 205 };
 206 struct IOMDDMACharacteristics {
 207     UInt64 fLength;
 208     UInt32 fSGCount;
 209     UInt32 fPages;
 210     UInt32 fPageAlign;
 211     ppnum_t fHighestPage;
 212     IODirection fDirection;
 213     UInt8 fIsPrepared;
 214 };
 215
 216 struct IOMDDMAMapArgs {
 217     IOMapper            * fMapper;
 218     IODMACommand        * fCommand;
 219     IODMAMapSpecification fMapSpec;
 220     uint64_t              fOffset;
 221     uint64_t              fLength;
 222     uint64_t              fAlloc;
 223     uint64_t              fAllocLength;
 224     uint8_t               fMapContig;
 225 };
 226
 227 struct IOMDDMAWalkSegmentArgs {
 228     UInt64 fOffset;                     // Input/Output offset
 229     UInt64 fIOVMAddr, fLength;          // Output variables
 230     UInt8 fMapped;                      // Input Variable, Require mapped IOVMA
 231 };
 232 typedef UInt8 IOMDDMAWalkSegmentState[128];
 233
 234 #endif /* KERNEL_PRIVATE */
 235
 236 enum
 237 {
 238     kIOPreparationIDUnprepared = 0,
 239     kIOPreparationIDUnsupported = 1,
 240     kIOPreparationIDAlwaysPrepared = 2,
 241 };
 242
 243 #ifdef XNU_KERNEL_PRIVATE
 244 struct IOMemoryReference;
 245 #endif
 246
 247
 248 /*! @class IOMemoryDescriptor : public OSObject
 249     @abstract An abstract base class defining common methods for describing physical or virtual memory.
 250     @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. */
 251
 252 class IOMemoryDescriptor : public OSObject
 253 {
 254     friend class IOMemoryMap;
 255     friend class IOMultiMemoryDescriptor;
 256
 257     OSDeclareDefaultStructors(IOMemoryDescriptor);
 258
 259 protected:
 260
 261 /*! @var reserved
 262     Reserved for future use.  (Internal use only)  */
 263     struct IOMemoryDescriptorReserved * reserved;
 264
 265 protected:
 266     OSSet *             _mappings;
 267     IOOptionBits        _flags;
 268
 269
 270 #ifdef XNU_KERNEL_PRIVATE
 271 public:
 272     struct IOMemoryReference *  _memRef;
 273 protected:
 274 #else
 275     void * __iomd_reserved5;
 276 #endif
 277
 278 #ifdef __LP64__
 279     uint64_t            __iomd_reserved1;
 280     uint64_t            __iomd_reserved2;
 281     uint64_t            __iomd_reserved3;
 282     uint64_t            __iomd_reserved4;
 283 #else /* !__LP64__ */
 284     IODirection         _direction;        /* use _flags instead */
 285 #endif /* !__LP64__ */
 286     IOByteCount         _length;           /* length of all ranges */
 287     IOOptionBits        _tag;
 288
 289 public:
 290 typedef IOOptionBits DMACommandOps;
 291 #ifndef __LP64__
 292     virtual IOPhysicalAddress getSourceSegment( IOByteCount offset,
 293                                                 IOByteCount * length ) APPLE_KEXT_DEPRECATED;
 294 #endif /* !__LP64__ */
 295
 296 /*! @function initWithOptions
 297     @abstract Master initialiser for all variants of memory descriptors.  For a more complete description see IOMemoryDescriptor::withOptions.
 298     @discussion Note this function can be used to re-init a previously created memory descriptor.
 299     @result true on success, false on failure. */
 300     virtual bool initWithOptions(void *         buffers,
 301                                  UInt32         count,
 302                                  UInt32         offset,
 303                                  task_t         task,
 304                                  IOOptionBits   options,
 305                                  IOMapper *     mapper = kIOMapperSystem);
 306
 307 #ifndef __LP64__
 308     virtual addr64_t getPhysicalSegment64( IOByteCount offset,
 309                                             IOByteCount * length ) APPLE_KEXT_DEPRECATED; /* use getPhysicalSegment() and kIOMemoryMapperNone instead */
 310 #endif /* !__LP64__ */
 311
 312 /*! @function setPurgeable
 313     @abstract Control the purgeable status of a memory descriptors memory.
 314     @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.
 315     @param newState - the desired new purgeable state of the memory:<br>
 316     kIOMemoryPurgeableKeepCurrent - make no changes to the memory's purgeable state.<br>
 317     kIOMemoryPurgeableVolatile    - make the memory volatile - the memory may be reclaimed by the VM system without saving its contents to backing store.<br>
 318     kIOMemoryPurgeableNonVolatile - make the memory nonvolatile - the memory is treated as with usual allocations and must be saved to backing store if paged.<br>
 319     kIOMemoryPurgeableEmpty       - make the memory volatile, and discard any pages allocated to it.
 320     @param oldState - if non-NULL, the previous purgeable state of the memory is returned here:<br>
 321     kIOMemoryPurgeableNonVolatile - the memory was nonvolatile.<br>
 322     kIOMemoryPurgeableVolatile    - the memory was volatile but its content has not been discarded by the VM system.<br>
 323     kIOMemoryPurgeableEmpty       - the memory was volatile and has been discarded by the VM system.<br>
 324     @result An IOReturn code. */
 325
 326     virtual IOReturn setPurgeable( IOOptionBits newState,
 327                                     IOOptionBits * oldState );
 328
 329
 330 /*! @function getPageCounts
 331     @abstract Retrieve the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.
 332     @discussion This method returns the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.
 333     @param residentPageCount - If non-null, a pointer to a byte count that will return the number of resident pages encompassed by this IOMemoryDescriptor.
 334     @param dirtyPageCount - If non-null, a pointer to a byte count that will return the number of dirty pages encompassed by this IOMemoryDescriptor.
 335     @result An IOReturn code. */
 336
 337     IOReturn getPageCounts( IOByteCount * residentPageCount,
 338                             IOByteCount * dirtyPageCount);
 339
 340 /*! @function performOperation
 341     @abstract Perform an operation on the memory descriptor's memory.
 342     @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.
 343     @param options The operation to perform on the memory:<br>
 344     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>
 345     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.
 346     @param offset A byte offset into the memory descriptor's memory.
 347     @param length The length of the data range.
 348     @result An IOReturn code. */
 349
 350     virtual IOReturn performOperation( IOOptionBits options,
 351                                         IOByteCount offset, IOByteCount length );
 352
 353     // Used for dedicated communications for IODMACommand
 354     virtual IOReturn dmaCommandOperation(DMACommandOps op, void *vData, UInt dataSize) const;
 355
 356 /*! @function getPhysicalSegment
 357     @abstract Break a memory descriptor into its physically contiguous segments.
 358     @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.
 359     @param offset A byte offset into the memory whose physical address to return.
 360     @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
 361     @result A physical address, or zero if the offset is beyond the length of the memory. */
 362
 363 #ifdef __LP64__
 364     virtual addr64_t getPhysicalSegment( IOByteCount   offset,
 365                                          IOByteCount * length,
 366                                          IOOptionBits  options = 0 ) = 0;
 367 #else /* !__LP64__ */
 368     virtual addr64_t getPhysicalSegment( IOByteCount   offset,
 369                                          IOByteCount * length,
 370                                          IOOptionBits  options );
 371 #endif /* !__LP64__ */
 372
 373     virtual uint64_t getPreparationID( void );
 374     void             setPreparationID( void );
 375
 376 #ifdef XNU_KERNEL_PRIVATE
 377     IOMemoryDescriptorReserved * getKernelReserved( void );
 378     IOReturn dmaMap(
 379         IOMapper                    * mapper,
 380         IODMACommand                * command,
 381         const IODMAMapSpecification * mapSpec,
 382         uint64_t                      offset,
 383         uint64_t                      length,
 384         uint64_t                    * mapAddress,
 385         uint64_t                    * mapLength);
 386 #endif
 387
 388 private:
 389     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 0);
 390 #ifdef __LP64__
 391     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 1);
 392     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 2);
 393     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 3);
 394     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 4);
 395     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 5);
 396     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 6);
 397     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 7);
 398 #else /* !__LP64__ */
 399     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 1);
 400     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 2);
 401     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 3);
 402     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 4);
 403     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 5);
 404     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 6);
 405     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 7);
 406 #endif /* !__LP64__ */
 407     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 8);
 408     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 9);
 409     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 10);
 410     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 11);
 411     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 12);
 412     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 13);
 413     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 14);
 414     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 15);
 415
 416 protected:
 417     virtual void free() APPLE_KEXT_OVERRIDE;
 418 public:
 419     static void initialize( void );
 420
 421 public:
 422 /*! @function withAddress
 423     @abstract Create an IOMemoryDescriptor to describe one virtual range of the kernel task.
 424     @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map.  This memory descriptor needs to be prepared before it can be used to extract data from the memory described.
 425     @param address The virtual address of the first byte in the memory.
 426     @param withLength The length of memory.
 427     @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.
 428     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 429
 430     static IOMemoryDescriptor * withAddress(void *       address,
 431                                             IOByteCount  withLength,
 432                                             IODirection  withDirection);
 433
 434 #ifndef __LP64__
 435     static IOMemoryDescriptor * withAddress(IOVirtualAddress address,
 436                                             IOByteCount  withLength,
 437                                             IODirection  withDirection,
 438                                             task_t       withTask) APPLE_KEXT_DEPRECATED; /* use withAddressRange() and prepare() instead */
 439 #endif /* !__LP64__ */
 440
 441 /*! @function withPhysicalAddress
 442     @abstract Create an IOMemoryDescriptor to describe one physical range.
 443     @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.
 444     @param address The physical address of the first byte in the memory.
 445     @param withLength The length of memory.
 446     @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.
 447     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 448
 449     static IOMemoryDescriptor * withPhysicalAddress(
 450                                 IOPhysicalAddress       address,
 451                                 IOByteCount             withLength,
 452                                 IODirection             withDirection );
 453
 454 #ifndef __LP64__
 455      static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges,
 456                                             UInt32           withCount,
 457                                             IODirection      withDirection,
 458                                             task_t           withTask,
 459                                             bool             asReference = false) APPLE_KEXT_DEPRECATED; /* use withAddressRanges() instead */
 460 #endif /* !__LP64__ */
 461
 462 /*! @function withAddressRange
 463     @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
 464     @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map.  This memory descriptor needs to be prepared before it can be used to extract data from the memory described.
 465     @param address The virtual address of the first byte in the memory.
 466     @param withLength The length of memory.
 467     @param options
 468         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.
 469     @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. The task argument may be NULL to specify memory by physical address.
 470     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 471
 472     static IOMemoryDescriptor * withAddressRange(
 473                                         mach_vm_address_t address,
 474                                         mach_vm_size_t    length,
 475                                         IOOptionBits      options,
 476                                         task_t            task);
 477
 478 /*! @function withAddressRanges
 479     @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
 480     @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.  This memory descriptor needs to be prepared before it can be used to extract data from the memory described.
 481     @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.
 482     @param rangeCount The member count of the ranges array.
 483     @param options
 484         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.
 485         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.
 486     @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. The task argument may be NULL to specify memory by physical address.
 487     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 488
 489     static IOMemoryDescriptor * withAddressRanges(
 490                                         IOAddressRange * ranges,
 491                                         UInt32           rangeCount,
 492                                         IOOptionBits     options,
 493                                         task_t           task);
 494
 495 /*! @function withOptions
 496     @abstract Master initialiser for all variants of memory descriptors.
 497     @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.
 498
 499
 500     @param buffers A pointer to an array of IOAddressRange when options:type is kIOMemoryTypeVirtual64 or kIOMemoryTypePhysical64 or a 64bit kernel. For type UPL it is a upl_t returned by the mach/memory_object_types.h apis, primarily used internally by the UBC. IOVirtualRanges or IOPhysicalRanges are 32 bit only types for use when options:type is kIOMemoryTypeVirtual or kIOMemoryTypePhysical on 32bit kernels.
 501
 502     @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.
 503
 504     @param offset Only used when options:type = UPL, in which case this field contains an offset for the memory within the buffers upl.
 505
 506     @param task Only used options:type = Virtual, The task each of the virtual ranges are mapped into.
 507
 508     @param options
 509         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.
 510         kIOMemoryTypeMask (options:type)        kIOMemoryTypeVirtual64, kIOMemoryTypeVirtual, kIOMemoryTypePhysical64, 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.
 511         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.
 512         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.
 513
 514     @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.
 515
 516     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
 517
 518     static IOMemoryDescriptor *withOptions(void *       buffers,
 519                                            UInt32       count,
 520                                            UInt32       offset,
 521                                            task_t       task,
 522                                            IOOptionBits options,
 523                                            IOMapper *   mapper = kIOMapperSystem);
 524
 525 #ifndef __LP64__
 526     static IOMemoryDescriptor * withPhysicalRanges(
 527                                             IOPhysicalRange *   ranges,
 528                                             UInt32              withCount,
 529                                             IODirection         withDirection,
 530                                             bool                asReference = false) APPLE_KEXT_DEPRECATED; /* use withOptions() and kIOMemoryTypePhysical instead */
 531 #endif /* !__LP64__ */
 532
 533 #ifndef __LP64__
 534     static IOMemoryDescriptor * withSubRange(IOMemoryDescriptor *of,
 535                                              IOByteCount offset,
 536                                              IOByteCount length,
 537                                              IODirection withDirection) APPLE_KEXT_DEPRECATED; /* use IOSubMemoryDescriptor::withSubRange() and kIOMemoryThreadSafe instead */
 538 #endif /* !__LP64__ */
 539
 540 /*! @function withPersistentMemoryDescriptor
 541     @abstract Copy constructor that generates a new memory descriptor if the backing memory for the same task's virtual address and length has changed.
 542     @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.
 543     @param originalMD The memory descriptor to be duplicated.
 544     @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. */
 545     static IOMemoryDescriptor *
 546         withPersistentMemoryDescriptor(IOMemoryDescriptor *originalMD);
 547
 548 #ifndef __LP64__
 549         // obsolete initializers
 550         // - initWithOptions is the designated initializer
 551     virtual bool initWithAddress(void *       address,
 552                                  IOByteCount  withLength,
 553                                  IODirection  withDirection) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
 554     virtual bool initWithAddress(IOVirtualAddress address,
 555                                  IOByteCount  withLength,
 556                                  IODirection  withDirection,
 557                                  task_t       withTask) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
 558     virtual bool initWithPhysicalAddress(
 559                                  IOPhysicalAddress      address,
 560                                  IOByteCount            withLength,
 561                                  IODirection            withDirection ) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
 562     virtual bool initWithRanges(IOVirtualRange * ranges,
 563                                 UInt32           withCount,
 564                                 IODirection      withDirection,
 565                                 task_t           withTask,
 566                                 bool             asReference = false) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
 567     virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
 568                                         UInt32           withCount,
 569                                         IODirection      withDirection,
 570                                         bool             asReference = false) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
 571 #endif /* __LP64__ */
 572
 573 /*! @function getDirection
 574     @abstract Accessor to get the direction the memory descriptor was created with.
 575     @discussion This method returns the direction the memory descriptor was created with.
 576     @result The direction. */
 577
 578     virtual IODirection getDirection() const;
 579
 580 /*! @function getLength
 581     @abstract Accessor to get the length of the memory descriptor (over all its ranges).
 582     @discussion This method returns the total length of the memory described by the descriptor, ie. the sum of its ranges' lengths.
 583     @result The byte count. */
 584
 585     virtual IOByteCount getLength() const;
 586
 587 /*! @function setTag
 588     @abstract Set the tag for the memory descriptor.
 589     @discussion This method sets the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
 590     @param tag The tag. */
 591
 592     virtual void setTag( IOOptionBits tag );
 593
 594 /*! @function getTag
 595     @abstract Accessor to the retrieve the tag for the memory descriptor.
 596     @discussion This method returns the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
 597     @result The tag. */
 598
 599     virtual IOOptionBits getTag( void );
 600
 601 /*! @function readBytes
 602     @abstract Copy data from the memory descriptor's buffer to the specified buffer.
 603     @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.
 604     @param offset A byte offset into the memory descriptor's memory.
 605     @param bytes The caller supplied buffer to copy the data to.
 606     @param withLength The length of the data to copy.
 607     @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. Development/debug kernel builds will assert if the offset is beyond the length of the descriptor. */
 608
 609     virtual IOByteCount readBytes(IOByteCount offset,
 610                                 void * bytes, IOByteCount withLength);
 611
 612 /*! @function writeBytes
 613     @abstract Copy data to the memory descriptor's buffer from the specified buffer.
 614     @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.
 615     @param offset A byte offset into the memory descriptor's memory.
 616     @param bytes The caller supplied buffer to copy the data from.
 617     @param withLength The length of the data to copy.
 618     @result The number of bytes copied, zero will be returned if the specified offset is beyond the length of the descriptor. Development/debug kernel builds will assert if the offset is beyond the length of the descriptor. */
 619
 620     virtual IOByteCount writeBytes(IOByteCount offset,
 621                                 const void * bytes, IOByteCount withLength);
 622
 623 #ifndef __LP64__
 624     virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
 625                                                  IOByteCount * length);
 626 #endif /* !__LP64__ */
 627
 628 /*! @function getPhysicalAddress
 629     @abstract Return the physical address of the first byte in the memory.
 630     @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.
 631     @result A physical address. */
 632
 633     IOPhysicalAddress getPhysicalAddress();
 634
 635 #ifndef __LP64__
 636     virtual void * getVirtualSegment(IOByteCount offset,
 637                                         IOByteCount * length) APPLE_KEXT_DEPRECATED; /* use map() and getVirtualAddress() instead */
 638 #endif /* !__LP64__ */
 639
 640 /*! @function prepare
 641     @abstract Prepare the memory for an I/O transfer.
 642     @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.
 643     @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
 644     @result An IOReturn code. */
 645
 646     virtual IOReturn prepare(IODirection forDirection = kIODirectionNone) = 0;
 647
 648 /*! @function complete
 649     @abstract Complete processing of the memory after an I/O transfer finishes.
 650     @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.
 651     @param forDirection DEPRECATED The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
 652     @result An IOReturn code. */
 653
 654     virtual IOReturn complete(IODirection forDirection = kIODirectionNone) = 0;
 655
 656     /*
 657      * Mapping functions.
 658      */
 659
 660 /*! @function createMappingInTask
 661     @abstract Maps a IOMemoryDescriptor into a task.
 662     @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.
 663     @param intoTask Sets the target task for the mapping. Pass kernel_task for the kernel address space.
 664     @param atAddress If a placed mapping is requested, atAddress specifies its address, and the kIOMapAnywhere should not be set. Otherwise, atAddress is ignored.
 665     @param options Mapping options are defined in IOTypes.h,<br>
 666         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>
 667         kIOMapDefaultCache to inhibit the cache in I/O areas, kIOMapCopybackCache in general purpose RAM.<br>
 668         kIOMapInhibitCache, kIOMapWriteThruCache, kIOMapCopybackCache to set the appropriate caching.<br>
 669         kIOMapReadOnly to allow only read only accesses to the memory - writes will cause and access fault.<br>
 670         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>
 671         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>
 672         kIOMapPrefault will try to prefault the pages corresponding to the mapping. This must not be done on the kernel task, and the memory must have been wired via prepare(). Otherwise, the function will fail.<br>
 673     @param offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
 674     @param length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
 675     @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. */
 676
 677     IOMemoryMap *       createMappingInTask(
 678         task_t                  intoTask,
 679         mach_vm_address_t       atAddress,
 680         IOOptionBits            options,
 681         mach_vm_size_t          offset = 0,
 682         mach_vm_size_t          length = 0 );
 683
 684 #ifndef __LP64__
 685     virtual IOMemoryMap *       map(
 686         task_t          intoTask,
 687         IOVirtualAddress        atAddress,
 688         IOOptionBits            options,
 689         IOByteCount             offset = 0,
 690         IOByteCount             length = 0 ) APPLE_KEXT_DEPRECATED; /* use createMappingInTask() instead */
 691 #endif /* !__LP64__ */
 692
 693 /*! @function map
 694     @abstract Maps a IOMemoryDescriptor into the kernel map.
 695     @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.
 696     @param options Mapping options as in the full version of the createMappingInTask method, with kIOMapAnywhere assumed.
 697     @result See the full version of the createMappingInTask method. */
 698
 699     virtual IOMemoryMap *       map(
 700         IOOptionBits            options = 0 );
 701
 702 /*! @function setMapping
 703     @abstract Establishes an already existing mapping.
 704     @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.
 705     @param task Address space in which the mapping exists.
 706     @param mapAddress Virtual address of the mapping.
 707     @param options Caching and read-only attributes of the mapping.
 708     @result A IOMemoryMap object created to represent the mapping. */
 709
 710     virtual IOMemoryMap *       setMapping(
 711         task_t          task,
 712         IOVirtualAddress        mapAddress,
 713         IOOptionBits            options = 0 );
 714
 715     // Following methods are private implementation
 716
 717 #ifdef __LP64__
 718     virtual
 719 #endif /* __LP64__ */
 720     IOReturn redirect( task_t safeTask, bool redirect );
 721
 722     IOReturn handleFault(
 723         void *                  _pager,
 724         mach_vm_size_t          sourceOffset,
 725         mach_vm_size_t          length);
 726
 727     IOReturn populateDevicePager(
 728         void *                  pager,
 729         vm_map_t                addressMap,
 730         mach_vm_address_t       address,
 731         mach_vm_size_t          sourceOffset,
 732         mach_vm_size_t          length,
 733         IOOptionBits            options );
 734
 735     virtual IOMemoryMap *       makeMapping(
 736         IOMemoryDescriptor *    owner,
 737         task_t                  intoTask,
 738         IOVirtualAddress        atAddress,
 739         IOOptionBits            options,
 740         IOByteCount             offset,
 741         IOByteCount             length );
 742
 743 protected:
 744     virtual void                addMapping(
 745         IOMemoryMap *           mapping );
 746
 747     virtual void                removeMapping(
 748         IOMemoryMap *           mapping );
 749
 750     virtual IOReturn doMap(
 751         vm_map_t                addressMap,
 752         IOVirtualAddress *      atAddress,
 753         IOOptionBits            options,
 754         IOByteCount             sourceOffset = 0,
 755         IOByteCount             length = 0 );
 756
 757     virtual IOReturn doUnmap(
 758         vm_map_t                addressMap,
 759         IOVirtualAddress        logical,
 760         IOByteCount             length );
 761 };
 762
 763 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 764
 765 /*! @class IOMemoryMap : public OSObject
 766     @abstract A class defining common methods for describing a memory mapping.
 767     @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. */
 768
 769 class IOMemoryMap : public OSObject
 770 {
 771     OSDeclareDefaultStructors(IOMemoryMap)
 772 #ifdef XNU_KERNEL_PRIVATE
 773 public:
 774     IOMemoryDescriptor * fMemory;
 775     IOMemoryMap *        fSuperMap;
 776     mach_vm_size_t       fOffset;
 777     mach_vm_address_t    fAddress;
 778     mach_vm_size_t       fLength;
 779     task_t               fAddressTask;
 780     vm_map_t             fAddressMap;
 781     IOOptionBits         fOptions;
 782     upl_t                fRedirUPL;
 783     ipc_port_t           fRedirEntry;
 784     IOMemoryDescriptor * fOwner;
 785     uint8_t              fUserClientUnmap;
 786 #if IOTRACKING
 787     IOTracking           fTracking;
 788 #endif
 789 #endif /* XNU_KERNEL_PRIVATE */
 790
 791 protected:
 792     virtual void taggedRelease(const void *tag = 0) const APPLE_KEXT_OVERRIDE;
 793     virtual void free() APPLE_KEXT_OVERRIDE;
 794
 795 public:
 796 /*! @function getVirtualAddress
 797     @abstract Accessor to the virtual address of the first byte in the mapping.
 798     @discussion This method returns the virtual address of the first byte in the mapping. Since the IOVirtualAddress is only 32bit in 32bit kernels, the getAddress() method should be used for compatibility with 64bit task mappings.
 799     @result A virtual address. */
 800
 801     virtual IOVirtualAddress    getVirtualAddress();
 802
 803 /*! @function getPhysicalSegment
 804     @abstract Break a mapping into its physically contiguous segments.
 805     @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.
 806     @param offset A byte offset into the mapping whose physical address to return.
 807     @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
 808     @result A physical address, or zero if the offset is beyond the length of the mapping. */
 809
 810 #ifdef __LP64__
 811     virtual IOPhysicalAddress   getPhysicalSegment(IOByteCount offset,
 812                                                    IOByteCount * length,
 813                                                    IOOptionBits  options = 0);
 814 #else /* !__LP64__ */
 815     virtual IOPhysicalAddress   getPhysicalSegment(IOByteCount offset,
 816                                                    IOByteCount * length);
 817 #endif /* !__LP64__ */
 818
 819 /*! @function getPhysicalAddress
 820     @abstract Return the physical address of the first byte in the mapping.
 821     @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.
 822     @result A physical address. */
 823
 824     IOPhysicalAddress getPhysicalAddress();
 825
 826 /*! @function getLength
 827     @abstract Accessor to the length of the mapping.
 828     @discussion This method returns the length of the mapping.
 829     @result A byte count. */
 830
 831     virtual IOByteCount         getLength();
 832
 833 /*! @function getAddressTask
 834     @abstract Accessor to the task of the mapping.
 835     @discussion This method returns the mach task the mapping exists in.
 836     @result A mach task_t. */
 837
 838     virtual task_t              getAddressTask();
 839
 840 /*! @function getMemoryDescriptor
 841     @abstract Accessor to the IOMemoryDescriptor the mapping was created from.
 842     @discussion This method returns the IOMemoryDescriptor the mapping was created from.
 843     @result An IOMemoryDescriptor reference, which is valid while the IOMemoryMap object is retained. It should not be released by the caller. */
 844
 845     virtual IOMemoryDescriptor * getMemoryDescriptor();
 846
 847 /*! @function getMapOptions
 848     @abstract Accessor to the options the mapping was created with.
 849     @discussion This method returns the options to IOMemoryDescriptor::map the mapping was created with.
 850     @result Options for the mapping, including cache settings. */
 851
 852     virtual IOOptionBits        getMapOptions();
 853
 854 /*! @function unmap
 855     @abstract Force the IOMemoryMap to unmap, without destroying the object.
 856     @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.
 857     @result An IOReturn code. */
 858
 859     virtual IOReturn            unmap();
 860
 861     virtual void                taskDied();
 862
 863 /*! @function redirect
 864     @abstract Replace the memory mapped in a process with new backing memory.
 865     @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.
 866     @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.
 867     @param options Mapping options are defined in IOTypes.h, and are documented in IOMemoryDescriptor::map()
 868     @param offset As with IOMemoryDescriptor::map(), a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default.
 869     @result An IOReturn code. */
 870
 871 #ifndef __LP64__
 872 // For 32 bit XNU, there is a 32 bit (IOByteCount) and a 64 bit (mach_vm_size_t) interface;
 873 // for 64 bit, these fall together on the 64 bit one.
 874     virtual IOReturn            redirect(IOMemoryDescriptor * newBackingMemory,
 875                                          IOOptionBits         options,
 876                                          IOByteCount          offset = 0);
 877 #endif
 878     virtual IOReturn            redirect(IOMemoryDescriptor * newBackingMemory,
 879                                          IOOptionBits         options,
 880                                          mach_vm_size_t       offset = 0);
 881
 882 #ifdef __LP64__
 883 /*! @function getAddress
 884     @abstract Accessor to the virtual address of the first byte in the mapping.
 885     @discussion This method returns the virtual address of the first byte in the mapping.
 886     @result A virtual address. */
 887 /*! @function getSize
 888     @abstract Accessor to the length of the mapping.
 889     @discussion This method returns the length of the mapping.
 890     @result A byte count. */
 891     inline mach_vm_address_t    getAddress() __attribute__((always_inline));
 892     inline mach_vm_size_t       getSize() __attribute__((always_inline));
 893 #else /* !__LP64__ */
 894 /*! @function getAddress
 895     @abstract Accessor to the virtual address of the first byte in the mapping.
 896     @discussion This method returns the virtual address of the first byte in the mapping.
 897     @result A virtual address. */
 898 /*! @function getSize
 899     @abstract Accessor to the length of the mapping.
 900     @discussion This method returns the length of the mapping.
 901     @result A byte count. */
 902     virtual mach_vm_address_t   getAddress();
 903     virtual mach_vm_size_t      getSize();
 904 #endif /* !__LP64__ */
 905
 906 #ifdef XNU_KERNEL_PRIVATE
 907     // for IOMemoryDescriptor use
 908     IOMemoryMap * copyCompatible( IOMemoryMap * newMapping );
 909
 910     bool init(
 911         task_t                  intoTask,
 912         mach_vm_address_t       toAddress,
 913         IOOptionBits            options,
 914         mach_vm_size_t          offset,
 915         mach_vm_size_t          length );
 916
 917     bool    setMemoryDescriptor(IOMemoryDescriptor * _memory, mach_vm_size_t _offset);
 918
 919     IOReturn redirect(
 920         task_t                  intoTask, bool redirect );
 921
 922     IOReturn userClientUnmap();
 923 #endif /* XNU_KERNEL_PRIVATE */
 924
 925     IOReturn wireRange(
 926         uint32_t                options,
 927         mach_vm_size_t          offset,
 928         mach_vm_size_t          length);
 929
 930     OSMetaClassDeclareReservedUnused(IOMemoryMap, 0);
 931     OSMetaClassDeclareReservedUnused(IOMemoryMap, 1);
 932     OSMetaClassDeclareReservedUnused(IOMemoryMap, 2);
 933     OSMetaClassDeclareReservedUnused(IOMemoryMap, 3);
 934     OSMetaClassDeclareReservedUnused(IOMemoryMap, 4);
 935     OSMetaClassDeclareReservedUnused(IOMemoryMap, 5);
 936     OSMetaClassDeclareReservedUnused(IOMemoryMap, 6);
 937     OSMetaClassDeclareReservedUnused(IOMemoryMap, 7);
 938 };
 939
 940 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 941 #ifdef XNU_KERNEL_PRIVATE
 942 // Also these flags should not overlap with the options to
 943 //      IOMemoryDescriptor::initWithRanges(... IOOptionsBits options);
 944 enum {
 945     _kIOMemorySourceSegment     = 0x00002000
 946 };
 947 #endif /* XNU_KERNEL_PRIVATE */
 948
 949 // The following classes are private implementation of IOMemoryDescriptor - they
 950 // should not be referenced directly, just through the public API's in the
 951 // IOMemoryDescriptor class. For example, an IOGeneralMemoryDescriptor instance
 952 // might be created by IOMemoryDescriptor::withAddressRange(), but there should be
 953 // no need to reference as anything but a generic IOMemoryDescriptor *.
 954
 955 class IOGeneralMemoryDescriptor : public IOMemoryDescriptor
 956 {
 957     OSDeclareDefaultStructors(IOGeneralMemoryDescriptor);
 958
 959 public:
 960     union Ranges {
 961         IOVirtualRange   *v;
 962         IOAddressRange   *v64;
 963         IOPhysicalRange  *p;
 964         void             *uio;
 965     };
 966 protected:
 967     Ranges              _ranges;
 968     unsigned            _rangesCount;       /* number of address ranges in list */
 969 #ifndef __LP64__
 970     bool                _rangesIsAllocated; /* is list allocated by us? */
 971 #endif /* !__LP64__ */
 972
 973     task_t              _task;               /* task where all ranges are mapped to */
 974
 975     union {
 976         IOVirtualRange  v;
 977         IOPhysicalRange p;
 978     }                   _singleRange;      /* storage space for a single range */
 979
 980     unsigned            _wireCount;        /* number of outstanding wires */
 981
 982 #ifndef __LP64__
 983     uintptr_t _cachedVirtualAddress;
 984
 985     IOPhysicalAddress   _cachedPhysicalAddress;
 986 #endif /* !__LP64__ */
 987
 988     bool                _initialized;      /* has superclass been initialized? */
 989
 990 public:
 991     virtual void free() APPLE_KEXT_OVERRIDE;
 992
 993     virtual IOReturn dmaCommandOperation(DMACommandOps op, void *vData, UInt dataSize) const APPLE_KEXT_OVERRIDE;
 994
 995     virtual uint64_t getPreparationID( void ) APPLE_KEXT_OVERRIDE;
 996
 997 #ifdef XNU_KERNEL_PRIVATE
 998     // Internal APIs may be made virtual at some time in the future.
 999     IOReturn wireVirtual(IODirection forDirection);
1000     IOReturn dmaMap(
1001         IOMapper                    * mapper,
1002         IODMACommand                * command,
1003         const IODMAMapSpecification * mapSpec,
1004         uint64_t                      offset,
1005         uint64_t                      length,
1006         uint64_t                    * mapAddress,
1007         uint64_t                    * mapLength);
1008     bool initMemoryEntries(size_t size, IOMapper * mapper);
1009
1010     IOMemoryReference * memoryReferenceAlloc(uint32_t capacity,
1011                                              IOMemoryReference * realloc);
1012     void memoryReferenceFree(IOMemoryReference * ref);
1013     void memoryReferenceRelease(IOMemoryReference * ref);
1014
1015     IOReturn memoryReferenceCreate(
1016                         IOOptionBits         options,
1017                         IOMemoryReference ** reference);
1018
1019     IOReturn memoryReferenceMap(IOMemoryReference * ref,
1020                          vm_map_t            map,
1021                          mach_vm_size_t      inoffset,
1022                          mach_vm_size_t      size,
1023                          IOOptionBits        options,
1024                          mach_vm_address_t * inaddr);
1025
1026     static IOReturn memoryReferenceSetPurgeable(
1027                                 IOMemoryReference * ref,
1028                                 IOOptionBits newState,
1029                                 IOOptionBits * oldState);
1030     static IOReturn memoryReferenceGetPageCounts(
1031                                IOMemoryReference * ref,
1032                                IOByteCount       * residentPageCount,
1033                                IOByteCount       * dirtyPageCount);
1034 #endif
1035
1036 private:
1037
1038 #ifndef __LP64__
1039     virtual void setPosition(IOByteCount position);
1040     virtual void mapIntoKernel(unsigned rangeIndex);
1041     virtual void unmapFromKernel();
1042 #endif /* !__LP64__ */
1043
1044     // Internal
1045     OSData *        _memoryEntries;
1046     unsigned int    _pages;
1047     ppnum_t         _highestPage;
1048     uint32_t        __iomd_reservedA;
1049     uint32_t        __iomd_reservedB;
1050
1051     IOLock *        _prepareLock;
1052
1053 public:
1054     /*
1055      * IOMemoryDescriptor required methods
1056      */
1057
1058     // Master initaliser
1059     virtual bool initWithOptions(void *         buffers,
1060                                  UInt32         count,
1061                                  UInt32         offset,
1062                                  task_t         task,
1063                                  IOOptionBits   options,
1064                                  IOMapper *     mapper = kIOMapperSystem) APPLE_KEXT_OVERRIDE;
1065
1066 #ifndef __LP64__
1067     // Secondary initialisers
1068     virtual bool initWithAddress(void *         address,
1069                                  IOByteCount    withLength,
1070                                  IODirection    withDirection) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1071
1072     virtual bool initWithAddress(IOVirtualAddress address,
1073                                  IOByteCount    withLength,
1074                                  IODirection    withDirection,
1075                                  task_t         withTask) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1076
1077     virtual bool initWithPhysicalAddress(
1078                                  IOPhysicalAddress      address,
1079                                  IOByteCount            withLength,
1080                                  IODirection            withDirection ) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1081
1082     virtual bool initWithRanges(        IOVirtualRange * ranges,
1083                                         UInt32           withCount,
1084                                         IODirection      withDirection,
1085                                         task_t           withTask,
1086                                         bool             asReference = false) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1087
1088     virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
1089                                         UInt32           withCount,
1090                                         IODirection      withDirection,
1091                                         bool             asReference = false) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1092
1093     virtual addr64_t getPhysicalSegment64( IOByteCount offset,
1094                                             IOByteCount * length ) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1095
1096     virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
1097                                                  IOByteCount * length) APPLE_KEXT_OVERRIDE;
1098
1099     virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
1100                                                IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1101
1102     virtual void * getVirtualSegment(IOByteCount offset,
1103                                         IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED;
1104 #endif /* !__LP64__ */
1105
1106     virtual IOReturn setPurgeable( IOOptionBits newState,
1107                                     IOOptionBits * oldState ) APPLE_KEXT_OVERRIDE;
1108
1109     virtual addr64_t getPhysicalSegment( IOByteCount   offset,
1110                                          IOByteCount * length,
1111 #ifdef __LP64__
1112                                          IOOptionBits  options = 0 ) APPLE_KEXT_OVERRIDE;
1113 #else /* !__LP64__ */
1114                                          IOOptionBits  options ) APPLE_KEXT_OVERRIDE;
1115 #endif /* !__LP64__ */
1116
1117     virtual IOReturn prepare(IODirection forDirection = kIODirectionNone) APPLE_KEXT_OVERRIDE;
1118
1119     virtual IOReturn complete(IODirection forDirection = kIODirectionNone) APPLE_KEXT_OVERRIDE;
1120
1121     virtual IOReturn doMap(
1122         vm_map_t                addressMap,
1123         IOVirtualAddress *      atAddress,
1124         IOOptionBits            options,
1125         IOByteCount             sourceOffset = 0,
1126         IOByteCount             length = 0 ) APPLE_KEXT_OVERRIDE;
1127
1128     virtual IOReturn doUnmap(
1129         vm_map_t                addressMap,
1130         IOVirtualAddress        logical,
1131         IOByteCount             length ) APPLE_KEXT_OVERRIDE;
1132
1133     virtual bool serialize(OSSerialize *s) const APPLE_KEXT_OVERRIDE;
1134
1135     // Factory method for cloning a persistent IOMD, see IOMemoryDescriptor
1136     static IOMemoryDescriptor *
1137         withPersistentMemoryDescriptor(IOGeneralMemoryDescriptor *originalMD);
1138
1139 };
1140
1141 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
1142
1143 #ifdef __LP64__
1144 mach_vm_address_t       IOMemoryMap::getAddress()
1145 {
1146     return (getVirtualAddress());
1147 }
1148
1149 mach_vm_size_t  IOMemoryMap::getSize()
1150 {
1151     return (getLength());
1152 }
1153 #else /* !__LP64__ */
1154 #include <IOKit/IOSubMemoryDescriptor.h>
1155 #endif /* !__LP64__ */
1156
1157 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
1158
1159 #endif /* !_IOMEMORYDESCRIPTOR_H */