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

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