[v2] Documentation: tpm_tis

Commit Message

Jarkko Sakkinen March 20, 2024, 8:56 a.m. UTC

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 <[e-mail]>
CC: Daniel P. Smith <[e-mail]>
Cc: Lino Sanfilippo <[e-mail]>
Cc: Jason Gunthorpe <[e-mail]>
Cc: Peter Huewe <[e-mail]>
Cc: James Bottomley <[e-mail]>
Cc: Alexander Steffen <[e-mail]>
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: [e-mail]
Cc: Randy Dunlap <[e-mail]>
Signed-off-by: Jarkko Sakkinen <[e-mail]>
---
v2:
- Fixed errors reported by Randy:
  https://lore.kernel.org/all/[e-mail]/
- 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

Comments

Randy Dunlap March 20, 2024, 2:27 p.m. UTC | #1

Hi,

On 3/20/24 01:56, Jarkko Sakkinen wrote:
> 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 <[e-mail]>
> CC: Daniel P. Smith <[e-mail]>
> Cc: Lino Sanfilippo <[e-mail]>
> Cc: Jason Gunthorpe <[e-mail]>
> Cc: Peter Huewe <[e-mail]>
> Cc: James Bottomley <[e-mail]>
> Cc: Alexander Steffen <[e-mail]>
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: Randy Dunlap <[e-mail]>
> Signed-off-by: Jarkko Sakkinen <[e-mail]>

Makes sense to me. Thanks.

Reviewed-by: Randy Dunlap <[e-mail]>

> ---
> v2:
> - Fixed errors reported by Randy:
>   https://lore.kernel.org/all/[e-mail]/
> - 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
> 
> diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
> index fc40e9f23c85..f27a17f60a96 100644
> --- a/Documentation/security/tpm/index.rst
> +++ b/Documentation/security/tpm/index.rst
> @@ -5,6 +5,7 @@ Trusted Platform Module documentation
>  .. toctree::
>  
>     tpm_event_log
> +   tpm_tis
>     tpm_vtpm_proxy
>     xen-tpmfront
>     tpm_ftpm_tee
> diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> new file mode 100644
> index 000000000000..b331813b3c45
> --- /dev/null
> +++ b/Documentation/security/tpm/tpm_tis.rst
> @@ -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 5 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 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.

Stefan Berger March 20, 2024, 4:15 p.m. UTC | #2

On 3/20/24 04:56, Jarkko Sakkinen wrote:
> 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 <[e-mail]>
> CC: Daniel P. Smith <[e-mail]>
> Cc: Lino Sanfilippo <[e-mail]>
> Cc: Jason Gunthorpe <[e-mail]>
> Cc: Peter Huewe <[e-mail]>
> Cc: James Bottomley <[e-mail]>
> Cc: Alexander Steffen <[e-mail]>
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: [e-mail]
> Cc: Randy Dunlap <[e-mail]>
> Signed-off-by: Jarkko Sakkinen <[e-mail]>
> ---
> v2:
> - Fixed errors reported by Randy:
>    https://lore.kernel.org/all/[e-mail]/
> - 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
> 
> diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
> index fc40e9f23c85..f27a17f60a96 100644
> --- a/Documentation/security/tpm/index.rst
> +++ b/Documentation/security/tpm/index.rst
> @@ -5,6 +5,7 @@ Trusted Platform Module documentation
>   .. toctree::
>   
>      tpm_event_log
> +   tpm_tis
>      tpm_vtpm_proxy
>      xen-tpmfront
>      tpm_ftpm_tee
> diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> new file mode 100644
> index 000000000000..b331813b3c45
> --- /dev/null
> +++ b/Documentation/security/tpm/tpm_tis.rst
> @@ -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

FIFO is the type. I am surprised you call it a 'name'. I would say TIS 
is the 'name'.

> +tpm_tis_core dependent drivers. The prefix "tis" comes from the TPM Interface

tis is a tla -- a three letter *acronym*. You aren't using it as a 'prefix'.

> +Specification, which is the hardware interface specification for TPM 1.x chips.

It's also available for TPM2.

