1 /*---------------------------------------------------------------------------*
2   Project:  Revolution USB keyboard library
3   File:     kbd.h
4 
5   Copyright 2007 Nintendo.  All rights reserved.
6 
7   These coded instructions, statements, and computer programs contain
8   proprietary information of Nintendo of America Inc. and/or Nintendo
9   Company Ltd., and are protected by Federal copyright law.  They may
10   not be disclosed to third parties or copied or duplicated in any form,
11   in whole or in part, without the prior written consent of Nintendo.
12 
13   $Log: kbd.h,v $
14   Revision 1.20.6.1  2009/10/14 10:11:05  iwai_yuma
15   Rool back into StackB.
16 
17   Revision 1.19  2008/03/14 18:38:10  dante.treglia
18   Fixed KBD_UC_IS_CTRL_KEY macro
19 
20   Revision 1.18  2007/10/08 18:44:20  henrch
21   - KBD now uses dynanmic memory for lib
22   - callbacks registered on KBDInit
23   - removed KBD_ERR_BAD_POINTER, now ASSERTMSG
24 
25   Revision 1.17  2007/07/13 23:49:11  carlmu
26   Added KBDSetLedsRetry.
27   Changed API for LED callback.
28 
29   Revision 1.16  2007/07/12 01:38:05  dante.treglia
30   KBD: Removed unsupported languages from typedef enum _KBDCountryCode.
31 
32   Revision 1.15  2007/06/21 22:40:38  carlmu
33   Updated for 1.4 API (changed LED handling).
34 
35   Revision 1.14  2007/05/29 21:56:06  carlmu
36   Changed macro indicating NumLock state.
37 
38   Revision 1.13  2007/05/22 00:43:30  carlmu
39   Changed #ifdef USBKBD to #ifndef USE_PPC_HID, etc.
40 
41   Revision 1.12  2007/05/17 21:57:58  carlmu
42   Added ability to set PPC HID lib memory.
43 
44   Revision 1.11  2007/05/11 23:21:07  carlmu
45   Added US_International map code.
46   Added macros related to CTRL keys.
47 
48   Revision 1.10  2007/05/05 01:58:13  carlmu
49   Changes for 0.8 API
50 
51   Revision 1.9  2007/05/01 21:38:13  carlmu
52   Stripped dead-key-related code.
53   Changed KBD_MS_BASE_KEY to KBD_MS_SHIFTED_KEY.
54 
55   Revision 1.8  2007/04/25 19:17:22  carlmu
56   Added macros related to keypad digit keys.
57 
58   Revision 1.7  2007/04/18 00:01:32  carlmu
59   Updated for 0.5 API.
60 
61   Revision 1.6  2007/04/10 18:43:20  carlmu
62   New 0.4 API structure.
63 
64   Revision 1.5  2007/04/05 21:56:59  carlmu
65   Changed kbd_usb_codes.h to kbd_hid_codes.h.
66 
67   Revision 1.4  2007/04/04 19:39:50  carlmu
68   Added KBD_HID_NONE.
69 
70   Revision 1.3  2007/04/02 19:11:24  carlmu
71   Get/Set LED calls now private.
72   Set callback functions return old callback.
73   Added scroll lock modifier state.
74 
75   Revision 1.2  2007/03/28 00:27:45  carlmu
76   Updated to 0.2 API.
77 
78   Revision 1.1  2007/03/21 18:06:02  carlmu
79   Initial version.
80 
81   $NoKeywords: $
82  *---------------------------------------------------------------------------*/
83 
84 #ifndef __KBD_H__
85 #define __KBD_H__
86 
87 #include <revolution/types.h>
88 #include <revolution/kbd/kbd_key_defs.h>
89 #include <revolution/kbd/kbd_hid_codes.h>
90 
91 #ifdef __cplusplus
92 extern "C" {
93 #endif
94 
95 #define KBD_MEM_SIZE    3264
96 
97 // Low-level key press API
98 
99 //-----------------------------------------------------------------------------
100 // Types:
101 
102 // Up to 4 keyboards can be attached
103 #define KBD_MAX_CHANNELS       (4)   // valid channel numbers are 0-3
104 
105 typedef enum _KBDEc {                // function return code
106   KBD_SUCCESS                 = 0,
107   KBD_ERR_OTHER               = 1,   // usually from HID error
108   KBD_ERR_NOT_INITIALIZED     = 2,
109   KBD_ERR_ALREADY_INITIALIZED = 3,
110   KBD_ERR_BAD_VALUE           = 4,   // input argument out of range
111   KBD_ERR_BAD_STATUS          = 5,   // ie, keyboard disconnected
112 //  KBD_ERR_BAD_POINTER         = 6,
113   KBD_ERR_BUSY                = 7    // for KBDSetLeds
114 } KBDEc;
115 
116 typedef enum _KBDChanStatus { // status bits may be OR-ed together
117   KBD_CS_OK           = 0x00,
118   KBD_CS_DISCONNECTED = 0x01,
119   KBD_CS_ROLL_OVER    = 0x02,
120   KBD_CS_ERROR        = 0x04
121 } KBDChanStatus;
122 
123 typedef u8 KBDChannel;
124 typedef u8 KBDHIDCode;
125 
126 #define KBD_HID_NONE       0 // value returned when queue is empty
127 #define KBD_HID_OVERFLOW 255 // value returned when queue overflows
128 
129 typedef enum _KBDKeyMode {
130   KBD_KM_DOWN   = 0x01,    // on=key down;             off=key up
131   KBD_KM_REPEAT = 0x02,    // on=repeat key;           off=initial key press
132   KBD_KM_NULL   = 0x00
133 } KBDKeyMode;
134 
135 #define KBD_KEY_MODE_UP(_key_mode)     (!((_key_mode) & KBD_KM_DOWN))
136 #define KBD_KEY_MODE_DOWN(_key_mode)   ((_key_mode) & KBD_KM_DOWN)
137 #define KBD_KEY_MODE_REPEAT(_key_mode) ((_key_mode) & KBD_KM_REPEAT)
138 
139 // xxx Some of these countries may disappear from this list.
140 //     Others may be added.  Names may be changed.
141 
142 typedef enum _KBDCountryCode {
143   KBD_CC_INTERNATIONAL,
144   KBD_CC_CANADIAN_BI,
145   KBD_CC_CANADIAN_FR,
146   KBD_CC_DANISH,
147   KBD_CC_FINNISH,
148   KBD_CC_FRENCH,
149   KBD_CC_GERMAN,
150   KBD_CC_GREEK,
151   KBD_CC_ITALIAN,
152   KBD_CC_JAPANESE,
153   KBD_CC_LATIN_AMERICAN,
154   KBD_CC_NETHERLANDS_DUTCH,
155   KBD_CC_NORWEGIAN,
156   KBD_CC_PORTUGUESE,
157   KBD_CC_SPANISH,
158   KBD_CC_SWEDISH,
159   KBD_CC_UNITED_KINGDOM,
160   KBD_CC_UNITED_STATES,
161   KBD_CC_RESERVED
162 } KBDCountryCode;
163 
164 #define KBD_NUM_COUNTRY_CODES  KBD_CC_RESERVED
165 
166 typedef enum _KBDModState {   // state bits may be OR-ed together
167   KBD_MS_CTRL        = 0x0001,
168   KBD_MS_SHIFT       = 0x0002,
169   KBD_MS_ALT         = 0x0004,
170   KBD_MS_GUI         = 0x0008,
171   KBD_MS_EXTRA       = 0x0010,
172   KBD_MS_ALTGR       = 0x0020,
173   KBD_MS_LANG1       = 0x0040, // (Hiragana)
174   KBD_MS_LANG2       = 0x0080, // (Katakana)
175   KBD_MS_NUM_LOCK    = 0x0100,
176   KBD_MS_CAPS_LOCK   = 0x0200,
177   KBD_MS_SCROLL_LOCK = 0x0400,
178   KBD_MS_SHIFTED_KEY = 0x0800, // when CTRL/ALT/GUI/EXTRA is on, allow shifted key to be returned
179                                // (the default is that the base/unshifted key is returned)
180   KBD_MS_SET_ALL     = 0x1000, // With KBDSetModState, allows setting of all bits
181   KBD_MS_NULL        = 0x0000
182 } KBDModState;
183 
184 // define alternate names for these
185 #define KBD_MS_HIRAGANA KBD_MS_LANG1
186 #define KBD_MS_KATAKANA KBD_MS_LANG2
187 
188 // define convenient groups of state
189 #define KBD_MS_TRANSIENTS (KBD_MS_CTRL|KBD_MS_SHIFT|KBD_MS_ALT|KBD_MS_GUI|KBD_MS_EXTRA|KBD_MS_ALTGR)
190 #define KBD_MS_TOGGLES (KBD_MS_LANG1|KBD_MS_LANG2|KBD_MS_NUM_LOCK|KBD_MS_CAPS_LOCK|KBD_MS_SCROLL_LOCK)
191 
192 typedef u16 KBDUnicode; // should it be wchar_t? xxx
193 
194 // Indicate if a KBDUnicode value is private to KBD (special KBD internal value)
195 #define KBD_UC_IS_PRIVATE(uc) (((uc)>=0xf000 && (uc)<=0xF1FF) || ((uc)==0xFFFF))
196 
197 // This macro may be used to determine if a KBDUnicode is a modifier key
198 #define KBD_UC_IS_MODIFIER(uc) ((uc)>=0xf000 && (uc)<=0xf01f)
199 
200 // These defines may be used to determine if a KBDUnicode
201 // value is a regular ASCII key from the keypad, and if so, to
202 // convert that value to the regular ASCII value
203 #define KBD_UC_IS_KP_REG_KEY(uc) (((uc)>=0xf100) && ((uc)<=0xf13f))
204 #define KBD_KP_REG_KEY_TO_ASCII(uc) ((uc)&0x3f)
205 
206 // Indicate if a key is a keypad number (digit) key with NumLock on
207 #define KBD_UC_IS_KP_NUM_NL_KEY(uc) (((uc)>=KBK_Keypad_0 && ((uc)<=KBK_Keypad_9)))
208 // Indicate if a key is a keypad number (digit) key with NumLock off
209 #define KBD_UC_IS_KP_NUM_UL_KEY(uc) (((uc)>=KBK_Keypad_Insert && ((uc)<=KBK_Keypad_Page_Up)))
210 // Convert from NumLock off digit key to NumLock on digit key
211 #define KBD_KP_NUM_UL_KEY_TO_KP_NUM_NL_KEY(uc) ((KBDUnicode)((uc)-0x40))
212 
213 // Indicate if a ModState represents NumLock == on
214 #define KBD_MS_IS_NUMLOCK(ms) (((ms)&KBD_MS_NUM_LOCK) && !((ms)&KBD_MS_SHIFT))
215 
216 // Indicate if a key is a private control Unicode, and convert to ASCII
217 #define KBD_UC_IS_CTRL_KEY(uc)  (((uc)>=0xf1c0) && ((uc)<=0xf1df))
218 #define KBD_CTRL_KEY_TO_ASCII(uc) ((uc)&0x1f)
219 
220 typedef enum _KBDLedState {
221   KBD_LED_NUM_LOCK    = 0x01,
222   KBD_LED_CAPS_LOCK   = 0x02,
223   KBD_LED_SCROLL_LOCK = 0x04,
224   KBD_LED_NULL        = 0x00,
225   KBD_LED_RESERVED    = 0x10
226 } KBDLedState;
227 
228 //-----------------------------------------------------------------------------
229 // Structs:
230 
231 typedef struct _KBDDevEvent {                // kbd attach/detach callbacks
232   KBDChannel channel;
233 } KBDDevEvent;
234 
235 typedef struct _KBDKeyEvent {            // for key callback/getkey
236   KBDChannel  channel;
237   KBDHIDCode  hid;        // USB HID code
238   KBDKeyMode  mode;       // for up/down/etc
239   KBDModState modState;   // modifier state
240   KBDUnicode  unicode;    // unicode, if any
241 } KBDKeyEvent;
242 
243 typedef struct _KBDLedEvent {                // kbd LED callback
244   KBDChannel  channel;
245   KBDLedState leds;
246   KBDEc       rc;
247 } KBDLedEvent;
248 
249 typedef void (*KBDDevCallbackF) (KBDDevEvent *ev);
250 typedef void (*KBDKeyCallbackF) (KBDKeyEvent *ev);
251 typedef void (*KBDLedCallbackF) (KBDLedEvent *ev, void *cbArg);
252 
253 //-----------------------------------------------------------------------------
254 // Function calls
255 
256 // One of these MUST be called before KBDInit:
257 void  KBDInitRegionUS(void);
258 void  KBDInitRegionJP(void);
259 void  KBDInitRegionEU(void);
260 
261 KBDEc KBDInit (void *kbd_mem, KBDDevCallbackF attach_cb, KBDDevCallbackF detach_cb, KBDKeyCallbackF key_cb);  // init library
262 KBDEc KBDExit (void);  // terminate library
263 
264 KBDDevCallbackF KBDSetAttachCallback (KBDDevCallbackF fn); // set kbd attach callback
265 KBDDevCallbackF KBDSetDetachCallback (KBDDevCallbackF fn); // set kbd detach callback
266 
267 KBDEc KBDGetChannelStatus (KBDChannel ch, KBDChanStatus *chanStatus);
268 KBDEc KBDResetChannel (KBDChannel ch);                        // reset key press state
269 
270 KBDEc KBDSetCountry (KBDChannel ch, KBDCountryCode country);  // set country
271 KBDEc KBDGetCountry (KBDChannel ch, KBDCountryCode *country); // get country
272 
273 KBDKeyCallbackF KBDSetKeyCallback (KBDKeyCallbackF fn);  // set key callback
274 KBDEc KBDGetKey(KBDChannel ch, KBDKeyEvent *keyEvent);        // synch key API
275 
276 KBDEc KBDSetLockProcessing(KBDChannel ch, BOOL  enable);
277 KBDEc KBDGetLockProcessing(KBDChannel ch, BOOL *enable);
278 
279 KBDEc KBDSetModState(KBDChannel ch, KBDModState  modState);
280 KBDEc KBDGetModState(KBDChannel ch, KBDModState *modState);
281 
282 KBDUnicode KBDTranslateHidCode(KBDHIDCode hid, KBDModState modState, KBDCountryCode country);
283 
284 KBDEc KBDSetRepeat(KBDChannel ch, u16  delay, u16  interval);
285 KBDEc KBDGetRepeat(KBDChannel ch, u16 *delay, u16 *interval);
286 
287 KBDEc KBDSetAccessSticky(KBDChannel, BOOL  enable);
288 KBDEc KBDGetAccessSticky(KBDChannel, BOOL *enable);
289 
290 KBDEc KBDSetLeds(KBDChannel ch, KBDLedState  leds);
291 KBDEc KBDSetLedsAsync(KBDChannel ch, KBDLedState  leds, KBDLedCallbackF fn, void *cbArg);
292 KBDEc KBDSetLedsRetry(KBDChannel ch, KBDLedState  leds);
293 
294 #ifdef USE_PPC_HID
295 // Temporary test function
296 void KBDSetHidMem(u8 *ptr, u32 size);
297 #endif
298 
299 #ifdef __cplusplus
300 }
301 #endif
302 
303 #endif // __KBD_H__
304