MdePkg/Include/Ppi/SuperIo.h

   1 /** @file
   2   This PPI provides the super I/O register access functionality.
   3
   4   Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
   5   This program and the accompanying materials
   6   are licensed and made available under the terms and conditions of the BSD License
   7   which accompanies this distribution.  The full text of the license may be found at
   8   http://opensource.org/licenses/bsd-license.php
   9
  10   THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  11   WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  12
  13   @par Revision Reference:
  14   This PPI is from PI Version 1.2.1.
  15
  16 **/
  17
  18 #ifndef __EFI_SUPER_IO_PPI_H__
  19 #define __EFI_SUPER_IO_PPI_H__
  20
  21 #include <Protocol/SuperIo.h>
  22
  23 #define EFI_SIO_PPI_GUID \
  24   { \
  25     0x23a464ad, 0xcb83, 0x48b8, {0x94, 0xab, 0x1a, 0x6f, 0xef, 0xcf, 0xe5, 0x22} \
  26   }
  27
  28 typedef struct _EFI_SIO_PPI EFI_SIO_PPI;
  29 typedef struct _EFI_SIO_PPI *PEFI_SIO_PPI;
  30
  31 typedef UINT16 EFI_SIO_REGISTER;
  32 #define EFI_SIO_REG(ldn,reg)    (EFI_SIO_REGISTER) (((ldn) << 8) | reg)
  33 #define EFI_SIO_LDN_GLOBAL      0xFF
  34
  35 /**
  36   Read a Super I/O register.
  37
  38   The register is specified as an 8-bit logical device number and an 8-bit
  39   register value. The logical device numbers for specific SIO devices can be
  40   determined using the Info member of the PPI structure.
  41
  42   @param PeiServices  A pointer to a pointer to the PEI Services.
  43   @param This         A pointer to this instance of the EFI_SIO_PPI.
  44   @param ExitCfgMode  A boolean specifying whether the driver should turn on
  45                       configuration mode (FALSE) or turn off configuration mode
  46                       (TRUE) after completing the read operation. The driver must
  47                       track the current state of the configuration mode (if any)
  48                       and turn on configuration mode (if necessary) prior to
  49                       register access.
  50   @param Register     A value specifying the logical device number (bits 15:8)
  51                       and the register to read (bits 7:0). The logical device
  52                       number of EFI_SIO_LDN_GLOBAL indicates that global
  53                       registers will be used.
  54   @param IoData       A pointer to the returned register value.
  55
  56   @retval EFI_SUCCESS            Success.
  57   @retval EFI_TIMEOUT            The register could not be read in the a reasonable
  58                                  amount of time. The exact time is device-specific.
  59   @retval EFI_INVALID_PARAMETERS Register was out of range for this device.
  60   @retval EFI_INVALID_PARAMETERS IoData was NULL
  61   @retval EFI_DEVICE_ERROR       There was a device fault or the device was not present.
  62 **/
  63 typedef
  64 EFI_STATUS
  65 (EFIAPI *EFI_PEI_SIO_REGISTER_READ)(
  66   IN EFI_PEI_SERVICES       **PeiServices,
  67   IN CONST EFI_SIO_PPI      *This,
  68   IN BOOLEAN                ExitCfgMode,
  69   IN EFI_SIO_REGISTER       Register,
  70   OUT UINT8                 *IoData
  71   );
  72
  73 /**
  74   Write a Super I/O register.
  75
  76   The register is specified as an 8-bit logical device number and an 8-bit register
  77   value. The logical device numbers for specific SIO devices can be determined
  78   using the Info member of the PPI structure.
  79
  80   @param PeiServices  A pointer to a pointer to the PEI Services.
  81   @param This         A pointer to this instance of the EFI_SIO_PPI.
  82   @param ExitCfgMode  A boolean specifying whether the driver should turn on
  83                       configuration mode (FALSE) or turn off configuration mode
  84                       (TRUE) after completing the read operation. The driver must
  85                       track the current state of the configuration mode (if any)
  86                       and turn on configuration mode (if necessary) prior to
  87                       register access.
  88   @param Register     A value specifying the logical device number (bits 15:8)
  89                       and the register to read (bits 7:0). The logical device
  90                       number of EFI_SIO_LDN_GLOBAL indicates that global
  91                       registers will be used.
  92   @param IoData       A pointer to the returned register value.
  93
  94   @retval EFI_SUCCESS            Success.
  95   @retval EFI_TIMEOUT            The register could not be read in the a reasonable
  96                                  amount of time. The exact time is device-specific.
  97   @retval EFI_INVALID_PARAMETERS Register was out of range for this device.
  98   @retval EFI_INVALID_PARAMETERS IoData was NULL
  99   @retval EFI_DEVICE_ERROR       There was a device fault or the device was not present.
 100 **/
 101 typedef
 102 EFI_STATUS
 103 (EFIAPI *EFI_PEI_SIO_REGISTER_WRITE)(
 104   IN EFI_PEI_SERVICES       **PeiServices,
 105   IN CONST EFI_SIO_PPI      *This,
 106   IN BOOLEAN                ExitCfgMode,
 107   IN EFI_SIO_REGISTER       Register,
 108   IN UINT8                  IoData
 109   );
 110
 111 /**
 112   Provides an interface for a table based programming of the Super I/O registers.
 113
 114   The Modify() function provides an interface for table based programming of the
 115   Super I/O registers. This function can be used to perform programming of
 116   multiple Super I/O registers with a single function call. For each table entry,
 117   the Register is read, its content is bitwise ANDed with AndMask, and then ORed
 118   with OrMask before being written back to the Register. The Super I/O driver
 119   must track the current state of the Super I/O and enable the configuration mode
 120   of Super I/O if necessary prior to table processing. Once the table is processed,
 121   the Super I/O device must be returned to the original state.
 122
 123   @param PeiServices      A pointer to a pointer to the PEI Services.
 124   @param This             A pointer to this instance of the EFI_SIO_PPI.
 125   @param Command          A pointer to an array of NumberOfCommands EFI_SIO_REGISTER_MODIFY
 126                           structures. Each structure specifies a single Super I/O register
 127                           modify operation.
 128   @param NumberOfCommands The number of elements in the Command array.
 129
 130   @retval EFI_SUCCESS             The operation completed successfully.
 131   @retval EFI_INVALID_PARAMETERS  Command is NULL.
 132 **/
 133 typedef
 134 EFI_STATUS
 135 (EFIAPI *EFI_PEI_SIO_REGISTER_MODIFY)(
 136   IN EFI_PEI_SERVICES              **PeiServices,
 137   IN CONST EFI_SIO_PPI             *This,
 138   IN CONST EFI_SIO_REGISTER_MODIFY *Command,
 139   IN UINTN                         NumberOfCommands
 140   );
 141
 142 ///
 143 /// Specifies the end of the information list.
 144 ///
 145 #define EFI_ACPI_PNP_HID_END       0
 146
 147 typedef UINT32                     EFI_ACPI_HID;
 148 typedef UINT32                     EFI_ACPI_UID;
 149 #pragma pack(1)
 150 typedef struct _EFI_SIO_INFO {
 151   EFI_ACPI_HID                     Hid;
 152   EFI_ACPI_UID                     Uid;
 153   UINT8                            Ldn;
 154 } EFI_SIO_INFO, *PEFI_SIO_INFO;
 155 #pragma pack()
 156
 157 ///
 158 /// This PPI provides low-level access to Super I/O registers using Read() and
 159 /// Write(). It also uniquely identifies this Super I/O controller using a GUID
 160 /// and provides mappings between ACPI style PNP IDs and the logical device numbers.
 161 /// There is one instance of this PPI per Super I/O device.
 162 ///
 163 struct _EFI_SIO_PPI {
 164   ///
 165   /// This function reads a register's value from the Super I/O controller.
 166   ///
 167   EFI_PEI_SIO_REGISTER_READ   Read;
 168   ///
 169   /// This function writes a value to a register in the Super I/O controller.
 170   ///
 171   EFI_PEI_SIO_REGISTER_WRITE  Write;
 172   ///
 173   /// This function modifies zero or more registers in the Super I/O controller
 174   /// using a table.
 175   ///
 176   EFI_PEI_SIO_REGISTER_MODIFY Modify;
 177   ///
 178   /// This GUID uniquely identifies the Super I/O controller.
 179   ///
 180   EFI_GUID                    SioGuid;
 181   ///
 182   /// This pointer is to an array which maps EISA identifiers to logical devices numbers.
 183   ///
 184   PEFI_SIO_INFO               Info;
 185 };
 186
 187 extern EFI_GUID gEfiSioPpiGuid;
 188
 189 #endif