> +
> +Communication is based on a 5 KiB buffer shared by the TPM chip through a

I thought it was typically 4 KiB.

> +hardware bus or memory map, depending on the physical wiring. The buffer is
> +further split into five equal-size buffers, which provide equivalent sets of

equal-sized MMIO regions?

> +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:

I think I know what pending localities are because I have worked with 
this device but I am not sure whether the user can deduce this from the 
paragraph above. Also, why this particular detail when the driver only 
uses locality 0 and nobody is competing about access to localities?

> +
> +- 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.

Jarkko Sakkinen March 21, 2024, 3:51 p.m. UTC | #3

On Wed Mar 20, 2024 at 6:15 PM EET, Stefan Berger wrote:
>
>
> On 3/20/24 04:56, Jarkko Sakkinen wrote:
> > 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 <[e-mail]>
> > CC: Daniel P. Smith <[e-mail]>
> > Cc: Lino Sanfilippo <[e-mail]>
> > Cc: Jason Gunthorpe <[e-mail]>
> > Cc: Peter Huewe <[e-mail]>
> > Cc: James Bottomley <[e-mail]>
> > Cc: Alexander Steffen <[e-mail]>
> > Cc: [e-mail]
> > Cc: [e-mail]
> > Cc: [e-mail]
> > Cc: [e-mail]
> > Cc: Randy Dunlap <[e-mail]>
> > Signed-off-by: Jarkko Sakkinen <[e-mail]>
> > ---
> > v2:
> > - Fixed errors reported by Randy:
> >    https://lore.kernel.org/all/[e-mail]/
> > - 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
> > 
> > diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
> > index fc40e9f23c85..f27a17f60a96 100644
> > --- a/Documentation/security/tpm/index.rst
> > +++ b/Documentation/security/tpm/index.rst
> > @@ -5,6 +5,7 @@ Trusted Platform Module documentation
> >   .. toctree::
> >   
> >      tpm_event_log
> > +   tpm_tis
> >      tpm_vtpm_proxy
> >      xen-tpmfront
> >      tpm_ftpm_tee
> > diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> > new file mode 100644
> > index 000000000000..b331813b3c45
> > --- /dev/null
> > +++ b/Documentation/security/tpm/tpm_tis.rst
> > @@ -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
>
> FIFO is the type. I am surprised you call it a 'name'. I would say TIS 
> is the 'name'.

It's what the official specification calls it [1].


>
> > +tpm_tis_core dependent drivers. The prefix "tis" comes from the TPM Interface
>
> tis is a tla -- a three letter *acronym*. You aren't using it as a 'prefix'.

I don't know what "tla" means.

>
> > +Specification, which is the hardware interface specification for TPM 1.x chips.
>
> It's also available for TPM2.
 
Yes, but TIS is the name used by the legacy specification.

>
> > +
> > +Communication is based on a 5 KiB buffer shared by the TPM chip through a
>
> I thought it was typically 4 KiB.

You are basing this on table 9 in [1]?

>
> > +hardware bus or memory map, depending on the physical wiring. The buffer is
> > +further split into five equal-size buffers, which provide equivalent sets of
>
> equal-sized MMIO regions?

I'm not sure what spec you are referring to but [1] defines also other
communication paths.

>
> > +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:
>
> I think I know what pending localities are because I have worked with 
> this device but I am not sure whether the user can deduce this from the 
> paragraph above. Also, why this particular detail when the driver only 
> uses locality 0 and nobody is competing about access to localities?

This is pretty good summary that is IMHO somewhat useful.

You are welcome to contribute to the documentation but it has to start
from something.

>
> > +
> > +- 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.
o


[1] https://trustedcomputinggroup.org/resource/pc-client-platform-tpm-profile-ptp-specification/

BR, Jarkko

Jarkko Sakkinen March 21, 2024, 3:55 p.m. UTC | #4

