- @abstract Create an IOMemoryDescriptor to describe one physical range.
- @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.
- @param address The physical address of the first byte in the memory.
- @param withLength The length of memory.
- @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.
- @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
-
- static IOMemoryDescriptor * withPhysicalAddress(
- IOPhysicalAddress address,
- IOByteCount withLength,
- IODirection withDirection );
-
-/*! @function withRanges
- @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
- @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.
- @param ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
- @param withCount The member count of the ranges array.
- @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.
- @param withTask The task each of the virtual ranges are mapped into.
- @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
- @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
-
- static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges,
- UInt32 withCount,
- IODirection withDirection,
- task_t withTask,
- bool asReference = false);
-
-/*! @function withPhysicalRanges
- @abstract Create an IOMemoryDescriptor to describe one or more physical ranges.
- @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges.
- @param ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
- @param withCount The member count of the ranges array.
- @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.
- @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
- @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
-
- static IOMemoryDescriptor * withPhysicalRanges(
- IOPhysicalRange * ranges,
- UInt32 withCount,
- IODirection withDirection,
- bool asReference = false);
-
-/*! @function withSubRange
- @abstract Create an IOMemoryDescriptor to describe a subrange of an existing descriptor.
- @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a subrange of the specified memory descriptor. The parent memory descriptor is retained by the new descriptor.
- @param of The parent IOMemoryDescriptor of which a subrange is to be used for the new descriptor, which will be retained by the subrange IOMemoryDescriptor.
- @param offset A byte offset into the parent memory descriptor's memory.
- @param length The length of the subrange.
- @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. This is used over the direction of the parent descriptor.
- @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
-
- static IOMemoryDescriptor * withSubRange(IOMemoryDescriptor * of,
- IOByteCount offset,
- IOByteCount length,
- IODirection withDirection);
-
-/*! @function initWithAddress
- @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the kernel task.
- @discussion This method initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
- @param address The virtual address of the first byte in the memory.
- @param withLength The length of memory.
- @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.
- @result true on success, false on failure. */
-
- virtual bool initWithAddress(void * address,
- IOByteCount withLength,
- IODirection withDirection) = 0;
-
-/*! @function initWithAddress
- @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the specified map.
- @discussion This method initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
- @param address The virtual address of the first byte in the memory.
- @param withLength The length of memory.
- @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.
- @param withTask The task the virtual ranges are mapped into.
- @result true on success, false on failure. */
-
- virtual bool initWithAddress(vm_address_t address,
- IOByteCount withLength,
- IODirection withDirection,
- task_t withTask) = 0;
-
-/*! @function initWithPhysicalAddress
- @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one physical range.
- @discussion This method initializes an IOMemoryDescriptor for memory consisting of a single physical memory range. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
- @param address The physical address of the first byte in the memory.
- @param withLength The length of memory.
- @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.
- @result true on success, false on failure. */
-
- virtual bool initWithPhysicalAddress(
- IOPhysicalAddress address,
- IOByteCount withLength,
- IODirection withDirection ) = 0;
-
-/*! @function initWithRanges
- @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more virtual ranges.
- @discussion This method initializes an IOMemoryDescriptor for memory consisting of an array of virtual memory ranges each mapped into a specified source task. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
- @param ranges An array of IOVirtualRange structures which specify the virtual ranges in the specified map which make up the memory to be described.
- @param withCount The member count of the ranges array.
- @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.
- @param withTask The task each of the virtual ranges are mapped into.
- @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
- @result true on success, false on failure. */
-
- virtual bool initWithRanges( IOVirtualRange * ranges,
- UInt32 withCount,
- IODirection withDirection,
- task_t withTask,
- bool asReference = false) = 0;
-
-/*! @function initWithPhysicalRanges
- @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more physical ranges.
- @discussion This method initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges. An IOMemoryDescriptor can be re-used by calling initWithAddress or initWithRanges again on an existing instance -- note this behavior is not commonly supported in other IOKit classes, although it is supported here.
- @param ranges An array of IOPhysicalRange structures which specify the physical ranges which make up the memory to be described.
- @param withCount The member count of the ranges array.
- @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.
- @param asReference If false, the IOMemoryDescriptor object will make a copy of the ranges array, otherwise, the array will be used in situ, avoiding an extra allocation.
- @result true on success, false on failure. */
-
- virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
- UInt32 withCount,
- IODirection withDirection,
- bool asReference = false) = 0;
+ * @abstract Create an IOMemoryDescriptor to describe one physical range.
+ * @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.
+ * @param address The physical address of the first byte in the memory.
+ * @param withLength The length of memory.
+ * @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.
+ * @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
+
+ static IOMemoryDescriptor * withPhysicalAddress(
+ IOPhysicalAddress address,
+ IOByteCount withLength,
+ IODirection withDirection );
+
+#ifndef __LP64__
+ static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges,
+ UInt32 withCount,
+ IODirection withDirection,
+ task_t withTask,
+ bool asReference = false) APPLE_KEXT_DEPRECATED; /* use withAddressRanges() instead */
+#endif /* !__LP64__ */
+
+/*! @function withAddressRange
+ * @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
+ * @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.
+ * @param address The virtual address of the first byte in the memory.
+ * @param length The length of memory.
+ * @param options
+ * 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.
+ * @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.
+ * @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
+
+ static IOMemoryDescriptor * withAddressRange(
+ mach_vm_address_t address,
+ mach_vm_size_t length,
+ IOOptionBits options,
+ task_t task);
+
+/*! @function withAddressRanges
+ * @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
+ * @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.
+ * @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.
+ * @param rangeCount The member count of the ranges array.
+ * @param options
+ * 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.
+ * 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.
+ * @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.
+ * @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
+
+ static IOMemoryDescriptor * withAddressRanges(
+ IOAddressRange * ranges,
+ UInt32 rangeCount,
+ IOOptionBits options,
+ task_t task);
+
+/*! @function withOptions
+ * @abstract Master initialiser for all variants of memory descriptors.
+ * @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.
+ *
+ *
+ * @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.
+ *
+ * @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.
+ *
+ * @param offset Only used when options:type = UPL, in which case this field contains an offset for the memory within the buffers upl.
+ *
+ * @param task Only used options:type = Virtual, The task each of the virtual ranges are mapped into.
+ *
+ * @param options
+ * 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.
+ * 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.
+ * 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.
+ * 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.
+ *
+ * @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.
+ *
+ * @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
+
+ static IOMemoryDescriptor *withOptions(void * buffers,
+ UInt32 count,
+ UInt32 offset,
+ task_t task,
+ IOOptionBits options,
+ IOMapper * mapper = kIOMapperSystem);
+
+#ifndef __LP64__
+ static IOMemoryDescriptor * withPhysicalRanges(
+ IOPhysicalRange * ranges,
+ UInt32 withCount,
+ IODirection withDirection,
+ bool asReference = false) APPLE_KEXT_DEPRECATED; /* use withOptions() and kIOMemoryTypePhysical instead */
+#endif /* !__LP64__ */
+
+#ifndef __LP64__
+ static IOMemoryDescriptor * withSubRange(IOMemoryDescriptor *of,
+ IOByteCount offset,
+ IOByteCount length,
+ IODirection withDirection) APPLE_KEXT_DEPRECATED; /* use IOSubMemoryDescriptor::withSubRange() and kIOMemoryThreadSafe instead */
+#endif /* !__LP64__ */
+
+/*! @function withPersistentMemoryDescriptor
+ * @abstract Copy constructor that generates a new memory descriptor if the backing memory for the same task's virtual address and length has changed.
+ * @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.
+ * @param originalMD The memory descriptor to be duplicated.
+ * @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. */
+ static IOMemoryDescriptor *
+ withPersistentMemoryDescriptor(IOMemoryDescriptor *originalMD);
+
+#ifndef __LP64__
+// obsolete initializers
+// - initWithOptions is the designated initializer
+ virtual bool initWithAddress(void * address,
+ IOByteCount withLength,
+ IODirection withDirection) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
+ virtual bool initWithAddress(IOVirtualAddress address,
+ IOByteCount withLength,
+ IODirection withDirection,
+ task_t withTask) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
+ virtual bool initWithPhysicalAddress(
+ IOPhysicalAddress address,
+ IOByteCount withLength,
+ IODirection withDirection ) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
+ virtual bool initWithRanges(IOVirtualRange * ranges,
+ UInt32 withCount,
+ IODirection withDirection,
+ task_t withTask,
+ bool asReference = false) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
+ virtual bool initWithPhysicalRanges(IOPhysicalRange * ranges,
+ UInt32 withCount,
+ IODirection withDirection,
+ bool asReference = false) APPLE_KEXT_DEPRECATED; /* use initWithOptions() instead */
+#endif /* __LP64__ */
projects / apple / xnu.git / blobdiff