[mirror_edk2.git] / MdePkg / Include / Ppi / SuperIo.h

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