Received-SPF: pass (google.com: domain of linux-kernel+bounces-110282-linux.lists.archive=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223;
Precedence: bulk
Mime-Version: 1.0
Content-Transfer-Encoding: quoted-printable
Content-Type: text/plain; charset=UTF-8
Date: Thu, 21 Mar 2024 17:51:27 +0200
Message-Id: <CZZJQR121P7H.3QS68A6320S32@kernel.org>
Cc: "Jonathan Corbet" <corbet@lwn.net>, "Daniel P . Smith"
 <dpsmith@apertussolutions.com>, "Lino Sanfilippo"
 <l.sanfilippo@kunbus.com>, "Jason Gunthorpe" <jgg@ziepe.ca>, "Peter Huewe"
 <peterhuewe@gmx.de>, "James Bottomley"
 <James.Bottomley@HansenPartnership.com>, "Alexander Steffen"
 <Alexander.Steffen@infineon.com>, <keyrings@vger.kernel.org>,
 <linux-doc@vger.kernel.org>, <linux-kernel@vger.kernel.org>, "Randy Dunlap"
 <rdunlap@infradead.org>
Subject: Re: [PATCH v2] Documentation: tpm_tis
From: "Jarkko Sakkinen" <jarkko@kernel.org>
To: "Stefan Berger" <stefanb@linux.ibm.com>,
 <linux-integrity@vger.kernel.org>
References: <20240320085601.40450-1-jarkko@kernel.org>
 <afc9471c-1c28-4384-82c1-29464ca1fb1f@linux.ibm.com>
In-Reply-To: <afc9471c-1c28-4384-82c1-29464ca1fb1f@linux.ibm.com>

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_c=
ore
> > dependent drivers. Includes only bare essentials but can be extended la=
ter
> > on case by case. This way some people may even want to read it later on=
.
> >=20
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > CC: Daniel P. Smith <dpsmith@apertussolutions.com>
> > Cc: Lino Sanfilippo <l.sanfilippo@kunbus.com>
> > Cc: Jason Gunthorpe <jgg@ziepe.ca>
> > Cc: Peter Huewe <peterhuewe@gmx.de>
> > Cc: James Bottomley <James.Bottomley@HansenPartnership.com>
> > Cc: Alexander Steffen <Alexander.Steffen@infineon.com>
> > Cc: keyrings@vger.kernel.org
> > Cc: linux-doc@vger.kernel.org
> > Cc: linux-kernel@vger.kernel.org
> > Cc: linux-integrity@vger.kernel.org
> > Cc: Randy Dunlap <rdunlap@infradead.org>
> > Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>
> > ---
> > v2:
> > - Fixed errors reported by Randy:
> >    https://lore.kernel.org/all/aed28265-d677-491a-a045-24b351854b24@inf=
radead.org/
> > - 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
> >=20
> > diff --git a/Documentation/security/tpm/index.rst b/Documentation/secur=
ity/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::
> >  =20
> >      tpm_event_log
> > +   tpm_tis
> >      tpm_vtpm_proxy
> >      xen-tpmfront
> >      tpm_ftpm_tee
> > diff --git a/Documentation/security/tpm/tpm_tis.rst b/Documentation/sec=
urity/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
> > +
> > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D
> > +TPM FIFO interface Driver
> > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D
> > +
> > +FIFO (First-In-First-Out) is the name of the hardware interface used b=
y the
>
> FIFO is the type. I am surprised you call it a 'name'. I would say TIS=20
> is the 'name'.

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


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

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.
=20
Yes, but TIS is the name used by the legacy specification.

>
> > +
> > +Communication is based on a 5 KiB buffer shared by the TPM chip throug=
h 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 buff=
er is
> > +further split into five equal-size buffers, which provide equivalent s=
ets 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 communicati=
on
> > +endpoints are called localities in the TCG terminology.
> > +
> > +When the kernel wants to send commands to the TPM chip, it first reser=
ves
> > +locality 0 by setting the requestUse bit in the TPM_ACCESS register. T=
he bit is
> > +cleared by the chip when the access is granted. Once it completes its
> > +communication, the kernel writes the TPM_ACCESS.activeLocality bit. Th=
is
> > +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=20
> this device but I am not sure whether the user can deduce this from the=
=20
> paragraph above. Also, why this particular detail when the driver only=20
> 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 b=
e found
> > +in section 3.2 of the TCG PC Client Platform TPM Profile Specification=
.
o


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

BR, Jarkko