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

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
 * 
 * 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. 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_LICENSE_HEADER_END@
 */
#ifndef _IOBUFFERMEMORYDESCRIPTOR_H
#define _IOBUFFERMEMORYDESCRIPTOR_H

#include <IOKit/IOMemoryDescriptor.h>

enum {
    kIOMemoryPhysicallyContiguous	= 0x00000010,
    kIOMemoryPageable	      		= 0x00000020,
    kIOMemorySharingTypeMask		= 0x000f0000,
    kIOMemoryUnshared			= 0x00000000,
    kIOMemoryKernelUserShared		= 0x00010000,
};

#define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_	1

class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
{
    OSDeclareDefaultStructors(IOBufferMemoryDescriptor);

protected:
/*! @struct ExpansionData
    @discussion This structure will be used to expand the capablilties of this class in the future.
    */    
    struct ExpansionData {
	vm_map_t	map;
    };

/*! @var reserved
    Reserved for future use.  (Internal use only)  */
    ExpansionData * reserved;

protected:
    void *               _buffer;
    vm_size_t            _capacity;
    vm_offset_t		 _alignment;
    IOOptionBits	 _options;
    IOPhysicalAddress *  _physAddrs;
    unsigned             _physSegCount;

private:
    virtual bool initWithOptions(
                               IOOptionBits options,
                               vm_size_t    capacity,
                               vm_offset_t  alignment,
			       task_t	    inTask);

    OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);
    OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);
    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();

    virtual bool initWithAddress( void *      address,       /* not supported */
                                  IOByteCount withLength,
                                  IODirection withDirection );

    virtual bool initWithAddress( vm_address_t address,      /* not supported */
                                  IOByteCount  withLength,
                                  IODirection  withDirection,
                                  task_t       withTask );

    virtual bool initWithPhysicalAddress( 
                                  IOPhysicalAddress address, /* not supported */
                                  IOByteCount       withLength,
                                  IODirection       withDirection );

    virtual bool initWithPhysicalRanges( 
                                  IOPhysicalRange * ranges,  /* not supported */
                                  UInt32            withCount,
                                  IODirection       withDirection,
                                  bool              asReference = false );

    virtual bool initWithRanges(  IOVirtualRange * ranges,   /* not supported */
                                  UInt32           withCount,
                                  IODirection      withDirection,
                                  task_t           withTask,
                                  bool             asReference = false );

    IOGeneralMemoryDescriptor::withAddress;                  /* not supported */
    IOGeneralMemoryDescriptor::withPhysicalAddress;          /* not supported */
    IOGeneralMemoryDescriptor::withPhysicalRanges;           /* not supported */
    IOGeneralMemoryDescriptor::withRanges;                   /* not supported */
    IOGeneralMemoryDescriptor::withSubRange;                 /* not supported */

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.
     */
    virtual bool initWithOptions(   IOOptionBits options,
                                    vm_size_t    capacity,
                                    vm_offset_t  alignment);

    static IOBufferMemoryDescriptor * withOptions(  IOOptionBits options,
                                                    vm_size_t    capacity,
                                                    vm_offset_t  alignment = 1);

/*! @function inTaskWithOptions
    @abstract Create a memory buffer with memory descriptor for that buffer. Added in Mac OS X 10.2.
    @discussion 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 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:
    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.
    kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
    @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 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);

    /*
     * 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);
    /*
     * initWithBytes:
     *
     * Initialize a new IOBufferMemoryDescriptor preloaded with bytes (copied).
     * The descriptor's length and capacity are set to the input buffer's size.
     */
    virtual bool initWithBytes(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);

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

#endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */
Commit	Line	Data
1c79356b A	1	/*
	2	* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_LICENSE_HEADER_START@
	5	*
d7e50217	6	* Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
1c79356b	7	*
d7e50217 A	8	* This file contains Original Code and/or Modifications of Original Code
	9	* as defined in and that are subject to the Apple Public Source License
	10	* Version 2.0 (the 'License'). You may not use this file except in
	11	* compliance with the License. Please obtain a copy of the License at
	12	* http://www.opensource.apple.com/apsl/ and read it before using this
	13	* file.
	14	*
	15	* The Original Code and all software distributed under the License are
	16	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
1c79356b A	17	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
1c79356b A	18	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
d7e50217 A	19	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
	20	* Please see the License for the specific language governing rights and
	21	* limitations under the License.
1c79356b A	22	*
	23	* @APPLE_LICENSE_HEADER_END@
	24	*/
	25	#ifndef _IOBUFFERMEMORYDESCRIPTOR_H
	26	#define _IOBUFFERMEMORYDESCRIPTOR_H
	27
	28	#include <IOKit/IOMemoryDescriptor.h>
	29
	30	enum {
1c79356b A	31	kIOMemoryPhysicallyContiguous = 0x00000010,
	32	kIOMemoryPageable = 0x00000020,
	33	kIOMemorySharingTypeMask = 0x000f0000,
	34	kIOMemoryUnshared = 0x00000000,
	35	kIOMemoryKernelUserShared = 0x00010000,
	36	};
	37
9bccf70c	38	#define _IOBUFFERMEMORYDESCRIPTOR_INTASKWITHOPTIONS_ 1
1c79356b A	39
	40	class IOBufferMemoryDescriptor : public IOGeneralMemoryDescriptor
	41	{
	42	OSDeclareDefaultStructors(IOBufferMemoryDescriptor);
	43
	44	protected:
	45	/*! @struct ExpansionData
	46	@discussion This structure will be used to expand the capablilties of this class in the future.
	47	*/
9bccf70c A	48	struct ExpansionData {
	49	vm_map_t map;
	50	};
1c79356b A	51
	52	/*! @var reserved
	53	Reserved for future use. (Internal use only) */
	54	ExpansionData * reserved;
	55
	56	protected:
	57	void * _buffer;
	58	vm_size_t _capacity;
	59	vm_offset_t _alignment;
	60	IOOptionBits _options;
	61	IOPhysicalAddress * _physAddrs;
	62	unsigned _physSegCount;
	63
	64	private:
9bccf70c A	65	virtual bool initWithOptions(
	66	IOOptionBits options,
	67	vm_size_t capacity,
	68	vm_offset_t alignment,
	69	task_t inTask);
	70
	71	OSMetaClassDeclareReservedUsed(IOBufferMemoryDescriptor, 0);
1c79356b A	72	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 1);
	73	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 2);
	74	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 3);
	75	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 4);
	76	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 5);
	77	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 6);
	78	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 7);
	79	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 8);
	80	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 9);
	81	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 10);
	82	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 11);
	83	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 12);
	84	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 13);
	85	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 14);
	86	OSMetaClassDeclareReservedUnused(IOBufferMemoryDescriptor, 15);
	87
	88	protected:
	89	virtual void free();
	90
	91	virtual bool initWithAddress( void * address, /* not supported */
	92	IOByteCount withLength,
	93	IODirection withDirection );
	94
	95	virtual bool initWithAddress( vm_address_t address, /* not supported */
	96	IOByteCount withLength,
	97	IODirection withDirection,
	98	task_t withTask );
	99
	100	virtual bool initWithPhysicalAddress(
	101	IOPhysicalAddress address, /* not supported */
	102	IOByteCount withLength,
	103	IODirection withDirection );
	104
	105	virtual bool initWithPhysicalRanges(
	106	IOPhysicalRange * ranges, /* not supported */
	107	UInt32 withCount,
	108	IODirection withDirection,
	109	bool asReference = false );
	110
	111	virtual bool initWithRanges( IOVirtualRange * ranges, /* not supported */
	112	UInt32 withCount,
	113	IODirection withDirection,
	114	task_t withTask,
	115	bool asReference = false );
	116
	117	IOGeneralMemoryDescriptor::withAddress; /* not supported */
	118	IOGeneralMemoryDescriptor::withPhysicalAddress; /* not supported */
	119	IOGeneralMemoryDescriptor::withPhysicalRanges; /* not supported */
	120	IOGeneralMemoryDescriptor::withRanges; /* not supported */
	121	IOGeneralMemoryDescriptor::withSubRange; /* not supported */
	122
	123	public:
	124
	125	/*
	126	* withOptions:
	127	*
	128	* Returns a new IOBufferMemoryDescriptor with a buffer large enough to
	129	* hold capacity bytes. The descriptor's length is initially set to the
	130	* capacity.
	131	*/
	132	virtual bool initWithOptions( IOOptionBits options,
	133	vm_size_t capacity,
	134	vm_offset_t alignment);
	135
