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


#ifndef _IOKIT_IOAGPDEVICE_H
#define _IOKIT_IOAGPDEVICE_H

#include <IOKit/IORangeAllocator.h>
#include <IOKit/pci/IOPCIDevice.h>

/* Definitions of AGP config registers */
enum {
    kIOPCIConfigAGPStatusOffset	 = 4,
    kIOPCIConfigAGPCommandOffset = 8
};

/* Definitions of AGP Command & Status registers */
enum {
    kIOAGPRequestQueueMask	= 0xff000000,
    kIOAGPSideBandAddresssing	= 0x00000200,
    kIOAGPEnable		= 0x00000100,
    kIOAGP4GbAddressing		= 0x00000020,
    kIOAGPFastWrite		= 0x00000010,
    kIOAGP4xDataRate		= 0x00000004,
    kIOAGP2xDataRate		= 0x00000002,
    kIOAGP1xDataRate		= 0x00000001
};

enum {
    kIOAGPGartInvalidate	= 0x00000001
};

// getAGPStatus() defines
enum {
    kIOAGPDefaultStatus		= 0
};
enum {
    kIOAGPIdle			= 0x00000001,
    kIOAGPInvalidGARTEntry	= 0x00000002,
    kIOAGPAccessOutOfRange	= 0x00000004
};

#define kIOAGPBusFlagsKey	"IOAGPFlags"
enum {
    kIOAGPGartIdleInvalidate	= 0x00000001
};

// masterState
enum {
    kIOAGPStateEnabled		= 0x00000001,
    kIOAGPStateEnablePending	= 0x00010000
};


/*! @class IOAGPDevice : public IOPCIDevice
    @abstract An IOService class representing an AGP master device.
    @discussion The discovery of an AGP master device by the PCI bus family results in an instance of the IOAGPDevice being created and published. It provides services specific to AGP, in addition to the PCI services supplied by its superclass IOPCIDevice. */

class IOAGPDevice : public IOPCIDevice
{
    OSDeclareDefaultStructors(IOAGPDevice)

protected:

/*! @struct ExpansionData
    @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
    */    
    struct ExpansionData { };

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

public:
    UInt32	masterState;
    UInt8	masterAGPRegisters;

/*! @function createAGPSpace
    @abstract Allocates the AGP space, and enables AGP transactions on the master and slave.
    @discussion This method should be called by the driver for the AGP master device  to set the size of the space and enable AGP transactions. It will destroy any AGP space currently allocated.
    @param options No options are currently defined, pass zero.
    @param address The physical range allocated for the AGP space is passed back to the caller.
    @param length An in/out parameter - the caller sets the devices maximum AGP addressing and the actual size created is passed back.
    @result An IOReturn code indicating success or failure. */

    virtual IOReturn createAGPSpace( IOOptionBits options,
				    IOPhysicalAddress * address, 
				    IOPhysicalLength * length );

/*! @function destroyAGPSpace
    @abstract Destroys the AGP space, and disables AGP transactions on the master and slave.
    @discussion This method should be called by the driver to shutdown AGP transactions and release resources. */

    virtual IOReturn destroyAGPSpace( void );

/*! @function getAGPRangeAllocator
    @abstract Accessor to obtain the AGP range allocator.
    @discussion To allocate ranges in AGP space, obtain a range allocator for the space with this method. It is retained while the space is created (until destroyAGPSpace is called) and should not be released by the caller.
    @result A pointer to the range allocator for the AGP space. */

    virtual IORangeAllocator * getAGPRangeAllocator( void );

/*! @function getAGPStatus
    @abstract Returns the current state of the AGP bus.
    @discussion Returns state bits for the AGP bus. Only one type of status is currently defined. 
    @param which Type of status - only kIOAGPDefaultStatus is currently valid.
    @result Mask of status bits for the AGP bus. */

