Re: [PATCH v4 5/6] doc: fru: add documentation for the fru command and APIs

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

    

Re: [PATCH v4 5/6] doc: fru: add documentation for the fru command and APIs

Michal Simek

Signed-off-by: Jae Hyun Yoo quic_jaehyoo@quicinc.com