converter/ibmpc_usb/ibmpc_usb.c

   1 /*
   2 Copyright 2019,2020 Jun Wako <wakojun@gmail.com>
   3
   4 This program is free software: you can redistribute it and/or modify
   5 it under the terms of the GNU General Public License as published by
   6 the Free Software Foundation, either version 2 of the License, or
   7 (at your option) any later version.
   8
   9 This program is distributed in the hope that it will be useful,
  10 but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 GNU General Public License for more details.
  13
  14 You should have received a copy of the GNU General Public License
  15 along with this program.  If not, see <http://www.gnu.org/licenses/>.
  16 */
  17
  18 #include <stdint.h>
  19 #include <stdbool.h>
  20 #include "print.h"
  21 #include "util.h"
  22 #include "debug.h"
  23 #include "ibmpc.h"
  24 #include "host.h"
  25 #include "led.h"
  26 #include "matrix.h"
  27 #include "timer.h"
  28 #include "action.h"
  29 #include "ibmpc_usb.h"
  30 #include "ibmpc.h"
  31
  32
  33 static void matrix_make(uint8_t code);
  34 static void matrix_break(uint8_t code);
  35
  36 static int8_t process_cs1(uint8_t code);
  37 static int8_t process_cs2(uint8_t code);
  38 static int8_t process_cs3(uint8_t code);
  39
  40
  41 static uint8_t matrix[MATRIX_ROWS];
  42 #define ROW(code)      ((code>>3)&0x0F)
  43 #define COL(code)      (code&0x07)
  44
  45 static int16_t read_wait(uint16_t wait_ms)
  46 {
  47     uint16_t start = timer_read();
  48     int16_t code;
  49     while ((code = ibmpc_host_recv()) == -1 && timer_elapsed(start) < wait_ms);
  50     return code;
  51 }
  52
  53 static uint16_t read_keyboard_id(void)
  54 {
  55     uint16_t id = 0;
  56     int16_t  code = 0;
  57
  58     // Disable
  59     //code = ibmpc_host_send(0xF5);
  60
  61     // Read ID
  62     code = ibmpc_host_send(0xF2);
  63     if (code == -1) { id = 0xFFFF; goto DONE; }     // XT or No keyboard
  64     if (code != 0xFA) { id = 0xFFFE; goto DONE; }   // Broken PS/2?
  65
  66     // ID takes 500ms max TechRef [8] 4-41
  67     code = read_wait(500);
  68     if (code == -1) { id = 0x0000; goto DONE; }     // AT
  69     id = (code & 0xFF)<<8;
  70
  71     // Mouse responds with one-byte 00, this returns 00FF [y] p.14
  72     code = read_wait(500);
  73     id |= code & 0xFF;
  74
  75 DONE:
  76     // Enable
  77     //code = ibmpc_host_send(0xF4);
  78
  79     return id;
  80 }
  81
  82 void hook_early_init(void)
  83 {
  84     ibmpc_host_init();
  85     ibmpc_host_enable();
  86 }
  87
  88 void matrix_init(void)
  89 {
  90     debug_enable = true;
  91
  92     // initialize matrix state: all keys off
  93     for (uint8_t i=0; i < MATRIX_ROWS; i++) matrix[i] = 0x00;
  94
  95     return;
  96 }
  97
  98 /*
  99  * keyboard recognition
 100  *
 101  * 1. Send F2 to get keyboard ID
 102  *      a. no ACK(FA): XT keyobard
 103  *      b. ACK but no ID: 84-key AT keyboard CodeSet2
 104  *      c. ID is AB 83: PS/2 keyboard CodeSet2
 105  *      d. ID is BF BF: Terminal keyboard CodeSet3
 106  *      e. error on recv: maybe broken PS/2
 107  */
 108 uint8_t current_protocol = 0;
 109 uint16_t keyboard_id = 0x0000;
 110 keyboard_kind_t keyboard_kind = NONE;
 111 uint8_t matrix_scan(void)
 112 {
 113     // scan code reading states
 114     static enum {
 115         INIT,
 116         WAIT_SETTLE,
 117         AT_RESET,
 118         XT_RESET,
 119         XT_RESET_WAIT,
 120         XT_RESET_DONE,
 121         WAIT_AA,
 122         WAIT_AABF,
 123         WAIT_AABFBF,
 124         READ_ID,
 125         SETUP,
 126         LOOP,
 127     } state = INIT;
 128     static uint16_t init_time;
 129
 130
 131     if (ibmpc_error) {
 132         xprintf("\nERR:%02X ISR:%04X ", ibmpc_error, ibmpc_isr_debug);
 133
 134         // when recv error, neither send error nor buffer full
 135         if (!(ibmpc_error & (IBMPC_ERR_SEND | IBMPC_ERR_FULL))) {
 136             // keyboard init again
 137             if (state == LOOP) {
 138                 xprintf("[RST] ");
 139                 state = INIT;
 140             }
 141         }
 142
 143         // clear or process error
 144         ibmpc_error = IBMPC_ERR_NONE;
 145         ibmpc_isr_debug = 0;
 146     }
 147
 148     // check protocol change AT/XT
 149     if (ibmpc_protocol && ibmpc_protocol != current_protocol) {
 150         xprintf("\nPRT:%02X ISR:%04X ", ibmpc_protocol, ibmpc_isr_debug);
 151
 152         // protocol change between AT and XT indicates that
 153         // keyboard is hotswapped or something goes wrong.
 154         // This requires initializing keyboard again probably.
 155         if (((current_protocol&IBMPC_PROTOCOL_XT) && (ibmpc_protocol&IBMPC_PROTOCOL_AT)) ||
 156             ((current_protocol&IBMPC_PROTOCOL_AT) && (ibmpc_protocol&IBMPC_PROTOCOL_XT))) {
 157             if (state == LOOP) {
 158                 xprintf("[CHG] ");
 159                 state = INIT;
 160             }
 161         }
 162
 163         current_protocol = ibmpc_protocol;
 164         ibmpc_isr_debug = 0;
 165     }
 166
 167     switch (state) {
 168         case INIT:
 169             ibmpc_host_disable();
 170
 171             xprintf("I%u ", timer_read());
 172             keyboard_kind = NONE;
 173             keyboard_id = 0x0000;
 174
 175             matrix_clear();
 176             clear_keyboard();
 177
 178             init_time = timer_read();
 179             state = WAIT_SETTLE;
 180             break;
 181         case WAIT_SETTLE:
 182             // wait for keyboard to settle after plugin
 183             if (timer_elapsed(init_time) > 1000) {
 184                 state = AT_RESET;
 185             }
 186             break;
 187         case AT_RESET:
 188             ibmpc_host_isr_clear();
 189             ibmpc_host_enable();
 190             wait_ms(1); // keyboard can't respond to command without this
 191
 192             // SKIDATA-2-DE(and some other keyboards?) stores 'Code Set' setting in nonvlatile memory
 193             // and keeps it until receiving reset. Sending reset here may be useful to clear it, perhaps.
 194             // https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol#select-alternate-scan-codesf0
 195
 196             // reset command
 197             if (0xFA == ibmpc_host_send(0xFF)) {
 198                 state = WAIT_AA;
 199             } else {
 200                 state = XT_RESET;
 201             }
 202             xprintf("A%u ", timer_read());
 203             break;
 204         case XT_RESET:
 205             // Reset XT-initialize keyboard
 206             // XT: hard reset 500ms for IBM XT Type-1 keyboard and clones
 207             // XT: soft reset 20ms min(clock Lo)
 208             ibmpc_host_disable();   // soft reset: inihibit(clock Lo/Data Hi)
 209             IBMPC_RST_LO();         // hard reset: reset pin Lo
 210
 211             init_time = timer_read();
 212             state = XT_RESET_WAIT;
 213             break;
 214         case XT_RESET_WAIT:
 215             if (timer_elapsed(init_time) > 500) {
 216                 state = XT_RESET_DONE;
 217             }
 218             break;
 219         case XT_RESET_DONE:
 220             IBMPC_RST_HIZ();        // hard reset: reset pin HiZ
 221             ibmpc_host_isr_clear();
 222             ibmpc_host_enable();    // soft reset: idle(clock Hi/Data Hi)
 223
 224             xprintf("X%u ", timer_read());
 225             init_time = timer_read();
 226             state = WAIT_AA;
 227             break;
 228         case WAIT_AA:
 229             // 1) Read BAT code and ID on keybaord power-up
 230             // For example, XT/AT sends 'AA' and Terminal sends 'AA BF BF' after BAT
 231             // AT 84-key: POR and BAT can take 900-9900ms according to AT TechRef [8] 4-7
 232             // AT 101/102-key: POR and BAT can take 450-2500ms according to AT TechRef [8] 4-39
 233             // 2) Read key typed by user or anything after error on protocol or scan code
 234             // This can happen in case of keyboard hotswap, unstable hardware, signal integrity problem or bug
 235
 236             /* wait until keyboard sends any code without 10000ms timeout
 237             if (timer_elapsed(init_time) > 10000) {
 238                 state = READ_ID;
 239             }
 240             */
 241             if (ibmpc_host_recv() != -1) {  // wait for AA
 242                 xprintf("W%u ", timer_read());
 243                 init_time = timer_read();
 244                 state = WAIT_AABF;
 245             }
 246             break;
 247         case WAIT_AABF:
 248             // NOTE: we can omit to wait BF BF
 249             // ID takes 500ms max? TechRef [8] 4-41, though 1ms is enough for 122-key Terminal 6110345
 250             if (timer_elapsed(init_time) > 500) {
 251                 state = READ_ID;
 252             }
 253             if (ibmpc_host_recv() != -1) {  // wait for BF
 254                 xprintf("W%u ", timer_read());
 255                 init_time = timer_read();
 256                 state = WAIT_AABFBF;
 257             }
 258             break;
 259         case WAIT_AABFBF:
 260             if (timer_elapsed(init_time) > 500) {
 261                 state = READ_ID;
 262             }
 263             if (ibmpc_host_recv() != -1) {  // wait for BF
 264                 xprintf("W%u ", timer_read());
 265                 state = READ_ID;
 266             }
 267             break;
 268         case READ_ID:
 269             keyboard_id = read_keyboard_id();
 270             xprintf("R%u ", timer_read());
 271
 272             if (0x0000 == keyboard_id) {            // CodeSet2 AT(IBM PC AT 84-key)
 273                 keyboard_kind = PC_AT;
 274             } else if (0xFFFF == keyboard_id) {     // CodeSet1 XT
 275                 keyboard_kind = PC_XT;
 276             } else if (0xFFFE == keyboard_id) {     // CodeSet2 PS/2 fails to response?
 277                 keyboard_kind = PC_AT;
 278             } else if (0x00FF == keyboard_id) {     // Mouse is not supported
 279                 xprintf("Mouse: not supported\n");
 280                 keyboard_kind = NONE;
 281 #ifdef G80_2551_SUPPORT
 282             } else if (0xAB86 == keyboard_id ||
 283                        0xAB85 == keyboard_id) {     // For G80-2551 and other 122-key terminal
 284                 // https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol#ab86
 285                 // https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol#ab85
 286
 287                 if ((0xFA == ibmpc_host_send(0xF0)) &&
 288                     (0xFA == ibmpc_host_send(0x03))) {
 289                     // switch to code set 3
 290                     keyboard_kind = PC_TERMINAL;
 291                 } else {
 292                     keyboard_kind = PC_AT;
 293                 }
 294 #endif
 295             } else if (0xBFB0 == keyboard_id) {     // IBM RT Keyboard
 296                 // https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol#bfb0
 297                 // TODO: LED indicator fix
 298                 //keyboard_kind = PC_TERMINAL_IBM_RT;
 299                 keyboard_kind = PC_TERMINAL;
 300             } else if (0xAB00 == (keyboard_id & 0xFF00)) {  // CodeSet2 PS/2
 301                 keyboard_kind = PC_AT;
 302             } else if (0xBF00 == (keyboard_id & 0xFF00)) {  // CodeSet3 Terminal
 303                 keyboard_kind = PC_TERMINAL;
 304             } else {
 305                 keyboard_kind = PC_AT;
 306             }
 307
 308             xprintf("\nID:%04X(%d) ", keyboard_id, keyboard_kind);
 309
 310             state = SETUP;
 311             break;
 312         case SETUP:
 313             xprintf("S%u ", timer_read());
 314             switch (keyboard_kind) {
 315                 case PC_XT:
 316                     break;
 317                 case PC_AT:
 318                     led_set(host_keyboard_leds());
 319                     break;
 320                 case PC_TERMINAL:
 321                     // Set all keys to make/break type
 322                     ibmpc_host_send(0xF8);
 323                     // This should not be harmful
 324                     led_set(host_keyboard_leds());
 325                     break;
 326                 default:
 327                     break;
 328             }
 329             state = LOOP;
 330             xprintf("L%u ", timer_read());
 331         case LOOP:
 332             {
 333                 uint16_t code = ibmpc_host_recv();
 334                 if (code == -1) {
 335                     // no code
 336                     break;
 337                 }
 338
 339                 // Keyboard Error/Overrun([3]p.26) or Buffer full
 340                 // Scan Code Set 1: 0xFF
 341                 // Scan Code Set 2 and 3: 0x00
 342                 // Buffer full(IBMPC_ERR_FULL): 0xFF
 343                 if (code == 0x00 || code == 0xFF) {
 344                     // clear stuck keys
 345                     matrix_clear();
 346                     clear_keyboard();
 347
 348                     xprintf("\n[OVR] ");
 349                     break;
 350                 }
 351
 352                 switch (keyboard_kind) {
 353                     case PC_XT:
 354                         if (process_cs1(code) == -1) state = INIT;
 355                         break;
 356                     case PC_AT:
 357                         if (process_cs2(code) == -1) state = INIT;
 358                         break;
 359                     case PC_TERMINAL:
 360                         if (process_cs3(code) == -1) state = INIT;
 361                         break;
 362                     default:
 363                         break;
 364                 }
 365             }
 366             break;
 367         default:
 368             break;
 369     }
 370     return 1;
 371 }
 372
 373 inline
 374 bool matrix_is_on(uint8_t row, uint8_t col)
 375 {
 376     return (matrix[row] & (1<<col));
 377 }
 378
 379 inline
 380 uint8_t matrix_get_row(uint8_t row)
 381 {
 382     return matrix[row];
 383 }
 384
 385 uint8_t matrix_key_count(void)
 386 {
 387     uint8_t count = 0;
 388     for (uint8_t i = 0; i < MATRIX_ROWS; i++) {
 389         count += bitpop(matrix[i]);
 390     }
 391     return count;
 392 }
 393
 394
 395 inline
 396 static void matrix_make(uint8_t code)
 397 {
 398     if (!matrix_is_on(ROW(code), COL(code))) {
 399         matrix[ROW(code)] |= 1<<COL(code);
 400     }
 401 }
 402
 403 inline
 404 static void matrix_break(uint8_t code)
 405 {
 406     if (matrix_is_on(ROW(code), COL(code))) {
 407         matrix[ROW(code)] &= ~(1<<COL(code));
 408     }
 409 }
 410
 411 void matrix_clear(void)
 412 {
 413     for (uint8_t i=0; i < MATRIX_ROWS; i++) matrix[i] = 0x00;
 414 }
 415
 416 void led_set(uint8_t usb_led)
 417 {
 418     // Sending before keyboard recognition may be harmful for XT keyboard
 419     if (keyboard_kind == NONE) return;
 420
 421     // XT keyobard doesn't support any command and it is harmful perhaps
 422     // https://github.com/tmk/tmk_keyboard/issues/635#issuecomment-626993437
 423     if (keyboard_kind == PC_XT) return;
 424
 425     // It should be safe to send the command to keyboards with AT protocol
 426     // - IBM Terminal doesn't support the command and response with 0xFE but it is not harmful.
 427     // - Some other Terminals like G80-2551 supports the command.
 428     //   https://geekhack.org/index.php?topic=103648.msg2894921#msg2894921
 429
 430     // TODO: PC_TERMINAL_IBM_RT support
 431     uint8_t ibmpc_led = 0;
 432     if (usb_led &  (1<<USB_LED_SCROLL_LOCK))
 433         ibmpc_led |= (1<<IBMPC_LED_SCROLL_LOCK);
 434     if (usb_led &  (1<<USB_LED_NUM_LOCK))
 435         ibmpc_led |= (1<<IBMPC_LED_NUM_LOCK);
 436     if (usb_led &  (1<<USB_LED_CAPS_LOCK))
 437         ibmpc_led |= (1<<IBMPC_LED_CAPS_LOCK);
 438     ibmpc_host_set_led(ibmpc_led);
 439 }
 440
 441
 442 /*******************************************************************************
 443  * XT: Scan Code Set 1
 444  *
 445  * See [3], [a]
 446  *
 447  * E0-escaped scan codes are translated into unused range of the matrix.(54-7F)
 448  *
 449  *     01-53: Normal codes used in original XT keyboard
 450  *     54-7F: Not used in original XT keyboard
 451  *
 452  *         0   1   2   3   4   5   6   7   8   9   A   B   C   D   E   F
 453  *     50  -   -   -   -   *   *   x   x   x   x   *   *   *   *   *   *
 454  *     60  *   *   *   *   x   x   x   x   x   x   x   x   x   x   x   *
 455  *     70  x   *   *   x   *   *   x   *   *   x   *   x   *   x   x   *
 456  *
 457  * -: codes existed in original XT keyboard
 458  * *: E0-escaped codes translated
 459  * x: Non-espcaped codes(Some are not used in real keyboards probably)
 460  *
 461  * Codes assigned in range 54-7F:
 462  *
 463  *     50  -                60  Up*                 70  KANAx
 464  *     51  -                61  Left*               71  Insert*
 465  *     52  -                62  Down*               72  Delete*
 466  *     53  -                63  Right*              73  ROx
 467  *     54  PrintScr*        64  F13x                74  Home*
 468  *     55  Pause*           65  F14x                75  End*
 469  *     56  Euro2x           66  F15x                76  F24x
 470  *     57  F11x             67  F16x                77  PageUp*
 471  *     58  F12x             68  F17x                78  PageDown*
 472  *     59  Keypad=x         69  F18x                79  HENKANx
 473  *     5A  LGUI*            6A  F19x                7A  RCTL*
 474  *     5B  RGUI*            6B  F20x                7B  MUHENKANx
 475  *     5C  APP*             6C  F21x                7C  RALT*
 476  *     5D  Mute*            6D  F22x                7D  JPYx
 477  *     5E  Volume Down*     6E  F23x                7E  Keypad,x
 478  *     5F  Volume Up*       6F  Keypad Enter*       7F  Keypad/ *
 479  */
 480 static uint8_t cs1_e0code(uint8_t code) {
 481     switch(code) {
 482         // Original IBM XT keyboard doesn't use E0-codes probably
 483         // Some XT compatilble keyobards need these keys?
 484         case 0x37: return 0x54; // Print Screen
 485         case 0x46: return 0x55; // Ctrl + Pause
 486         case 0x5B: return 0x5A; // Left  GUI
 487         case 0x5C: return 0x5B; // Right GUI
 488         case 0x5D: return 0x5C; // Application
 489         case 0x20: return 0x5D; // Mute
 490         case 0x2E: return 0x5E; // Volume Down
 491         case 0x30: return 0x5F; // Volume Up
 492         case 0x48: return 0x60; // Up
 493         case 0x4B: return 0x61; // Left
 494         case 0x50: return 0x62; // Down
 495         case 0x4D: return 0x63; // Right
 496         case 0x1C: return 0x6F; // Keypad Enter
 497         case 0x52: return 0x71; // Insert
 498         case 0x53: return 0x72; // Delete
 499         case 0x47: return 0x74; // Home
 500         case 0x4F: return 0x75; // End
 501         case 0x49: return 0x77; // Page Up
 502         case 0x51: return 0x78; // Page Down
 503         case 0x1D: return 0x7A; // Right Ctrl
 504         case 0x38: return 0x7C; // Right Alt
 505         case 0x35: return 0x7F; // Keypad /
 506
 507         // Shared matrix cell with other keys
 508         case 0x5E: return 0x70; // Power (KANA)
 509         case 0x5F: return 0x79; // Sleep (HENKAN)
 510         case 0x63: return 0x7B; // Wake  (MUHENKAN)
 511
 512         default:
 513            xprintf("!CS1_E0_%02X!\n", code);
 514            return code;
 515     }
 516     return 0x00;
 517 }
 518
 519 static int8_t process_cs1(uint8_t code)
 520 {
 521     static enum {
 522         INIT,
 523         E0,
 524         // Pause: E1 1D 45, E1 9D C5 [a] (TODO: test)
 525         E1,
 526         E1_1D,
 527         E1_9D,
 528     } state = INIT;
 529
 530     switch (state) {
 531         case INIT:
 532             switch (code) {
 533                 case 0xE0:
 534                     state = E0;
 535                     break;
 536                 case 0xE1:
 537                     state = E1;
 538                     break;
 539                 default:
 540                     if (code < 0x80)
 541                         matrix_make(code);
 542                     else
 543                         matrix_break(code & 0x7F);
 544                     break;
 545             }
 546             break;
 547         case E0:
 548             switch (code) {
 549                 case 0x2A:
 550                 case 0xAA:
 551                 case 0x36:
 552                 case 0xB6:
 553                     //ignore fake shift
 554                     state = INIT;
 555                     break;
 556                 default:
 557                     if (code < 0x80)
 558                         matrix_make(cs1_e0code(code));
 559                     else
 560                         matrix_break(cs1_e0code(code & 0x7F));
 561                     state = INIT;
 562                     break;
 563             }
 564             break;
 565         case E1:
 566             switch (code) {
 567                 case 0x1D:
 568                     state = E1_1D;
 569                     break;
 570                 case 0x9D:
 571                     state = E1_9D;
 572                     break;
 573                 default:
 574                     state = INIT;
 575                     break;
 576             }
 577             break;
 578         case E1_1D:
 579             switch (code) {
 580                 case 0x45:
 581                     matrix_make(0x55);
 582                     break;
 583                 default:
 584                     state = INIT;
 585                     break;
 586             }
 587             break;
 588         case E1_9D:
 589             switch (code) {
 590                 case 0x45:
 591                     matrix_break(0x55);
 592                     break;
 593                 default:
 594                     state = INIT;
 595                     break;
 596             }
 597             break;
 598         default:
 599             state = INIT;
 600     }
 601     return 0;
 602 }
 603
 604
 605 /*******************************************************************************
 606  * AT, PS/2: Scan Code Set 2
 607  *
 608  * Exceptional Handling
 609  * --------------------
 610  * Some keys should be handled exceptionally. See [b].
 611  *
 612  * Scan codes are varied or prefix/postfix'd depending on modifier key state.
 613  *
 614  * 1) Insert, Delete, Home, End, PageUp, PageDown, Up, Down, Right, Left
 615  *     a) when Num Lock is off
 616  *     modifiers | make                      | break
 617  *     ----------+---------------------------+----------------------
 618  *     Ohter     |                    <make> | <break>
 619  *     LShift    | E0 F0 12           <make> | <break>  E0 12
 620  *     RShift    | E0 F0 59           <make> | <break>  E0 59
 621  *     L+RShift  | E0 F0 12  E0 F0 59 <make> | <break>  E0 59 E0 12
 622  *
 623  *     b) when Num Lock is on
 624  *     modifiers | make                      | break
 625  *     ----------+---------------------------+----------------------
 626  *     Other     | E0 12              <make> | <break>  E0 F0 12
 627  *     Shift'd   |                    <make> | <break>
 628  *
 629  *     Handling: These prefix/postfix codes are ignored.
 630  *
 631  *
 632  * 2) Keypad /
 633  *     modifiers | make                      | break
 634  *     ----------+---------------------------+----------------------
 635  *     Ohter     |                    <make> | <break>
 636  *     LShift    | E0 F0 12           <make> | <break>  E0 12
 637  *     RShift    | E0 F0 59           <make> | <break>  E0 59
 638  *     L+RShift  | E0 F0 12  E0 F0 59 <make> | <break>  E0 59 E0 12
 639  *
 640  *     Handling: These prefix/postfix codes are ignored.
 641  *
 642  *
 643  * 3) PrintScreen
 644  *     modifiers | make         | break
 645  *     ----------+--------------+-----------------------------------
 646  *     Other     | E0 12  E0 7C | E0 F0 7C  E0 F0 12
 647  *     Shift'd   |        E0 7C | E0 F0 7C
 648  *     Control'd |        E0 7C | E0 F0 7C
 649  *     Alt'd     |           84 | F0 84
 650  *
 651  *     Handling: These prefix/postfix codes are ignored, and both scan codes
 652  *               'E0 7C' and 84 are seen as PrintScreen.
 653  *
 654  * 4) Pause
 655  *     modifiers | make(no break code)
 656  *     ----------+--------------------------------------------------
 657  *     Other     | E1 14 77 E1 F0 14 F0 77
 658  *     Control'd | E0 7E E0 F0 7E
 659  *
 660  *     Handling: Both code sequences are treated as a whole.
 661  *               And we need a ad hoc 'pseudo break code' hack to get the key off
 662  *               because it has no break code.
 663  *
 664  * Notes:
 665  * 'Hanguel/English'(F1) and 'Hanja'(F2) have no break code. See [a].
 666  * These two Korean keys need exceptional handling and are not supported for now.
 667  *
 668  */
 669 static uint8_t cs2_e0code(uint8_t code) {
 670     switch(code) {
 671         // E0 prefixed codes translation See [a].
 672         case 0x11: return 0x0F; // right alt
 673         case 0x14: return 0x17; // right control
 674         case 0x1F: return 0x19; // left GUI
 675         case 0x27: return 0x1F; // right GUI
 676         case 0x2F: return 0x5C; // apps
 677         case 0x4A: return 0x60; // keypad /
 678         case 0x5A: return 0x62; // keypad enter
 679         case 0x69: return 0x27; // end
 680         case 0x6B: return 0x53; // cursor left
 681         case 0x6C: return 0x2F; // home
 682         case 0x70: return 0x39; // insert
 683         case 0x71: return 0x37; // delete
 684         case 0x72: return 0x3F; // cursor down
 685         case 0x74: return 0x47; // cursor right
 686         case 0x75: return 0x4F; // cursor up
 687         case 0x7A: return 0x56; // page down
 688         case 0x7D: return 0x5E; // page up
 689         case 0x7C: return 0x7F; // Print Screen
 690         case 0x7E: return 0x00; // Control'd Pause
 691
 692         case 0x21: return 0x65; // volume down
 693         case 0x32: return 0x6E; // volume up
 694         case 0x23: return 0x6F; // mute
 695         case 0x10: return 0x08; // (WWW search)     -> F13
 696         case 0x18: return 0x10; // (WWW favourites) -> F14
 697         case 0x20: return 0x18; // (WWW refresh)    -> F15
 698         case 0x28: return 0x20; // (WWW stop)       -> F16
 699         case 0x30: return 0x28; // (WWW forward)    -> F17
 700         case 0x38: return 0x30; // (WWW back)       -> F18
 701         case 0x3A: return 0x38; // (WWW home)       -> F19
 702         case 0x40: return 0x40; // (my computer)    -> F20
 703         case 0x48: return 0x48; // (email)          -> F21
 704         case 0x2B: return 0x50; // (calculator)     -> F22
 705         case 0x34: return 0x08; // (play/pause)     -> F13
 706         case 0x3B: return 0x10; // (stop)           -> F14
 707         case 0x15: return 0x18; // (previous track) -> F15
 708         case 0x4D: return 0x20; // (next track)     -> F16
 709         case 0x50: return 0x28; // (media select)   -> F17
 710         case 0x5E: return 0x50; // (ACPI wake)      -> F22
 711         case 0x3F: return 0x57; // (ACPI sleep)     -> F23
 712         case 0x37: return 0x5F; // (ACPI power)     -> F24
 713
 714         // https://github.com/tmk/tmk_keyboard/pull/636
 715         case 0x03: return 0x18; // Help        DEC LK411 -> F15
 716         case 0x04: return 0x08; // F13         DEC LK411
 717         case 0x0B: return 0x20; // Do          DEC LK411 -> F16
 718         case 0x0C: return 0x10; // F14         DEC LK411
 719         case 0x0D: return 0x19; // LCompose    DEC LK411 -> LGUI
 720         case 0x79: return 0x6D; // KP-         DEC LK411 -> PCMM
 721         case 0x83: return 0x28; // F17         DEC LK411
 722         default: return (code & 0x7F);
 723     }
 724 }
 725
 726 static int8_t process_cs2(uint8_t code)
 727 {
 728     // scan code reading states
 729     static enum {
 730         INIT,
 731         F0,
 732         E0,
 733         E0_F0,
 734         // Pause
 735         E1,
 736         E1_14,
 737         E1_F0,
 738         E1_F0_14,
 739         E1_F0_14_F0,
 740     } state = INIT;
 741
 742     switch (state) {
 743         case INIT:
 744             switch (code) {
 745                 case 0xE0:
 746                     state = E0;
 747                     break;
 748                 case 0xF0:
 749                     state = F0;
 750                     break;
 751                 case 0xE1:
 752                     state = E1;
 753                     break;
 754                 case 0x83:  // F7
 755                     matrix_make(0x02);
 756                     state = INIT;
 757                     break;
 758                 case 0x84:  // Alt'd PrintScreen
 759                     matrix_make(0x7F);
 760                     state = INIT;
 761                     break;
 762                 case 0xAA:  // Self-test passed
 763                 case 0xFC:  // Self-test failed
 764                     // replug or unstable connection probably
 765                 default:    // normal key make
 766                     state = INIT;
 767                     if (code < 0x80) {
 768                         matrix_make(code);
 769                     } else {
 770                         matrix_clear();
 771                         xprintf("!CS2_INIT!\n");
 772                         return -1;
 773                     }
 774             }
 775             break;
 776         case E0:    // E0-Prefixed
 777             switch (code) {
 778                 case 0x12:  // to be ignored
 779                 case 0x59:  // to be ignored
 780                     state = INIT;
 781                     break;
 782                 case 0xF0:
 783                     state = E0_F0;
 784                     break;
 785                 default:
 786                     state = INIT;
 787                     if (code < 0x80) {
 788                         matrix_make(cs2_e0code(code));
 789                     } else {
 790                         matrix_clear();
 791                         xprintf("!CS2_E0!\n");
 792                         return -1;
 793                     }
 794             }
 795             break;
 796         case F0:    // Break code
 797             switch (code) {
 798                 case 0x83:  // F7
 799                     matrix_break(0x02);
 800                     state = INIT;
 801                     break;
 802                 case 0x84:  // Alt'd PrintScreen
 803                     matrix_break(0x7F);
 804                     state = INIT;
 805                     break;
 806                 default:
 807                     state = INIT;
 808                     if (code < 0x80) {
 809                         matrix_break(code);
 810                     } else {
 811                         matrix_clear();
 812                         xprintf("!CS2_F0!\n");
 813                         return -1;
 814                     }
 815             }
 816             break;
 817         case E0_F0: // Break code of E0-prefixed
 818             switch (code) {
 819                 case 0x12:  // to be ignored
 820                 case 0x59:  // to be ignored
 821                     state = INIT;
 822                     break;
 823                 default:
 824                     state = INIT;
 825                     if (code < 0x80) {
 826                         matrix_break(cs2_e0code(code));
 827                     } else {
 828                         matrix_clear();
 829                         xprintf("!CS2_E0_F0!\n");
 830                         return -1;
 831                     }
 832             }
 833             break;
 834         // Pause make: E1 14 77
 835         case E1:
 836             switch (code) {
 837                 case 0x14:
 838                     state = E1_14;
 839                     break;
 840                 case 0xF0:
 841                     state = E1_F0;
 842                     break;
 843                 default:
 844                     state = INIT;
 845             }
 846             break;
 847         case E1_14:
 848             switch (code) {
 849                 case 0x77:
 850                     matrix_make(0x00);
 851                     state = INIT;
 852                     break;
 853                 default:
 854                     state = INIT;
 855             }
 856             break;
 857         // Pause break: E1 F0 14 F0 77
 858         case E1_F0:
 859             switch (code) {
 860                 case 0x14:
 861                     state = E1_F0_14;
 862                     break;
 863                 default:
 864                     state = INIT;
 865             }
 866             break;
 867         case E1_F0_14:
 868             switch (code) {
 869                 case 0xF0:
 870                     state = E1_F0_14_F0;
 871                     break;
 872                 default:
 873                     state = INIT;
 874             }
 875             break;
 876         case E1_F0_14_F0:
 877             switch (code) {
 878                 case 0x77:
 879                     matrix_break(0x00);
 880                     state = INIT;
 881                     break;
 882                 default:
 883                     state = INIT;
 884             }
 885             break;
 886         default:
 887             state = INIT;
 888     }
 889     return 0;
 890 }
 891
 892 /*
 893  * Terminal: Scan Code Set 3
 894  *
 895  * See [3], [7] and
 896  * https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol#scan-code-set-3
 897  */
 898 static int8_t process_cs3(uint8_t code)
 899 {
 900     static enum {
 901         READY,
 902         F0,
 903 #ifdef G80_2551_SUPPORT
 904         // G80-2551 four extra keys around cursor keys
 905         G80,
 906         G80_F0,
 907 #endif
 908     } state = READY;
 909
 910     switch (state) {
 911         case READY:
 912             switch (code) {
 913                 case 0xF0:
 914                     state = F0;
 915                     break;
 916                 case 0x83:  // PrintScreen
 917                     matrix_make(0x02);
 918                     break;
 919                 case 0x84:  // Keypad *
 920                     matrix_make(0x7F);
 921                     break;
 922                 case 0x85:  // Muhenkan
 923                     matrix_make(0x0B);
 924                     break;
 925                 case 0x86:  // Henkan
 926                     matrix_make(0x06);
 927                     break;
 928                 case 0x87:  // Hiragana
 929                     matrix_make(0x00);
 930                     break;
 931                 case 0x8B:  // Left GUI
 932                     matrix_make(0x01);
 933                     break;
 934                 case 0x8C:  // Right GUI
 935                     matrix_make(0x09);
 936                     break;
 937                 case 0x8D:  // Application
 938                     matrix_make(0x0A);
 939                     break;
 940 #ifdef G80_2551_SUPPORT
 941                 case 0x80:  // G80-2551 four extra keys around cursor keys
 942                     state = G80;
 943                     break;
 944 #endif
 945                 default:    // normal key make
 946                     if (code < 0x80) {
 947                         matrix_make(code);
 948                     } else {
 949                         xprintf("!CS3_READY!\n");
 950                         return -1;
 951                     }
 952             }
 953             break;
 954         case F0:    // Break code
 955             switch (code) {
 956                 case 0x83:  // PrintScreen
 957                     matrix_break(0x02);
 958                     state = READY;
 959                     break;
 960                 case 0x84:  // Keypad *
 961                     matrix_break(0x7F);
 962                     state = READY;
 963                     break;
 964                 case 0x85:  // Muhenkan
 965                     matrix_break(0x0B);
 966                     state = READY;
 967                     break;
 968                 case 0x86:  // Henkan
 969                     matrix_break(0x06);
 970                     state = READY;
 971                     break;
 972                 case 0x87:  // Hiragana
 973                     matrix_break(0x00);
 974                     state = READY;
 975                     break;
 976                 case 0x8B:  // Left GUI
 977                     matrix_break(0x01);
 978                     state = READY;
 979                     break;
 980                 case 0x8C:  // Right GUI
 981                     matrix_break(0x09);
 982                     state = READY;
 983                     break;
 984                 case 0x8D:  // Application
 985                     matrix_break(0x0A);
 986                     state = READY;
 987                     break;
 988                 default:
 989                     state = READY;
 990                     if (code < 0x80) {
 991                         matrix_break(code);
 992                     } else {
 993                         xprintf("!CS3_F0!\n");
 994                         return -1;
 995                     }
 996             }
 997             break;
 998 #ifdef G80_2551_SUPPORT
 999         /*
1000          * G80-2551 terminal keyboard support
1001          * https://deskthority.net/wiki/Cherry_G80-2551
1002          * https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-AT-Keyboard-Protocol#g80-2551-in-code-set-3
1003          */
1004         case G80:   // G80-2551 four extra keys around cursor keys
1005             switch (code) {
1006                 case (0x26):    // TD= -> JYEN
1007                     matrix_make(0x5D);
1008                     break;
1009                 case (0x25):    // page with edge -> NUHS
1010                     matrix_make(0x53);
1011                     break;
1012                 case (0x16):    // two pages -> RO
1013                     matrix_make(0x51);
1014                     break;
1015                 case (0x1E):    // calc -> KANA
1016                     matrix_make(0x00);
1017                     break;
1018                 case (0xF0):
1019                     state = G80_F0;
1020                     return 0;
1021                 default:
1022                     // Not supported
1023                     matrix_clear();
1024                     break;
1025             }
1026             state = READY;
1027             break;
1028         case G80_F0:
1029             switch (code) {
1030                 case (0x26):    // TD= -> JYEN
1031                     matrix_break(0x5D);
1032                     break;
1033                 case (0x25):    // page with edge -> NUHS
1034                     matrix_break(0x53);
1035                     break;
1036                 case (0x16):    // two pages -> RO
1037                     matrix_break(0x51);
1038                     break;
1039                 case (0x1E):    // calc -> KANA
1040                     matrix_break(0x00);
1041                     break;
1042                 default:
1043                     // Not supported
1044                     matrix_clear();
1045                     break;
1046             }
1047             state = READY;
1048             break;
1049 #endif
1050     }
1051     return 0;
1052 }
1053
1054 /*
1055  * IBM PC Keyboard Protocol Resources:
1056  *
1057  * [a] Microsoft USB HID to PS/2 Translation Table - Scan Code Set 1 and 2
1058  * http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/translate.pdf
1059  *
1060  * [b] Microsoft Keyboard Scan Code Specification - Special rules of Scan Code Set 1 and 2
1061  * http://download.microsoft.com/download/1/6/1/161ba512-40e2-4cc9-843a-923143f3456c/scancode.doc
1062  *
1063  * [1] PS/2 Reference Manuals - Collection of IBM Personal System/2 documents.
1064  * http://www.mcamafia.de/pdf/pdfref.htm
1065  *
1066  * [2] Keyboard and Auxiliary Device Controller - Signal Timing and Format
1067  * http://www.mcamafia.de/pdf/ibm_hitrc07.pdf
1068  *
1069  * [3] Keyboards(101- and 102-key) - Keyboard Layout, Scan Code Set, POR, and Commands.
1070  * http://www.mcamafia.de/pdf/ibm_hitrc11.pdf
1071  *
1072  * [4] IBM PC XT Keyboard Protocol
1073  * https://github.com/tmk/tmk_keyboard/wiki/IBM-PC-XT-Keyboard-Protocol
1074  *
1075  * [5] IBM Keyboard Scan Code by John Elliott - 83-key, 84-key, 102-key and 122-key
1076  * https://www.seasip.info/VintagePC/index.html
1077  *
1078  * [6] IBM 1391406 Keyboard - Scan Code Set 2 of 102-key PS/2 keyboard
1079  * https://www.seasip.info/VintagePC/ibm_1391406.html
1080  *
1081  * [7] The IBM 6110344 Keyboard - Scan Code Set 3 of 122-key terminal keyboard
1082  * https://www.seasip.info/VintagePC/ibm_6110344.html
1083  *
1084  * [8] IBM PC AT Technical Reference 1986
1085  * http://bitsavers.org/pdf/ibm/pc/at/6183355_PC_AT_Technical_Reference_Mar86.pdf
1086  *
1087  * [y] TrackPoint Engineering Specifications for version 3E
1088  * https://web.archive.org/web/20100526161812/http://wwwcssrv.almaden.ibm.com/trackpoint/download.html
1089  *
1090  * [z] [Soarer's XT/AT/PS2/Terminal to USB converter]
1091  * https://geekhack.org/index.php?topic=17458.0
1092  *
1093  */