kernel/hil/
usb_hid.rs

1// Licensed under the Apache License, Version 2.0 or the MIT License.
2// SPDX-License-Identifier: Apache-2.0 OR MIT
3// Copyright Tock Contributors 2022.
4
5//! Interface for USB HID (Human Interface Device) class
6
7use crate::ErrorCode;
8
9/// The 'types' of USB HID, this should define the size of send/received packets
10pub trait UsbHidType: Copy + Clone + Sized {}
11
12impl UsbHidType for [u8; 64] {}
13impl UsbHidType for [u8; 32] {}
14impl UsbHidType for [u8; 16] {}
15impl UsbHidType for [u8; 8] {}
16
17/// Implement this trait and use `set_client()` in order to receive callbacks.
18pub trait Client<'a, T: UsbHidType> {
19    /// Called when a packet is received.
20    /// This will return the buffer passed into `receive_buffer()` as well as
21    /// the endpoint where the data was received. If the buffer length is smaller
22    /// then the data length the buffer will only contain part of the packet and
23    /// `result` will contain indicate an `SIZE` error. Result will indicate
24    /// `CANCEL` if a receive was cancelled by `receive_cancel()` but the
25    /// callback still occurred. See `receive_cancel()` for more details.
26    fn packet_received(
27        &'a self,
28        result: Result<(), ErrorCode>,
29        buffer: &'static mut T,
30        endpoint: usize,
31    );
32
33    /// Called when a packet has been finished transmitting.
34    /// This will return the buffer passed into `send_buffer()` as well as
35    /// the endpoint where the data was sent. If not all of the data could
36    /// be sent the `result` will contain the `SIZE` error. Result will
37    /// indicate `CANCEL` if a send was cancelled by `send_cancel()`
38    /// but the callback still occurred. See `send_cancel()` for more
39    /// details.
40    fn packet_transmitted(
41        &'a self,
42        result: Result<(), ErrorCode>,
43        buffer: &'static mut T,
44        endpoint: usize,
45    );
46}
47
48pub trait UsbHid<'a, T: UsbHidType> {
49    /// Sets the buffer to be sent and starts a send transaction.
50    /// Once the packet is sent the `packet_transmitted()` callback will
51    /// be triggered and no more data will be sent until
52    /// this is called again.
53    ///
54    /// Once this is called, the implementation will wait until either
55    /// the packet is sent or `send_cancel()` is called.
56    ///
57    /// Calling `send_buffer()` while there is an outstanding
58    /// `send_buffer()` operation will return BUSY.
59    ///
60    /// On success returns the length of data to be sent.
61    /// On failure returns an error code and the buffer passed in.
62    fn send_buffer(&'a self, send: &'static mut T) -> Result<usize, (ErrorCode, &'static mut T)>;
63
64    /// Cancels a send called by `send_buffer()`.
65    /// If `send_cancel()` successfully cancels a send transaction
66    /// before the transaction has been acted upon this function will
67    /// return the buffer passed via `send_buffer()` and no callback
68    /// will occur.
69    /// If there is currently no send transaction (`send_buffer()`
70    /// hasn't been called) this will return `Err(INVAL)`.
71    /// If the transaction can't be cancelled cleanly, either because
72    /// the send has already occured, a partial send has occured or the
73    /// send can not be cancelled by the hardware this will return
74    /// `Err(BUSY)` and the callback will still occur.
75    /// Note that unless the transaction completes the callback will
76    /// indicate a result of `CANCEL`.
77    fn send_cancel(&'a self) -> Result<&'static mut T, ErrorCode>;
78
79    /// Sets the buffer for received data to be stored and enables receive
80    /// transactions. Once this is called the implementation will enable
81    /// receiving via USB. Once a packet is received the `packet_received()`
82    /// callback will be triggered and no more data will be received until
83    /// this is called again.
84    ///
85    /// Once this is called, the implementation will wait until either
86    /// a packet is received or `receive_cancel()` is called.
87    ///
88    /// Calling `receive_buffer()` while there is an outstanding
89    /// `receive_buffer()` operation will return BUSY.
90    ///
91    /// On success returns nothing.
92    /// On failure returns an error code and the buffer passed in.
93    fn receive_buffer(&'a self, recv: &'static mut T) -> Result<(), (ErrorCode, &'static mut T)>;
94
95    /// Cancels a receive called by `receive_buffer()`.
96    /// If `receive_cancel()` successfully cancels a receive transaction
97    /// before the transaction has been acted upon this function will
98    /// return the buffer passed via `receive_buffer()` and no callback
99    /// will occur.
100    /// If there is currently no receive transaction (`receive_buffer()`
101    /// hasn't been called) this will return `Err(INVAL)`.
102    /// If the transaction can't be cancelled cleanly, either because
103    /// the receive has already occured, a partial receive has occured or the
104    /// receive can not be cancelled by the hardware this will return
105    /// `Err(BUSY)` and the callback will still occur.
106    /// Note that unless the transaction completes the callback will
107    /// indicate a result of `CANCEL`.
108    fn receive_cancel(&'a self) -> Result<&'static mut T, ErrorCode>;
109}
kernel/hil/usb_hid.rs

kernel/hil/
usb_hid.rs
