tpm: update descriptions in tpm headers

* 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@canonical.com>
Reviewed-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>
Reviewed-by: Miquel Raynal <miquel.raynal@bootlin.com>
Signed-off-by: Ilias Apalodimas <ilias.apalodimas@linaro.org>

diff --git a/include/tpm-common.h b/include/tpm-common.h
index fd33cba..bfb84a9 100644 (file)
--- a/include/tpm-common.h
+++ b/include/tpm-common.h
@@ -42,12 +42,10 @@ enum tpm_version {
        TPM_V2,
 };
 
-/*
- *  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
+ * The value 16 can be found in the current standard
+ * TCG TSS 2.0 Overview and Common Structures Specification 1.0, rev 10
  */
 #define TPM2_NUM_PCR_BANKS 16
 

diff --git a/include/tpm-v2.h b/include/tpm-v2.h
index 6e9bc79..6568146 100644 (file)
--- 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/
  *
  * Author: Miquel Raynal <miquel.raynal@bootlin.com>
@@ -45,20 +50,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];