MdePkg/Include/Protocol/SuperIo.h

   1 /** @file
   2   The Super I/O Protocol is installed by the Super I/O driver. The Super I/O driver is a UEFI driver
   3   model compliant driver. In the Start() routine of the Super I/O driver, a handle with an instance
   4   of EFI_SIO_PROTOCOL is created for each device within the Super I/O. The device within the
   5   Super I/O is powered up, enabled, and assigned with the default set of resources. In the Stop()
   6   routine of the Super I/O driver, the device is disabled and Super I/O protocol is uninstalled.
   7
   8   Copyright (c) 2006 - 2008, Intel Corporation
   9   All rights reserved. This program and the accompanying materials
  10   are licensed and made available under the terms and conditions of the BSD License
  11   which accompanies this distribution.  The full text of the license may be found at
  12   http://opensource.org/licenses/bsd-license.php
  13
  14   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  15   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  16
  17 **/
  18
  19 #ifndef __EFI_SUPER_IO_PROTOCOL_H__
  20 #define __EFI_SUPER_IO_PROTOCOL_H__
  21
  22 #define EFI_SIO_PROTOCOL_GUID \
  23   { 0x215fdd18, 0xbd50, 0x4feb, { 0x89, 0xb, 0x58, 0xca, 0xb, 0x47, 0x39, 0xe9 } }
  24
  25 typedef union {
  26   UINT8     Byte;
  27   struct {
  28     UINT8 Length : 3;
  29     UINT8 Name : 4;
  30     UINT8 Type : 1;
  31   } Bits;
  32 } ACPI_SMALL_RESOURCE_HEADER;
  33
  34 typedef struct {
  35   union {
  36     UINT8 Byte;
  37     struct{
  38       UINT8 Name : 7;
  39       UINT8 Type : 1;
  40     }Bits;
  41   } Header;
  42   UINT16 Length;
  43 } ACPI_LARGE_RESOURCE_HEADER;
  44
  45 typedef union {
  46   ACPI_SMALL_RESOURCE_HEADER *SmallHeader;
  47   ACPI_LARGE_RESOURCE_HEADER *LargeHeader;
  48 } ACPI_RESOURCE_HEADER_PTR;
  49
  50 typedef struct {
  51   UINT8 Register;       ///< Register number.
  52   UINT8 AndMask;        ///< Bitwise AND mask.
  53   UINT8 OrMask;         ///< Bitwise OR mask.
  54 } EFI_SIO_REGISTER_MODIFY;
  55
  56 typedef struct _EFI_SIO_PROTOCOL  EFI_SIO_PROTOCOL;
  57
  58 /**
  59   Provides a low level access to the registers for the Super I/O.
  60
  61   @param[in]        This        Indicates a pointer to the calling context.
  62   @param[in]        Write       Specifies the type of the register operation. If this parameter is TRUE, Value is
  63                                 interpreted as an input parameter and the operation is a register write. If this parameter
  64                                 is FALSE, Value is interpreted as an output parameter and the operation is a register
  65                                 read.
  66   @param[in]        ExitCfgMode Exit Configuration Mode Indicator. If this parameter is set to TRUE, the Super I/O
  67                                 driver will turn off configuration mode of the Super I/O prior to returning from this
  68                                 function. If this parameter is set to FALSE, the Super I/O driver will leave Super I/O
  69                                 in the configuration mode.
  70                                 The Super I/O driver must track the current state of the Super I/O and enable the
  71                                 configuration mode of Super I/O if necessary prior to register access.
  72   @param[in]        Register    Register number.
  73   @param[in, out]   Value       If Write is TRUE, Value is a pointer to the buffer containing the byte of data to be
  74                                 written to the Super I/O register. If Write is FALSE, Value is a pointer to the
  75                                 destination buffer for the byte of data to be read from the Super I/O register.
  76
  77   @retval EFI_SUCCESS           The operation completed successfully
  78   @retval EFI_INVALID_PARAMETER The Value is NULL
  79   @retval EFI_INVALID_PARAMETER Invalid Register number
  80
  81 **/
  82 typedef
  83 EFI_STATUS
  84 (EFIAPI *EFI_SIO_REGISTER_ACCESS)(
  85   IN   CONST  EFI_SIO_PROTOCOL  *This,
  86   IN          BOOLEAN           Write,
  87   IN          BOOLEAN           ExitCfgMode,
  88   IN          UINT8             Register,
  89   IN OUT      UINT8             *Value
  90 );
  91
  92 /**
  93   Provides an interface to get a list of the current resources consumed by the device in the ACPI
  94   Resource Descriptor format.
  95
  96   GetResources() returns a list of resources currently consumed by the device. The
  97   ResourceList is a pointer to the buffer containing resource descriptors for the device. The
  98   descriptors are in the format of Small or Large ACPI resource descriptor as defined by ACPI
  99   specification (2.0 & 3.0). The buffer of resource descriptors is terminated with the 'End tag'
 100   resource descriptor.
 101
 102   @param[in]    This            Indicates a pointer to the calling context.
 103   @param[out]   ResourceList    A pointer to an ACPI resource descriptor list that defines the current resources used by
 104                                 the device. Type ACPI_RESOURCE_HEADER_PTR is defined in the "Related
 105                                 Definitions" below.
 106
 107   @retval EFI_SUCCESS           The operation completed successfully
 108   @retval EFI_INVALID_PARAMETER ResourceList is NULL
 109
 110 **/
 111 typedef
 112 EFI_STATUS
 113 (EFIAPI *EFI_SIO_GET_RESOURCES)(
 114   IN  CONST EFI_SIO_PROTOCOL            *This,
 115   OUT       ACPI_RESOURCE_HEADER_PTR    *ResourceList
 116 );
 117
 118 /**
 119   Sets the resources for the device.
 120
 121   @param[in]  This          Indicates a pointer to the calling context.
 122   @param[in]  ResourceList  Pointer to the ACPI resource descriptor list. Type ACPI_RESOURCE_HEADER_PTR
 123                             is defined in the "Related Definitions" section of
 124                             EFI_SIO_PROTOCOL.GetResources().
 125
 126   @retval EFI_SUCCESS           The operation completed successfully
 127   @retval EFI_INVALID_PARAMETER ResourceList is invalid
 128   @retval EFI_ACCESS_DENIED     Some of the resources in ResourceList are in use
 129
 130 **/
 131 typedef
 132 EFI_STATUS
 133 (EFIAPI *EFI_SIO_SET_RESOURCES)(
 134   IN CONST  EFI_SIO_PROTOCOL        *This,
 135   IN        ACPI_RESOURCE_HEADER_PTR ResourceList
 136 );
 137
 138 /**
 139   Provides a collection of resource descriptor lists. Each resource descriptor list in the collection
 140   defines a combination of resources that can potentially be used by the device.
 141
 142   @param[in]  This                  Indicates a pointer to the calling context.
 143   @param[out] ResourceCollection    Collection of the resource descriptor lists.
 144
 145   @retval EFI_SUCCESS               The operation completed successfully
 146   @retval EFI_INVALID_PARAMETER     ResourceCollection is NULL
 147 **/
 148 typedef
 149 EFI_STATUS
 150 (EFIAPI *EFI_SIO_POSSIBLE_RESOURCES)(
 151   IN  CONST EFI_SIO_PROTOCOL         *This,
 152   OUT       ACPI_RESOURCE_HEADER_PTR *ResourceCollection
 153 );
 154
 155 /**
 156   Provides an interface for a table based programming of the Super I/O registers.
 157
 158   The Modify() function provides an interface for table based programming of the Super I/O
 159   registers. This function can be used to perform programming of multiple Super I/O registers with a
 160   single function call. For each table entry, the Register is read, its content is bitwise ANDed with
 161   AndMask, and then ORed with OrMask before being written back to the Register. The Super
 162   I/O driver must track the current state of the Super I/O and enable the configuration mode of Super I/
 163   O if necessary prior to table processing. Once the table is processed, the Super I/O device has to be
 164   returned to the original state.
 165
 166   @param[in] This       Indicates a pointer to the calling context.
 167   @param[in] Command    A pointer to an array of NumberOfCommands EFI_SIO_REGISTER_MODIFY
 168                         structures. Each structure specifies a single Super I/O register modify operation. Type
 169                         EFI_SIO_REGISTER_MODIFY is defined in the "Related Definitions" below.
 170   @param[in] NumberOfCommands Number of elements in the Command array.
 171
 172   @retval EFI_SUCCESS           The operation completed successfully
 173   @retval EFI_INVALID_PARAMETER Command is NULL
 174
 175 **/
 176 typedef
 177 EFI_STATUS
 178 (EFIAPI *EFI_SIO_MODIFY)(
 179   IN CONST EFI_SIO_PROTOCOL         *This,
 180   IN CONST EFI_SIO_REGISTER_MODIFY  *Command,
 181   IN       UINTN                    NumberOfCommands
 182 );
 183
 184 struct _EFI_SIO_PROTOCOL {
 185   EFI_SIO_REGISTER_ACCESS       RegisterAccess;
 186   EFI_SIO_GET_RESOURCES         GetResources;
 187   EFI_SIO_SET_RESOURCES         SetResources;
 188   EFI_SIO_POSSIBLE_RESOURCES    PossibleResources;
 189   EFI_SIO_MODIFY Modify;
 190 };
 191
 192 extern EFI_GUID gEfiSioProtocolGuid;
 193
 194 #endif // __EFI_SUPER_IO_PROTOCOL_H__