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