[mirror_edk2.git] / SecurityPkg / Include / Library / TpmCommLib.h

/** @file\r
  This library is only intended to be used by TPM modules.\r
  It provides basic TPM Interface Specification (TIS) and Command functions.\r
\r
Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>\r
SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef _TPM_COMM_LIB_H_\r
#define _TPM_COMM_LIB_H_\r
\r
#include <IndustryStandard/Tpm12.h>\r
\r
typedef EFI_HANDLE  TIS_TPM_HANDLE;\r
\r
///\r
/// TPM register base address.\r
///\r
#define TPM_BASE_ADDRESS            0xfed40000\r
\r
//\r
// Set structure alignment to 1-byte\r
//\r
#pragma pack (1)\r
\r
//\r
// Register set map as specified in TIS specification Chapter 10\r
//\r
typedef struct {\r
  ///\r
  /// Used to gain ownership for this particular port.\r
  ///\r
  UINT8                             Access;             // 0\r
  UINT8                             Reserved1[7];       // 1\r
  ///\r
  /// Controls interrupts.\r
  ///\r
  UINT32                            IntEnable;          // 8\r
  ///\r
  /// SIRQ vector to be used by the TPM.\r
  ///\r
  UINT8                             IntVector;          // 0ch\r
  UINT8                             Reserved2[3];       // 0dh\r
  ///\r
  /// What caused interrupt.\r
  ///\r
  UINT32                            IntSts;             // 10h\r
  ///\r
  /// Shows which interrupts are supported by that particular TPM.\r
  ///\r
  UINT32                            IntfCapability;     // 14h\r
  ///\r
  /// Status Register. Provides status of the TPM.\r
  ///\r
  UINT8                             Status;             // 18h\r
  ///\r
  /// Number of consecutive writes that can be done to the TPM.\r
  ///\r
  UINT16                            BurstCount;         // 19h\r
  UINT8                             Reserved3[9];\r
  ///\r
  /// Read or write FIFO, depending on transaction.\r
  ///\r
  UINT32                            DataFifo;           // 24\r
  UINT8                             Reserved4[0xed8];   // 28h\r
  ///\r
  /// Vendor ID\r
  ///\r
  UINT16                            Vid;                // 0f00h\r
  ///\r
  /// Device ID\r
  ///\r
  UINT16                            Did;                // 0f02h\r
  ///\r
  /// Revision ID\r
  ///\r
  UINT8                             Rid;                // 0f04h\r
  ///\r
  /// TCG defined configuration registers.\r
  ///\r
  UINT8                             TcgDefined[0x7b];   // 0f05h\r
  ///\r
  /// Alias to I/O legacy space.\r
  ///\r
  UINT32                            LegacyAddress1;     // 0f80h\r
  ///\r
  /// Additional 8 bits for I/O legacy space extension.\r
  ///\r
  UINT32                            LegacyAddress1Ex;   // 0f84h\r
  ///\r
  /// Alias to second I/O legacy space.\r
  ///\r
  UINT32                            LegacyAddress2;     // 0f88h\r
  ///\r
  /// Additional 8 bits for second I/O legacy space extension.\r
  ///\r
  UINT32                            LegacyAddress2Ex;   // 0f8ch\r
  ///\r
  /// Vendor-defined configuration registers.\r
  ///\r
  UINT8                             VendorDefined[0x70];// 0f90h\r
} TIS_PC_REGISTERS;\r
\r
//\r
// Restore original structure alignment\r
//\r
#pragma pack ()\r
\r
//\r
// Define pointer types used to access TIS registers on PC\r
//\r
typedef TIS_PC_REGISTERS  *TIS_PC_REGISTERS_PTR;\r
\r
//\r
// TCG Platform Type based on TCG ACPI Specification Version 1.00\r
//\r
#define TCG_PLATFORM_TYPE_CLIENT   0\r
#define TCG_PLATFORM_TYPE_SERVER   1\r
\r
//\r
// Define bits of ACCESS and STATUS registers\r
//\r
\r
///\r
/// This bit is a 1 to indicate that the other bits in this register are valid.\r
///\r
#define TIS_PC_VALID                BIT7\r
///\r
/// Indicate that this locality is active.\r
///\r
#define TIS_PC_ACC_ACTIVE           BIT5\r
///\r
/// Set to 1 to indicate that this locality had the TPM taken away while\r
/// this locality had the TIS_PC_ACC_ACTIVE bit set.\r
///\r
#define TIS_PC_ACC_SEIZED           BIT4\r
///\r
/// Set to 1 to indicate that TPM MUST reset the\r
/// TIS_PC_ACC_ACTIVE bit and remove ownership for localities less than the\r
/// locality that is writing this bit.\r
///\r
#define TIS_PC_ACC_SEIZE            BIT3\r
///\r
/// When this bit is 1, another locality is requesting usage of the TPM.\r
///\r
#define TIS_PC_ACC_PENDIND          BIT2\r
///\r
/// Set to 1 to indicate that this locality is requesting to use TPM.\r
///\r
#define TIS_PC_ACC_RQUUSE           BIT1\r
///\r
/// A value of 1 indicates that a T/OS has not been established on the platform\r
///\r
#define TIS_PC_ACC_ESTABLISH        BIT0\r
\r
///\r
/// When this bit is 1, TPM is in the Ready state,\r
/// indicating it is ready to receive a new command.\r
///\r
#define TIS_PC_STS_READY            BIT6\r
///\r
/// Write a 1 to this bit to cause the TPM to execute that command.\r
///\r
#define TIS_PC_STS_GO               BIT5\r
///\r
/// This bit indicates that the TPM has data available as a response.\r
///\r
#define TIS_PC_STS_DATA             BIT4\r
///\r
/// The TPM sets this bit to a value of 1 when it expects another byte of data for a command.\r
///\r
#define TIS_PC_STS_EXPECT           BIT3\r
///\r
/// Writes a 1 to this bit to force the TPM to re-send the response.\r
///\r
#define TIS_PC_STS_RETRY            BIT1\r
\r
//\r
// Default TimeOut value\r
//\r
#define TIS_TIMEOUT_A               750 * 1000   // 750ms\r
#define TIS_TIMEOUT_B               2000 * 1000  // 2s\r
#define TIS_TIMEOUT_C               750 * 1000   // 750ms\r
#define TIS_TIMEOUT_D               750 * 1000   // 750ms\r
\r
//\r
// Max TPM command/reponse length\r
//\r
#define TPMCMDBUFLENGTH             1024\r
\r
/**\r
  Check whether the value of a TPM chip register satisfies the input BIT setting.\r
\r
  @param[in]  Register     Address port of register to be checked.\r
  @param[in]  BitSet       Check these data bits are set.\r
  @param[in]  BitClear     Check these data bits are clear.\r
  @param[in]  TimeOut      The max wait time (unit MicroSecond) when checking register.\r
\r
  @retval     EFI_SUCCESS  The register satisfies the check bit.\r
  @retval     EFI_TIMEOUT  The register can't run into the expected status in time.\r
**/\r
EFI_STATUS\r
EFIAPI\r
TisPcWaitRegisterBits (\r
  IN UINT8   *Register,\r
  IN UINT8   BitSet,\r
  IN UINT8   BitClear,\r
  IN UINT32  TimeOut\r
  );\r
