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 D759EC32772 for ; Tue, 23 Aug 2022 21:55:01 +0000 (UTC) Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id CE5E184855; Tue, 23 Aug 2022 23:54:06 +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="fs7d21CU"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 12ECA847FC; Tue, 23 Aug 2022 23:53:50 +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 2F51F842E0 for ; Tue, 23 Aug 2022 23:53:46 +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 (m0279867.ppops.net [127.0.0.1]) by mx0a-0031df01.pphosted.com (8.17.1.5/8.17.1.5) with ESMTP id 27NGj3O5030644; Tue, 23 Aug 2022 21:53:22 GMT DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=quicinc.com; h=from : to : cc : subject : date : message-id : in-reply-to : references : mime-version : content-transfer-encoding : content-type; s=qcppdkim1; bh=9QAqzCKzJgZhe+4Cd2XywLWBa8P2foCf23xW4oYnxyI=; b=fs7d21CU20wJryw1y35Qon7io/oG4VEfRU8BMQLCQ7RQb3yEbKNvJpIjR0wfRsFLUUr2 PHcT5DchrF7scHAxqGC6+A6TpEXQmN8b7YIoVzaIP3wG4FXFmpWutRbLBqfp1W8LQn+f yFQT+tArlwqiKH6I82Gya6MeaUjGqrt0Px1vElVbIkIMzKfmUuP9rdScQ10OrJuyAxZa SLxGafaIqip0e+UGY14YhnmLxx5lXBR8SjmGRm9vmyhlcPXmp0KtEOuwM5IOOORoObvu MnO7oIvy6X3GNhOEPK5bjeG8ALH/Z0NAxQt8TKOVOB4CvAsxGgI6Op+PWvAyKsZfkQtB 3g== Received: from nalasppmta03.qualcomm.com (Global_NAT1.qualcomm.com [129.46.96.20]) by mx0a-0031df01.pphosted.com (PPS) with ESMTPS id 3j52pk8uma-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 23 Aug 2022 21:53:21 +0000 Received: from pps.filterd (NALASPPMTA03.qualcomm.com [127.0.0.1]) by NALASPPMTA03.qualcomm.com (8.17.1.5/8.17.1.5) with ESMTP id 27NLrLVd003639; Tue, 23 Aug 2022 21:53:21 GMT Received: from pps.reinject (localhost [127.0.0.1]) by NALASPPMTA03.qualcomm.com (PPS) with ESMTPS id 3j47bmxw2q-1 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 23 Aug 2022 21:53:21 +0000 Received: from NALASPPMTA03.qualcomm.com (NALASPPMTA03.qualcomm.com [127.0.0.1]) by pps.reinject (8.17.1.5/8.17.1.5) with ESMTP id 27NLrLWr003631; Tue, 23 Aug 2022 21:53:21 GMT Received: from nalasex01a.na.qualcomm.com (nalasex01a.na.qualcomm.com [10.47.209.196]) by NALASPPMTA03.qualcomm.com (PPS) with ESMTPS id 27NLrLUW003630 (version=TLSv1.2 cipher=ECDHE-RSA-AES256-GCM-SHA384 bits=256 verify=NOT); Tue, 23 Aug 2022 21:53:21 +0000 Received: from maru.qualcomm.com (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; Tue, 23 Aug 2022 14:53:19 -0700 From: Jae Hyun Yoo To: Michal Simek , Ovidiu Panait , Simon Glass , Mario Six , Masahisa Kojima , =?UTF-8?q?Pali=20Roh=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=20Le=20Goater?= , Jae Hyun Yoo , Subject: [PATCH v3 5/7] doc: fru: add documentation for the fru command and APIs Date: Tue, 23 Aug 2022 14:52:58 -0700 Message-ID: <20220823215300.1485789-6-quic_jaehyoo@quicinc.com> X-Mailer: git-send-email 2.25.1 In-Reply-To: <20220823215300.1485789-1-quic_jaehyoo@quicinc.com> References: <20220823215300.1485789-1-quic_jaehyoo@quicinc.com> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Content-Type: text/plain 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: Weelm8moV84BiFmJncNjkyHNH8M3AWbl X-Proofpoint-ORIG-GUID: Weelm8moV84BiFmJncNjkyHNH8M3AWbl X-Proofpoint-Virus-Version: vendor=baseguard engine=ICAP:2.0.205,Aquarius:18.0.895,Hydra:6.0.517,FMLib:17.11.122.1 definitions=2022-08-23_09,2022-08-22_02,2022-06-22_01 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 clxscore=1015 lowpriorityscore=0 adultscore=0 priorityscore=1501 malwarescore=0 bulkscore=0 phishscore=0 impostorscore=0 mlxlogscore=999 spamscore=0 suspectscore=0 mlxscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.12.0-2207270000 definitions=main-2208230082 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 Add a usage document for the 'fru' u-boot command. Add kerneldocs for . Signed-off-by: Jae Hyun Yoo --- 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 [ ...] + fru generate -p [ ...] + +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 */ -- 2.25.1