USB: Short new 'graph for usb-serial.txt
[linux-2.6.git] / Documentation / usb / gadget_hid.txt
1
2                      Linux USB HID gadget driver
3
4 Introduction
5
6         The HID Gadget driver provides emulation of USB Human Interface
7         Devices (HID). The basic HID handling is done in the kernel,
8         and HID reports can be sent/received through I/O on the
9         /dev/hidgX character devices.
10
11         For more details about HID, see the developer page on
12         http://www.usb.org/developers/hidpage/
13
14 Configuration
15
16         g_hid is a platform driver, so to use it you need to add
17         struct platform_device(s) to your platform code defining the
18         HID function descriptors you want to use - E.G. something
19         like:
20
21 #include <linux/platform_device.h>
22 #include <linux/usb/g_hid.h>
23
24 /* hid descriptor for a keyboard */
25 static struct hidg_func_descriptor my_hid_data = {
26         .subclass               = 0, /* No subclass */
27         .protocol               = 1, /* Keyboard */
28         .report_length          = 8,
29         .report_desc_length     = 63,
30         .report_desc            = {
31                 0x05, 0x01,     /* USAGE_PAGE (Generic Desktop)           */
32                 0x09, 0x06,     /* USAGE (Keyboard)                       */
33                 0xa1, 0x01,     /* COLLECTION (Application)               */
34                 0x05, 0x07,     /*   USAGE_PAGE (Keyboard)                */
35                 0x19, 0xe0,     /*   USAGE_MINIMUM (Keyboard LeftControl) */
36                 0x29, 0xe7,     /*   USAGE_MAXIMUM (Keyboard Right GUI)   */
37                 0x15, 0x00,     /*   LOGICAL_MINIMUM (0)                  */
38                 0x25, 0x01,     /*   LOGICAL_MAXIMUM (1)                  */
39                 0x75, 0x01,     /*   REPORT_SIZE (1)                      */
40                 0x95, 0x08,     /*   REPORT_COUNT (8)                     */
41                 0x81, 0x02,     /*   INPUT (Data,Var,Abs)                 */
42                 0x95, 0x01,     /*   REPORT_COUNT (1)                     */
43                 0x75, 0x08,     /*   REPORT_SIZE (8)                      */
44                 0x81, 0x03,     /*   INPUT (Cnst,Var,Abs)                 */
45                 0x95, 0x05,     /*   REPORT_COUNT (5)                     */
46                 0x75, 0x01,     /*   REPORT_SIZE (1)                      */
47                 0x05, 0x08,     /*   USAGE_PAGE (LEDs)                    */
48                 0x19, 0x01,     /*   USAGE_MINIMUM (Num Lock)             */
49                 0x29, 0x05,     /*   USAGE_MAXIMUM (Kana)                 */
50                 0x91, 0x02,     /*   OUTPUT (Data,Var,Abs)                */
51                 0x95, 0x01,     /*   REPORT_COUNT (1)                     */
52                 0x75, 0x03,     /*   REPORT_SIZE (3)                      */
53                 0x91, 0x03,     /*   OUTPUT (Cnst,Var,Abs)                */
54                 0x95, 0x06,     /*   REPORT_COUNT (6)                     */
55                 0x75, 0x08,     /*   REPORT_SIZE (8)                      */
56                 0x15, 0x00,     /*   LOGICAL_MINIMUM (0)                  */
57                 0x25, 0x65,     /*   LOGICAL_MAXIMUM (101)                */
58                 0x05, 0x07,     /*   USAGE_PAGE (Keyboard)                */
59                 0x19, 0x00,     /*   USAGE_MINIMUM (Reserved)             */
60                 0x29, 0x65,     /*   USAGE_MAXIMUM (Keyboard Application) */
61                 0x81, 0x00,     /*   INPUT (Data,Ary,Abs)                 */
62                 0xc0            /* END_COLLECTION                         */
63         }
64 };
65
66 static struct platform_device my_hid = {
67         .name                   = "hidg",
68         .id                     = 0,
69         .num_resources          = 0,
70         .resource               = 0,
71         .dev.platform_data      = &my_hid_data,
72 };
73
74         You can add as many HID functions as you want, only limited by
75         the amount of interrupt endpoints your gadget driver supports.
76
77 Send and receive HID reports
78
79         HID reports can be sent/received using read/write on the
80         /dev/hidgX character devices. See below for an example program
81         to do this.
82
83         hid_gadget_test is a small interactive program to test the HID
84         gadget driver. To use, point it at a hidg device and set the
85         device type (keyboard / mouse / joystick) - E.G.:
86
87                 # hid_gadget_test /dev/hidg0 keyboard
88
89         You are now in the prompt of hid_gadget_test. You can type any
90         combination of options and values. Available options and
91         values are listed at program start. In keyboard mode you can
92         send up to six values.
93
94         For example type: g i s t r --left-shift
95
96         Hit return and the corresponding report will be sent by the
97         HID gadget.
98
99         Another interesting example is the caps lock test. Type
100         -–caps-lock and hit return. A report is then sent by the
101         gadget and you should receive the host answer, corresponding
102         to the caps lock LED status.
103
104                 --caps-lock
105                 recv report:2
106
107         With this command:
108
109                 # hid_gadget_test /dev/hidg1 mouse
110
111         You can test the mouse emulation. Values are two signed numbers.
112
113
114 Sample code
115
116 /* hid_gadget_test */
117
118 #include <pthread.h>
119 #include <string.h>
120 #include <stdio.h>
121 #include <ctype.h>
122 #include <fcntl.h>
123 #include <errno.h>
124 #include <stdio.h>
125 #include <stdlib.h>
126 #include <unistd.h>
127
128 #define BUF_LEN 512
129
130 struct options {
131         const char    *opt;
132         unsigned char val;
133 };
134
135 static struct options kmod[] = {
136         {.opt = "--left-ctrl",          .val = 0x01},
137         {.opt = "--right-ctrl",         .val = 0x10},
138         {.opt = "--left-shift",         .val = 0x02},
139         {.opt = "--right-shift",        .val = 0x20},
140         {.opt = "--left-alt",           .val = 0x04},
141         {.opt = "--right-alt",          .val = 0x40},
142         {.opt = "--left-meta",          .val = 0x08},
143         {.opt = "--right-meta",         .val = 0x80},
144         {.opt = NULL}
145 };
146
147 static struct options kval[] = {
148         {.opt = "--return",     .val = 0x28},
149         {.opt = "--esc",        .val = 0x29},
150         {.opt = "--bckspc",     .val = 0x2a},
151         {.opt = "--tab",        .val = 0x2b},
152         {.opt = "--spacebar",   .val = 0x2c},
153         {.opt = "--caps-lock",  .val = 0x39},
154         {.opt = "--f1",         .val = 0x3a},
155         {.opt = "--f2",         .val = 0x3b},
156         {.opt = "--f3",         .val = 0x3c},
157         {.opt = "--f4",         .val = 0x3d},
158         {.opt = "--f5",         .val = 0x3e},
159         {.opt = "--f6",         .val = 0x3f},
160         {.opt = "--f7",         .val = 0x40},
161         {.opt = "--f8",         .val = 0x41},
162         {.opt = "--f9",         .val = 0x42},
163         {.opt = "--f10",        .val = 0x43},
164         {.opt = "--f11",        .val = 0x44},
165         {.opt = "--f12",        .val = 0x45},
166         {.opt = "--insert",     .val = 0x49},
167         {.opt = "--home",       .val = 0x4a},
168         {.opt = "--pageup",     .val = 0x4b},
169         {.opt = "--del",        .val = 0x4c},
170         {.opt = "--end",        .val = 0x4d},
171         {.opt = "--pagedown",   .val = 0x4e},
172         {.opt = "--right",      .val = 0x4f},
173         {.opt = "--left",       .val = 0x50},
174         {.opt = "--down",       .val = 0x51},
175         {.opt = "--kp-enter",   .val = 0x58},
176         {.opt = "--up",         .val = 0x52},
177         {.opt = "--num-lock",   .val = 0x53},
178         {.opt = NULL}
179 };
180
181 int keyboard_fill_report(char report[8], char buf[BUF_LEN], int *hold)
182 {
183         char *tok = strtok(buf, " ");
184         int key = 0;
185         int i = 0;
186
187         for (; tok != NULL; tok = strtok(NULL, " ")) {
188
189                 if (strcmp(tok, "--quit") == 0)
190                         return -1;
191
192                 if (strcmp(tok, "--hold") == 0) {
193                         *hold = 1;
194                         continue;
195                 }
196
197                 if (key < 6) {
198                         for (i = 0; kval[i].opt != NULL; i++)
199                                 if (strcmp(tok, kval[i].opt) == 0) {
200                                         report[2 + key++] = kval[i].val;
201                                         break;
202                                 }
203                         if (kval[i].opt != NULL)
204                                 continue;
205                 }
206
207                 if (key < 6)
208                         if (islower(tok[0])) {
209                                 report[2 + key++] = (tok[0] - ('a' - 0x04));
210                                 continue;
211                         }
212
213                 for (i = 0; kmod[i].opt != NULL; i++)
214                         if (strcmp(tok, kmod[i].opt) == 0) {
215                                 report[0] = report[0] | kmod[i].val;
216                                 break;
217                         }
218                 if (kmod[i].opt != NULL)
219                         continue;
220
221                 if (key < 6)
222                         fprintf(stderr, "unknown option: %s\n", tok);
223         }
224         return 8;
225 }
226
227 static struct options mmod[] = {
228         {.opt = "--b1", .val = 0x01},
229         {.opt = "--b2", .val = 0x02},
230         {.opt = "--b3", .val = 0x04},
231         {.opt = NULL}
232 };
233
234 int mouse_fill_report(char report[8], char buf[BUF_LEN], int *hold)
235 {
236         char *tok = strtok(buf, " ");
237         int mvt = 0;
238         int i = 0;
239         for (; tok != NULL; tok = strtok(NULL, " ")) {
240
241                 if (strcmp(tok, "--quit") == 0)
242                         return -1;
243
244                 if (strcmp(tok, "--hold") == 0) {
245                         *hold = 1;
246                         continue;
247                 }
248
249                 for (i = 0; mmod[i].opt != NULL; i++)
250                         if (strcmp(tok, mmod[i].opt) == 0) {
251                                 report[0] = report[0] | mmod[i].val;
252                                 break;
253                         }
254                 if (mmod[i].opt != NULL)
255                         continue;
256
257                 if (!(tok[0] == '-' && tok[1] == '-') && mvt < 2) {
258                         errno = 0;
259                         report[1 + mvt++] = (char)strtol(tok, NULL, 0);
260                         if (errno != 0) {
261                                 fprintf(stderr, "Bad value:'%s'\n", tok);
262                                 report[1 + mvt--] = 0;
263                         }
264                         continue;
265                 }
266
267                 fprintf(stderr, "unknown option: %s\n", tok);
268         }
269         return 3;
270 }
271
272 static struct options jmod[] = {
273         {.opt = "--b1",         .val = 0x10},
274         {.opt = "--b2",         .val = 0x20},
275         {.opt = "--b3",         .val = 0x40},
276         {.opt = "--b4",         .val = 0x80},
277         {.opt = "--hat1",       .val = 0x00},
278         {.opt = "--hat2",       .val = 0x01},
279         {.opt = "--hat3",       .val = 0x02},
280         {.opt = "--hat4",       .val = 0x03},
281         {.opt = "--hatneutral", .val = 0x04},
282         {.opt = NULL}
283 };
284
285 int joystick_fill_report(char report[8], char buf[BUF_LEN], int *hold)
286 {
287         char *tok = strtok(buf, " ");
288         int mvt = 0;
289         int i = 0;
290
291         *hold = 1;
292
293         /* set default hat position: neutral */
294         report[3] = 0x04;
295
296         for (; tok != NULL; tok = strtok(NULL, " ")) {
297
298                 if (strcmp(tok, "--quit") == 0)
299                         return -1;
300
301                 for (i = 0; jmod[i].opt != NULL; i++)
302                         if (strcmp(tok, jmod[i].opt) == 0) {
303                                 report[3] = (report[3] & 0xF0) | jmod[i].val;
304                                 break;
305                         }
306                 if (jmod[i].opt != NULL)
307                         continue;
308
309                 if (!(tok[0] == '-' && tok[1] == '-') && mvt < 3) {
310                         errno = 0;
311                         report[mvt++] = (char)strtol(tok, NULL, 0);
312                         if (errno != 0) {
313                                 fprintf(stderr, "Bad value:'%s'\n", tok);
314                                 report[mvt--] = 0;
315                         }
316                         continue;
317                 }
318
319                 fprintf(stderr, "unknown option: %s\n", tok);
320         }
321         return 4;
322 }
323
324 void print_options(char c)
325 {
326         int i = 0;
327
328         if (c == 'k') {
329                 printf("        keyboard options:\n"
330                        "                --hold\n");
331                 for (i = 0; kmod[i].opt != NULL; i++)
332                         printf("\t\t%s\n", kmod[i].opt);
333                 printf("\n      keyboard values:\n"
334                        "                [a-z] or\n");
335                 for (i = 0; kval[i].opt != NULL; i++)
336                         printf("\t\t%-8s%s", kval[i].opt, i % 2 ? "\n" : "");
337                 printf("\n");
338         } else if (c == 'm') {
339                 printf("        mouse options:\n"
340                        "                --hold\n");
341                 for (i = 0; mmod[i].opt != NULL; i++)
342                         printf("\t\t%s\n", mmod[i].opt);
343                 printf("\n      mouse values:\n"
344                        "                Two signed numbers\n"
345                        "--quit to close\n");
346         } else {
347                 printf("        joystick options:\n");
348                 for (i = 0; jmod[i].opt != NULL; i++)
349                         printf("\t\t%s\n", jmod[i].opt);
350                 printf("\n      joystick values:\n"
351                        "                three signed numbers\n"
352                        "--quit to close\n");
353         }
354 }
355
356 int main(int argc, const char *argv[])
357 {
358         const char *filename = NULL;
359         int fd = 0;
360         char buf[BUF_LEN];
361         int cmd_len;
362         char report[8];
363         int to_send = 8;
364         int hold = 0;
365         fd_set rfds;
366         int retval, i;
367
368         if (argc < 3) {
369                 fprintf(stderr, "Usage: %s devname mouse|keyboard|joystick\n",
370                         argv[0]);
371                 return 1;
372         }
373
374         if (argv[2][0] != 'k' && argv[2][0] != 'm' && argv[2][0] != 'j')
375           return 2;
376
377         filename = argv[1];
378
379         if ((fd = open(filename, O_RDWR, 0666)) == -1) {
380                 perror(filename);
381                 return 3;
382         }
383
384         print_options(argv[2][0]);
385
386         while (42) {
387
388                 FD_ZERO(&rfds);
389                 FD_SET(STDIN_FILENO, &rfds);
390                 FD_SET(fd, &rfds);
391
392                 retval = select(fd + 1, &rfds, NULL, NULL, NULL);
393                 if (retval == -1 && errno == EINTR)
394                         continue;
395                 if (retval < 0) {
396                         perror("select()");
397                         return 4;
398                 }
399
400                 if (FD_ISSET(fd, &rfds)) {
401                         cmd_len = read(fd, buf, BUF_LEN - 1);
402                         printf("recv report:");
403                         for (i = 0; i < cmd_len; i++)
404                                 printf(" %02x", buf[i]);
405                         printf("\n");
406                 }
407
408                 if (FD_ISSET(STDIN_FILENO, &rfds)) {
409                         memset(report, 0x0, sizeof(report));
410                         cmd_len = read(STDIN_FILENO, buf, BUF_LEN - 1);
411
412                         if (cmd_len == 0)
413                                 break;
414
415                         buf[cmd_len - 1] = '\0';
416                         hold = 0;
417
418                         memset(report, 0x0, sizeof(report));
419                         if (argv[2][0] == 'k')
420                                 to_send = keyboard_fill_report(report, buf, &hold);
421                         else if (argv[2][0] == 'm')
422                                 to_send = mouse_fill_report(report, buf, &hold);
423                         else
424                                 to_send = joystick_fill_report(report, buf, &hold);
425
426                         if (to_send == -1)
427                                 break;
428
429                         if (write(fd, report, to_send) != to_send) {
430                                 perror(filename);
431                                 return 5;
432                         }
433                         if (!hold) {
434                                 memset(report, 0x0, sizeof(report));
435                                 if (write(fd, report, to_send) != to_send) {
436                                         perror(filename);
437                                         return 6;
438                                 }
439                         }
440                 }
441         }
442
443         close(fd);
444         return 0;
445 }