aboutsummaryrefslogtreecommitdiff
path: root/lib/chibios-contrib/os/hal/include/hal_usb_hid.h
diff options
context:
space:
mode:
Diffstat (limited to 'lib/chibios-contrib/os/hal/include/hal_usb_hid.h')
-rw-r--r--lib/chibios-contrib/os/hal/include/hal_usb_hid.h571
1 files changed, 571 insertions, 0 deletions
diff --git a/lib/chibios-contrib/os/hal/include/hal_usb_hid.h b/lib/chibios-contrib/os/hal/include/hal_usb_hid.h
new file mode 100644
index 000000000..7698a083e
--- /dev/null
+++ b/lib/chibios-contrib/os/hal/include/hal_usb_hid.h
@@ -0,0 +1,571 @@
1/*
2 ChibiOS - Copyright (C) 2016 Jonathan Struebel
3
4 Licensed under the Apache License, Version 2.0 (the "License");
5 you may not use this file except in compliance with the License.
6 You may obtain a copy of the License at
7
8 http://www.apache.org/licenses/LICENSE-2.0
9
10 Unless required by applicable law or agreed to in writing, software
11 distributed under the License is distributed on an "AS IS" BASIS,
12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 See the License for the specific language governing permissions and
14 limitations under the License.
15*/
16
17/**
18 * @file hal_usb_hid.h
19 * @brief USB HID macros and structures.
20 *
21 * @addtogroup USB_HID
22 * @{
23 */
24
25#ifndef HAL_USB_HID_H
26#define HAL_USB_HID_H
27
28#if (HAL_USE_USB_HID == TRUE) || defined(__DOXYGEN__)
29
30/*===========================================================================*/
31/* Driver constants. */
32/*===========================================================================*/
33
34/**
35 * @name HID specific messages.
36 * @{
37 */
38#define HID_GET_REPORT 0x01U
39#define HID_GET_IDLE 0x02U
40#define HID_GET_PROTOCOL 0x03U
41#define HID_SET_REPORT 0x09U
42#define HID_SET_IDLE 0x0AU
43#define HID_SET_PROTOCOL 0x0BU
44/** @} */
45
46/**
47 * @name HID classes
48 * @{
49 */
50#define HID_INTERFACE_CLASS 0x03U
51/** @} */
52
53/**
54 * @name HID subclasses
55 * @{
56 */
57#define HID_BOOT_INTERFACE 0x01U
58/** @} */
59
60/**
61 * @name HID descriptors
62 * @{
63 */
64#define USB_DESCRIPTOR_HID 0x21U
65#define HID_REPORT 0x22U
66#define HID_PHYSICAL 0x23U
67/** @} */
68
69/**
70 * @name HID Report items
71 * @{
72 */
73#define HID_REPORT_INPUT 0x80
74#define HID_REPORT_OUTPUT 0x90
75#define HID_REPORT_COLLECTION 0xA0
76#define HID_REPORT_FEATURE 0xB0
77#define HID_REPORT_END_COLLECTION 0xC0
78
79#define HID_REPORT_USAGE_PAGE 0x04
80#define HID_REPORT_LOGICAL_MINIMUM 0x14
81#define HID_REPORT_LOGICAL_MAXIMUM 0x24
82#define HID_REPORT_PHYSICAL_MINIMUM 0x34
83#define HID_REPORT_PHYSICAL_MAXIMUM 0x44
84#define HID_REPORT_UNIT_EXPONENT 0x54
85#define HID_REPORT_UNIT 0x64
86#define HID_REPORT_REPORT_SIZE 0x74
87#define HID_REPORT_REPORT_ID 0x84
88#define HID_REPORT_REPORT_COUNT 0x94
89#define HID_REPORT_REPORT_PUSH 0xA4
90#define HID_REPORT_REPORT_POP 0xB4
91
92#define HID_REPORT_USAGE 0x08
93#define HID_REPORT_USAGE_MINIMUM 0x18
94#define HID_REPORT_USAGE_MAXIMUM 0x28
95#define HID_REPORT_DESIGNATOR_INDEX 0x38
96#define HID_REPORT_DESIGNATOR_MINUMUM 0x48
97#define HID_REPORT_DESIGNATOR_MAXIMUM 0x58
98#define HID_REPORT_STRING_INDEX 0x78
99#define HID_REPORT_STRING_MINUMUM 0x88
100#define HID_REPORT_STRING_MAXIMUM 0x98
101#define HID_REPORT_DELIMITER 0xA8
102/** @} */
103
104/**
105 * @name HID Collection item definitions
106 * @{
107 */
108#define HID_COLLECTION_PHYSICAL 0x00
109#define HID_COLLECTION_APPLICATION 0x01
110#define HID_COLLECTION_LOGICAL 0x02
111#define HID_COLLECTION_REPORT 0x03
112#define HID_COLLECTION_NAMED_ARRAY 0x04
113#define HID_COLLECTION_USAGE_SWITCH 0x05
114#define HID_COLLECTION_USAGE_MODIFIER 0x06
115/** @} */
116
117/**
118 * @name HID Usage Page item definitions
119 * @{
120 */
121#define HID_USAGE_PAGE_GENERIC_DESKTOP 0x01
122#define HID_USAGE_PAGE_SIMULATION 0x02
123#define HID_USAGE_PAGE_VR 0x03
124#define HID_USAGE_PAGE_SPORT 0x04
125#define HID_USAGE_PAGE_GAME 0x05
126#define HID_USAGE_PAGE_GENERIC_DEVICE 0x06
127#define HID_USAGE_PAGE_KEYBOARD_KEYPAD 0x07
128#define HID_USAGE_PAGE_LEDS 0x08
129#define HID_USAGE_PAGE_BUTTON 0x09
130#define HID_USAGE_PAGE_ORDINAL 0x0A
131#define HID_USAGE_PAGE_TELEPHONY 0x0B
132#define HID_USAGE_PAGE_CONSUMER 0x0C
133#define HID_USAGE_PAGE_DIGITIZER 0x0D
134#define HID_USAGE_PAGE_PID 0x0F
135#define HID_USAGE_PAGE_UNICODE 0x10
136#define HID_USAGE_PAGE_VENDOR 0xFF00
137/** @} */
138
139/**
140 * @name HID Usage item definitions
141 * @{
142 */
143#define HID_USAGE_ALPHANUMERIC_DISPLAY 0x14
144#define HID_USAGE_MEDICAL_INSTRUMENTS 0x40
145#define HID_USAGE_MONITOR_PAGE1 0x80
146#define HID_USAGE_MONITOR_PAGE2 0x81
147#define HID_USAGE_MONITOR_PAGE3 0x82
148#define HID_USAGE_MONITOR_PAGE4 0x83
149#define HID_USAGE_POWER_PAGE1 0x84
150#define HID_USAGE_POWER_PAGE2 0x85
151#define HID_USAGE_POWER_PAGE3 0x86
152#define HID_USAGE_POWER_PAGE4 0x87
153#define HID_USAGE_BAR_CODE_SCANNER_PAGE 0x8C
154#define HID_USAGE_SCALE_PAGE 0x8D
155#define HID_USAGE_MSR_PAGE 0x8E
156#define HID_USAGE_CAMERA_PAGE 0x90
157#define HID_USAGE_ARCADE_PAGE 0x91
158
159#define HID_USAGE_POINTER 0x01
160#define HID_USAGE_MOUSE 0x02
161#define HID_USAGE_JOYSTICK 0x04
162#define HID_USAGE_GAMEPAD 0x05
163#define HID_USAGE_KEYBOARD 0x06
164#define HID_USAGE_KEYPAD 0x07
165#define HID_USAGE_MULTIAXIS_CONTROLLER 0x08
166
167#define HID_USAGE_BUTTON1 0x01
168#define HID_USAGE_BUTTON2 0x02
169#define HID_USAGE_BUTTON3 0x03
170#define HID_USAGE_BUTTON4 0x04
171#define HID_USAGE_BUTTON5 0x05
172#define HID_USAGE_BUTTON6 0x06
173#define HID_USAGE_BUTTON7 0x07
174#define HID_USAGE_BUTTON8 0x08
175
176#define HID_USAGE_X 0x30
177#define HID_USAGE_Y 0x31
178#define HID_USAGE_Z 0x32
179#define HID_USAGE_RX 0x33
180#define HID_USAGE_RY 0x34
181#define HID_USAGE_RZ 0x35
182#define HID_USAGE_VX 0x40
183#define HID_USAGE_VY 0x41
184#define HID_USAGE_VZ 0x42
185#define HID_USAGE_VBRX 0x43
186#define HID_USAGE_VBRY 0x44
187#define HID_USAGE_VBRZ 0x45
188#define HID_USAGE_VNO 0x46
189/** @} */
190
191/**
192 * @name HID item types definitions
193 * @{
194 */
195#define HID_ITEM_DATA 0x00
196#define HID_ITEM_CNST 0x01
197#define HID_ITEM_ARR 0x00
198#define HID_ITEM_VAR 0x02
199#define HID_ITEM_ABS 0x00
200#define HID_ITEM_REL 0x04
201#define HID_ITEM_NWRP 0x00
202#define HID_ITEM_WRP 0x08
203#define HID_ITEM_LIN 0x00
204#define HID_ITEM_NLIN 0x10
205#define HID_ITEM_PRF 0x00
206#define HID_ITEM_NPRF 0x20
207#define HID_ITEM_NNUL 0x00
208#define HID_ITEM_NUL 0x40
209#define HID_ITEM_NVOL 0x00
210#define HID_ITEM_VOL 0x80
211
212#define HID_ITEM_DATA_VAR_ABS (HID_ITEM_DATA | \
213 HID_ITEM_VAR | \
214 HID_ITEM_ABS)
215#define HID_ITEM_CNST_VAR_ABS (HID_ITEM_CNST | \
216 HID_ITEM_VAR | \
217 HID_ITEM_ABS)
218#define HID_ITEM_DATA_VAR_REL (HID_ITEM_DATA | \
219 HID_ITEM_VAR | \
220 HID_ITEM_REL)
221/** @} */
222
223/**
224 * @name Helper macros for USB HID descriptors
225 * @{
226 */
227/*
228 * @define HID Descriptor size.
229 */
230#define USB_DESC_HID_SIZE 9U
231
232/**
233 * @brief HID Descriptor helper macro.
234 * @note This macro can only be used with a single HID report descriptor
235 */
236#define USB_DESC_HID(bcdHID, bCountryCode, bNumDescriptors, \
237 bDescriptorType, wDescriptorLength) \
238 USB_DESC_BYTE(USB_DESC_HID_SIZE), \
239 USB_DESC_BYTE(USB_DESCRIPTOR_HID), \
240 USB_DESC_BCD(bcdHID), \
241 USB_DESC_BYTE(bCountryCode), \
242 USB_DESC_BYTE(bNumDescriptors), \
243 USB_DESC_BYTE(bDescriptorType), \
244 USB_DESC_WORD(wDescriptorLength)
245
246/**
247 * @brief HID Report item helper macro (Single byte).
248 */
249#define HID_ITEM_B(id, value) \
250 USB_DESC_BYTE(id | 0x01), \
251 USB_DESC_BYTE(value)
252
253/**
254 * @brief HID Report item helper macro (Double byte).
255 */
256#define HID_ITEM_W(id, value) \
257 USB_DESC_BYTE(id | 0x02), \
258 USB_DESC_WORD(value)
259
260/**
261 * @brief HID Report Usage Page item helper macro (Single byte).
262 */
263#define HID_USAGE_PAGE_B(up) \
264 HID_ITEM_B(HID_REPORT_USAGE_PAGE, up)
265
266/**
267 * @brief HID Report Usage Page item helper macro (Double byte).
268 */
269#define HID_USAGE_PAGE_W(up) \
270 HID_ITEM_W(HID_REPORT_USAGE_PAGE, up)
271
272/**
273 * @brief HID Report Usage item helper macro (Single byte).
274 */
275#define HID_USAGE_B(u) \
276 HID_ITEM_B(HID_REPORT_USAGE, u)
277
278/**
279 * @brief HID Report Usage item helper macro (Double byte).
280 */
281#define HID_USAGE_W(u) \
282 HID_ITEM_W(HID_REPORT_USAGE, u)
283
284/**
285 * @brief HID Report Collection item helper macro (Single Byte).
286 */
287#define HID_COLLECTION_B(c) \
288 HID_ITEM_B(HID_REPORT_COLLECTION, c)
289
290/**
291 * @brief HID Report Collection item helper macro (Double Byte).
292 */
293#define HID_COLLECTION_W(c) \
294 HID_ITEM_W(HID_REPORT_COLLECTION, c)
295
296/**
297 * @brief HID Report End Collection item helper macro.
298 */
299#define HID_END_COLLECTION \
300 USB_DESC_BYTE(HID_REPORT_END_COLLECTION)
301
302/**
303 * @brief HID Report Usage Minimum item helper macro (Single byte).
304 */
305#define HID_USAGE_MINIMUM_B(x) \
306 HID_ITEM_B(HID_REPORT_USAGE_MINIMUM, x)
307
308/**
309 * @brief HID Report Usage Minimum item helper macro (Double byte).
310 */
311#define HID_USAGE_MINIMUM_W(x) \
312 HID_ITEM_W(HID_REPORT_USAGE_MINIMUM, x)
313
314/**
315 * @brief HID Report Usage Maximum item helper macro (Single byte).
316 */
317#define HID_USAGE_MAXIMUM_B(x) \
318 HID_ITEM_B(HID_REPORT_USAGE_MAXIMUM, x)
319
320/**
321 * @brief HID Report Usage Maximum item helper macro (Double byte).
322 */
323#define HID_USAGE_MAXIMUM_W(x) \
324 HID_ITEM_W(HID_REPORT_USAGE_MAXIMUM, x)
325
326/**
327 * @brief HID Report Logical Minimum item helper macro (Single byte).
328 */
329#define HID_LOGICAL_MINIMUM_B(x) \
330 HID_ITEM_B(HID_REPORT_LOGICAL_MINIMUM, x)
331
332/**
333 * @brief HID Report Logical Minimum item helper macro (Double byte).
334 */
335#define HID_LOGICAL_MINIMUM_W(x) \
336 HID_ITEM_W(HID_REPORT_LOGICAL_MINIMUM, x)
337
338/**
339 * @brief HID Report Logical Maximum item helper macro (Single byte).
340 */
341#define HID_LOGICAL_MAXIMUM_B(x) \
342 HID_ITEM_B(HID_REPORT_LOGICAL_MAXIMUM, x)
343
344/**
345 * @brief HID Report Logical Maximum item helper macro (Double byte).
346 */
347#define HID_LOGICAL_MAXIMUM_W(x) \
348 HID_ITEM_W(HID_REPORT_LOGICAL_MAXIMUM, x)
349
350/**
351 * @brief HID Report ID item helper macro (Single byte).
352 */
353#define HID_REPORT_ID_B(x) \
354 HID_ITEM_B(HID_REPORT_REPORT_ID, x)
355
356/**
357 * @brief HID Report ID item helper macro (Double byte).
358 */
359#define HID_REPORT_ID_W(x) \
360 HID_ITEM_W(HID_REPORT_REPORT_ID, x)
361
362/**
363 * @brief HID Report Count item helper macro (Single byte).
364 */
365#define HID_REPORT_COUNT_B(x) \
366 HID_ITEM_B(HID_REPORT_REPORT_COUNT, x)
367
368/**
369 * @brief HID Report Count item helper macro (Double byte).
370 */
371#define HID_REPORT_COUNT_W(x) \
372 HID_ITEM_W(HID_REPORT_REPORT_COUNT, x)
373
374/**
375 * @brief HID Report Size item helper macro (Single byte).
376 */
377#define HID_REPORT_SIZE_B(x) \
378 HID_ITEM_B(HID_REPORT_REPORT_SIZE, x)
379
380/**
381 * @brief HID Report Size item helper macro (Double byte).
382 */
383#define HID_REPORT_SIZE_W(x) \
384 HID_ITEM_W(HID_REPORT_REPORT_SIZE, x)
385
386/**
387 * @brief HID Report Input item helper macro (Single byte).
388 */
389#define HID_INPUT_B(x) \
390 HID_ITEM_B(HID_REPORT_INPUT, x)
391
392/**
393 * @brief HID Report Input item helper macro (Double byte).
394 */
395#define HID_INPUT_W(x) \
396 HID_ITEM_W(HID_REPORT_INPUT, x)
397/** @} */
398
399/**
400 * @brief HID Report Output item helper macro (Single byte).
401 */
402#define HID_OUTPUT_B(x) \
403 HID_ITEM_B(HID_REPORT_OUTPUT, x)
404
405/**
406 * @brief HID Report Output item helper macro (Double byte).
407 */
408#define HID_OUTPUT_W(x) \
409 HID_ITEM_W(HID_REPORT_OUTPUT, x)
410/** @} */
411
412/*===========================================================================*/
413/* Driver pre-compile time settings. */
414/*===========================================================================*/
415
416/**
417 * @name USB HID configuration options
418 * @{
419 */
420/**
421 * @brief USB HID buffers size.
422 * @details Configuration parameter, the buffer size must be a multiple of
423 * the USB data endpoint maximum packet size.
424 * @note The default is 256 bytes for both the transmission and receive
425 * buffers.
426 */
427#if !defined(USB_HID_BUFFERS_SIZE) || defined(__DOXYGEN__)
428#define USB_HID_BUFFERS_SIZE 256
429#endif
430
431/**
432 * @brief USB HID number of buffers.
433 * @note The default is 2 buffers.
434 */
435#if !defined(USB_HID_BUFFERS_NUMBER) || defined(__DOXYGEN__)
436#define USB_HID_BUFFERS_NUMBER 2
437#endif
438/** @} */
439
440/*===========================================================================*/
441/* Derived constants and error checks. */
442/*===========================================================================*/
443
444#if HAL_USE_USB == FALSE
445#error "USB HID Driver requires HAL_USE_USB"
446#endif
447
448/*===========================================================================*/
449/* Driver data structures and types. */
450/*===========================================================================*/
451
452/**
453 * @brief Driver state machine possible states.
454 */
455typedef enum {
456 HID_UNINIT = 0, /**< Not initialized. */
457 HID_STOP = 1, /**< Stopped. */
458 HID_READY = 2 /**< Ready. */
459} hidstate_t;
460
461/**
462 * @brief Structure representing a USB HID driver.
463 */
464typedef struct USBHIDDriver USBHIDDriver;
465
466/**
467 * @brief USB HID Driver configuration structure.
468 * @details An instance of this structure must be passed to @p hidStart()
469 * in order to configure and start the driver operations.
470 */
471typedef struct {
472 /**
473 * @brief USB driver to use.
474 */
475 USBDriver *usbp;
476 /**
477 * @brief Interrupt IN endpoint used for outgoing data transfer.
478 */
479 usbep_t int_in;
480 /**
481 * @brief Interrupt OUT endpoint used for incoming data transfer.
482 */
483 usbep_t int_out;
484} USBHIDConfig;
485
486/**
487 * @brief @p USBHIDDriver specific data.
488 */
489#define _usb_hid_driver_data \
490 _base_asynchronous_channel_data \
491 /* Driver state.*/ \
492 hidstate_t state; \
493 /* Input buffers queue.*/ \
494 input_buffers_queue_t ibqueue; \
495 /* Output queue.*/ \
496 output_buffers_queue_t obqueue; \
497 /* Input buffer.*/ \
498 uint8_t ib[BQ_BUFFER_SIZE(USB_HID_BUFFERS_NUMBER, \
499 USB_HID_BUFFERS_SIZE)]; \
500 /* Output buffer.*/ \
501 uint8_t ob[BQ_BUFFER_SIZE(USB_HID_BUFFERS_NUMBER, \
502 USB_HID_BUFFERS_SIZE)]; \
503 /* End of the mandatory fields.*/ \
504 /* Current configuration data.*/ \
505 const USBHIDConfig *config;
506
507/**
508 * @brief @p USBHIDDriver specific methods.
509 */
510#define _usb_hid_driver_methods \
511 _base_asynchronous_channel_methods \
512 /* Buffer flush method.*/ \
513 void (*flush)(void *instance);
514
515/**
516 * @extends BaseAsynchronousChannelVMT
517 *
518 * @brief @p USBHIDDriver virtual methods table.
519 */
520struct USBHIDDriverVMT {
521 _usb_hid_driver_methods
522};
523
524/**
525 * @extends BaseAsynchronousChannel
526 *
527 * @brief Full duplex USB HID driver class.
528 * @details This class extends @p BaseAsynchronousChannel by adding physical
529 * I/O queues.
530 */
531struct USBHIDDriver {
532 /** @brief Virtual Methods Table.*/
533 const struct USBHIDDriverVMT *vmt;
534 _usb_hid_driver_data
535};
536
537#define USB_DRIVER_EXT_FIELDS \
538 USBHIDDriver hid
539
540/*===========================================================================*/
541/* Driver macros. */
542/*===========================================================================*/
543
544/*===========================================================================*/
545/* External declarations. */
546/*===========================================================================*/
547#ifdef __cplusplus
548extern "C" {
549#endif
550 void hidInit(void);
551 void hidObjectInit(USBHIDDriver *uhdp);
552 void hidStart(USBHIDDriver *uhdp, const USBHIDConfig *config);
553 void hidStop(USBHIDDriver *uhdp);
554 void hidDisconnectI(USBHIDDriver *uhdp);
555 void hidConfigureHookI(USBHIDDriver *uhdp);
556 bool hidRequestsHook(USBDriver *usbp);
557 void hidDataTransmitted(USBDriver *usbp, usbep_t ep);
558 void hidDataReceived(USBDriver *usbp, usbep_t ep);
559 size_t hidWriteReport(USBHIDDriver *uhdp, uint8_t *bp, size_t n);
560 size_t hidWriteReportt(USBHIDDriver *uhdp, uint8_t *bp, size_t n, systime_t timeout);
561 size_t hidReadReport(USBHIDDriver *uhdp, uint8_t *bp, size_t n);
562 size_t hidReadReportt(USBHIDDriver *uhdp, uint8_t *bp, size_t n, systime_t timeout);
563#ifdef __cplusplus
564}
565#endif
566
567#endif /* HAL_USE_USB_HID */
568
569#endif /* HAL_USB_HID_H */
570
571/** @} */
generated by cgit v1.2.3 (git 2.25.1) at 2025-08-30 20:59:21 +0100