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