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 */
37enum {
38    kIOPCIConfigAGPStatusOffset  = 4,
39    kIOPCIConfigAGPCommandOffset = 8
40};
41
42/* Definitions of AGP Command & Status registers */
43enum {
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
54enum {
55    kIOAGPGartInvalidate        = 0x00000001
56};
57
58// getAGPStatus() defines
59enum {
60    kIOAGPDefaultStatus         = 0
61};
62enum {
63    kIOAGPIdle                  = 0x00000001,
64    kIOAGPInvalidGARTEntry      = 0x00000002,
65    kIOAGPAccessOutOfRange      = 0x00000004
66};
67
68#define kIOAGPBusFlagsKey       "IOAGPFlags"
69enum {
70    // the AGP target must be idle before invalidating its gart tlb
71    kIOAGPGartIdleInvalidate    = 0x00000001,
72
73    // the AGP target cannot handle operations that cross page boundaries
74    kIOAGPDisablePageSpans      = 0x00000002,
75
76    // the AGP target cannot handle master -> target AGP writes
77    kIOAGPDisableAGPWrites      = 0x00000004,
78
79    // the AGP target cannot handle target -> master PCI reads
80    kIOAGPDisablePCIReads       = 0x00000008,
81
82    // the AGP target cannot handle master -> target PCI writes
83    kIOAGPDisablePCIWrites      = 0x00000010,
84
85    // the AGP target cannot handle all unaligned transactions
86    kIOAGPDisableUnaligned      = 0x00000020,
87
88    kIOAGPDisableFeature6       = 0x00000040,
89    kIOAGPDisableFeature7       = 0x00000080,
90    kIOAGPDisableFeature8       = 0x00000100,
91    kIOAGPDisableFeature9       = 0x00000200
92};
93
94// masterState
95enum {
96    kIOAGPStateEnabled          = 0x00000001,
97    kIOAGPStateEnablePending    = 0x00010000
98};
99
100
101/*! @class IOAGPDevice
102    @abstract An IOService class representing an AGP master device.
103    @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.
104*/
105
106class IOAGPDevice : public IOPCIDevice
107{
108    OSDeclareDefaultStructors(IOAGPDevice)
109
110protected:
111
112/*! @struct ExpansionData
113    @discussion This structure will be used to expand the capablilties of the IOWorkLoop in the future.
114*/
115    struct ExpansionData { };
116
117/*! @var reserved
118    Reserved for future use.  (Internal use only)
119*/
120    ExpansionData *reserved;
121
122public:
123    UInt32      masterState;
124    UInt8       masterAGPRegisters;
125
126/*! @function createAGPSpace
127    @abstract Allocates the AGP space, and enables AGP transactions on the master and slave.
128    @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.
129    @param options No options are currently defined, pass zero.
130    @param address The physical range allocated for the AGP space is passed back to the caller.
131    @param length An in/out parameter - the caller sets the devices maximum AGP addressing and the actual size created is passed back.
132    @result Returns an IOReturn code indicating success or failure.
133*/
134
135    virtual IOReturn createAGPSpace( IOOptionBits options,
136                                    IOPhysicalAddress * address,
137                                    IOPhysicalLength * length );
138
139/*! @function destroyAGPSpace
140    @abstract Destroys the AGP space, and disables AGP transactions on the master and slave.
141    @discussion This method should be called by the driver to shutdown AGP transactions and release resources.
142*/
143
144    virtual IOReturn destroyAGPSpace( void );
145
146/*! @function getAGPRangeAllocator
147    @abstract Accessor to obtain the AGP range allocator.
148    @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.
149    @result Returns a pointer to the range allocator for the AGP space.
150*/
151
152    virtual IORangeAllocator * getAGPRangeAllocator( void );
153
154/*! @function getAGPStatus
155    @abstract Returns the current state of the AGP bus.
156    @discussion Returns state bits for the AGP bus. Only one type of status is currently defined.
157    @param which Type of status - only kIOAGPDefaultStatus is currently valid.
158    @result Returns mask of status bits for the AGP bus.
159*/
160
161    virtual IOOptionBits getAGPStatus( IOOptionBits which = kIOAGPDefaultStatus );
162
163/*! @function commitAGPMemory
164    @abstract Makes memory addressable by AGP transactions.
165    @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 caller's responsibility to prepare non-kernel pageable memory before calling this method, with IOMemoryDescriptor::prepare.
166    @param memory A IOMemoryDescriptor object describing the memory to add to the GART.
167    @param agpOffset An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.
168    @param options Pass kIOAGPGartInvalidate if the AGP target should invalidate any GART TLB.
169    @result Returns an IOReturn code indicating success or failure.
170*/
171
172    virtual IOReturn commitAGPMemory( IOMemoryDescriptor * memory,
173                                        IOByteCount agpOffset,
174                                        IOOptionBits options = 0 );
175
176/*! @function releaseAGPMemory
177    @abstract Releases memory addressable by AGP transactions.
178    @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 caller's responsibility to complete non-kernel pageable memory before calling this method, with IOMemoryDescriptor::complete.
179    @param memory A IOMemoryDescriptor object describing the memory to remove from the GART.
180    @param agpOffset An offset into AGP space that the caller has allocated - usually allocated by the AGP range allocator.
181    @param options Pass kIOAGPGartInvalidate if the AGP target should invalidate any GART TLB.
182    @result Returns an IOReturn code indicating success or failure.
183*/
184
185    virtual IOReturn releaseAGPMemory( IOMemoryDescriptor * memory,
186                                        IOByteCount agpOffset,
187                                        IOOptionBits options = 0 );
188
189    virtual IOReturn resetAGP( IOOptionBits options = 0 );
190
191/*! @function getAGPSpace
192    @abstract Returns the allocated AGP space.
193    @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.
194    @param address The physical range allocated for the AGP space is passed back to the caller. Zero may be passed if the address is not needed by the caller.
195    @param length The size of the the AGP space created is passed back.  Zero may be passed if the length is not needed by the caller.
196    @result Returns an IOReturn code indicating success or failure.
197*/
198
199    virtual IOReturn getAGPSpace( IOPhysicalAddress * address,
200                                    IOPhysicalLength * length );
201
202    // Unused Padding
203    OSMetaClassDeclareReservedUnused(IOAGPDevice,  0);
204    OSMetaClassDeclareReservedUnused(IOAGPDevice,  1);
205    OSMetaClassDeclareReservedUnused(IOAGPDevice,  2);
206    OSMetaClassDeclareReservedUnused(IOAGPDevice,  3);
207    OSMetaClassDeclareReservedUnused(IOAGPDevice,  4);
208    OSMetaClassDeclareReservedUnused(IOAGPDevice,  5);
209    OSMetaClassDeclareReservedUnused(IOAGPDevice,  6);
210    OSMetaClassDeclareReservedUnused(IOAGPDevice,  7);
211    OSMetaClassDeclareReservedUnused(IOAGPDevice,  8);
212    OSMetaClassDeclareReservedUnused(IOAGPDevice,  9);
213    OSMetaClassDeclareReservedUnused(IOAGPDevice, 10);
214    OSMetaClassDeclareReservedUnused(IOAGPDevice, 11);
215    OSMetaClassDeclareReservedUnused(IOAGPDevice, 12);
216    OSMetaClassDeclareReservedUnused(IOAGPDevice, 13);
217    OSMetaClassDeclareReservedUnused(IOAGPDevice, 14);
218    OSMetaClassDeclareReservedUnused(IOAGPDevice, 15);
219    OSMetaClassDeclareReservedUnused(IOAGPDevice, 16);
220};
221
222#endif /* ! _IOKIT_IOAGPDEVICE_H */
223