[PATCH v1 2/2] doc_ cmd: add documentation for sm3sum

[Quentin Schulz]

Hi Heiko,

Typo in title, should be doc: and not doc_.

On 1/6/26 3:14 PM, Heiko Schocher wrote:
> add documentation for sm3sum command.
> 
> Signed-off-by: Heiko Schocher <hs at nabladev.com>
> ---
> 
>   doc/usage/cmd/sm3sum.rst | 117 +++++++++++++++++++++++++++++++++++++++
>   1 file changed, 117 insertions(+)
>   create mode 100644 doc/usage/cmd/sm3sum.rst
> 
> diff --git a/doc/usage/cmd/sm3sum.rst b/doc/usage/cmd/sm3sum.rst
> new file mode 100644
> index 00000000000..3b157779a0e
> --- /dev/null
> +++ b/doc/usage/cmd/sm3sum.rst
> @@ -0,0 +1,117 @@
> +.. SPDX-License-Identifier: GPL-2.0+:

Use the canonical version:

GPL-2.0-or-later

c.f. https://spdx.org/licenses/GPL-2.0-or-later.html

(Do not end it with a colon either).

> +   Copyright 2025 Nabladev

Seems like we typically use a new comment for this line

.. Copyright 2025 Nabladev

I **think** the copyright should use the name of the legal entity (so 
likely "Nabla Software Engineering GmbH"). But IANAL and I personally 
don't care :)

> +   Written by Heiko Schocher <hs at nabladev.com>
> +
> +.. index::
> +   single: sm3sum (command)
> +
> +sm3sum command
> +==============
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    sm3sum - compute SM3 message digest
> +
> +    Usage:
> +    sm3sum address count [[*]sum]
> +      - compute SM3 message digest [save to sum]
> +    sm3sum -v address count [*]sum
> +      - verify sm3sum of memory area
> +
> +
> +Description
> +-----------
> +
> +The sm3sum command calculates the SM3_256 Hash from a

Are there variants of SM3? From what I understood, it's "equivalent" to 
sha256 in terms of security and efficiency, but it's SM3, just that?

> +address with length of count bytes. If the -v option is

Can suggest:

"""
calculates the SM3 hash of data of ``count`` bytes at address ``address``.
"""

which highlights which parts of the command must be specific by the user.

s/-v/``-v``/

> +passed to the command, it compares the calculated hash
> +with the hash found at address sum.
> +

s/sum/``sum``/.

> +The SM3 secure hash, is calculated as specified by OSCCA GM/T

s/,//

> +0004-2012 SM3 and described at
> +
> +https://datatracker.ietf.org/doc/html/draft-sca-cfrg-sm3-02
> +
> +Parameters
> +----------
> +
> +address
> +    address from where the sm3 hash is calculated

How is this value parsed? Is it deducted from the string (e.g. starts 
with 0x or contains hex digits = hex, starts with 0, octal, otherwise 
decimal), or is it a forced base? This needs to be specified.

> +
> +count
> +    length in bytes of memory area for which the sm3 hash is calculated
> +
> +sum
> +    address of hash to which the calculated hash gets stored

This is only true if you sum starts with "*" no? Otherwise it's the name 
of the environment variable where to store the checksum?

> +
> +    or if "-v" option is passed:

s/"-v"/``-v``/

> +
> +    address of hash with which the calculated hash gets compared.
> +
> +Example
> +-------
> +
> +create some data
> +

+at address ``0x0000000100000000``

(do we need the leading zeroes?)

> +::
> +
> +    u-boot=> mw 0x0000000100000000 0x426f6f46 1
> +    u-boot=> md.b 0x0000000100000000 4
> +    00000000: 46 6f 6f 42                                      FooB
> +
> +and calculate the sm3sum from address and store it in environment

s/from address/of 4 bytes starting from address ``0x0000000100000000``/

> +variable hashval
> +

s/hashval/``hashval``/

> +::
> +
> +    u-boot=> sm3sum 0x0000000100000000 4 hashval
> +    sm3_256 for 100000000 ... 100000003 ==> cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7
> +    u-boot=> print hashval
> +    hashval=cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7
> +    u-boot=>
> +
> +or calculate sm3sum from address and store it at address sum

s/from address/of 4 bytes starting from address ``0x0000000100000000``/

s/sum/``0x0000000110000000``/

> +
> +::
> +
> +    u-boot=> sm3sum 0x0000000100000000 4 *0x0000000110000000
> +    sm3_256 for 100000000 ... 100000003 ==> cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7
> +
> +and now check if this hash is a valid sm3sum with "-v" option

s/is a valid sm3sum/is the expected sm3sum hash value/

s/"-v"/``-v``/
> +
> +::
> +
> +    u-boot=> sm3sum -v 0x0000000100000000 4 *0x0000000110000000
> +    u-boot=> echo $?
> +    0
> +
> +example with wrong hash
> +
> +::
> +
> +    u-boot=> sm3sum -v 0x0000000100000000 4 *0x0000000110000004
> +    sm3_256 for 100000000 ... 100000003 ==> cdf49da4e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7 != e33017bf2d9fe87b885d80c9a7c920be7e10ffb8c89036a1eb1503b7ffffffff ** ERROR **
> +    u-boot=>
> +
> +
> +Configuration
> +-------------
> +
> +Enable the sm3sum command via Kconfig option CONFIG_CMD_SM3SUM.

s/CONFIG_CMD_SM3SUM/``CONFIG_CMD_SM3SUM``/

> +The "-v" option is separate enabled through Kconfig option

s/"-v"/``-v``/

> +CONFIG_SM3SUM_VERIFY.

s/CONFIG_SM3SUM_VERIFY/``CONFIG_SM3SUM_VERIFY``/

> +
> +
> +Return value
> +------------
> +
> +The return value $? is true (0) if the hash is calculated or if
> +the created hash is the same as the hash stored in memory at
> +address sum.
> +
> +The return value is false (1) if there is a problem with
> +calculating the hash, or if the hash is not the same as
> +the hash stored ar address sum.

This matches the expectations I got from reading 
https://docs.u-boot.org/en/latest/usage/cmdline.html#general-rules 
(point 3). So I would simply remove the return value section in this 
patch here.

Cheers,
Quentin