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