On Wed Mar 20, 2024 at 4:27 PM EET, Randy Dunlap wrote:
> Hi,
>
> On 3/20/24 01:56, Jarkko Sakkinen wrote:
> > 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 <[e-mail]>
> > CC: Daniel P. Smith <[e-mail]>
> > Cc: Lino Sanfilippo <[e-mail]>
> > Cc: Jason Gunthorpe <[e-mail]>
> > Cc: Peter Huewe <[e-mail]>
> > Cc: James Bottomley <[e-mail]>
> > Cc: Alexander Steffen <[e-mail]>
> > Cc: [e-mail]
> > Cc: [e-mail]
> > Cc: [e-mail]
> > Cc: [e-mail]
> > Cc: Randy Dunlap <[e-mail]>
> > Signed-off-by: Jarkko Sakkinen <[e-mail]>
>
> Makes sense to me. Thanks.
>
> Reviewed-by: Randy Dunlap <[e-mail]>

Good to hear, I tried to write a summary that makes common sense :-)

Thanks for the review!

BR, Jarkko

Stefan Berger March 21, 2024, 4:09 p.m. UTC | #5

On 3/21/24 11:51, Jarkko Sakkinen wrote:
> On Wed Mar 20, 2024 at 6:15 PM EET, Stefan Berger wrote:
>>
>>
>> On 3/20/24 04:56, Jarkko Sakkinen wrote:
>>> 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 <[e-mail]>
>>> CC: Daniel P. Smith <[e-mail]>
>>> Cc: Lino Sanfilippo <[e-mail]>
>>> Cc: Jason Gunthorpe <[e-mail]>
>>> Cc: Peter Huewe <[e-mail]>
>>> Cc: James Bottomley <[e-mail]>
>>> Cc: Alexander Steffen <[e-mail]>
>>> Cc: [e-mail]
>>> Cc: [e-mail]
>>> Cc: [e-mail]
>>> Cc: [e-mail]
>>> Cc: Randy Dunlap <[e-mail]>
>>> Signed-off-by: Jarkko Sakkinen <[e-mail]>
>>> ---
>>> v2:
>>> - Fixed errors reported by Randy:
>>>     https://lore.kernel.org/all/[e-mail]/
>>> - 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
>>>
>>> diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
>>> index fc40e9f23c85..f27a17f60a96 100644
>>> --- a/Documentation/security/tpm/index.rst
>>> +++ b/Documentation/security/tpm/index.rst
>>> @@ -5,6 +5,7 @@ Trusted Platform Module documentation
>>>    .. toctree::
>>>    
>>>       tpm_event_log
>>> +   tpm_tis
>>>       tpm_vtpm_proxy
>>>       xen-tpmfront
>>>       tpm_ftpm_tee
>>> diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
>>> new file mode 100644
>>> index 000000000000..b331813b3c45
>>> --- /dev/null
>>> +++ b/Documentation/security/tpm/tpm_tis.rst
>>> @@ -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
>>
>> FIFO is the type. I am surprised you call it a 'name'. I would say TIS
>> is the 'name'.
> 
> It's what the official specification calls it [1].
> 
> 
>>
>>> +tpm_tis_core dependent drivers. The prefix "tis" comes from the TPM Interface
>>
>> tis is a tla -- a three letter *acronym*. You aren't using it as a 'prefix'.
> 
> I don't know what "tla" means.
> 
>>
>>> +Specification, which is the hardware interface specification for TPM 1.x chips.
>>
>> It's also available for TPM2.
>   
> Yes, but TIS is the name used by the legacy specification.


The point is that TIS is not just a TPM 1.x interface but also used for 
TPM 2.
> 
>>
>>> +
>>> +Communication is based on a 5 KiB buffer shared by the TPM chip through a
>>
>> I thought it was typically 4 KiB.
> 
> You are basing this on table 9 in [1]?

Yes. See below.

> 
>>
>>> +hardware bus or memory map, depending on the physical wiring. The buffer is
>>> +further split into five equal-size buffers, which provide equivalent sets of

If you are referring to the MMIO region between 0xfed4 0000 and 0xfed4 
4fff as a buffer then you are talking about a **20kb** MMIO region 
(0x5000) that is **split** into equal-sized MMIO regions, each having 
4kb (0x1000). Yes, that's the 4kb then but there that one is no 5kb 
'further split into five equal-sized buffers' of presumably 1kb each. 
Each locality has a 0x1000 sized MMIO region.

