Kernel/include/api_drv_joystick.h

   1 /**\r
   2  * \file api_drv_joystick.h\r
   3  * \brief Joystick Driver Interface Definitions\r
   4  * \author John Hodge (thePowersGang)\r
   5  * \r
   6  * \section dirs VFS Layout\r
   7  * Joystick drivers define a single VFS node, that acts as a fixed size file.\r
   8  * Reads from this file return the current state, writes are ignored.\r
   9  *\r
  10  * \section File Structure\r
  11  * The device file must begin with a valid sJoystick_FileHeader structure.\r
  12  * The file header is followed by \a NAxies instances of sJoystick_Axis, one\r
  13  * for each axis.\r
  14  * This is followed by \a NButtons boolean values (represented using \a Uint8),\r
  15  * each representing the state of a single button (where 0 is unpressed,\r
  16  * 0xFF is fully depressed - intermediate values are valid in the case of\r
  17  * variable-pressure buttons)\r
  18  */\r
  19 #ifndef _API_DRV_JOYSTICK_H\r
  20 #define _API_DRV_JOYSTICK_H\r
  21 \r
  22 #include <api_drv_common.h>\r
  23 \r
  24 /**\r
  25  * \enum eTplJoystick_IOCtl\r
  26  * \brief Common Joystick IOCtl Calls\r
  27  * \extends eTplDrv_IOCtl\r
  28  */\r
  29 enum eTplJoystick_IOCtl {\r
  30         /**\r
  31          * ioctl(..., tJoystick_Callback *Callback)\r
  32          * \brief Sets the callback\r
  33          * \note Can be called from kernel mode only\r
  34          *\r
  35          * Sets the callback that is called when a event occurs (button or axis\r
  36          * change). This function pointer must be in kernel mode (although,\r
  37          * kernel->user or kernel->ring3driver abstraction functions can be used)\r
  38          * \r
  39          * Axis events depend on the axis limit, if non-zero, the callback fires\r
  40          * if the cursor position changes. Otherwise it fires when the axis value\r
  41          * (cursor accelleration) changes.\r
  42          */\r
  43         JOY_IOCTL_SETCALLBACK = 4,\r
  44 \r
  45         /**\r
  46          * ioctl(..., int *Argument)\r
  47          * \brief Set the argument passed as the first parameter to the callback\r
  48          * \note Kernel mode only\r
  49          */\r
  50         JOY_IOCTL_SETCALLBACKARG,\r
  51 \r
  52         /**\r
  53          * ioctl(..., tJoystickNumValue *)\r
  54          * \brief Set maximum value for sJoystick_Axis.CursorPos\r
  55          * \note If \a Value is equal to -1 (all bits set), the value is not changed\r
  56          */\r
  57         JOY_IOCTL_GETSETAXISLIMIT,\r
  58 \r
  59         /**\r
  60          * ioctl(..., tJoystickNumValue *)\r
  61          * \brief Set the value of sJoystick_Axis.CursorPos\r
  62          * \note If \a Value is equal to -1 (all bits set), the value is not changed\r
  63          */\r
  64         JOY_IOCTL_GETSETAXISPOSITION,\r
  65         \r
  66         /**\r
  67          * ioctl(..., tJoystickNumValue *)\r
  68          * \brief Set axis flags\r
  69          * \note If \a Value is equal to -1 (all bits set), the value is not changed\r
  70          * \todo Define flag values\r
  71          */\r
  72         JOY_IOCTL_GETSETAXISFLAGS,\r
  73 \r
  74         /**\r
  75          * ioctl(..., tJoystickNumValue *)\r
  76          * \brief Set Button Flags\r
  77          * \note If \a Value is equal to -1 (all bits set), the value is not changed\r
  78          * \todo Define flag values\r
  79          */\r
  80         JOY_IOCTL_GETSETBUTTONFLAGS,\r
  81 };\r
  82 \r
  83 /**\r
  84  * \brief Symbolic names for Joystick IOCtls\r
  85  */\r
  86 #define DRV_JOY_IOCTLNAMES      "set_callback", "set_callback_arg", "getset_axis_limit", "getset_axis_position", \\r
  87         "getset_axis_flags", "getset_button_flags"\r
  88 \r
  89 // === TYPES ===\r
  90 typedef struct sJoystick_NumValue       tJoystick_NumValue;\r
  91 typedef struct sJoystick_FileHeader     tJoystick_FileHeader;\r
  92 typedef struct sJoystick_Axis   tJoystick_Axis;\r
  93 \r
  94 /**\r
  95  * \brief Number/Value pair for joystick IOCtls\r
  96  */\r
  97 struct sJoystick_NumValue\r
  98 {\r
  99          int    Num;    //!< Axis/Button number\r
 100          int    Value;  //!< Value (see IOCtl defs for meaning)\r
 101 };\r
 102 \r
 103 /**\r
 104  * \brief Callback type for JOY_IOCTL_SETCALLBACK\r
 105  * \param Ident Ident value passed to JOY_IOCTL_SETCALLBACK\r
 106  * \r
 107  */\r
 108 typedef void (*tJoystick_Callback)(int Ident, int bIsAxis, int Num, int Delta);\r
 109 \r
 110 /**\r
 111  * \struct sJoystick_FileHeader\r
 112  * \brief Format of the joystick VFS node's first bytes\r
 113  */\r
 114 struct sJoystick_FileHeader\r
 115 {\r
 116         Uint16  NAxies; //!< Number of Axies\r
 117         Uint16  NButtons;       //!< Number of buttons\r
 118 };\r
 119 \r
 120 /**\r
 121  * \brief Axis Definition in file data\r
 122  *\r
 123  * Describes the current state of an axis on the joystick.\r
 124  * \a CursorPos is between zero and the current limit set by the\r
 125  * JOY_IOCTL_GETSETAXISLIMIT IOCtl, while \a CurValue indicates the\r
 126  * current position of the joystick axis. This is defined to be between\r
 127  * \a MinValue and \a MaxValue.\r
 128  */\r
 129 struct sJoystick_Axis\r
 130 {\r
 131         Sint16  MinValue;       //!< Minumum value for \a CurValue\r
 132         Sint16  MaxValue;       //!< Maximum value for \a CurValue\r
 133         Sint16  CurValue;       //!< Current value (joystick position)\r
 134         Uint16  CursorPos;      //!< Current state (cursor position)\r
 135 };\r
 136 \r
 137 /**\r
 138  * \brief Macro to define a structure for a joystick's node\r
 139  * \param _naxies       Number of axies\r
 140  * \param _nbuttons     Number of buttons\r
 141  * \note This just defines the structure, it's up to the driver to set the\r
 142  *       sJoystick_FileHeader.NAxies and sJoystick_FileHeader.NButtons fields.\r
 143  */\r
 144 #define JOY_INFOSTRUCT(_naxies, _nbuttons) struct { \\r
 145         Uint16  NAxies, NButtons;\\r
 146         tJoystick_Axis  Axies[_naxies];\\r
 147         Uint16  Buttons[_nbuttons];\\r
 148         }\r
 149 \r
 150 #endif\r