X-Git-Url: https://git.saurik.com/apple/xnu.git/blobdiff_plain/b226f5e54a60dc81db17b1260381d7dbfea3cdf1..0a7de7458d150b5d4dffc935ba399be265ef0a1a:/iokit/IOKit/IOBufferMemoryDescriptor.h diff --git a/iokit/IOKit/IOBufferMemoryDescriptor.h b/iokit/IOKit/IOBufferMemoryDescriptor.h index 4b218498b..e025e01a3 100644 --- a/iokit/IOKit/IOBufferMemoryDescriptor.h +++ b/iokit/IOKit/IOBufferMemoryDescriptor.h @@ -2,7 +2,7 @@ * Copyright (c) 1998-2016 Apple Inc. All rights reserved. * * @APPLE_OSREFERENCE_LICENSE_HEADER_START@ - * + * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in @@ -11,10 +11,10 @@ * unlawful or unlicensed copies of an Apple operating system, or to * circumvent, violate, or enable the circumvention or violation of, any * terms of an Apple operating system software license agreement. - * + * * Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this file. - * + * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, @@ -22,7 +22,7 @@ * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. - * + * * @APPLE_OSREFERENCE_LICENSE_HEADER_END@ */ #ifndef _IOBUFFERMEMORYDESCRIPTOR_H @@ -31,249 +31,249 @@ #include enum { - kIOMemoryPhysicallyContiguous = 0x00000010, - kIOMemoryPageable = 0x00000020, - kIOMemoryPurgeable = 0x00000040, - kIOMemoryHostPhysicallyContiguous = 0x00000080, - kIOMemorySharingTypeMask = 0x000f0000, - kIOMemoryUnshared = 0x00000000, - kIOMemoryKernelUserShared = 0x00010000, - // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor: - kIOBufferDescriptorMemoryFlags = kIOMemoryDirectionMask + kIOMemoryPhysicallyContiguous = 0x00000010, + kIOMemoryPageable = 0x00000020, + kIOMemoryPurgeable = 0x00000040, + kIOMemoryHostPhysicallyContiguous = 0x00000080, + kIOMemorySharingTypeMask = 0x000f0000, + kIOMemoryUnshared = 0x00000000, + kIOMemoryKernelUserShared = 0x00010000, + // shared IOMemoryDescriptor options for IOBufferMemoryDescriptor: + kIOBufferDescriptorMemoryFlags = kIOMemoryDirectionMask #ifdef XNU_KERNEL_PRIVATE - | kIOMemoryAutoPrepare + | kIOMemoryAutoPrepare #endif - | kIOMemoryThreadSafe - | kIOMemoryClearEncrypt - | kIOMemoryMapperNone - | kIOMemoryUseReserve + | kIOMemoryThreadSafe + | kIOMemoryClearEncrypt + | kIOMemoryMapperNone + | kIOMemoryUseReserve }; -#define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1 -#define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_ 1 +#define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1 +#define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_ 1 /*! - @class IOBufferMemoryDescriptor - @abstract Provides a simple memory descriptor that allocates its own buffer memory. -*/ + * @class IOBufferMemoryDescriptor + * @abstract Provides a simple memory descriptor that allocates its own buffer memory. + */ class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor { - OSDeclareDefaultStructors(IOBufferMemoryDescriptor); + OSDeclareDefaultStructors(IOBufferMemoryDescriptor); private: /*! @struct ExpansionData - @discussion This structure will be used to expand the capablilties of this class in the future. - */ - struct ExpansionData { - IOMemoryMap * map; - }; + * @discussion This structure will be used to expand the capablilties of this class in the future. + */ + struct ExpansionData { + IOMemoryMap * map; + }; /*! @var reserved - Reserved for future use. (Internal use only) */ - APPLE_KEXT_WSHADOW_PUSH; - ExpansionData * reserved; + * Reserved for future use. (Internal use only) */ + APPLE_KEXT_WSHADOW_PUSH; + ExpansionData * reserved; protected: - void * _buffer; - vm_size_t _capacity; - vm_offset_t _alignment; - IOOptionBits _options; + void * _buffer; + vm_size_t _capacity; + vm_offset_t _alignment; + IOOptionBits _options; private: - uintptr_t _internalReserved; - unsigned _internalFlags; - APPLE_KEXT_WSHADOW_POP; + uintptr_t _internalReserved; + unsigned _internalFlags; + APPLE_KEXT_WSHADOW_POP; private: #ifndef __LP64__ - virtual bool initWithOptions( - IOOptionBits options, - vm_size_t capacity, - vm_offset_t alignment, - task_t inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ + virtual bool initWithOptions( + IOOptionBits options, + vm_size_t capacity, + vm_offset_t alignment, + task_t inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ #endif /* !__LP64__ */ public: - virtual bool initWithPhysicalMask( - task_t inTask, - IOOptionBits options, - mach_vm_size_t capacity, - mach_vm_address_t alignment, - mach_vm_address_t physicalMask); + virtual bool initWithPhysicalMask( + task_t inTask, + IOOptionBits options, + mach_vm_size_t capacity, + mach_vm_address_t alignment, + mach_vm_address_t physicalMask); #ifdef __LP64__ - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1); #else /* !__LP64__ */ - OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0); - OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1); + OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0); + OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1); #endif /* !__LP64__ */ - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14); - OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14); + OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15); protected: - virtual void free() APPLE_KEXT_OVERRIDE; + virtual void free() APPLE_KEXT_OVERRIDE; public: - /* - * withOptions: - * - * Returns a new IOBufferMemoryDescriptor with a buffer large enough to - * hold capacity bytes. The descriptor's length is initially set to the - * capacity. - */ +/* + * withOptions: + * + * Returns a new IOBufferMemoryDescriptor with a buffer large enough to + * hold capacity bytes. The descriptor's length is initially set to the + * capacity. + */ #ifndef __LP64__ - virtual bool initWithOptions( IOOptionBits options, - vm_size_t capacity, - vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ + virtual bool initWithOptions( IOOptionBits options, + vm_size_t capacity, + vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */ #endif /* !__LP64__ */ - static IOBufferMemoryDescriptor * withOptions( IOOptionBits options, - vm_size_t capacity, - vm_offset_t alignment = 1); + static IOBufferMemoryDescriptor * withOptions( IOOptionBits options, + vm_size_t capacity, + vm_offset_t alignment = 1); /*! @function inTaskWithOptions - @abstract Creates a memory buffer with memory descriptor for that buffer. - @discussion Added in Mac OS X 10.2, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. - @param inTask The task the buffer will be allocated in. - @param options Options for the allocation:
- kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.
- kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.
- kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.
- kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.
- kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
- kIOMapInhibitCache - allocate memory with inhibited cache setting.
- kIOMapWriteThruCache - allocate memory with writethru cache setting.
- kIOMapCopybackCache - allocate memory with copyback cache setting.
- kIOMapWriteCombineCache - allocate memory with writecombined cache setting. - @param capacity The number of bytes to allocate. - @param alignment The minimum required alignment of the buffer in bytes - 1 is the default for no required alignment. For example, pass 256 to get memory allocated at an address with bits 0-7 zero. - @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ + * @abstract Creates a memory buffer with memory descriptor for that buffer. + * @discussion Added in Mac OS X 10.2, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. + * @param inTask The task the buffer will be allocated in. + * @param options Options for the allocation:
+ * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.
+ * kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.
+ * kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.
+ * kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.
+ * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
+ * kIOMapInhibitCache - allocate memory with inhibited cache setting.
+ * kIOMapWriteThruCache - allocate memory with writethru cache setting.
+ * kIOMapCopybackCache - allocate memory with copyback cache setting.
+ * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. + * @param capacity The number of bytes to allocate. + * @param alignment The minimum required alignment of the buffer in bytes - 1 is the default for no required alignment. For example, pass 256 to get memory allocated at an address with bits 0-7 zero. + * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ - static IOBufferMemoryDescriptor * inTaskWithOptions( - task_t inTask, - IOOptionBits options, - vm_size_t capacity, - vm_offset_t alignment = 1); + static IOBufferMemoryDescriptor * inTaskWithOptions( + task_t inTask, + IOOptionBits options, + vm_size_t capacity, + vm_offset_t alignment = 1); /*! @function inTaskWithPhysicalMask - @abstract Creates a memory buffer with memory descriptor for that buffer. - @discussion Added in Mac OS X 10.5, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. - @param inTask The task the buffer will be mapped in. Pass NULL to create memory unmapped in any task (eg. for use as a DMA buffer). - @param options Options for the allocation:
- kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.
- kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.
- kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
- kIOMapInhibitCache - allocate memory with inhibited cache setting.
- kIOMapWriteThruCache - allocate memory with writethru cache setting.
- kIOMapCopybackCache - allocate memory with copyback cache setting.
- kIOMapWriteCombineCache - allocate memory with writecombined cache setting. - @param capacity The number of bytes to allocate. - @param physicalMask The buffer will be allocated with pages such that physical addresses will only have bits set present in physicalMask. For example, pass 0x00000000FFFFFFFFULL for a buffer to be accessed by hardware that has 32 address bits. - @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ + * @abstract Creates a memory buffer with memory descriptor for that buffer. + * @discussion Added in Mac OS X 10.5, this method allocates a memory buffer with a given size and alignment in the task's address space specified, and returns a memory descriptor instance representing the memory. It is recommended that memory allocated for I/O or sharing via mapping be created via IOBufferMemoryDescriptor. Options passed with the request specify the kind of memory to be allocated - pageablity and sharing are specified with option bits. This function may block and so should not be called from interrupt level or while a simple lock is held. + * @param inTask The task the buffer will be mapped in. Pass NULL to create memory unmapped in any task (eg. for use as a DMA buffer). + * @param options Options for the allocation:
+ * kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.
+ * kIOMemoryPhysicallyContiguous - pass to request memory be physically contiguous. This option is heavily discouraged. The request may fail if memory is fragmented, may cause large amounts of paging activity, and may take a very long time to execute.
+ * kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
+ * kIOMapInhibitCache - allocate memory with inhibited cache setting.
+ * kIOMapWriteThruCache - allocate memory with writethru cache setting.
+ * kIOMapCopybackCache - allocate memory with copyback cache setting.
+ * kIOMapWriteCombineCache - allocate memory with writecombined cache setting. + * @param capacity The number of bytes to allocate. + * @param physicalMask The buffer will be allocated with pages such that physical addresses will only have bits set present in physicalMask. For example, pass 0x00000000FFFFFFFFULL for a buffer to be accessed by hardware that has 32 address bits. + * @result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */ - static IOBufferMemoryDescriptor * inTaskWithPhysicalMask( - task_t inTask, - IOOptionBits options, - mach_vm_size_t capacity, - mach_vm_address_t physicalMask); + static IOBufferMemoryDescriptor * inTaskWithPhysicalMask( + task_t inTask, + IOOptionBits options, + mach_vm_size_t capacity, + mach_vm_address_t physicalMask); - /* - * withCapacity: - * - * Returns a new IOBufferMemoryDescriptor with a buffer large enough to - * hold capacity bytes. The descriptor's length is initially set to the - * capacity. - */ - static IOBufferMemoryDescriptor * withCapacity( - vm_size_t capacity, - IODirection withDirection, - bool withContiguousMemory = false); +/* + * withCapacity: + * + * Returns a new IOBufferMemoryDescriptor with a buffer large enough to + * hold capacity bytes. The descriptor's length is initially set to the + * capacity. + */ + static IOBufferMemoryDescriptor * withCapacity( + vm_size_t capacity, + IODirection withDirection, + bool withContiguousMemory = false); #ifndef __LP64__ - virtual bool initWithBytes(const void * bytes, - vm_size_t withLength, - IODirection withDirection, - bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */ + virtual bool initWithBytes(const void * bytes, + vm_size_t withLength, + IODirection withDirection, + bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */ #endif /* !__LP64__ */ - /* - * withBytes: - * - * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied). - * The descriptor's length and capacity are set to the input buffer's size. - */ - static IOBufferMemoryDescriptor * withBytes( - const void * bytes, - vm_size_t withLength, - IODirection withDirection, - bool withContiguousMemory = false); +/* + * withBytes: + * + * Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied). + * The descriptor's length and capacity are set to the input buffer's size. + */ + static IOBufferMemoryDescriptor * withBytes( + const void * bytes, + vm_size_t withLength, + IODirection withDirection, + bool withContiguousMemory = false); - /* - * setLength: - * - * Change the buffer length of the memory descriptor. When a new buffer - * is created, the initial length of the buffer is set to be the same as - * the capacity. The length can be adjusted via setLength for a shorter - * transfer (there is no need to create more buffer descriptors when you - * can reuse an existing one, even for different transfer sizes). Note - * that the specified length must not exceed the capacity of the buffer. - */ - virtual void setLength(vm_size_t length); +/* + * setLength: + * + * Change the buffer length of the memory descriptor. When a new buffer + * is created, the initial length of the buffer is set to be the same as + * the capacity. The length can be adjusted via setLength for a shorter + * transfer (there is no need to create more buffer descriptors when you + * can reuse an existing one, even for different transfer sizes). Note + * that the specified length must not exceed the capacity of the buffer. + */ + virtual void setLength(vm_size_t length); - /* - * setDirection: - * - * Change the direction of the transfer. This method allows one to redirect - * the descriptor's transfer direction. This eliminates the need to destroy - * and create new buffers when different transfer directions are needed. - */ - virtual void setDirection(IODirection direction); +/* + * setDirection: + * + * Change the direction of the transfer. This method allows one to redirect + * the descriptor's transfer direction. This eliminates the need to destroy + * and create new buffers when different transfer directions are needed. + */ + virtual void setDirection(IODirection direction); - /* - * getCapacity: - * - * Get the buffer capacity - */ - virtual vm_size_t getCapacity() const; +/* + * getCapacity: + * + * Get the buffer capacity + */ + virtual vm_size_t getCapacity() const; - /* - * getBytesNoCopy: - * - * Return the virtual address of the beginning of the buffer - */ - virtual void *getBytesNoCopy(); +/* + * getBytesNoCopy: + * + * Return the virtual address of the beginning of the buffer + */ + virtual void *getBytesNoCopy(); - /* - * getBytesNoCopy: - * - * Return the virtual address of an offset from the beginning of the buffer - */ - virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength); +/* + * getBytesNoCopy: + * + * Return the virtual address of an offset from the beginning of the buffer + */ + virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength); - /* - * appendBytes: - * - * Add some data to the end of the buffer. This method automatically - * maintains the memory descriptor buffer length. Note that appendBytes - * will not copy past the end of the memory descriptor's current capacity. - */ - virtual bool appendBytes(const void *bytes, vm_size_t withLength); +/* + * appendBytes: + * + * Add some data to the end of the buffer. This method automatically + * maintains the memory descriptor buffer length. Note that appendBytes + * will not copy past the end of the memory descriptor's current capacity. + */ + virtual bool appendBytes(const void *bytes, vm_size_t withLength); #ifndef __LP64__ - virtual void * getVirtualSegment(IOByteCount offset, - IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */ + virtual void * getVirtualSegment(IOByteCount offset, + IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */ #endif /* !__LP64__ */ };