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 - 2009, Intel Corporation
   6   All rights reserved. This program and the accompanying materials
   7   are licensed and made available under the terms and conditions of the BSD License
   8   which accompanies this distribution.  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;   ///< 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_SUCESS is returned.  If Device is a pointer
 116   to 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     Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 122   @param[out] Device   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.  If OnOff is TRUE, then power is applied to
 140   the ISA controller.  If OnOff is FALSE, then power is remobed from the ISA
 141   controller.  If the power state is sucessfully set on the ISA Controller, then
 142   EFI_SUCCESS is returned.
 143
 144   @param[in] This     Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 145   @param[in] Device   Pointer to an ISA controller named by ACPI HID/UID.
 146   @param[in] OnOff    TRUE to apply power to the ISA controller.  FALSE to remove
 147                       power from the ISA controller.
 148
 149   @retval EFI_SUCCESS   Successfully set the power state of the ISA controller.
 150   @retval Other         The ISA controller cound not be placed in the requested power state.
 151
 152 **/
 153 typedef
 154 EFI_STATUS
 155 (EFIAPI *EFI_ISA_ACPI_SET_DEVICE_POWER)(
 156   IN EFI_ISA_ACPI_PROTOCOL   *This,
 157   IN EFI_ISA_ACPI_DEVICE_ID  *Device,
 158   IN BOOLEAN                 OnOff
 159   );
 160
 161 /**
 162   Retrieves the current set of resource associated with an ISA controller.
 163
 164   Retrieves the set of I/O, MMIO, DMA, and interrupt resources currently
 165   assigned to the ISA controller specified by Device.  These resources
 166   are returned in ResourceList.
 167
 168   @param[in]  This          Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 169   @param[in]  Device        Pointer to an ISA controller named by ACPI HID/UID.
 170   @param[out] ResourceList  Pointer to the current resource list for Device.
 171
 172   @retval EFI_SUCCESS    Successfully retrieved the current resource list.
 173   @retval EFI_NOT_FOUND  The resource list could not be retrieved.
 174
 175 **/
 176 typedef
 177 EFI_STATUS
 178 (EFIAPI *EFI_ISA_ACPI_GET_CUR_RESOURCE)(
 179   IN  EFI_ISA_ACPI_PROTOCOL       *This,
 180   IN  EFI_ISA_ACPI_DEVICE_ID      *Device,
 181   OUT EFI_ISA_ACPI_RESOURCE_LIST  **ResourceList
 182   );
 183
 184 /**
 185   Retrieves the set of possible resources that may be assigned to an ISA controller
 186   with SetResource().
 187
 188   Retrieves the possible sets of I/O, MMIO, DMA, and interrupt resources for the
 189   ISA controller specified by Device.  The sets are returned in ResourceList.
 190
 191   @param[in]  This           Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 192   @param[in]  Device         Pointer to an ISA controller named by ACPI HID/UID.
 193   @param[out] ResourceList   Pointer to the returned list of resource lists.
 194
 195   @retval EFI_UNSUPPORTED  This services is not supported.
 196
 197 **/
 198 typedef
 199 EFI_STATUS
 200 (EFIAPI *EFI_ISA_ACPI_GET_POS_RESOURCE)(
 201   IN EFI_ISA_ACPI_PROTOCOL        *This,
 202   IN EFI_ISA_ACPI_DEVICE_ID       *Device,
 203   OUT EFI_ISA_ACPI_RESOURCE_LIST  **ResourceList
 204   );
 205
 206 /**
 207   Assigns resources to an ISA controller.
 208
 209   Assigns the I/O, MMIO, DMA, and interrupt resources specified by ResourceList
 210   to the ISA controller specified by Device.  ResourceList must match on of the
 211   possible resource lists returned by GetPosResource() for the same ISA controller.
 212
 213   @param[in] This           Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 214   @param[in] Device         Pointer to an ISA controller named by ACPI HID/UID.
 215   @param[in] ResourceList   Pointer to a resources list that must be one of the
 216                             resource lists returned by GetPosResource() for the
 217                             ISA controller specified by Device.
 218
 219   @retval EFI_SUCCESS  Successfully set resources on the ISA controller.
 220   @retval Other        The resources could not be set for the ISA controller.
 221
 222 **/
 223 typedef
 224 EFI_STATUS
 225 (EFIAPI *EFI_ISA_ACPI_SET_RESOURCE)(
 226   IN EFI_ISA_ACPI_PROTOCOL       *This,
 227   IN EFI_ISA_ACPI_DEVICE_ID      *Device,
 228   IN EFI_ISA_ACPI_RESOURCE_LIST  *ResourceList
 229   );
 230
 231 /**
 232   Enables or disables an ISA controller.
 233
 234   @param[in] This     Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 235   @param[in] Device   Pointer to the ISA controller to enable/disable.
 236   @param[in] Enable   TRUE to enable the ISA controller.  FALSE to disable the
 237                       ISA controller.
 238
 239   @retval EFI_SUCCESS   Successfully enabled/disabled the ISA controller.
 240   @retval Other         The ISA controller cound not be placed in the requested state.
 241
 242 **/
 243 typedef
 244 EFI_STATUS
 245 (EFIAPI *EFI_ISA_ACPI_ENABLE_DEVICE)(
 246   IN EFI_ISA_ACPI_PROTOCOL   *This,
 247   IN EFI_ISA_ACPI_DEVICE_ID  *Device,
 248   IN BOOLEAN                 Enable
 249   );
 250
 251 /**
 252   Places an ISA controller into a usable state.  This service must be called
 253   before SetResource(), EnableDevice(), or SetPower() will behave as expected.
 254
 255   @param[in] This     Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 256   @param[in] Device   Pointer to an ISA controller named by ACPI HID/UID.
 257
 258   @retval EFI_SUCCESS   Successfully initialized an ISA controller.
 259   @retval Other         The ISA controller could not be initialized.
 260
 261 **/
 262 typedef
 263 EFI_STATUS
 264 (EFIAPI *EFI_ISA_ACPI_INIT_DEVICE)(
 265   IN EFI_ISA_ACPI_PROTOCOL   *This,
 266   IN EFI_ISA_ACPI_DEVICE_ID  *Device
 267   );
 268
 269 /**
 270   Initializes all the HW state required for the ISA controlers on the ISA bus
 271   to be enumerated and managed by this rest of the services in this prorotol.
 272   This service must be called before any of the other services in this
 273   protocol will function as expected.
 274
 275   @param[in] This  Pointer to the EFI_ISA_ACPI_PROTOCOL instance.
 276
 277   @retval EFI_SUCCESS   Successfully initialized the ISA interface.
 278   @retval Other         The ISA interface could not be initialized.
 279
 280 **/
 281 typedef
 282 EFI_STATUS
 283 (EFIAPI *EFI_ISA_ACPI_INTERFACE_INIT)(
 284   IN EFI_ISA_ACPI_PROTOCOL  *This
 285   );
 286
 287 ///
 288 /// The EFI_ISA_ACPI_PROTOCOL provides the services to enumberate and manage
 289 /// ISA controllers on an ISA bus.  This include the ability to initialize,
 290 /// enable, disable, and manag the power state of ISA controllers.  It also
 291 /// includes services to query current ressources, query possible resources,
 292 /// and assign resources to an ISA controller.
 293 ///
 294 struct _EFI_ISA_ACPI_PROTOCOL {
 295   EFI_ISA_ACPI_DEVICE_ENUMERATE  DeviceEnumerate;
 296   EFI_ISA_ACPI_SET_DEVICE_POWER  SetPower;
 297   EFI_ISA_ACPI_GET_CUR_RESOURCE  GetCurResource;
 298   EFI_ISA_ACPI_GET_POS_RESOURCE  GetPosResource;
 299   EFI_ISA_ACPI_SET_RESOURCE      SetResource;
 300   EFI_ISA_ACPI_ENABLE_DEVICE     EnableDevice;
 301   EFI_ISA_ACPI_INIT_DEVICE       InitDevice;
 302   EFI_ISA_ACPI_INTERFACE_INIT    InterfaceInit;
 303 };
 304
 305 extern EFI_GUID gEfiIsaAcpiProtocolGuid;
 306
 307 #endif