\r
/**\r
  Get BurstCount by reading the burstCount field of a TIS regiger\r
  in the time of default TIS_TIMEOUT_D.\r
\r
  @param[in]  TisReg                Pointer to TIS register.\r
  @param[out] BurstCount            Pointer to a buffer to store the got BurstConut.\r
\r
  @retval     EFI_SUCCESS           Get BurstCount.\r
  @retval     EFI_INVALID_PARAMETER TisReg is NULL or BurstCount is NULL.\r
  @retval     EFI_TIMEOUT           BurstCount can't be got in time.\r
**/\r
EFI_STATUS\r
EFIAPI\r
TisPcReadBurstCount (\r
  IN  TIS_PC_REGISTERS_PTR  TisReg,\r
  OUT UINT16                *BurstCount\r
  );\r
\r
/**\r
  Set TPM chip to ready state by sending ready command TIS_PC_STS_READY\r
  to Status Register in time.\r
\r
  @param[in] TisReg                Pointer to TIS register.\r
\r
  @retval    EFI_SUCCESS           TPM chip enters into ready state.\r
  @retval    EFI_INVALID_PARAMETER TisReg is NULL.\r
  @retval    EFI_TIMEOUT           TPM chip can't be set to ready state in time.\r
**/\r
EFI_STATUS\r
EFIAPI\r
TisPcPrepareCommand (\r
  IN TIS_PC_REGISTERS_PTR  TisReg\r
  );\r
