[PATCH 1/2] doc: add note about characters like hyphens in variable names

[PATCH 1/2] doc: add note about characters like hyphens in variable names

[Ahmad Fatoum]

The mismatch between the allowed characters in shell variables and
device parameters is a common pitfall, especially because device
tree node names often have hyphens in them, which is disallowed by
hush.

While such variables can be read by the ${variable-example}, setting
them is only possible with the setenv command. Reflect this in the
documentation.

Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
Cc: Matthias Fend <Matthias.Fend@wolfvision.net>
---
 Documentation/user/driver-model.rst | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/Documentation/user/driver-model.rst b/Documentation/user/driver-model.rst
index a0fd3e99b55b..c543d6d9c410 100644
--- a/Documentation/user/driver-model.rst
+++ b/Documentation/user/driver-model.rst
@@ -88,7 +88,14 @@ The parameters can be used as shell variables:
 .. code-block:: sh
 
   eth0.ipaddr=192.168.23.15
-  echo "my current ip is: $eth0.ipaddr"
+  echo "my current ip is: ${eth0.ipaddr}"
+
+.. note::
+
+  Hush shell syntax for defining and setting variables is the same, so
+  some characters such as hyphens are not allowed on the left hand side
+  of a shell variable assignment. :ref:`command_setenv`, if enabled,
+  can still be used to write such a variable though.
 
 device variables may have a type, so assigning wrong values may fail:
 
-- 
2.28.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

[PATCH 2/2] Documentation: state: clarify how to access state device parameters

[Ahmad Fatoum]

Users may be inclined to use hyphens in state variable names as this is
customary for device tree nodes. Such variables can't be read with
$state.example-variable or written with state.example-variable=,
because it's incompatible with Hush. Adjust the documentation to nudge
users into the correct direction (${state.example-variabe} and setenv)

Suggested-by: Matthias Fend <Matthias.Fend@wolfvision.net>
Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
---
 Documentation/user/state.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/user/state.rst b/Documentation/user/state.rst
index 78ce24f9edce..54aa396257f9 100644
--- a/Documentation/user/state.rst
+++ b/Documentation/user/state.rst
@@ -684,9 +684,9 @@ Frontend
 --------
 
 As frontend a *state* instance is a regular barebox device which has
-device parameters for the *state* variables. With this the variables can
+:ref:`device_parameters` for the *state* variables. With this the variables can
 be accessed like normal shell variables. The ``state`` command is used
 to save/restore a *state* variable set to the backend device.
 
-After initializing the variable can be accessed with ``$state.foo``.
-``state -s`` stores the *state* to the backend device.
+After initializing the variable can be accessed with ``${state.foo}`` or
+:ref:`command_setenv`. ``state -s`` stores the *state* to the backend device.
-- 
2.28.0


_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox

Re: [PATCH 1/2] doc: add note about characters like hyphens in variable names

[Sascha Hauer]

On Tue, Nov 10, 2020 at 04:34:29PM +0100, Ahmad Fatoum wrote:
> The mismatch between the allowed characters in shell variables and
> device parameters is a common pitfall, especially because device
> tree node names often have hyphens in them, which is disallowed by
> hush.
> 
> While such variables can be read by the ${variable-example}, setting
> them is only possible with the setenv command. Reflect this in the
> documentation.
> 
> Signed-off-by: Ahmad Fatoum <a.fatoum@pengutronix.de>
> ---
> Cc: Matthias Fend <Matthias.Fend@wolfvision.net>
> ---
>  Documentation/user/driver-model.rst | 9 ++++++++-
>  1 file changed, 8 insertions(+), 1 deletion(-)

Applied, thanks

Sascha

> 
> diff --git a/Documentation/user/driver-model.rst b/Documentation/user/driver-model.rst
> index a0fd3e99b55b..c543d6d9c410 100644
> --- a/Documentation/user/driver-model.rst
> +++ b/Documentation/user/driver-model.rst
> @@ -88,7 +88,14 @@ The parameters can be used as shell variables:
>  .. code-block:: sh
>  
>    eth0.ipaddr=192.168.23.15
> -  echo "my current ip is: $eth0.ipaddr"
> +  echo "my current ip is: ${eth0.ipaddr}"
> +
> +.. note::
> +
> +  Hush shell syntax for defining and setting variables is the same, so
> +  some characters such as hyphens are not allowed on the left hand side
> +  of a shell variable assignment. :ref:`command_setenv`, if enabled,
> +  can still be used to write such a variable though.
>  
>  device variables may have a type, so assigning wrong values may fail:
>  
> -- 
> 2.28.0
> 
> 
> _______________________________________________
> barebox mailing list
> barebox@lists.infradead.org
> http://lists.infradead.org/mailman/listinfo/barebox
> 

-- 
Pengutronix e.K.                           |                             |
Steuerwalder Str. 21                       | http://www.pengutronix.de/  |
31137 Hildesheim, Germany                  | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |

_______________________________________________
barebox mailing list
barebox@lists.infradead.org
http://lists.infradead.org/mailman/listinfo/barebox