smolusb 0.2.2

An experimental lightweight library for implementing USB on embedded systems.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

use crate::device::Speed;
use crate::setup::Direction;

use zerocopy::AsBytes;

use core::slice;

// - UsbDriverOperations ------------------------------------------------------

// convenience alias
pub trait UsbDriver: ReadControl + ReadEndpoint + WriteEndpoint + UsbDriverOperations {}

pub trait UsbDriverOperations {
    /// Connect the device.
    fn connect(&mut self, device_speed: Speed);
    /// Disconnect the device.
    fn disconnect(&mut self);
    /// Perform a reset of the device.
    fn bus_reset(&self);
    /// Acknowledge the status stage of an incoming control request.
    fn ack(&self, endpoint_number: u8, direction: Direction);
    /// Set the device address.
    fn set_address(&self, address: u8);
    /// Stall the given IN endpoint number.
    fn stall_endpoint_in(&self, endpoint_number: u8);
    /// Stall the given OUT endpoint number.
    fn stall_endpoint_out(&self, endpoint_number: u8);

    /// Clear a halt condition on the target endpoint address.
    fn clear_feature_endpoint_halt(&self, endpoint_number: u8, direction: Direction);
}

/// These are used to deal with the situation where we need to block
/// on receipt of the host ACK following a usb write inside an ongoing
/// operation and are unable to process
/// [`UsbEvent::SendComplete`](crate::event::UsbEvent::SendComplete)
/// interrupt events.
///
/// Not having to do this is a powerful argument for implementing
/// async support.
///
/// This is not a particularly safe approach.
pub trait UnsafeUsbDriverOperations {
    /// Sets an atomic flag for the given endpoint number in order to
    /// be able to block on an event in an interrupt handler.
    ///
    /// # Safety
    ///
    /// Remember that the flag will stay set if your interrupt event
    /// never happens!
    unsafe fn set_tx_ack_active(&self, endpoint_number: u8);
    /// Clears an atomic flag for the given endpoint number in order to
    /// be able to block on an event in an interrupt handler.
    ///
    /// # Safety
    ///
    /// Remember that the flag will stay set if your interrupt event
    /// never happens!
    unsafe fn clear_tx_ack_active(&self, endpoint_number: u8);
    /// Tests an atomic flag for the given endpoint number in order to
    /// be able to block on an event in an interrupt handler.
    ///
    /// # Safety
    ///
    /// Remember that the flag will stay set if your interrupt event
    /// never happens!
    unsafe fn is_tx_ack_active(&self, endpoint_number: u8) -> bool;
}

// - UsbRead/UsbWrite ---------------------------------------------------------

pub trait ReadControl {
    /// Read a setup packet from the control endpoint.
    ///
    /// Returns the number of bytes read from the control endpoint.
    fn read_control(&self, buffer: &mut [u8]) -> usize;
}

pub trait ReadEndpoint {
    /// Prime the given OUT endpoint for reception.
    fn ep_out_prime_receive(&self, endpoint_number: u8);

    /// Re-enable all primed OUT endpoints for reception after receipt of a packet.
    fn ep_out_enable(&self);

    /// Read a packet from the given endpoint.
    ///
    /// Returns the number of bytes read from the endpoint.
    fn read(&self, endpoint_number: u8, buffer: &mut [u8]) -> usize;
}

pub trait WriteEndpoint {
    /// Write iterator to endpoint
    ///
    /// Returns the number of bytes written to the endpoint.
    fn write<I>(&self, endpoint_number: u8, iter: I) -> usize
    where
        I: Iterator<Item = u8>;

    /// Write the requested number of bytes from the iterator to endpoint
    ///
    /// Returns the number of bytes written to the endpoint.
    fn write_requested<I>(&self, endpoint_number: u8, requested_length: usize, iter: I) -> usize
    where
        I: Iterator<Item = u8>;

    /// Write iterator to endpoint using the given packet size
    ///
    /// Returns the number of bytes written to the endpoint.
    fn write_with_packet_size<I>(
        &self,
        endpoint_number: u8,
        requested_length: Option<usize>,
        iter: I,
        packet_size: usize,
    ) -> usize
    where
        I: Iterator<Item = u8>;
}

// - AsIterator ---------------------------------------------------------------

pub trait AsByteSliceIterator: AsBytes {
    fn as_iter(&self) -> slice::Iter<u8> {
        self.as_bytes().iter()
    }
}