Jarkko Sakkinen March 21, 2024, 4:24 p.m. UTC | #6

On Thu Mar 21, 2024 at 6:09 PM EET, Stefan Berger wrote:
>
>
> On 3/21/24 11:51, Jarkko Sakkinen wrote:
> > On Wed Mar 20, 2024 at 6:15 PM EET, Stefan Berger wrote:
> >>
> >>
> >> On 3/20/24 04:56, Jarkko Sakkinen wrote:
> >>> 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 <[e-mail]>
> >>> CC: Daniel P. Smith <[e-mail]>
> >>> Cc: Lino Sanfilippo <[e-mail]>
> >>> Cc: Jason Gunthorpe <[e-mail]>
> >>> Cc: Peter Huewe <[e-mail]>
> >>> Cc: James Bottomley <[e-mail]>
> >>> Cc: Alexander Steffen <[e-mail]>
> >>> Cc: [e-mail]
> >>> Cc: [e-mail]
> >>> Cc: [e-mail]
> >>> Cc: [e-mail]
> >>> Cc: Randy Dunlap <[e-mail]>
> >>> Signed-off-by: Jarkko Sakkinen <[e-mail]>
> >>> ---
> >>> v2:
> >>> - Fixed errors reported by Randy:
> >>>     https://lore.kernel.org/all/[e-mail]/
> >>> - 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
> >>>
> >>> diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
> >>> index fc40e9f23c85..f27a17f60a96 100644
> >>> --- a/Documentation/security/tpm/index.rst
> >>> +++ b/Documentation/security/tpm/index.rst
> >>> @@ -5,6 +5,7 @@ Trusted Platform Module documentation
> >>>    .. toctree::
> >>>    
> >>>       tpm_event_log
> >>> +   tpm_tis
> >>>       tpm_vtpm_proxy
> >>>       xen-tpmfront
> >>>       tpm_ftpm_tee
> >>> diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> >>> new file mode 100644
> >>> index 000000000000..b331813b3c45
> >>> --- /dev/null
> >>> +++ b/Documentation/security/tpm/tpm_tis.rst
> >>> @@ -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
> >>
> >> FIFO is the type. I am surprised you call it a 'name'. I would say TIS
> >> is the 'name'.
> > 
> > It's what the official specification calls it [1].
> > 
> > 
> >>
> >>> +tpm_tis_core dependent drivers. The prefix "tis" comes from the TPM Interface
> >>
> >> tis is a tla -- a three letter *acronym*. You aren't using it as a 'prefix'.
> > 
> > I don't know what "tla" means.
> > 
> >>
> >>> +Specification, which is the hardware interface specification for TPM 1.x chips.
> >>
> >> It's also available for TPM2.
> >   
> > Yes, but TIS is the name used by the legacy specification.
>
>
> The point is that TIS is not just a TPM 1.x interface but also used for 
> TPM 2.


FIFO interface is what is  used in the spec so I'll stick to that.

> > 
> >>
> >>> +
> >>> +Communication is based on a 5 KiB buffer shared by the TPM chip through a
> >>
> >> I thought it was typically 4 KiB.
> > 
> > You are basing this on table 9 in [1]?
>
> Yes. See below.
>
> > 
> >>
> >>> +hardware bus or memory map, depending on the physical wiring. The buffer is
> >>> +further split into five equal-size buffers, which provide equivalent sets of
>
> If you are referring to the MMIO region between 0xfed4 0000 and 0xfed4 
> 4fff as a buffer then you are talking about a **20kb** MMIO region 
> (0x5000) that is **split** into equal-sized MMIO regions, each having 
> 4kb (0x1000). Yes, that's the 4kb then but there that one is no 5kb 
> 'further split into five equal-sized buffers' of presumably 1kb each. 
> Each locality has a 0x1000 sized MMIO region.

Oops, true! I'll fix this part thanks, had a blind spot :-)

Will fix for v3.

BR, Jarkko

Jarkko Sakkinen March 21, 2024, 4:32 p.m. UTC | #7

