1 /* 2 * Copyright (c) 2018 Intel Corporation 3 * Copyright (c) 2018,2021 Nordic Semiconductor ASA 4 * 5 * SPDX-License-Identifier: Apache-2.0 6 */ 7 8 /** 9 * @file 10 * @brief USB HID Class device API header 11 */ 12 13 #ifndef ZEPHYR_INCLUDE_USB_HID_CLASS_DEVICE_H_ 14 #define ZEPHYR_INCLUDE_USB_HID_CLASS_DEVICE_H_ 15 16 #include <usb/class/hid.h> 17 18 #ifdef __cplusplus 19 extern "C" { 20 #endif 21 22 /** 23 * @brief usb_hid.h API 24 * @defgroup usb_hid_class USB HID class API 25 * @{ 26 * @} 27 */ 28 29 /** 30 * @defgroup usb_hid_device_api HID class USB specific definitions 31 * @ingroup usb_hid_class 32 * @{ 33 */ 34 35 typedef int (*hid_cb_t)(const struct device *dev, 36 struct usb_setup_packet *setup, int32_t *len, 37 uint8_t **data); 38 typedef void (*hid_int_ready_callback)(const struct device *dev); 39 typedef void (*hid_protocol_cb_t)(const struct device *dev, uint8_t protocol); 40 typedef void (*hid_idle_cb_t)(const struct device *dev, uint16_t report_id); 41 42 /** 43 * @brief USB HID device interface 44 */ 45 struct hid_ops { 46 hid_cb_t get_report; 47 hid_cb_t set_report; 48 hid_protocol_cb_t protocol_change; 49 hid_idle_cb_t on_idle; 50 /* 51 * int_in_ready is an optional callback that is called when 52 * the current interrupt IN transfer has completed. This can 53 * be used to wait for the endpoint to go idle or to trigger 54 * the next transfer. 55 */ 56 hid_int_ready_callback int_in_ready; 57 #ifdef CONFIG_ENABLE_HID_INT_OUT_EP 58 hid_int_ready_callback int_out_ready; 59 #endif 60 }; 61 62 /** 63 * @brief Register HID device 64 * 65 * @param[in] dev Pointer to USB HID device 66 * @param[in] desc Pointer to HID report descriptor 67 * @param[in] size Size of HID report descriptor 68 * @param[in] op Pointer to USB HID device interrupt struct 69 */ 70 void usb_hid_register_device(const struct device *dev, 71 const uint8_t *desc, 72 size_t size, 73 const struct hid_ops *op); 74 75 /** 76 * @brief Write to USB HID interrupt endpoint buffer 77 * 78 * @param[in] dev Pointer to USB HID device 79 * @param[in] data Pointer to data buffer 80 * @param[in] data_len Length of data to copy 81 * @param[out] bytes_ret Bytes written to the EP buffer. 82 * 83 * @return 0 on success, negative errno code on fail. 84 */ 85 int hid_int_ep_write(const struct device *dev, 86 const uint8_t *data, 87 uint32_t data_len, 88 uint32_t *bytes_ret); 89 90 /** 91 * @brief Read from USB HID interrupt endpoint buffer 92 * 93 * @param[in] dev Pointer to USB HID device 94 * @param[in] data Pointer to data buffer 95 * @param[in] max_data_len Max length of data to copy 96 * @param[out] ret_bytes Number of bytes to copy. If data is NULL and 97 * ret_bytes is 0 the number of bytes 98 * available in the buffer will be returned. 99 * 100 * @return 0 on success, negative errno code on fail. 101 */ 102 int hid_int_ep_read(const struct device *dev, 103 uint8_t *data, 104 uint32_t max_data_len, 105 uint32_t *ret_bytes); 106 107 /** 108 * @brief Set USB HID class Protocol Code 109 * 110 * @details Should be called before usb_hid_init(). 111 * 112 * @param[in] dev Pointer to USB HID device 113 * @param[in] proto_code Protocol Code to be used for bInterfaceProtocol 114 * 115 * @return 0 on success, negative errno code on fail. 116 */ 117 int usb_hid_set_proto_code(const struct device *dev, uint8_t proto_code); 118 119 /** 120 * @brief Initialize USB HID class support 121 * 122 * @param[in] dev Pointer to USB HID device 123 * 124 * @return 0 on success, negative errno code on fail. 125 */ 126 int usb_hid_init(const struct device *dev); 127 128 /** 129 * @} 130 */ 131 132 /* 133 * Macros below are deprecated in 2.6 release. 134 * Please replace with macros from common HID header, include/usb/class/hid.h 135 */ 136 137 #define HID_CLASS_DESCRIPTOR_HID __DEPRECATED_MACRO USB_DESC_HID 138 #define HID_CLASS_DESCRIPTOR_REPORT __DEPRECATED_MACRO USB_DESC_HID_REPORT 139 140 #define HID_GET_REPORT __DEPRECATED_MACRO USB_HID_GET_REPORT 141 #define HID_GET_IDLE __DEPRECATED_MACRO USB_HID_GET_IDLE 142 #define HID_GET_PROTOCOL __DEPRECATED_MACRO USB_HID_GET_PROTOCOL 143 #define HID_SET_REPORT __DEPRECATED_MACRO USB_HID_SET_REPORT 144 #define HID_SET_IDLE __DEPRECATED_MACRO USB_HID_SET_IDLE 145 #define HID_SET_PROTOCOL __DEPRECATED_MACRO USB_HID_SET_PROTOCOL 146 147 #define ITEM_MAIN __DEPRECATED_MACRO 0x0 148 #define ITEM_GLOBAL __DEPRECATED_MACRO 0x1 149 #define ITEM_LOCAL __DEPRECATED_MACRO 0x2 150 151 #define ITEM_TAG_INPUT __DEPRECATED_MACRO 0x8 152 #define ITEM_TAG_OUTPUT __DEPRECATED_MACRO 0x9 153 #define ITEM_TAG_COLLECTION __DEPRECATED_MACRO 0xA 154 #define ITEM_TAG_COLLECTION_END __DEPRECATED_MACRO 0xC 155 156 #define ITEM_TAG_USAGE_PAGE __DEPRECATED_MACRO 0x0 157 #define ITEM_TAG_LOGICAL_MIN __DEPRECATED_MACRO 0x1 158 #define ITEM_TAG_LOGICAL_MAX __DEPRECATED_MACRO 0x2 159 #define ITEM_TAG_REPORT_SIZE __DEPRECATED_MACRO 0x7 160 #define ITEM_TAG_REPORT_ID __DEPRECATED_MACRO 0x8 161 #define ITEM_TAG_REPORT_COUNT __DEPRECATED_MACRO 0x9 162 163 #define ITEM_TAG_USAGE __DEPRECATED_MACRO 0x0 164 #define ITEM_TAG_USAGE_MIN __DEPRECATED_MACRO 0x1 165 #define ITEM_TAG_USAGE_MAX __DEPRECATED_MACRO 0x2 166 167 #define HID_MAIN_ITEM(bTag, bSize) \ 168 __DEPRECATED_MACRO HID_ITEM(bTag, ITEM_MAIN, bSize) 169 #define HID_GLOBAL_ITEM(bTag, bSize) \ 170 __DEPRECATED_MACRO HID_ITEM(bTag, ITEM_GLOBAL, bSize) 171 #define HID_LOCAL_ITEM(bTag, bSize) \ 172 __DEPRECATED_MACRO HID_ITEM(bTag, ITEM_LOCAL, bSize) 173 174 #define HID_MI_COLLECTION \ 175 __DEPRECATED_MACRO HID_MAIN_ITEM(ITEM_TAG_COLLECTION, 1) 176 #define HID_MI_COLLECTION_END \ 177 __DEPRECATED_MACRO HID_MAIN_ITEM(ITEM_TAG_COLLECTION_END, 0) 178 #define HID_MI_INPUT \ 179 __DEPRECATED_MACRO HID_MAIN_ITEM(ITEM_TAG_INPUT, 1) 180 #define HID_MI_OUTPUT \ 181 __DEPRECATED_MACRO HID_MAIN_ITEM(ITEM_TAG_OUTPUT, 1) 182 #define HID_GI_USAGE_PAGE \ 183 __DEPRECATED_MACRO HID_GLOBAL_ITEM(ITEM_TAG_USAGE_PAGE, 1) 184 #define HID_GI_LOGICAL_MIN(size) \ 185 __DEPRECATED_MACRO HID_GLOBAL_ITEM(ITEM_TAG_LOGICAL_MIN, size) 186 #define HID_GI_LOGICAL_MAX(size) \ 187 __DEPRECATED_MACRO HID_GLOBAL_ITEM(ITEM_TAG_LOGICAL_MAX, size) 188 #define HID_GI_REPORT_SIZE \ 189 __DEPRECATED_MACRO HID_GLOBAL_ITEM(ITEM_TAG_REPORT_SIZE, 1) 190 #define HID_GI_REPORT_ID \ 191 __DEPRECATED_MACRO HID_GLOBAL_ITEM(ITEM_TAG_REPORT_ID, 1) 192 #define HID_GI_REPORT_COUNT \ 193 __DEPRECATED_MACRO HID_GLOBAL_ITEM(ITEM_TAG_REPORT_COUNT, 1) 194 195 #define HID_LI_USAGE \ 196 __DEPRECATED_MACRO HID_LOCAL_ITEM(ITEM_TAG_USAGE, 1) 197 #define HID_LI_USAGE_MIN(size) \ 198 __DEPRECATED_MACRO HID_LOCAL_ITEM(ITEM_TAG_USAGE_MIN, size) 199 #define HID_LI_USAGE_MAX(size) \ 200 __DEPRECATED_MACRO HID_LOCAL_ITEM(ITEM_TAG_USAGE_MAX, size) 201 202 #define USAGE_GEN_DESKTOP __DEPRECATED_MACRO 0x01 203 #define USAGE_GEN_KEYBOARD __DEPRECATED_MACRO 0x07 204 #define USAGE_GEN_LEDS __DEPRECATED_MACRO 0x08 205 #define USAGE_GEN_BUTTON __DEPRECATED_MACRO 0x09 206 207 #define USAGE_GEN_DESKTOP_UNDEFINED __DEPRECATED_MACRO 0x00 208 #define USAGE_GEN_DESKTOP_POINTER __DEPRECATED_MACRO 0x01 209 #define USAGE_GEN_DESKTOP_MOUSE __DEPRECATED_MACRO 0x02 210 #define USAGE_GEN_DESKTOP_JOYSTICK __DEPRECATED_MACRO 0x04 211 #define USAGE_GEN_DESKTOP_GAMEPAD __DEPRECATED_MACRO 0x05 212 #define USAGE_GEN_DESKTOP_KEYBOARD __DEPRECATED_MACRO 0x06 213 #define USAGE_GEN_DESKTOP_KEYPAD __DEPRECATED_MACRO 0x07 214 #define USAGE_GEN_DESKTOP_X __DEPRECATED_MACRO 0x30 215 #define USAGE_GEN_DESKTOP_Y __DEPRECATED_MACRO 0x31 216 #define USAGE_GEN_DESKTOP_WHEEL __DEPRECATED_MACRO 0x38 217 218 #define COLLECTION_PHYSICAL __DEPRECATED_MACRO 0x00 219 #define COLLECTION_APPLICATION __DEPRECATED_MACRO 0x01 220 221 #ifdef __cplusplus 222 } 223 #endif 224 225 #endif /* ZEPHYR_INCLUDE_USB_HID_CLASS_DEVICE_H_ */ 226
