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 mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id AD4FDC433F5 for ; Sat, 23 Oct 2021 08:24:13 +0000 (UTC) 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 mail.kernel.org (Postfix) with ESMTPS id 73B6C60FBF for ; Sat, 23 Oct 2021 08:24:12 +0000 (UTC) DMARC-Filter: OpenDMARC Filter v1.4.1 mail.kernel.org 73B6C60FBF Authentication-Results: mail.kernel.org; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: mail.kernel.org; spf=pass smtp.mailfrom=lists.denx.de Received: from h2850616.stratoserver.net (localhost [IPv6:::1]) by phobos.denx.de (Postfix) with ESMTP id 4DA20833D4; Sat, 23 Oct 2021 10:24:10 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=fail (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=u-boot-bounces@lists.denx.de Authentication-Results: phobos.denx.de; dkim=pass (1024-bit key; secure) header.d=gmx.net header.i=@gmx.net header.b="aZUZGDCd"; dkim-atps=neutral Received: by phobos.denx.de (Postfix, from userid 109) id 6AB4D833D4; Sat, 23 Oct 2021 10:24:08 +0200 (CEST) Received: from mout.gmx.net (mout.gmx.net [212.227.17.21]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) (No client certificate requested) by phobos.denx.de (Postfix) with ESMTPS id 4CB0383303; Sat, 23 Oct 2021 10:24:00 +0200 (CEST) Authentication-Results: phobos.denx.de; dmarc=pass (p=none dis=none) header.from=gmx.de Authentication-Results: phobos.denx.de; spf=pass smtp.mailfrom=xypron.glpk@gmx.de DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=gmx.net; s=badeba3b8450; t=1634977432; bh=0zyvD05oCq13rxwkFlLFmHLAeVbg6O1324ZkPmSzfS0=; h=X-UI-Sender-Class:Date:Subject:To:Cc:References:From:In-Reply-To; b=aZUZGDCdmcORFqDTSoVKQRR0HmjTY5ST2OhkuHFLnxMOTohHYz12sn3XRN79MqZpM 6NjjUwE2p8tB5OwDfsgW2RptXDj11Nd7SstgkBfIgk4bkTfgoRtM/Wd073luRHhn+9 IC9gMha4pvU6nIO6B2/VKeea8ZOZRv2qz9nO5/r8= X-UI-Sender-Class: 01bb95c1-4bf8-414a-932a-4f6e2808ef9c Received: from [192.168.123.35] ([88.152.144.157]) by mail.gmx.net (mrgmx105 [212.227.17.168]) with ESMTPSA (Nemesis) id 1MYvcG-1m9NnM0vy4-00Uvyi; Sat, 23 Oct 2021 10:23:52 +0200 Message-ID: <134ab4e3-59a9-a246-69bb-a29595934f96@gmx.de> Date: Sat, 23 Oct 2021 10:23:50 +0200 MIME-Version: 1.0 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.1.2 Subject: Re: [PATCH v10 7/9] doc: Improve environment documentation further Content-Language: en-US To: Simon Glass , U-Boot Mailing List Cc: Wolfgang Denk , u-boot-board-maintainers@lists.denx.de, Rasmus Villemoes , u-boot-custodians@lists.denx.de, Tom Rini , =?UTF-8?Q?Marek_Beh=c3=ban?= References: <20211022030852.1986718-1-sjg@chromium.org> <20211022030852.1986718-6-sjg@chromium.org> From: Heinrich Schuchardt In-Reply-To: <20211022030852.1986718-6-sjg@chromium.org> Content-Type: text/plain; charset=UTF-8; format=flowed Content-Transfer-Encoding: quoted-printable X-Provags-ID: V03:K1:r/EAwE2nh1GWHSbZJqn7MRnMkeVccWt/YFwNmX4iuEt8DerscXX 0rS4dP2dw8fy01lQw9mUBfkn8GG/5qfibP7XgVuGy3wicpdXOTuuchcR6S1lF/a1dENZuAb yO/p7uzNDG2XnyZchd3Vl5RjnBPLbmqka4KWtsXAhll7HblJmJ5tGdez/B3GrEfpL7Kf/vE pYhmRjECM+1Jgv7A54svA== X-UI-Out-Filterresults: notjunk:1;V03:K0:6uSYr4s2Dyo=:jOgHjydeqptOQ2oLx/eNpq fnIo6QlcJvki9nXTo/wBCNrmZLZ0yQ5xeqrsWyBPGgx3mC5c5f7GsU4w4C/J+YKYbECdlAwcf QOJXc+8bvIu7zh5Rz2F15kkU7CScmOH3/hng4kMn0r+eulEXiFSwB/bR0Xu6ruHpJzaI9cqDJ X6I9uKWmlvhUVaNe20keAmjWkPHV2+Z9vvLATO3wvhvnBSYybmfm91f2s8OhkoW0w9SDgwl7+ iuhw7WGqCKh0yOgTExHhOnjRPfVe2P6CMKU0NuJKcdXXZxwlXs5rnqoSCSyCJk8HjghQHK0FH XziSUd6yXnGNicKalQV9Yv2LH+tIxN25AZcjOCmGsnhSUFSGZC03jA07cvoz3OfUCdhtrmtAA 7zLrheztHf2HlW9qbJ9nFNxe0euec94KJh1DA+5xfRFLf1OdJCLpB96t8VIhUpdQrNHuXQKNQ eWWibdciGx7XNI/Hmtrqw4wpxkADMRgbN9xuCGhvTAAwthUmVUFWUDDpDOY85ZDt3FLlcH4Al FCw+LxEpBUOSrjFIatvFbpdwNoUWLWN/GDB5CzGul82LZpzX9WVgtVXvkHZR8GihxhpA7YuvK nlg9wgBls6sQhl2S2U8/sj2CNXxrmtZqui5YscC96fVAfs/97OnTrO/NwFhRuofMFtx+mMetQ 6OCYVRxFnre9hn8DdAs7QUNhd5QkGuhBwnipp04m/8x/t4ipcIGVoijvRJpaqgpF0Rdn4eaHn uNsy5tip7r6osAZGsfFd10wYY98Lac+9Zps7WDuxRqB9AHjoa+jFAlTwymUnyIwGkrTCjCIaj nIiuQlXbOdm6nMunnWtxPD5xLHK8TkJvnThgc+Q7KfhYA5LqxUzd6IlN7eBFdptmSmSWqOvlg R+iT+awbxQ4lcZgbBl2Pq2DWwwXk82hCX0L+yLSToIV4qdJkK5cTTrMjjziCrfYW+t+eIEqzl ObwDVjj+0sU5k5MPqSS4WYMOZPowi31wS2sbRE/TCsrmLueemf/BJNGEz3gMlnlyWMuKILzll 4mCbPu4vPZlAH8uOHAHwKdOA6CJWZxb/ovzUGPcsRiz0VvOJ4vhCWkSP6aJAWclH2eB5F6tGv RFrWQ7DwLQkUE8= X-BeenThere: u-boot@lists.denx.de X-Mailman-Version: 2.1.34 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.2 at phobos.denx.de X-Virus-Status: Clean On 10/22/21 05:08, Simon Glass wrote: > Make various other updates suggested during review of the rST conversion= . > > Signed-off-by: Simon Glass > Suggested-by: Heinrich Schuchardt > --- > > Changes in v10: > - Add updates as suggested by Heinrich > > doc/develop/environment.rst | 51 ++++++++++++++++ > doc/develop/index.rst | 1 + > doc/usage/environment.rst | 115 ++++++++++++++---------------------- > 3 files changed, 95 insertions(+), 72 deletions(-) > create mode 100644 doc/develop/environment.rst > > diff --git a/doc/develop/environment.rst b/doc/develop/environment.rst > new file mode 100644 > index 00000000000..0b86fafbff7 > --- /dev/null > +++ b/doc/develop/environment.rst > @@ -0,0 +1,51 @@ > +.. SPDX-License-Identifier: GPL-2.0+ > + > +Environment implementation > +=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D > + > +See :doc:`../usage/environment` for usage information. > + > +Callback functions for environment variables > +-------------------------------------------- > + > +For some environment variables, the behavior of u-boot needs to change > +when their values are changed. This functionality allows functions to > +be associated with arbitrary variables. On creation, overwrite, or > +deletion, the callback will provide the opportunity for some side > +effect to happen or for the change to be rejected. > + > +The callbacks are named and associated with a function using the > +U_BOOT_ENV_CALLBACK macro in your board or driver code. > + > +These callbacks are associated with variables in one of two ways. The > +static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC > +in the board configuration to a string that defines a list of > +associations. The list must be in the following format:: > + > + entry =3D variable_name[:callback_name] > + list =3D entry[,list] > + > +If the callback name is not specified, then the callback is deleted. > +Spaces are also allowed anywhere in the list. > + > +Callbacks can also be associated by defining the ".callbacks" variable > +with the same list format above. Any association in ".callbacks" will > +override any association in the static list. You can define > +CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the > +".callbacks" environment variable in the default or embedded environmen= t. > + > +If CONFIG_REGEX is defined, the variable_name above is evaluated as a > +regular expression. This allows multiple variables to be connected to > +the same callback without explicitly listing them all out. > + > +The signature of the callback functions is:: > + > + int callback(const char *name, const char *value, enum env_op op, i= nt flags) > + > +* name - changed environment variable > +* value - new value of the environment variable > +* op - operation (create, overwrite, or delete) > +* flags - attributes of the environment variable change, see flags H_* = in > + include/search.h > + > +The return value is 0 if the variable change is accepted and 1 otherwis= e. > diff --git a/doc/develop/index.rst b/doc/develop/index.rst > index 5e064a4dac1..9eee8190453 100644 > --- a/doc/develop/index.rst > +++ b/doc/develop/index.rst > @@ -15,6 +15,7 @@ Implementation > config_binding > devicetree/index > driver-model/index > + environment > global_data > logging > makefiles > diff --git a/doc/usage/environment.rst b/doc/usage/environment.rst > index af193739a5a..8ddc672d467 100644 > --- a/doc/usage/environment.rst > +++ b/doc/usage/environment.rst > @@ -3,11 +3,11 @@ > Environment Variables > =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D > > -U-Boot supports user configuration using Environment Variables which > +U-Boot supports user configuration using environment variables which > can be made persistent by saving to persistent storage, for example fl= ash > memory. > > -Environment Variables are set using "env set" (alias "setenv"), printed= using > +Environment variables are set using "env set" (alias "setenv"), printed= using > "env print" (alias "printenv"), and saved to persistent storage using > "env save" (alias "saveenv"). Using "env set" > without a value can be used to delete a variable from the > @@ -98,27 +98,37 @@ environment but work is underway to address this. > List of environment variables > ----------------------------- > > -Some configuration options can be set using Environment Variables. In m= any cases > -the value in the default environment comes from a CONFIG option - see > +Some device configuration options can be set using environment variable= s. In > +many cases the value in the default environment comes from a CONFIG opt= ion - see > `include/env_default.h`) for this. > > This is most-likely not complete: > > baudrate > - Current baud rate used by the serial console. The built-in value is= set by > - CONFIG_BAUDRATE (see `drivers/serial/Kconfig`) > + Used to set the baudrate of the UART - it defaults to CONFIG_BAUDRA= TE (which > + defaults to 115200). > > bootdelay > - Current autoboot delay. The built-in value is set by CONFIG_BOOTDEL= AY (see > - `common/Kconfig`) > + Delay before automatically running bootcmd. During this time the us= er > + can choose to enter the shell (or the boot menu if > + CONFIG_AUTOBOOT_MENU_SHOW=3Dy): > + > + - 0 to autoboot with no delay, but you can stop it by key input. > + - -1 to disable autoboot. > + - -2 to autoboot with no delay and not check for abort > + > + The default value is defined by CONFIG_BOOTDELAY. > + The value of 'bootdelay' is overridden by the /config/bootdelay val= ue in > + the device-tree if CONFIG_OF_CONTROL=3Dy. > + Does it really make sense that the devicetree overrides the user se= tting? This sentence was not meant for inclusion. It was just as comment on the code. Adding this to a man-page is irritating users. You could at it as a TODO in the code. > > bootcmd > - Defines a command string that is automatically executed when no cha= racter > - is read on the console interface within a cetain boot delay after r= eset. > - The built-in value is set by CONFIG_BOOTCOMMAND (see `common/Kconfi= g`) > + The command that is run if the user does not enter the shell during= the > + boot delay. > > bootargs > - Boot arguments when booting an RTOS image > + Command line arguments passed when booting an operating system or b= inary > + image > > bootfile > Name of the image to load with TFTP > @@ -159,12 +169,12 @@ updatefile > > autoload > if set to "no" (any string beginning with 'n'), > - "bootp" will just load perform a lookup of the > + "bootp" and "dhcp" will just load perform a lookup of the > configuration from the BOOTP server, but not try to > load any image using TFTP or DHCP. %s/using TFTP or DHCP// DHCP is not a protocol to load images. A DHCP server may indicate a TFPT server. > > autostart > - if set to "yes", an image loaded using the "bootp", > + if set to "yes", an image loaded using the "bootp", "dhcp", > "rarpboot", "tftpboot" or "diskboot" commands will > be automatically started (by internally calling > "bootm") > @@ -186,7 +196,8 @@ fdt_high > of the 704 MB low memory, so that Linux kernel can > access it during the boot procedure. > > - If this is set to the special value 0xFFFFFFFF then > + If this is set to the special value 0xffffffff (32-bit machines) or > + 0xffffffffffffffff (64-bit machines) then > the fdt will not be copied at all on boot. For this > to work it must reside in writable memory, have > sufficient padding on the end of it for u-boot to > @@ -220,7 +231,8 @@ initrd_high > > setenv initrd_high 00c00000 > > - If you set initrd_high to 0xFFFFFFFF, this is an > + If you set initrd_high to 0xffffffff (32-bit machines) or > + 0xffffffffffffffff (64-bit machines), this is an > indication to U-Boot that all addresses are legal > for the Linux kernel, including addresses in flash > memory. In this case U-Boot will NOT COPY the > @@ -251,7 +263,7 @@ bootstopkey > see CONFIG_AUTOBOOT_STOP_STR > > ethprime > - controls which interface is used first. > + controls which network interface is used first. > > ethact > controls which interface is currently active. > @@ -265,7 +277,9 @@ ethact > ethrotate > When set to "no" U-Boot does not go through all > available network interfaces. > - It just stays at the currently selected interface. > + It just stays at the currently selected interface. When unset or se= t to > + anything other than "no", U-Boot does go through all > + available network interfaces. > > netretry > When set to "no" each network operation will > @@ -276,12 +290,9 @@ netretry > Useful on scripts which control the retry operation > themselves. > > -npe_ucode > - set load address for the NPE microcode > - > silent_linux > If set then Linux will be told to boot silently, by > - changing the console to be empty. If "yes" it will be > + adding 'console=3D' to its command line. If "yes" it will be > made silent. If "no" it will not be made silent. If > unset, then it will be made silent if the U-Boot console > is silent. > @@ -292,7 +303,7 @@ tftpsrcp > > tftpdstp > If this is set, the value is used for TFTP's UDP > - destination port instead of the Well Know Port 69. > + destination port instead of the default port 69. > > tftpblocksize > Block size to use for TFTP transfers; if not set, > @@ -415,11 +426,12 @@ serial# > contains hardware identification information such as type string a= nd/or > serial number > ethaddr > - Ethernet address > + Ethernet address. If CONFIG_REGEX=3Dy, also eth*addr (where * is an= integer). ethaddr Ethernet address This variable can be set only once. U-Boot refuses to delete or overwrite this variable once it has bee set unless CONFIG_ENV_OVERWRITE is enabled in the board configuration. The same applies to eth*addr (where * is an integer) if CONFIG_REGEX=3Dy. Best regards Heinrich > > These variables can be set only once (usually during manufacturing of > the board). U-Boot refuses to delete or overwrite these variables > -once they have been set once. > +once they have been set, unless CONFIG_ENV_OVERWRITE is enabled in the = board > +configuration. > > Also: > > @@ -429,53 +441,7 @@ ver > readonly (see CONFIG_VERSION_VARIABLE). > > Please note that changes to some configuration parameters may take > -only effect after the next boot (yes, that's just like Windoze :-). > - > - > -Callback functions for environment variables > --------------------------------------------- > - > -For some environment variables, the behavior of u-boot needs to change > -when their values are changed. This functionality allows functions to > -be associated with arbitrary variables. On creation, overwrite, or > -deletion, the callback will provide the opportunity for some side > -effect to happen or for the change to be rejected. > - > -The callbacks are named and associated with a function using the > -U_BOOT_ENV_CALLBACK macro in your board or driver code. > - > -These callbacks are associated with variables in one of two ways. The > -static list can be added to by defining CONFIG_ENV_CALLBACK_LIST_STATIC > -in the board configuration to a string that defines a list of > -associations. The list must be in the following format:: > - > - entry =3D variable_name[:callback_name] > - list =3D entry[,list] > - > -If the callback name is not specified, then the callback is deleted. > -Spaces are also allowed anywhere in the list. > - > -Callbacks can also be associated by defining the ".callbacks" variable > -with the same list format above. Any association in ".callbacks" will > -override any association in the static list. You can define > -CONFIG_ENV_CALLBACK_LIST_DEFAULT to a list (string) to define the > -".callbacks" environment variable in the default or embedded environmen= t. > - > -If CONFIG_REGEX is defined, the variable_name above is evaluated as a > -regular expression. This allows multiple variables to be connected to > -the same callback without explicitly listing them all out. > - > -The signature of the callback functions is:: > - > - int callback(const char *name, const char *value, enum env_op op, i= nt flags) > - > -* name - changed environment variable > -* value - new value of the environment variable > -* op - operation (create, overwrite, or delete) > -* flags - attributes of the environment variable change, see flags H_* = in > - include/search.h > - > -The return value is 0 if the variable change is accepted and 1 otherwis= e. > +only effect after the next boot (yes, that's just like Windows). > > > External environment file > @@ -491,3 +457,8 @@ key=3Dvalue pairs. Blank lines and lines beginning w= ith # are ignored. > > Future work may unify this feature with the text-based environment, pe= rhaps > moving the contents of `env_default.h` to a text file. > + > +Implementation > +-------------- > + > +See :doc:`../develop/environment` for internal development details. >