\r
/**\r
  Get the control of TPM chip by sending requestUse command TIS_PC_ACC_RQUUSE\r
  to ACCESS Register in the time of default TIS_TIMEOUT_D.\r
\r
  @param[in] TisReg                Pointer to TIS register.\r
\r
  @retval    EFI_SUCCESS           Get the control of TPM chip.\r
  @retval    EFI_INVALID_PARAMETER TisReg is NULL.\r
  @retval    EFI_NOT_FOUND         TPM chip doesn't exit.\r
  @retval    EFI_TIMEOUT           Can't get the TPM control in time.\r
**/\r
EFI_STATUS\r
EFIAPI\r
TisPcRequestUseTpm (\r
  IN TIS_PC_REGISTERS_PTR  TisReg\r
  );\r
\r
/**\r
  Single function calculates SHA1 digest value for all raw data. It\r
  combines Sha1Init(), Sha1Update() and Sha1Final().\r
\r
  @param[in]  Data          Raw data to be digested.\r
  @param[in]  DataLen       Size of the raw data.\r
  @param[out] Digest        Pointer to a buffer that stores the final digest.\r
\r
  @retval     EFI_SUCCESS   Always successfully calculate the final digest.\r
**/\r
EFI_STATUS\r
EFIAPI\r
TpmCommHashAll (\r
  IN  CONST UINT8       *Data,\r
  IN        UINTN       DataLen,\r
  OUT       TPM_DIGEST  *Digest\r
  );\r
