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

[Dirk Behme]

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 at 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