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

[Quentin Schulz]

Hi Heiko,

On 1/22/26 10:40 AM, Heiko Schocher wrote:
> Hello Quentin,
> 
> On 22.01.26 10:24, Quentin Schulz wrote:
>> Hi Heiko,
>>
>> On 1/22/26 10:12 AM, Heiko Schocher wrote:
>>> Hello Quentin,
>>>
>>> sorry for long delay...
>>>
>>> On 14.01.26 15:22, Quentin Schulz wrote:
>>>> Hi Heiko,
>>>>
>>>> Typo in title, should be doc: and not doc_.
>>>>
>>>> On 1/6/26 3:14 PM, Heiko Schocher wrote:
>> [...]
>>>>> 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://eur02.safelinks.protection.outlook.com/? 
>>>> url=https%3A%2F%2Fspdx.org%2Flicenses%2FGPL-2.0-or- 
>>>> later.html&data=05%7C02%7Cquentin.schulz%40cherry.de%7C752a802f23394270c5f808de5996472c%7C5e0e1b5221b54e7b83bb514ec460677e%7C0%7C0%7C639046699157004614%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=hFPbf2cm4pcD17T8ORnYC%2FL9VOWm2s%2B8Ebnb6TMjru8%3D&reserved=0
>>>>
>>>> (Do not end it with a colon either).
>>>
>>> okay, but I just copied from other files... for example
>>> doc/usage/cmd/dm.rst:
>>>    1 .. SPDX-License-Identifier: GPL-2.0+:
>>>    2
>>>
>>> So of course I change it... but does that mean, we should fix all other
>>> files too?
>>>
>>
>> It's unnecessary churn so I would say no. Considering I had other 
>> comments on the patch, I allowed myself this nitpick but if that was 
>> the only thing I was bothered with I wouldn't have told you. It's 
>> still clear we're talking about the -or-later version of the license. 
>> The biggest issue would be with GPL-2.0 or GPLv2 for example because 
>> it isn't clear if it's the -only version of the -or-later version 
>> since it matches none of the SPDX license identifier.
>>

https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/#simple-license-expressions

specifies we can have the short form identifier with a unary + operator 
to mean -or-later, so this seems fine actually.

>> I don't think Tom will want a patch to change all SPDX-License- 
>> Identifier from GPL-2.0+ to GPL-2.0-or-later but maybe I'm wrong :)
> 
> I think not :-P
> 
> What is with ending ":" ... above example has also the ending ":"
> I removed it as you suggested...
> 

Ah. I don't think this is valid.

https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/#overview 
has the exact syntax of a license expression.

https://spdx.github.io/using/license-id-in-source/ specifies how it 
should look like in code and I don't see a trailing colon. Whether that 
will trip license parsers remains unknown.

I think *this* specifically should be fine for a doc/-wide patch.

I think this may stem from editor plugins automatically adding colons at 
the end of a string started with ".. " as that's the start of a 
directive in rST? Or maybe the first contributor made a mistake and 
everybody copy-pasted it :)

The kernel doesn't have any of this kind of strings and it specifies how 
to specify the license for rST files here:

https://elixir.bootlin.com/linux/v6.18.6/source/Documentation/process/license-rules.rst#L80

>>
>> [...]
>>
>>>>> +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?
>>>
>>> As I know, there is only sm3_256 hash. If you look for example
>>> into include/tpm-v2.h
>>>   33 #define TPM2_SM3_256_DIGEST_SIZE 32
>>> [...]
>>> 277         TPM2_ALG_SM3_256        = 0x12,
>>> [...]
>>> 301 #define TCG2_BOOT_HASH_ALG_SM3_256 0x00000010
>>>
>>
>> So I would say we should use ``SM3`` here, instead of ``SM3_256``?
> 
> No, as linux also use the same define, see linux base:
> *   6c790212c588 - (HEAD -> master, origin/master, origin/HEAD) Merge 
> tag 'devicetree-fixes-for-6.19-3' of git://git.kernel.org/pub/scm/linux/ 
> kernel/git/robh/linux
> 
>   include/linux/tpm.h:
>   55         TPM_ALG_SM3_256         = 0x0012,
> 

/me shrugs

No strong opinion.

Cheers,
Quentin