\r
#endif\r
Commit	Line	Data
0c18794e	1	/** @file\r
07309c3d	2	This library is only intended to be used by TPM modules.\r
0c18794e	3	It provides basic TPM Interface Specification (TIS) and Command functions.\r
0c18794e	4	\r
b3548d32	5	Copyright (c) 2005 - 2018, Intel Corporation. All rights reserved.<BR>\r
289b714b	6	SPDX-License-Identifier: BSD-2-Clause-Patent\r
0c18794e	7	\r
	8	**/\r
	9	\r
	10	#ifndef _TPM_COMM_LIB_H_\r
	11	#define _TPM_COMM_LIB_H_\r
	12	\r
	13	#include <IndustryStandard/Tpm12.h>\r
	14	\r
	15	typedef EFI_HANDLE TIS_TPM_HANDLE;\r
	16	\r
	17	///\r
	18	/// TPM register base address.\r
	19	///\r
	20	#define TPM_BASE_ADDRESS 0xfed40000\r
	21	\r
	22	//\r
	23	// Set structure alignment to 1-byte\r
	24	//\r
	25	#pragma pack (1)\r
	26	\r
	27	//\r
	28	// Register set map as specified in TIS specification Chapter 10\r
	29	//\r
	30	typedef struct {\r
	31	///\r
	32	/// Used to gain ownership for this particular port.\r
	33	///\r
	34	UINT8 Access; // 0\r
	35	UINT8 Reserved1[7]; // 1\r
	36	///\r
	37	/// Controls interrupts.\r
	38	///\r
	39	UINT32 IntEnable; // 8\r
	40	///\r
	41	/// SIRQ vector to be used by the TPM.\r
	42	///\r
	43	UINT8 IntVector; // 0ch\r
	44	UINT8 Reserved2[3]; // 0dh\r
	45	///\r
	46	/// What caused interrupt.\r
	47	///\r
	48	UINT32 IntSts; // 10h\r
	49	///\r
	50	/// Shows which interrupts are supported by that particular TPM.\r
	51	///\r
	52	UINT32 IntfCapability; // 14h\r
	53	///\r
	54	/// Status Register. Provides status of the TPM.\r
	55	///\r
	56	UINT8 Status; // 18h\r
	57	///\r
	58	/// Number of consecutive writes that can be done to the TPM.\r
	59	///\r
	60	UINT16 BurstCount; // 19h\r
	61	UINT8 Reserved3[9];\r
	62	///\r
	63	/// Read or write FIFO, depending on transaction.\r
	64	///\r
	65	UINT32 DataFifo; // 24\r
	66	UINT8 Reserved4[0xed8]; // 28h\r
	67	///\r
	68	/// Vendor ID\r
	69	///\r
	70	UINT16 Vid; // 0f00h\r
71	///\r
72	/// Device ID\r
73	///\r
74	UINT16 Did; // 0f02h\r
75	///\r
76	/// Revision ID\r
77	///\r
78	UINT8 Rid; // 0f04h\r
79	///\r
80	/// TCG defined configuration registers.\r
81	///\r
82	UINT8 TcgDefined[0x7b]; // 0f05h\r
83	///\r
84	/// Alias to I/O legacy space.\r
85	///\r
86	UINT32 LegacyAddress1; // 0f80h\r
87	///\r
88	/// Additional 8 bits for I/O legacy space extension.\r
89	///\r
90	UINT32 LegacyAddress1Ex; // 0f84h\r
91	///\r
92	/// Alias to second I/O legacy space.\r
93	///\r
94	UINT32 LegacyAddress2; // 0f88h\r
95	///\r
96	/// Additional 8 bits for second I/O legacy space extension.\r
97	///\r
98	UINT32 LegacyAddress2Ex; // 0f8ch\r
99	///\r
100	/// Vendor-defined configuration registers.\r
101	///\r
102	UINT8 VendorDefined[0x70];// 0f90h\r
103	} TIS_PC_REGISTERS;\r
104	\r
105	//\r
106	// Restore original structure alignment\r
107	//\r
108	#pragma pack ()\r
109	\r
110	//\r
111	// Define pointer types used to access TIS registers on PC\r
112	//\r
113	typedef TIS_PC_REGISTERS *TIS_PC_REGISTERS_PTR;\r
114	\r
115	//\r
116	// TCG Platform Type based on TCG ACPI Specification Version 1.00\r
117	//\r
118	#define TCG_PLATFORM_TYPE_CLIENT 0\r
119	#define TCG_PLATFORM_TYPE_SERVER 1\r
120	\r
121	//\r
122	// Define bits of ACCESS and STATUS registers\r
123	//\r
124	\r
125	///\r
126	/// This bit is a 1 to indicate that the other bits in this register are valid.\r
127	///\r
128	#define TIS_PC_VALID BIT7\r
129	///\r
130	/// Indicate that this locality is active.\r
131	///\r
132	#define TIS_PC_ACC_ACTIVE BIT5\r
133	///\r
134	/// Set to 1 to indicate that this locality had the TPM taken away while\r
135	/// this locality had the TIS_PC_ACC_ACTIVE bit set.\r
136	///\r
137	#define TIS_PC_ACC_SEIZED BIT4\r
138	///\r
139	/// Set to 1 to indicate that TPM MUST reset the\r
140	/// TIS_PC_ACC_ACTIVE bit and remove ownership for localities less than the\r
141	/// locality that is writing this bit.\r
142	///\r
143	#define TIS_PC_ACC_SEIZE BIT3\r
144	///\r
145	/// When this bit is 1, another locality is requesting usage of the TPM.\r
146	///\r
147	#define TIS_PC_ACC_PENDIND BIT2\r
148	///\r
149	/// Set to 1 to indicate that this locality is requesting to use TPM.\r
150	///\r
151	#define TIS_PC_ACC_RQUUSE BIT1\r
152	///\r
153	/// A value of 1 indicates that a T/OS has not been established on the platform\r
154	///\r
155	#define TIS_PC_ACC_ESTABLISH BIT0\r
156	\r
157	///\r
b3548d32	158	/// When this bit is 1, TPM is in the Ready state,\r
0c18794e	159	/// indicating it is ready to receive a new command.\r
	160	///\r
	161	#define TIS_PC_STS_READY BIT6\r
	162	///\r
	163	/// Write a 1 to this bit to cause the TPM to execute that command.\r
	164	///\r
	165	#define TIS_PC_STS_GO BIT5\r
	166	///\r
	167	/// This bit indicates that the TPM has data available as a response.\r
	168	///\r
	169	#define TIS_PC_STS_DATA BIT4\r
	170	///\r
	171	/// The TPM sets this bit to a value of 1 when it expects another byte of data for a command.\r
	172	///\r
	173	#define TIS_PC_STS_EXPECT BIT3\r
	174	///\r
	175	/// Writes a 1 to this bit to force the TPM to re-send the response.\r
	176	///\r
	177	#define TIS_PC_STS_RETRY BIT1\r
	178	\r
	179	//\r
	180	// Default TimeOut value\r
	181	//\r
