[PATCH v4 5/6] doc: fru: add documentation for the fru command and APIs
Jae Hyun Yoo
quic_jaehyoo at quicinc.com
Thu Sep 22 08:40:35 CEST 2022
Hello Michal,
On 9/21/2022 6:54 AM, Michal Simek wrote:
>
>
> 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
I added the return value description like below for an example.
* Returns 0 on success or a negative error code.
But it's not detected as valid description by the kernel-doc script.
Will change it like below.
* Return: 0 on success or a negative error code.
Checked that it doesn't make the warnings.
Thank you,
Jae
More information about the U-Boot
mailing list