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

/*
 * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * The contents of this file constitute Original Code as defined in and
 * are subject to the Apple Public Source License Version 1.1 (the
 * "License").  You may not use this file except in compliance with the
 * License.  Please obtain a copy of the License at
 * http://www.apple.com/publicsource and read it before using this file.
 * 
 * This 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 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 {
    kIOMemoryDirectionMask		= 0x0000000f,
    kIOMemoryPhysicallyContiguous	= 0x00000010,
    kIOMemoryPageable	      		= 0x00000020,
    kIOMemorySharingTypeMask		= 0x000f0000,
    kIOMemoryUnshared			= 0x00000000,
    kIOMemoryKernelUserShared		= 0x00010000,
};


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 { };

/*! @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:
    OSMetaClassDeclareReservedUnused(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);

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

    /*
     * getPhysicalSegment:
     *
     * Get the physical address of the buffer, relative to the current position.
     * If the current position is at the end of the buffer, a zero is returned.
     */
    virtual IOPhysicalAddress getPhysicalSegment(IOByteCount offset,
						 IOByteCount * length);    
};

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