    virtual IOOptionBits getAGPStatus( IOOptionBits which = kIOAGPDefaultStatus );

/*! @function commitAGPMemory
    @abstract Makes memory addressable by AGP transactions.
    @discussion Makes the memory described by the IOMemoryDescriptor object addressable by AGP by entering its pages into the GART array, given an offset into AGP space supplied by the caller (usually allocated by the AGP range allocator). It  is the callers responsibility to prepare non-kernel pageable memory before calling this method, with IOMemoryDescriptor::prepare.
    @param memory A IOMemoryDescriptor object describing the memory to add to the GART.
    @param agpOffset An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.
    @param options Pass kIOAGPGartInvalidate if the AGP target should invalidate any GART TLB.
    @result An IOReturn code indicating success or failure. */

    virtual IOReturn commitAGPMemory( IOMemoryDescriptor * memory,
					IOByteCount agpOffset,
					IOOptionBits options = 0 );

/*! @function releaseAGPMemory
    @abstract Releases memory addressable by AGP transactions.
    @discussion Makes the memory described by the IOMemoryDescriptor object unaddressable by AGP by removing its pages from the GART array, given an offset into AGP space supplied by the caller (usually allocated by the AGP range allocator). It  is the callers responsibility to complete non-kernel pageable memory before calling this method, with IOMemoryDescriptor::complete.
    @param memory A IOMemoryDescriptor object describing the memory to remove from the GART.
    @param agpOffset An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.
    @param options Pass kIOAGPGartInvalidate if the AGP target should invalidate any GART TLB.
    @result An IOReturn code indicating success or failure. */

    virtual IOReturn releaseAGPMemory( IOMemoryDescriptor * memory, 
					IOByteCount agpOffset,
					IOOptionBits options = 0 );

    virtual IOReturn resetAGP( IOOptionBits options = 0 );

/*! @function getAGPSpace
    @abstract Returns the allocated AGP space.
    @discussion This method can be called by the driver for the AGP master device to retrieve the physical address and size of the space created with createAGPSpace.
    @param address The physical range allocated for the AGP space is passed back to the caller. Zero may be pased if the address is not needed by the caller.
    @param length The size of the the AGP space created is passed back. Zero may be pased if the length is not needed by the caller.
    @result An IOReturn code indicating success or failure. */

    virtual IOReturn getAGPSpace( IOPhysicalAddress * address, 
				    IOPhysicalLength * length );

    // Unused Padding
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  0);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  1);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  2);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  3);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  4);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  5);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  6);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  7);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  8);
    OSMetaClassDeclareReservedUnused(IOAGPDevice,  9);
    OSMetaClassDeclareReservedUnused(IOAGPDevice, 10);
    OSMetaClassDeclareReservedUnused(IOAGPDevice, 11);
    OSMetaClassDeclareReservedUnused(IOAGPDevice, 12);
    OSMetaClassDeclareReservedUnused(IOAGPDevice, 13);
    OSMetaClassDeclareReservedUnused(IOAGPDevice, 14);
    OSMetaClassDeclareReservedUnused(IOAGPDevice, 15);
    OSMetaClassDeclareReservedUnused(IOAGPDevice, 16);
};

