Line data    Source code

       1           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 <zephyr/usb/class/hid.h>
      17             : #include <zephyr/usb/usb_ch9.h>
      18             : 
      19             : #ifdef __cplusplus
      20             : extern "C" {
      21             : #endif
      22             : 
      23             : /**
      24             :  * @brief usb_hid.h API
      25             :  * @defgroup usb_hid_class USB HID class API
      26             :  * @ingroup usb
      27             :  * @since 1.11
      28             :  * @version 1.0.0
      29             :  * @{
      30             :  */
      31             : 
      32             : /**
      33             :  * @defgroup usb_hid_device_api HID class USB specific definitions
      34             :  * @{
      35             :  */
      36             : 
      37           0 : typedef int (*hid_cb_t)(const struct device *dev,
      38             :                         struct usb_setup_packet *setup, int32_t *len,
      39             :                         uint8_t **data);
      40           0 : typedef void (*hid_int_ready_callback)(const struct device *dev);
      41           0 : typedef void (*hid_protocol_cb_t)(const struct device *dev, uint8_t protocol);
      42           0 : typedef void (*hid_idle_cb_t)(const struct device *dev, uint16_t report_id);
      43             : 
      44             : /**
      45             :  * @brief USB HID device interface
      46             :  */
      47           1 : struct hid_ops {
      48           0 :         hid_cb_t get_report;
      49           0 :         hid_cb_t set_report;
      50           0 :         hid_protocol_cb_t protocol_change;
      51           0 :         hid_idle_cb_t on_idle;
      52             :         /*
      53             :          * int_in_ready is an optional callback that is called when
      54             :          * the current interrupt IN transfer has completed.  This can
      55             :          * be used to wait for the endpoint to go idle or to trigger
      56             :          * the next transfer.
      57             :          */
      58           0 :         hid_int_ready_callback int_in_ready;
      59           0 :         hid_int_ready_callback int_out_ready;
      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           1 : 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           1 : 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             :  *                          max_data_len 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           1 : 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           1 : 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           1 : int usb_hid_init(const struct device *dev);
     127             : 
     128             : /**
     129             :  * @}
     130             :  */
     131             : 
     132             : /**
     133             :  * @}
     134             :  */
     135             : 
     136             : #ifdef __cplusplus
     137             : }
     138             : #endif
     139             : 
     140             : #endif /* ZEPHYR_INCLUDE_USB_HID_CLASS_DEVICE_H_ */