[apple/xnu.git] / iokit / Kernel / IOMultiMemoryDescriptor.cpp

/*
 * 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@
 */

#include <IOKit/IOLib.h>
#include <IOKit/IOMultiMemoryDescriptor.h>

#define super IOMemoryDescriptor
OSDefineMetaClassAndStructors(IOMultiMemoryDescriptor, IOMemoryDescriptor)

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bool IOMultiMemoryDescriptor::initWithAddress(
                                  void *      /* address       */ ,
                                  IOByteCount /* withLength    */ ,
                                  IODirection /* withDirection */ )
{
    return false;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bool IOMultiMemoryDescriptor::initWithAddress(
                                  vm_address_t /* address       */ ,
                                  IOByteCount  /* withLength    */ ,
                                  IODirection  /* withDirection */ ,
                                  task_t       /* withTask      */ )
{
    return false;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bool IOMultiMemoryDescriptor::initWithPhysicalAddress(
                                  IOPhysicalAddress /* address       */ ,
                                  IOByteCount       /* withLength    */ ,
                                  IODirection       /* withDirection */ )
{
    return false;
}


// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bool IOMultiMemoryDescriptor::initWithPhysicalRanges(
                                  IOPhysicalRange * /* ranges        */ ,
                                  UInt32            /* withCount     */ ,
                                  IODirection       /* withDirection */ ,
                                  bool              /* asReference   */ )
{
    return false;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bool IOMultiMemoryDescriptor::initWithRanges(
                                  IOVirtualRange * /* ranges        */ ,
                                  UInt32           /* withCount     */ ,
                                  IODirection      /* withDirection */ ,
                                  task_t           /* withTask      */ ,
                                  bool             /* asReference   */ )
{
    return false;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

IOMultiMemoryDescriptor * IOMultiMemoryDescriptor::withDescriptors(
                                  IOMemoryDescriptor ** descriptors,
                                  UInt32                withCount,
                                  IODirection           withDirection,
                                  bool                  asReference = false )
{
    //
    // Create a new IOMultiMemoryDescriptor.  The "buffer" is made up of several
    // memory descriptors, that are to be chained end-to-end to make up a single
    // memory descriptor.
    //
    // Passing the ranges as a reference will avoid an extra allocation.
    //

    IOMultiMemoryDescriptor * me = new IOMultiMemoryDescriptor;
    
    if ( me && me->initWithDescriptors(
                                  /* descriptors   */ descriptors,
                                  /* withCount     */ withCount,
                                  /* withDirection */ withDirection,
                                  /* asReference   */ asReference ) == false )
    {
	    me->release();
	    me = 0;
    }

    return me;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

bool IOMultiMemoryDescriptor::initWithDescriptors(
                                  IOMemoryDescriptor ** descriptors,
                                  UInt32                withCount,
                                  IODirection           withDirection,
                                  bool                  asReference = false )
{
    //
    // Initialize an IOMultiMemoryDescriptor. The "buffer" is made up of several
    // memory descriptors, that are to be chained end-to-end to make up a single
    // memory descriptor.
    //
    // Passing the ranges as a reference will avoid an extra allocation.
    //

    assert(descriptors);
    assert(withCount);

    // Ask our superclass' opinion.

    if ( super::init() == false )  return false;

    // Initialize our minimal state.

    _descriptors            = 0;
    _descriptorsCount       = withCount;
    _descriptorsIsAllocated = asReference ? false : true;
    _direction              = withDirection;
    _length                 = 0;
    _mappings               = 0;
    _tag                    = 0;

    if ( asReference )
    {
        _descriptors = descriptors;
    }
    else
    {
        _descriptors = IONew(IOMemoryDescriptor *, withCount);
        if ( _descriptors == 0 )  return false;

        bcopy( /* from  */ descriptors,
               /* to    */ _descriptors,
               /* bytes */ withCount * sizeof(IOMemoryDescriptor *) );
    }

    for ( unsigned index = 0; index < withCount; index++ ) 
    {
        descriptors[index]->retain();
        _length += descriptors[index]->getLength();
        if ( _tag == 0 )  _tag = descriptors[index]->getTag();
        assert(descriptors[index]->getDirection() == withDirection);
    }

    return true;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

void IOMultiMemoryDescriptor::free()
{
    //
    // Free all of this object's outstanding resources.
    //

    if ( _descriptors )
    {
        for ( unsigned index = 0; index < _descriptorsCount; index++ ) 
            _descriptors[index]->release();

        if ( _descriptorsIsAllocated )
            IODelete(_descriptors, IOMemoryDescriptor *, _descriptorsCount);
    }

    super::free();
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

IOReturn IOMultiMemoryDescriptor::prepare(IODirection forDirection)
{
    //
    // Prepare the memory for an I/O transfer.
    //
    // This involves paging in the memory and wiring it down for the duration
    // of the transfer.  The complete() method finishes the processing of the
    // memory after the I/O transfer finishes.
    //

    unsigned index;
    IOReturn status = kIOReturnInternalError;
    IOReturn statusUndo;

    if ( forDirection == kIODirectionNone )
    {
        forDirection = _direction;
    }

    for ( index = 0; index < _descriptorsCount; index++ ) 
    {
        status = _descriptors[index]->prepare(forDirection);
        if ( status != kIOReturnSuccess )  break;
    }

    if ( status != kIOReturnSuccess )
    {
        for ( unsigned indexUndo = 0; indexUndo <= index; indexUndo++ )
        {
            statusUndo = _descriptors[index]->complete(forDirection);
            assert(statusUndo == kIOReturnSuccess);
        }
    }

    return status;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

IOReturn IOMultiMemoryDescriptor::complete(IODirection forDirection)
{
    //
    // Complete processing of the memory after an I/O transfer finishes.
    //
    // This method shouldn't be called unless a prepare() was previously issued;
    // the prepare() and complete() must occur in pairs, before and after an I/O
    // transfer.
    //

    IOReturn status;
    IOReturn statusFinal = kIOReturnSuccess;

    if ( forDirection == kIODirectionNone )
    {
        forDirection = _direction;
    }

    for ( unsigned index = 0; index < _descriptorsCount; index++ ) 
    {
        status = _descriptors[index]->complete(forDirection);
        if ( status != kIOReturnSuccess )  statusFinal = status;
        assert(status == kIOReturnSuccess);
    }

    return statusFinal;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

IOPhysicalAddress IOMultiMemoryDescriptor::getPhysicalSegment(
                                                       IOByteCount   offset,
                                                       IOByteCount * length )
{
    //
    // 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.
    //

    assert(offset <= _length);

    for ( unsigned index = 0; index < _descriptorsCount; index++ ) 
    {
        if ( offset < _descriptors[index]->getLength() )
        {
            return _descriptors[index]->getPhysicalSegment(offset, length);
        }
        offset -= _descriptors[index]->getLength();
    }

    if ( length )  *length = 0;

    return 0;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

void * IOMultiMemoryDescriptor::getVirtualSegment( IOByteCount   /* offset */ ,
                                                   IOByteCount * /* length */ )
{
    return 0;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

IOByteCount IOMultiMemoryDescriptor::readBytes( IOByteCount offset,
                                                void *      bytes,
                                                IOByteCount withLength )
{
    //
    // Copies data from the memory descriptor's buffer at the given offset, to
    // the specified buffer.  Returns the number of bytes copied.
    //

    IOByteCount bytesCopied = 0;
    unsigned    index;

    for ( index = 0; index < _descriptorsCount; index++ ) 
    {
        if ( offset < _descriptors[index]->getLength() )  break;
        offset -= _descriptors[index]->getLength();
    }

    for ( ; index < _descriptorsCount && withLength; index++)
    {
        IOByteCount copy   = min(_descriptors[index]->getLength(), withLength);
        IOByteCount copied = _descriptors[index]->readBytes(offset,bytes,copy);

        bytesCopied += copied;
        if ( copied != copy )  break;

        bytes = ((UInt8 *) bytes) + copied;
        withLength -= copied;
        offset = 0;
    }

    return bytesCopied;
}

// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

IOByteCount IOMultiMemoryDescriptor::writeBytes( IOByteCount  offset,
                                                 const void * bytes,
                                                 IOByteCount  withLength )
{
    //
    // Copies data to the memory descriptor's buffer at the given offset, from
    // the specified buffer.  Returns the number of bytes copied.
    //

    IOByteCount bytesCopied = 0;
    unsigned    index;

    for ( index = 0; index < _descriptorsCount; index++ ) 
    {
        if ( offset < _descriptors[index]->getLength() )  break;
        offset -= _descriptors[index]->getLength();
    }

    for ( ; index < _descriptorsCount && withLength; index++)
    {
        IOByteCount copy   = min(_descriptors[index]->getLength(), withLength);
        IOByteCount copied = _descriptors[index]->writeBytes(offset,bytes,copy);

        bytesCopied += copied;
        if ( copied != copy )  break;

        bytes = ((UInt8 *) bytes) + copied;
        withLength -= copied;
        offset = 0;
    }

    return bytesCopied;
}
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
	23	#include <IOKit/IOLib.h>
	24	#include <IOKit/IOMultiMemoryDescriptor.h>
	25
	26	#define super IOMemoryDescriptor
	27	OSDefineMetaClassAndStructors(IOMultiMemoryDescriptor, IOMemoryDescriptor)
	28
	29	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
	30
	31	bool IOMultiMemoryDescriptor::initWithAddress(
	32	void * /* address */ ,
	33	IOByteCount /* withLength */ ,
	34	IODirection /* withDirection */ )
	35	{
	36	return false;
	37	}
	38
	39	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
	40
	41	bool IOMultiMemoryDescriptor::initWithAddress(
	42	vm_address_t /* address */ ,
	43	IOByteCount /* withLength */ ,
	44	IODirection /* withDirection */ ,
	45	task_t /* withTask */ )
	46	{
	47	return false;
	48	}
	49
	50	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
	51
	52	bool IOMultiMemoryDescriptor::initWithPhysicalAddress(
	53	IOPhysicalAddress /* address */ ,
	54	IOByteCount /* withLength */ ,
	55	IODirection /* withDirection */ )
	56	{
	57	return false;
	58	}
	59
	60
	61	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
	62
	63	bool IOMultiMemoryDescriptor::initWithPhysicalRanges(
	64	IOPhysicalRange * /* ranges */ ,
65	UInt32 /* withCount */ ,
66	IODirection /* withDirection */ ,
67	bool /* asReference */ )
68	{
69	return false;
70	}
71
72	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
73
74	bool IOMultiMemoryDescriptor::initWithRanges(
75	IOVirtualRange * /* ranges */ ,
76	UInt32 /* withCount */ ,
77	IODirection /* withDirection */ ,
78	task_t /* withTask */ ,
79	bool /* asReference */ )
80	{
81	return false;
82	}
83
84	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
85
86	IOMultiMemoryDescriptor * IOMultiMemoryDescriptor::withDescriptors(
87	IOMemoryDescriptor ** descriptors,
88	UInt32 withCount,
89	IODirection withDirection,
90	bool asReference = false )
91	{
92	//
93	// Create a new IOMultiMemoryDescriptor. The "buffer" is made up of several
94	// memory descriptors, that are to be chained end-to-end to make up a single
95	// memory descriptor.
96	//
97	// Passing the ranges as a reference will avoid an extra allocation.
98	//
99
100	IOMultiMemoryDescriptor * me = new IOMultiMemoryDescriptor;
101
102	if ( me && me->initWithDescriptors(
103	/* descriptors */ descriptors,
104	/* withCount */ withCount,
105	/* withDirection */ withDirection,
106	/* asReference */ asReference ) == false )
107	{
108	me->release();
109	me = 0;
110	}
111
112	return me;
113	}
114
115	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
116
117	bool IOMultiMemoryDescriptor::initWithDescriptors(
118	IOMemoryDescriptor ** descriptors,
119	UInt32 withCount,
120	IODirection withDirection,
121	bool asReference = false )
122	{
123	//
124	// Initialize an IOMultiMemoryDescriptor. The "buffer" is made up of several
125	// memory descriptors, that are to be chained end-to-end to make up a single
126	// memory descriptor.
127	//
128	// Passing the ranges as a reference will avoid an extra allocation.
129	//
130
131	assert(descriptors);
132	assert(withCount);
133
134	// Ask our superclass' opinion.
135
136	if ( super::init() == false ) return false;
137
138	// Initialize our minimal state.
139
140	_descriptors = 0;
141	_descriptorsCount = withCount;
142	_descriptorsIsAllocated = asReference ? false : true;
143	_direction = withDirection;
144	_length = 0;
145	_mappings = 0;
146	_tag = 0;
147
148	if ( asReference )
149	{
150	_descriptors = descriptors;
151	}
152	else
153	{
154	_descriptors = IONew(IOMemoryDescriptor *, withCount);
155	if ( _descriptors == 0 ) return false;
156
157	bcopy( /* from */ descriptors,
158	/* to */ _descriptors,
159	/* bytes / withCount sizeof(IOMemoryDescriptor *) );
160	}
161
162	for ( unsigned index = 0; index < withCount; index++ )
163	{
164	descriptors[index]->retain();
165	_length += descriptors[index]->getLength();
166	if ( _tag == 0 ) _tag = descriptors[index]->getTag();
167	assert(descriptors[index]->getDirection() == withDirection);
168	}
169
170	return true;
171	}
172
173	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
174
175	void IOMultiMemoryDescriptor::free()
176	{
177	//
178	// Free all of this object's outstanding resources.
179	//
180
181	if ( _descriptors )
182	{
183	for ( unsigned index = 0; index < _descriptorsCount; index++ )
184	_descriptors[index]->release();
185
186	if ( _descriptorsIsAllocated )
187	IODelete(_descriptors, IOMemoryDescriptor *, _descriptorsCount);
188	}
189
190	super::free();
191	}
192
193	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
194
195	IOReturn IOMultiMemoryDescriptor::prepare(IODirection forDirection)
196	{
197	//
198	// Prepare the memory for an I/O transfer.
199	//
200	// This involves paging in the memory and wiring it down for the duration
201	// of the transfer. The complete() method finishes the processing of the
202	// memory after the I/O transfer finishes.
203	//
204
205	unsigned index;
206	IOReturn status = kIOReturnInternalError;
207	IOReturn statusUndo;
208
209	if ( forDirection == kIODirectionNone )
210	{
211	forDirection = _direction;
212	}
213
214	for ( index = 0; index < _descriptorsCount; index++ )
215	{
216	status = _descriptors[index]->prepare(forDirection);
217	if ( status != kIOReturnSuccess ) break;
218	}
219
220	if ( status != kIOReturnSuccess )
221	{
222	for ( unsigned indexUndo = 0; indexUndo <= index; indexUndo++ )
223	{
224	statusUndo = _descriptors[index]->complete(forDirection);
225	assert(statusUndo == kIOReturnSuccess);
226	}
227	}
228
229	return status;
230	}
231
232	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
233
234	IOReturn IOMultiMemoryDescriptor::complete(IODirection forDirection)
235	{
236	//
237	// Complete processing of the memory after an I/O transfer finishes.
238	//
239	// This method shouldn't be called unless a prepare() was previously issued;
240	// the prepare() and complete() must occur in pairs, before and after an I/O
241	// transfer.
242	//
243
244	IOReturn status;
245	IOReturn statusFinal = kIOReturnSuccess;
246
247	if ( forDirection == kIODirectionNone )
248	{
249	forDirection = _direction;
250	}
251
252	for ( unsigned index = 0; index < _descriptorsCount; index++ )
253	{
254	status = _descriptors[index]->complete(forDirection);
255	if ( status != kIOReturnSuccess ) statusFinal = status;
256	assert(status == kIOReturnSuccess);
257	}
258
259	return statusFinal;
260	}
261
262	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
263
264	IOPhysicalAddress IOMultiMemoryDescriptor::getPhysicalSegment(
265	IOByteCount offset,
266	IOByteCount * length )
267	{
268	//
269	// This method returns the physical address of the byte at the given offset
270	// into the memory, and optionally the length of the physically contiguous
271	// segment from that offset.
272	//
273
274	assert(offset <= _length);
275
276	for ( unsigned index = 0; index < _descriptorsCount; index++ )
277	{
278	if ( offset < _descriptors[index]->getLength() )
279	{
280	return _descriptors[index]->getPhysicalSegment(offset, length);
281	}
282	offset -= _descriptors[index]->getLength();
283	}
284
285	if ( length ) *length = 0;
286
287	return 0;
288	}
289
290	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
291
292	void * IOMultiMemoryDescriptor::getVirtualSegment( IOByteCount /* offset */ ,
293	IOByteCount * /* length */ )
294	{
295	return 0;
296	}
297
298	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
299
300	IOByteCount IOMultiMemoryDescriptor::readBytes( IOByteCount offset,
301	void * bytes,
302	IOByteCount withLength )
303	{
304	//
305	// Copies data from the memory descriptor's buffer at the given offset, to
306	// the specified buffer. Returns the number of bytes copied.
307	//
308
309	IOByteCount bytesCopied = 0;
310	unsigned index;
311
312	for ( index = 0; index < _descriptorsCount; index++ )
313	{
314	if ( offset < _descriptors[index]->getLength() ) break;
315	offset -= _descriptors[index]->getLength();
316	}
317
318	for ( ; index < _descriptorsCount && withLength; index++)
319	{
320	IOByteCount copy = min(_descriptors[index]->getLength(), withLength);
321	IOByteCount copied = _descriptors[index]->readBytes(offset,bytes,copy);
322
323	bytesCopied += copied;
324	if ( copied != copy ) break;
325
326	bytes = ((UInt8 *) bytes) + copied;
327	withLength -= copied;
328	offset = 0;
329	}
330
331	return bytesCopied;
332	}
333
334	// - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
335
336	IOByteCount IOMultiMemoryDescriptor::writeBytes( IOByteCount offset,
337	const void * bytes,
338	IOByteCount withLength )
339	{
340	//
341	// Copies data to the memory descriptor's buffer at the given offset, from
342	// the specified buffer. Returns the number of bytes copied.
343	//
344
345	IOByteCount bytesCopied = 0;
346	unsigned index;
347
348	for ( index = 0; index < _descriptorsCount; index++ )
349	{
350	if ( offset < _descriptors[index]->getLength() ) break;
351	offset -= _descriptors[index]->getLength();
352	}
353
354	for ( ; index < _descriptorsCount && withLength; index++)
355	{
356	IOByteCount copy = min(_descriptors[index]->getLength(), withLength);
357	IOByteCount copied = _descriptors[index]->writeBytes(offset,bytes,copy);
358
359	bytesCopied += copied;
360	if ( copied != copy ) break;
361
362	bytes = ((UInt8 *) bytes) + copied;
363	withLength -= copied;
364	offset = 0;
365	}
366
367	return bytesCopied;
368	}