From 36ac0d2cf46cf2cf35214e8a6ea654dbf9f4c974 Mon Sep 17 00:00:00 2001 From: Gregory Nutt Date: Fri, 28 Nov 2014 19:27:42 -0600 Subject: [PATCH] Add an interface definition header file for an analog joystick device --- ChangeLog | 4 + include/nuttx/fs/ioctl.h | 9 +- include/nuttx/input/ajoystick.h | 273 ++++++++++++++++++++++++++++++++ include/nuttx/input/djoystick.h | 4 +- 4 files changed, 287 insertions(+), 3 deletions(-) create mode 100644 include/nuttx/input/ajoystick.h diff --git a/ChangeLog b/ChangeLog index 2b9864da00..f4e2918fe2 100755 --- a/ChangeLog +++ b/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/include/nuttx/fs/ioctl.h b/include/nuttx/fs/ioctl.h index 3a2111ebd9..491aed3c5f 100644 --- a/include/nuttx/fs/ioctl.h +++ b/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/include/nuttx/input/ajoystick.h b/include/nuttx/input/ajoystick.h new file mode 100644 index 0000000000..35ebd7210e --- /dev/null +++ b/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 + * + * 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 +#include + +/**************************************************************************** + * 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/include/nuttx/input/djoystick.h b/include/nuttx/input/djoystick.h index 14ef508ceb..f8e52f023f 100644 --- a/include/nuttx/input/djoystick.h +++ b/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.