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

/*
 * Copyright (c) 1998-2000 Apple Computer, 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 _IOINTERLEAVEDMEMORYDESCRIPTOR_H
#define _IOINTERLEAVEDMEMORYDESCRIPTOR_H

#include <IOKit/IOMemoryDescriptor.h>

/*! @class IOInterleavedMemoryDescriptor : public IOMemoryDescriptor
    @abstract The IOInterleavedMemoryDescriptor object describes a memory area made up of portions of several other IOMemoryDescriptors.
    @discussion The IOInterleavedMemoryDescriptor object represents interleaved ranges of memory, specified as an ordered list of portions of individual IOMemoryDescriptors.  The portions are chained end-to-end to make up a single contiguous buffer. */

class IOInterleavedMemoryDescriptor : public IOMemoryDescriptor
{
    OSDeclareDefaultStructors(IOInterleavedMemoryDescriptor);

protected:

    UInt32                _descriptorCapacity;
    UInt32                _descriptorCount;
    IOMemoryDescriptor ** _descriptors;
    IOByteCount         * _descriptorOffsets;
    IOByteCount         * _descriptorLengths;
    bool                  _descriptorPrepared;

    virtual void free();

    /*
     * These methods are not supported under this subclass.
     */

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

    virtual void * getVirtualSegment( IOByteCount   offset,  /* not supported */
                                      IOByteCount * length );

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

public:

/*! @function withCapacity
    @abstract Create an IOInterleavedMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
    @discussion This method creates and initializes an IOInterleavedMemoryDescriptor for memory consisting of portions of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer.
    @param capacity The maximum number of IOMemoryDescriptors that may be subsequently added to this IOInterleavedMemoryDescriptor.
    @param direction An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
    @result The created IOInterleavedMemoryDescriptor on success, to be released by the caller, or zero on failure. */

    static IOInterleavedMemoryDescriptor * withCapacity( UInt32		       capacity,
                                                         IODirection           direction);

/*! @function initWithCapacity
    @abstract Initialize an IOInterleavedMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
    @discussion This method initializes an IOInterleavedMemoryDescriptor for memory consisting of portions of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer.
    @param capacity The maximum number of IOMemoryDescriptors that may be subsequently added to this IOInterleavedMemoryDescriptor.
    @param direction An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
    @result The created IOInterleavedMemoryDescriptor on success, to be released by the caller, or zero on failure. */

    virtual bool initWithCapacity( UInt32                capacity,
                                   IODirection           direction );

/*! @function clearMemoryDescriptors
    @abstract Clear all of the IOMemoryDescriptors currently contained in and reset the IOInterleavedMemoryDescriptor.
    @discussion Clears each IOMemoryDescriptor by completing (if needed) and releasing.  The IOInterleavedMemoryDescriptor is then reset and may accept new descriptors up to the capacity specified when it was created.
    @param direction An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures. */

    virtual void clearMemoryDescriptors( IODirection direction = kIODirectionNone );

/*! @function setMemoryDescriptor
    @abstract Add a portion of an IOMemoryDescriptor to the IOInterleavedMemoryDescriptor.
    @discussion This method adds the portion of an IOMemoryDescriptor described by the offset and length parameters to the end of the IOInterleavedMemoryDescriptor.  A single IOMemoryDescriptor may be added as many times as there is room for it.  The offset and length must describe a portion entirely within the IOMemoryDescriptor.
    @param descriptor An IOMemoryDescriptor to be added to the IOInterleavedMemoryDescriptor.  Its direction must be compatible with that of the IOInterleavedMemoryDescriptor.
    @param offset The offset into the IOMemoryDescriptor of the portion that will be added to the virtualized buffer.
    @param length The length of the portion of the IOMemoryDescriptor to be added to the virtualized buffer. 
    @result Returns true the portion was successfully added. */

    virtual bool setMemoryDescriptor( IOMemoryDescriptor * descriptor,
                                      IOByteCount offset,
                                      IOByteCount length );

/*! @function getPhysicalSegment
    @abstract Break a memory descriptor into its physically contiguous segments.
    @discussion This method returns the physical address of the byte at the given offset into the memory, and optionally the length of the physically contiguous segment from that offset.
    @param offset A byte offset into the memory whose physical address to return.
    @param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
    @result A physical address, or zero if the offset is beyond the length of the memory. */

    virtual IOPhysicalAddress getPhysicalSegment( IOByteCount   offset,
                                                  IOByteCount * length );

