sys/dev/hid/hid_if.m

   1 #-
   2 # Copyright (c) 2019 Vladimir Kondratyev
   3 #
   4 # Redistribution and use in source and binary forms, with or without
   5 # modification, are permitted provided that the following conditions
   6 # are met:
   7 # 1. Redistributions of source code must retain the above copyright
   8 #    notice, this list of conditions and the following disclaimer.
   9 # 2. Redistributions in binary form must reproduce the above copyright
  10 #    notice, this list of conditions and the following disclaimer in the
  11 #    documentation and/or other materials provided with the distribution.
  12 #
  13 # THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 # ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 # ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 # FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 # DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 # OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 # HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 # LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 # OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 # SUCH DAMAGE.
  24 #
  25 # $FreeBSD$
  26 #
  27
  28 #include <sys/param.h>
  29 #include <sys/bus.h>
  30 #include <sys/kernel.h>
  31 #include <sys/malloc.h>
  32 #include <dev/hid/hid.h>
  33
  34 # Any function listed here can do unbound sleeps waiting for IO to complete.
  35
  36 INTERFACE hid;
  37
  38 # Interrupts interface
  39
  40 #
  41 # Allocate memory and initialise interrupt transfers.
  42 # intr callback function which is called if input data is available.
  43 # context is the private softc pointer, which will be used to callback.
  44 # rdesc is pointer to structire containing requested maximal sizes of input,
  45 # output and feature reports.  It is used by hardware transport drivers
  46 # to determine sizes of internal buffers.
  47 # This function can be subsequently called with intr parameter set to NULL
  48 # to request intr_poll method support for transport driver.
  49 #
  50 METHOD void intr_setup {
  51         device_t dev;
  52         hid_intr_t intr;
  53         void *context;
  54         struct hid_rdesc_info *rdesc;
  55 };
  56
  57 #
  58 # Release all allocated resources associated with interrupt transfers.
  59 #
  60 METHOD void intr_unsetup {
  61         device_t dev;
  62 };
  63
  64 #
  65 # Start the interrupt transfers if not already started.
  66 #
  67 METHOD int intr_start {
  68         device_t dev;
  69 };
  70
  71 #
  72 # Stop the interrupt transfers if not already stopped.
  73 #
  74 METHOD int intr_stop {
  75         device_t dev;
  76 };
  77
  78 #
  79 # The following function gets called from the HID keyboard driver when
  80 # the system has panicked. intr_setup method with NULL passed as intr parameter
  81 # must be called once before to let transport driver to be prepared.
  82 #
  83 METHOD void intr_poll {
  84         device_t dev;
  85 };
  86
  87 # HID interface
  88
  89 #
  90 # Read out an report descriptor from the HID device.
  91 #
  92 METHOD int get_rdesc {
  93         device_t dev;
  94         void *data;
  95         hid_size_t len;
  96 };
  97
  98 #
  99 # Get input data from the device. Data should be read in chunks
 100 # of the size prescribed by the report descriptor.
 101 # This function interferes with interrupt transfers and should not be used.
 102 #
 103 METHOD int read {
 104         device_t dev;
 105         void *data;
 106         hid_size_t maxlen;
 107         hid_size_t *actlen;
 108 };
 109
 110 #
 111 # Send data to the device. Data should be written in
 112 # chunks of the size prescribed by the report descriptor.
 113 #
 114 METHOD int write {
 115         device_t dev;
 116         const void *data;
 117         hid_size_t len;
 118 };
 119
 120 #
 121 # Get a report from the device without waiting for data on the interrupt.
 122 # Copies a maximum of len bytes of the report data into the memory specified
 123 # by data. Upon return actlen is set to the number of bytes copied. The type
 124 # field indicates which report is requested. It should be HID_INPUT_REPORT,
 125 # HID_OUTPUT_REPORT, or HID_FEATURE_REPORT. This call may fail if the device
 126 # does not support this feature.
 127 #
 128 METHOD int get_report {
 129         device_t dev;
 130         void *data;
 131         hid_size_t maxlen;
 132         hid_size_t *actlen;
 133         uint8_t type;
 134         uint8_t id;
 135 };
 136
 137 #
 138 # Set a report in the device. The type field indicates which report is to be
 139 # set. It should be HID_INPUT_REPORT, HID_OUTPUT_REPORT, or HID_FEATURE_REPORT.
 140 # The value of the report is specified by the data and the len fields.
 141 # This call may fail if the device does not support this feature.
 142 #
 143 METHOD int set_report {
 144         device_t dev;
 145         const void *data;
 146         hid_size_t len;
 147         uint8_t type;
 148         uint8_t id;
 149 };
 150
 151 #
 152 # Set duration between input reports (in mSec).
 153 #
 154 METHOD int set_idle {
 155         device_t dev;
 156         uint16_t duration;
 157         uint8_t id;
 158 };
 159
 160 #
 161 # Switch between the boot protocol and the report protocol (or vice versa).
 162 #
 163 METHOD int set_protocol {
 164         device_t dev;
 165         uint16_t protocol;
 166 };
 167
 168 #
 169 # Executes arbitrary transport backend command.
 170 # Format of command is defined by hardware transport driver.
 171 #
 172 METHOD int ioctl {
 173         device_t dev;
 174         unsigned long cmd;
 175         uintptr_t data;
 176 };