[apple/xnu.git] / iokit / IOKit / IOBufferMemoryDescriptor.h

/*
 * 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
 * compliance with the License. The rights granted to you under the License
 * may not be used to create, or enable the creation or redistribution of,
 * 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,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * 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
#define _IOBUFFERMEMORYDESCRIPTOR_H

#include <IOKit/IOMemoryDescriptor.h>

enum {
    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
#endif
					| kIOMemoryThreadSafe
					| kIOMemoryClearEncrypt
					| kIOMemoryMapperNone
					| kIOMemoryUseReserve
};

#define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_		1
#define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_	1
/*!
    @class IOBufferMemoryDescriptor
    @abstract Provides a simple memory descriptor that allocates its own buffer memory.
*/

class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
{
    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;
    };

/*! @var 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;
private:
    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 */
#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);

#ifdef __LP64__
    OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0);
    OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);
#else /* !__LP64__ */
    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);

protected:
    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.
     */
#ifndef __LP64__
    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);

/*! @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:<br>
    kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
    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.<br>
    kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br>
    kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br>
    kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br>
    kIOMapInhibitCache - allocate memory with inhibited cache setting. <br>		
    kIOMapWriteThruCache - allocate memory with writethru cache setting. <br>		
    kIOMapCopybackCache - allocate memory with copyback cache setting. <br>		
    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);

/*! @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:<br>
    kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
    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.<br>
    kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br>
    kIOMapInhibitCache - allocate memory with inhibited cache setting. <br>		
    kIOMapWriteThruCache - allocate memory with writethru cache setting. <br>		
    kIOMapCopybackCache - allocate memory with copyback cache setting. <br>		
    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);

    /*
     * 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 */
#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);

    /*
     * 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);

    /*
     * 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 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);

#ifndef __LP64__
    virtual void * getVirtualSegment(IOByteCount offset,
					IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */
#endif /* !__LP64__ */
};

#endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */
Commit	Line	Data
1c79356b	1	/*
39037602	2	* Copyright (c) 1998-2016 Apple Inc. All rights reserved.
1c79356b	3	*
2d21ac55	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
1c79356b	5	*
2d21ac55 A	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.
8f6c56a5	14	*
2d21ac55 A	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
8f6c56a5 A	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
8f6c56a5 A	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
2d21ac55 A	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.
8f6c56a5	25	*
2d21ac55	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
1c79356b A	27	*/
	28	#ifndef _IOBUFFERMEMORYDESCRIPTOR_H
	29	#define _IOBUFFERMEMORYDESCRIPTOR_H
	30
	31	#include <IOKit/IOMemoryDescriptor.h>
	32
	33	enum {
1c79356b A	34	kIOMemoryPhysicallyContiguous = 0x00000010,
1c79356b A	35	kIOMemoryPageable = 0x00000020,
91447636	36	kIOMemoryPurgeable = 0x00000040,
99c3a104	37	kIOMemoryHostPhysicallyContiguous = 0x00000080,
1c79356b A	38	kIOMemorySharingTypeMask = 0x000f0000,
1c79356b A	39	kIOMemoryUnshared = 0x00000000,
c910b4d9 A	40	kIOMemoryKernelUserShared = 0x00010000,
	41	// shared IOMemoryDescriptor options for IOBufferMemoryDescriptor:
	42	kIOBufferDescriptorMemoryFlags = kIOMemoryDirectionMask
	43	#ifdef XNU_KERNEL_PRIVATE
	44	\| kIOMemoryAutoPrepare
	45	#endif
	46	\| kIOMemoryThreadSafe
0b4c1975	47	\| kIOMemoryClearEncrypt
99c3a104	48	\| kIOMemoryMapperNone
39037602	49	\| kIOMemoryUseReserve
1c79356b A	50	};
1c79356b A	51
99c3a104 A	52	#define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1
99c3a104 A	53	#define _IOBUFFERMEMORYDESCRIPTOR_HOSTPHYSICALLYCONTIGUOUS_ 1
91447636 A	54	/*!
	55	@class IOBufferMemoryDescriptor
	56	@abstract Provides a simple memory descriptor that allocates its own buffer memory.
	57	*/
