[PATCH v3 5/7] doc: fru: add documentation for the fru command and APIs
Jae Hyun Yoo
quic_jaehyoo at quicinc.com
Tue Aug 23 23:52:58 CEST 2022
Add a usage document for the 'fru' u-boot command.
Add kerneldocs for <fru.h>.
Signed-off-by: Jae Hyun Yoo <quic_jaehyoo at 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
More information about the U-Boot
mailing list