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