JOY(4)

💖 joy(4) — game adapter driver 💖

okay so real talk: this is the joy man page from the Kernel Interfaces Manual, section 4 (kernel interfaces, bestie, that's the driver zone 🎀). Let's get into it ✨

---

🌈 SYNOPSIS

joy* at acpi?
joy* at eap?
joy* at eso?
joy0 at isa? port 0x201
joy* at isapnp?
joy* at ofisa?
joy* at pci?
joy* at pnpbios? index ?

that's the whole vibe check for how this thing attaches, no cap 🫶

---

✨ DESCRIPTION ✨

So this driver gives you access to the game adapter. And the cutest part? The lower bit in the minor device number picks which joystick you're talking to: 0 is the first joystick, 1 is the second. literally that's it, that's the whole selection mechanism 💅

The game control adapter lets you hook up to two joysticks to the system. The adapter plus the driver work together to convert the present resistive value into a relative joystick position. The way it works (and this is iconic honestly): on receipt of an output signal, four timing circuits get started 🏁 and by figuring out how long it takes for the circuit to time-out (which is a function of the resistance), you can determine the paddle position. oh and side quest — the adapter could totally be used as a general purpose I/O card with four analog (resistive) inputs plus four digital input points. versatility queen 👑

---

🦋 the ioctl situation 🦋

Apps may call ioctl(2) on a game adapter driver file descriptor to set and get the offsets of the two potentiometers and the maximum time-out value for the circuit. These ioctl(2) commands live in <machine/joystick.h> and currently are:

• JOY_SETTIMEOUT — sets the maximum time-out for the adapter ⏱️
• JOY_GETTIMEOUT — returns the current maximum time-out
• JOY_SET_X_OFFSET — sets an offset on X value
• JOY_GET_X_OFFSET — returns the current X offset
• JOY_SET_Y_OFFSET — sets an offset on Y value
• JOY_GET_Y_OFFSET — returns the current Y offset

All these commands take an integer parameter. periodt 💜

---

🌸 the struct, the moment, the icon 🌸

read(2) on the file descriptor returns a joystick structure:

struct joystick {
        int x;
        int y;
        int b1;
        int b2;
};

and here's what each field is giving:

• x — current X coordinate of the joystick (or position of paddle 1) 🎯
• y — current Y coordinate of the joystick (or position of paddle 2)
• b1 — current state of button 1 🔘
• b2 — current state of button 2

The b1 and b2 fields in struct joystick are set to 1 if the corresponding button is down, and 0 otherwise. simple as that 🍓

---

😭 the calibration lore (important) 😭

The x and y coordinates are supposed to be between 0 and 255 for a good joystick and a good adapter. but unfortunately — and this is the messy part — because of the hardware hack used to measure the position (by measuring the time needed to discharge an RC circuit made from the joystick's potentiometer and a capacitor on the adapter), calibration is needed to determine exactly what values get returned for a specific joystick/adapter combo. and ngl, incorrect hardware can yield negative values or values greater than 255 💀

A typical calibration procedure uses the values returned at lower left, center and upper right positions of the joystick to compute the relative position.

⚠️ heads up bestie: this calibration is not part of the driver. you gotta do it yourself, the driver is not doing that labor 🙈

---

🎀 FILES

• /dev/joy0 — first joystick
• /dev/joy1 — second joystick

---

👑 SEE ALSO

acpi(4), eap(4), eso(4), isa(4), isapnp(4), ofisa(4), pci(4), pnpbios(4)

go read those, iykyk 📚

---

💜 AUTHORS

Jean-Marc Zucconi wrote the FreeBSD driver. Matthieu Herrb ported it to NetBSD and wrote this manual page. legends only 🫶✨

---

and that's the page!! mwah 💋

this cutie came from the Debian folks, dated July 22, 2006 — yeah it's giving vintage but it still ate 🔥 bye bestie, go calibrate your joystick 💖🎀🦋