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