PS/2 Keyboard
Overview
The PS/2 Keyboard is a device that talks to a PS/2 controller using serial communication. Ideally, each different type of PS/2 controller driver should provide some sort of standard/simple "send byte/receive byte" interface, and the PS/2 Keyboard driver would use this interface without caring about lower level details (like what type of PS/2 controller the device is plugged into).
The PS/2 Keyboard accepts commands and sends responses to those commands, and also sends scan codes indicating when a key was pressed or released.
Commands
A PS/2 Keyboard accepts many types of commands. A command is one byte. Some commands have data byte/s which must be sent after the command byte. The keyboard typically responds to a command by sending either an "ACK" (to acknowledge the command) or a "Resend" (to say something was wrong with the previous command) back.
The commands that a PS/2 Keyboard accepts are:
Command Byte | Data Byte/s | Meaning | Response |
---|---|---|---|
0xED | LED states (e.g. bit 0 = ScrollLock, bit 1 = NumLock, bit 2 = CapsLock) | Set LEDs | 0xFA (ACK) or 0xFE (Resend) |
0xEE | None | Echo (for diagnostic purposes, and useful for device removal detection) | 0xEE (Echo) or 0xFE (Resend) |
0xF0 | 0 = get scancode, 1 = set scancode set 1, 2 = set scancode set 2, 3 = set scancode set 3 | Get/set current scan code | 0xFA (ACK) or 0xFE (Resend) |
0xF2 | None | Identify keyboard | 0xFA (ACK) followed by none or more ID bytes (see [| "Detecting Device Types"]) |
0xF3 | Typematic byte (described below) | Set typematic rate and delay | 0xFA (ACK) or 0xFE (Resend) |
0xF4 | None | Enable scanning (keyboard will send scan codes) | 0xFA (ACK) or 0xFE (Resend) |
0xF5 | None | Disable scanning (keyboard won't send scan codes)
Note: May also restore default parameters |
0xFA (ACK) or 0xFE (Resend) |
0xF6 | None | Set default parameters | 0xFA (ACK) or 0xFE (Resend) |
0xF6 | None | Set default parameters | 0xFA (ACK) or 0xFE (Resend) |
0xF7 | None | Set all keys to typematic/autorepeat only (scancode set 3 only) | 0xFA (ACK) or 0xFE (Resend) |
0xF8 | None | Set all keys to make/release (scancode set 3 only) | 0xFA (ACK) or 0xFE (Resend) |
0xF9 | None | Set all keys to make only (scancode set 3 only) | 0xFA (ACK) or 0xFE (Resend) |
0xFA | None | Set all keys to typematic/autorepeat/make/release (scancode set 3 only) | 0xFA (ACK) or 0xFE (Resend) |
0xFB | Scancode for key | Set specific key to typematic/autorepeat only (scancode set 3 only) | 0xFA (ACK) or 0xFE (Resend) |
0xFC | Scancode for key | Set specific key to make/release (scancode set 3 only) | 0xFA (ACK) or 0xFE (Resend) |
0xFD | Scancode for key | Set specific key to make only (scancode set 3 only) | 0xFA (ACK) or 0xFE (Resend) |
0xFE | None | Resend last byte | Previously sent byte or 0xFE (Resend) |
0xFF | None | Reset and start self-test | 0xAA (self-test passed), 0xFC or 0xFD (self test failed), or 0xFE (Resend) |
Typematic Byte
The Typematic Byte used for command 0xF3 (Set typematic rate and delay) has the following format:
Bit | Meaning |
---|---|
0 to 4 | Repeat rate (00000b = 30 Hz, ..., 11111b = 2 Hz) |
5 to 6 | Delay before keys repeat (00b = 250 ms, 01b = 500 ms, 01b = 750 ms, 11b = 1000 ms) |
7 | Must be zero |
Special Bytes
The keyboard sends bytes to the system. Some of these bytes have special meaning (e.g. responses from the commands above). The bytes the keyboard may send are:
Response Byte | Meaning |
---|---|
0x00 | Key detection error or internal buffer overrun |
0xAA | Self test passed (sent after "0xFF (reset)" command or keyboard power up) |
0xEE | Response to "0xEE (echo)" command |
0xFA | Command acknowledged |
0xFC and 0xFD | Self test failed (sent after "0xFF (reset)" command or keyboard power up) |
0xFE | Resend (keyboard wants controller to repeat last command it sent) |
0xFF | Key detection error or internal buffer overrun |
All other bytes sent by the keyboard are scan codes, where interpretation depends on the currently selected scan code set.
Driver Model: Command Queue and State Machine
Commands must be sent one at a time (e.g. if your driver is interrupt driven, you can't start sending a command within the IRQ handler because code outside the IRQ handler may be in the middle of sending a command). The command isn't completed until you've received an ACK for it. For example, if you send a command and the keyboard responds with "0xFE (resend)" then you have to send the command again (possibly limited to 3 retries before you give up and assume the keyboard doesn't support the command you're sending or there's been a hardware failure). Finally, sometimes you want to send several commands at once. For example, you might have a "reinitialise()" function that sets the scan code set, sets the typematic byte, sets the LEDs and enables scanning.
The simplest way to achieve this is for the driver to maintain a queue of commands. When you add a command to the queue, if the queue is empty you start sending the command; otherwise you append the command to the queue. When you receive an "0xFA (ACK)" from the keyboard you discard the command at the head of the queue and start sending the next command in the queue (if any). If you receive an "0xFE (Resend)" from the keyboard you can resend the command at the head of the queue.
The remainder of the driver should be a kind of state machine. The state machine moves into a different state when some commands are successfully completed, and when various bytes are received from the keyboard. For example, the driver might be in a default state and receive a break code that puts it into a "waiting for scan code after receiving break code" state. Then it might receive the first byte of a multi-byte scan code and shift to a "waiting for second byte of scan code after receiving break code" state. Finally it might receive the second/last byte of the scan code, combine the previous bytes into some sort of "key press packet" (and send the packet somewhere - e.g. GUI) and then switch back to the default state.
Scancodes
The keyboard only reports keystrokes. That means it makes no difference between an uppercase 'A' and a lowercase 'a' when you hit the key. The trick is that you'll get two kind of scancodes: make codes and break codes, depending on whether you hit or release the key. For instance if you type an uppercase 'A', you'll get
0x2A | (make shift) |
0x1E | (make A) |
0x9E | (break A) |
0xAA | (break shift) |
Similarly, when you type 'hi' with the CTRL key hold down, your keyboard sends the codes 1d, 23, a3, 17, 97, 9d to the CPU. That means if you want to interpret character 'A' differently based on whether the 'SHIFT' key is up or down, you have first to remember the state of the shift key.
char lowercase[256] = {0x1E:'a'};
char uppercase[256] = {0x1E:'A'};
unsigned shift_state = 0;
void KeyboardIsr()
{
byte new_scan_code = inportb(0x60);
switch(new_scan_code) {
case 0x2a:
shift_state = 1;
break;
case 0xaa:
shift_state = 0;
break;
default:
if (new_scan_code & 0x80) {
/* Ignore the break code */
} else {
new_char =(shift_state ? uppercase:lowercase)[new_scan_code];
/* Do something with new_char. */
}
break;
}
outportb(0x20,0x20);
}
The arrays lowercase and uppercase are the conversion arrays, also called keyboard map. A different keyboard language will lead to different keyboard maps, so you're welcome to provide an API call that will allow the change of that map. You might also want an alternate map for characters composed with ~[ALTgr] key hold down or a wchar_t based map that will allow you to map a keystroke directly to Unicode characters.
Escaped Scancodes
Several keys on your keyboard have a two-bytes scan code (they're said to be escaped scancodes). All those codes start with 0xe0 and are then followed by the 'real' scancode, which means when receiving scancode 0xe0, you should just store the info and wait for the next scancode to know what key even actually occurred.
If you look at the list of escaped scancodes on http://www.win.tue.nl/~aeb/linux/kbd/scancodes.html, you'll note that none of them correspond to a 'printable' character.
unsigned shift_state = 0;
unsigned escaped=0;
void KeyboardIsr()
{
unsigned new_scan_code = inportb(0x60);
if (escaped)
{ new_scan_code += 256;
escaped = 0;
}
switch(new_scan_code) {
case 0x2a: shift_state = 1; break;
case 0xaa: shift_state = 0; break;
case 0xe0: escaped = 1; break;
default:
if (new_scan_code & 0x80) {
// ignore the break code
} else {
new_char=(shift_state?uppercase:lowercase)[new_scan_code];
// do something with new_char
}
break;
outportb(0x20,0x20);
}
Keyboard LEDs
The LEDs of the keyboard are quite simple to enable and disable. To update the status, you must wait for the keyboard buffer to be empty and ready to receive commands. This consists of read port 0x64 until bit 1 is 0. Then you send the command byte 0xED. Then you wait for the keyboard buffer to clear again, and then you send the byte consisting of the LED data. Here is some example code (in C)
#define SCROLL_LED 1
#define NUM_LED 2
#define CAPS_LED 4
void kbd_update_leds(uint8_t status){
uint8_t tmp;
while((inportb(0x64)&2)!=0){} //loop until zero
outportb(0x60,0xED);
while((inportb(0x64)&2)!=0){} //loop until zero
outportb(0x60,status);
}
So to enable the caps lock LED and the scroll lock LED you would do
kbd_update_leds(CAPS_LED | SCROLL_LED);
Non-Printable Characters
ToDo: think about it. We can however already say that they should follow the same 'datapath' as regular characters: we want cursor displacements, regular key types and commands (such as CTRL+S) to be delivered to the application in the same order the user typed them, and the best way to achieve this is to ensure they're delivered through the same data stream.
Non-Latin Characters
In case you'd like to write an OS with support of Arabic, Kanji or whatever, you'll at least need support for Unicode. We had a thread about loading Arabic fonts on the forum, which you might like to look at.
Anyway, please consider the following: even if your userbase is mainly Arabic/Japanese/whatever, your guru base is likely to be international and to prefer messages about "queue" or "thread" than about whatever the translation might look like, so English might be preferred for "behind the scene" stuff.
See Also
Threads
- Keyboard input
- Up or down press?
- Change typerate
- Converting the scancodes
- Discussion about keyboard input in a GUI
- Scroll-lock LED
- Keyboard LEDs (C source)
- Keyboard LEDs (asm source)
External Links
- www.Computer-Engineering.org
- KMT dk's ps2 keyboard and controller referance
- Keyboard scancodes - A complete reference on all scancodes you might encounter.