[PATCH v3 5/7] doc: fru: add documentation for the fru command and APIs

[Jae Hyun Yoo <quic_jaehyoo@quicinc.com>]

Add a usage document for the 'fru' u-boot command.
Add kerneldocs for <fru.h>.

Signed-off-by: Jae Hyun Yoo <quic_jaehyoo@quicinc.com>
---
Changes from v2:
 * Added kerneldocs to 'include/fru.h'. (Simon)

Changes from v1:
 * Newly added in v2. (Heinrich)

 doc/usage/cmd/fru.rst | 144 +++++++++++++++++++++++++++++++++
 doc/usage/index.rst   |   1 +
 include/fru.h         | 182 ++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 327 insertions(+)
 create mode 100644 doc/usage/cmd/fru.rst

diff --git a/doc/usage/cmd/fru.rst b/doc/usage/cmd/fru.rst
new file mode 100644
index 000000000000..d65bbc6dcbba
--- /dev/null
+++ b/doc/usage/cmd/fru.rst
@@ -0,0 +1,144 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+fru command
+===========
+
+Synopsis
+--------
+
+::
+
+    fru capture <addr>
+    fru display
+    fru generate -b <addr> <manufacturer> <board name> <serial number> <part number> <file id> [<custom> ...]
+    fru generate -p <addr> <manufacturer> <product name> <part number> <version number> <serial number> <asset number> <file id> [<custom> ...]
+
+Description
+-----------
+
+The *fru* commands is used to generate, capture and display FRU (Field
+Replaceable Unit) information data.
+
+Capture
+~~~~~~~
+
+The *fru capture* command parses and captures FRU configuration table at
+a specified address.
+
+    addr
+        memory address which FRU configuration table is stored.
+
+Display
+~~~~~~~
+
+The *fru display* command displays FRU information that is parsed using
+fru capture command.
+
+Generate
+~~~~~~~~
+
+The *fru generate* command generates a FRU configuration table which has Board
+or Product Info Area using the given field parameters.
+
+    -b
+        generate FRU which has board info area.
+
+        addr
+            memory address which FRU configuration table will be stored.
+
+        manufacturer
+            board manufacturer string.
+
+        board name
+            board product name string.
+
+        serial number
+            board serial number string.
+
+        serial number
+            board serial number string.
+
+        part number
+            board part number string.
+
+        file id
+            FRU File ID string. The FRU File version field is a pre-defined
+            field provided as a manufacturing aid for verifying the file that
+            was used during manufacture or field update to load the FRU
+            information. The content is manufacturer-specific.
+
+        custom
+            additional custom board info area fields, if any.
+
+    -p
+        generate FRU which has product info area.
+
+        addr
+            memory address which FRU configuration table will be stored.
+
+        manufacturer
+            product manufacturer string.
+
+        board name
+            product name string.
+
+        part number
+            product part/model number string.
+
+        version number
+            product version number string.
+
+        serial number
+            product serial number string.
+
+        asset number
+            asset tag.
+
+        file id
+            FRU File ID string. The FRU File version field is a pre-defined
+            field provided as a manufacturing aid for verifying the file that
+            was used during manufacture or field update to load the FRU
+            information. The content is manufacturer-specific.
+
+        custom
+            additional custom product info area fields, if any.
+
+Example
+-------
+
+::
+
+    => fru generate -b 90000000 abc def ghi jkl mno prs tuv wxy
+    => fru capture 90000000
+    => fru display
+    *****COMMON HEADER*****
+    Version:1
+    *** No Internal Area ***
+    *** No Chassis Info Area ***
+    Board Area Offset:8
+    *** No Product Info Area ***
+    *** No MultiRecord Area ***
+    *****BOARD INFO*****
+    Version:1
+    Board Area Length:40
+    Time in Minutes from 0:00hrs 1/1/96: 0
+     Manufacturer Name: abc
+     Product Name: def
+     Serial Number: ghi
+     Part Number: jkl
+     File ID: mno
+     Custom Type/Length: 0xc3
+      00000000: 70 72 73                                         prs
+     Custom Type/Length: 0xc3
+      00000000: 74 75 76                                         tuv
+     Custom Type/Length: 0xc3
+      00000000: 77 78 79                                         wxy
+    *****PRODUCT INFO*****
+    Version:0
+    Product Area Length:0
+    *****MULTIRECORDS*****
+
+Configuration
+-------------
+
+The fru command is only available if CONFIG_CMD_FRU=y.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 28f9683a3e6f..e96a16356307 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -45,6 +45,7 @@ Shell commands
    cmd/fatload
    cmd/fdt
    cmd/for
