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@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