Implement encoding the usbhost HID keyboard driver; configre olimex-lpc1766stk HID keyboard configuration to use the kconfig-frontends tool

git-svn-id: svn://svn.code.sf.net/p/nuttx/code/trunk@5461 42af7a65-404d-4744-a932-0658087f49c3

ChangeLog

@@ -3821,3 +3821,9 @@
 	* libc/misc/lib_kbdencode.c and lib_kbddecode.c:  Add logic to marshal
 	  and serialized "out-of-band" keyboard commands intermixed with normal
 	  ASCII data (not yet hooked into anything).
+	* drivers/usbhost/usbhost_hidkbd.c:  If CONFIG_HIDKBD_ENCODED is
+	  defined, this driver will now use libc/misc/lib_kbdencode.c to
+	  encode special function keys.
+	* configs/olimex-lpc1766stk/hidkbd:  This configuration has been
+	  converted to use the kconfig-frontends configuration tool.
+

Documentation/NuttxPortingGuide.html

@@ -131,7 +131,8 @@
        <a href="#pwmdrivers">6.3.12 PWM Drivers</a><br>
        <a href="#candrivers">6.3.13 CAN Drivers</a><br>
        <a href="#quadencoder">6.3.14 Quadrature Encoder Drivers</a><br>
-       <a href="#wdogdriver">6.3.15 Watchdog Timer Drivers</a>
+       <a href="#wdogdriver">6.3.15 Watchdog Timer Drivers</a><br>
+       <a href="#kbddriver">6.3.16 Keyboard/Keypad Drivers</a><br>
     </ul>
     <a href="#pwrmgmt">6.4 Power Management</a>
     <ul>
@@ -3620,6 +3621,151 @@ extern void up_ledoff(int led);
   </li>
 </ul>
 
+<h3><a name="kbddriver">6.3.16 Keyboard/Keypad Drivers</a></h3>
+<p>
+  <b>&quot;Out-of-Band&quot; Commands</b>.
+  Keyboards and keypads are the same device for NuttX.
+  A keypad is thought of as simply a keyboard with fewer keys.
+  In NuttX, a keyboard/keypad driver is simply a character driver that may have an (optional) encoding/decoding layer on the data returned by the character driver.
+  A keyboard may return simple text data (alphabetic, numeric, and punctuaction) or control characters (enter,  control-C, etc.).
+  We can think about this the normal &quot;in-band&quot; keyboard data stream.
+  However, in addition, most keyboards support actions that cannot be represented as text data.
+  Such actions include things like cursor controls (home, up arrow, page down, etc.), editing functions (insert, delete, etc.), volume controls, (mute, volume up, etc.) and other special functions.
+  We can think about this as special, &quot;out-of-band&quot; keyboard commands.
+  In this case, some special encoding may be required to multiplex the in-band text data and out-of-band command streams.
+</p>
+<p>
+  <b>Encoding/Decoding</b> Layer</b>.
+  An optional encoding/decoding layer can be used with the basic character driver to encode the out-of-band commands into the text data stream.
+  The function interfaces that comprise that encoding/decoding layer are defined in the header file <code>include/nuttx/input/kbd_code.h</code>.
+  These functions provide an matched set of (a) driver encoding interfaces, and (b) application decoding interfaces.
+</p>
+<ol>
+  <li>
+    <p>
+      <b>Driver Encoding Interfaces</b>.
+    </p>
+    <ul>
+      <li>
+        <p>
+          <b><code>kbd_puttext()</code></b>
+        </p>
+        <p><b>Function Prototype:</b></p>
+          <ul><pre>
+#include &lt;nuttx/streams.h&gt;
+#include &lt;nuttx/input/kbd_codec.h&gt;
+void kbd_puttext(int ch, FAR struct lib_outstream_s *stream);
+</pre></ul>
+        <p><b>Description:</b></p>
+        <ul>
+          Put one byte of normal, &quot;in-band&quot; ASCII data into the output stream.
+        </ul>
+        <p><b>Input Pameters:</b></p>
+        <ul>
+          <li>
+            <code>ch</code>:  The character to be added to the output stream.
+          </li>
+          <li>
+            <code>stream</code>:  An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation.
+          </li>
+        </ul>
+        <p><b>Returned Value:</b></p>
+        <ul>
+          None.
+        </ul>
+      </li>
+      <li>
+        <p>
+          <b><code>kbd_putspecial()</code></b>
+        </p>
+        <p><b>Function Prototype:</b></p>
+          <ul><pre>
+#include &lt;nuttx/streams.h&gt;
+#include &lt;nuttx/input/kbd_codec.h&gt;
+void kbd_putspecial(enum kbd_keycode_e keycode, FAR struct lib_outstream_s *stream);
+</pre></ul>
+        <p><b>Description:</b></p>
+        <ul>
+          Put one special, &quot;out-of-band&quot; command into the output stream.
+        </ul>
+        <p><b>Input Pameters:</b></p>
+        <ul>
+          <li>
+            <code>keycode</code>:  The command to be added to the output stream.
+            The enumeration <code>enum kbd_keycode_e keycode</code> identifies all commands known to the system.
+          </li>
+          <li>
+            <code>stream</code>:  An instance of <code>lib_outstream_s</code> to perform the actual low-level put operation.
+          </li>
+        </ul>
+        <p><b>Returned Value:</b></p>
+        <ul>
+          None.
+        </ul>
+      </li>
+    </ul>
+  </li>
+  <li>
+    <p>
+      <b>Application Decoding Interfaces</b>.
+      </p>
+    <ul>
+      <li>
+        <p>
+          <b><code>kbd_get()</code></b>
+        </p>
+        <p><b>Function Prototype:</b></p>
+          <ul><pre>
+#include &lt;nuttx/streams.h&gt;
+#include &lt;nuttx/input/kbd_codec.h&gt;
+int kbd_get(FAR struct lib_instream_s *stream, FAR struct kbd_getstate_s *state, FAR uint8_t *pch);
+</pre></ul>
+        <p><b>Description:</b></p>
+        <ul>
+           Get one byte of data or special command from the driver provided input buffer.
+        </ul>
+        <p><b>Input Pameters:</b></p>
+        <ul>
+          <li>
+            <code>stream</code>:  An instance of <code>lib_instream_s</code> to perform the actual low-level get operation.
+          </li>
+          <li>
+            <code>pch</code>:  The location character to save the returned value. 
+            This may be either a normal, &quot;in-band&quot; ASCII characer or a special, "out-of-band" command (i.e., a value from <code>enum kbd_getstate_s</code>.
+          </li>
+          <li>
+            <code>state</code>:  A user provided buffer to support parsing. 
+            This structure should be cleared the first time that <code>kbd_get</code> is called.
+          </li>
+        </ul>
+        <p><b>Returned Value:</b></p>
+        <ul>
+          <li>
+            <b>1</b>:
+            Indicates the successful receipt of a special, &quot;out-of-band&quot; command.
+            The returned value in <code>pch</code> is a value from <code>enum kbd_getstate_s</code>.
+          </li>
+          <li>
+            <b>0</b>:
+            Indicates the successful receipt of normal, &quot;in-band&quot; ASCII data.
+            The returned value in <code>pch</code> is a simple byte of text or control data.
+          </li>
+          <li>
+            <b><code>EOF</code></b>:
+              An error has getting the next character (reported by the <code>stream</code>).
+              Normally indicates the end of file.
+          </li>
+        </ul>
+      </li>
+    </ul>
+  </li>
+</ol>
+<p>
+  <b>I/O Streams</b>.
+  Notice the use of the abstract I/O streams in these interfaces.
+  These stream interfaces are defined in <code>include/nuttx/streams.h</code>.
+</p>
+
 <h2><a name="pwrmgmt">6.4 Power Management</a></h2>
 
 <h3><a name="pmoverview">6.4.1 Overview</a></h3>

configs/olimex-lpc1766stk/README.txt

@@ -899,7 +899,25 @@ Where <subdir> is one of the following:
     This configuration directory, performs a simple test of the USB host
     HID keyboard class driver using the test logic in apps/examples/hidkbd.
 
-  nettest:
+    NOTES:
+ 
+    1. This configuration uses the mconf-based configuration tool.  To
+       change this configuration using that tool, you should:
+
+       a. Build and install the mconf tool.  See nuttx/README.txt and
+          misc/tools/
+
+       b. Execute 'make menuconfig' in nuttx/ in order to start the
+          reconfiguration process.
+
+    2. Default platform/toolchain: This is how the build is configured by
+       be default.  These options can easily be re-confured, however.
+
+       CONFIG_HOST_WINDOWS=y         : Windows
+       CONFIG_WINDOWS_CYGWIN=y       : Cygwin environment on Windows
+       CONFIG_STM32_CODESOURCERYW=y  : CodeSourcery under Windows
+
+   nettest:
     This configuration directory may be used to enable networking using the
     LPC17xx's Ethernet controller. It uses apps/examples/nettest to excercise the
     TCP/IP network.

configs/olimex-lpc1766stk/hidkbd/appconfig

@@ -1,39 +0,0 @@
-############################################################################
-# configs/olimex-lpc1766stk/hidkbd/appconfig
-#
-#   Copyright (C) 2011 Gregory Nutt. All rights reserved.
-#   Author: Gregory Nutt <gnutt@nuttx.org>
-#
-# Redistribution and use in source and binary forms, with or without
-# modification, are permitted provided that the following conditions
-# are met:
-#
-# 1. Redistributions of source code must retain the above copyright
-#    notice, this list of conditions and the following disclaimer.
-# 2. Redistributions in binary form must reproduce the above copyright
-#    notice, this list of conditions and the following disclaimer in
-#    the documentation and/or other materials provided with the
-#    distribution.
-# 3. Neither the name NuttX nor the names of its contributors may be
-#    used to endorse or promote products derived from this software
-#    without specific prior written permission.
-#
-# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
-# FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
-# COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
-# INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
-# BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
-# OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
-# AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
-# LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
-# ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
-# POSSIBILITY OF SUCH DAMAGE.
-#
-############################################################################
-
-# Path to example in apps/examples containing the user_start entry point
-
-CONFIGURED_APPS += examples/hidkbd
-

configs/olimex-lpc1766stk/hidkbd/setenv.sh

@@ -50,7 +50,7 @@ fi
 # This is the Cygwin path to the location where I installed the CodeSourcery
 # toolchain under windows.  You will also have to edit this if you install
 # the CodeSourcery toolchain in any other location
-# export TOOLCHAIN_BIN="/cygdrive/c/Program Files (x86)/CodeSourcery/Sourcery G++ Lite/bin"
+export TOOLCHAIN_BIN="/cygdrive/c/Program Files (x86)/CodeSourcery/Sourcery G++ Lite/bin"
 
 # These are the Cygwin paths to the locations where I installed the Atollic
 # toolchain under windows.  You will also have to edit this if you install
@@ -62,7 +62,7 @@ fi
 
 # This is the Cygwin path to the location where I build the buildroot
 # toolchain.
-export TOOLCHAIN_BIN="${WD}/../misc/buildroot/build_arm_nofpu/staging_dir/bin"
+# export TOOLCHAIN_BIN="${WD}/../misc/buildroot/build_arm_nofpu/staging_dir/bin"
 
 # The Olimex-lpc1766stk/tools directory
 export LPCTOOL_DIR="${WD}/configs/olimex-lpc1766stk/tools"

drivers/usbhost/Kconfig

@@ -2,6 +2,7 @@
 # For a description of the syntax of this configuration file,
 # see misc/tools/kconfig-language.txt.
 #
+
 config USBHOST_NPREALLOC
 	int "Number of pre-allocated class instances"
 	default 4
@@ -29,64 +30,85 @@ config USBHOST_ISOC_DISABLE
 		On some architectures, selecting this setting will reduce driver size
 		by disabling isochronous endpoint support
 
-config USBHOST_HIDKBD
+config USBHOST_MSC
-	bool "HID keyboad class support"
+	bool "Mass Storage Class Support"
 	default n
-	depends on !USBHOST_INT_DISABLE  && SCHED_WORKQUEUE && !DISABLE_SIGNALS
+	depends on !BULK_DISABLE
+	---help---
+		Enable support for the keyboard class driver.  This also depends on
+		NFILE_DESCRIPTORS > 0 && SCHED_WORKQUEUE=y
+
+config USBHOST_HIDKBD
+	bool "HID Keyboard Class Support"
+	default n
+	depends on !INT_DISABLE
+	---help---
+		Enable support for the keyboard class driver.  This also depends on
+		SCHED_WORKQUEUE && !DISABLE_SIGNALS
 
 if  USBHOST_HIDKBD
 config HIDKBD_POLLUSEC
-	bool ""
+	int "Keyboard Poll Rate (MSEC)"
-	default n
+	default 100000
 	---help---
-		Device poll rate in microseconds. Default: 100 milliseconds.
+		Device poll rate in microseconds. Default: 100,000 microseconds.
 
 config HIDKBD_DEFPRIO
-	bool ""
+	int "Polling Thread Priority"
-	default n
+	default 50
 	---help---
 		Priority of the polling thread.  Default: 50.
 
 config HIDKBD_STACKSIZE
-	bool ""
+	int "Polling thread stack size"
-	default n
+	default 1024
 	---help---
 		Stack size for polling thread.  Default: 1024
 
 config HIDKBD_BUFSIZE
-	bool ""
+	int "Scancode Buffer Size"
-	default n
+	default 64
 	---help---
 		Scancode buffer size.  Default: 64.
 
 config HIDKBD_NPOLLWAITERS
-	bool ""
+	int "Max Number of Waiters for Poll Event"
-	default n
+	default 2
+	depends on !DISABLE_POLL
 	---help---
 		If the poll() method is enabled, this defines the maximum number
 		of threads that can be waiting for keyboard events.  Default: 2.
 
 config HIDKBD_RAWSCANCODES
-	bool ""
+	bool "Use Raw Scan Codes"
 	default n
 	---help---
-		If set to y no conversion will be made on the raw keyboard scan
+		If set to y no conversions will be made on the raw keyboard scan
-		codes.  Default: ASCII conversion.
+		codes.  This option is useful during testing. Default: ASCII conversion.
+
+config HIDKBD_ENCODED
+	bool "Enocode Special Keys"
+	default n
+	depends on !HIDKBD_RAWSCANCODES
+	---help---
+		Encode special key press events in the user buffer.  In this case,
+		the use end must decode the encoded special key values using the
+		interfaces defined in include/nuttx/input/kbd_codec.h.  These
+		special keys include such things as up/down arrows, home and end
+		keys, etc.  If this not defined, only 7-bit print-able and control
+		ASCII characters will be provided to the user.
 
 config HIDKBD_ALLSCANCODES
-	bool ""
+	bool "Use All Scancodes"
 	default n
 	---help---
 		If set to y all 231 possible scancodes will be converted to
 		something.  Default:  104 key US keyboard.
 
 config HIDKBD_NODEBOUNCE
-	bool ""
+	bool "Disable Debounce"
 	default n
 	---help---
 		If set to y normal debouncing is disabled.  Default: 
 		Debounce enabled (No repeat keys).
-		USB host mass storage class driver. Requires USBHOST=y,
-		config USBHOST_BULK_DISABLE=n, NFILE_DESCRIPTORS > 0,
-		and SCHED_WORKQUEUE=y
 endif

include/nuttx/input/kbd_codec.h

@@ -113,7 +113,7 @@ enum kbd_keycode_e
   KEYCODE_PAUSE,               /* Pause */
   KEYCODE_BREAK,               /* Break */
   KEYCODE_CANCEL,              /* Cancel */
-  KEYCODE_PRINTSCN,            /* PrintScreen */
+  KEYCODE_PRTSCRN,             /* PrintScreen */
   KEYCODE_SYSREQ,              /* SysReq/Attention */
 
   /* Audio */
@@ -131,14 +131,15 @@ enum kbd_keycode_e
 
   KEYCODE_CLEAR,               /* Clear */
   KEYCODE_CLEARENTRY,          /* Clear entry */
+  KEYCODE_NEGATE,              /* +/- */
 
-  KEYCODE_MEMSET,              /* Memory set */
+  KEYCODE_MEMSTORE,            /* Memory store */
   KEYCODE_MEMCLEAR,            /* Memory clear */
   KEYCODE_MEMRECALL,           /* Memory recall */
   KEYCODE_MEMADD,              /* Memory add */
-  KEYCODE_MEMSUBTRACT,         /* Memory substract */
+  KEYCODE_MEMSUB,              /* Memory substract */
-  KEYCODE_MEMMULTIPY,          /* Memory multiply */
+  KEYCODE_MEMMUL,              /* Memory multiply */
-  KEYCODE_MEMDIVIDE,           /* Memory divide */
+  KEYCODE_MEMDIV,              /* Memory divide */
 
   KEYCODE_BINARY,              /* Binary mode */
   KEYCODE_OCTAL,               /* Octal mode */
@@ -197,7 +198,7 @@ enum kbd_keycode_e
  * Public Types
  ****************************************************************************/
 
-struct kget_getstate_s
+struct kbd_getstate_s
 {
   uint8_t nch;                 /* Number of characters in the buffer */
   uint8_t ndx;                 /* Index to next character in the buffer */
@@ -225,7 +226,7 @@ extern "C"
  *   Put one byte of normal, "in-band" ASCII data into the output stream.
  *
  * Input Parameters:
- *   ch - The character to be into the output stream.
+ *   ch - The character to be added to the output stream.
  *   stream - An instance of lib_outstream_s to do the low-level put
  *     operation.
  *
@@ -243,6 +244,9 @@ extern "C"
  *   Put one special, "out-of-band" command into the output stream.
  *
  * Input Parameters:
+ *   keycode - The command to be added to the output stream.
+ *   stream - An instance of lib_outstream_s to do the low-level put
+ *     operation.
  *
  * Returned Value:
  *   None
@@ -261,7 +265,7 @@ void kbd_putspecial(enum kbd_keycode_e keycode,
  * Name: kbd_get
  *
  * Description:
- *   Put one byte of data or special command from the driver provided input
+ *   Get one byte of data or special command from the driver provided input
  *   buffer.
  *
  * Input Parameters:
@@ -274,15 +278,17 @@ void kbd_putspecial(enum kbd_keycode_e keycode,
  *     should be cleared the first time that kbd_get is called.
  *
  * Returned Value:
- *   1  - Indicates the successful receipt of a special, "out-of-band" command
+ *   1  - Indicates the successful receipt of a special, "out-of-band" command.
+ *        The returned value in pch is a value from enum kbd_getstate_s.
  *   0  - Indicates the successful receipt of normal, "in-band" ASCII data.
+ *        The returned value in pch is a simple byte of text or control data.
  *  EOF - An error has getting the next character (reported by the stream).
  *        Normally indicates the end of file.
  *
  ****************************************************************************/
 
 int kbd_get(FAR struct lib_instream_s *stream,
-            FAR struct kget_getstate_s *state, FAR uint8_t *pch);
+            FAR struct kbd_getstate_s *state, FAR uint8_t *pch);
 
 #ifdef __cplusplus
 }

libc/misc/lib_kbddecode.c

@@ -89,7 +89,7 @@
  *
  ****************************************************************************/
 
-static int kbd_reget(FAR struct kget_getstate_s *state, FAR uint8_t *pch)
+static int kbd_reget(FAR struct kbd_getstate_s *state, FAR uint8_t *pch)
 {
   /* Return the next character */
 
@@ -107,7 +107,7 @@ static int kbd_reget(FAR struct kget_getstate_s *state, FAR uint8_t *pch)
  * Name: kbd_get
  *
  * Description:
- *   Put one byte of data or special command from the driver provided input
+ *   Get one byte of data or special command from the driver provided input
  *   buffer.
  *
  * Input Parameters:
@@ -120,15 +120,17 @@ static int kbd_reget(FAR struct kget_getstate_s *state, FAR uint8_t *pch)
  *     should be cleared the first time that kbd_get is called.
  *
  * Returned Value:
- *   1  - Indicates the successful receipt of a special, "out-of-band" command
+ *   1  - Indicates the successful receipt of a special, "out-of-band" command.
+ *        The returned value in pch is a value from enum kbd_getstate_s.
  *   0  - Indicates the successful receipt of normal, "in-band" ASCII data.
+ *        The returned value in pch is a simple byte of text or control data.
  *  EOF - An error has getting the next character (reported by the stream).
  *        Normally indicates the end of file.
  *
  ****************************************************************************/
 
 int kbd_get(FAR struct lib_instream_s *stream,
-            FAR struct kget_getstate_s *state, FAR uint8_t *pch)
+            FAR struct kbd_getstate_s *state, FAR uint8_t *pch)
 {
   int ch;
 

libc/misc/lib_kbdencode.c

@@ -62,6 +62,9 @@
  *   Put one special, "out-of-band" command into the output stream.
  *
  * Input Parameters:
+ *   keycode - The command to be added to the output stream.
+ *   stream - An instance of lib_outstream_s to do the low-level put
+ *     operation.
  *
  * Returned Value:
  *   None