From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from phobos.denx.de (phobos.denx.de [85.214.62.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id 96172C6FA8B for ; Thu, 22 Sep 2022 06:41:12 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 606FA849F4; Thu, 22 Sep 2022 08:41:10 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=quicinc.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (2048-bit key; unprotected) header.d=quicinc.com header.i=@quicinc.com header.b="OE6eeQQm"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 3395C84C9F; Thu, 22 Sep 2022 08:41:09 +0200 (CEST) Received: from mx0a-0031df01.pphosted.com (mx0a-0031df01.pphosted.com [205.220.168.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 9EFC2849EE for ; Thu, 22 Sep 2022 08:41:05 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=quicinc.com Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=quic_jaehyoo@quicinc.com Received: from pps.filterd (m0279865.ppops.net [127.0.0.1]) by mx0a-0031df01.pphosted.com (8.17.1.5/8.17.1.5) with ESMTP id 28M60LxW002130; Thu, 22 Sep 2022 06:40:39 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=quicinc.com; h=message-id : date : mime-version : from : subject : to : cc : references : in-reply-to : content-type : content-transfer-encoding; s=qcppdkim1; bh=vmfYsnmKzzRezgLpszJzr0bIoecGbga2T0xnyDOya90=; b=OE6eeQQmVmmCBmisdCn5WsG4k01ChFdGcpuFMQSHNtdP76W40RMDQF08rM48GEhaAF8H J8fZQ7b9I/2XnYcl/vtWzF2o82AT9WRIoXyUp6MDlagar/adgXSvAvz6JRk454uzDq9A xBV4aUmxmND0AzWq67G6i4e0Aa21AJ5v/kb2l5lHP9wYczND06B2aRSHMf6i92H9dxpE ISwrDjhfky03jyQka/s57rn4NucfvhxiNcU8FaNnnJ8tkEFvXrwrBs4diWTJC871teuh 0LVLCNbC3zJnctd7DJYpPEHfpkIJP/oHQvevdDYctxJrRqJw7tCT0L19PFAPL2pU9wiu hw== Received: from nalasppmta05.qualcomm.com (Global_NAT1.qualcomm.com [129.46.96.20]) by mx0a-0031df01.pphosted.com (PPS) with ESMTPS id 3jqx5wc0bn-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 22 Sep 2022 06:40:39 +0000 Received: from pps.filterd (NALASPPMTA05.qualcomm.com [127.0.0.1]) by NALASPPMTA05.qualcomm.com (8.17.1.5/8.17.1.5) with ESMTP id 28M6Wd3M026981; Thu, 22 Sep 2022 06:40:38 GMT Received: from pps.reinject (localhost [127.0.0.1]) by NALASPPMTA05.qualcomm.com (PPS) with ESMTPS id 3jnqp994jv-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 22 Sep 2022 06:40:38 +0000 Received: from NALASPPMTA05.qualcomm.com (NALASPPMTA05.qualcomm.com [127.0.0.1]) by pps.reinject (8.17.1.5/8.17.1.5) with ESMTP id 28M6ecFK003154; Thu, 22 Sep 2022 06:40:38 GMT Received: from nalasex01a.na.qualcomm.com (nalasex01a.na.qualcomm.com [10.47.209.196]) by NALASPPMTA05.qualcomm.com (PPS) with ESMTPS id 28M6eceN003153 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Thu, 22 Sep 2022 06:40:38 +0000 Received: from [10.110.34.158] (10.80.80.8) by nalasex01a.na.qualcomm.com (10.47.209.196) with Microsoft SMTP Server (version=TLS1_2, cipher=TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384) id 15.2.986.29; Wed, 21 Sep 2022 23:40:36 -0700 Message-ID: <801e49e3-4126-3299-eb38-9f355f51df93@quicinc.com> Date: Wed, 21 Sep 2022 23:40:35 -0700 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:102.0) Gecko/20100101 Thunderbird/102.2.2 From: Jae Hyun Yoo Subject: Re: [PATCH v4 5/6] doc: fru: add documentation for the fru command and APIs To: Michal Simek , Ovidiu Panait , Simon Glass , Mario Six , Masahisa Kojima , =?UTF-8?Q?Pali_Roh=c3=a1r?= , Heinrich Schuchardt , Ashok Reddy Soma , "Thomas Huth" , Huang Jianan , Chris Morgan , Roland Gaudig , Patrick Delaunay , Alexandru Gagniuc CC: Jamie Iles , Graeme Gregory , =?UTF-8?Q?C=c3=a9dric_Le_Goater?= , References: <20220825164245.1606958-1-quic_jaehyoo@quicinc.com> <20220825164245.1606958-6-quic_jaehyoo@quicinc.com> <4b30a7e8-8d2c-bb5c-63b0-15635828e420@amd.com> Content-Language: en-US In-Reply-To: <4b30a7e8-8d2c-bb5c-63b0-15635828e420@amd.com> Content-Type: text/plain; charset="UTF-8"; format=flowed Content-Transfer-Encoding: 8bit X-Originating-IP: [10.80.80.8] X-ClientProxiedBy: nasanex01b.na.qualcomm.com (10.46.141.250) To nalasex01a.na.qualcomm.com (10.47.209.196) X-QCInternal: smtphost X-QCInternal: smtphost X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=5800 signatures=585085 X-Proofpoint-Virus-Version: vendor=nai engine=6200 definitions=5800 signatures=585085 X-Proofpoint-GUID: N6EuGkfQ4-OH4CyFR-AMweOiuDcxSZKg X-Proofpoint-ORIG-GUID: N6EuGkfQ4-OH4CyFR-AMweOiuDcxSZKg X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.895,Hydra:6.0.528,FMLib:17.11.122.1 definitions=2022-09-22_04,2022-09-20_02,2022-06-22_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 clxscore=1015 adultscore=0 malwarescore=0 phishscore=0 impostorscore=0 mlxscore=0 lowpriorityscore=0 priorityscore=1501 bulkscore=0 mlxlogscore=999 suspectscore=0 spamscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2209130000 definitions=main-2209220043 X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.39 Precedence: list List-Id: U-Boot discussion List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: u-boot-bounces@lists.denx.de Sender: "U-Boot" X-Virus-Scanned: clamav-milter 0.103.6 at phobos.denx.de X-Virus-Status: Clean 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 . >> >> Signed-off-by: Jae Hyun Yoo >> --- >> 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 >> +    fru display >> +    fru generate -b > number> [ ...] >> +    fru generate -p > number> >> [ ...] >> + >> +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 >> +/** >> + * 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