f941becd	182	#define TIS_TIMEOUT_A 750 * 1000 // 750ms\r
0c18794e	183	#define TIS_TIMEOUT_B 2000 * 1000 // 2s\r
	184	#define TIS_TIMEOUT_C 750 * 1000 // 750ms\r
	185	#define TIS_TIMEOUT_D 750 * 1000 // 750ms\r
	186	\r
	187	//\r
	188	// Max TPM command/reponse length\r
	189	//\r
	190	#define TPMCMDBUFLENGTH 1024\r
	191	\r
	192	/**\r
	193	Check whether the value of a TPM chip register satisfies the input BIT setting.\r
	194	\r
	195	@param[in] Register Address port of register to be checked.\r
	196	@param[in] BitSet Check these data bits are set.\r
	197	@param[in] BitClear Check these data bits are clear.\r
	198	@param[in] TimeOut The max wait time (unit MicroSecond) when checking register.\r
	199	\r
	200	@retval EFI_SUCCESS The register satisfies the check bit.\r
	201	@retval EFI_TIMEOUT The register can't run into the expected status in time.\r
	202	**/\r
	203	EFI_STATUS\r
	204	EFIAPI\r
	205	TisPcWaitRegisterBits (\r
	206	IN UINT8 *Register,\r
b3548d32 LG	207	IN UINT8 BitSet,\r
	208	IN UINT8 BitClear,\r
	209	IN UINT32 TimeOut\r
0c18794e	210	);\r
	211	\r
	212	/**\r
b3548d32	213	Get BurstCount by reading the burstCount field of a TIS regiger\r
0c18794e	214	in the time of default TIS_TIMEOUT_D.\r
	215	\r
	216	@param[in] TisReg Pointer to TIS register.\r
	217	@param[out] BurstCount Pointer to a buffer to store the got BurstConut.\r
	218	\r
	219	@retval EFI_SUCCESS Get BurstCount.\r
	220	@retval EFI_INVALID_PARAMETER TisReg is NULL or BurstCount is NULL.\r
	221	@retval EFI_TIMEOUT BurstCount can't be got in time.\r
	222	**/\r
	223	EFI_STATUS\r
	224	EFIAPI\r
	225	TisPcReadBurstCount (\r
	226	IN TIS_PC_REGISTERS_PTR TisReg,\r
	227	OUT UINT16 *BurstCount\r
	228	);\r
	229	\r
	230	/**\r
b3548d32	231	Set TPM chip to ready state by sending ready command TIS_PC_STS_READY\r
0c18794e	232	to Status Register in time.\r
	233	\r
	234	@param[in] TisReg Pointer to TIS register.\r
	235	\r
	236	@retval EFI_SUCCESS TPM chip enters into ready state.\r
	237	@retval EFI_INVALID_PARAMETER TisReg is NULL.\r
	238	@retval EFI_TIMEOUT TPM chip can't be set to ready state in time.\r
	239	**/\r
	240	EFI_STATUS\r
	241	EFIAPI\r
	242	TisPcPrepareCommand (\r
	243	IN TIS_PC_REGISTERS_PTR TisReg\r
	244	);\r
	245	\r
	246	/**\r
b3548d32	247	Get the control of TPM chip by sending requestUse command TIS_PC_ACC_RQUUSE\r
0c18794e	248	to ACCESS Register in the time of default TIS_TIMEOUT_D.\r
	249	\r
	250	@param[in] TisReg Pointer to TIS register.\r
	251	\r
	252	@retval EFI_SUCCESS Get the control of TPM chip.\r
	253	@retval EFI_INVALID_PARAMETER TisReg is NULL.\r
	254	@retval EFI_NOT_FOUND TPM chip doesn't exit.\r
	255	@retval EFI_TIMEOUT Can't get the TPM control in time.\r
	256	**/\r
	257	EFI_STATUS\r
	258	EFIAPI\r
	259	TisPcRequestUseTpm (\r
	260	IN TIS_PC_REGISTERS_PTR TisReg\r
	261	);\r
	262	\r
	263	/**\r
	264	Single function calculates SHA1 digest value for all raw data. It\r
	265	combines Sha1Init(), Sha1Update() and Sha1Final().\r
	266	\r
	267	@param[in] Data Raw data to be digested.\r
	268	@param[in] DataLen Size of the raw data.\r
	269	@param[out] Digest Pointer to a buffer that stores the final digest.\r
b3548d32	270	\r
0c18794e	271	@retval EFI_SUCCESS Always successfully calculate the final digest.\r
	272	**/\r
	273	EFI_STATUS\r
	274	EFIAPI\r
	275	TpmCommHashAll (\r
	276	IN CONST UINT8 *Data,\r
	277	IN UINTN DataLen,\r
	278	OUT TPM_DIGEST *Digest\r
	279	);\r
	280	\r
	281	#endif\r