13. Super I/O Protocol¶

13.1. Super I/O Protocol¶

13.1.1. EFI_SIO_PROTOCOL¶

Summary

The Super I/O driver installs an instance of this protocol on the handle of every device within the Super I/O chip.

GUID

#define EFI_SIO_PROTOCOL_GUID \
  { 0x215fdd18, 0xbd50, 0x4feb, { 0x89, 0xb, 0x58, 0xca, \
  0xb, 0x47, 0x39, 0xe9 } }

Protocol Interface Structure

typedef struct \_EFI_SIO_PROTOCOL {
  EFI_SIO_REGISTER_ACCESS       RegisterAccess;
  EFI_SIO_GET_RESOURCES         GetResources;
  EFI_SIO_SET_RESOURCES         SetResources;
  EFI_SIO_POSSIBLE_RESOURCES    PossibleResources;
  EFI_SIO_MODIFY                Modify;
} EFI_SIO_PROTOCOL;

Parameter

RegisterAccess: Provides a low level access to the registers for the Super I/O.
GetResources: Provides a list of current resources consumed by the device in ACPI Resource Descriptor Format.
SetResources: Sets resources for a device.
PossibleResources: Provides a collection of possible resource descriptors for the device. Each resource descriptor in the collection defines a combination of resources that can potentially be used by the device.
Modify: Provides an interface for table based programming of the Super I/O registers.

Description

The Super I/O Protocol is installed by the Super I/O driver. The Super I/O driver is a UEFI driver model compliant driver. In the Start() routine of the Super I/O driver, a handle with an instance of EFI_SIO_PROTOCOL is created for each device within the Super I/O. The device within the Super I/O is powered up, enabled, and assigned with the default set of resources. In the Stop() routine of the Super I/O driver, the device is disabled and Super I/O protocol is uninstalled.

13.1.2. EFI_SIO_PROTOCOL.RegisterAccess()¶

Summary

Provides a low level access to the registers for the Super I/O.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_SIO_REGISTER_ACCESS) (
  IN CONST EFI_SIO_PROTOCOL        *This,
  IN BOOLEAN                       Write,
  IN BOOLEAN                       ExitCfgMode,
  IN UINT8                         Register,
  IN OUT UINT8                     *Value
  );

Parameters

This

Indicates a pointer to the calling context.

Write

Specifies the type of the register operation. If this parameter is TRUE , Value is interpreted as an input parameter and the operation is a register write. If this parameter is FALSE , Value is interpreted as an output parameter and the operation is a register read.

ExitCfgMode

Exit Configuration Mode Indicator. If this parameter is set to TRUE , the Super I/O driver will turn off configuration mode of the Super I/O prior to returning from this function. If this parameter is set to FALSE , the Super I/O driver will leave Super I/O in the configuration mode.

The Super I/O driver must track the current state of the Super I/O and enable the configuration mode of Super I/O if necessary prior to register access.

Register

Register number.

Value If Write is TRUE , Value is a pointer to the buffer containing the byte of data to be written to the Super I/O register. If Write is FALSE , Value is a pointer to the destination buffer for the byte of data to be read from the Super I/O register.

Description

The RegisterAccess() function provides low level interface to the registers in the Super I/O.

Note

This function only provides access to the internal registers of the Super I/O chip. For example, on a typical desktop system, these are the registers accessed via the 0x2E/0x2F indexed port I/O. This function cannot be used to access I/O or memory locations assigned to individual logical devices.

Status Codes Returned

EFI_SUCCESS	The operation completed successfully
EFI_INVALID_PARAMETER	The Value is NULL
EFI_INVALID_PARAMETER	Invalid Register number

13.1.3. EFI_SIO_PROTOCOL.GetResources()¶

Summary

Provides an interface to get a list of the current resources consumed by the device in the ACPI Resource Descriptor format.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_SIO_GET_RESOURCES)(
  IN CONST EFI_SIO_PROTOCOL       *This,
  OUT ACPI_RESOURCE_HEADER_PTR    *ResourceList
  );

Parameters

This: Indicates a pointer to the calling context.
ResourceList: A pointer to an ACPI resource descriptor list that defines the current resources used by the device. Type ACPI_RESOURCE_HEADER_PTR is defined in the “Related Definitions” below.

Description

GetResources() returns a list of resources currently consumed by the device. The ResourceList is a pointer to the buffer containing resource descriptors for the device. The descriptors are in the format of Small or Large ACPI resource descriptor as defined by ACPI specification (2.0 & 3.0). The buffer of resource descriptors is terminated with the ‘End tag’ resource descriptor.

typedef union {
  UINT8 Byte;
  struct{
    UINT8 Length : 3;
    UINT8 Name   : 4;
    UINT8 Type   : 1;
  }Bits;
} ACPI_SMALL_RESOURCE_HEADER;

