µGFX  2.9
version 2.9
ginput_keyboard_microcode.h
Go to the documentation of this file.
1 /*
2  * This file is subject to the terms of the GFX License. If a copy of
3  * the license was not distributed with this file, you can obtain one at:
4  *
5  * http://ugfx.io/license.html
6  */
7 
8 /**
9  * @file src/ginput/ginput_keyboard_microcode.h
10  * @brief GINPUT keyboard layout microcode definition.
11  */
12 
13 #ifndef _KEYBOARD_MICROCODE_H
14 #define _KEYBOARD_MICROCODE_H
15 
16 /*
17  * Keyboard Layout Microcode Definition
18  *
19  * Each time a byte is received from the keyboard it is processed through the layout microcode engine. This enables conversion from
20  * scancodes to ascii, internationalization, and various other tricky keyboard behavior.
21  * Note a "code" is defined as a single byte of data from the keyboard, a "scancode" is one or more "codes" that are sent in response to one keyboard press or release.
22  *
23  * The layout microcode can even be switched on the fly by the application to effect such changes as changing from US English to Russian layouts.
24  * They could conceivably even be loaded from disk at run-time.
25  *
26  * In the interest of efficiency there is very little error checking. Make sure your layout microcode has been debugged properly before releasing
27  * to production code.
28  *
29  * Layout microcode consists of a header followed by 1 or more records.
30  *
31  * The header consists of a KMC_HEADERSTART and associated bytes. The is used only to check it looks like it might be layout microcode and to specify the
32  * version of microcode. Future versions of layout microcode will always have the same header at least to the version number.
33  *
34  * Each record is delimited by a KMC_RECORDSTART. Each record can contain a maximum of 255 bytes.
35  * A record length of zero indicates the end of the layout microcode.
36  *
37  * A record consists a mixture of tests and actions (normally the tests are first). If a test fails the rest of this record is skipped and the next
38  * record is processed. This has the effect of AND'ing multiple tests that occur together.
39  * KMC_TEST_INIT and KMC_TEST_ERROR are special. These tests must be the first byte in their respective record as without this test being there, there
40  * is an implicit test that a code has actually been received.
41  * If no records have successful tests for this code then by extension no actions are executed. That is, the code is ignored.
42  * After fully processing a record, the next record is processed. This can be prevented by using the KMC_ACT_STOP action. When encountered all processing
43  * on this code stops.
44  *
45  * Some tests set a pseudo variable called "diff". This is then used by some actions. At the start of a new record "diff" is set to "code" (or 0 for the init and
46  * error conditions).
47  * Some tests and actions do bit operations on either the saved key-state or on the code itself. Bit numbers (which can range from 0 to 31) test or affect the
48  * "set" state of the bit. OR'ing KMC_BIT_CLEAR with the bit number test or affect the "clear" state of the bit. For example, KMC_ACT_STATEBIT with a parameter
49  * of 10 will set bit 10 of the key-state. KMC_ACT_STATEBIT with a parameter of (10 | KMC_BIT_CLEAR) will clear bit 10 of the key-state.
50  *
51  */
52 
53 #define KMC_HEADERSTART 0x00 // Followed by: ID1 ID2 VER - This is the start of layout microcode.
54  #define KMC_HEADER_ID1 'L'
55  #define KMC_HEADER_ID2 'M'
56  #define KMC_HEADER_VER_1 0x01
57 
58  #define KMC_HEADER_VER_CURRENT KMC_HEADER_VER_1 // The current version number
59  #define KMC_HEADER_VER_MIN KMC_HEADER_VER_1 // The minimum version number accepted
60  #define KMC_HEADER_VER_MAX KMC_HEADER_VER_1 // The maximum version number accepted
61 
62 #define KMC_RECORDSTART 0x01 // Followed by: nn b0 b1 ... b(nn-1) - nn bytes of test and action follow, nn = 00 means end of all tests
63 
64 #define KMC_TEST_INIT 0x10 // Followed by: nothing - The layout is initializing
65 #define KMC_TEST_ERROR 0x11 // Followed by: nothing - The keyboard has signaled an error
66 #define KMC_TEST_CODE 0x12 // Followed by: aa - Code must equal aa. Diff is set to 0
67 #define KMC_TEST_CODERANGE 0x13 // Followed by: aa bb - Code must be between aa and bb (inclusive). Diff is set to (code - aa)
68 #define KMC_TEST_CODETABLE 0x14 // Followed by: n m1 m2 ... - Code must equal an m value. There are n possible m values. Diff is set to 0 to n-1 (the match position)
69 #define KMC_TEST_STATEBIT 0x15 // Followed by: b - Test if a key-state bit is set/clear. b = 0 to 31 or b = (0 | KMC_BIT_CLEAR) to (31 | KMC_BIT_CLEAR)
70 #define KMC_TEST_STATEOR 0x16 // Followed by: b1 b2 - Test two key-state bits and OR the result
71 #define KMC_TEST_STATEAND 0x17 // Followed by: b1 b2 - Test two key-state bits and AND the result
72 #define KMC_TEST_LAYOUTBIT 0x18 // Followed by: b - Test if a layout bit is set/clear. b = 0 to 15 or b = (0 | KMC_BIT_CLEAR) to (15 | KMC_BIT_CLEAR)
73 #define KMC_TEST_LAYOUTOR 0x19 // Followed by: b1 b2 - Test two layout bits and OR the result
74 #define KMC_TEST_LAYOUTAND 0x1A // Followed by: b1 b2 - Test two layout bits and AND the result
75 #define KMC_TEST_CODEBIT 0x1B // Followed by: b - Test if a code bit is set/clear. b = 0 to 7 or b = (0 | KMC_BIT_CLEAR) to (7 | KMC_BIT_CLEAR)
76 #define KMC_TEST_CODEOR 0x1C // Followed by: b1 b2 - Test two code bits and OR the result
77 #define KMC_TEST_CODEAND 0x1D // Followed by: b1 b2 - Test two code bits and AND the result
78 #define KMC_TEST_LASTCODE 0x1E // Followed by: aa - Test if the last scancode was aa
79 #define KMC_TEST_SHIFT 0x20 // Followed by: nothing - Test if a shift key is down
80 #define KMC_TEST_NOSHIFT 0x21 // Followed by: nothing - Test if a shift key is not down
81 #define KMC_TEST_CTRL 0x22 // Followed by: nothing - Test if a control key is down
82 #define KMC_TEST_NOCTRL 0x23 // Followed by: nothing - Test if a control key is not down
83 #define KMC_TEST_ALT 0x24 // Followed by: nothing - Test if an alt key is down
84 #define KMC_TEST_NOALT 0x25 // Followed by: nothing - Test if an alt key is not down
85 #define KMC_TEST_CAPS 0x26 // Followed by: nothing - Test if capslock as modified by shift is active
86 #define KMC_TEST_NOCAPS 0x27 // Followed by: nothing - Test if capslock as modified by shift is not active
87 #define KMC_TEST_NUMLOCK 0x28 // Followed by: nothing - Test if numlock is active
88 #define KMC_TEST_NONUMLOCK 0x29 // Followed by: nothing - Test if numlock is not active
89 
90 #define KMC_ACT_STOP 0xFF // Followed by: nothing - Stop processing this code
91 #define KMC_ACT_DONE 0xFE // Followed by: nothing - Finished processing this scancode sequence. (also implies STOP)
92 #define KMC_ACT_RESET 0xFD // Followed by: nothing - Empty all buffers
93 #define KMC_ACT_STATEBIT 0x80 // Followed by: b - Set or clear bit b in key-state. b = 0 to 31 or b = (0 | KMC_BIT_CLEAR) to (31 | KMC_BIT_CLEAR)
94 #define KMC_ACT_LAYOUTBIT 0x81 // Followed by: b - Set or clear bit b in layout bits. b = 0 to 15 or b = (0 | KMC_BIT_CLEAR) to (15 | KMC_BIT_CLEAR)
95 #define KMC_ACT_CODEBIT 0x82 // Followed by: b - Set or clear bit b in code. b = 0 to 7 or b = (0 | KMC_BIT_CLEAR) to (7 | KMC_BIT_CLEAR)
96 #define KMC_ACT_CHAR 0x83 // Followed by: nn - Append char nn to output buffer
97 #define KMC_ACT_CHARCODE 0x84 // Followed by: nothing - Append the code to output buffer
98 #define KMC_ACT_CHARRANGE 0x85 // Followed by: nn - Append char nn + Diff to output
99 #define KMC_ACT_CHARTABLE 0x86 // Followed by: n c1 c2 ... - Append char to output based on c[Diff]. If Diff is greater than n then nothing is appended.
100 #define KMC_ACT_CLEAR 0x87 // Followed by: nothing - Clear the output buffer
101 #define KMC_ACT_CHARADD 0x88 // Followed by: nn - Multiple the last char in output buffer by nn (assume 0 if none) and add Diff
102 #define KMC_ACT_DATA 0x89 // Followed by: nn - Send nn back to the keyboard
103 
104 #define KMC_BIT_CLEAR 0x80 // The bit number is being used for a bit clear operation rather than a bit set operation.
105 #define KMC_BIT_INVERT 0x40 // Invert the bit rather than setting or clearing it.
106 
107 #endif /* _KEYBOARD_MICROCODE_H */