+   cmd/fru
    cmd/gpio
    cmd/load
    cmd/loadm
diff --git a/include/fru.h b/include/fru.h
index 2b19033a3843..1d11fd1a5964 100644
--- a/include/fru.h
+++ b/include/fru.h
@@ -10,6 +10,21 @@
 
 #include <linux/list.h>
 
+/**
+ * struct fru_common_hdr - FRU common header
+ *
+ * @version:		Common header format version
+ * @off_internal:	Internal use area starting offset
+ * @off_chassis:	Chassis info area starting offset
+ * @off_board:		Board area starting offset
+ * @off_product:	Product info area starting offset
+ * @off_multirec:	MultiRecord area starting offset
+ * @pad:		PAD, write as 00h
+ * @crc:		Common header checksum (zero checksum)
+ *
+ * Offsets are all in multiples of 8 bytes). 00h indicates that the area is not
+ * present.
+ */
 struct fru_common_hdr {
 	u8 version;
 	u8 off_internal;
@@ -24,6 +39,17 @@ struct fru_common_hdr {
 #define FRU_INFO_FIELD_LEN_MAX		32
 #define FRU_MULTIREC_DATA_LEN_MAX	255
 
+/**
+ * struct fru_board_info_header - Board info area header
+ *
+ * @ver:	Board area format version
+ * @len:	Board area length (in multiples of 8 bytes)
+ * @lang_code:	Language code
+ * @time:	Mfg. date / time
+ *		Number of minutes from 0:00 hrs 1/1/96.
+ *		LSbyte first (little endian)
+ *		00_00_00h = unspecified
+ */
 struct fru_board_info_header {
 	u8 ver;
 	u8 len;
@@ -31,27 +57,71 @@ struct fru_board_info_header {
 	u8 time[3];
 } __packed;
 
+/**
+ * struct fru_product_info_header - Product info area header
+ *
+ * @ver:	Product area format version
+ * @len:	Product area length (in multiples of 8 bytes)
+ * @lang_code:	Language code
+ */
 struct fru_product_info_header {
 	u8 ver;
 	u8 len;
 	u8 lang_code;
 } __packed;
 
+/**
+ * struct fru_common_info_member - FRU common info member
+ *
+ * @type_len:	type/length byte
+ * @name:	Member information bytes
+ */
 struct fru_common_info_member {
 	u8 type_len;
 	u8 *name;
 } __packed;
 
+/**
+ * struct fru_custom_info - Custom info field
+ *
+ * @type_len:	Type/length byte
+ * @data:	Custom information bytes
+ */
 struct fru_custom_info {
 	u8 type_len;
 	u8 data[FRU_INFO_FIELD_LEN_MAX];
 } __packed;
 
+/**
+ * struct fru_custom_field_node - Linked list head for Custom info fields
+ *
+ * @list:	Linked list head
+ * @info:	Custom info field of the node
+ */
 struct fru_custom_field_node {
 	struct list_head list;
 	struct fru_custom_info info;
 };
 
+/**
+ * struct fru_board_data - Board info area
+ *
+ * @ver:			Board area format version
+ * @len:			Board area length (in multiples of 8 bytes)
+ * @lang_code:			Language code
+ * @time:			Mfg. date / time
+ * @manufacturer_type_len:	Type/length byte
+ * @manufacturer_name:		Board manufacturer name
+ * @product_name_type_len:	Type/length byte
+ * @product_name:		Board product name
+ * @serial_number_type_len:	Type/length byte
+ * @serial_number:		Board serial number
+ * @part_number_type_len:	Type/length byte
+ * @part_number:		Board part number
+ * @file_id_type_len:		Type/length byte
+ * @file_id:			FRU file ID
+ * @custom_fields:		Linked list head for Custom info fields
+ */
 struct fru_board_data {
 	u8 ver;
 	u8 len;
@@ -70,6 +140,28 @@ struct fru_board_data {
 	struct list_head custom_fields;
 };
 
+/**
+ * struct fru_product_data - Product info area
+ *
+ * @ver:			Product area format version
+ * @len:			Product area length (in multiples of 8 bytes)
+ * @lang_code:			Language code
+ * @manufacturer_type_len:	Type/length byte
+ * @manufacturer_name:		Product manufacturer name
+ * @product_name_type_len:	Type/length byte
+ * @product_name:		Product name
+ * @part_number_type_len:	Type/length byte
+ * @part_number:		Product part number
+ * @version_number_type_len:	Type/length byte
+ * @version_number:		Product version number
+ * @serial_number_type_len:	Type/length byte
+ * @serial_number:		Product serial number
+ * @asset_number_type_len:	Type/length byte
+ * @asset_number:		Product asset number
+ * @file_id_type_len:		Type/length byte
+ * @file_id:			FRU file ID
+ * @custom_fields:		Linked list head for Custom info fields
+ */
 struct fru_product_data {
 	u8 ver;
 	u8 len;
@@ -91,6 +183,15 @@ struct fru_product_data {
 	struct list_head custom_fields;
 };
 
+/**
+ * struct fru_multirec_hdr - MultiRecord area header
+ *
+ * @rec_type:	Product area format version
+ * @type:	Product area length (in multiples of 8 bytes)
+ * @len:	Language code
+ * @csum:	Type/length byte
+ * @hdr_csum:	Product manufacturer name
+ */
 struct fru_multirec_hdr {
 	u8 rec_type;
 	u8 type;
@@ -99,16 +200,37 @@ struct fru_multirec_hdr {
 	u8 hdr_csum;
 } __packed;
 
+/**
+ * struct fru_multirec_info - MultiRecord info field
+ *
+ * @hdr:	MultiRecord area header
+ * @data:	MultiRecord information bytes
+ */
 struct fru_multirec_info {
 	struct fru_multirec_hdr hdr;
 	u8 data[FRU_MULTIREC_DATA_LEN_MAX];
 } __packed;
 
+/**
+ * struct fru_multirec_node - Linked list head for MultiRecords
+ *
+ * @list:	Linked list head
+ * @info:	MultiRecord info field of the node
+ */
 struct fru_multirec_node {
 	struct list_head list;
 	struct fru_multirec_info info;
 };
 
+/**
+ * struct fru_table - FRU table storage
+ *
+ * @hdr:	FRU common header
+ * @brd:	Board info
+ * @prd:	Product info
+ * @multi_recs:	MultiRecords
+ * @captured:	TRUE when this table is captured and parsed
+ */
 struct fru_table {
 	struct fru_common_hdr hdr;
 	struct fru_board_data brd;
@@ -135,12 +257,72 @@ struct fru_table {
 #define FRU_TYPELEN_TYPE_BINARY		0
 #define FRU_TYPELEN_TYPE_ASCII8		3
 
+/**
+ * fru_display() - display captured FRU information
+ *
+ * @verbose:	Enable (1) verbose output or not (0)
+ *
+ * Returns 0 on success or a negative error code.
+ */
 int fru_display(int verbose);
+
+/**
+ * fru_display() - parse and capture FRU configuration table
+ *
+ * @addr:	Address where the FRU configuration table is stored
+ *
+ * Returns 0 on success or a negative error code.
+ */
 int fru_capture(const void *addr);
+
+/**
+ * fru_board_generate() - generate FRU which has board info area
+ *
+ * @addr:	Address to store generated FRU configuration table at
+ * @argc:	Length of @argv
+ * @argv:	Vector of arguments. See doc/usage/fru.rst for more details
+ *
+ * Returns 0 on success or a negative error code.
+ */
 int fru_board_generate(const void *addr, int argc, char *const argv[]);
+
+/**
+ * fru_product_generate() - generate FRU which has product info area
+ *
+ * @addr:	Address to store generated FRU configuration table at
+ * @argc:	Length of @argv
+ * @argv:	Vector of arguments. See doc/usage/fru.rst for more details
+ *
+ * Returns 0 on success or a negative error code.
+ */
 int fru_product_generate(const void *addr, int argc, char *const argv[]);
+
+/**
+ * fru_checksum() - calculate checksum of FRU info
+ *
+ * @addr:	Address of the FRU info data source
+ * @len:	Length of the FRU info data
+ *
+ * Returns a calculated checksum.
+ */
 u8 fru_checksum(u8 *addr, u8 len);
+
+/**
+ * fru_check_type_len() - check and parse type/len byte
+ *
+ * @type_len:	Type/len byte
+ * @language:	Language code byte
+ * @type:	Pointer to a variable to store parsed type
+ *
+ * Returns length of the type, -EINVAL on the FRU_TYPELEN_EOF type
+ */
 int fru_check_type_len(u8 type_len, u8 language, u8 *type);
+
+/**
+ * fru_get_fru_data() - get pointer to captured FRU info table
+ *
+ * Returns pointer to captured FRU table
+ */
 const struct fru_table *fru_get_fru_data(void);
 
 #endif /* FRU_H */
-- 
2.25.1