share/man/man4/joy.4

   1 .\" $NetBSD: joy.4,v 1.7 2004/12/02 15:02:37 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 1996 Matthieu Herrb
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"      This product includes software developed by Christopher G. Demetriou.
  17 .\" 4. The name of the author may not be used to endorse or promote products
  18 .\"    derived from this software without specific prior written permission
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  21 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  22 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  25 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  29 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .Dd July 22, 2006
  32 .Dt JOY 4
  33 .Os
  34 .Sh NAME
  35 .Nm joy
  36 .Nd game adapter driver
  37 .Sh SYNOPSIS
  38 .Cd "joy* at acpi?"
  39 .Cd "joy* at eap?"
  40 .Cd "joy* at eso?"
  41 .Cd "joy0 at isa? port 0x201"
  42 .Cd "joy* at isapnp?"
  43 .Cd "joy* at ofisa?"
  44 .Cd "joy* at pci?"
  45 .Cd "joy* at pnpbios? index ?"
  46 .Sh DESCRIPTION
  47 This driver provides access to the game adapter.
  48 The lower bit in the minor device number selects the joystick: 0
  49 is the first joystick and 1 is the second.
  50 .Pp
  51 The game control adapter allows up to two joysticks to be attached to
  52 the system.
  53 The adapter plus the driver convert the present resistive value to
  54 a relative joystick position.
  55 On receipt of an output signal, four timing circuits are started.
  56 By determining the time required for the circuit to time-out (a
  57 function of the resistance), the paddle position can be determined.
  58 The adapter could be used as a general purpose I/O card with four
  59 analog (resistive) inputs plus four digital input points.
  60 .Pp
  61 Applications may call
  62 .Xr ioctl 2
  63 on a game adapter driver file descriptor
  64 to set and get the offsets of the two potentiometers and the maximum
  65 time-out value for the circuit.
  66 The
  67 .Xr ioctl 2
  68 commands are listed in
  69 .Aq Pa machine/joystick.h
  70 and currently are:
  71 .Pp
  72 .Bl -tag -width JOY_GET_X_OFFSET -compact
  73 .It Dv JOY_SETTIMEOUT
  74 Sets the maximum time-out for the adapter.
  75 .It Dv JOY_GETTIMEOUT
  76 Returns the current maximum time-out.
  77 .It Dv JOY_SET_X_OFFSET
  78 Sets an offset on X value.
  79 .It Dv JOY_GET_X_OFFSET
  80 Returns the current X offset.
  81 .It Dv JOY_SET_Y_OFFSET
  82 Sets an offset on Y value.
  83 .It Dv JOY_GET_Y_OFFSET
  84 Returns the current Y offset.
  85 .El
  86 .Pp
  87 All these commands take an integer parameter.
  88 .Pp
  89 .Xr read 2
  90 on the file descriptor returns a
  91 .Fa joystick
  92 structure:
  93 .Bd -literal -offset indent
  94 struct joystick {
  95         int x;
  96         int y;
  97         int b1;
  98         int b2;
  99 };
 100 .Ed
 101 .Pp
 102 The fields have the following functions:
 103 .Bl -tag -width xxx
 104 .It Fa x
 105 current X coordinate of the joystick (or position of paddle 1)
 106 .It Fa y
 107 current Y coordinate of the joystick (or position of paddle 2)
 108 .It Fa b1
 109 current state of button 1
 110 .It Fa b2
 111 current state of button 2
 112 .El
 113 .Pp
 114 The b1 and b2 fields in struct joystick are set to 1 if the
 115 corresponding button is down, 0 otherwise.
 116 .Pp
 117 The x and y coordinates are supposed to be between 0 and 255 for a
 118 good joystick and a good adapter.
 119 Unfortunately, because of the
 120 hardware hack that is used to measure the position (by measuring the
 121 time needed to discharge an RC circuit made from the joystick's
 122 potentiometer and a capacitor on the adapter), calibration
 123 is needed to determine exactly what values are returned for a specific
 124 joystick/adapter combination.
 125 Incorrect hardware can yield negative or values greater than 255.
 126 .Pp
 127 A typical calibration procedure uses the values returned at lower
 128 left, center and upper right positions of the joystick to compute the
 129 relative position.
 130 .Pp
 131 This calibration is not part of the driver.
 132 .Sh FILES
 133 .Bl -tag -width Pa -compact
 134 .It Pa /dev/joy0
 135 first joystick
 136 .It Pa /dev/joy1
 137 second joystick
 138 .El
 139 .Sh SEE ALSO
 140 .Xr acpi 4 ,
 141 .Xr eap 4 ,
 142 .Xr eso 4 ,
 143 .Xr isa 4 ,
 144 .Xr isapnp 4 ,
 145 .Xr ofisa 4 ,
 146 .Xr pci 4 ,
 147 .Xr pnpbios 4
 148 .Sh AUTHORS
 149 Jean-Marc Zucconi wrote the
 150 .Fx
 151 driver.
 152 Matthieu Herrb ported it to
 153 .Nx
 154 and wrote this manual page.