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 */