Lines Matching defs:IOMemoryDescriptor
111 /*! @class IOMemoryDescriptor : public OSObject
113 @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. */
115 class IOMemoryDescriptor : public OSObject
120 OSDeclareDefaultStructors(IOMemoryDescriptor);
130 IOMemoryDescriptor * memory;
150 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 0);
153 @abstract Master initialiser for all variants of memory descriptors. For a more complete description see IOMemoryDescriptor::withOptions.
162 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 1);
166 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 2);
185 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 3);
199 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 4);
203 OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 5);
206 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 6);
207 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 7);
208 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 8);
209 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 9);
210 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 10);
211 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 11);
212 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 12);
213 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 13);
214 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 14);
215 OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 15);
224 @abstract Create an IOMemoryDescriptor to describe one virtual range of the kernel task.
225 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the kernel map.
229 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
231 static IOMemoryDescriptor * withAddress(void * address,
236 @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
237 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map.
242 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
244 static IOMemoryDescriptor * withAddress(vm_address_t address,
250 @abstract Create an IOMemoryDescriptor to describe one physical range.
251 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.
255 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
257 static IOMemoryDescriptor * withPhysicalAddress(
263 @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
264 @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.
269 @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.
270 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
272 static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges,
279 @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
280 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single virtual memory range mapped into the specified map. Note that unlike IOMemoryDescriptor::withAddress(), kernel_task memory must be explicitly prepared when passed to this api.
285 @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.
286 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
288 static IOMemoryDescriptor * withAddressRange(
295 @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
296 @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. Note that unlike IOMemoryDescriptor::withAddress(), kernel_task memory must be explicitly prepared when passed to this api.
302 @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.
303 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
305 static IOMemoryDescriptor * withAddressRanges(
313 @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. However we temporarily have setup a mechanism that automatically prepares kernel_task memory descriptors at creation time.
333 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
335 static IOMemoryDescriptor *withOptions(void * buffers,
343 @abstract Create an IOMemoryDescriptor to describe one or more physical ranges.
344 @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of an array of physical memory ranges.
348 @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.
349 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
351 static IOMemoryDescriptor * withPhysicalRanges(
358 @abstract Create an IOMemoryDescriptor to describe a subrange of an existing descriptor.
359 @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.
360 @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.
364 @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
366 static IOMemoryDescriptor * withSubRange(IOMemoryDescriptor *of,
376 static IOMemoryDescriptor *
377 withPersistentMemoryDescriptor(IOMemoryDescriptor *originalMD);
380 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the kernel task.
381 @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.
392 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one virtual range of the specified map.
393 @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.
406 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one physical range.
407 @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.
419 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more virtual ranges.
420 @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.
425 @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.
435 @abstract Initialize or reinitialize an IOMemoryDescriptor to describe one or more physical ranges.
436 @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.
440 @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.
464 @discussion This method sets the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
471 @discussion This method returns the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
542 @abstract Maps a IOMemoryDescriptor into a task.
543 @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.
553 @param offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
554 @param length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
555 @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. */
565 @abstract Maps a IOMemoryDescriptor into a task - deprecated, only safe for 32 bit tasks. Use createMappingInTask instead.
566 @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.
576 @param offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
577 @param length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
578 @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. */
589 @abstract Maps a IOMemoryDescriptor into the kernel map.
599 @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.
625 IOMemoryDescriptor * owner,
655 @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. */
671 @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.
702 @abstract Accessor to the IOMemoryDescriptor the mapping was created from.
703 @discussion This method returns the IOMemoryDescriptor the mapping was created from.
704 @result An IOMemoryDescriptor reference, which is valid while the IOMemoryMap object is retained. It should not be released by the caller. */
706 virtual IOMemoryDescriptor * getMemoryDescriptor() = 0;
710 @discussion This method returns the options to IOMemoryDescriptor::map the mapping was created with.
726 @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.
727 @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.
728 @param options Mapping options are defined in IOTypes.h, and are documented in IOMemoryDescriptor::map()
729 @param offset As with IOMemoryDescriptor::map(), a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default.
732 virtual IOReturn redirect(IOMemoryDescriptor * newBackingMemory,
736 virtual IOReturn redirect(IOMemoryDescriptor * newBackingMemory,
746 // The following classes are private implementation of IOMemoryDescriptor - they
748 // IOMemoryDescriptor class. For example, an IOGeneralMemoryDescriptor instance
749 // might be created by IOMemoryDescriptor::withAddress(), but there should be
750 // no need to reference as anything but a generic IOMemoryDescriptor *.
752 class IOGeneralMemoryDescriptor : public IOMemoryDescriptor
808 * IOMemoryDescriptor required methods
875 // Factory method for cloning a persistent IOMD, see IOMemoryDescriptor
876 static IOMemoryDescriptor *
883 class IOSubMemoryDescriptor : public IOMemoryDescriptor
885 friend class IOMemoryDescriptor;
890 IOMemoryDescriptor * _parent;
920 IOMemoryDescriptor::withAddress;
921 IOMemoryDescriptor::withPhysicalAddress;
922 IOMemoryDescriptor::withPhysicalRanges;
923 IOMemoryDescriptor::withRanges;
924 IOMemoryDescriptor::withSubRange;
938 virtual bool initSubRange( IOMemoryDescriptor * parent,
943 * IOMemoryDescriptor required methods
980 IOMemoryDescriptor * owner,