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
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
//! A Framed flavor of BBQueue, useful for variable length packets
//!
//! This module allows for a `Framed` mode of operation,
//! where a size header is included in each grant, allowing for
//! "chunks" of data to be passed through a BBQueue, rather than
//! just a stream of bytes. This is convenient when receiving
//! packets of variable sizes.
//!
//! ## Frame header
//!
//! An internal header is required for each frame stored
//! inside of the `BBQueue`. This header is never exposed to end
//! users of the bbqueue library.
//!
//! A variable sized integer is used for the header size, and the
//! size of this header is based on the max size requested for the grant.
//! This header size must be factored in when calculating an appropriate
//! total size of your buffer.
//!
//! Even if a smaller portion of the grant is committed, the original
//! requested grant size will be used for the header size calculation.
//!
//! For example, if you request a 128 byte grant, the header size will
//! be two bytes. If you then only commit 32 bytes, two bytes will still
//! be used for the header of that grant.
//!
//! | Grant Size (bytes)    | Header size (bytes)  |
//! | :---                  | :---                 |
//! | 1..(2^7)              | 1                    |
//! | (2^7)..(2^14)         | 2                    |
//! | (2^14)..(2^21)        | 3                    |
//! | (2^21)..(2^28)        | 4                    |
//! | (2^28)..(2^35)        | 5                    |
//! | (2^35)..(2^42)        | 6                    |
//! | (2^42)..(2^49)        | 7                    |
//! | (2^49)..(2^56)        | 8                    |
//! | (2^56)..(2^64)        | 9                    |
//!

use crate::bbqueue_ipc::{Consumer, GrantR, GrantW, Producer};

use crate::bbqueue_ipc::Result;

use core::{
    cmp::min,
    ops::{Deref, DerefMut},
};

const HDR_LEN: usize = core::mem::size_of::<u16>();

/// A producer of Framed data
pub struct FrameProducer<'a> {
    pub(crate) producer: Producer<'a>,
}

impl<'a> FrameProducer<'a> {
    /// Receive a grant for a frame with a maximum size of `max_sz` in bytes.
    ///
    /// This size does not include the size of the frame header. The exact size
    /// of the frame can be set on `commit`.
    pub fn grant(&self, max_sz: usize) -> Result<FrameGrantW<'a>> {
        Ok(FrameGrantW {
            grant_w: self.producer.grant_exact(max_sz + HDR_LEN)?,
        })
    }
}

/// A consumer of Framed data
pub struct FrameConsumer<'a> {
    pub(crate) consumer: Consumer<'a>,
}

impl<'a> FrameConsumer<'a> {
    /// Obtain the next available frame, if any
    pub fn read(&self) -> Option<FrameGrantR<'a>> {
        // Get all available bytes. We never wrap a frame around,
        // so if a header is available, the whole frame will be.
        let mut grant_r = self.consumer.read().ok()?;

        // Additionally, we never commit less than a full frame with
        // a header, so if we have ANY data, we'll have a full header
        // and frame. `Consumer::read` will return an Error when
        // there are 0 bytes available.

        // The header consists of a single u16, in little endian order
        let mut len_b = [0u8; 2];
        len_b.copy_from_slice(&grant_r[..HDR_LEN]);
        let total_len = u16::from_le_bytes(len_b) as usize;

        debug_assert!(grant_r.len() >= total_len);

        // Reduce the grant down to the size of the frame with a header
        grant_r.shrink(total_len);

        Some(FrameGrantR { grant_r })
    }
}

/// A write grant for a single frame
///
/// NOTE: If the grant is dropped without explicitly commiting
/// the contents without first calling `to_commit()`, then no
/// frame will be comitted for writing.
#[derive(Debug, PartialEq)]
pub struct FrameGrantW<'a> {
    grant_w: GrantW<'a>,
}

/// A read grant for a single frame
///
/// NOTE: If the grant is dropped without explicitly releasing
/// the contents, then no frame will be released.
#[derive(Debug, PartialEq)]
pub struct FrameGrantR<'a> {
    grant_r: GrantR<'a>,
}

impl<'a> Deref for FrameGrantW<'a> {
    type Target = [u8];

    fn deref(&self) -> &Self::Target {
        &self.grant_w.buf[HDR_LEN..]
    }
}

impl<'a> DerefMut for FrameGrantW<'a> {
    fn deref_mut(&mut self) -> &mut [u8] {
        &mut self.grant_w.buf[HDR_LEN..]
    }
}

impl<'a> Deref for FrameGrantR<'a> {
    type Target = [u8];

    fn deref(&self) -> &Self::Target {
        &self.grant_r.buf[HDR_LEN..]
    }
}

impl<'a> DerefMut for FrameGrantR<'a> {
    fn deref_mut(&mut self) -> &mut [u8] {
        &mut self.grant_r.buf[HDR_LEN..]
    }
}

impl<'a> FrameGrantW<'a> {
    /// Commit a frame to make it available to the Consumer half.
    ///
    /// `used` is the size of the payload, in bytes, not
    /// including the frame header
    pub fn commit(mut self, used: usize) {
        let total_len = self.set_header(used);

        // Commit the header + frame
        self.grant_w.commit(total_len);
    }

    /// Set the header and return the total size
    fn set_header(&mut self, used: usize) -> usize {
        // Saturate the commit size to the available frame size
        let grant_len = self.grant_w.len();
        let frame_len = min(used, grant_len - HDR_LEN);
        let total_len = frame_len + HDR_LEN;

        // Write the actual frame length to the header

        self.grant_w[..HDR_LEN].copy_from_slice(&(total_len as u16).to_le_bytes());

        total_len
    }

    /// Configures the amount of bytes to be commited on drop.
    pub fn to_commit(&mut self, amt: usize) {
        if amt == 0 {
            self.grant_w.to_commit(0);
        } else {
            let size = self.set_header(amt);
            self.grant_w.to_commit(size);
        }
    }
}

impl<'a> FrameGrantR<'a> {
    /// Release a frame to make the space available for future writing
    ///
    /// Note: The full frame is always released
    pub fn release(mut self) {
        // For a read grant, we have already shrunk the grant
        // size down to the correct size
        let len = self.grant_r.len();
        self.grant_r.release_inner(len);
    }

    /// Set whether the read fram should be automatically released
    pub fn auto_release(&mut self, is_auto: bool) {
        self.grant_r
            .to_release(if is_auto { self.grant_r.len() } else { 0 });
    }
}