[PATCH 1/1] tpm: update descriptions in tpm-v2.h header

[Ilias Apalodimas]

Thanks Heinrich,

On Wed, 25 Dec 2024 at 00:00, Heinrich Schuchardt
<heinrich.schuchardt at canonical.com> wrote:
>
> * Provide a link to 'TPM 2.0 Library Specification'
> * Remove outdated comment for TPM2_NUM_PCR_BANKS.
>   The value 16 can be found in the current standard
>   TCG TSS 2.0 Overview and Common Structures Specification 1.0, rev 10
> * Describe some of the structures in Sphinx style.
>
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt at canonical.com>
> ---
>  include/tpm-v2.h | 42 +++++++++++++++++++++++++++++++++---------
>  1 file changed, 33 insertions(+), 9 deletions(-)
>
> diff --git a/include/tpm-v2.h b/include/tpm-v2.h
> index 4fd19c52fd7..0f388b26496 100644
> --- a/include/tpm-v2.h
> +++ b/include/tpm-v2.h
> @@ -6,6 +6,11 @@
>   * Copyright (c) 2020 Linaro
>   * Copyright (c) 2018 Bootlin
>   *
> + * The structures are described in
> + * Trusted Platform Module Library Part 2: Structures
> + * http://tcg.tjn.chef.causewaynow.com/resource/tpm-library-specification/
> + *
> + * C header files are listed in
>   * https://trustedcomputinggroup.org/resource/tss-overview-common-structures-specification/

We already define that a few lines above
>   *
>   * Author: Miquel Raynal <miquel.raynal at bootlin.com>
> @@ -34,12 +39,8 @@ struct udevice;
>
>  #define TPM2_HDR_LEN           10
>
> -/*
> - *  We deviate from this draft of the specification by increasing the value of
> - *  TPM2_NUM_PCR_BANKS from 3 to 16 to ensure compatibility with TPM2
> - *  implementations that have enabled a larger than typical number of PCR
> - *  banks. This larger value for TPM2_NUM_PCR_BANKS is expected to be included
> - *  in a future revision of the specification.
> +/**
> + * define TPM2_NUM_PCR_BANKS - number of PCR banks
>   */
>  #define TPM2_NUM_PCR_BANKS 16
>
> @@ -55,20 +56,43 @@ struct udevice;
>  #define TPM2_PT_MAX_COMMAND_SIZE       (u32)(TPM2_PT_FIXED + 30)
>  #define TPM2_PT_MAX_RESPONSE_SIZE      (u32)(TPM2_PT_FIXED + 31)
>
> -/* TPMS_TAGGED_PROPERTY Structure */
> +/**
> + * struct tpms_tagged_property - TPMS_TAGGED_PROPERTY structure
> + *
> + * This structure is returned by TPM2_GetCapability() to report
> + * a u32 property value.
> + *
> + * @property:  property identifier
> + * @value:     value of the property
> + */
>  struct tpms_tagged_property {
>         u32 property;
>         u32 value;
>  } __packed;
>
> -/* TPMS_PCR_SELECTION Structure */
> +/**
> + * struct tpms_pcr_selection - TPMS_PCR_SELECTION structure
> + *
> + * This structure allows to specify a hash algorithm and a list of
> + * selected PCRs. A PCR is selected by setting the related bit in
> + * @pcr_select to 1.
> + *
> + * @hash:              hash algorithm associated with the selection
> + * @size_of_select:    size in bytes of the @pcr_select array
> + * @pcr_select:                bit map of selected PCRs
> + */
>  struct tpms_pcr_selection {
>         u16 hash;
>         u8 size_of_select;
>         u8 pcr_select[TPM2_PCR_SELECT_MAX];
>  } __packed;
>
> -/* TPML_PCR_SELECTION Structure */
> +/**
> + * struct tpml_pcr_selection - TPML_PCR_SELECTION structure
> + *
> + * @count:     number of selection structures, may be zero
> + * @selection: list of selections
> + */
>  struct tpml_pcr_selection {
>         u32 count;
>         struct tpms_pcr_selection selection[TPM2_NUM_PCR_BANKS];
> --
> 2.47.1
>

Reviewed-by: Ilias Apalodimas <ilias.apalodimas at linaro.org>