#endif /* ! _IOKIT_IOAGPDEVICE_H */
Commit	Line	Data
de355530 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	* Copyright (c) 1999 Apple Computer, Inc. All rights reserved.
	24	*
	25	* HISTORY
	26	*
	27	*/
	28
	29
	30	#ifndef _IOKIT_IOAGPDEVICE_H
	31	#define _IOKIT_IOAGPDEVICE_H
	32
	33	#include <IOKit/IORangeAllocator.h>
	34	#include <IOKit/pci/IOPCIDevice.h>
	35
	36	/* Definitions of AGP config registers */
	37	enum {
	38	kIOPCIConfigAGPStatusOffset = 4,
	39	kIOPCIConfigAGPCommandOffset = 8
	40	};
	41
	42	/* Definitions of AGP Command & Status registers */
	43	enum {
	44	kIOAGPRequestQueueMask = 0xff000000,
	45	kIOAGPSideBandAddresssing = 0x00000200,
	46	kIOAGPEnable = 0x00000100,
	47	kIOAGP4GbAddressing = 0x00000020,
	48	kIOAGPFastWrite = 0x00000010,
	49	kIOAGP4xDataRate = 0x00000004,
	50	kIOAGP2xDataRate = 0x00000002,
	51	kIOAGP1xDataRate = 0x00000001
	52	};
	53
	54	enum {
	55	kIOAGPGartInvalidate = 0x00000001
	56	};
	57
	58	// getAGPStatus() defines
	59	enum {
	60	kIOAGPDefaultStatus = 0
	61	};
	62	enum {
	63	kIOAGPIdle = 0x00000001,
	64	kIOAGPInvalidGARTEntry = 0x00000002,
65	kIOAGPAccessOutOfRange = 0x00000004
66	};
67
68	#define kIOAGPBusFlagsKey "IOAGPFlags"
69	enum {
70	kIOAGPGartIdleInvalidate = 0x00000001
71	};
72
73	// masterState
74	enum {
75	kIOAGPStateEnabled = 0x00000001,
76	kIOAGPStateEnablePending = 0x00010000
77	};
78
79
80	/*! @class IOAGPDevice : public IOPCIDevice
81	@abstract An IOService class representing an AGP master device.
82	@discussion The discovery of an AGP master device by the PCI bus family results in an instance of the IOAGPDevice being created and published. It provides services specific to AGP, in addition to the PCI services supplied by its superclass IOPCIDevice. */
83
84	class IOAGPDevice : public IOPCIDevice
85	{
86	OSDeclareDefaultStructors(IOAGPDevice)
87
88	protected:
89
90	/*! @struct ExpansionData
91	@discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
92	*/
93	struct ExpansionData { };
94
95	/*! @var reserved
96	Reserved for future use. (Internal use only) */
97	ExpansionData *reserved;
98
99	public:
100	UInt32 masterState;
101	UInt8 masterAGPRegisters;
102
103	/*! @function createAGPSpace
104	@abstract Allocates the AGP space, and enables AGP transactions on the master and slave.
105	@discussion This method should be called by the driver for the AGP master device to set the size of the space and enable AGP transactions. It will destroy any AGP space currently allocated.
106	@param options No options are currently defined, pass zero.
107	@param address The physical range allocated for the AGP space is passed back to the caller.
108	@param length An in/out parameter - the caller sets the devices maximum AGP addressing and the actual size created is passed back.
109	@result An IOReturn code indicating success or failure. */
110
111	virtual IOReturn createAGPSpace( IOOptionBits options,
112	IOPhysicalAddress * address,
113	IOPhysicalLength * length );
114
115	/*! @function destroyAGPSpace
116	@abstract Destroys the AGP space, and disables AGP transactions on the master and slave.
117	@discussion This method should be called by the driver to shutdown AGP transactions and release resources. */
118
119	virtual IOReturn destroyAGPSpace( void );
120
121	/*! @function getAGPRangeAllocator
122	@abstract Accessor to obtain the AGP range allocator.
123	@discussion To allocate ranges in AGP space, obtain a range allocator for the space with this method. It is retained while the space is created (until destroyAGPSpace is called) and should not be released by the caller.
124	@result A pointer to the range allocator for the AGP space. */
125
126	virtual IORangeAllocator * getAGPRangeAllocator( void );
127
128	/*! @function getAGPStatus
129	@abstract Returns the current state of the AGP bus.
130	@discussion Returns state bits for the AGP bus. Only one type of status is currently defined.
131	@param which Type of status - only kIOAGPDefaultStatus is currently valid.
132	@result Mask of status bits for the AGP bus. */
133
134	virtual IOOptionBits getAGPStatus( IOOptionBits which = kIOAGPDefaultStatus );
135
136	/*! @function commitAGPMemory
137	@abstract Makes memory addressable by AGP transactions.
138	@discussion Makes the memory described by the IOMemoryDescriptor object addressable by AGP by entering its pages into the GART array, given an offset into AGP space supplied by the caller (usually allocated by the AGP range allocator). It is the callers responsibility to prepare non-kernel pageable memory before calling this method, with IOMemoryDescriptor::prepare.
139	@param memory A IOMemoryDescriptor object describing the memory to add to the GART.
140	@param agpOffset An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.
141	@param options Pass kIOAGPGartInvalidate if the AGP target should invalidate any GART TLB.
142	@result An IOReturn code indicating success or failure. */
143
144	virtual IOReturn commitAGPMemory( IOMemoryDescriptor * memory,
145	IOByteCount agpOffset,
146	IOOptionBits options = 0 );
147
148	/*! @function releaseAGPMemory
149	@abstract Releases memory addressable by AGP transactions.
150	@discussion Makes the memory described by the IOMemoryDescriptor object unaddressable by AGP by removing its pages from the GART array, given an offset into AGP space supplied by the caller (usually allocated by the AGP range allocator). It is the callers responsibility to complete non-kernel pageable memory before calling this method, with IOMemoryDescriptor::complete.
151	@param memory A IOMemoryDescriptor object describing the memory to remove from the GART.
152	@param agpOffset An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.
153	@param options Pass kIOAGPGartInvalidate if the AGP target should invalidate any GART TLB.
154	@result An IOReturn code indicating success or failure. */
155
156	virtual IOReturn releaseAGPMemory( IOMemoryDescriptor * memory,
157	IOByteCount agpOffset,
158	IOOptionBits options = 0 );
159
160	virtual IOReturn resetAGP( IOOptionBits options = 0 );
161
162	/*! @function getAGPSpace
163	@abstract Returns the allocated AGP space.
164	@discussion This method can be called by the driver for the AGP master device to retrieve the physical address and size of the space created with createAGPSpace.
165	@param address The physical range allocated for the AGP space is passed back to the caller. Zero may be pased if the address is not needed by the caller.
166	@param length The size of the the AGP space created is passed back. Zero may be pased if the length is not needed by the caller.
167	@result An IOReturn code indicating success or failure. */
168
169	virtual IOReturn getAGPSpace( IOPhysicalAddress * address,
170	IOPhysicalLength * length );
171
172	// Unused Padding
173	OSMetaClassDeclareReservedUnused(IOAGPDevice, 0);
174	OSMetaClassDeclareReservedUnused(IOAGPDevice, 1);
175	OSMetaClassDeclareReservedUnused(IOAGPDevice, 2);
176	OSMetaClassDeclareReservedUnused(IOAGPDevice, 3);
177	OSMetaClassDeclareReservedUnused(IOAGPDevice, 4);
178	OSMetaClassDeclareReservedUnused(IOAGPDevice, 5);
179	OSMetaClassDeclareReservedUnused(IOAGPDevice, 6);
180	OSMetaClassDeclareReservedUnused(IOAGPDevice, 7);
181	OSMetaClassDeclareReservedUnused(IOAGPDevice, 8);
182	OSMetaClassDeclareReservedUnused(IOAGPDevice, 9);
183	OSMetaClassDeclareReservedUnused(IOAGPDevice, 10);
184	OSMetaClassDeclareReservedUnused(IOAGPDevice, 11);
185	OSMetaClassDeclareReservedUnused(IOAGPDevice, 12);
186	OSMetaClassDeclareReservedUnused(IOAGPDevice, 13);
187	OSMetaClassDeclareReservedUnused(IOAGPDevice, 14);
188	OSMetaClassDeclareReservedUnused(IOAGPDevice, 15);
189	OSMetaClassDeclareReservedUnused(IOAGPDevice, 16);
190	};
191
192	#endif /* ! _IOKIT_IOAGPDEVICE_H */