iokit/IOKit/IOMemoryDescriptor.h

187 /*! @class IOMemoryDescriptor : public OSObject
189     @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. */
191 class IOMemoryDescriptor : public OSObject
195     OSDeclareDefaultStructors(IOMemoryDescriptor);
235     @abstract Master initialiser for all variants of memory descriptors.  For a more complete description see IOMemoryDescriptor::withOptions.
269     @abstract Retrieve the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.
270     @discussion This method returns the number of resident and/or dirty pages encompassed by an IOMemoryDescriptor.
271     @param residentPageCount - If non-null, a pointer to a byte count that will return the number of resident pages encompassed by this IOMemoryDescriptor.
272     @param dirtyPageCount - If non-null, a pointer to a byte count that will return the number of dirty pages encompassed by this IOMemoryDescriptor.
326     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 0);
328     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 1);
329     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 2);
330     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 3);
331     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 4);
332     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 5);
333     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 6);
334     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 7);
336     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 1);
337     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 2);
338     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 3);
339     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 4);
340     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 5);
341     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 6);
342     OSMetaClassDeclareReservedUsed(IOMemoryDescriptor, 7);
344     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 8);
345     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 9);
346     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 10);
347     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 11);
348     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 12);
349     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 13);
350     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 14);
351     OSMetaClassDeclareReservedUnused(IOMemoryDescriptor, 15);
360     @abstract Create an IOMemoryDescriptor to describe one virtual range of the kernel task.
361     @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.
365     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
367     static IOMemoryDescriptor * withAddress(void *       address,
372     static IOMemoryDescriptor * withAddress(IOVirtualAddress address,
379     @abstract Create an IOMemoryDescriptor to describe one physical range.
380     @discussion This method creates and initializes an IOMemoryDescriptor for memory consisting of a single physical memory range.
384     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
386     static IOMemoryDescriptor * withPhysicalAddress(
392      static IOMemoryDescriptor * withRanges(IOVirtualRange * ranges,
400     @abstract Create an IOMemoryDescriptor to describe one virtual range of the specified map.
401     @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.
406     @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.
407     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
409     static IOMemoryDescriptor * withAddressRange(
416     @abstract Create an IOMemoryDescriptor to describe one or more virtual ranges.
417     @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.
423     @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.
424     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
426     static IOMemoryDescriptor * withAddressRanges(
434     @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.
453     @result The created IOMemoryDescriptor on success, to be released by the caller, or zero on failure. */
455     static IOMemoryDescriptor *withOptions(void *	buffers,
463     static IOMemoryDescriptor * withPhysicalRanges(
471     static IOMemoryDescriptor *	withSubRange(IOMemoryDescriptor *of,
482     static IOMemoryDescriptor *
483 	withPersistentMemoryDescriptor(IOMemoryDescriptor *originalMD);
526     @discussion This method sets the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
533     @discussion This method returns the tag for the memory descriptor. Tag bits are not interpreted by IOMemoryDescriptor.
598     @abstract Maps a IOMemoryDescriptor into a task.
599     @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.
610     @param offset Is a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default to map all the memory.
611     @param length Is the length of the mapping requested for a subset of the IOMemoryDescriptor. Zero is the default to map all the memory.
612     @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. */
631     @abstract Maps a IOMemoryDescriptor into the kernel map.
641     @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.
673 	IOMemoryDescriptor *	owner,
704     @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. */
711     IOMemoryDescriptor * fMemory;
721     IOMemoryDescriptor * fOwner;
739     @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.
775     @abstract Accessor to the IOMemoryDescriptor the mapping was created from.
776     @discussion This method returns the IOMemoryDescriptor the mapping was created from.
777     @result An IOMemoryDescriptor reference, which is valid while the IOMemoryMap object is retained. It should not be released by the caller. */
779     virtual IOMemoryDescriptor * getMemoryDescriptor();
783     @discussion This method returns the options to IOMemoryDescriptor::map the mapping was created with.
799     @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.
800     @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.
801     @param options Mapping options are defined in IOTypes.h, and are documented in IOMemoryDescriptor::map()
802     @param offset As with IOMemoryDescriptor::map(), a beginning offset into the IOMemoryDescriptor's memory where the mapping starts. Zero is the default.
808     virtual IOReturn		redirect(IOMemoryDescriptor * newBackingMemory,
812     virtual IOReturn		redirect(IOMemoryDescriptor * newBackingMemory,
841     // for IOMemoryDescriptor use
851     bool    setMemoryDescriptor(IOMemoryDescriptor * _memory, mach_vm_size_t _offset);
877 //	IOMemoryDescriptor::initWithRanges(... IOOptionsBits options);
883 // The following classes are private implementation of IOMemoryDescriptor - they
885 // IOMemoryDescriptor class. For example, an IOGeneralMemoryDescriptor instance
886 // might be created by IOMemoryDescriptor::withAddressRange(), but there should be
887 // no need to reference as anything but a generic IOMemoryDescriptor *.
889 class IOGeneralMemoryDescriptor : public IOMemoryDescriptor
988      * IOMemoryDescriptor required methods
1068     // Factory method for cloning a persistent IOMD, see IOMemoryDescriptor
1069     static IOMemoryDescriptor *