* [PATCH 0/3] doc: Add a general note about $?
@ 2025-10-21 20:25 Tom Rini
2025-10-21 20:25 ` [PATCH 1/3] doc: usage: Add general rule for `$?` Tom Rini
` (2 more replies)
0 siblings, 3 replies; 14+ messages in thread
From: Tom Rini @ 2025-10-21 20:25 UTC (permalink / raw)
To: u-boot; +Cc: Heinrich Schuchardt
Hey all,
This is a small series to first add a general explanation for how $? is
set by commands to the cmdline documentation and second remove the
redundant information. The first patch adds this while removing the
identical (and sometimes slightly wrong or incomplete) information from
commands which had it. The last two patches remove the information from
cases that were not quite as clear, to make review easier. The commands
which either do something different or provided additional information
about what counts as success or failure have been retained.
--
Tom
^ permalink raw reply [flat|nested] 14+ messages in thread* [PATCH 1/3] doc: usage: Add general rule for `$?` 2025-10-21 20:25 [PATCH 0/3] doc: Add a general note about $? Tom Rini @ 2025-10-21 20:25 ` Tom Rini 2025-10-22 9:19 ` Quentin Schulz 2025-10-21 20:25 ` [PATCH 2/3] doc: askenv: Reword and remove return value Tom Rini 2025-10-21 20:25 ` [PATCH 3/3] doc: seama: Reword return value section Tom Rini 2 siblings, 1 reply; 14+ messages in thread From: Tom Rini @ 2025-10-21 20:25 UTC (permalink / raw) To: u-boot; +Cc: Heinrich Schuchardt For nearly all commands in U-Boot the '?' variable is handled the same way with 0 meaning success, 1 meaning failure and -1 meaning invalid usage. Explain this in the general rules section of the cmdline documentation (with a link to a counter example) and then remove the redundant wording from most commands. We retain a section about the return value in a number of places where we are doing something such as always returning a specific value or we have useful additional information to go along with the normal return codes. Signed-off-by: Tom Rini <trini@konsulko.com> --- Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> --- doc/usage/cmd/armffa.rst | 5 ----- doc/usage/cmd/bdinfo.rst | 5 ----- doc/usage/cmd/bind.rst | 5 ----- doc/usage/cmd/blkcache.rst | 6 ------ doc/usage/cmd/cat.rst | 5 ----- doc/usage/cmd/cli.rst | 5 ----- doc/usage/cmd/cls.rst | 5 ----- doc/usage/cmd/cp.rst | 6 ------ doc/usage/cmd/cpu.rst | 6 ------ doc/usage/cmd/cpuid.rst | 5 ----- doc/usage/cmd/dmareset.rst | 6 ------ doc/usage/cmd/ebtupdate.rst | 6 ------ doc/usage/cmd/fatinfo.rst | 6 ------ doc/usage/cmd/fdt.rst | 5 ----- doc/usage/cmd/font.rst | 6 ------ doc/usage/cmd/fuse.rst | 6 ------ doc/usage/cmd/gpio.rst | 6 ------ doc/usage/cmd/host.rst | 6 ------ doc/usage/cmd/i3c.rst | 6 ------ doc/usage/cmd/imxtract.rst | 6 ------ doc/usage/cmd/loadb.rst | 5 ----- doc/usage/cmd/loadm.rst | 7 ------- doc/usage/cmd/loads.rst | 5 ----- doc/usage/cmd/loadx.rst | 5 ----- doc/usage/cmd/loady.rst | 5 ----- doc/usage/cmd/msr.rst | 5 ----- doc/usage/cmd/mtest.rst | 5 ----- doc/usage/cmd/optee.rst | 5 ----- doc/usage/cmd/part.rst | 6 ------ doc/usage/cmd/pause.rst | 6 ------ doc/usage/cmd/pinmux.rst | 6 ------ doc/usage/cmd/pwm.rst | 6 ------ doc/usage/cmd/saves.rst | 5 ----- doc/usage/cmd/scmi.rst | 7 ------- doc/usage/cmd/setexpr.rst | 7 ------- doc/usage/cmd/size.rst | 6 ------ doc/usage/cmd/smbios.rst | 5 ----- doc/usage/cmd/sound.rst | 5 ----- doc/usage/cmd/source.rst | 6 ------ doc/usage/cmd/temperature.rst | 6 ------ doc/usage/cmd/tftpput.rst | 5 ----- doc/usage/cmd/unbind.rst | 5 ----- doc/usage/cmd/wdt.rst | 5 ----- doc/usage/cmd/wget.rst | 5 ----- doc/usage/cmdline.rst | 6 ++++++ 45 files changed, 6 insertions(+), 245 deletions(-) diff --git a/doc/usage/cmd/armffa.rst b/doc/usage/cmd/armffa.rst index 4f41e3393fda..dbe4d5bc8425 100644 --- a/doc/usage/cmd/armffa.rst +++ b/doc/usage/cmd/armffa.rst @@ -90,8 +90,3 @@ Configuration ------------- The command is available if CONFIG_CMD_ARMFFA=y and CONFIG_ARM_FFA_TRANSPORT=y. - -Return value ------------- - -The return value $? is 0 (true) on success, 1 (false) on failure. diff --git a/doc/usage/cmd/bdinfo.rst b/doc/usage/cmd/bdinfo.rst index a21fbc83ccf6..a139c9d855c0 100644 --- a/doc/usage/cmd/bdinfo.rst +++ b/doc/usage/cmd/bdinfo.rst @@ -115,8 +115,3 @@ Configuration ------------- The bdinfo command is available if CONFIG_CMD_BDI=y. - -Return code ------------ - -The return code $? is 0 (true). diff --git a/doc/usage/cmd/bind.rst b/doc/usage/cmd/bind.rst index 67a0405bab53..d2bef15508d0 100644 --- a/doc/usage/cmd/bind.rst +++ b/doc/usage/cmd/bind.rst @@ -99,8 +99,3 @@ Configuration ------------- The bind command is only available if CONFIG_CMD_BIND=y. - -Return code ------------ - -The return code $? is 0 (true) on success and 1 (false) on failure. diff --git a/doc/usage/cmd/blkcache.rst b/doc/usage/cmd/blkcache.rst index 0329261ba9af..764a4903ca05 100644 --- a/doc/usage/cmd/blkcache.rst +++ b/doc/usage/cmd/blkcache.rst @@ -69,9 +69,3 @@ Configuration ------------- The blkcache command is only available if CONFIG_CMD_BLOCK_CACHE=y. - -Return code ------------ - -If the command succeeds, the return code $? is set 0 (true). In case of an -error the return code is set to 1 (false). diff --git a/doc/usage/cmd/cat.rst b/doc/usage/cmd/cat.rst index b22dc6184a27..fa70e5f6a093 100644 --- a/doc/usage/cmd/cat.rst +++ b/doc/usage/cmd/cat.rst @@ -45,8 +45,3 @@ Configuration ------------- The cat command is only available if CONFIG_CMD_CAT=y. - -Return value ------------- - -The return value $? is set to 0 (true) if the file is readable, otherwise it returns a non-zero error code. diff --git a/doc/usage/cmd/cli.rst b/doc/usage/cmd/cli.rst index 23e5ee7a902e..97de5331d1b2 100644 --- a/doc/usage/cmd/cli.rst +++ b/doc/usage/cmd/cli.rst @@ -70,8 +70,3 @@ compiled:: modern => cli set old Want to set current parser to old, but its code was not compiled! - -Return value ------------- - -The return value $? indicates whether the command succeeded. diff --git a/doc/usage/cmd/cls.rst b/doc/usage/cmd/cls.rst index 828276742b9b..b8fa335079ea 100644 --- a/doc/usage/cmd/cls.rst +++ b/doc/usage/cmd/cls.rst @@ -22,8 +22,3 @@ Configuration ------------- The cls command is only available if CONFIG_CMD_CLS=y. - -Return value ------------- - -The return value $? is 0 (true) on success and 1 (false) on failure. diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst index 434dfedfc2b7..7bf2f468421b 100644 --- a/doc/usage/cmd/cp.rst +++ b/doc/usage/cmd/cp.rst @@ -79,9 +79,3 @@ Configuration The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words (cp.q) is only available on 64-bit targets. Copying to flash depends on CONFIG_MTD_NOR_FLASH=y. - -Return value ------------- - -The return value $? is set to 0 (true) if the command was successfully, -1 (false) otherwise. diff --git a/doc/usage/cmd/cpu.rst b/doc/usage/cmd/cpu.rst index 8b0b7d5a6991..705fb2dd6913 100644 --- a/doc/usage/cmd/cpu.rst +++ b/doc/usage/cmd/cpu.rst @@ -93,9 +93,3 @@ Configuration ------------- The cpu command is available if CONFIG_CMD_CPU=y. - -Return code ------------ - -The return value $? is set to 0 (true) if the command is successful, -1 (false) otherwise. diff --git a/doc/usage/cmd/cpuid.rst b/doc/usage/cmd/cpuid.rst index cccf9262ed4d..568c7e86ca15 100644 --- a/doc/usage/cmd/cpuid.rst +++ b/doc/usage/cmd/cpuid.rst @@ -25,11 +25,6 @@ Configuration The cpuid command is only available on x86. -Return value ------------- - -The return value $? is 0 (true). - Example ------- diff --git a/doc/usage/cmd/dmareset.rst b/doc/usage/cmd/dmareset.rst index ab06979251be..56180595363e 100644 --- a/doc/usage/cmd/dmareset.rst +++ b/doc/usage/cmd/dmareset.rst @@ -47,9 +47,3 @@ Configuration The dmareset command is only available if CONFIG_CMD_C5_PL330_DMA=y in "Shell scripting commands". - -Return value ------------- - -If the command succeeds, the return value $? is set to 0 (true). -If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/ebtupdate.rst b/doc/usage/cmd/ebtupdate.rst index 22415ee07b43..5102e6090a49 100644 --- a/doc/usage/cmd/ebtupdate.rst +++ b/doc/usage/cmd/ebtupdate.rst @@ -64,9 +64,3 @@ Configuration The ebtupdate command is only available if CONFIG_CMD_EBTUPDATE=y and only on Tegra 2 and Tegra 3 configurations. - -Return value ------------- - -The return value $? is set to 0 (true) if everything went successfully. If an -error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/fatinfo.rst b/doc/usage/cmd/fatinfo.rst index 2e05ab8becee..e5a89f37ba66 100644 --- a/doc/usage/cmd/fatinfo.rst +++ b/doc/usage/cmd/fatinfo.rst @@ -46,9 +46,3 @@ Configuration ------------- The fatinfo command is only available if CONFIG_CMD_FAT=y. - -Return value ------------- - -The return value $? is set to 0 (true) if the partition is a FAT partition. -Otherwise it is set to 1 (false). diff --git a/doc/usage/cmd/fdt.rst b/doc/usage/cmd/fdt.rst index 71a9fc627e55..493ed895bc78 100644 --- a/doc/usage/cmd/fdt.rst +++ b/doc/usage/cmd/fdt.rst @@ -66,8 +66,3 @@ address and expand it to 0xf000 in size:: Working FDT set to 10000 => md 10000 4 00010000: edfe0dd0 00f00000 78000000 7c270000 ...........x..'| - -Return value ------------- - -The return value $? indicates whether the command succeeded. diff --git a/doc/usage/cmd/font.rst b/doc/usage/cmd/font.rst index 44a04f5d075e..a1860466ac1b 100644 --- a/doc/usage/cmd/font.rst +++ b/doc/usage/cmd/font.rst @@ -54,9 +54,3 @@ Configuration ------------- The command is only available if CONFIG_CONSOLE_TRUETYPE=y. - -Return value ------------- - -The return value $? is 0 (true) if the command completes. -The return value is 1 (false) if the command fails. diff --git a/doc/usage/cmd/fuse.rst b/doc/usage/cmd/fuse.rst index 42c6e209f992..50cf5a4b6578 100644 --- a/doc/usage/cmd/fuse.rst +++ b/doc/usage/cmd/fuse.rst @@ -168,9 +168,3 @@ Configuration The fuse commands are available if CONFIG_CMD_FUSE=y. The fuse writebuff command is available if CONFIG_CMD_FUSE_WRITEBUFF=y. - -Return code ------------ - -The return value $? is set to 0 (true) if the command is successful, -1 (false) otherwise. diff --git a/doc/usage/cmd/gpio.rst b/doc/usage/cmd/gpio.rst index 4b0dc2716e57..0159d3478c2d 100644 --- a/doc/usage/cmd/gpio.rst +++ b/doc/usage/cmd/gpio.rst @@ -127,9 +127,3 @@ Configuration The *gpio* command is only available if CONFIG_CMD_GPIO=y. The *gpio read* command is only available if CONFIG_CMD_GPIO_READ=y. - -Return value ------------- - -If the command succeds the return value $? is set to 0. If an error occurs, the -return value $? is set to 1. diff --git a/doc/usage/cmd/host.rst b/doc/usage/cmd/host.rst index a70a432b6f2b..672d8f2112bc 100644 --- a/doc/usage/cmd/host.rst +++ b/doc/usage/cmd/host.rst @@ -111,9 +111,3 @@ Unbind a device:: => host info dev blocks label path 1 2048 fat 1MB.fat32.img - - -Return value ------------- - -The return value $? indicates whether the command succeeded. diff --git a/doc/usage/cmd/i3c.rst b/doc/usage/cmd/i3c.rst index 922fa3ea37c0..f49fcd4e7663 100644 --- a/doc/usage/cmd/i3c.rst +++ b/doc/usage/cmd/i3c.rst @@ -129,12 +129,6 @@ Configuration The ``i3c`` command is only available if CONFIG_CMD_I3C=y. -Return value ------------- - -If the command succeeds, the return value ``$?`` is set to 0. If an error -occurs, the return value ``$?`` is set to 1. - Note ---- diff --git a/doc/usage/cmd/imxtract.rst b/doc/usage/cmd/imxtract.rst index 235d15e445b0..1621a4a68b22 100644 --- a/doc/usage/cmd/imxtract.rst +++ b/doc/usage/cmd/imxtract.rst @@ -76,9 +76,3 @@ Configuration The imxtract command is only available if CONFIG_CMD_XIMG=y. Support for FIT images requires CONFIG_FIT=y. Support for legacy U-Boot images requires CONFIG_LEGACY_IMAGE_FORMAT=y. - -Return value ------------- - -On success the return value $? of the command is 0 (true). On failure the -return value is 1 (false). diff --git a/doc/usage/cmd/loadb.rst b/doc/usage/cmd/loadb.rst index 4f9a52c793f3..9e6a41e7fa04 100644 --- a/doc/usage/cmd/loadb.rst +++ b/doc/usage/cmd/loadb.rst @@ -66,8 +66,3 @@ Configuration ------------- The command is only available if CONFIG_CMD_LOADB=y. - -Return value ------------- - -The return value $? is 0 (true) on success, 1 (false) on error. diff --git a/doc/usage/cmd/loadm.rst b/doc/usage/cmd/loadm.rst index 005840a27bb0..722690be2c57 100644 --- a/doc/usage/cmd/loadm.rst +++ b/doc/usage/cmd/loadm.rst @@ -43,10 +43,3 @@ Configuration ------------- The command is only available if CONFIG_CMD_LOADM=y. - -Return value ------------- - -The return value $? is set 0 (true) if the loading is succefull, and -is set to 1 (false) in case of error. - diff --git a/doc/usage/cmd/loads.rst b/doc/usage/cmd/loads.rst index 0a2ac14acfe8..278d17850d75 100644 --- a/doc/usage/cmd/loads.rst +++ b/doc/usage/cmd/loads.rst @@ -92,8 +92,3 @@ Configuration The command is only available if CONFIG_CMD_LOADS=y. The parameter to set the baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y - -Return value ------------- - -The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/loadx.rst b/doc/usage/cmd/loadx.rst index 661b36723c32..50182eaa9d3b 100644 --- a/doc/usage/cmd/loadx.rst +++ b/doc/usage/cmd/loadx.rst @@ -73,8 +73,3 @@ The command is only available if CONFIG_CMD_LOADB=y. Initial timeout in seconds while waiting for transfer is configured by config option CMD_LOADXY_TIMEOUT or by env variable $loadxy_timeout. Setting it to 0 means infinite timeout. - -Return value ------------- - -The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/loady.rst b/doc/usage/cmd/loady.rst index 8367759471e3..8d21d7c32679 100644 --- a/doc/usage/cmd/loady.rst +++ b/doc/usage/cmd/loady.rst @@ -70,8 +70,3 @@ The command is only available if CONFIG_CMD_LOADB=y. Initial timeout in seconds while waiting for transfer is configured by config option CMD_LOADXY_TIMEOUT or by env variable $loadxy_timeout. Setting it to 0 means infinite timeout. - -Return value ------------- - -The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/msr.rst b/doc/usage/cmd/msr.rst index 04ee52cc1c75..8bb1212cdc17 100644 --- a/doc/usage/cmd/msr.rst +++ b/doc/usage/cmd/msr.rst @@ -38,11 +38,6 @@ Configuration The msr command is only available on x86. -Return value ------------- - -The return value $? is 0 (true). - Example ------- diff --git a/doc/usage/cmd/mtest.rst b/doc/usage/cmd/mtest.rst index e01f2a6d575e..a5705076af7a 100644 --- a/doc/usage/cmd/mtest.rst +++ b/doc/usage/cmd/mtest.rst @@ -62,8 +62,3 @@ Configuration ------------- The mtest command is enabled by CONFIG_CMD_MEMTEST=y. - -Return value ------------- - -The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise. diff --git a/doc/usage/cmd/optee.rst b/doc/usage/cmd/optee.rst index 46c569a105fd..caefdceeb7b6 100644 --- a/doc/usage/cmd/optee.rst +++ b/doc/usage/cmd/optee.rst @@ -63,8 +63,3 @@ Configuration ------------- The optee command is enabled by CONFIG_OPTEE=y and CONFIG_CMD_OPTEE=y. - -Return value ------------- - -The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise. diff --git a/doc/usage/cmd/part.rst b/doc/usage/cmd/part.rst index e7f6e54ecea4..72f5d8b8de74 100644 --- a/doc/usage/cmd/part.rst +++ b/doc/usage/cmd/part.rst @@ -223,9 +223,3 @@ This shows looking at a device with multiple partition tables:: type: ebd0a0a2-b9e5-4433-87c0-68b6b72699c7 guid: a0891d7e-b930-4513-94da-f629dbd637b2 => - -Return value ------------- - -The return value $? is set to 0 (true) if the command succededd. If an -error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/pause.rst b/doc/usage/cmd/pause.rst index 6cdd83d31636..b55825f5d93a 100644 --- a/doc/usage/cmd/pause.rst +++ b/doc/usage/cmd/pause.rst @@ -48,9 +48,3 @@ Note that complex prompts require proper quoting: Usage: pause [prompt] - Wait until users presses any key. [prompt] can be used to customize the message. - -Return value ------------- - -The return value $? is always set to 0 (true), unless invoked in an invalid -manner. diff --git a/doc/usage/cmd/pinmux.rst b/doc/usage/cmd/pinmux.rst index 30c5eb16a689..c066db1770cb 100644 --- a/doc/usage/cmd/pinmux.rst +++ b/doc/usage/cmd/pinmux.rst @@ -90,9 +90,3 @@ Configuration ------------- The pinmux command is only available if CONFIG_CMD_PINMUX=y. - -Return value ------------- - -The return value $? is set to 0 (true) if the command succeded and to 1 (false) -otherwise. diff --git a/doc/usage/cmd/pwm.rst b/doc/usage/cmd/pwm.rst index 522acb5afa33..6f7daba0736d 100644 --- a/doc/usage/cmd/pwm.rst +++ b/doc/usage/cmd/pwm.rst @@ -83,9 +83,3 @@ Configuration ------------- The ``pwm`` command is only available if CONFIG_CMD_PWM=y. - -Return value ------------- - -If the command succeeds, the return value ``$?`` is set to 0. If an error occurs, the -return value ``$?`` is set to 1. diff --git a/doc/usage/cmd/saves.rst b/doc/usage/cmd/saves.rst index b380a4feb6f0..d429eeceddf2 100644 --- a/doc/usage/cmd/saves.rst +++ b/doc/usage/cmd/saves.rst @@ -84,8 +84,3 @@ Configuration The command is only available if CONFIG_CMD_SAVES=y. The parameter to set the baud rate is only available if CONFIG_SYS_LOADS_BAUD_CHANGE=y - -Return value ------------- - -The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/scmi.rst b/doc/usage/cmd/scmi.rst index 9591cdc07a5a..c6e80a56a603 100644 --- a/doc/usage/cmd/scmi.rst +++ b/doc/usage/cmd/scmi.rst @@ -119,11 +119,4 @@ Configuration The scmi command is only available if CONFIG_CMD_SCMI=y. Default n because this command is mainly for debug purpose. -Return value ------------- - -The return value ($?) is set to 0 if the operation succeeded, -1 if the operation failed or -1 if the operation failed due to -a syntax error. - .. _`SCMI specification`: https://developer.arm.com/documentation/den0056/e/?lang=en diff --git a/doc/usage/cmd/setexpr.rst b/doc/usage/cmd/setexpr.rst index 5bc37ae50fc0..96894a2754f6 100644 --- a/doc/usage/cmd/setexpr.rst +++ b/doc/usage/cmd/setexpr.rst @@ -147,10 +147,3 @@ Configuration * The *setexpr gsub* and *setexpr sub* sub-commands are only available if CONFIG_REGEX=y. For an overview of the supported regex syntax, see :doc:`test`. - -Return value ------------- - -The return value $? is set to 0 (true) if the operation was successful. - -If an error occurs, the return value $? is set to 1 (false). diff --git a/doc/usage/cmd/size.rst b/doc/usage/cmd/size.rst index 306fcba0ba4a..42e2dec6323c 100644 --- a/doc/usage/cmd/size.rst +++ b/doc/usage/cmd/size.rst @@ -35,9 +35,3 @@ Configuration ------------- The size command is only available if CONFIG_CMD_FS_GENERIC=y. - -Return value ------------- - -The return value $? is set to 0 (true) if the command succeded and to 1 (false) -otherwise. diff --git a/doc/usage/cmd/smbios.rst b/doc/usage/cmd/smbios.rst index 1ffd706d7dee..3c98795698e7 100644 --- a/doc/usage/cmd/smbios.rst +++ b/doc/usage/cmd/smbios.rst @@ -86,8 +86,3 @@ Configuration ------------- The command is only available if CONFIG_CMD_SMBIOS=y. - -Return value ------------- - -The return value $? is 0 (true) on success, 1 (false) otherwise. diff --git a/doc/usage/cmd/sound.rst b/doc/usage/cmd/sound.rst index 97d610f3745c..4474ce954202 100644 --- a/doc/usage/cmd/sound.rst +++ b/doc/usage/cmd/sound.rst @@ -56,8 +56,3 @@ Configuration ------------- The sound command is enabled by CONFIG_CMD_SOUND=y. - -Return value ------------- - -The return value $? is 0 (true) if the command succeeds, 1 (false) otherwise. diff --git a/doc/usage/cmd/source.rst b/doc/usage/cmd/source.rst index 0de5f33390e7..bd585f374140 100644 --- a/doc/usage/cmd/source.rst +++ b/doc/usage/cmd/source.rst @@ -188,9 +188,3 @@ The FIT image file format requires CONFIG_FIT=y.# The legacy U-Boot image file format requires CONFIG_LEGACY_IMAGE_FORMAT=y. On hardened systems support for the legacy U-Boot image format should be disabled as these images cannot be signed and verified. - -Return value ------------- - -If the scripts is executed successfully, the return value $? is 0 (true). -Otherwise it is 1 (false). diff --git a/doc/usage/cmd/temperature.rst b/doc/usage/cmd/temperature.rst index 945bc8204ac7..d5ea1196f452 100644 --- a/doc/usage/cmd/temperature.rst +++ b/doc/usage/cmd/temperature.rst @@ -45,9 +45,3 @@ Configuration ------------- The *temperature* command is only available if CONFIG_CMD_TEMPERATURE=y. - -Return value ------------- - -The return value $? is set to 0 (true) if the command succeeded and to 1 (false) -otherwise. diff --git a/doc/usage/cmd/tftpput.rst b/doc/usage/cmd/tftpput.rst index 351c9faa38b9..214c7777da6f 100644 --- a/doc/usage/cmd/tftpput.rst +++ b/doc/usage/cmd/tftpput.rst @@ -83,8 +83,3 @@ after which an ACK response is required. The window size defaults to 1. If CONFIG_TFTP_TSIZE=y, the progress bar is limited to 50 '#' characters. Otherwise an '#' is written per UDP package which may decrease performance. - -Return value ------------- - -The return value $? is 0 (true) on success and 1 (false) otherwise. diff --git a/doc/usage/cmd/unbind.rst b/doc/usage/cmd/unbind.rst index 1ae9c1b172c1..5a165cfee230 100644 --- a/doc/usage/cmd/unbind.rst +++ b/doc/usage/cmd/unbind.rst @@ -91,8 +91,3 @@ Configuration ------------- The unbind command is only available if CONFIG_CMD_BIND=y. - -Return code ------------ - -The return code $? is 0 (true) on success and 1 (false) on failure. diff --git a/doc/usage/cmd/wdt.rst b/doc/usage/cmd/wdt.rst index f48b8840907d..711b74d20dab 100644 --- a/doc/usage/cmd/wdt.rst +++ b/doc/usage/cmd/wdt.rst @@ -73,8 +73,3 @@ Configuration ------------- The command is only available if CONFIG_CMD_WDT=y. - -Return value ------------- - -The return value $? is 0 if the command succeeds, 1 upon failure. diff --git a/doc/usage/cmd/wget.rst b/doc/usage/cmd/wget.rst index 8feda0248b20..e6c42f967b9b 100644 --- a/doc/usage/cmd/wget.rst +++ b/doc/usage/cmd/wget.rst @@ -184,8 +184,3 @@ CONFIG_WGET_CACERT=y (for the wget cacert command). TCP Selective Acknowledgments in the legacy network stack can be enabled via CONFIG_PROT_TCP_SACK=y. This will improve the download speed. Selective Acknowledgments are enabled by default with lwIP. - -Return value ------------- - -The return value $? is 0 (true) on success and 1 (false) otherwise. diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst index 58240c5279cd..cb353975eb82 100644 --- a/doc/usage/cmdline.rst +++ b/doc/usage/cmdline.rst @@ -55,6 +55,12 @@ General rules command will cause "run" to terminate, i. e. the remaining variables are not executed. +#. The variable `?` will be set as the return value of any command. These + values are 0 on success, -1 on a usage related errors, i. e. invalid syntax + and 1 on any other error. Any exceptions to this are documented by the + specific command, i. e. :doc:`cmd/for` sets this based on the last command + run within the loop. + Representing numbers -------------------- -- 2.43.0 ^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: [PATCH 1/3] doc: usage: Add general rule for `$?` 2025-10-21 20:25 ` [PATCH 1/3] doc: usage: Add general rule for `$?` Tom Rini @ 2025-10-22 9:19 ` Quentin Schulz 2025-10-22 13:54 ` Tom Rini 0 siblings, 1 reply; 14+ messages in thread From: Quentin Schulz @ 2025-10-22 9:19 UTC (permalink / raw) To: Tom Rini, u-boot; +Cc: Heinrich Schuchardt Hi Tom, On 10/21/25 10:25 PM, Tom Rini wrote: [...] > diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst > index 58240c5279cd..cb353975eb82 100644 > --- a/doc/usage/cmdline.rst > +++ b/doc/usage/cmdline.rst > @@ -55,6 +55,12 @@ General rules > command will cause "run" to terminate, i. e. the remaining > variables are not executed. > > +#. The variable `?` will be set as the return value of any command. These s/These/The possible/ ? > + values are 0 on success, -1 on a usage related errors, i. e. invalid syntax s/a// or s/a/any/ ? I would also add a comma after "syntax". Should i.e. be e.g.? c.f. https://en.wiktionary.org/wiki/i.e. > + and 1 on any other error. Any exceptions to this are documented by the > + specific command, i. e. :doc:`cmd/for` sets this based on the last command s/i. e./e.g./ Cheers, Quentin ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 1/3] doc: usage: Add general rule for `$?` 2025-10-22 9:19 ` Quentin Schulz @ 2025-10-22 13:54 ` Tom Rini 2025-10-22 14:24 ` Quentin Schulz 0 siblings, 1 reply; 14+ messages in thread From: Tom Rini @ 2025-10-22 13:54 UTC (permalink / raw) To: Quentin Schulz; +Cc: u-boot, Heinrich Schuchardt [-- Attachment #1: Type: text/plain, Size: 1164 bytes --] On Wed, Oct 22, 2025 at 11:19:21AM +0200, Quentin Schulz wrote: > Hi Tom, > > On 10/21/25 10:25 PM, Tom Rini wrote: > [...] > > diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst > > index 58240c5279cd..cb353975eb82 100644 > > --- a/doc/usage/cmdline.rst > > +++ b/doc/usage/cmdline.rst > > @@ -55,6 +55,12 @@ General rules > > command will cause "run" to terminate, i. e. the remaining > > variables are not executed. > > +#. The variable `?` will be set as the return value of any command. These > > s/These/The possible/ ? Sure. > > + values are 0 on success, -1 on a usage related errors, i. e. invalid syntax > > s/a// > or > s/a/any/ > ? I'll drop 'a'. > I would also add a comma after "syntax". Is that oxford comma or no? > > Should i.e. be e.g.? c.f. https://en.wiktionary.org/wiki/i.e. > > > + and 1 on any other error. Any exceptions to this are documented by the > > + specific command, i. e. :doc:`cmd/for` sets this based on the last command > > s/i. e./e.g./ Maybe? In both cases I'm following the example in the previous rule here that's quoted for context. -- Tom [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 228 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 1/3] doc: usage: Add general rule for `$?` 2025-10-22 13:54 ` Tom Rini @ 2025-10-22 14:24 ` Quentin Schulz 0 siblings, 0 replies; 14+ messages in thread From: Quentin Schulz @ 2025-10-22 14:24 UTC (permalink / raw) To: Tom Rini; +Cc: u-boot, Heinrich Schuchardt On 10/22/25 3:54 PM, Tom Rini wrote: > On Wed, Oct 22, 2025 at 11:19:21AM +0200, Quentin Schulz wrote: >> Hi Tom, >> >> On 10/21/25 10:25 PM, Tom Rini wrote: >>> diff --git a/doc/usage/cmdline.rst b/doc/usage/cmdline.rst [...] >>> + values are 0 on success, -1 on a usage related errors, i. e. invalid syntax [...] >> I would also add a comma after "syntax". > > Is that oxford comma or no? > I don't believe so? "Values are 0 on success, -1 on usage related errors and 1 on any other error." With Oxford comma: "Values are 0 on success, -1 on usage related errors, and 1 on any other error." Here it's simply to "close" an example/clarification/extension: "I found an apple, an orange, next to a kiwi and a potato." "I found an apple, an orange, next to a kiwi, and a potato." In the second sentence *I* (so to take with a grain of salt as I'm not a native speaker :) ), I know the potato is not necessarily next to the kiwi, it's just that I found one. In the first sentence, it's implied because otherwise the sentence would be "odd" (removing "useless" info would mean the sentence is now "I found an apple, an orange."). I could even see "I found an apple, an orange (next to a kiwi) and a potato." so values are 0 on success, -1 on a usage related errors (i.e. invalid syntax) and 1 on any other error. Anyway, nothing important (nor necessarily proper English). >> >> Should i.e. be e.g.? c.f. https://en.wiktionary.org/wiki/i.e. >> This one "it depends", if the only possible usage related error is a syntax error, "i.e." is fine, otherwise not. >>> + and 1 on any other error. Any exceptions to this are documented by the >>> + specific command, i. e. :doc:`cmd/for` sets this based on the last command >> >> s/i. e./e.g./ > > Maybe? In both cases I'm following the example in the previous rule here > that's quoted for context. > That's for sure not an "i.e." that should be here. Replace "i.e." with "that is" or "in other words" and if it doesn't work, it's likely "e.g." (to be replaced with "for example"). Cheers, Quentin ^ permalink raw reply [flat|nested] 14+ messages in thread
* [PATCH 2/3] doc: askenv: Reword and remove return value 2025-10-21 20:25 [PATCH 0/3] doc: Add a general note about $? Tom Rini 2025-10-21 20:25 ` [PATCH 1/3] doc: usage: Add general rule for `$?` Tom Rini @ 2025-10-21 20:25 ` Tom Rini 2025-10-22 9:28 ` Quentin Schulz 2025-10-21 20:25 ` [PATCH 3/3] doc: seama: Reword return value section Tom Rini 2 siblings, 1 reply; 14+ messages in thread From: Tom Rini @ 2025-10-21 20:25 UTC (permalink / raw) To: u-boot; +Cc: Heinrich Schuchardt With the addition of general text about how the return value is handled, remove the examples from the askenv documentation as they are all normal expected results. Signed-off-by: Tom Rini <trini@konsulko.com> --- Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> --- doc/usage/cmd/askenv.rst | 27 +++------------------------ 1 file changed, 3 insertions(+), 24 deletions(-) diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst index e2b3c5379aea..a8867ce4d266 100644 --- a/doc/usage/cmd/askenv.rst +++ b/doc/usage/cmd/askenv.rst @@ -42,9 +42,8 @@ Value of a environment variable env1 without message and size parameters: :: - => askenv env1;echo $? + => askenv env1 Please enter 'env1': val1 - 0 => printenv env1 env1=val1 @@ -52,9 +51,8 @@ Value of a environment variable env2 with message and size parameters: :: - => askenv env2 Please type-in a value for env2: 10;echo $? + => askenv env2 Please type-in a value for env2: 10 Please type-in a value for env2: 1234567890123 - 0 => printenv env2 env2=1234567890 @@ -62,31 +60,12 @@ Value of a environment variable env3 with size parameter only: :: - => askenv env3 10;echo $? + => askenv env3 10 Please enter 'env3': val3 - 0 => printenv env3 env3=val3 -Return Value of askenv command, when used without any other arguments: - -:: - - => askenv;echo $? - askenv - get environment variables from stdin - - Usage: - askenv name [message] [size] - - display 'message' and get environment variable 'name' from stdin (max 'size' chars) - 1 - Configuration ------------- The askenv command is only available if CMD_ASKENV=y - -Return value ------------- - -The return value $? is set to 0 (true). -If no other arguments are specified (along with askenv), it is set to 1 (false). -- 2.43.0 ^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: [PATCH 2/3] doc: askenv: Reword and remove return value 2025-10-21 20:25 ` [PATCH 2/3] doc: askenv: Reword and remove return value Tom Rini @ 2025-10-22 9:28 ` Quentin Schulz 2025-10-22 13:49 ` Tom Rini 0 siblings, 1 reply; 14+ messages in thread From: Quentin Schulz @ 2025-10-22 9:28 UTC (permalink / raw) To: Tom Rini, u-boot; +Cc: Heinrich Schuchardt Hi Tom, On 10/21/25 10:25 PM, Tom Rini wrote: > With the addition of general text about how the return value is handled, > remove the examples from the askenv documentation as they are all normal > expected results. > > Signed-off-by: Tom Rini <trini@konsulko.com> > --- > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > --- > doc/usage/cmd/askenv.rst | 27 +++------------------------ > 1 file changed, 3 insertions(+), 24 deletions(-) > > diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst > index e2b3c5379aea..a8867ce4d266 100644 > --- a/doc/usage/cmd/askenv.rst > +++ b/doc/usage/cmd/askenv.rst [...] > -Return Value of askenv command, when used without any other arguments: > - > -:: > - > - => askenv;echo $? > - askenv - get environment variables from stdin > - > - Usage: > - askenv name [message] [size] > - - display 'message' and get environment variable 'name' from stdin (max 'size' chars) > - 1 Shouldn't that be -1 here to match the expected return value when the syntax is incorrect? If it is 1, then it's a difference to the expected return value and thus should be documented below? Cheers, Quentin ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 2/3] doc: askenv: Reword and remove return value 2025-10-22 9:28 ` Quentin Schulz @ 2025-10-22 13:49 ` Tom Rini 2025-10-22 14:06 ` Quentin Schulz 0 siblings, 1 reply; 14+ messages in thread From: Tom Rini @ 2025-10-22 13:49 UTC (permalink / raw) To: Quentin Schulz; +Cc: u-boot, Heinrich Schuchardt [-- Attachment #1: Type: text/plain, Size: 1911 bytes --] On Wed, Oct 22, 2025 at 11:28:15AM +0200, Quentin Schulz wrote: > Hi Tom, > > On 10/21/25 10:25 PM, Tom Rini wrote: > > With the addition of general text about how the return value is handled, > > remove the examples from the askenv documentation as they are all normal > > expected results. > > > > Signed-off-by: Tom Rini <trini@konsulko.com> > > --- > > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > > --- > > doc/usage/cmd/askenv.rst | 27 +++------------------------ > > 1 file changed, 3 insertions(+), 24 deletions(-) > > > > diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst > > index e2b3c5379aea..a8867ce4d266 100644 > > --- a/doc/usage/cmd/askenv.rst > > +++ b/doc/usage/cmd/askenv.rst > [...] > > -Return Value of askenv command, when used without any other arguments: > > - > > -:: > > - > > - => askenv;echo $? > > - askenv - get environment variables from stdin > > - > > - Usage: > > - askenv name [message] [size] > > - - display 'message' and get environment variable 'name' from stdin (max 'size' chars) > > - 1 > > Shouldn't that be -1 here to match the expected return value when the syntax > is incorrect? > > If it is 1, then it's a difference to the expected return value and thus > should be documented below? This was included seemingly to include the built-in help message in-text. If desired, we should figure out how to do that automatically and for all commands. This is separate from what I see this morning right now of any invalid usage returning "1" and not "-1". This is from sandbox build yesterday on top of tree: => loadm y y y y y y loadm - load binary blob from source address to destination address Usage: loadm [src_addr] [dst_addr] [size] - load a binary blob from one memory location to other from src_addr to dst_addr by size bytes => echo $? 1 -- Tom [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 228 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 2/3] doc: askenv: Reword and remove return value 2025-10-22 13:49 ` Tom Rini @ 2025-10-22 14:06 ` Quentin Schulz 2025-10-22 14:47 ` Tom Rini 0 siblings, 1 reply; 14+ messages in thread From: Quentin Schulz @ 2025-10-22 14:06 UTC (permalink / raw) To: Tom Rini; +Cc: u-boot, Heinrich Schuchardt On 10/22/25 3:49 PM, Tom Rini wrote: > On Wed, Oct 22, 2025 at 11:28:15AM +0200, Quentin Schulz wrote: >> Hi Tom, >> >> On 10/21/25 10:25 PM, Tom Rini wrote: >>> With the addition of general text about how the return value is handled, >>> remove the examples from the askenv documentation as they are all normal >>> expected results. >>> >>> Signed-off-by: Tom Rini <trini@konsulko.com> >>> --- >>> Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> >>> --- >>> doc/usage/cmd/askenv.rst | 27 +++------------------------ >>> 1 file changed, 3 insertions(+), 24 deletions(-) >>> >>> diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst >>> index e2b3c5379aea..a8867ce4d266 100644 >>> --- a/doc/usage/cmd/askenv.rst >>> +++ b/doc/usage/cmd/askenv.rst >> [...] >>> -Return Value of askenv command, when used without any other arguments: >>> - >>> -:: >>> - >>> - => askenv;echo $? >>> - askenv - get environment variables from stdin >>> - >>> - Usage: >>> - askenv name [message] [size] >>> - - display 'message' and get environment variable 'name' from stdin (max 'size' chars) >>> - 1 >> >> Shouldn't that be -1 here to match the expected return value when the syntax >> is incorrect? >> >> If it is 1, then it's a difference to the expected return value and thus >> should be documented below? > > This was included seemingly to include the built-in help message > in-text. If desired, we should figure out how to do that automatically > and for all commands. > Agreed, it'd be awesome to extract the _usage part of U_BOOT_CMDs as summary for doc/usage/cmd/*.rst and _help part as the synopsis part so that they don't need to be kept in sync (at least that part). > This is separate from what I see this morning right now of any invalid > usage returning "1" and not "-1". > > This is from sandbox build yesterday on top of tree: > => loadm y y y y y y > loadm - load binary blob from source address to destination address > > Usage: > loadm [src_addr] [dst_addr] [size] > - load a binary blob from one memory location to other from src_addr to dst_addr by size bytes > => echo $? > 1 > Then patch 1 is wrong? Or rather, what is moved in patch 1 is wrong? """ values are 0 on success, -1 on a usage related errors, i. e. invalid syntax and 1 on any other error. """ loadm y y y y y y would be an invalid syntax, meaning the return value is expected to be -1 according to the definition above. ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 2/3] doc: askenv: Reword and remove return value 2025-10-22 14:06 ` Quentin Schulz @ 2025-10-22 14:47 ` Tom Rini 0 siblings, 0 replies; 14+ messages in thread From: Tom Rini @ 2025-10-22 14:47 UTC (permalink / raw) To: Quentin Schulz; +Cc: u-boot, Heinrich Schuchardt [-- Attachment #1: Type: text/plain, Size: 3020 bytes --] On Wed, Oct 22, 2025 at 04:06:09PM +0200, Quentin Schulz wrote: > On 10/22/25 3:49 PM, Tom Rini wrote: > > On Wed, Oct 22, 2025 at 11:28:15AM +0200, Quentin Schulz wrote: > > > Hi Tom, > > > > > > On 10/21/25 10:25 PM, Tom Rini wrote: > > > > With the addition of general text about how the return value is handled, > > > > remove the examples from the askenv documentation as they are all normal > > > > expected results. > > > > > > > > Signed-off-by: Tom Rini <trini@konsulko.com> > > > > --- > > > > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > > > > --- > > > > doc/usage/cmd/askenv.rst | 27 +++------------------------ > > > > 1 file changed, 3 insertions(+), 24 deletions(-) > > > > > > > > diff --git a/doc/usage/cmd/askenv.rst b/doc/usage/cmd/askenv.rst > > > > index e2b3c5379aea..a8867ce4d266 100644 > > > > --- a/doc/usage/cmd/askenv.rst > > > > +++ b/doc/usage/cmd/askenv.rst > > > [...] > > > > -Return Value of askenv command, when used without any other arguments: > > > > - > > > > -:: > > > > - > > > > - => askenv;echo $? > > > > - askenv - get environment variables from stdin > > > > - > > > > - Usage: > > > > - askenv name [message] [size] > > > > - - display 'message' and get environment variable 'name' from stdin (max 'size' chars) > > > > - 1 > > > > > > Shouldn't that be -1 here to match the expected return value when the syntax > > > is incorrect? > > > > > > If it is 1, then it's a difference to the expected return value and thus > > > should be documented below? > > > > This was included seemingly to include the built-in help message > > in-text. If desired, we should figure out how to do that automatically > > and for all commands. > > > > Agreed, it'd be awesome to extract the _usage part of U_BOOT_CMDs as summary > for doc/usage/cmd/*.rst and _help part as the synopsis part so that they > don't need to be kept in sync (at least that part). > > > This is separate from what I see this morning right now of any invalid > > usage returning "1" and not "-1". > > > > This is from sandbox build yesterday on top of tree: > > => loadm y y y y y y > > loadm - load binary blob from source address to destination address > > > > Usage: > > loadm [src_addr] [dst_addr] [size] > > - load a binary blob from one memory location to other from src_addr to dst_addr by size bytes > > => echo $? > > 1 > > > > Then patch 1 is wrong? Or rather, what is moved in patch 1 is wrong? > > """ > values are 0 on success, -1 on a usage related errors, i. e. invalid syntax > and 1 on any other error. > """ > > loadm y y y y y y would be an invalid syntax, meaning the return value is > expected to be -1 according to the definition above. Yes. So while internally we do differentiate between failure of the command and invalid syntax, we do not seem to populate that to the user. I had misread one of the headers, so I'll rework the first patch. Thanks! -- Tom [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 228 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* [PATCH 3/3] doc: seama: Reword return value section 2025-10-21 20:25 [PATCH 0/3] doc: Add a general note about $? Tom Rini 2025-10-21 20:25 ` [PATCH 1/3] doc: usage: Add general rule for `$?` Tom Rini 2025-10-21 20:25 ` [PATCH 2/3] doc: askenv: Reword and remove return value Tom Rini @ 2025-10-21 20:25 ` Tom Rini 2025-10-22 9:33 ` Quentin Schulz 2 siblings, 1 reply; 14+ messages in thread From: Tom Rini @ 2025-10-21 20:25 UTC (permalink / raw) To: u-boot; +Cc: Heinrich Schuchardt With the addition of general text about how the return value is handled, reference that while retaining the additional information about setting $seama_image_size Signed-off-by: Tom Rini <trini@konsulko.com> --- Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> --- doc/usage/cmd/seama.rst | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/doc/usage/cmd/seama.rst b/doc/usage/cmd/seama.rst index 17fd559f4856..a6b00f32902e 100644 --- a/doc/usage/cmd/seama.rst +++ b/doc/usage/cmd/seama.rst @@ -56,8 +56,5 @@ The command is available if CONFIG_CMD_SEAMA=y. Return value ------------ -The return value $? is set 0 (true) if the loading is succefull, and -is set to 1 (false) in case of error. - -The environment variable $seama_image_size is set to the size of the -loaded SEAMA image. +Along with the general rules for setting $?, the environment variable +$seama_image_size is set to the size of the loaded SEAMA image. -- 2.43.0 ^ permalink raw reply related [flat|nested] 14+ messages in thread
* Re: [PATCH 3/3] doc: seama: Reword return value section 2025-10-21 20:25 ` [PATCH 3/3] doc: seama: Reword return value section Tom Rini @ 2025-10-22 9:33 ` Quentin Schulz 2025-10-22 13:51 ` Tom Rini 0 siblings, 1 reply; 14+ messages in thread From: Quentin Schulz @ 2025-10-22 9:33 UTC (permalink / raw) To: Tom Rini, u-boot; +Cc: Heinrich Schuchardt Hi Tom, On 10/21/25 10:25 PM, Tom Rini wrote: > With the addition of general text about how the return value is handled, > reference that while retaining the additional information about setting > $seama_image_size > > Signed-off-by: Tom Rini <trini@konsulko.com> > --- > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > --- > doc/usage/cmd/seama.rst | 7 ++----- > 1 file changed, 2 insertions(+), 5 deletions(-) > > diff --git a/doc/usage/cmd/seama.rst b/doc/usage/cmd/seama.rst > index 17fd559f4856..a6b00f32902e 100644 > --- a/doc/usage/cmd/seama.rst > +++ b/doc/usage/cmd/seama.rst > @@ -56,8 +56,5 @@ The command is available if CONFIG_CMD_SEAMA=y. > Return value > ------------ > > -The return value $? is set 0 (true) if the loading is succefull, and > -is set to 1 (false) in case of error. > - > -The environment variable $seama_image_size is set to the size of the > -loaded SEAMA image. > +Along with the general rules for setting $?, the environment variable > +$seama_image_size is set to the size of the loaded SEAMA image. Maybe add "as reported by the SEAMA image header" as that seems to be what is reported in this variable reading cmd/seama.c? Also wondering if this shouldn't be in a separate section like "Side effects" since it isn't really the return value. I'm thinking doc/usage/cmd/fatload.rst (and a few others) could benefit from something like that to explain filesize env variable is set automatically. Cheers, Quentin ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 3/3] doc: seama: Reword return value section 2025-10-22 9:33 ` Quentin Schulz @ 2025-10-22 13:51 ` Tom Rini 2025-10-22 14:09 ` Quentin Schulz 0 siblings, 1 reply; 14+ messages in thread From: Tom Rini @ 2025-10-22 13:51 UTC (permalink / raw) To: Quentin Schulz; +Cc: u-boot, Heinrich Schuchardt [-- Attachment #1: Type: text/plain, Size: 2067 bytes --] On Wed, Oct 22, 2025 at 11:33:30AM +0200, Quentin Schulz wrote: > Hi Tom, > > On 10/21/25 10:25 PM, Tom Rini wrote: > > With the addition of general text about how the return value is handled, > > reference that while retaining the additional information about setting > > $seama_image_size > > > > Signed-off-by: Tom Rini <trini@konsulko.com> > > --- > > Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> > > --- > > doc/usage/cmd/seama.rst | 7 ++----- > > 1 file changed, 2 insertions(+), 5 deletions(-) > > > > diff --git a/doc/usage/cmd/seama.rst b/doc/usage/cmd/seama.rst > > index 17fd559f4856..a6b00f32902e 100644 > > --- a/doc/usage/cmd/seama.rst > > +++ b/doc/usage/cmd/seama.rst > > @@ -56,8 +56,5 @@ The command is available if CONFIG_CMD_SEAMA=y. > > Return value > > ------------ > > -The return value $? is set 0 (true) if the loading is succefull, and > > -is set to 1 (false) in case of error. > > - > > -The environment variable $seama_image_size is set to the size of the > > -loaded SEAMA image. > > +Along with the general rules for setting $?, the environment variable > > +$seama_image_size is set to the size of the loaded SEAMA image. > > Maybe add "as reported by the SEAMA image header" as that seems to be what > is reported in this variable reading cmd/seama.c? > > Also wondering if this shouldn't be in a separate section like "Side > effects" since it isn't really the return value. I'm thinking > doc/usage/cmd/fatload.rst (and a few others) could benefit from something > like that to explain filesize env variable is set automatically. Perhaps, but I would see all of that as future clean-ups, I'm just trying to get (most) everything consistent first. I say most because on reflection, I think a number of commands that say they only return 0 are just not mentioning invalid syntax, but verifying that is a more involved process (I did check a few commands that say the only ever return 0 and saw the normal CMD_RET_USAGE checks, so removed their incorrect text). -- Tom [-- Attachment #2: signature.asc --] [-- Type: application/pgp-signature, Size: 228 bytes --] ^ permalink raw reply [flat|nested] 14+ messages in thread
* Re: [PATCH 3/3] doc: seama: Reword return value section 2025-10-22 13:51 ` Tom Rini @ 2025-10-22 14:09 ` Quentin Schulz 0 siblings, 0 replies; 14+ messages in thread From: Quentin Schulz @ 2025-10-22 14:09 UTC (permalink / raw) To: Tom Rini; +Cc: u-boot, Heinrich Schuchardt On 10/22/25 3:51 PM, Tom Rini wrote: > On Wed, Oct 22, 2025 at 11:33:30AM +0200, Quentin Schulz wrote: >> Hi Tom, >> >> On 10/21/25 10:25 PM, Tom Rini wrote: >>> With the addition of general text about how the return value is handled, >>> reference that while retaining the additional information about setting >>> $seama_image_size >>> >>> Signed-off-by: Tom Rini <trini@konsulko.com> >>> --- >>> Cc: Heinrich Schuchardt <xypron.glpk@gmx.de> >>> --- >>> doc/usage/cmd/seama.rst | 7 ++----- >>> 1 file changed, 2 insertions(+), 5 deletions(-) >>> >>> diff --git a/doc/usage/cmd/seama.rst b/doc/usage/cmd/seama.rst >>> index 17fd559f4856..a6b00f32902e 100644 >>> --- a/doc/usage/cmd/seama.rst >>> +++ b/doc/usage/cmd/seama.rst >>> @@ -56,8 +56,5 @@ The command is available if CONFIG_CMD_SEAMA=y. >>> Return value >>> ------------ >>> -The return value $? is set 0 (true) if the loading is succefull, and >>> -is set to 1 (false) in case of error. >>> - >>> -The environment variable $seama_image_size is set to the size of the >>> -loaded SEAMA image. >>> +Along with the general rules for setting $?, the environment variable >>> +$seama_image_size is set to the size of the loaded SEAMA image. >> >> Maybe add "as reported by the SEAMA image header" as that seems to be what >> is reported in this variable reading cmd/seama.c? >> >> Also wondering if this shouldn't be in a separate section like "Side >> effects" since it isn't really the return value. I'm thinking >> doc/usage/cmd/fatload.rst (and a few others) could benefit from something >> like that to explain filesize env variable is set automatically. > > Perhaps, but I would see all of that as future clean-ups, I'm just > trying to get (most) everything consistent first. > > I say most because on reflection, I think a number of commands that say > they only return 0 are just not mentioning invalid syntax, but > verifying that is a more involved process (I did check a few commands > that say the only ever return 0 and saw the normal CMD_RET_USAGE checks, > so removed their incorrect text). > Fair, I sometimes forget in the review that not everything part of the feedback needs to be part of this patch or series. Considering it does match the current wording and just aligns with the rest of the commands, this is fine. The seama command seems to be handling the usage syntax error and "normal" errors as reported in patch 1, so: Reviewed-by: Quentin Schulz <quentin.schulz@cherry.de> Thanks! Quentin ^ permalink raw reply [flat|nested] 14+ messages in thread
end of thread, other threads:[~2025-10-22 14:47 UTC | newest] Thread overview: 14+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2025-10-21 20:25 [PATCH 0/3] doc: Add a general note about $? Tom Rini 2025-10-21 20:25 ` [PATCH 1/3] doc: usage: Add general rule for `$?` Tom Rini 2025-10-22 9:19 ` Quentin Schulz 2025-10-22 13:54 ` Tom Rini 2025-10-22 14:24 ` Quentin Schulz 2025-10-21 20:25 ` [PATCH 2/3] doc: askenv: Reword and remove return value Tom Rini 2025-10-22 9:28 ` Quentin Schulz 2025-10-22 13:49 ` Tom Rini 2025-10-22 14:06 ` Quentin Schulz 2025-10-22 14:47 ` Tom Rini 2025-10-21 20:25 ` [PATCH 3/3] doc: seama: Reword return value section Tom Rini 2025-10-22 9:33 ` Quentin Schulz 2025-10-22 13:51 ` Tom Rini 2025-10-22 14:09 ` Quentin Schulz
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.