typedef struct {
  union {
    UINT8 Byte;
    struct{
      UINT8 Name : 7;
      UINT8 Type : 1;
    }Bits;
  } Header;
  UINT16 Length;
} ACPI_LARGE_RESOURCE_HEADER;

typedef union {
  ACPI_SMALL_RESOURCE_HEADER    *SmallHeader;
  ACPI_LARGE_RESOURCE_HEADER    *LargeHeader;
} ACPI_RESOURCE_HEADER_PTR;

Length: Length of the resource descriptor in bytes.
Name: Resource descriptor name. Possible values for this field are defined in the ACPI specification.
Type: Descriptor type. 0 - ACPI Small Resource Descriptor 1 - ACPI Large Resource Descriptor

Status Codes Returned

EFI_SUCCESS	The iperation completed successfully
EFI_INVALID_PARAMETER	ResourceList is NULL

13.1.4. EFI_SIO_PROTOCOL.SetResources()¶

Summary

Sets the resources for the device.

Prototype

typedef
EFI_STATUS
(EFIAPI *EFI_SIO_SET_RESOURCES)(
  IN CONST EFI_SIO_PROTOCOL      *This,
  IN ACPI_RESOURCE_HEADER_PTR    ResourceList
  );

Parameters

This: Indicates a pointer to the calling context.
ResourceList: Pointer to the ACPI resource descriptor list. Type ACPI_RESOURCE_HEADER_PTR is defined in the “Related Definitions” section of EFI_SIO_PROTOCOL.GetResources() .

Description

SetResources() sets the resources for the device. ResourceList is a pointer to the ACPI resource descriptor list containing requested resources for the device.

Status Codes Returned

EFI_SUCCESS	The operation completed successfully
EFI_INVALID_PARAMETER	ResourceList is invalid
EFI_ACCESS_DENIED	Some of the resources in ResourceList are in use

13.1.5. EFI_SIO_PROTOCOL.PossibleResources()¶

Summary

Provides a collection of resource descriptor lists. Each resource descriptor list in the collection defines a combination of resources that can potentially be used by the device.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_SIO_POSSIBLE_RESOURCES)(
  IN CONST EFI_SIO_PROTOCOL         *This,
  OUT ACPI_RESOURCE_HEADER_PTR      *ResourceCollection
  );

Parameters

This: Indicates a pointer to the calling context.
ResourceCollection: Collection of the resource descriptor lists. Type ACPI_RESOURCE_HEADER_PTR is defined in the “Related Definitions” section of EFI_SIO_PROTOCOL.GetResources() .

Description

PossibleResources() returns a collection of resource descriptor lists. Each resource descriptor list in the collection defines a combination of resources that can potentially be used by the device. The descriptors are in the format of Small or Large ACPI Resource Descriptor as defined by the ACPI Specification (2.0 & 3.0). The collection is terminated with the ‘End tag’ resource descriptor.

Status Codes Returned

EFI_SUCCESS	The operation completed successfully
EFI_INVALID_PARAMETER	ResourceCollection is NULL

13.1.6. EFI_SIO_PROTOCOL.Modify()¶

Summary

Provides an interface for a table based programming of the Super I/O registers.

Prototype

typedef
EFI_STATUS
(EFIAPI \*EFI_SIO_MODIFY)(
  IN CONST EFI_SIO_PROTOCOL         *This,
  IN CONST EFI_SIO_REGISTER_MODIFY  *Command,
  IN UINTN                          NumberOfCommands
  );

Parameters

This: Indicates a pointer to the calling context.
Command: A pointer to an array of NumberOfCommands EFI_SIO_REGISTER_MODIFY structures. Each structure specifies a single Super I/O register modify operation. Type EFI_SIO_REGISTER_MODIFY is defined in the “Related Definitions” below.
NumberOfCommands: Number of elements in the Command array.

Description

The Modify() function provides an interface for table based programming of the Super I/O registers. This function can be used to perform programming of multiple Super I/O registers with a single function call. For each table entry, the Register is read, its content is bitwise ANDed with AndMask, and then ORed with OrMask before being written back to the Register . The Super I/O driver must track the current state of the Super I/O and enable the configuration mode of Super I/O if necessary prior to table processing. Once the table is processed, the Super I/O device has to be returned to the original state.

Note

This function only provides access to the internal registers of the Super I/O chip. For example, on a typical desktop system, these are the registers accessed via the 0x2E/0x2F indexed port I/O. This function cannot be used to access I/O or memory locations assigned to individual logical devices.

typedef struct {
  UINT8     Register;
  UINT8     AndMask;
  UINT8     OrMask;
} EFI_SIO_REGISTER_MODIFY;

Register: Register number.
AndMask: Bitwise AND mask.
OrMask: Bitwise OR mask.

Status Codes Returned

EFI_SUCCESS	The operation completed successfully
EFI_INVALID_PARAMETER	Command is NULL