Skip to contentSkip to conversation

Documentation: tpm_tis

PATCH Superseded Jarkko Sakkinen 1 participant 3 messages Mar 21, 2024

Subsystems (3)

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore

Jarkko Sakkinen

author maintainer
#0 lore raw

PATCH v3 1/1 Documentation: tpm_tis

Based recent discussions on LKML, provide preliminary bits of tpm_tis_core dependent drivers. Includes only bare essentials but can be extended later on case by case. This way some people may even want to read it later on.

Cc Jonathan Corbet <[email protected]>
CC Daniel P. Smith <[email protected]>
Cc Lino Sanfilippo <[email protected]>
Cc Jason Gunthorpe <[email protected]>
Cc Peter Huewe <[email protected]>
Cc James Bottomley <[email protected]>
Cc Alexander Steffen <[email protected]>

---
v3:
- Fixed incorrect buffer size:
https://lore.kernel.org/linux-integrity/[email protected]/
v2:
- Fixed errors reported by Randy:
https://lore.kernel.org/all/[email protected]/
- Improved the text a bit to have a better presentation.

---
 Documentation/security/tpm/index.rst   |  1 +
 Documentation/security/tpm/tpm_tis.rst | 30 ++++++++++++++++++++++++++
 2 files changed, 31 insertions(+)
 create mode 100644 Documentation/security/tpm/tpm_tis.rst
Documentation/security/tpm/index.rst +1 -0
index fc40e9f23c85..f27a17f60a96 100644
@@ -5,6 +5,7 @@ Trusted Platform Module documentation
 .. toctree::
 
    tpm_event_log
+   tpm_tis
    tpm_vtpm_proxy
    xen-tpmfront
    tpm_ftpm_tee
Documentation/security/tpm/tpm_tis.rst new file +30 -0
new file mode 100644
index 000000000000..078b75666086
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+=========================
+TPM FIFO interface Driver
+=========================
+
+FIFO (First-In-First-Out) is the name of the hardware interface used by the
+tpm_tis_core dependent drivers. The prefix "tis" comes from the TPM Interface
+Specification, which is the hardware interface specification for TPM 1.x chips.
+
+Communication is based on a 20 KiB buffer shared by the TPM chip through a
+hardware bus or memory map, depending on the physical wiring. The buffer is
+further split into five equal-size 4 KiB buffers, which provide equivalent
+sets of registers for communication between the CPU and TPM. These
+communication endpoints are called localities in the TCG terminology.
+
+When the kernel wants to send commands to the TPM chip, it first reserves
+locality 0 by setting the requestUse bit in the TPM_ACCESS register. The bit is
+cleared by the chip when the access is granted. Once it completes its
+communication, the kernel writes the TPM_ACCESS.activeLocality bit. This
+informs the chip that the locality has been relinquished.
+
+Pending localities are served in order by the chip in descending order, one at
+a time:
+
+- Locality 0 has the lowest priority.
+- Locality 5 has the highest priority.
+
+Further information on the purpose and meaning of the localities can be found
+in section 3.2 of the TCG PC Client Platform TPM Profile Specification.
Signature · 1 line
2.43.0
author maintainer
#1 lore raw
Quoted 3 lines · Jarkko Sakkinen

Based recent discussions on LKML, provide preliminary bits of tpm_tis_core dependent drivers. Includes only bare essentials but can be extended later on case by case. This way some people may even want to read it later on.

$ pdftotext PC-Client-Specific-Platform-TPM-Profile-for-TPM-2p0-v1p05p_r14_pub.pdf
$ grep -ci 'FIFO interface' PC-Client-Specific-Platform-TPM-Profile-for-TPM-2p0-v1p05p_r14_pub.txt 
55
$ grep -ci 'TIS interface' PC-Client-Specific-Platform-TPM-Profile-for-TPM-2p0-v1p05p_r14_pub.txt
2

55 > 2 so that pretty much nails this terminology.

BR, Jarkko

author maintainer
#2 lore raw
Quoted 5 lines · Jarkko Sakkinen
Quoted 3 lines · Jarkko Sakkinen

Based recent discussions on LKML, provide preliminary bits of tpm_tis_core dependent drivers. Includes only bare essentials but can be extended later on case by case. This way some people may even want to read it later on.

Quoted 8 lines
$ pdftotext PC-Client-Specific-Platform-TPM-Profile-for-TPM-2p0-v1p05p_r14_pub.pdf
$ grep -ci 'FIFO interface' PC-Client-Specific-Platform-TPM-Profile-for-TPM-2p0-v1p05p_r14_pub.txt 
55
$ grep -ci 'TIS interface' PC-Client-Specific-Platform-TPM-Profile-for-TPM-2p0-v1p05p_r14_pub.txt
2

55 > 2 so that pretty much nails this terminology.

To add, this documentation *clears* the confusion in "FIFO vs TIS" by documenting where TIS comes from (i.e. from the original TPM Interface Spefication).

If you read the current standards you bump quite often (55 times in the current spec) to FIFO interface, so it is good to clarify their relation in the kernel documentation.

BR, Jarkko