0001 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0002 Programming gameport drivers
0003 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0004
0005 A basic classic gameport
0006 ~~~~~~~~~~~~~~~~~~~~~~~~
0007
0008 If the gameport doesn't provide more than the inb()/outb() functionality,
0009 the code needed to register it with the joystick drivers is simple::
0010
0011 struct gameport gameport;
0012
0013 gameport.io = MY_IO_ADDRESS;
0014 gameport_register_port(&gameport);
0015
0016 Make sure struct gameport is initialized to 0 in all other fields. The
0017 gameport generic code will take care of the rest.
0018
0019 If your hardware supports more than one io address, and your driver can
0020 choose which one to program the hardware to, starting from the more exotic
0021 addresses is preferred, because the likelihood of clashing with the standard
0022 0x201 address is smaller.
0023
0024 E.g. if your driver supports addresses 0x200, 0x208, 0x210 and 0x218, then
0025 0x218 would be the address of first choice.
0026
0027 If your hardware supports a gameport address that is not mapped to ISA io
0028 space (is above 0x1000), use that one, and don't map the ISA mirror.
0029
0030 Also, always request_region() on the whole io space occupied by the
0031 gameport. Although only one ioport is really used, the gameport usually
0032 occupies from one to sixteen addresses in the io space.
0033
0034 Please also consider enabling the gameport on the card in the ->open()
0035 callback if the io is mapped to ISA space - this way it'll occupy the io
0036 space only when something really is using it. Disable it again in the
0037 ->close() callback. You also can select the io address in the ->open()
0038 callback, so that it doesn't fail if some of the possible addresses are
0039 already occupied by other gameports.
0040
0041 Memory mapped gameport
0042 ~~~~~~~~~~~~~~~~~~~~~~
0043
0044 When a gameport can be accessed through MMIO, this way is preferred, because
0045 it is faster, allowing more reads per second. Registering such a gameport
0046 isn't as easy as a basic IO one, but not so much complex::
0047
0048 struct gameport gameport;
0049
0050 void my_trigger(struct gameport *gameport)
0051 {
0052 my_mmio = 0xff;
0053 }
0054
0055 unsigned char my_read(struct gameport *gameport)
0056 {
0057 return my_mmio;
0058 }
0059
0060 gameport.read = my_read;
0061 gameport.trigger = my_trigger;
0062 gameport_register_port(&gameport);
0063
0064 .. _gameport_pgm_cooked_mode:
0065
0066 Cooked mode gameport
0067 ~~~~~~~~~~~~~~~~~~~~
0068
0069 There are gameports that can report the axis values as numbers, that means
0070 the driver doesn't have to measure them the old way - an ADC is built into
0071 the gameport. To register a cooked gameport::
0072
0073 struct gameport gameport;
0074
0075 int my_cooked_read(struct gameport *gameport, int *axes, int *buttons)
0076 {
0077 int i;
0078
0079 for (i = 0; i < 4; i++)
0080 axes[i] = my_mmio[i];
0081 buttons[0] = my_mmio[4];
0082 }
0083
0084 int my_open(struct gameport *gameport, int mode)
0085 {
0086 return -(mode != GAMEPORT_MODE_COOKED);
0087 }
0088
0089 gameport.cooked_read = my_cooked_read;
0090 gameport.open = my_open;
0091 gameport.fuzz = 8;
0092 gameport_register_port(&gameport);
0093
0094 The only confusing thing here is the fuzz value. Best determined by
0095 experimentation, it is the amount of noise in the ADC data. Perfect
0096 gameports can set this to zero, most common have fuzz between 8 and 32.
0097 See analog.c and input.c for handling of fuzz - the fuzz value determines
0098 the size of a gaussian filter window that is used to eliminate the noise
0099 in the data.
0100
0101 More complex gameports
0102 ~~~~~~~~~~~~~~~~~~~~~~
0103
0104 Gameports can support both raw and cooked modes. In that case combine either
0105 examples 1+2 or 1+3. Gameports can support internal calibration - see below,
0106 and also lightning.c and analog.c on how that works. If your driver supports
0107 more than one gameport instance simultaneously, use the ->private member of
0108 the gameport struct to point to your data.
0109
0110 Unregistering a gameport
0111 ~~~~~~~~~~~~~~~~~~~~~~~~
0112
0113 Simple::
0114
0115 gameport_unregister_port(&gameport);
0116
0117 The gameport structure
0118 ~~~~~~~~~~~~~~~~~~~~~~
0119
0120 ::
0121
0122 struct gameport {
0123
0124 void *port_data;
0125
0126 A private pointer for free use in the gameport driver. (Not the joystick
0127 driver!)
0128
0129 ::
0130
0131 char name[32];
0132
0133 Driver's name as set by driver calling gameport_set_name(). Informational
0134 purpose only.
0135
0136 ::
0137
0138 char phys[32];
0139
0140 gameport's physical name/description as set by driver calling gameport_set_phys().
0141 Informational purpose only.
0142
0143 ::
0144
0145 int io;
0146
0147 I/O address for use with raw mode. You have to either set this, or ->read()
0148 to some value if your gameport supports raw mode.
0149
0150 ::
0151
0152 int speed;
0153
0154 Raw mode speed of the gameport reads in thousands of reads per second.
0155
0156 ::
0157
0158 int fuzz;
0159
0160 If the gameport supports cooked mode, this should be set to a value that
0161 represents the amount of noise in the data. See
0162 :ref:`gameport_pgm_cooked_mode`.
0163
0164 ::
0165
0166 void (*trigger)(struct gameport *);
0167
0168 Trigger. This function should trigger the ns558 oneshots. If set to NULL,
0169 outb(0xff, io) will be used.
0170
0171 ::
0172
0173 unsigned char (*read)(struct gameport *);
0174
0175 Read the buttons and ns558 oneshot bits. If set to NULL, inb(io) will be
0176 used instead.
0177
0178 ::
0179
0180 int (*cooked_read)(struct gameport *, int *axes, int *buttons);
0181
0182 If the gameport supports cooked mode, it should point this to its cooked
0183 read function. It should fill axes[0..3] with four values of the joystick axes
0184 and buttons[0] with four bits representing the buttons.
0185
0186 ::
0187
0188 int (*calibrate)(struct gameport *, int *axes, int *max);
0189
0190 Function for calibrating the ADC hardware. When called, axes[0..3] should be
0191 pre-filled by cooked data by the caller, max[0..3] should be pre-filled with
0192 expected maximums for each axis. The calibrate() function should set the
0193 sensitivity of the ADC hardware so that the maximums fit in its range and
0194 recompute the axes[] values to match the new sensitivity or re-read them from
0195 the hardware so that they give valid values.
0196
0197 ::
0198
0199 int (*open)(struct gameport *, int mode);
0200
0201 Open() serves two purposes. First a driver either opens the port in raw or
0202 in cooked mode, the open() callback can decide which modes are supported.
0203 Second, resource allocation can happen here. The port can also be enabled
0204 here. Prior to this call, other fields of the gameport struct (namely the io
0205 member) need not to be valid.
0206
0207 ::
0208
0209 void (*close)(struct gameport *);
0210
0211 Close() should free the resources allocated by open, possibly disabling the
0212 gameport.
0213
0214 ::
0215
0216 struct timer_list poll_timer;
0217 unsigned int poll_interval; /* in msecs */
0218 spinlock_t timer_lock;
0219 unsigned int poll_cnt;
0220 void (*poll_handler)(struct gameport *);
0221 struct gameport *parent, *child;
0222 struct gameport_driver *drv;
0223 struct mutex drv_mutex; /* protects serio->drv so attributes can pin driver */
0224 struct device dev;
0225 struct list_head node;
0226
0227 For internal use by the gameport layer.
0228
0229 ::
0230
0231 };
0232
0233 Enjoy!