1c79356b A	58
	59	class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
	60	{
	61	OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
	62
2d21ac55	63	private:
1c79356b A	64	/*! @struct ExpansionData
	65	@discussion This structure will be used to expand the capablilties of this class in the future.
	66	*/
9bccf70c	67	struct ExpansionData {
2d21ac55	68	IOMemoryMap * map;
9bccf70c	69	};
1c79356b A	70
	71	/*! @var reserved
	72	Reserved for future use. (Internal use only) */
a39ff7e2	73	APPLE_KEXT_WSHADOW_PUSH;
1c79356b A	74	ExpansionData * reserved;
	75
	76	protected:
	77	void * _buffer;
	78	vm_size_t _capacity;
	79	vm_offset_t _alignment;
	80	IOOptionBits _options;
b0d623f7 A	81	private:
	82	uintptr_t _internalReserved;
	83	unsigned _internalFlags;
a39ff7e2	84	APPLE_KEXT_WSHADOW_POP;
1c79356b A	85
1c79356b A	86	private:
b0d623f7	87	#ifndef __LP64__
9bccf70c A	88	virtual bool initWithOptions(
	89	IOOptionBits options,
	90	vm_size_t capacity,
	91	vm_offset_t alignment,
b0d623f7 A	92	task_t inTask) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */
b0d623f7 A	93	#endif /* !__LP64__ */
0c530ab8	94
6d2010ae	95	public:
0c530ab8 A	96	virtual bool initWithPhysicalMask(
	97	task_t inTask,
	98	IOOptionBits options,
	99	mach_vm_size_t capacity,
	100	mach_vm_address_t alignment,
	101	mach_vm_address_t physicalMask);
2d21ac55	102
b0d623f7 A	103	#ifdef __LP64__
	104	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 0);
	105	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);
	106	#else /* !__LP64__ */
2d21ac55	107	OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);
0c530ab8	108	OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 1);
b0d623f7	109	#endif /* !__LP64__ */
1c79356b A	110	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);
	111	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);
	112	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);
	113	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5);
	114	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6);
	115	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7);
	116	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8);
	117	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9);
	118	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10);
	119	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11);
	120	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12);
	121	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13);
	122	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14);
	123	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15);
	124
	125	protected:
3e170ce0	126	virtual void free() APPLE_KEXT_OVERRIDE;
1c79356b	127
1c79356b A	128	public:
	129
	130	/*
	131	* withOptions:
	132	*
	133	* Returns a new IOBufferMemoryDescriptor with a buffer large enough to
	134	* hold capacity bytes. The descriptor's length is initially set to the
	135	* capacity.
	136	*/
b0d623f7	137	#ifndef __LP64__
1c79356b A	138	virtual bool initWithOptions( IOOptionBits options,
1c79356b A	139	vm_size_t capacity,
b0d623f7 A	140	vm_offset_t alignment) APPLE_KEXT_DEPRECATED; /* use withOptions() instead */
b0d623f7 A	141	#endif /* !__LP64__ */
1c79356b A	142
	143	static IOBufferMemoryDescriptor * withOptions( IOOptionBits options,
	144	vm_size_t capacity,
	145	vm_offset_t alignment = 1);
	146
9bccf70c	147	/*! @function inTaskWithOptions
91447636 A	148	@abstract Creates a memory buffer with memory descriptor for that buffer.
91447636 A	149	@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.
9bccf70c	150	@param inTask The task the buffer will be allocated in.
91447636	151	@param options Options for the allocation:<br>
0c530ab8	152	kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
91447636 A	153	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.<br>
	154	kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.<br>
	155	kIOMemoryPurgeable - pass to request memory that may later have its purgeable state set with IOMemoryDescriptor::setPurgeable. Only supported for kIOMemoryPageable allocations.<br>
6d2010ae A	156	kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br>
	157	kIOMapInhibitCache - allocate memory with inhibited cache setting. <br>
	158	kIOMapWriteThruCache - allocate memory with writethru cache setting. <br>
	159	kIOMapCopybackCache - allocate memory with copyback cache setting. <br>
	160	kIOMapWriteCombineCache - allocate memory with writecombined cache setting.
9bccf70c A	161	@param capacity The number of bytes to allocate.
9bccf70c A	162	@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.
91447636	163	@result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */
9bccf70c A	164
	165	static IOBufferMemoryDescriptor * inTaskWithOptions(
	166	task_t inTask,
	167	IOOptionBits options,
	168	vm_size_t capacity,
	169	vm_offset_t alignment = 1);
	170
