[PATCH v4 5/6] doc: fru: add documentation for the fru command and APIs
Michal Simek
michal.simek at amd.com
Wed Sep 21 15:54:34 CEST 2022
On 8/25/22 18:42, Jae Hyun Yoo wrote:
> 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 v3:
> * None.
>
> 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 */
please fix these warnings.
$ ./scripts/kernel-doc -v -man include/fru.h >/dev/null
include/fru.h:14: info: Scanning doc for struct fru_common_hdr
include/fru.h:43: info: Scanning doc for struct fru_board_info_header
include/fru.h:61: info: Scanning doc for struct fru_product_info_header
include/fru.h:74: info: Scanning doc for struct fru_common_info_member
include/fru.h:85: info: Scanning doc for struct fru_custom_info
include/fru.h:96: info: Scanning doc for struct fru_custom_field_node
include/fru.h:107: info: Scanning doc for struct fru_board_data
include/fru.h:144: info: Scanning doc for struct fru_product_data
include/fru.h:187: info: Scanning doc for struct fru_multirec_hdr
include/fru.h:204: info: Scanning doc for struct fru_multirec_info
include/fru.h:215: info: Scanning doc for struct fru_multirec_node
include/fru.h:226: info: Scanning doc for struct fru_table
include/fru.h:261: info: Scanning doc for fru_display
include/fru.h:267: warning: No description found for return value of 'fru_display'
include/fru.h:270: info: Scanning doc for fru_display
include/fru.h:276: warning: No description found for return value of 'fru_capture'
include/fru.h:279: info: Scanning doc for fru_board_generate
include/fru.h:287: warning: No description found for return value of
'fru_board_generate'
include/fru.h:290: info: Scanning doc for fru_product_generate
include/fru.h:298: warning: No description found for return value of
'fru_product_generate'
include/fru.h:301: info: Scanning doc for fru_checksum
include/fru.h:308: warning: No description found for return value of 'fru_checksum'
include/fru.h:311: info: Scanning doc for fru_check_type_len
include/fru.h:319: warning: No description found for return value of
'fru_check_type_len'
include/fru.h:322: info: Scanning doc for fru_get_fru_data
include/fru.h:326: warning: No description found for return value of
'fru_get_fru_data'
7 warnings
M
More information about the U-Boot
mailing list