[apple/xnu.git] / iokit / IOKit / IODeviceMemory.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@
 */
/*
 * Copyright (c) 1998 Apple Computer, Inc.  All rights reserved. 
 *
 * HISTORY
 *
 */

#ifndef _IOKIT_IODEVICEMEMORY_H
#define _IOKIT_IODEVICEMEMORY_H

#include <IOKit/IOMemoryDescriptor.h>

/*! @class IODeviceMemory : public IOMemoryDescriptor
    @abstract An IOMemoryDescriptor used for device physical memory ranges.
    @discussion The IODeviceMemory class is a simple subclass of IOMemoryDescriptor that uses its methods to describe a single range of physical memory on a device. IODeviceMemory objects are usually looked up with IOService or IOPCIDevice accessors, and are created by memory mapped bus families. IODeviceMemory implements only some factory methods in addition to the methods of IOMemoryDescriptor. */

class IODeviceMemory : public IOMemoryDescriptor
{
    OSDeclareDefaultStructors(IODeviceMemory)

public:

/*! @struct InitElement
    @field start First physical address in the range.
    @field length Length of the range.
    @field tag 32-bit value not interpreted by IODeviceMemory or IOMemoryDescriptor, for use by the bus family. */

    struct InitElement {
        IOPhysicalAddress	start;
        IOPhysicalLength	length;
        IOOptionBits 		tag;
    };

/*! @function arrayFromList
    @abstract Constructs an OSArray of IODeviceMemory instances, each describing one physical range, and a tag value.
    @discussion This method creates IODeviceMemory instances for each physical range passed in a IODeviceMemory::InitElement array. Each element consists of a physical address, length and tag value for the IODeviceMemory. The instances are returned as a created OSArray.
    @param list An array of IODeviceMemory::InitElement structures.
    @param count The number of elements in the list.
    @result A created OSArray of IODeviceMemory objects, to be released by the caller, or zero on failure. */

    static OSArray *		arrayFromList(
	InitElement		list[],
	IOItemCount		count );

/*! @function withRange
    @abstract Constructs an IODeviceMemory instance, describing one physical range.
    @discussion This method creates IODeviceMemory instance for one physical range passed as a physical address and length. It just calls IOMemoryDescriptor::withPhysicalAddress.
    @param address The physical address of the first byte in the memory.
    @param withLength The length of memory.
    @result The created IODeviceMemory on success, to be released by the caller, or zero on failure. */

    static IODeviceMemory *	withRange( 
	IOPhysicalAddress	start,
	IOPhysicalLength	length );

/*! @function withRange
    @abstract Constructs an IODeviceMemory instance, describing a subset of an existing IODeviceMemory range.
    @discussion This method creates IODeviceMemory instance for a subset of an existing IODeviceMemory range, passed as a physical address offset and length. It just calls IOMemoryDescriptor::withSubRange.
    @param of The parent IODeviceMemory of which a subrange is to be used for the new descriptor, which will be retained by the subrange IODeviceMemory.
    @param offset A byte offset into the parent's memory.
    @param length The length of the subrange.
    @result The created IODeviceMemory on success, to be released by the caller, or zero on failure. */

    static IODeviceMemory *	withSubRange( 
	IODeviceMemory *	of,
	IOPhysicalAddress	offset,
	IOPhysicalLength	length );
};

#endif /* ! _IOKIT_IODEVICEMEMORY_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	*
43866e37	6	* Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved.
1c79356b	7	*
43866e37 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,
43866e37 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	/*
	26	* Copyright (c) 1998 Apple Computer, Inc. All rights reserved.
	27	*
	28	* HISTORY
	29	*
	30	*/
	31
	32	#ifndef _IOKIT_IODEVICEMEMORY_H
	33	#define _IOKIT_IODEVICEMEMORY_H
	34
	35	#include <IOKit/IOMemoryDescriptor.h>
	36
	37	/*! @class IODeviceMemory : public IOMemoryDescriptor
	38	@abstract An IOMemoryDescriptor used for device physical memory ranges.
	39	@discussion The IODeviceMemory class is a simple subclass of IOMemoryDescriptor that uses its methods to describe a single range of physical memory on a device. IODeviceMemory objects are usually looked up with IOService or IOPCIDevice accessors, and are created by memory mapped bus families. IODeviceMemory implements only some factory methods in addition to the methods of IOMemoryDescriptor. */
	40
	41	class IODeviceMemory : public IOMemoryDescriptor
	42	{
	43	OSDeclareDefaultStructors(IODeviceMemory)
	44
	45	public:
	46
	47	/*! @struct InitElement
	48	@field start First physical address in the range.
	49	@field length Length of the range.
	50	@field tag 32-bit value not interpreted by IODeviceMemory or IOMemoryDescriptor, for use by the bus family. */
	51
	52	struct InitElement {
	53	IOPhysicalAddress start;
	54	IOPhysicalLength length;
	55	IOOptionBits tag;
	56	};
	57
	58	/*! @function arrayFromList
	59	@abstract Constructs an OSArray of IODeviceMemory instances, each describing one physical range, and a tag value.
	60	@discussion This method creates IODeviceMemory instances for each physical range passed in a IODeviceMemory::InitElement array. Each element consists of a physical address, length and tag value for the IODeviceMemory. The instances are returned as a created OSArray.
	61	@param list An array of IODeviceMemory::InitElement structures.
	62	@param count The number of elements in the list.
	63	@result A created OSArray of IODeviceMemory objects, to be released by the caller, or zero on failure. */
	64
	65	static OSArray * arrayFromList(
	66	InitElement list[],
	67	IOItemCount count );
	68
	69	/*! @function withRange
	70	@abstract Constructs an IODeviceMemory instance, describing one physical range.
	71	@discussion This method creates IODeviceMemory instance for one physical range passed as a physical address and length. It just calls IOMemoryDescriptor::withPhysicalAddress.
	72	@param address The physical address of the first byte in the memory.
	73	@param withLength The length of memory.
	74	@result The created IODeviceMemory on success, to be released by the caller, or zero on failure. */
	75
	76	static IODeviceMemory * withRange(
	77	IOPhysicalAddress start,
	78	IOPhysicalLength length );
	79
	80	/*! @function withRange
	81	@abstract Constructs an IODeviceMemory instance, describing a subset of an existing IODeviceMemory range.
	82	@discussion This method creates IODeviceMemory instance for a subset of an existing IODeviceMemory range, passed as a physical address offset and length. It just calls IOMemoryDescriptor::withSubRange.
	83	@param of The parent IODeviceMemory of which a subrange is to be used for the new descriptor, which will be retained by the subrange IODeviceMemory.
	84	@param offset A byte offset into the parent's memory.
	85	@param length The length of the subrange.
86	@result The created IODeviceMemory on success, to be released by the caller, or zero on failure. */
87
88	static IODeviceMemory * withSubRange(
89	IODeviceMemory * of,
90	IOPhysicalAddress offset,
91	IOPhysicalLength length );
92	};
93
94	#endif /* ! _IOKIT_IODEVICEMEMORY_H */