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