Grammatical and disclaimer changes (does not follow internal C coding stds.)
[mirror_edk2.git] / IntelFrameworkModulePkg / Include / Protocol / IsaAcpi.h
1 /** @file
2 EFI ISA ACPI Protocol is used to enumerate and manage all the ISA controllers on
3 the platform's ISA Bus.
4
5 Copyright (c) 2006 - 2010, Intel Corporation. All rights reserved<BR>
6 This program and the accompanying materials are licensed and made available under
7 the terms and conditions of the BSD License that accompanies this distribution.
8 The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php.
10
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
13
14 **/
15
16 #ifndef __ISA_ACPI_H_
17 #define __ISA_ACPI_H_
18
19 ///
20 /// Global ID for the EFI ISA ACPI Protocol.
21 ///
22 #define EFI_ISA_ACPI_PROTOCOL_GUID \
23 { \
24 0x64a892dc, 0x5561, 0x4536, { 0x92, 0xc7, 0x79, 0x9b, 0xfc, 0x18, 0x33, 0x55 } \
25 }
26
27 ///
28 /// Forward declaration fo the EFI ISA ACPI Protocol
29 ///
30 typedef struct _EFI_ISA_ACPI_PROTOCOL EFI_ISA_ACPI_PROTOCOL;
31
32 ///
33 /// ISA ACPI Protocol interrupt resource attributes.
34 ///
35 #define EFI_ISA_ACPI_IRQ_TYPE_HIGH_TRUE_EDGE_SENSITIVE 0x01 ///< Edge triggered interrupt on a rising edge.
36 #define EFI_ISA_ACPI_IRQ_TYPE_LOW_TRUE_EDGE_SENSITIVE 0x02 ///< Edge triggered interrupt on a falling edge.
37 #define EFI_ISA_ACPI_IRQ_TYPE_HIGH_TRUE_LEVEL_SENSITIVE 0x04 ///< Level sensitive interrupt active high.
38 #define EFI_ISA_ACPI_IRQ_TYPE_LOW_TRUE_LEVEL_SENSITIVE 0x08 ///< Level sensitive interrupt active low.
39
40 ///
41 /// ISA ACPI Protocol DMA resource attributes.
42 ///
43 #define EFI_ISA_ACPI_DMA_SPEED_TYPE_MASK 0x03 ///< Bit mask of supported DMA speed attributes.
44 #define EFI_ISA_ACPI_DMA_SPEED_TYPE_COMPATIBILITY 0x00 ///< ISA controller supports compatibility mode DMA transfers.
45 #define EFI_ISA_ACPI_DMA_SPEED_TYPE_A 0x01 ///< ISA controller supports type A DMA transfers.
46 #define EFI_ISA_ACPI_DMA_SPEED_TYPE_B 0x02 ///< ISA controller supports type B DMA transfers.
47 #define EFI_ISA_ACPI_DMA_SPEED_TYPE_F 0x03 ///< ISA controller supports type F DMA transfers.
48 #define EFI_ISA_ACPI_DMA_COUNT_BY_BYTE 0x04 ///< ISA controller increments DMA address by bytes (8-bit).
49 #define EFI_ISA_ACPI_DMA_COUNT_BY_WORD 0x08 ///< ISA controller increments DMA address by words (16-bit).
50 #define EFI_ISA_ACPI_DMA_BUS_MASTER 0x10 ///< ISA controller is a DMA bus master.
51 #define EFI_ISA_ACPI_DMA_TRANSFER_TYPE_8_BIT 0x20 ///< ISA controller only supports 8-bit DMA transfers.
52 #define EFI_ISA_ACPI_DMA_TRANSFER_TYPE_8_BIT_AND_16_BIT 0x40 ///< ISA controller both 8-bit and 16-bit DMA transfers.
53 #define EFI_ISA_ACPI_DMA_TRANSFER_TYPE_16_BIT 0x80 ///< ISA controller only supports 16-bit DMA transfers.
54
55 ///
56 /// ISA ACPI Protocol MMIO resource attributes
57 ///
58 #define EFI_ISA_ACPI_MEMORY_WIDTH_MASK 0x03 ///< Bit mask of supported ISA memory width attributes.
59 #define EFI_ISA_ACPI_MEMORY_WIDTH_8_BIT 0x00 ///< ISA MMIO region only supports 8-bit access.
60 #define EFI_ISA_ACPI_MEMORY_WIDTH_16_BIT 0x01 ///< ISA MMIO region only supports 16-bit access.
61 #define EFI_ISA_ACPI_MEMORY_WIDTH_8_BIT_AND_16_BIT 0x02 ///< ISA MMIO region supports both 8-bit and 16-bit access.
62 #define EFI_ISA_ACPI_MEMORY_WRITEABLE 0x04 ///< ISA MMIO region supports write transactions.
63 #define EFI_ISA_ACPI_MEMORY_CACHEABLE 0x08 ///< ISA MMIO region supports being cached.
64 #define EFI_ISA_ACPI_MEMORY_SHADOWABLE 0x10 ///< ISA MMIO region may be shadowed.
65 #define EFI_ISA_ACPI_MEMORY_EXPANSION_ROM 0x20 ///< ISA MMIO region is an expansion ROM.
66
67 ///
68 /// ISA ACPI Protocol I/O resource attributes
69 ///
70 #define EFI_ISA_ACPI_IO_DECODE_10_BITS 0x01 ///< ISA controllers uses a 10-bit address decoder for I/O cycles.
71 #define EFI_ISA_ACPI_IO_DECODE_16_BITS 0x02 ///< ISA controllers uses a 16-bit address decoder for I/O cycles.
72
73 ///
74 /// EFI ISA ACPI resource type
75 ///
76 typedef enum {
77 EfiIsaAcpiResourceEndOfList, ///< Marks the end if a resource list.
78 EfiIsaAcpiResourceIo, ///< ISA I/O port resource range.
79 EfiIsaAcpiResourceMemory, ///< ISA MMIO resource range.
80 EfiIsaAcpiResourceDma, ///< ISA DMA resource.
81 EfiIsaAcpiResourceInterrupt ///< ISA interrupt resource.
82 } EFI_ISA_ACPI_RESOURCE_TYPE;
83
84 ///
85 /// EFI ISA ACPI generic resource structure
86 ///
87 typedef struct {
88 EFI_ISA_ACPI_RESOURCE_TYPE Type; ///< The type of resource (I/O, MMIO, DMA, Interrupt).
89 UINT32 Attribute; ///< Bit mask of attributes associated with this resource. See EFI_ISA_ACPI_xxx macros for valid combinations.
90 UINT32 StartRange; ///< The start of the resource range.
91 UINT32 EndRange; ///< The end of the resource range.
92 } EFI_ISA_ACPI_RESOURCE;
93
94 ///
95 /// EFI ISA ACPI resource device identifier
96 ///
97 typedef struct {
98 UINT32 HID; ///< The ACPI Hardware Identifier value associated with an ISA controller. Matchs ACPI DSDT contents.
99 UINT32 UID; ///< The ACPI Unique Identifier value associated with an ISA controller. Matches ACPI DSDT contents.
100 } EFI_ISA_ACPI_DEVICE_ID;
101
102 ///
103 /// EFI ISA ACPI resource list
104 ///
105 typedef struct {
106 EFI_ISA_ACPI_DEVICE_ID Device; ///< The ACPI HID/UID associated with an ISA controller.
107 EFI_ISA_ACPI_RESOURCE *ResourceItem; ///< A pointer to the list of resources associated with an ISA controller.
108 } EFI_ISA_ACPI_RESOURCE_LIST;
109
110 /**
111 Enumerates the ISA controllers on an ISA bus.
112
113 This service allows all the ISA controllers on an ISA bus to be enumerated. If
114 Device is a pointer to a NULL value, then the first ISA controller on the ISA
115 bus is returned in Device and EFI_SUCCESS is returned. If Device is a pointer
116 to a value that was returned on a prior call to DeviceEnumerate(), then the next
117 ISA controller on the ISA bus is returned in Device and EFI_SUCCESS is returned.
118 If Device is a pointer to the last ISA controller on the ISA bus, then
119 EFI_NOT_FOUND is returned.
120
121 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
122 @param[out] Device The pointer to an ISA controller named by ACPI HID/UID.
123
124 @retval EFI_SUCCESS The next ISA controller on the ISA bus was returned.
125 @retval EFI_NOT_FOUND No device found.
126
127 **/
128 typedef
129 EFI_STATUS
130 (EFIAPI *EFI_ISA_ACPI_DEVICE_ENUMERATE)(
131 IN EFI_ISA_ACPI_PROTOCOL *This,
132 OUT EFI_ISA_ACPI_DEVICE_ID **Device
133 );
134
135 /**
136 Sets the power state of an ISA controller.
137
138 This services sets the power state of the ISA controller specified by Device to
139 the power state specified by OnOff. TRUE denotes on, FALSE denotes off.
140 If the power state is sucessfully set on the ISA Controller, then
141 EFI_SUCCESS is returned.
142
143 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
144 @param[in] Device The pointer to an ISA controller named by ACPI HID/UID.
145 @param[in] OnOff TRUE denotes on, FALSE denotes off.
146
147 @retval EFI_SUCCESS Successfully set the power state of the ISA controller.
148 @retval Other The ISA controller could not be placed in the requested power state.
149
150 **/
151 typedef
152 EFI_STATUS
153 (EFIAPI *EFI_ISA_ACPI_SET_DEVICE_POWER)(
154 IN EFI_ISA_ACPI_PROTOCOL *This,
155 IN EFI_ISA_ACPI_DEVICE_ID *Device,
156 IN BOOLEAN OnOff
157 );
158
159 /**
160 Retrieves the current set of resources associated with an ISA controller.
161
162 Retrieves the set of I/O, MMIO, DMA, and interrupt resources currently
163 assigned to the ISA controller specified by Device. These resources
164 are returned in ResourceList.
165
166 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
167 @param[in] Device The pointer to an ISA controller named by ACPI HID/UID.
168 @param[out] ResourceList The pointer to the current resource list for Device.
169
170 @retval EFI_SUCCESS Successfully retrieved the current resource list.
171 @retval EFI_NOT_FOUND The resource list could not be retrieved.
172
173 **/
174 typedef
175 EFI_STATUS
176 (EFIAPI *EFI_ISA_ACPI_GET_CUR_RESOURCE)(
177 IN EFI_ISA_ACPI_PROTOCOL *This,
178 IN EFI_ISA_ACPI_DEVICE_ID *Device,
179 OUT EFI_ISA_ACPI_RESOURCE_LIST **ResourceList
180 );
181
182 /**
183 Retrieves the set of possible resources that may be assigned to an ISA controller
184 with SetResource().
185
186 Retrieves the possible sets of I/O, MMIO, DMA, and interrupt resources for the
187 ISA controller specified by Device. The sets are returned in ResourceList.
188
189 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
190 @param[in] Device The pointer to an ISA controller named by ACPI HID/UID.
191 @param[out] ResourceList The pointer to the returned list of resource lists.
192
193 @retval EFI_UNSUPPORTED This service is not supported.
194
195 **/
196 typedef
197 EFI_STATUS
198 (EFIAPI *EFI_ISA_ACPI_GET_POS_RESOURCE)(
199 IN EFI_ISA_ACPI_PROTOCOL *This,
200 IN EFI_ISA_ACPI_DEVICE_ID *Device,
201 OUT EFI_ISA_ACPI_RESOURCE_LIST **ResourceList
202 );
203
204 /**
205 Assigns resources to an ISA controller.
206
207 Assigns the I/O, MMIO, DMA, and interrupt resources specified by ResourceList
208 to the ISA controller specified by Device. ResourceList must match a resource list returned by GetPosResource() for the same ISA controller.
209
210 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
211 @param[in] Device The pointer to an ISA controller named by ACPI HID/UID.
212 @param[in] ResourceList The pointer to a resources list that must be one of the
213 resource lists returned by GetPosResource() for the
214 ISA controller specified by Device.
215
216 @retval EFI_SUCCESS Successfully set resources on the ISA controller.
217 @retval Other The resources could not be set for the ISA controller.
218
219 **/
220 typedef
221 EFI_STATUS
222 (EFIAPI *EFI_ISA_ACPI_SET_RESOURCE)(
223 IN EFI_ISA_ACPI_PROTOCOL *This,
224 IN EFI_ISA_ACPI_DEVICE_ID *Device,
225 IN EFI_ISA_ACPI_RESOURCE_LIST *ResourceList
226 );
227
228 /**
229 Enables or disables an ISA controller.
230
231 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
232 @param[in] Device The pointer to the ISA controller to enable/disable.
233 @param[in] Enable TRUE to enable the ISA controller. FALSE to disable the
234 ISA controller.
235
236 @retval EFI_SUCCESS Successfully enabled/disabled the ISA controller.
237 @retval Other The ISA controller could not be placed in the requested state.
238
239 **/
240 typedef
241 EFI_STATUS
242 (EFIAPI *EFI_ISA_ACPI_ENABLE_DEVICE)(
243 IN EFI_ISA_ACPI_PROTOCOL *This,
244 IN EFI_ISA_ACPI_DEVICE_ID *Device,
245 IN BOOLEAN Enable
246 );
247
248 /**
249 Initializes an ISA controller, so that it can be used. This service must be called
250 before SetResource(), EnableDevice(), or SetPower() will behave as expected.
251
252 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
253 @param[in] Device The pointer to an ISA controller named by ACPI HID/UID.
254
255 @retval EFI_SUCCESS Successfully initialized an ISA controller.
256 @retval Other The ISA controller could not be initialized.
257
258 **/
259 typedef
260 EFI_STATUS
261 (EFIAPI *EFI_ISA_ACPI_INIT_DEVICE)(
262 IN EFI_ISA_ACPI_PROTOCOL *This,
263 IN EFI_ISA_ACPI_DEVICE_ID *Device
264 );
265
266 /**
267 Initializes all the HW states required for the ISA controllers on the ISA bus
268 to be enumerated and managed by the rest of the services in this prorotol.
269 This service must be called before any of the other services in this
270 protocol will function as expected.
271
272 @param[in] This The pointer to the EFI_ISA_ACPI_PROTOCOL instance.
273
274 @retval EFI_SUCCESS Successfully initialized all required hardware states.
275 @retval Other The ISA interface could not be initialized.
276
277 **/
278 typedef
279 EFI_STATUS
280 (EFIAPI *EFI_ISA_ACPI_INTERFACE_INIT)(
281 IN EFI_ISA_ACPI_PROTOCOL *This
282 );
283
284 ///
285 /// The EFI_ISA_ACPI_PROTOCOL provides the services to enumerate and manage
286 /// ISA controllers on an ISA bus. These services include the ability to initialize,
287 /// enable, disable, and manage the power state of ISA controllers. It also
288 /// includes services to query current resources, query possible resources,
289 /// and assign resources to an ISA controller.
290 ///
291 struct _EFI_ISA_ACPI_PROTOCOL {
292 EFI_ISA_ACPI_DEVICE_ENUMERATE DeviceEnumerate;
293 EFI_ISA_ACPI_SET_DEVICE_POWER SetPower;
294 EFI_ISA_ACPI_GET_CUR_RESOURCE GetCurResource;
295 EFI_ISA_ACPI_GET_POS_RESOURCE GetPosResource;
296 EFI_ISA_ACPI_SET_RESOURCE SetResource;
297 EFI_ISA_ACPI_ENABLE_DEVICE EnableDevice;
298 EFI_ISA_ACPI_INIT_DEVICE InitDevice;
299 EFI_ISA_ACPI_INTERFACE_INIT InterfaceInit;
300 };
301
302 extern EFI_GUID gEfiIsaAcpiProtocolGuid;
303
304 #endif