136	static IOBufferMemoryDescriptor * withOptions( IOOptionBits options,
137	vm_size_t capacity,
138	vm_offset_t alignment = 1);
139
9bccf70c A	140	/*! @function inTaskWithOptions
	141	@abstract Create a memory buffer with memory descriptor for that buffer. Added in Mac OS X 10.2.
	142	@discussion 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 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.
	143	@param inTask The task the buffer will be allocated in.
	144	@param options Options for the allocation:
	145	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.
	146	kIOMemoryPageable - pass to request memory be non-wired - the default for kernel allocated memory is wired.
	147	kIOMemoryKernelUserShared - pass to request memory that will be mapped into both the kernel and client applications.
	148	@param capacity The number of bytes to allocate.
	149	@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.
	150	@result An instance of class IOBufferMemoryDescriptor. To be released by the caller, which will free the memory desriptor and associated buffer. */
	151
	152	static IOBufferMemoryDescriptor * inTaskWithOptions(
	153	task_t inTask,
	154	IOOptionBits options,
	155	vm_size_t capacity,
	156	vm_offset_t alignment = 1);
	157
1c79356b A	158	/*
	159	* withCapacity:
	160	*
	161	* Returns a new IOBufferMemoryDescriptor with a buffer large enough to
	162	* hold capacity bytes. The descriptor's length is initially set to the
	163	* capacity.
	164	*/
	165	static IOBufferMemoryDescriptor * withCapacity(
	166	vm_size_t capacity,
	167	IODirection withDirection,
	168	bool withContiguousMemory = false);
	169	/*
	170	* initWithBytes:
	171	*
	172	* Initialize a new IOBufferMemoryDescriptor preloaded with bytes (copied).
	173	* The descriptor's length and capacity are set to the input buffer's size.
	174	*/
	175	virtual bool initWithBytes(const void * bytes,
	176	vm_size_t withLength,
	177	IODirection withDirection,
	178	bool withContiguousMemory = false);
	179
	180	/*
	181	* withBytes:
	182	*
	183	* Returns a new IOBufferMemoryDescriptor preloaded with bytes (copied).
	184	* The descriptor's length and capacity are set to the input buffer's size.
	185	*/
	186	static IOBufferMemoryDescriptor * withBytes(
	187	const void * bytes,
	188	vm_size_t withLength,
	189	IODirection withDirection,
	190	bool withContiguousMemory = false);
	191
	192	/*
	193	* setLength:
	194	*
	195	* Change the buffer length of the memory descriptor. When a new buffer
	196	* is created, the initial length of the buffer is set to be the same as
	197	* the capacity. The length can be adjusted via setLength for a shorter
	198	* transfer (there is no need to create more buffer descriptors when you
	199	* can reuse an existing one, even for different transfer sizes). Note
	200	* that the specified length must not exceed the capacity of the buffer.
	201	*/
	202	virtual void setLength(vm_size_t length);
	203
	204	/*
	205	* setDirection:
	206	*
	207	* Change the direction of the transfer. This method allows one to redirect
	208	* the descriptor's transfer direction. This eliminates the need to destroy
	209	* and create new buffers when different transfer directions are needed.
	210	*/
	211	virtual void setDirection(IODirection direction);
	212
	213	/*
	214	* getCapacity:
	215	*
	216	* Get the buffer capacity
	217	*/
	218	virtual vm_size_t getCapacity() const;
	219
	220	/*
	221	* getBytesNoCopy:
222	*
223	* Return the virtual address of the beginning of the buffer
224	*/
225	virtual void *getBytesNoCopy();
226
227	/*
228	* getBytesNoCopy:
229	*
230	* Return the virtual address of an offset from the beginning of the buffer
231	*/
232	virtual void *getBytesNoCopy(vm_size_t start, vm_size_t withLength);
233
234	/*
235	* appendBytes:
236	*
237	* Add some data to the end of the buffer. This method automatically
238	* maintains the memory descriptor buffer length. Note that appendBytes
239	* will not copy past the end of the memory descriptor's current capacity.
240	*/
241	virtual bool appendBytes(const void *bytes, vm_size_t withLength);
1c79356b A	242	};
	243
	244	#endif /* !_IOBUFFERMEMORYDESCRIPTOR_H */