* [U-Boot] [PATCH] Add doc/README.kbd [not found] <http://lists.denx.de/pipermail/u-boot/2012-March/119248.html> @ 2012-04-16 15:48 ` Eric Nelson 2012-04-16 16:18 ` Eric Nelson 2012-08-09 20:34 ` Wolfgang Denk 0 siblings, 2 replies; 6+ messages in thread From: Eric Nelson @ 2012-04-16 15:48 UTC (permalink / raw) To: u-boot 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. + +Note that "keyboard" has multiple meanings, and this document +does not describe the use of keyboards as a tty or console +input device. + +Think of the button on your WiFi access point that resets to +factory defaults and not the keyboard on your desk. + +This use case is similar in function to the mechanism used +by a PC BIOS to enter a setup application at boot time or +on an Android device to access "recovery" mode. + +At the highest level, the function of this subsystem is to +run a set of commands other than the content of the "bootcmd" +environment variable when one or more keys is pressed at +startup. The alternate commands are also stored in environment +variables as illustrated in this snippet from the file +include/configs/lwmon.h: + +"key_cmd2=echo *** Entering Update Mode ***;" \ + "if fatload ide 0:3 10000 update.scr;" \ + "then source 10000;" \ + "else echo *** UPDATE FAILED ***;" \ + "fi\0" \ + +As of this writing, there are eight boards which implement +this mechanism: + enbw/enbw_cmc/enbw_cmc.c + lwmon/lwmon.c + lwmon5/kbd.c + manroland/hmi1001/hmi1001.c + manroland/uc101/uc101.c + manroland/mucmc52/mucmc52.c + pcs440ep/pcs440ep.c + r360mpi/r360mpi.c + +They all share some things in common: + +1. They each check for keys pressed in misc_init_r() and + use the content of the environment variable "magic_keys" + to locate command strings matching key combinations. +2. If a keystroke is matched, it is placed into the "preboot" + environment variable. +3. The "magic_keys" environment variable is used as an + index or pointer of sorts to other environment variables + which contain key combinations. +4. Each character in the value of "magic_keys" is used as a + suffix for a key-combination environment variable name. + The name "key_magic" is used in all implementations except + enbw_cmc. + For example, if "magic_keys" contains the value "1234", + the code will check against these environment variables. + key_magic1 + key_magic2 + key_magic3 + key_magic4 +5. If the currently pressed key combination matches the + content of the key_magicX variable, the content of + another variable, "key_cmdX" is copied to "preboot". + +The implementations otherwise vary. + +Some implementations, notably the lwmon and r360mpi boards, +include a command "kbd", which is used to read the current +key state into an environment variable "keybd". + +To recap: to implement this for your platform, you should do the +following. + +Add a section conditional on CONFIG_PREBOOT to implement the +key handling: + + #ifdef CONFIG_PREBOOT + #endif + +If CONFIG_PREBOOT is set, add a call to check and conditionally +define the "preboot" variable based on the current key state. + -- 1.7.9 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* [U-Boot] [PATCH] Add doc/README.kbd 2012-04-16 15:48 ` [U-Boot] [PATCH] Add doc/README.kbd Eric Nelson @ 2012-04-16 16:18 ` Eric Nelson 2012-05-15 12:47 ` Dirk Behme 2012-08-09 20:34 ` Wolfgang Denk 1 sibling, 1 reply; 6+ messages in thread From: Eric Nelson @ 2012-04-16 16:18 UTC (permalink / raw) To: u-boot 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? ^ permalink raw reply [flat|nested] 6+ messages in thread
* [U-Boot] [PATCH] Add doc/README.kbd 2012-04-16 16:18 ` Eric Nelson @ 2012-05-15 12:47 ` Dirk Behme 2012-05-15 22:58 ` Eric Nelson 0 siblings, 1 reply; 6+ messages in thread From: Dirk Behme @ 2012-05-15 12:47 UTC (permalink / raw) To: u-boot 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 ;) Best regards Dirk ^ permalink raw reply [flat|nested] 6+ messages in thread
* [U-Boot] [PATCH] Add doc/README.kbd 2012-05-15 12:47 ` Dirk Behme @ 2012-05-15 22:58 ` Eric Nelson 2012-05-16 5:50 ` Dirk Behme 0 siblings, 1 reply; 6+ messages in thread From: Eric Nelson @ 2012-05-15 22:58 UTC (permalink / raw) To: u-boot 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? If so, perhaps this isn't needed at all. Thanks, Eric ^ permalink raw reply [flat|nested] 6+ messages in thread
* [U-Boot] [PATCH] Add doc/README.kbd 2012-05-15 22:58 ` Eric Nelson @ 2012-05-16 5:50 ` Dirk Behme 0 siblings, 0 replies; 6+ messages in thread From: Dirk Behme @ 2012-05-16 5:50 UTC (permalink / raw) To: u-boot 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 ^ permalink raw reply [flat|nested] 6+ messages in thread
* [U-Boot] [PATCH] Add doc/README.kbd 2012-04-16 15:48 ` [U-Boot] [PATCH] Add doc/README.kbd Eric Nelson 2012-04-16 16:18 ` Eric Nelson @ 2012-08-09 20:34 ` Wolfgang Denk 1 sibling, 0 replies; 6+ messages in thread From: Wolfgang Denk @ 2012-08-09 20:34 UTC (permalink / raw) To: u-boot Dear Eric Nelson, In message <1334591288-22859-1-git-send-email-eric.nelson@boundarydevices.com> you 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 Do you plan to post an updated version of this patch, based on Dirk's comments, or should this version be applied, or dropped, or ... ? Best regards, Wolfgang Denk -- DENX Software Engineering GmbH, MD: Wolfgang Denk & Detlev Zundel HRB 165235 Munich, Office: Kirchenstr.5, D-82194 Groebenzell, Germany Phone: (+49)-8142-66989-10 Fax: (+49)-8142-66989-80 Email: wd at denx.de SW engineering is a race between programmers trying to make better idiot-proof programs and the universe producing greater idiots. ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2012-08-09 20:34 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
[not found] <http://lists.denx.de/pipermail/u-boot/2012-March/119248.html>
2012-04-16 15:48 ` [U-Boot] [PATCH] Add doc/README.kbd Eric Nelson
2012-04-16 16:18 ` Eric Nelson
2012-05-15 12:47 ` Dirk Behme
2012-05-15 22:58 ` Eric Nelson
2012-05-16 5:50 ` Dirk Behme
2012-08-09 20:34 ` Wolfgang Denk
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox