[U-Boot] [PATCH] Add doc/README.kbd

Dirk Behme
2012-05-16T05:50:38Z

On 16.05.2012 00:58, Eric Nelson wrote:
> On 05/15/2012 05:47 AM, Dirk Behme wrote:
>> On 16.04.2012 18:18, Eric Nelson wrote:
>>> On 04/16/2012 08:48 AM, Eric Nelson wrote:
>>>> Signed-off-by: Eric Nelson<eric.nelson@boundarydevices.com>
>>>>
>>>> ---
>>>> doc/README.kbd | 84 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
>>>> 1 files changed, 84 insertions(+), 0 deletions(-)
>>>> create mode 100644 doc/README.kbd
>>>>
>>>> diff --git a/doc/README.kbd b/doc/README.kbd
>>>> new file mode 100644
>>>> index 0000000..dff4b92
>>>> --- /dev/null
>>>> +++ b/doc/README.kbd
>>>> @@ -0,0 +1,84 @@
>>>> +Keyboard handling
>>>> +========================================
>>>> +This document describes asynchronous keyboard handling, also
>>>> +known as "magic key" or "button" handling used to alter the
>>>> +boot flow at power-on when one or more keys or buttons are
>>>> +pressed.
>>>> +
>>>> <snip>
>>> Just before I finished this, I noticed that there is a document in
>>> board/lwmon/README.kbd which appears to detail the same information.
>>> (I don't read German, so I'm going based on Google and Babelfish
>>> translations).
>>>
>>> Should that be moved into doc/ where it would be easier to find?
>> What's the status of this? Let me know if you need some help with German ;)
>>
>
> Hi Dirk,
>
> I haven't received any feedback or even acknowledgement about this patch.
>
> Can you read through the file board/lwmon/README.kbd and find out if I'm just
> being redundant?

Trying a (very bad ;) ) translation of board/lwmon/README.kbd [1]:

-- cut --
Keyboard scan:

The implementation/decoding is done based on the document "PIC
LWE-Tastatur", version from 9.3.2001, especially table 3 in chapter 4.3
key codes. In U-Boot, the data read from the keyboard controller are
passed in the auto generated environment variable "keybd" using a
hexadecimal format. Is there no key press, keybd is

keybd=000000000000000000

The decoded key code ("keybd") can be passed to the Linux kernel in
"bootargs". The Linux system can use this in a device driver or an
application.

Special boot functionality:

It's possible to define one or more (as many as needed) keys or key
combinations. If pressed at boot time (reset), these will raise special
functionality.

If the configured key or key combination is detected, U-Boot will
execute the content of the environment variable associated with the key
or key combination. This will be done before the start of the "count
down", i.e. before any other command is executed.

The environment variable "magic_keys" is used as a list of characters,
which will be appended to the name "magic_keys". With this, they define
the name of the environment variable which define the key (-combinations):

Is "magic_keys" EMPTY, only the key (-combination) given in "magic_keys"
will be checked. If this matches, the contend of "key_cmd" will be
executed (to be even more precise: The content of "key_cmd" will be
assigned to the variable "preboot", which is executed just before the
interactive command execution starts).

If "magic_keys" contains e.g. the string "0123CB*", the following
actions are taken:

check key code execute command
in variable in variable
-----------------------------------
key_magic0 ==> key_cmd0
key_magic1 ==> key_cmd1
key_magic2 ==> key_cmd2
key_magic3 ==> key_cmd3
key_magicC ==> key_cmdC
key_magicB ==> key_cmdB
key_magicA ==> key_cmdA
key_magic* ==> key_cmd*

Hint: As soon as an interactive key code is detected, the execution is
stopped; at least one of the defined commands will be executed. The
priority is given by the search order, i.e. the order of the chars in
the variable "magic_keys".

The encoding of the keys to be pressed at boot to start a functionality
are encoded by the keyboard table.

The definition

=> setenv key_magic0 3a+3b
=> setenv key_cmd0 setenv bootdelay 30

does mean: The keys with the code 0x3A (key "F1") and 0x3B (key "F2")
have to be pressed at the same time. You can enter any key combination
as you like (2 chars for the hex code of the keys and '+' as the glue).

Is the configured key combination detected, U-Boot will execute the
given command before any other command and before the start of the
"count down". This will result in a long boot delay.

This does mean that you can set "bootdelay" in U-Boot to 0 and boot
automatically with out any user interaction, except you press the two
keys "F1" and "F2". This would result in a boot delay of 30s.

Hint: The char '#' has a special meaning in "magic_keys": The key
sequence defined by this switches the monitor into the "debug mode".
This does mean that all U-Boot messages are output to the LCD screen;
additionally, the command associated with this key combination can e.g.
switch the boot messages of the Linux kernel to the LCD screen, too.
This allows an analysis of the boot process without any additional debug
tools.

Example:

Set the following environment variables and save them in U-Boot:

(1) => setenv magic_keys 01234#X
(2) => setenv key_cmd# setenv addfb setenv bootargs \\${bootargs}
console=tty0 console=ttyS1,\\${baudrate}
(3) => setenv nfsargs setenv bootargs root=/dev/nfs rw
nfsroot=\${serverip}:\${rootpath}
(4) => setenv addip setenv bootargs \${bootargs}
ip=\${ipaddr}:\${serverip}:\${gatewayip}:\${netmask}:\${hostname}::off
panic=1
(5) => setenv addfb setenv bootargs \${bootargs} console=ttyS1,\${baudrate}
(6) => setenv bootcmd bootp\;run nfsargs\;run addip\;run addfb\;bootm

With this, the Linux command line (in the variable "bootargs") in the
boot command "bootcmd" (6) is concatenated step by step: first, the NFS
root file system options are set ("run nfsargs", compare (3)), then the
network configuration is added ("run addip", compare (4)), and the last
step is the definition of the system console ("run addfb").

By default, the definition (5) is used for this. But if you press the
special key combination at reset, this definition will be overwritten by
the execution of the command defined in (2). This will result in the
output of the boot messages using the frame buffer device (LCD).

Note the doubled '\'-escapes in the definition of "key_cmd#" - this is
necessary because of the interpretation of that string _two_ times: The
first time while entering "key_cmd#", the second time when the string
(the content of "preboot") is executed.
-- cut --

Best regards

Dirk

[1]
http://git.denx.de/cgi-bin/gitweb.cgi?p=u-boot.git;a=blob;f=board/lwmon/README.keybd;h=5e5144e56974aed3a7f442da8a897e2da691e48d;hb=refs/heads/master