Skip to main content

rusty_rtos_kernel_core/
stream.rs

1//! `stream_buffer.c`: a byte ring one task writes and another reads.
2//!
3//! A stream buffer is the only kernel object here that is not built on a
4//! queue and not built on an event list. It is a ring of bytes plus two
5//! task handles, and a task waiting on one blocks on a **task
6//! notification** rather than on an event list — which is why the
7//! notification API had to exist before this file could.
8//!
9//! Two shapes share the code:
10//!
11//! * a **stream buffer** passes bytes, and a reader wakes when at least
12//!   the trigger level of them have arrived;
13//! * a **message buffer** passes whole messages, by writing the length in
14//!   front of each one. A read returns one message or nothing.
15//!
16//! The length prefix is `sizeof( configMESSAGE_BUFFER_LENGTH_TYPE )` wide,
17//! which is `size_t` unless a configuration says otherwise — eight bytes on
18//! the machine the oracle runs on. That width is in the arithmetic of every
19//! message send, so it is a [`Config`] const here rather than a guess.
20
21use rusty_rtos_core::config::Config;
22use rusty_rtos_core::error::{Error, Result};
23use rusty_rtos_core::handle::{StreamBufferHandle, TaskHandle};
24use rusty_rtos_core::hooks::TickHook;
25use rusty_rtos_core::isr::Woken;
26use rusty_rtos_core::port::Port;
27use rusty_rtos_core::trace::{Event, Trace};
28
29use crate::kernel::{Kernel, NotifyAction, OwedTrace};
30use crate::queue::{Blocked, Ready, Wait};
31
32/// One stream or message buffer.
33#[derive(Debug, Clone, Copy, Default)]
34pub(crate) struct StreamBuffer {
35    /// Where this buffer's bytes start in the kernel's byte arena.
36    pub(crate) base: usize,
37    /// `xLength`: the ring is one byte longer than the buffer asked for,
38    /// because a ring that is full and a ring that is empty would otherwise
39    /// look the same.
40    pub(crate) length: usize,
41    /// `xTriggerLevelBytes`.
42    pub(crate) trigger: usize,
43    /// `xHead`: where the next byte is written.
44    pub(crate) head: usize,
45    /// `xTail`: where the next byte is read.
46    pub(crate) tail: usize,
47    /// `xTaskWaitingToReceive`.
48    pub(crate) waiting_to_receive: TaskHandle,
49    /// `xTaskWaitingToSend`.
50    pub(crate) waiting_to_send: TaskHandle,
51    /// `sbFLAGS_IS_MESSAGE_BUFFER`.
52    pub(crate) is_message: bool,
53    /// `uxNotificationIndex`.
54    pub(crate) notify_index: usize,
55}
56
57impl StreamBuffer {
58    /// `prvBytesInBuffer`.
59    ///
60    /// The C adds the length before subtracting the tail so the unsigned
61    /// arithmetic cannot go below zero, then folds the extra length back
62    /// out. These are the C's own operations, and they need no checks for
63    /// the same reason the C's do not.
64    ///
65    /// `head` and `tail` are kept below `length` by the wrap arithmetic that
66    /// writes them, and `length` is at least 1. So `length + head` is at
67    /// most `2 * length - 1` and cannot overflow; `length + head - tail` is
68    /// at least `head + 1` and cannot underflow; and the fold only runs when
69    /// `count >= length`, where `count` is at most `2 * length - 1`, so it
70    /// lands back inside `0..length`.
71    pub(crate) const fn bytes_in_buffer(&self) -> usize {
72        let mut count = self.length.wrapping_add(self.head).wrapping_sub(self.tail);
73        if count >= self.length {
74            count = count.wrapping_sub(self.length);
75        }
76        count
77    }
78
79    /// `xStreamBufferSpacesAvailable`: one less than the gap, because the
80    /// ring keeps a spare byte so full and empty do not look alike.
81    ///
82    /// Bounded as [`StreamBuffer::bytes_in_buffer`] is, with one more step:
83    /// `length + tail - head` is at least 1, because `head` is at most
84    /// `length - 1`, so taking the spare byte off it cannot underflow.
85    pub(crate) const fn spaces_available(&self) -> usize {
86        let mut space = self
87            .length
88            .wrapping_add(self.tail)
89            .wrapping_sub(self.head)
90            .wrapping_sub(1);
91        if space >= self.length {
92            space = space.wrapping_sub(self.length);
93        }
94        space
95    }
96
97    /// `prvBytesInBufferMeetTriggerLevel`, for the two shapes that are not
98    /// a batching buffer.
99    pub(crate) const fn meets_trigger(&self, bytes: usize) -> bool {
100        bytes >= self.trigger
101    }
102}
103
104impl<
105    C: Config,
106    P: Port,
107    T: Trace,
108    H,
109    const TASKS: usize,
110    const ITEMS: usize,
111    const LISTS: usize,
112    const QUEUES: usize,
113    const SLOTS: usize,
114    const BUFFERS: usize,
115    const BYTES: usize,
116    const TIMERS: usize,
117    const GROUPS: usize,
118> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS>
119where
120    H: TickHook<Self>,
121{
122    /// How many bytes a message buffer spends on each message's length.
123    pub const MESSAGE_LENGTH_BYTES: usize = C::MESSAGE_LENGTH_BYTES;
124
125    /// `xStreamBufferCreate`.
126    ///
127    /// A trigger level of zero becomes one, as the C does: a reader that
128    /// woke on nothing would spin.
129    ///
130    /// # Errors
131    /// [`Error::Full`] when the buffer arena or the byte arena is full;
132    /// [`Error::InvalidArgument`] for a zero-length buffer.
133    pub fn stream_buffer_create(
134        &mut self,
135        size: usize,
136        trigger: usize,
137    ) -> Result<StreamBufferHandle> {
138        self.new_stream_buffer(size, trigger, false)
139    }
140
141    /// `xMessageBufferCreate`.
142    ///
143    /// # Errors
144    /// As [`Kernel::stream_buffer_create`]; a message buffer must also be
145    /// longer than one length prefix.
146    pub fn message_buffer_create(&mut self, size: usize) -> Result<StreamBufferHandle> {
147        if size <= Self::MESSAGE_LENGTH_BYTES {
148            return Err(Error::InvalidArgument);
149        }
150        self.new_stream_buffer(size, 1, true)
151    }
152
153    fn new_stream_buffer(
154        &mut self,
155        size: usize,
156        trigger: usize,
157        is_message: bool,
158    ) -> Result<StreamBufferHandle> {
159        let caller = self.current;
160        if size == 0 || trigger > size {
161            return Err(Error::InvalidArgument);
162        }
163        let trigger = if trigger == 0 { 1 } else { trigger };
164        // `xBufferSizeBytes++` before the allocation: the spare byte.
165        let length = size.saturating_add(1);
166        let base = self.take_bytes(length).ok_or(Error::Full)?;
167        let handle = self
168            .buffers
169            .try_insert(StreamBuffer {
170                base,
171                length,
172                trigger,
173                head: 0,
174                tail: 0,
175                waiting_to_receive: TaskHandle::NULL,
176                waiting_to_send: TaskHandle::NULL,
177                is_message,
178                notify_index: 0,
179            })
180            .map_err(|_| Error::Full)?;
181        self.account_for_allocation();
182        // The malloc's `xTaskResumeAll` can release a tick and switch us
183        // away, and the C's thread then stops there with
184        // `traceSTREAM_BUFFER_CREATE` still ahead of it -- so the line
185        // belongs to this task's NEXT run, not to whoever took the CPU.
186        self.trace_failure_or_owe(
187            caller,
188            OwedTrace::StreamBufferCreate {
189                buffer: handle,
190                is_message_buffer: is_message,
191            },
192        );
193        Ok(handle)
194    }
195
196    /// Take `length` bytes of the arena: first fit from what deleted
197    /// buffers gave back, and only then from the untouched end.
198    ///
199    /// First fit rather than best fit because the pattern that needs an
200    /// allocator at all is create-then-delete of the *same size*, which
201    /// first fit serves exactly and without fragmenting.
202    fn take_bytes(&mut self, length: usize) -> Option<usize> {
203        for i in 0..self.free_count {
204            let (base, free) = *self.free_blocks.get(i)?;
205            if free < length {
206                continue;
207            }
208            if free == length {
209                self.drop_free_block(i);
210            } else if let Some(slot) = self.free_blocks.get_mut(i) {
211                *slot = (base.saturating_add(length), free.saturating_sub(length));
212            }
213            return Some(base);
214        }
215        let end = self.bytes_used.checked_add(length)?;
216        if end > BYTES {
217            return None;
218        }
219        let base = self.bytes_used;
220        self.bytes_used = end;
221        Some(base)
222    }
223
224    /// Give a block back, coalescing with whichever neighbours touch it so
225    /// the list cannot grow past one entry per hole.
226    fn give_bytes(&mut self, base: usize, length: usize) {
227        let mut base = base;
228        let mut length = length;
229        let mut i = 0;
230        while i < self.free_count {
231            let Some(&(other_base, other_len)) = self.free_blocks.get(i) else {
232                break;
233            };
234            if other_base.saturating_add(other_len) == base {
235                base = other_base;
236                length = length.saturating_add(other_len);
237                self.drop_free_block(i);
238                continue;
239            }
240            if base.saturating_add(length) == other_base {
241                length = length.saturating_add(other_len);
242                self.drop_free_block(i);
243                continue;
244            }
245            i = i.saturating_add(1);
246        }
247        // A block at the very end goes back to the bump pointer instead of
248        // the list, which is what keeps a create/delete loop free.
249        if base.saturating_add(length) == self.bytes_used {
250            self.bytes_used = base;
251            return;
252        }
253        if let Some(slot) = self.free_blocks.get_mut(self.free_count) {
254            *slot = (base, length);
255            self.free_count = self.free_count.saturating_add(1);
256        }
257    }
258
259    fn drop_free_block(&mut self, index: usize) {
260        let last = self.free_count.saturating_sub(1);
261        if index < last {
262            if let Some(&moved) = self.free_blocks.get(last) {
263                if let Some(slot) = self.free_blocks.get_mut(index) {
264                    *slot = moved;
265                }
266            }
267        }
268        self.free_count = last;
269    }
270
271    /// `vStreamBufferDelete`: the handle goes stale and the ring's bytes go
272    /// back to the arena.
273    ///
274    /// # Errors
275    /// [`Error::Gone`] for a stale handle.
276    pub fn stream_buffer_delete(&mut self, buffer: StreamBufferHandle) -> Result<()> {
277        let b = *self.buffers.resolve(buffer)?;
278        let _ = self.buffers.remove(buffer);
279        self.give_bytes(b.base, b.length);
280        // `vStreamBufferDelete` ends in `vPortFree` (stream_buffer.c:582),
281        // and `heap_4` brackets that with `vTaskSuspendAll` /
282        // `xTaskResumeAll` -- which takes a critical section, and on the sim
283        // a critical-section exit is the clock. The create paid for its
284        // `pvPortMalloc` and the delete did not, so every deleted buffer
285        // lost one exit. `StreamBufferDemo`'s trigger-level test deletes one
286        // per pass and drifted by exactly 1 at its second `vTaskDelay`.
287        //
288        // The timer service's `Delete` arm had the identical defect.
289        self.account_for_allocation();
290        Ok(())
291    }
292
293    /// `xStreamBufferBytesAvailable`. No critical section, as in the C.
294    ///
295    /// # Errors
296    /// [`Error::Gone`] for a stale handle.
297    pub fn stream_buffer_bytes_available(&self, buffer: StreamBufferHandle) -> Result<usize> {
298        Ok(self.buffers.resolve(buffer)?.bytes_in_buffer())
299    }
300
301    /// `xStreamBufferSpacesAvailable`. No critical section, as in the C.
302    ///
303    /// # Errors
304    /// [`Error::Gone`] for a stale handle.
305    pub fn stream_buffer_spaces_available(&self, buffer: StreamBufferHandle) -> Result<usize> {
306        Ok(self.buffers.resolve(buffer)?.spaces_available())
307    }
308
309    /// `xStreamBufferIsEmpty`: head and tail in the same place.
310    ///
311    /// # Errors
312    /// [`Error::Gone`] for a stale handle.
313    pub fn stream_buffer_is_empty(&self, buffer: StreamBufferHandle) -> Result<bool> {
314        let b = self.buffers.resolve(buffer)?;
315        Ok(b.head == b.tail)
316    }
317
318    /// `xStreamBufferIsFull`: no room for another message.
319    ///
320    /// For a message buffer "another message" means at least one more byte
321    /// than its length prefix, so a buffer with exactly a prefix's worth of
322    /// room left is already full. A stream buffer compares against zero.
323    ///
324    /// # Errors
325    /// [`Error::Gone`] for a stale handle.
326    pub fn stream_buffer_is_full(&self, buffer: StreamBufferHandle) -> Result<bool> {
327        let b = self.buffers.resolve(buffer)?;
328        let prefix = if b.is_message {
329            Self::MESSAGE_LENGTH_BYTES
330        } else {
331            0
332        };
333        Ok(b.spaces_available() <= prefix)
334    }
335
336    /// `xStreamBufferSetTriggerLevel`.
337    ///
338    /// # Errors
339    /// [`Error::Gone`] for a stale handle.
340    pub fn stream_buffer_set_trigger_level(
341        &mut self,
342        buffer: StreamBufferHandle,
343        trigger: usize,
344    ) -> Result<bool> {
345        let length = self.buffers.resolve(buffer)?.length;
346        // Coerce first, then bounds-check, which is the order the C uses:
347        //
348        //     if( xTriggerLevel == ( size_t ) 0 ) { xTriggerLevel = 1; }
349        //     if( xTriggerLevel < pxStreamBuffer->xLength ) { ...pdPASS }
350        //     else { xReturn = pdFALSE; }
351        //
352        // The two orders disagree on exactly one input: a zero trigger
353        // against a length of ONE. Coercing first makes it 1, finds `1 < 1`
354        // false, and refuses without storing; bounds-checking first lets 0
355        // through and stores the coerced 1.
356        //
357        // THAT INPUT IS UNREACHABLE HERE, and the ordering is matched anyway
358        // rather than left to depend on it. `length` is `size + 1` -- the
359        // spare byte a ring buffer needs to tell full from empty, the C's
360        // own `xBufferSizeBytes++` -- and `size == 0` is refused at
361        // creation, so no buffer has a length of 1 and the orders agree on
362        // every input a caller can construct.
363        //
364        // Written down because the first version of this comment claimed a
365        // live divergence. It is not one; it is an inconsistency with the C
366        // that one arithmetic detail in a different function is keeping
367        // harmless.
368        let trigger = if trigger == 0 { 1 } else { trigger };
369        if trigger >= length {
370            return Ok(false);
371        }
372        self.buffers.resolve_mut(buffer)?.trigger = trigger;
373        Ok(true)
374    }
375
376    /// `xStreamBufferReset`: empty it, unless a task is waiting on it.
377    ///
378    /// # Errors
379    /// [`Error::Gone`] for a stale handle.
380    pub fn stream_buffer_reset(&mut self, buffer: StreamBufferHandle) -> Result<bool> {
381        self.enter_critical();
382        let done = match self.buffers.resolve_mut(buffer) {
383            Ok(b)
384                if b.waiting_to_receive == TaskHandle::NULL
385                    && b.waiting_to_send == TaskHandle::NULL =>
386            {
387                b.head = 0;
388                b.tail = 0;
389                true
390            }
391            _ => false,
392        };
393        self.exit_critical();
394        Ok(done)
395    }
396
397    /// `xStreamBufferNextMessageLengthBytes`.
398    ///
399    /// # Errors
400    /// [`Error::Gone`] for a stale handle.
401    pub fn stream_buffer_next_message_length(&self, buffer: StreamBufferHandle) -> Result<usize> {
402        let b = *self.buffers.resolve(buffer)?;
403        if !b.is_message {
404            return Ok(0);
405        }
406        let available = b.bytes_in_buffer();
407        if available <= Self::MESSAGE_LENGTH_BYTES {
408            return Ok(0);
409        }
410        Ok(self.read_length_prefix(&b, b.tail).0)
411    }
412
413    // ---------------------------------------------------------- sending --
414
415    /// `xTaskCheckForTimeOut`, the tail of `xStreamBufferSend`'s do-while.
416    ///
417    /// The C wraps the sample-and-wait in
418    /// `do { ... } while( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait )
419    /// == pdFALSE )`, and that call takes a critical section of its own
420    /// (tasks.c:5703) -- so on the sim it is one more exit, and one more
421    /// sixteenth of a tick.
422    ///
423    /// It runs **only when the wait actually blocked**: a send that finds
424    /// the space it needs on the first pass leaves the loop with a `break`
425    /// from inside the sampling section and never reaches the condition.
426    /// `xStreamBufferReceive` has no loop and no such call, which is why
427    /// this is on the send alone.
428    fn check_for_time_out(&mut self) {
429        self.enter_critical();
430        self.exit_critical();
431    }
432
433    /// `xStreamBufferSend`.
434    ///
435    /// Returns how many bytes went in. `Blocked` means the caller must
436    /// make the same call again: the C loops here waiting for space, and a
437    /// kernel with no stacks returns between passes.
438    ///
439    /// # Errors
440    /// [`Error::Gone`] for a stale handle.
441    /// Sim contract v2: what a kernel call costs when it took no critical
442    /// section.
443    ///
444    /// v1 had two tick sources, the idle hook and every 16th outermost
445    /// critical-section exit. Both are kernel-visible points, and between
446    /// them they left one hole: a task that is always ready and whose
447    /// no-progress path takes no critical section takes NO TIME, never
448    /// yields, and stops the clock for every other task.
449    ///
450    /// `xStreamBufferSend` and `xStreamBufferReceive` are the only calls in
451    /// this corpus that can return that way -- the zero-wait path reads the
452    /// ring and leaves. Every other object closes the hole by accident:
453    /// `uxQueueMessagesWaiting`, `eTaskGetState` and `uxTaskPriorityGet`
454    /// all take a section. `StreamBufferDemo`'s `prvNonBlockingReceiverTask`
455    /// is the task that found it, and under v1 the whole run froze at
456    /// `ticks=1 exits=16` (`docs/HOLES.md`, H9).
457    ///
458    /// So a blind call costs exactly one empty critical section. Not a new
459    /// clock -- the SAME one, so the count, the every-16th rule, the
460    /// running-task test and the switch all reuse paths v1 already proved,
461    /// and `exits` keeps its meaning: the number of kernel-visible points.
462    /// The C port does the identical thing from
463    /// `traceRETURN_xStreamBufferSend` / `..._Receive`; see
464    /// `vPortKairosApiReturn`.
465    ///
466    /// A call that BLOCKED is not blind: the C's thread stops inside it,
467    /// other tasks run, and the counter has moved by the time the return
468    /// hook is reached. Comparing the count is what says so on both sides.
469    fn blind_call(&mut self, exits_at_entry: u64) {
470        if self.port.exits() != exits_at_entry {
471            return;
472        }
473        self.enter_critical();
474        self.exit_critical();
475    }
476
477    /// `xStreamBufferSend`, with the contract-v2 bracket around it.
478    ///
479    /// # Errors
480    /// As [`Kernel::stream_buffer_send_inner`].
481    pub fn stream_buffer_send(
482        &mut self,
483        buffer: StreamBufferHandle,
484        data: &[u8],
485        ticks: u64,
486    ) -> Result<Wait<usize>> {
487        let entry = self.port.exits();
488        let out = self.stream_buffer_send_inner(buffer, data, ticks);
489        self.blind_call(entry);
490        out
491    }
492
493    fn stream_buffer_send_inner(
494        &mut self,
495        buffer: StreamBufferHandle,
496        data: &[u8],
497        ticks: u64,
498    ) -> Result<Wait<usize>> {
499        let caller = self.current;
500        let snapshot = *self.buffers.resolve(buffer)?;
501        let max_reported = snapshot.length.saturating_sub(1);
502        let mut required = data.len();
503        let mut ticks = ticks;
504        if snapshot.is_message {
505            required = required.saturating_add(Self::MESSAGE_LENGTH_BYTES);
506            if required > max_reported {
507                // It will never fit, so do not wait for it to.
508                ticks = 0;
509            }
510        } else if required > max_reported {
511            required = max_reported;
512        }
513
514        let mut sampled = self.take_stream_resume(caller);
515        if let Some(space) = sampled {
516            // Resuming after the exit that sampled the space. The same
517            // point as in `stream_buffer_receive`: the C tests `xSpace <
518            // xRequiredSpace` below the exit, against the sample taken
519            // inside it, so a task preempted there still blocks.
520            if space < required {
521                match self.notify_wait(snapshot.notify_index, 0, 0, ticks)? {
522                    Blocked => return Ok(Blocked),
523                    Ready(_) => {
524                        self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
525                        self.check_for_time_out();
526                        // The sample it went to sleep on is stale now, and
527                        // the C re-reads whenever that sample was zero.
528                        sampled = None;
529                    }
530                }
531            }
532        } else if self.notify_wait_pending(caller) {
533            match self.notify_wait(snapshot.notify_index, 0, 0, ticks)? {
534                Blocked => return Ok(Blocked),
535                Ready(_) => {}
536            }
537            self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
538            self.check_for_time_out();
539        } else if ticks > 0 {
540            // `vTaskSetTimeOutState( &xTimeOut )` (stream_buffer.c:878),
541            // which the C runs before it looks at the buffer at all.
542            //
543            // It is the PUBLIC entry point, so it takes a critical section
544            // of its own -- unlike the queue calls, which reach the same
545            // state through `vTaskInternalSetTimeOutState` from inside one.
546            // One exit per blocking send, and `StreamBufferDemo` makes the
547            // first of them 350 ticks in.
548            //
549            // ... and only once per call: a task preempted at this very
550            // exit resumes BELOW it, so re-entry must not buy it again.
551            if !self.take_stream_timed(caller) {
552                self.enter_critical();
553                self.exit_critical();
554                if self.current != caller {
555                    self.set_stream_timed(caller);
556                    return Ok(Blocked);
557                }
558            }
559            self.enter_critical();
560            let space = self.buffers.resolve(buffer)?.spaces_available();
561            let must_block = space < required;
562            if must_block {
563                let _ = self.notify_state_clear(None, snapshot.notify_index);
564                self.buffers.resolve_mut(buffer)?.waiting_to_send = caller;
565            }
566            self.exit_critical();
567            // That exit can release a tick, and a tick can switch this task
568            // away. The C's thread stops inside the exit and everything
569            // below it runs when the task is resumed — with the sample it
570            // already took, and without paying for the section twice.
571            if self.current != caller {
572                self.set_stream_resume(caller, space);
573                return Ok(Blocked);
574            }
575            if must_block {
576                // `traceBLOCKING_ON_STREAM_BUFFER_SEND` is not one of the
577                // harness's hooks, so blocking says nothing on either side.
578                match self.notify_wait(snapshot.notify_index, 0, 0, ticks)? {
579                    Blocked => return Ok(Blocked),
580                    Ready(_) => {
581                        self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
582                        self.check_for_time_out();
583                    }
584                }
585            }
586        }
587
588        let space = match sampled.take() {
589            Some(space) => space,
590            None => self.buffers.resolve(buffer)?.spaces_available(),
591        };
592        let written = self.write_message(buffer, data, space, required)?;
593        if written > 0 {
594            let tick = self.tick;
595            self.trace.note_exits(self.port.exits());
596            self.trace.event(
597                tick,
598                Event::StreamBufferSend {
599                    buffer,
600                    bytes: written,
601                },
602            );
603            // One resolve, not two: nothing moves between the byte count and
604            // the trigger test, and both read the same buffer. The block ends
605            // the borrow before the completion call needs `self` mutably.
606            let trigger = {
607                let b = self.buffers.resolve(buffer)?;
608                b.meets_trigger(b.bytes_in_buffer())
609            };
610            if trigger {
611                self.send_completed(buffer)?;
612            }
613        }
614        Ok(Ready(written))
615    }
616
617    /// `xStreamBufferSendFromISR`.
618    ///
619    /// # Errors
620    /// [`Error::Gone`] for a stale handle.
621    pub fn stream_buffer_send_from_isr(
622        &mut self,
623        buffer: StreamBufferHandle,
624        data: &[u8],
625    ) -> Result<(usize, Woken)> {
626        let snapshot = *self.buffers.resolve(buffer)?;
627        let max_reported = snapshot.length.saturating_sub(1);
628        let mut required = data.len();
629        if snapshot.is_message {
630            required = required.saturating_add(Self::MESSAGE_LENGTH_BYTES);
631        } else if required > max_reported {
632            required = max_reported;
633        }
634        let space = snapshot.spaces_available();
635        let written = self.write_message(buffer, data, space, required)?;
636        let mut woken = Woken::NO;
637        if written > 0 {
638            // `traceSTREAM_BUFFER_SEND_FROM_ISR` is a different macro from
639            // `traceSTREAM_BUFFER_SEND`, and the harness hooks only the
640            // latter — so an interrupt's send says nothing on either side.
641            // One resolve, not two: nothing moves between the byte count and
642            // the trigger test, and both read the same buffer. The block ends
643            // the borrow before the completion call needs `self` mutably.
644            let trigger = {
645                let b = self.buffers.resolve(buffer)?;
646                b.meets_trigger(b.bytes_in_buffer())
647            };
648            if trigger {
649                woken = self.send_completed_from_isr(buffer)?;
650            }
651        }
652        Ok((written, woken))
653    }
654
655    // -------------------------------------------------------- receiving --
656
657    /// What `xStreamBufferReceive` runs once its notify wait returns.
658    ///
659    /// `xTaskNotifyWaitIndexed`'s own trailing critical section can release
660    /// a tick and switch the caller away, and the C's thread then stops
661    /// THERE -- with `prvReadMessageFromBuffer` and
662    /// `traceSTREAM_BUFFER_RECEIVE` still ahead of it. So the bytes move,
663    /// and the line appears, on this task's next run and not inside
664    /// whoever took the CPU. `StreamBufferDemo`'s echo clients showed it
665    /// four times in a 2,000-tick run, each a receive traced six exits
666    /// early.
667    ///
668    /// `None` means "stop here"; the caller returns `Blocked` and the body
669    /// makes the same call again, which then takes the resume path.
670    fn after_stream_wait(
671        &mut self,
672        caller: TaskHandle,
673        buffer: StreamBufferHandle,
674    ) -> Result<Option<usize>> {
675        self.buffers.resolve_mut(buffer)?.waiting_to_receive = TaskHandle::NULL;
676        let available = self.buffers.resolve(buffer)?.bytes_in_buffer();
677        if self.current != caller {
678            self.set_stream_waited(caller);
679            self.set_stream_resume(caller, available);
680            return Ok(None);
681        }
682        Ok(Some(available))
683    }
684
685    /// `xStreamBufferReceive`: bytes into `out`, and how many arrived.
686    ///
687    /// # Errors
688    /// [`Error::Gone`] for a stale handle.
689    /// `xStreamBufferReceive`, with the contract-v2 bracket around it.
690    /// See [`Kernel::blind_call`].
691    ///
692    /// # Errors
693    /// As [`Kernel::stream_buffer_receive_inner`].
694    pub fn stream_buffer_receive(
695        &mut self,
696        buffer: StreamBufferHandle,
697        out: &mut [u8],
698        ticks: u64,
699    ) -> Result<Wait<usize>> {
700        let entry = self.port.exits();
701        let received = self.stream_buffer_receive_inner(buffer, out, ticks);
702        self.blind_call(entry);
703        received
704    }
705
706    fn stream_buffer_receive_inner(
707        &mut self,
708        buffer: StreamBufferHandle,
709        out: &mut [u8],
710        ticks: u64,
711    ) -> Result<Wait<usize>> {
712        let caller = self.current;
713        let snapshot = *self.buffers.resolve(buffer)?;
714        let prefix = if snapshot.is_message {
715            Self::MESSAGE_LENGTH_BYTES
716        } else {
717            0
718        };
719        let mut available;
720        if let Some(local) = self.take_stream_resume(caller) {
721            // Resuming after the exit that sampled the buffer.
722            //
723            // The C's thread stops inside `taskEXIT_CRITICAL`, and when it
724            // runs again it still evaluates the `if( xBytesAvailable <=
725            // xBytesToStoreMessageLength )` BELOW that exit -- against the
726            // sample it took inside the section. So a task preempted there
727            // goes on to block exactly like one that was not.
728            //
729            // Falling straight through to the read instead returns 0 from a
730            // call that was told to wait 350 ticks, which is what
731            // `StreamBufferDemo`'s lower-priority echo server caught: the C
732            // blocked at tick 1 and the sim created its client instead.
733            available = local;
734            if !self.take_stream_waited(caller) && available <= prefix {
735                match self.notify_wait(snapshot.notify_index, 0, 0, ticks)? {
736                    Blocked => return Ok(Blocked),
737                    Ready(_) => match self.after_stream_wait(caller, buffer)? {
738                        Some(now) => available = now,
739                        None => return Ok(Blocked),
740                    },
741                }
742            }
743        } else if self.notify_wait_pending(caller) {
744            // Resuming: the C's wait returns here, so its second half runs
745            // whatever the buffer now holds.
746            match self.notify_wait(snapshot.notify_index, 0, 0, ticks)? {
747                Blocked => return Ok(Blocked),
748                Ready(_) => {}
749            }
750            match self.after_stream_wait(caller, buffer)? {
751                Some(now) => available = now,
752                None => return Ok(Blocked),
753            }
754        } else if ticks > 0 {
755            self.enter_critical();
756            available = self.buffers.resolve(buffer)?.bytes_in_buffer();
757            let must_block = available <= prefix;
758            if must_block {
759                let _ = self.notify_state_clear(None, snapshot.notify_index);
760                self.buffers.resolve_mut(buffer)?.waiting_to_receive = caller;
761            }
762            self.exit_critical();
763            // That exit can release a tick, and a tick can switch this task
764            // away. The C's thread stops inside the exit and everything
765            // below it runs when the task is resumed — with the sample it
766            // already took, and without paying for the section twice.
767            if self.current != caller {
768                self.set_stream_resume(caller, available);
769                return Ok(Blocked);
770            }
771            if must_block {
772                match self.notify_wait(snapshot.notify_index, 0, 0, ticks)? {
773                    Blocked => return Ok(Blocked),
774                    Ready(_) => match self.after_stream_wait(caller, buffer)? {
775                        Some(now) => available = now,
776                        None => return Ok(Blocked),
777                    },
778                }
779            }
780        } else {
781            available = self.buffers.resolve(buffer)?.bytes_in_buffer();
782        }
783
784        let mut received = 0;
785        if available > prefix {
786            received = self.read_message(buffer, out, available)?;
787            if received != 0 {
788                let tick = self.tick;
789                self.trace.note_exits(self.port.exits());
790                self.trace.event(
791                    tick,
792                    Event::StreamBufferReceive {
793                        buffer,
794                        bytes: received,
795                    },
796                );
797                self.receive_completed(buffer)?;
798            }
799        }
800        Ok(Ready(received))
801    }
802
803    /// `xStreamBufferReceiveFromISR`.
804    ///
805    /// # Errors
806    /// [`Error::Gone`] for a stale handle.
807    pub fn stream_buffer_receive_from_isr(
808        &mut self,
809        buffer: StreamBufferHandle,
810        out: &mut [u8],
811    ) -> Result<(usize, Woken)> {
812        let snapshot = *self.buffers.resolve(buffer)?;
813        let prefix = if snapshot.is_message {
814            Self::MESSAGE_LENGTH_BYTES
815        } else {
816            0
817        };
818        let available = snapshot.bytes_in_buffer();
819        let mut received = 0;
820        let mut woken = Woken::NO;
821        if available > prefix {
822            received = self.read_message(buffer, out, available)?;
823            if received != 0 {
824                // `traceSTREAM_BUFFER_RECEIVE_FROM_ISR`, likewise unhooked.
825                woken = self.receive_completed_from_isr(buffer)?;
826            }
827        }
828        Ok((received, woken))
829    }
830
831    // --------------------------------------------------- the completions --
832
833    /// `sbSEND_COMPLETED`: tell a waiting reader, with the scheduler
834    /// suspended so the notify cannot switch away mid-update.
835    ///
836    /// The application may replace it — that is what the macro is for, and
837    /// `MessageBufferAMP` is the demo that does — so the hook gets first
838    /// refusal and `true` means it handled the whole thing.
839    // No `inline`: one was tried and cost 323,801 instructions on
840    // `StreamBufferDemo`. The body is small but it is reached from inside
841    // `stream_buffer_send`, which is already large.
842    fn send_completed(&mut self, buffer: StreamBufferHandle) -> Result<()> {
843        if H::send_completed(self, buffer) {
844            return Ok(());
845        }
846        self.suspend_all();
847        let waiting = self.buffers.resolve(buffer)?.waiting_to_receive;
848        if waiting != TaskHandle::NULL {
849            let index = self.buffers.resolve(buffer)?.notify_index;
850            let _ = self.notify(waiting, index, 0, NotifyAction::None)?;
851            self.buffers.resolve_mut(buffer)?.waiting_to_receive = TaskHandle::NULL;
852        }
853        let _ = self.resume_all();
854        Ok(())
855    }
856
857    /// `xStreamBufferSendCompletedFromISR` / `sbSEND_COMPLETED_FROM_ISR`.
858    ///
859    /// Public because an application that replaced [`TickHook::send_completed`]
860    /// has to be able to do the notify itself, later and from interrupt
861    /// context — which is exactly what `MessageBufferAMP` does once its
862    /// stand-in interrupt has read the handle back off the control buffer.
863    ///
864    /// # Errors
865    /// [`Error::Gone`] for a stale handle.
866    pub fn send_completed_from_isr(&mut self, buffer: StreamBufferHandle) -> Result<Woken> {
867        let waiting = self.buffers.resolve(buffer)?.waiting_to_receive;
868        if waiting == TaskHandle::NULL {
869            return Ok(Woken::NO);
870        }
871        let index = self.buffers.resolve(buffer)?.notify_index;
872        let (_, woken) = self.notify_from_isr(waiting, index, 0, NotifyAction::None)?;
873        self.buffers.resolve_mut(buffer)?.waiting_to_receive = TaskHandle::NULL;
874        Ok(woken)
875    }
876
877    /// `sbRECEIVE_COMPLETED`.
878    fn receive_completed(&mut self, buffer: StreamBufferHandle) -> Result<()> {
879        self.suspend_all();
880        let waiting = self.buffers.resolve(buffer)?.waiting_to_send;
881        if waiting != TaskHandle::NULL {
882            let index = self.buffers.resolve(buffer)?.notify_index;
883            let _ = self.notify(waiting, index, 0, NotifyAction::None)?;
884            self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
885        }
886        let _ = self.resume_all();
887        Ok(())
888    }
889
890    /// `sbRECEIVE_COMPLETED_FROM_ISR`.
891    fn receive_completed_from_isr(&mut self, buffer: StreamBufferHandle) -> Result<Woken> {
892        let waiting = self.buffers.resolve(buffer)?.waiting_to_send;
893        if waiting == TaskHandle::NULL {
894            return Ok(Woken::NO);
895        }
896        let index = self.buffers.resolve(buffer)?.notify_index;
897        let (_, woken) = self.notify_from_isr(waiting, index, 0, NotifyAction::None)?;
898        self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
899        Ok(woken)
900    }
901
902    // ------------------------------------------------ the ring itself --
903
904    /// `prvWriteMessageToBuffer`.
905    fn write_message(
906        &mut self,
907        buffer: StreamBufferHandle,
908        data: &[u8],
909        space: usize,
910        required: usize,
911    ) -> Result<usize> {
912        let b = *self.buffers.resolve(buffer)?;
913        let mut next_head = b.head;
914        let mut length = data.len();
915        let mut space = space;
916        if b.is_message {
917            if space >= required {
918                next_head = self.write_length_prefix(&b, length, next_head);
919            } else {
920                length = 0;
921            }
922            space = space.saturating_sub(Self::MESSAGE_LENGTH_BYTES);
923        }
924        let length = length.min(space);
925        if length != 0 {
926            let chunk = data.get(..length).unwrap_or(data);
927            let head = self.write_bytes(&b, chunk, next_head);
928            self.buffers.resolve_mut(buffer)?.head = head;
929        }
930        Ok(length)
931    }
932
933    /// `prvReadMessageFromBuffer`.
934    fn read_message(
935        &mut self,
936        buffer: StreamBufferHandle,
937        out: &mut [u8],
938        available: usize,
939    ) -> Result<usize> {
940        let b = *self.buffers.resolve(buffer)?;
941        let mut next_tail = b.tail;
942        let mut available = available;
943        let next_length;
944        if b.is_message {
945            let (message_length, tail) = self.read_length_prefix(&b, next_tail);
946            next_tail = tail;
947            available = available.saturating_sub(Self::MESSAGE_LENGTH_BYTES);
948            next_length = if message_length > out.len() {
949                // The C returns nothing rather than half a message.
950                0
951            } else {
952                message_length
953            };
954        } else {
955            next_length = out.len();
956        }
957        let count = next_length.min(available);
958        if count != 0 {
959            let slot = out.get_mut(..count);
960            let tail = match slot {
961                Some(slot) => self.read_bytes(&b, slot, next_tail),
962                None => next_tail,
963            };
964            self.buffers.resolve_mut(buffer)?.tail = tail;
965        }
966        Ok(count)
967    }
968
969    /// `prvWriteBytesToBuffer`: the ring wrap, in two `memcpy`s.
970    ///
971    /// The index arithmetic here is `wrapping_*`, because the geometry has
972    /// already bounded every term: `head` is below `length`, `base + length`
973    /// is at most `BYTES`, `first` is `min(len, upto)` so `len - first`
974    /// cannot go below zero, and `head + first` is at most `length` -- which
975    /// the fold on the line after turns back into 0, exactly as `wrap_next`
976    /// does. Each index then passes through a `get_mut` that refuses
977    /// anything the ring does not own.
978    fn write_bytes(&mut self, b: &StreamBuffer, data: &[u8], head: usize) -> usize {
979        // The two copies the doc above describes, and the two the C makes.
980        // Taken only when the payload fits the ring once -- which is the only
981        // shape that reaches here, because a send larger than the buffer is
982        // refused before this -- so a payload that would wrap more than once
983        // still walks the original loop and behaves exactly as it did.
984        if data.len() <= b.length {
985            let upto = b.length.wrapping_sub(head);
986            let first = data.len().min(upto);
987            let from = b.base.wrapping_add(head);
988            if let (Some(dst), Some(src)) = (
989                self.bytes.get_mut(from..from.wrapping_add(first)),
990                data.get(..first),
991            ) {
992                dst.copy_from_slice(src);
993            }
994            let rest = data.len().wrapping_sub(first);
995            if rest > 0 {
996                if let (Some(dst), Some(src)) = (
997                    self.bytes.get_mut(b.base..b.base.wrapping_add(rest)),
998                    data.get(first..),
999                ) {
1000                    dst.copy_from_slice(src);
1001                }
1002                return rest;
1003            }
1004            let next = head.wrapping_add(first);
1005            return if next >= b.length { 0 } else { next };
1006        }
1007
1008        let mut head = head;
1009        for byte in data {
1010            if let Some(slot) = self.bytes.get_mut(b.base.wrapping_add(head)) {
1011                *slot = *byte;
1012            }
1013            head = head.wrapping_add(1);
1014            if head >= b.length {
1015                head = 0;
1016            }
1017        }
1018        head
1019    }
1020
1021    /// `prvReadBytesFromBuffer`.
1022    ///
1023    /// Bounded as [`Kernel::write_bytes`] is, and for the same reasons.
1024    fn read_bytes(&mut self, b: &StreamBuffer, out: &mut [u8], tail: usize) -> usize {
1025        // The mirror of `write_bytes`: two copies rather than a byte at a
1026        // time, taken only when the request fits the ring once.
1027        if out.len() <= b.length {
1028            let upto = b.length.wrapping_sub(tail);
1029            let first = out.len().min(upto);
1030            let from = b.base.wrapping_add(tail);
1031            if let (Some(dst), Some(src)) = (
1032                out.get_mut(..first),
1033                self.bytes.get(from..from.wrapping_add(first)),
1034            ) {
1035                dst.copy_from_slice(src);
1036            }
1037            let rest = out.len().wrapping_sub(first);
1038            if rest > 0 {
1039                if let (Some(dst), Some(src)) = (
1040                    out.get_mut(first..),
1041                    self.bytes.get(b.base..b.base.wrapping_add(rest)),
1042                ) {
1043                    dst.copy_from_slice(src);
1044                }
1045                return rest;
1046            }
1047            let next = tail.wrapping_add(first);
1048            return if next >= b.length { 0 } else { next };
1049        }
1050
1051        let mut tail = tail;
1052        for slot in out.iter_mut() {
1053            *slot = self
1054                .bytes
1055                .get(b.base.wrapping_add(tail))
1056                .copied()
1057                .unwrap_or(0);
1058            tail = tail.wrapping_add(1);
1059            if tail >= b.length {
1060                tail = 0;
1061            }
1062        }
1063        tail
1064    }
1065
1066    /// The message length, written little-endian across
1067    /// [`Kernel::MESSAGE_LENGTH_BYTES`] bytes of the ring.
1068    fn write_length_prefix(&mut self, b: &StreamBuffer, length: usize, head: usize) -> usize {
1069        let bytes = (length as u64).to_le_bytes();
1070        // The prefix is bytes in the ring like any other, and `write_bytes`
1071        // already wraps in two copies -- this loop was a third hand-rolled
1072        // version of the same walk.
1073        let prefix = bytes.get(..Self::MESSAGE_LENGTH_BYTES).unwrap_or(&bytes);
1074        self.write_bytes(b, prefix, head)
1075    }
1076
1077    /// The message length back out, and where the message starts.
1078    /// Bounded as [`Kernel::read_bytes`] is, and converted for the same
1079    /// reasons: `tail` is below `length`, `base + length` is at most
1080    /// `BYTES`, `first` is `min(want, upto)`, and every index passes through
1081    /// a `get` that refuses anything the ring does not own.
1082    fn read_length_prefix(&self, b: &StreamBuffer, tail: usize) -> (usize, usize) {
1083        let mut raw = [0_u8; 8];
1084        let want = Self::MESSAGE_LENGTH_BYTES;
1085
1086        // Two reads rather than a byte at a time, the way the write side now
1087        // writes it. `read_bytes` would do this, but it needs `&mut self` and
1088        // this does not have it.
1089        if want <= b.length {
1090            let upto = b.length.wrapping_sub(tail);
1091            let first = want.min(upto);
1092            let from = b.base.wrapping_add(tail);
1093            if let (Some(dst), Some(src)) = (
1094                raw.get_mut(..first),
1095                self.bytes.get(from..from.wrapping_add(first)),
1096            ) {
1097                dst.copy_from_slice(src);
1098            }
1099            let rest = want.wrapping_sub(first);
1100            if rest > 0 {
1101                if let (Some(dst), Some(src)) = (
1102                    raw.get_mut(first..want),
1103                    self.bytes.get(b.base..b.base.wrapping_add(rest)),
1104                ) {
1105                    dst.copy_from_slice(src);
1106                }
1107                return (u64::from_le_bytes(raw) as usize, rest);
1108            }
1109            let next = tail.wrapping_add(first);
1110            let next = if next >= b.length { 0 } else { next };
1111            return (u64::from_le_bytes(raw) as usize, next);
1112        }
1113
1114        let mut tail = tail;
1115        for i in 0..want {
1116            let byte = self
1117                .bytes
1118                .get(b.base.wrapping_add(tail))
1119                .copied()
1120                .unwrap_or(0);
1121            if let Some(slot) = raw.get_mut(i) {
1122                *slot = byte;
1123            }
1124            tail = tail.wrapping_add(1);
1125            if tail >= b.length {
1126                tail = 0;
1127            }
1128        }
1129        (u64::from_le_bytes(raw) as usize, tail)
1130    }
1131}
1132
1133// ================================================================ tests ==
1134
1135/// `stream.rs` had no unit test at all, and six of its APIs are also the
1136/// ones no conformance scenario reaches (`docs/HOLES.md`, H2 and H3). For
1137/// those, the only evidence available is a semantic audit against the C
1138/// source plus tests that pin what it says.
1139///
1140/// So every test here quotes the `stream_buffer.c` line it is pinning, and
1141/// pins **the C's contract** rather than this kernel's behaviour. A test
1142/// written the other way round proves only that the code still does what it
1143/// did, which is worth having and is not evidence of conformance.
1144#[cfg(test)]
1145#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
1146mod tests {
1147    use rusty_rtos_core::config::Config;
1148    use rusty_rtos_core::hooks::NoTickHook;
1149
1150    use crate::queue::Wait;
1151    use crate::system::tests::{NoTrace, TestConfig, TestPort};
1152
1153    /// A kernel with buffers, which `system!` never declares: the macro
1154    /// sizes `BUFFERS` and `BYTES` at zero. Four tasks is the idle task,
1155    /// the timer daemon and one of our own, with room to spare.
1156    type K = crate::Kernel<
1157        TestConfig,
1158        TestPort,
1159        NoTrace,
1160        NoTickHook,
1161        4,
1162        { crate::list_slots_for(4, 0, crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0)) },
1163        { crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0) },
1164        1,
1165        1,
1166        2,
1167        64,
1168        0,
1169        0,
1170    >;
1171
1172    fn kernel() -> K {
1173        K::new(TestPort::default(), NoTrace).expect("the declared geometry adds up")
1174    }
1175
1176    /// The header a message buffer writes in front of every message.
1177    const HDR: usize = K::MESSAGE_LENGTH_BYTES;
1178
1179    /// `xStreamBufferIsEmpty`:
1180    ///
1181    /// ```c
1182    /// if( pxStreamBuffer->xHead == xTail ) { xReturn = pdTRUE; }
1183    /// ```
1184    ///
1185    /// Head-equals-tail, which is emptiness and NOT "nothing readable" --
1186    /// the two differ on a message buffer holding only a header, which the
1187    /// zero-length-message test below pins.
1188    #[test]
1189    fn is_empty_is_head_equals_tail() {
1190        let mut k = kernel();
1191        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1192        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1193
1194        k.stream_buffer_send(b, b"abc", 0).expect("send");
1195        assert_eq!(k.stream_buffer_is_empty(b), Ok(false));
1196
1197        let mut out = [0_u8; 8];
1198        k.stream_buffer_receive(b, &mut out, 0).expect("receive");
1199        assert_eq!(
1200            k.stream_buffer_is_empty(b),
1201            Ok(true),
1202            "drained is empty again, wherever head and tail have walked to"
1203        );
1204    }
1205
1206    /// `xStreamBufferIsFull` on a STREAM buffer:
1207    ///
1208    /// ```c
1209    /// xBytesToStoreMessageLength = 0;   /* not a message buffer */
1210    /// if( xStreamBufferSpacesAvailable( xStreamBuffer ) <= xBytesToStoreMessageLength )
1211    /// ```
1212    ///
1213    /// so full is exactly "no spaces left".
1214    #[test]
1215    fn is_full_on_a_stream_buffer_means_no_spaces_at_all() {
1216        let mut k = kernel();
1217        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1218        assert_eq!(k.stream_buffer_spaces_available(b), Ok(8));
1219        assert_eq!(k.stream_buffer_is_full(b), Ok(false));
1220
1221        k.stream_buffer_send(b, b"1234567", 0).expect("send seven");
1222        assert_eq!(k.stream_buffer_spaces_available(b), Ok(1));
1223        assert_eq!(
1224            k.stream_buffer_is_full(b),
1225            Ok(false),
1226            "one free byte is not full on a STREAM buffer"
1227        );
1228
1229        k.stream_buffer_send(b, b"8", 0).expect("send the last");
1230        assert_eq!(k.stream_buffer_spaces_available(b), Ok(0));
1231        assert_eq!(k.stream_buffer_is_full(b), Ok(true));
1232    }
1233
1234    /// `xStreamBufferIsFull` on a MESSAGE buffer, which is the one that
1235    /// surprises:
1236    ///
1237    /// ```c
1238    /// if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != 0 )
1239    ///     xBytesToStoreMessageLength = sbBYTES_TO_STORE_MESSAGE_LENGTH;
1240    /// if( xStreamBufferSpacesAvailable( xStreamBuffer ) <= xBytesToStoreMessageLength )
1241    /// ```
1242    ///
1243    /// `<=`, against the size of the LENGTH HEADER rather than against
1244    /// zero. So a message buffer reports FULL while it still has free
1245    /// bytes, because those bytes could not hold even a zero-length
1246    /// message's header.
1247    ///
1248    /// A caller that polls `is_full` and expects `spaces_available() == 0`
1249    /// is wrong by up to a header, and only on message buffers.
1250    #[test]
1251    fn is_full_on_a_message_buffer_leaves_a_header_of_bytes_free() {
1252        let mut k = kernel();
1253        let b = k.message_buffer_create(8).expect("a message buffer");
1254        assert_eq!(k.stream_buffer_spaces_available(b), Ok(8));
1255        assert_eq!(k.stream_buffer_is_full(b), Ok(false));
1256
1257        // One three-byte message costs the header plus the payload.
1258        k.stream_buffer_send(b, b"abc", 0).expect("send");
1259        let spaces = k.stream_buffer_spaces_available(b).expect("spaces");
1260        assert_eq!(spaces, 8 - (HDR + 3));
1261        assert!(spaces > 0, "there ARE free bytes");
1262        assert!(spaces <= HDR, "but not enough for another header");
1263        assert_eq!(
1264            k.stream_buffer_is_full(b),
1265            Ok(true),
1266            "full with {spaces} byte(s) free: the C compares against the header, not zero"
1267        );
1268    }
1269
1270    /// `xStreamBufferNextMessageLengthBytes` on a stream buffer:
1271    ///
1272    /// ```c
1273    /// if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != 0 ) { ... }
1274    /// else { xReturn = 0; }
1275    /// ```
1276    ///
1277    /// Zero for a stream buffer NO MATTER WHAT IT HOLDS. That is not "no
1278    /// message waiting", it is "the question does not apply" -- and the
1279    /// return type cannot tell a caller which of the two it got.
1280    #[test]
1281    fn next_message_length_is_zero_on_a_stream_buffer_however_full() {
1282        let mut k = kernel();
1283        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1284        assert_eq!(k.stream_buffer_next_message_length(b), Ok(0));
1285
1286        k.stream_buffer_send(b, b"abcde", 0).expect("send");
1287        assert_eq!(k.stream_buffer_bytes_available(b), Ok(5));
1288        assert_eq!(
1289            k.stream_buffer_next_message_length(b),
1290            Ok(0),
1291            "five bytes waiting and still zero, because it is not a message buffer"
1292        );
1293    }
1294
1295    /// The same call on a message buffer PEEKS:
1296    ///
1297    /// ```c
1298    /// ( void ) prvReadBytesFromBuffer( pxStreamBuffer, ..., pxStreamBuffer->xTail );
1299    /// ```
1300    ///
1301    /// It reads at the tail without advancing it, so asking twice answers
1302    /// twice and the message is still there to be received.
1303    #[test]
1304    fn next_message_length_peeks_and_does_not_consume() {
1305        let mut k = kernel();
1306        let b = k.message_buffer_create(16).expect("a message buffer");
1307        k.stream_buffer_send(b, b"hello", 0).expect("send");
1308
1309        assert_eq!(k.stream_buffer_next_message_length(b), Ok(5));
1310        assert_eq!(
1311            k.stream_buffer_next_message_length(b),
1312            Ok(5),
1313            "asking did not consume it"
1314        );
1315
1316        let mut out = [0_u8; 16];
1317        assert_eq!(k.stream_buffer_receive(b, &mut out, 0), Ok(Wait::Ready(5)));
1318        assert_eq!(&out[..5], b"hello");
1319        assert_eq!(k.stream_buffer_next_message_length(b), Ok(0), "drained");
1320    }
1321
1322    /// A zero-length message is a NO-OP that is indistinguishable from a
1323    /// send that failed -- which is not visible from the call site, and is
1324    /// the sort of thing only a source audit finds.
1325    ///
1326    /// `prvWriteMessageToBuffer`:
1327    ///
1328    /// ```c
1329    /// if( message buffer ) {
1330    ///     xMessageLength = ( configMESSAGE_BUFFER_LENGTH_TYPE ) xDataLengthBytes;  /* 0 */
1331    ///     if( xSpace >= xRequiredSpace ) {
1332    ///         xNextHead = prvWriteBytesToBuffer( pxStreamBuffer, &xMessageLength,
1333    ///                                            sbBYTES_TO_STORE_MESSAGE_LENGTH, xNextHead );
1334    ///     }
1335    /// }
1336    /// if( xDataLengthBytes != ( size_t ) 0 ) {
1337    ///     pxStreamBuffer->xHead = prvWriteBytesToBuffer( ..., xNextHead );
1338    /// }
1339    /// return xDataLengthBytes;
1340    /// ```
1341    ///
1342    /// The header IS written into the storage array -- but the new position
1343    /// goes into `xNextHead`, a LOCAL. `pxStreamBuffer->xHead` is only
1344    /// committed inside the `xDataLengthBytes != 0` branch, which a
1345    /// zero-length message does not take.
1346    ///
1347    /// So the bytes are in the array and the buffer does not know it: the
1348    /// head never moves, the buffer stays empty, the call returns 0, and
1349    /// the next send writes over them. A caller cannot tell this apart from
1350    /// a send that was refused for want of space.
1351    ///
1352    /// Pinned because the earlier version of this test asserted the
1353    /// opposite -- that the header would show up in `bytes_available` --
1354    /// and the kernel was right.
1355    #[test]
1356    fn a_zero_length_message_is_a_no_op_that_looks_like_a_failed_send() {
1357        let mut k = kernel();
1358        let b = k.message_buffer_create(16).expect("a message buffer");
1359        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1360
1361        assert_eq!(
1362            k.stream_buffer_send(b, b"", 0),
1363            Ok(Wait::Ready(0)),
1364            "zero bytes written, which is also what a refused send answers"
1365        );
1366        assert_eq!(
1367            k.stream_buffer_bytes_available(b),
1368            Ok(0),
1369            "the header went into the array and the head was never committed"
1370        );
1371        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1372        assert_eq!(k.stream_buffer_next_message_length(b), Ok(0));
1373
1374        // And a real message lands in the same place, over the top of it.
1375        k.stream_buffer_send(b, b"ok", 0).expect("a real message");
1376        assert_eq!(k.stream_buffer_next_message_length(b), Ok(2));
1377        let mut out = [0_u8; 16];
1378        assert_eq!(k.stream_buffer_receive(b, &mut out, 0), Ok(Wait::Ready(2)));
1379        assert_eq!(&out[..2], b"ok");
1380        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1381    }
1382
1383    /// `xStreamBufferReset`:
1384    ///
1385    /// ```c
1386    /// if( ( pxStreamBuffer->xTaskWaitingToReceive == NULL ) &&
1387    ///     ( pxStreamBuffer->xTaskWaitingToSend == NULL ) )
1388    /// {
1389    ///     prvInitialiseNewStreamBuffer( ..., pxStreamBuffer->xTriggerLevelBytes, ... );
1390    ///     xReturn = pdPASS;
1391    /// }
1392    /// ```
1393    ///
1394    /// The buffer's own trigger level is passed straight back in, so a
1395    /// reset empties the buffer and KEEPS the trigger. It is not a return
1396    /// to the creation default, which is what the name suggests.
1397    #[test]
1398    fn reset_empties_the_buffer_and_keeps_the_trigger_level() {
1399        let mut k = kernel();
1400        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1401        assert_eq!(k.stream_buffer_set_trigger_level(b, 5), Ok(true));
1402        k.stream_buffer_send(b, b"abcd", 0).expect("send");
1403        assert_eq!(k.stream_buffer_bytes_available(b), Ok(4));
1404
1405        assert_eq!(k.stream_buffer_reset(b), Ok(true));
1406        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1407        assert_eq!(k.stream_buffer_bytes_available(b), Ok(0));
1408        assert_eq!(
1409            k.stream_buffer_spaces_available(b),
1410            Ok(8),
1411            "the whole usable length is back"
1412        );
1413    }
1414
1415    /// The other half of that guard: a reset must REFUSE while a task is
1416    /// blocked on the buffer, because reinitialising would drop the handle
1417    /// that task is waiting on.
1418    #[test]
1419    fn reset_refuses_while_a_task_is_waiting_to_receive() {
1420        let mut k = kernel();
1421        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1422        k.create_task("rx", 1).expect("a task");
1423        let started = k.start_scheduler().expect("start");
1424        k.suspend(Some(started.timer)).expect("park the daemon");
1425
1426        // Run until our task is the one on the CPU, then block it.
1427        let mut out = [0_u8; 8];
1428        let mut blocked = false;
1429        for _ in 0..50_u32 {
1430            let running = k.name_of(k.current()).expect("a running task has a name");
1431            if running.as_str() == "rx" {
1432                assert_eq!(
1433                    k.stream_buffer_receive(b, &mut out, 20),
1434                    Ok(Wait::Blocked),
1435                    "an empty buffer with a timeout blocks"
1436                );
1437                blocked = true;
1438                break;
1439            }
1440            k.switch_context();
1441        }
1442        assert!(blocked, "never got the task onto the CPU");
1443
1444        assert_eq!(
1445            k.stream_buffer_reset(b),
1446            Ok(false),
1447            "a waiting receiver refuses the reset"
1448        );
1449    }
1450
1451    /// `xStreamBufferReceiveFromISR` never blocks: it takes a whole
1452    /// message, or nothing.
1453    #[test]
1454    fn receive_from_isr_takes_a_whole_message_or_nothing() {
1455        let mut k = kernel();
1456        let b = k.message_buffer_create(16).expect("a message buffer");
1457        let mut out = [0_u8; 16];
1458
1459        let (n, _) = k.stream_buffer_receive_from_isr(b, &mut out).expect("isr");
1460        assert_eq!(n, 0, "nothing waiting, and it did not block");
1461
1462        k.stream_buffer_send(b, b"xy", 0).expect("send");
1463        let (n, _) = k.stream_buffer_receive_from_isr(b, &mut out).expect("isr");
1464        assert_eq!(n, 2);
1465        assert_eq!(&out[..2], b"xy");
1466        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1467    }
1468
1469    /// `bytes_available` and `spaces_available` partition the USABLE
1470    /// length, which is one less than the ring's own -- the spare byte that
1471    /// tells full from empty, the C's `xBufferSizeBytes++` at creation.
1472    #[test]
1473    fn bytes_and_spaces_partition_the_usable_length() {
1474        let mut k = kernel();
1475        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1476        for n in 0..=8_usize {
1477            let bytes = k.stream_buffer_bytes_available(b).expect("bytes");
1478            let spaces = k.stream_buffer_spaces_available(b).expect("spaces");
1479            assert_eq!(
1480                bytes.saturating_add(spaces),
1481                8,
1482                "at {n} byte(s) in: {bytes} + {spaces} should be the usable 8"
1483            );
1484            if n < 8 {
1485                k.stream_buffer_send(b, b"z", 0).expect("send one");
1486            }
1487        }
1488    }
1489    /// A STREAM buffer takes a partial write; a MESSAGE buffer is
1490    /// all-or-nothing. `prvWriteMessageToBuffer`:
1491    ///
1492    /// ```c
1493    /// if( message buffer ) {
1494    ///     if( xSpace >= xRequiredSpace ) { ...write the header... }
1495    ///     else { xDataLengthBytes = 0; }          /* nothing at all */
1496    /// } else {
1497    ///     xDataLengthBytes = configMIN( xDataLengthBytes, xSpace );   /* as much as fits */
1498    /// }
1499    /// ```
1500    ///
1501    /// So the same call with the same arguments loses the tail on one kind
1502    /// and loses everything on the other, and the return value is the only
1503    /// way to tell which happened.
1504    #[test]
1505    fn a_stream_takes_a_partial_write_and_a_message_is_all_or_nothing() {
1506        let mut k = kernel();
1507        let s = k.stream_buffer_create(8, 1).expect("a stream buffer");
1508        k.stream_buffer_send(s, b"123456", 0).expect("six");
1509        assert_eq!(
1510            k.stream_buffer_send(s, b"789", 0),
1511            Ok(Wait::Ready(2)),
1512            "two of the three fit, and two is what it took"
1513        );
1514        assert_eq!(k.stream_buffer_spaces_available(s), Ok(0));
1515
1516        let mut k = kernel();
1517        let m = k.message_buffer_create(8).expect("a message buffer");
1518        // One message of two costs the header plus two: six of the eight.
1519        k.stream_buffer_send(m, b"xy", 0)
1520            .expect("the first message");
1521        assert_eq!(
1522            k.stream_buffer_send(m, b"zzz", 0),
1523            Ok(Wait::Ready(0)),
1524            "the header plus three does not fit, so NOTHING was written"
1525        );
1526        assert_eq!(
1527            k.stream_buffer_next_message_length(m),
1528            Ok(2),
1529            "and the message already there is untouched"
1530        );
1531    }
1532
1533    /// `xStreamBufferSendFromISR` writes what fits and never blocks -- the
1534    /// same body as the task-side send with the block time forced to zero.
1535    #[test]
1536    fn send_from_isr_writes_what_fits_and_never_blocks() {
1537        let mut k = kernel();
1538        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1539
1540        let (n, _) = k.stream_buffer_send_from_isr(b, b"abc").expect("isr");
1541        assert_eq!(n, 3);
1542        assert_eq!(k.stream_buffer_bytes_available(b), Ok(3));
1543
1544        // Past the end: it takes the five that fit rather than waiting.
1545        let (n, _) = k.stream_buffer_send_from_isr(b, b"defghijkl").expect("isr");
1546        assert_eq!(n, 5, "five of the nine fit");
1547        assert_eq!(k.stream_buffer_is_full(b), Ok(true));
1548
1549        let (n, _) = k.stream_buffer_send_from_isr(b, b"m").expect("isr");
1550        assert_eq!(n, 0, "full, and it still did not block");
1551    }
1552
1553    /// A round trip through the two ISR halves, which is what an
1554    /// interrupt-driven driver actually does.
1555    #[test]
1556    fn a_message_survives_a_round_trip_through_both_isr_halves() {
1557        let mut k = kernel();
1558        let b = k.message_buffer_create(16).expect("a message buffer");
1559        let (n, _) = k.stream_buffer_send_from_isr(b, b"ping").expect("isr");
1560        assert_eq!(n, 4);
1561
1562        let mut out = [0_u8; 16];
1563        let (n, _) = k.stream_buffer_receive_from_isr(b, &mut out).expect("isr");
1564        assert_eq!(n, 4);
1565        assert_eq!(&out[..4], b"ping");
1566        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1567    }
1568}