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 };
  97
  98 #define kIOMapperSystem ((IOMapper *) 0)
  99
 100 enum
 101 {
 102     kIOMemoryPurgeableKeepCurrent = 1,
 103     kIOMemoryPurgeableNonVolatile = 2,
 104     kIOMemoryPurgeableVolatile    = 3,
 105     kIOMemoryPurgeableEmpty       = 4
 106 };
 107 enum
 108 {
 109     kIOMemoryIncoherentIOFlush   = 1,
 110     kIOMemoryIncoherentIOStore   = 2,
 111 };
 112
 113 #define IOMEMORYDESCRIPTOR_SUPPORTS_DMACOMMAND  1
 114
 115 enum
 116 {
 117     kIOPreparationIDUnprepared = 0,
 118     kIOPreparationIDUnsupported = 1,
 119     kIOPreparationIDAlwaysPrepared = 2,
 120 };
 121
 122 /*! @class IOMemoryDescriptor : public OSObject
 123     @abstract An abstract base class defining common methods for describing physical or virtual memory.
 124     @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. */
 125
 126 class IOMemoryDescriptor : public OSObject
 127 {
 128     friend class IOMemoryMap;
 129
 130     OSDeclareDefaultStructors(IOMemoryDescriptor);
 131
 132 protected:
 133 /*! @struct ExpansionData
 134     @discussion This structure will be used to expand the capablilties of this class in the future.
 135     */
 136     struct ExpansionData {
 137         void *                          devicePager;
 138         unsigned int                    pagerContig:1;
 139         unsigned int                    unused:31;
 140         IOMemoryDescriptor *            memory;
 141     };
 142
 143 /*! @var reserved
 144     Reserved for future use.  (Internal use only)  */
 145     ExpansionData * reserved;
 146
 147 protected:
 148     OSSet *             _mappings;
 149     IOOptionBits        _flags;
 150     void *              _memEntry;
 151
 152 #ifdef __LP64__
 153     uint64_t            __iomd_reserved1;
 154     uint64_t            __iomd_reserved2;
 155     uint64_t            __iomd_reserved3;
 156     uint64_t            __iomd_reserved4;
 157 #else /* !__LP64__ */
 158     IODirection         _direction;        /* use _flags instead */
 159 #endif /* !__LP64__ */
 160     IOByteCount         _length;           /* length of all ranges */
 161     IOOptionBits        _tag;
 162
 163 public:
 164 typedef IOOptionBits DMACommandOps;
 165 #ifndef __LP64__
 166     virtual IOPhysicalAddress getSourceSegment( IOByteCount offset,
 167                                                 IOByteCount * length ) APPLE_KEXT_DEPRECATED;
 168 #endif /* !__LP64__ */
 169
 170 /*! @function initWithOptions
 171     @abstract Master initialiser for all variants of memory descriptors.  For a more complete description see IOMemoryDescriptor::withOptions.
 172     @discussion Note this function can be used to re-init a previously created memory descriptor.
 173     @result true on success, false on failure. */
 174     virtual bool initWithOptions(void *         buffers,
 175                                  UInt32         count,
 176                                  UInt32         offset,
 177                                  task_t         task,
 178                                  IOOptionBits   options,
 179                                  IOMapper *     mapper = kIOMapperSystem);
 180
 181 #ifndef __LP64__
 182     virtual addr64_t getPhysicalSegment64( IOByteCount offset,
 183                                             IOByteCount * length ) APPLE_KEXT_DEPRECATED; /* use getPhysicalSegment() and kIOMemoryMapperNone instead */
 184 #endif /* !__LP64__ */
 185
 186 /*! @function setPurgeable
 187     @abstract Control the purgeable status of a memory descriptors memory.
 188     @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.
 189     @param newState - the desired new purgeable state of the memory:<br>
 190     kIOMemoryPurgeableKeepCurrent - make no changes to the memory's purgeable state.<br>
 191     kIOMemoryPurgeableVolatile    - make the memory volatile - the memory may be reclaimed by the VM system without saving its contents to backing store.<br>
 192     kIOMemoryPurgeableNonVolatile - make the memory nonvolatile - the memory is treated as with usual allocations and must be saved to backing store if paged.<br>
 193     kIOMemoryPurgeableEmpty       - make the memory volatile, and discard any pages allocated to it.
 194     @param oldState - if non-NULL, the previous purgeable state of the memory is returned here:<br>
 195     kIOMemoryPurgeableNonVolatile - the memory was nonvolatile.<br>
 196     kIOMemoryPurgeableVolatile    - the memory was volatile but its content has not been discarded by the VM system.<br>
 197     kIOMemoryPurgeableEmpty       - the memory was volatile and has been discarded by the VM system.<br>
 198     @result An IOReturn code. */
 199
 200     virtual IOReturn setPurgeable( IOOptionBits newState,
 201                                     IOOptionBits * oldState );
 202
 203 /*! @function performOperation
 204     @abstract Perform an operation on the memory descriptor's memory.
 205     @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.
 206     @param options The operation to perform on the memory:<br>
 207     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>
 208     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.
 209     @param offset A byte offset into the memory descriptor's memory.
 210     @param length The length of the data range.
 211     @result An IOReturn code. */
 212
 213     virtual IOReturn performOperation( IOOptionBits options,
 214                                         IOByteCount offset, IOByteCount length );
 215
 216     // Used for dedicated communications for IODMACommand
 217     virtual IOReturn dmaCommandOperation(DMACommandOps op, void *vData, UInt dataSize) const;
 218
 219 /*! @function getPhysicalSegment
 220     @abstract Break a memory descriptor into its physically contiguous segments.
 221     @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.
 222     @param offset A byte offset into the memory whose physical address to return.
 223     @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
 224     @result A physical address, or zero if the offset is beyond the length of the memory. */
 225
 226 #ifdef __LP64__
 227     virtual addr64_t getPhysicalSegment( IOByteCount   offset,
 228                                          IOByteCount * length,
 229                                          IOOptionBits  options = 0 ) = 0;
 230 #else /* !__LP64__ */
 231     virtual addr64_t getPhysicalSegment( IOByteCount   offset,
 232                                          IOByteCount * length,
 233                                          IOOptionBits  options );
 234 #endif /* !__LP64__ */
 235
 236     virtual uint64_t getPreparationID( void );
 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.
 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.
 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.
 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     inline mach_vm_address_t    getAddress() __attribute__((always_inline));
 725     inline mach_vm_size_t       getSize() __attribute__((always_inline));
 726 #else /* !__LP64__ */
 727     virtual mach_vm_address_t   getAddress();
 728     virtual mach_vm_size_t      getSize();
 729 #endif /* !__LP64__ */
 730
 731 #ifdef XNU_KERNEL_PRIVATE
 732     // for IOMemoryDescriptor use
 733     IOMemoryMap * copyCompatible( IOMemoryMap * newMapping );
 734
 735     bool init(
 736         task_t                  intoTask,
 737         mach_vm_address_t       toAddress,
 738         IOOptionBits            options,
 739         mach_vm_size_t          offset,
 740         mach_vm_size_t          length );
 741
 742     bool    setMemoryDescriptor(IOMemoryDescriptor * _memory, mach_vm_size_t _offset);
 743
 744     IOReturn redirect(
 745         task_t                  intoTask, bool redirect );
 746
 747     IOReturn userClientUnmap();
 748 #endif /* XNU_KERNEL_PRIVATE */
 749
 750     OSMetaClassDeclareReservedUnused(IOMemoryMap, 0);
 751     OSMetaClassDeclareReservedUnused(IOMemoryMap, 1);
 752     OSMetaClassDeclareReservedUnused(IOMemoryMap, 2);
 753     OSMetaClassDeclareReservedUnused(IOMemoryMap, 3);
 754     OSMetaClassDeclareReservedUnused(IOMemoryMap, 4);
 755     OSMetaClassDeclareReservedUnused(IOMemoryMap, 5);
 756     OSMetaClassDeclareReservedUnused(IOMemoryMap, 6);
 757     OSMetaClassDeclareReservedUnused(IOMemoryMap, 7);
 758 };
 759
 760 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 761 #ifdef XNU_KERNEL_PRIVATE
 762 // Also these flags should not overlap with the options to
 763 //      IOMemoryDescriptor::initWithRanges(... IOOptionsBits options);
 764 enum {
 765     _kIOMemorySourceSegment     = 0x00002000
 766 };
 767 #endif /* XNU_KERNEL_PRIVATE */
 768
 769 #if !defined(__LP64) || defined(_IOMEMORYDESCRIPTOR_INTERNAL_)
 770
 771 // The following classes are private implementation of IOMemoryDescriptor - they
 772 // should not be referenced directly, just through the public API's in the
 773 // IOMemoryDescriptor class. For example, an IOGeneralMemoryDescriptor instance
 774 // might be created by IOMemoryDescriptor::withAddressRange(), but there should be
 775 // no need to reference as anything but a generic IOMemoryDescriptor *.
 776
 777 class IOGeneralMemoryDescriptor : public IOMemoryDescriptor
 778 {
 779     OSDeclareDefaultStructors(IOGeneralMemoryDescriptor);
 780
 781 public:
 782     union Ranges {
 783         IOVirtualRange   *v;
 784         IOAddressRange   *v64;
 785         IOPhysicalRange  *p;
 786         void             *uio;
 787     };
 788 protected:
 789     Ranges              _ranges;
 790     unsigned            _rangesCount;       /* number of address ranges in list */
 791 #ifndef __LP64__
 792     bool                _rangesIsAllocated; /* is list allocated by us? */
 793 #endif /* !__LP64__ */
 794
 795     task_t              _task;               /* task where all ranges are mapped to */
 796
 797     union {
 798         IOVirtualRange  v;
 799         IOPhysicalRange p;
 800     }                   _singleRange;      /* storage space for a single range */
 801
 802     unsigned            _wireCount;        /* number of outstanding wires */
 803
 804 #ifndef __LP64__
 805     uintptr_t _cachedVirtualAddress;
 806
 807     IOPhysicalAddress   _cachedPhysicalAddress;
 808 #endif /* !__LP64__ */
 809
 810     bool                _initialized;      /* has superclass been initialized? */
 811
 812 public:
 813     virtual void free();
 814
 815     virtual IOReturn dmaCommandOperation(DMACommandOps op, void *vData, UInt dataSize) const;
 816
 817     virtual uint64_t getPreparationID( void );
 818
 819 private:
 820
 821 #ifndef __LP64__
 822     virtual void setPosition(IOByteCount position);
 823     virtual void mapIntoKernel(unsigned rangeIndex);
 824     virtual void unmapFromKernel();
 825 #endif /* !__LP64__ */
 826
 827     // Internal APIs may be made virtual at some time in the future.
 828     IOReturn wireVirtual(IODirection forDirection);
 829     void *createNamedEntry();
 830
 831     // Internal
 832     OSData *        _memoryEntries;
 833     unsigned int    _pages;
 834     ppnum_t         _highestPage;
 835     uint32_t        __iomd_reservedA;
 836     uint32_t        __iomd_reservedB;
 837
 838     IOLock *        _prepareLock;
 839
 840 public:
 841     /*
 842      * IOMemoryDescriptor required methods
 843      */
 844
 845     // Master initaliser
 846     virtual bool initWithOptions(void *         buffers,
 847                                  UInt32         count,
 848                                  UInt32         offset,
 849                                  task_t         task,
 850                                  IOOptionBits   options,
 851                                  IOMapper *     mapper = kIOMapperSystem);
 852
 853 #ifndef __LP64__
 854     // Secondary initialisers
 855     virtual bool initWithAddress(void *         address,
 856                                  IOByteCount    withLength,
 857                                  IODirection    withDirection) APPLE_KEXT_DEPRECATED;
 858
 859     virtual bool initWithAddress(IOVirtualAddress address,
 860                                  IOByteCount    withLength,
 861                                  IODirection    withDirection,
 862                                  task_t         withTask) APPLE_KEXT_DEPRECATED;
 863
 864     virtual bool initWithPhysicalAddress(
 865                                  IOPhysicalAddress      address,
 866                                  IOByteCount            withLength,
 867                                  IODirection            withDirection ) APPLE_KEXT_DEPRECATED;
 868
 869     virtual bool initWithRanges(        IOVirtualRange * ranges,
 870                                         UInt32           withCount,
 871                                         IODirection      withDirection,
 872                                         task_t           withTask,
 873                                         bool             asReference = false) APPLE_KEXT_DEPRECATED;
 874
 875     virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
 876                                         UInt32           withCount,
 877                                         IODirection      withDirection,
 878                                         bool             asReference = false) APPLE_KEXT_DEPRECATED;
 879
 880     virtual addr64_t getPhysicalSegment64( IOByteCount offset,
 881                                             IOByteCount * length ) APPLE_KEXT_DEPRECATED;
 882
 883     virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
 884                                                  IOByteCount * length);
 885
 886     virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
 887                                                IOByteCount * length) APPLE_KEXT_DEPRECATED;
 888
 889     virtual void * getVirtualSegment(IOByteCount offset,
 890                                         IOByteCount * length) APPLE_KEXT_DEPRECATED;
 891 #endif /* !__LP64__ */
 892
 893     virtual IOReturn setPurgeable( IOOptionBits newState,
 894                                     IOOptionBits * oldState );
 895
 896     virtual addr64_t getPhysicalSegment( IOByteCount   offset,
 897                                          IOByteCount * length,
 898 #ifdef __LP64__
 899                                          IOOptionBits  options = 0 );
 900 #else /* !__LP64__ */
 901                                          IOOptionBits  options );
 902 #endif /* !__LP64__ */
 903
 904     virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);
 905
 906     virtual IOReturn complete(IODirection forDirection = kIODirectionNone);
 907
 908     virtual IOReturn doMap(
 909         vm_map_t                addressMap,
 910         IOVirtualAddress *      atAddress,
 911         IOOptionBits            options,
 912         IOByteCount             sourceOffset = 0,
 913         IOByteCount             length = 0 );
 914
 915     virtual IOReturn doUnmap(
 916         vm_map_t                addressMap,
 917         IOVirtualAddress        logical,
 918         IOByteCount             length );
 919
 920     virtual bool serialize(OSSerialize *s) const;
 921
 922     // Factory method for cloning a persistent IOMD, see IOMemoryDescriptor
 923     static IOMemoryDescriptor *
 924         withPersistentMemoryDescriptor(IOGeneralMemoryDescriptor *originalMD);
 925
 926 };
 927
 928 #endif /* !defined(__LP64) || defined(_IOMEMORYDESCRIPTOR_INTERNAL_) */
 929
 930 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 931
 932 #ifdef __LP64__
 933 mach_vm_address_t       IOMemoryMap::getAddress()
 934 {
 935     return (getVirtualAddress());
 936 }
 937
 938 mach_vm_size_t  IOMemoryMap::getSize()
 939 {
 940     return (getLength());
 941 }
 942 #else /* !__LP64__ */
 943 #include <IOKit/IOSubMemoryDescriptor.h>
 944 #endif /* !__LP64__ */
 945
 946 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 947
 948 #endif /* !_IOMEMORYDESCRIPTOR_H */