On Thu Mar 21, 2024 at 6:24 PM EET, Jarkko Sakkinen wrote:
> On Thu Mar 21, 2024 at 6:09 PM EET, Stefan Berger wrote:
> >
> >
> > On 3/21/24 11:51, Jarkko Sakkinen wrote:
> > > On Wed Mar 20, 2024 at 6:15 PM EET, Stefan Berger wrote:
> > >>
> > >>
> > >> On 3/20/24 04:56, Jarkko Sakkinen wrote:
> > >>> 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 <[e-mail]>
> > >>> CC: Daniel P. Smith <[e-mail]>
> > >>> Cc: Lino Sanfilippo <[e-mail]>
> > >>> Cc: Jason Gunthorpe <[e-mail]>
> > >>> Cc: Peter Huewe <[e-mail]>
> > >>> Cc: James Bottomley <[e-mail]>
> > >>> Cc: Alexander Steffen <[e-mail]>
> > >>> Cc: [e-mail]
> > >>> Cc: [e-mail]
> > >>> Cc: [e-mail]
> > >>> Cc: [e-mail]
> > >>> Cc: Randy Dunlap <[e-mail]>
> > >>> Signed-off-by: Jarkko Sakkinen <[e-mail]>
> > >>> ---
> > >>> v2:
> > >>> - Fixed errors reported by Randy:
> > >>>     https://lore.kernel.org/all/[e-mail]/
> > >>> - 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
> > >>>
> > >>> diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
> > >>> index fc40e9f23c85..f27a17f60a96 100644
> > >>> --- a/Documentation/security/tpm/index.rst
> > >>> +++ b/Documentation/security/tpm/index.rst
> > >>> @@ -5,6 +5,7 @@ Trusted Platform Module documentation
> > >>>    .. toctree::
> > >>>    
> > >>>       tpm_event_log
> > >>> +   tpm_tis
> > >>>       tpm_vtpm_proxy
> > >>>       xen-tpmfront
> > >>>       tpm_ftpm_tee
> > >>> diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> > >>> new file mode 100644
> > >>> index 000000000000..b331813b3c45
> > >>> --- /dev/null
> > >>> +++ b/Documentation/security/tpm/tpm_tis.rst
> > >>> @@ -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
> > >>
> > >> FIFO is the type. I am surprised you call it a 'name'. I would say TIS
> > >> is the 'name'.
> > > 
> > > It's what the official specification calls it [1].
> > > 
> > > 
> > >>
> > >>> +tpm_tis_core dependent drivers. The prefix "tis" comes from the TPM Interface
> > >>
> > >> tis is a tla -- a three letter *acronym*. You aren't using it as a 'prefix'.
> > > 
> > > I don't know what "tla" means.
> > > 
> > >>
> > >>> +Specification, which is the hardware interface specification for TPM 1.x chips.
> > >>
> > >> It's also available for TPM2.
> > >   
> > > Yes, but TIS is the name used by the legacy specification.
> >
> >
> > The point is that TIS is not just a TPM 1.x interface but also used for 
> > TPM 2.
>
>
> FIFO interface is what is  used in the spec so I'll stick to that.

E.g. Table 15 - *FIFO* Interface Identifier Register

Not *TIS* Inteface Identifier Register.

I don't want to invent my own terminology here and this the spec
that we usually refer in every possible discussion around the topic.

BR, Jarkko

Jarkko Sakkinen March 21, 2024, 4:35 p.m. UTC | #8