0c530ab8 A	171	/*! @function inTaskWithPhysicalMask
	172	@abstract Creates a memory buffer with memory descriptor for that buffer.
	173	@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.
	174	@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).
	175	@param options Options for the allocation:<br>
	176	kIODirectionOut, kIODirectionIn - set the direction of the I/O transfer.<br>
	177	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.<br>
6d2010ae A	178	kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.<br>
	179	kIOMapInhibitCache - allocate memory with inhibited cache setting. <br>
	180	kIOMapWriteThruCache - allocate memory with writethru cache setting. <br>
	181	kIOMapCopybackCache - allocate memory with copyback cache setting. <br>
	182	kIOMapWriteCombineCache - allocate memory with writecombined cache setting.
0c530ab8	183	@param capacity The number of bytes to allocate.
39037602	184	@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.
0c530ab8 A	185	@result Returns an instance of class IOBufferMemoryDescriptor to be released by the caller, which will free the memory desriptor and associated buffer. */
	186
	187	static IOBufferMemoryDescriptor * inTaskWithPhysicalMask(
	188	task_t inTask,
	189	IOOptionBits options,
	190	mach_vm_size_t capacity,
	191	mach_vm_address_t physicalMask);
0c530ab8	192
1c79356b A	193	/*
	194	* withCapacity:
	195	*
	196	* Returns a new IOBufferMemoryDescriptor with a buffer large enough to
	197	* hold capacity bytes. The descriptor's length is initially set to the
	198	* capacity.
	199	*/
	200	static IOBufferMemoryDescriptor * withCapacity(
	201	vm_size_t capacity,
	202	IODirection withDirection,
	203	bool withContiguousMemory = false);
b0d623f7	204	#ifndef __LP64__
1c79356b A	205	virtual bool initWithBytes(const void * bytes,
	206	vm_size_t withLength,
	207	IODirection withDirection,
b0d623f7 A	208	bool withContiguousMemory = false) APPLE_KEXT_DEPRECATED; /* use withBytes() instead */
b0d623f7 A	209	#endif /* !__LP64__ */
1c79356b A	210
	211	/*
	212	* withBytes:
	213	*
	214	* Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).
	215	* The descriptor's length and capacity are set to the input buffer's size.
	216	*/
	217	static IOBufferMemoryDescriptor * withBytes(
	218	const void * bytes,
	219	vm_size_t withLength,
	220	IODirection withDirection,
	221	bool withContiguousMemory = false);
	222
	223	/*
	224	* setLength:
	225	*
	226	* Change the buffer length of the memory descriptor. When a new buffer
	227	* is created, the initial length of the buffer is set to be the same as
	228	* the capacity. The length can be adjusted via setLength for a shorter
	229	* transfer (there is no need to create more buffer descriptors when you
	230	* can reuse an existing one, even for different transfer sizes). Note
	231	* that the specified length must not exceed the capacity of the buffer.
	232	*/
	233	virtual void setLength(vm_size_t length);
	234
	235	/*
	236	* setDirection:
	237	*
	238	* Change the direction of the transfer. This method allows one to redirect
	239	* the descriptor's transfer direction. This eliminates the need to destroy
	240	* and create new buffers when different transfer directions are needed.
	241	*/
	242	virtual void setDirection(IODirection direction);
	243
	244	/*
	245	* getCapacity:
	246	*
	247	* Get the buffer capacity
	248	*/
	249	virtual vm_size_t getCapacity() const;
	250
	251	/*
	252	* getBytesNoCopy:
	253	*
	254	* Return the virtual address of the beginning of the buffer
	255	*/
	256	virtual void *getBytesNoCopy();
	257
	258	/*
	259	* getBytesNoCopy:
	260	*
	261	* Return the virtual address of an offset from the beginning of the buffer
	262	*/
	263	virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);
	264
	265	/*
	266	* appendBytes:
	267	*
	268	* Add some data to the end of the buffer. This method automatically
	269	* maintains the memory descriptor buffer length. Note that appendBytes
	270	* will not copy past the end of the memory descriptor's current capacity.
	271	*/
	272	virtual bool appendBytes(const void *bytes, vm_size_t withLength);
0c530ab8	273
b0d623f7 A	274	#ifndef __LP64__
b0d623f7 A	275	virtual void * getVirtualSegment(IOByteCount offset,
3e170ce0	276	IOByteCount * length) APPLE_KEXT_OVERRIDE APPLE_KEXT_DEPRECATED; /* use getBytesNoCopy() instead */
b0d623f7	277	#endif /* !__LP64__ */
1c79356b A	278	};
	279
	280	#endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */