Add an interface definition header file for an analog joystick device

4 files changed, 287 insertions, 3 deletions

diff --git a/nuttx/ChangeLog b/nuttx/ChangeLog
index 2b9864da0..f4e2918fe 100755
--- a/nuttx/ChangeLog
+++ b/nuttx/ChangeLog
@@ -9110,3 +9110,7 @@
 	  for the STM3210E-EVAL (2014-11-28).
 	* drivers/input/djoystick.c include/nuttx/input/djoystick.h: Add a new
 	  ioctl to get the supported joystick discrete signals (2014-11-28).
+	* drivers/input/ajoystick.c and include/nuttx/input/ajoystick.h.  Also
+	  drivers/input/Kconfig and Make.defs, and include/nuttx/fs/ioctl.h: Add
+	  an interface definition and upper half driver for an analog joystick
+	  device (2014-11-27).
diff --git a/nuttx/include/nuttx/fs/ioctl.h b/nuttx/include/nuttx/fs/ioctl.h
index 3a2111ebd..491aed3c5 100644
--- a/nuttx/include/nuttx/fs/ioctl.h
+++ b/nuttx/include/nuttx/fs/ioctl.h
@@ -72,6 +72,7 @@
 #define _CFGDIOCBASE    (0x1300) /* Config Data device (app config) ioctl commands */
 #define _TCIOCBASE      (0x1400) /* Timer ioctl commands */
 #define _DJOYBASE       (0x1500) /* Discrete joystick ioctl commands */
+#define _AJOYBASE       (0x1600) /* Analog joystick ioctl commands */
 
 /* Macros used to manage ioctl commands */
 
@@ -295,12 +296,18 @@
 #define _TCIOCVALID(c)     (_IOC_TYPE(c)==_TCIOCBASE)
 #define _TCIOC(nr)         _IOC(_TCIOCBASE,nr)
 
-/* Application Config Data driver ioctl definitions *************************/
+/* Discrete joystick driver ioctl definitions *******************************/
 /* (see nuttx/include/input/djoystick.h */
 
 #define _DJOYIOCVALID(c)   (_IOC_TYPE(c)==_DJOYBASE)
 #define _DJOYIOC(nr)       _IOC(_DJOYBASE,nr)
 
+/* Analog joystick driver ioctl definitions *********************************/
+/* (see nuttx/include/input/ajoystick.h */
+
+#define _AJOYIOCVALID(c)   (_IOC_TYPE(c)==_AJOYBASE)
+#define _AJOYIOC(nr)       _IOC(_AJOYBASE,nr)
+
 /****************************************************************************
  * Public Type Definitions
  ****************************************************************************/
diff --git a/nuttx/include/nuttx/input/ajoystick.h b/nuttx/include/nuttx/input/ajoystick.h
new file mode 100644
index 000000000..35ebd7210
--- /dev/null
+++ b/nuttx/include/nuttx/input/ajoystick.h
@@ -0,0 +1,273 @@
+/****************************************************************************
+ * include/nuttx/input/ajoystick.h
+ *
+ *   Copyright (C) 2014 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.
+ *
+ ****************************************************************************/
+
+/* This header file provides definition for a standard analog joystick
+ * interface.  An analog joystick refers to a joystick that provides X/Y
+ * positional data as integer values such as might be provides by DACs.
+ * The analog positional data may be accompanied by discrete button data.
+ *
+ * The analog joystick driver exports a standard character driver
+ * interface. By convention, the analog joystick is registered as an input
+ * device at /dev/ajoyN where N uniquely identifies the driver instance.
+ *
+ * This header file documents the generic interface that all NuttX analog
+ * joystick devices must conform.  It adds standards and conventions on top
+ * of the standard character driver interface.
+ */
+
+#ifndef __INCLUDE_NUTTX_INPUT_AJOYSTICK_H
+#define __INCLUDE_NUTTX_INPUT_AJOYSTICK_H
+
+/****************************************************************************
+ * Included Files
+ ****************************************************************************/
+
+#include <nuttx/config.h>
+#include <nuttx/fs/ioctl.h>
+
+/****************************************************************************
+ * Pre-Processor Definitions
+ ****************************************************************************/
+/* Configuration ************************************************************/
+
+#ifndef CONFIG_AJOYSTICK_NPOLLWAITERS
+#  define CONFIG_AJOYSTICK_NPOLLWAITERS 2
+#endif
+
+/* Joystick Interface *******************************************************/
+/* These definitions provide the meaning of all of the bits that may be
+ * reported in the ajoy_buttonset_t bitset.
+ */
+
+#define AJOY_BUTTON(n)       ((n)-1)              /* Bit n-1: Button n, n=1..8 */
+#define AJOY_BUTTON_1        (0)                  /* Bit 0: Button 1 */
+#define AJOY_BUTTON_2        (1)                  /* Bit 1: Button 2 */
+#define AJOY_BUTTON_3        (2)                  /* Bit 2: Button 3 */
+#define AJOY_BUTTON_4        (3)                  /* Bit 3: Button 4 */
+#define AJOY_BUTTON_5        (4)                  /* Bit 4: Button 5 */
+#define AJOY_BUTTON_6        (5)                  /* Bit 5: Button 6 */
+#define AJOY_BUTTON_7        (6)                  /* Bit 6: Button 7 */
+#define AJOY_BUTTON_8        (7)                  /* Bit 7: Button 8 */
+#define AJOY_NBUTTONS        (8)                  /* Total number of buttons */
+
+#define AJOY_BUTTON_1_BIT    (1 << AJOY_BUTTON_1) /* 1:Button 1 pressed */
+#define AJOY_BUTTON_2_BIT    (1 << AJOY_BUTTON_2) /* 1:Button 2 pressed */
+#define AJOY_BUTTON_3_BIT    (1 << AJOY_BUTTON_3) /* 1:Button 3 pressed */
+#define AJOY_BUTTON_4_BIT    (1 << AJOY_BUTTON_4) /* 1:Button 4 pressed */
+#define AJOY_BUTTON_5_BIT    (1 << AJOY_BUTTON_5) /* 1:Button 5 pressed */
+#define AJOY_BUTTON_6_BIT    (1 << AJOY_BUTTON_6) /* 1:Button 6 pressed */
+#define AJOY_BUTTON_7_BIT    (1 << AJOY_BUTTON_7) /* 1:Button 7 pressed */
+#define AJOY_BUTTON_8_BIT    (1 << AJOY_BUTTON_8) /* 1:Button 8 pressed */
+#define AJOY_BUTTONS_ALL     0xff                 /* Set of all buttons */
+
+/* Typical usage */
+
+#define AJOY_BUTTON_SELECT     AJOY_BUTTON_1
+#define AJOY_BUTTON_FIRE       AJOY_BUTTON_2
+#define AJOY_BUTTON_JUMP       AJOY_BUTTON_3
+
+#define AJOY_BUTTON_SELECT_BIT AJOY_BUTTON_1_BIT
+#define AJOY_BUTTON_FIRE_BIT   AJOY_BUTTON_2_BIT
+#define AJOY_BUTTON_JUMP_BIT   AJOY_BUTTON_3_BIT
+
+/* IOCTL commands
+ *
+ * Discrete joystick drivers do not support the character driver write() or
+ * seek() methods.  The remaining driver methods behave as follows:
+ *
+ * 1) The read() method will always return a single value of size
+ *    struct ajoy_sample_s represent the current joystick positiona and the
+ *    state of all joystick buttons. read() never blocks.
+ * 2) The poll() method can be used to notify a client if there is a change
+ *    in any of the joystick button inputs.  This feature, of course,
+ *    depends upon interrupt GPIO support from the platform.  NOTE: that
+ *    semantics of poll() for POLLIN are atypical:  The successful poll
+ *    means that the button data has changed and has nothing to with the
+ *    availability of data to be read; data is always available to be
+ *    read.
+ * 3) The ioctl() method supports the commands documented below:
+ */
+
+/* Command:     AJOYIOC_SUPPORTED
+ * Description: Report the set of button events supported by the hardware;
+ * Argument:    A pointer to writeable integer value in which to return the
+ *              set of supported buttons.
+ * Return:      Zero (OK) on success.  Minus one will be returned on failure
+ *              with the errno value set appropriately.
+ */
+
+#define AJOYIOC_SUPPORTED  _AJOYIOC(0x0001)
+
+/* Command:     AJOYIOC_POLLEVENTS
+ * Description: Specify the set of button events that can cause a poll()
+ *              to awaken.  The default is all button depressions and all
+ *              button releases (all supported buttons);
+ * Argument:    A read-only pointer to an instance of struct ajoy_pollevents_s
+ * Return:      Zero (OK) on success.  Minus one will be returned on failure
+ *              with the errno value set appropriately.
+ */
+
+#define AJOYIOC_POLLEVENTS  _AJOYIOC(0x0002)
+
+/* Command:     AJOYIOC_REGISTER
+ * Description: Register to receive a signal whenever there is a change in
+ *              any of the joystick analog inputs.  This feature, of
+ *              course, depends upon interrupt GPIO support from the
+ *              platform.
+ * Argument:    A read-only pointer to an instance of struct ajoy_notify_s
+ * Return:      Zero (OK) on success.  Minus one will be returned on failure
+ *              with the errno value set appropriately.
+ */
+
+#define AJOYIOC_REGISTER   _AJOYIOC(0x0003)
+
+/****************************************************************************
+ * Public Types
+ ****************************************************************************/
+/* This type is a bit set that contains the state of all analog joystick
+ * buttons.
+ */
+
+typedef uint8_t ajoy_buttonset_t;
+
+/* A reference to this structure is provided with the AJOYIOC_POLLEVENTS IOCTL
+ * command and describes the conditions under which the client would like
+ * to receive notification.
+ */
+
+struct ajoy_pollevents_s
+{
+  ajoy_buttonset_t ap_press;   /* Set of button depressions to wake up the poll */
+  ajoy_buttonset_t ap_release; /* Set of button releases to wake up the poll */
+};
+
+/* A reference to this structure is provided with the AJOYIOC_REGISTER IOCTL
+ * command and describes the conditions under which the client would like
+ * to receive notification.
+ */
+
+struct ajoy_notify_s
+{
+  ajoy_buttonset_t an_press;   /* Set of button depressions to be notified */
+  ajoy_buttonset_t an_release; /* Set of button releases to be notified */
+  uint8_t          an_signo;   /* Signal number to use in the notification */
+};
+
+/* This is the type of the analog joystick interrupt handler used with
+ * the struct ajoy_lowerhalf_s enable() method.
+ */
+
+struct ajoy_lowerhalf_s;
+typedef CODE void (*ajoy_handler_t)
+  (FAR const struct ajoy_lowerhalf_s *lower, FAR void *arg);
+
+/* The analog joystick driver is a two-part driver:
+ *
+ * 1) A common upper half driver that provides the common user interface to
+ *    the joystick,
+ * 2) Platform-specific lower half drivers that provide the interface
+ *    between the common upper half and the platform analog inputs.
+ *
+ * This structure defines the interface between an instance of the lower
+ * half driver and the common upper half driver.  Such an instance is
+ * passed to the upper half driver when the driver is initialized, binding
+ * the upper and lower halves into one driver.
+ */
+
+struct ajoy_lowerhalf_s
+{
+  /* Return the set of buttons supported on the analog joystick device */
+
+  CODE ajoy_buttonset_t (*dl_supported)(FAR const struct ajoy_lowerhalf_s *lower);
+
+  /* Return the current state of all analog joystick buttons */
+
+  CODE ajoy_buttonset_t (*dl_sample)(FAR const struct ajoy_lowerhalf_s *lower);
+
+  /* Enable interrupts on the selecte set of joystick buttons.  And empty
+   * set will disable all interrupts.
+   */
+
+  CODE void (*dl_enable)(FAR const struct ajoy_lowerhalf_s *lower,
+                         ajoy_buttonset_t press, ajoy_buttonset_t release,
+                         ajoy_handler_t handler, FAR void *arg);
+};
+
+/****************************************************************************
+ * Public Data
+ ****************************************************************************/
+
+#ifdef __cplusplus
+#define EXTERN extern "C"
+extern "C"
+{
+#else
+#define EXTERN extern
+#endif
+
+/****************************************************************************
+ * Public Function Prototypes
+ ****************************************************************************/
+
+/****************************************************************************
+ * Name: ajoy_register
+ *
+ * Description:
+ *   Bind the lower half analog joystick driver to an instance of the
+ *   upper half analog joystick driver and register the composite character
+ *   driver as the specific device.
+ *
+ * Input Parameters:
+ *   devname - The name of the analog joystick device to be registers.
+ *     This should be a string of the form "/dev/ajoyN" where N is the the
+ *     minor device number.
+ *   lower - An instance of the platform-specific analog joystick lower
+ *     half driver.
+ *
+ * Returned Values:
+ *   Zero (OK) is returned on success.  Otherwise a negated errno value is
+ *   returned to indicate the nature of the failure.
+ *
+ ****************************************************************************/
+
+int ajoy_register(FAR const char *devname,
+                  FAR const struct ajoy_lowerhalf_s *lower);
+
+#undef EXTERN
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* __INCLUDE_NUTTX_INPUT_AJOYSTICK_H */
diff --git a/nuttx/include/nuttx/input/djoystick.h b/nuttx/include/nuttx/input/djoystick.h
index 14ef508ce..f8e52f023 100644
--- a/nuttx/include/nuttx/input/djoystick.h
+++ b/nuttx/include/nuttx/input/djoystick.h
@@ -220,7 +220,7 @@ struct djoy_lowerhalf_s
 
   CODE djoy_buttonset_t (*dl_sample)(FAR const struct djoy_lowerhalf_s *lower);
 
-  /* Enable interrupts on the selecte set of joystick buttons.  And empty
+  /* Enable interrupts on the selected set of joystick buttons.  And empty
    * set will disable all interrupts.
    */
 
@@ -251,7 +251,7 @@ extern "C"
  * Description:
  *   Bind the lower half discrete joystick driver to an instance of the
  *   upper half discrete joystick driver and register the composite character
- *   driver as the specific device.
+ *   driver as the specified device.
  *
  * Input Parameters:
  *   devname - The name of the discrete joystick device to be registers.