PS/2 Keyboard

From OSDev.wiki
Revision as of 04:05, 26 March 2012 by Brendan (talk | contribs) (Heading correction)
Jump to navigation Jump to search

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

External Links

Retrieved from "https://osdev.wiki/wiki/PS/2_Keyboard?oldid=19285"