    virtual addr64_t getPhysicalSegment64(        IOByteCount   offset,
                                                  IOByteCount * length );

/*! @function prepare
    @abstract Prepare the memory for an I/O transfer.
    @discussion This involves paging in the memory, if necessary, and wiring it down for the duration of the transfer.  The complete() method completes the processing of the memory after the I/O transfer finishes.  This method need not called for non-pageable memory.
    @param forDirection The direction of the I/O to be performed, or kIODirectionNone for the direction specified by the memory descriptor.
    @result An IOReturn code. */

    virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);

/*! @function complete
    @abstract Complete processing of the memory after an I/O transfer finishes.
    @discussion This method should not be called unless a prepare was previously issued; the prepare() and complete() must occur in pairs, before and after an I/O transfer involving pageable memory.
    @param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
    @result An IOReturn code. */

    virtual IOReturn complete(IODirection forDirection = kIODirectionNone);

    virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
                                               IOByteCount * length);
};

#endif /* !_IOINTERLEAVEDMEMORYDESCRIPTOR_H */
Commit	Line	Data
2d21ac55 A	1	/*
	2	* Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
	3	*
	4	* @APPLE_OSREFERENCE_LICENSE_HEADER_START@
	5	*
	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.
	14	*
	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
	20	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
	21	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
	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.
	25	*
	26	* @APPLE_OSREFERENCE_LICENSE_HEADER_END@
	27	*/
	28
	29	#ifndef _IOINTERLEAVEDMEMORYDESCRIPTOR_H
	30	#define _IOINTERLEAVEDMEMORYDESCRIPTOR_H
	31
	32	#include <IOKit/IOMemoryDescriptor.h>
	33
	34	/*! @class IOInterleavedMemoryDescriptor : public IOMemoryDescriptor
	35	@abstract The IOInterleavedMemoryDescriptor object describes a memory area made up of portions of several other IOMemoryDescriptors.
	36	@discussion The IOInterleavedMemoryDescriptor object represents interleaved ranges of memory, specified as an ordered list of portions of individual IOMemoryDescriptors. The portions are chained end-to-end to make up a single contiguous buffer. */
	37
	38	class IOInterleavedMemoryDescriptor : public IOMemoryDescriptor
	39	{
	40	OSDeclareDefaultStructors(IOInterleavedMemoryDescriptor);
	41
	42	protected:
	43
	44	UInt32 _descriptorCapacity;
	45	UInt32 _descriptorCount;
	46	IOMemoryDescriptor ** _descriptors;
	47	IOByteCount * _descriptorOffsets;
	48	IOByteCount * _descriptorLengths;
	49	bool _descriptorPrepared;
	50
	51	virtual void free();
	52
	53	/*
	54	* These methods are not supported under this subclass.
	55	*/
	56
	57	virtual bool initWithAddress( void * address, /* not supported */
	58	IOByteCount withLength,
	59	IODirection withDirection );
	60
	61	virtual bool initWithAddress( vm_address_t address, /* not supported */
	62	IOByteCount withLength,
	63	IODirection withDirection,
	64	task_t withTask );
65
66	virtual bool initWithPhysicalAddress(
67	IOPhysicalAddress address, /* not supported */
68	IOByteCount withLength,
69	IODirection withDirection );
70
71	virtual bool initWithPhysicalRanges(
72	IOPhysicalRange * ranges, /* not supported */
73	UInt32 withCount,
74	IODirection withDirection,
75	bool asReference = false );
76
77	virtual bool initWithRanges( IOVirtualRange * ranges, /* not supported */
78	UInt32 withCount,
79	IODirection withDirection,
80	task_t withTask,
81	bool asReference = false );
82
83	virtual void * getVirtualSegment( IOByteCount offset, /* not supported */
84	IOByteCount * length );
85
86	IOMemoryDescriptor::withAddress; /* not supported */
87	IOMemoryDescriptor::withPhysicalAddress; /* not supported */
88	IOMemoryDescriptor::withPhysicalRanges; /* not supported */
89	IOMemoryDescriptor::withRanges; /* not supported */
90	IOMemoryDescriptor::withSubRange; /* not supported */
91
92	public:
93
94	/*! @function withCapacity
95	@abstract Create an IOInterleavedMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
96	@discussion This method creates and initializes an IOInterleavedMemoryDescriptor for memory consisting of portions of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer.
97	@param capacity The maximum number of IOMemoryDescriptors that may be subsequently added to this IOInterleavedMemoryDescriptor.
98	@param direction An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
99	@result The created IOInterleavedMemoryDescriptor on success, to be released by the caller, or zero on failure. */
100
101	static IOInterleavedMemoryDescriptor * withCapacity( UInt32 capacity,
102	IODirection direction);
103
104	/*! @function initWithCapacity
105	@abstract Initialize an IOInterleavedMemoryDescriptor to describe a memory area made up of several other IOMemoryDescriptors.
106	@discussion This method initializes an IOInterleavedMemoryDescriptor for memory consisting of portions of a number of other IOMemoryDescriptors, chained end-to-end (in the order they appear in the array) to represent a single contiguous memory buffer.
107	@param capacity The maximum number of IOMemoryDescriptors that may be subsequently added to this IOInterleavedMemoryDescriptor.
108	@param direction An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures.
109	@result The created IOInterleavedMemoryDescriptor on success, to be released by the caller, or zero on failure. */
110
111	virtual bool initWithCapacity( UInt32 capacity,
112	IODirection direction );
113
114	/*! @function clearMemoryDescriptors
115	@abstract Clear all of the IOMemoryDescriptors currently contained in and reset the IOInterleavedMemoryDescriptor.
116	@discussion Clears each IOMemoryDescriptor by completing (if needed) and releasing. The IOInterleavedMemoryDescriptor is then reset and may accept new descriptors up to the capacity specified when it was created.
117	@param direction An I/O direction to be associated with the descriptor, which may affect the operation of the prepare and complete methods on some architectures. */
118
119	virtual void clearMemoryDescriptors( IODirection direction = kIODirectionNone );
120
121	/*! @function setMemoryDescriptor
122	@abstract Add a portion of an IOMemoryDescriptor to the IOInterleavedMemoryDescriptor.
123	@discussion This method adds the portion of an IOMemoryDescriptor described by the offset and length parameters to the end of the IOInterleavedMemoryDescriptor. A single IOMemoryDescriptor may be added as many times as there is room for it. The offset and length must describe a portion entirely within the IOMemoryDescriptor.
124	@param descriptor An IOMemoryDescriptor to be added to the IOInterleavedMemoryDescriptor. Its direction must be compatible with that of the IOInterleavedMemoryDescriptor.
125	@param offset The offset into the IOMemoryDescriptor of the portion that will be added to the virtualized buffer.
126	@param length The length of the portion of the IOMemoryDescriptor to be added to the virtualized buffer.
127	@result Returns true the portion was successfully added. */
128
129	virtual bool setMemoryDescriptor( IOMemoryDescriptor * descriptor,
130	IOByteCount offset,
131	IOByteCount length );
132
133	/*! @function getPhysicalSegment
134	@abstract Break a memory descriptor into its physically contiguous segments.
135	@discussion This method returns the physical address of the byte at the given offset into the memory, and optionally the length of the physically contiguous segment from that offset.
136	@param offset A byte offset into the memory whose physical address to return.
137	@param length If non-zero, getPhysicalSegment will store here the length of the physically contiguous segement at the given offset.
138	@result A physical address, or zero if the offset is beyond the length of the memory. */
139
140	virtual IOPhysicalAddress getPhysicalSegment( IOByteCount offset,
141	IOByteCount * length );
142
143	virtual addr64_t getPhysicalSegment64( IOByteCount offset,
144	IOByteCount * length );
145
146	/*! @function prepare
147	@abstract Prepare the memory for an I/O transfer.
148	@discussion This involves paging in the memory, if necessary, and wiring it down for the duration of the transfer. The complete() method completes the processing of the memory after the I/O transfer finishes. This method need not called for non-pageable memory.
149	@param forDirection The direction of the I/O to be performed, or kIODirectionNone for the direction specified by the memory descriptor.
150	@result An IOReturn code. */
151
152	virtual IOReturn prepare(IODirection forDirection = kIODirectionNone);
153
154	/*! @function complete
155	@abstract Complete processing of the memory after an I/O transfer finishes.
156	@discussion This method should not be called unless a prepare was previously issued; the prepare() and complete() must occur in pairs, before and after an I/O transfer involving pageable memory.
157	@param forDirection The direction of the I/O just completed, or kIODirectionNone for the direction specified by the memory descriptor.
158	@result An IOReturn code. */
159
160	virtual IOReturn complete(IODirection forDirection = kIODirectionNone);
161
162	virtual IOPhysicalAddress getSourceSegment(IOByteCount offset,
163	IOByteCount * length);
164	};
165
166	#endif /* !_IOINTERLEAVEDMEMORYDESCRIPTOR_H */