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