On Thu Mar 21, 2024 at 6:32 PM EET, Jarkko Sakkinen wrote:
> On Thu Mar 21, 2024 at 6:24 PM EET, Jarkko Sakkinen wrote:
> > On Thu Mar 21, 2024 at 6:09 PM EET, Stefan Berger wrote:
> > >
> > >
> > > On 3/21/24 11:51, Jarkko Sakkinen wrote:
> > > > On Wed Mar 20, 2024 at 6:15 PM EET, Stefan Berger wrote:
> > > >>
> > > >>
> > > >> On 3/20/24 04:56, Jarkko Sakkinen wrote:
> > > >>> 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 <[e-mail]>
> > > >>> CC: Daniel P. Smith <[e-mail]>
> > > >>> Cc: Lino Sanfilippo <[e-mail]>
> > > >>> Cc: Jason Gunthorpe <[e-mail]>
> > > >>> Cc: Peter Huewe <[e-mail]>
> > > >>> Cc: James Bottomley <[e-mail]>
> > > >>> Cc: Alexander Steffen <[e-mail]>
> > > >>> Cc: [e-mail]
> > > >>> Cc: [e-mail]
> > > >>> Cc: [e-mail]
> > > >>> Cc: [e-mail]
> > > >>> Cc: Randy Dunlap <[e-mail]>
> > > >>> Signed-off-by: Jarkko Sakkinen <[e-mail]>
> > > >>> ---
> > > >>> v2:
> > > >>> - Fixed errors reported by Randy:
> > > >>>     https://lore.kernel.org/all/[e-mail]/
> > > >>> - 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
> > > >>>
> > > >>> diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
> > > >>> index fc40e9f23c85..f27a17f60a96 100644
> > > >>> --- a/Documentation/security/tpm/index.rst
> > > >>> +++ b/Documentation/security/tpm/index.rst
> > > >>> @@ -5,6 +5,7 @@ Trusted Platform Module documentation
> > > >>>    .. toctree::
> > > >>>    
> > > >>>       tpm_event_log
> > > >>> +   tpm_tis
> > > >>>       tpm_vtpm_proxy
> > > >>>       xen-tpmfront
> > > >>>       tpm_ftpm_tee
> > > >>> diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
> > > >>> new file mode 100644
> > > >>> index 000000000000..b331813b3c45
> > > >>> --- /dev/null
> > > >>> +++ b/Documentation/security/tpm/tpm_tis.rst
> > > >>> @@ -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
> > > >>
> > > >> FIFO is the type. I am surprised you call it a 'name'. I would say TIS
> > > >> is the 'name'.
> > > > 
> > > > It's what the official specification calls it [1].
> > > > 
> > > > 
> > > >>
> > > >>> +tpm_tis_core dependent drivers. The prefix "tis" comes from the TPM Interface
> > > >>
> > > >> tis is a tla -- a three letter *acronym*. You aren't using it as a 'prefix'.
> > > > 
> > > > I don't know what "tla" means.
> > > > 
> > > >>
> > > >>> +Specification, which is the hardware interface specification for TPM 1.x chips.
> > > >>
> > > >> It's also available for TPM2.
> > > >   
> > > > Yes, but TIS is the name used by the legacy specification.
> > >
> > >
> > > The point is that TIS is not just a TPM 1.x interface but also used for 
> > > TPM 2.
> >
> >
> > FIFO interface is what is  used in the spec so I'll stick to that.
>
> E.g. Table 15 - *FIFO* Interface Identifier Register
>
> Not *TIS* Inteface Identifier Register.
>
> I don't want to invent my own terminology here and this the spec
> that we usually refer in every possible discussion around the topic.

That table actually also clarifies this pretty well, see interface type:

0000 – FIFO interface as defined in PTP for TPM 2.0 is active.
0001 – CRB interface is active.
1111 – FIFO interface as defined in TIS1.3 is active (all other fields
of this register are don’t care).

E.g. FIFO interface can be configured according to TIS 1.3 specification
but the interface is still referred as FIFO interface in the current
spec.

BR, Jarkko

Patch

diff --git a/Documentation/security/tpm/index.rst b/Documentation/security/tpm/index.rst
index fc40e9f23c85..f27a17f60a96 100644
--- a/Documentation/security/tpm/index.rst
+++ b/Documentation/security/tpm/index.rst
@@ -5,6 +5,7 @@  Trusted Platform Module documentation
 .. toctree::
 
    tpm_event_log
+   tpm_tis
    tpm_vtpm_proxy
    xen-tpmfront
    tpm_ftpm_tee
diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/security/tpm/tpm_tis.rst
new file mode 100644
index 000000000000..b331813b3c45
--- /dev/null
+++ b/Documentation/security/tpm/tpm_tis.rst
@@ -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 5 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 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.