dsp: firmware_update: Document package format pin metadata
The magic and version fields of the pin struct were some what cryptic
while also being fundamental to the correctness of the implementation.
Improve the documentation.
Change-Id: I0c3e1c0169719ee0ad6442e426e533e55fd08d15
Signed-off-by: Andrew Jeffery <andrew@codeconstruct.com.au>
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 26a9ac8..a7e04fc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,7 @@
### Changed
- Stabilised `decode_get_event_receiver_resp()`
+- Improved documentation of `struct pldm_package_format_pin`
### Deprecated
diff --git a/include/libpldm/firmware_update.h b/include/libpldm/firmware_update.h
index cdf4c6b..2143c44 100644
--- a/include/libpldm/firmware_update.h
+++ b/include/libpldm/firmware_update.h
@@ -2181,29 +2181,50 @@
/** @brief Firmware update v1.1 package header format revision */
#define PLDM_PACKAGE_HEADER_FORMAT_REVISION_FR02H 0x02
-/** @brief Client-side version pinning for package format parsing
+/** @brief Consumer-side version pinning for package format parsing
*
* Parsing a firmware update package requires the package to be of a revision
* defined in the specification, for libpldm to support parsing a package
- * formatted at the specified revision, and for the client to support calling
+ * formatted at the specified revision, and for the consumer to support calling
* libpldm's package-parsing APIs in the manner required for the package format.
*
* pldm_package_format_pin communicates to libpldm the maximum package format
- * revision supported by the client.
+ * revision supported by the consumer.
*
- * The definition of the pldm_package_format_pin object in the client
+ * The definition of the pldm_package_format_pin object in the consumer
* application should not be open-coded. Instead, users should call on of the
* following macros:
*
* - @ref DEFINE_PLDM_PACKAGE_FORMAT_PIN_FR01H
* - @ref DEFINE_PLDM_PACKAGE_FORMAT_PIN_FR02H
+ *
+ * The package pinning operates by providing versioning over multiple structs
+ * required to perform the package parsing. See [Conventions for extensible
+ * system calls][lwn-extensible-syscalls] for discussion of related concepts.
+ * Like the syscall structs described there, the structs captured here by the
+ * pinning concept must only ever be modified by addition of new members, never
+ * alteration of existing members.
+ *
+ * [lwn-extensible-syscalls]: https://lwn.net/Articles/830666/
*/
struct pldm_package_format_pin {
struct {
- /** A value that communicates information about object sizes to the implementation */
+ /**
+ * A value that communicates information about object sizes to the implementation.
+ *
+ * For magic version 0, the sum must be calculated using @ref LIBPLDM_SIZEAT for
+ * the final relevant member of each relevant struct for the format revision
+ * represented by the pin.
+ */
const uint32_t magic;
- /** Versioning for the derivation of the magic value */
+ /**
+ * Versioning for the derivation of the magic value
+ *
+ * A version value of 0 defines the magic number to be the sum of the relevant
+ * struct sizes for the members required at the format revision specified by
+ * the pin.
+ */
const uint8_t version;
} meta;
struct {