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 core::num::NonZeroU64;
22
23use rusty_rtos_core::config::Config;
24use rusty_rtos_core::error::{Error, Result};
25use rusty_rtos_core::handle::{QueueHandle, StreamBufferHandle, TaskHandle};
26use rusty_rtos_core::hooks::TickHook;
27use rusty_rtos_core::isr::Woken;
28use rusty_rtos_core::port::Port;
29use rusty_rtos_core::trace::{Event, Trace};
30
31use crate::kernel::{Kernel, NotifyAction, OwedTrace};
32use crate::queue::{Blocked, Ready, Wait};
33
34/// One stream or message buffer.
35#[derive(Debug, Clone, Copy, Default)]
36pub(crate) struct StreamBuffer {
37    /// Where this buffer's bytes start in the kernel's byte arena.
38    pub(crate) base: usize,
39    /// `xLength`: the ring is one byte longer than the buffer asked for,
40    /// because a ring that is full and a ring that is empty would otherwise
41    /// look the same.
42    pub(crate) length: usize,
43    /// `xTriggerLevelBytes`.
44    pub(crate) trigger: usize,
45    /// `xHead`: where the next byte is written.
46    pub(crate) head: usize,
47    /// `xTail`: where the next byte is read.
48    pub(crate) tail: usize,
49    /// `xTaskWaitingToReceive`.
50    pub(crate) waiting_to_receive: TaskHandle,
51    /// `xTaskWaitingToSend`.
52    pub(crate) waiting_to_send: TaskHandle,
53    /// `sbFLAGS_IS_MESSAGE_BUFFER`.
54    pub(crate) is_message: bool,
55    /// `uxNotificationIndex`.
56    pub(crate) notify_index: usize,
57}
58
59impl StreamBuffer {
60    /// `prvBytesInBuffer`.
61    ///
62    /// The C adds the length before subtracting the tail so the unsigned
63    /// arithmetic cannot go below zero, then folds the extra length back
64    /// out. These are the C's own operations, and they need no checks for
65    /// the same reason the C's do not.
66    ///
67    /// `head` and `tail` are kept below `length` by the wrap arithmetic that
68    /// writes them, and `length` is at least 1. So `length + head` is at
69    /// most `2 * length - 1` and cannot overflow; `length + head - tail` is
70    /// at least `head + 1` and cannot underflow; and the fold only runs when
71    /// `count >= length`, where `count` is at most `2 * length - 1`, so it
72    /// lands back inside `0..length`.
73    #[inline]
74    pub(crate) const fn bytes_in_buffer(&self) -> usize {
75        let mut count = self.length.wrapping_add(self.head).wrapping_sub(self.tail);
76        if count >= self.length {
77            count = count.wrapping_sub(self.length);
78        }
79        count
80    }
81
82    /// `xStreamBufferSpacesAvailable`: one less than the gap, because the
83    /// ring keeps a spare byte so full and empty do not look alike.
84    ///
85    /// Bounded as [`StreamBuffer::bytes_in_buffer`] is, with one more step:
86    /// `length + tail - head` is at least 1, because `head` is at most
87    /// `length - 1`, so taking the spare byte off it cannot underflow.
88    #[inline]
89    pub(crate) const fn spaces_available(&self) -> usize {
90        let mut space = self
91            .length
92            .wrapping_add(self.tail)
93            .wrapping_sub(self.head)
94            .wrapping_sub(1);
95        if space >= self.length {
96            space = space.wrapping_sub(self.length);
97        }
98        space
99    }
100
101    /// `prvBytesInBufferMeetTriggerLevel`, for the two shapes that are not
102    /// a batching buffer.
103    pub(crate) const fn meets_trigger(&self, bytes: usize) -> bool {
104        bytes >= self.trigger
105    }
106}
107
108impl<
109    C: Config,
110    P: Port,
111    T: Trace,
112    H,
113    const TASKS: usize,
114    const ITEMS: usize,
115    const LISTS: usize,
116    const QUEUES: usize,
117    const SLOTS: usize,
118    const BUFFERS: usize,
119    const BYTES: usize,
120    const TIMERS: usize,
121    const GROUPS: usize,
122    const TIMER_CMDS: usize,
123> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS, TIMER_CMDS>
124where
125    H: TickHook<Self>,
126{
127    /// How many bytes a message buffer spends on each message's length.
128    pub const MESSAGE_LENGTH_BYTES: usize = C::MESSAGE_LENGTH_BYTES;
129
130    /// The key a blocking `xStreamBufferSend` files its `TimeOut_t` under
131    /// in the task's wait frame, which is keyed by queue. Index `u32::MAX`
132    /// is past `Handle::MAX_INDEX`, so no queue is ever this one, and a task
133    /// is inside one blocking call at a time.
134    const STREAM_SEND_WAIT: QueueHandle = QueueHandle::from_parts(u32::MAX, 1);
135
136    /// `xStreamBufferCreate`.
137    ///
138    /// A trigger level of zero becomes one, as the C does: a reader that
139    /// woke on nothing would spin.
140    ///
141    /// # Errors
142    /// [`Error::Full`] when the buffer arena or the byte arena is full;
143    /// [`Error::InvalidArgument`] for a zero-length buffer.
144    pub fn stream_buffer_create(
145        &mut self,
146        size: usize,
147        trigger: usize,
148    ) -> Result<StreamBufferHandle> {
149        self.new_stream_buffer(size, trigger, false)
150    }
151
152    /// `xMessageBufferCreate`.
153    ///
154    /// # Errors
155    /// As [`Kernel::stream_buffer_create`]; a message buffer must also be
156    /// longer than one length prefix.
157    pub fn message_buffer_create(&mut self, size: usize) -> Result<StreamBufferHandle> {
158        if size <= Self::MESSAGE_LENGTH_BYTES {
159            return Err(Error::InvalidArgument);
160        }
161        self.new_stream_buffer(size, 1, true)
162    }
163
164    fn new_stream_buffer(
165        &mut self,
166        size: usize,
167        trigger: usize,
168        is_message: bool,
169    ) -> Result<StreamBufferHandle> {
170        let caller = self.cur();
171        if size == 0 || trigger > size {
172            return Err(Error::InvalidArgument);
173        }
174        let trigger = if trigger == 0 { 1 } else { trigger };
175        // `xBufferSizeBytes++` before the allocation: the spare byte.
176        let length = size.saturating_add(1);
177        let base = self.take_bytes(length).ok_or(Error::Full)?;
178        let handle = self
179            .buffers
180            .try_insert(StreamBuffer {
181                base,
182                length,
183                trigger,
184                head: 0,
185                tail: 0,
186                waiting_to_receive: TaskHandle::NULL,
187                waiting_to_send: TaskHandle::NULL,
188                is_message,
189                notify_index: 0,
190            })
191            .map_err(|_| Error::Full)?;
192        self.account_for_allocation();
193        // The malloc's `xTaskResumeAll` can release a tick and switch us
194        // away, and the C's thread then stops there with
195        // `traceSTREAM_BUFFER_CREATE` still ahead of it -- so the line
196        // belongs to this task's NEXT run, not to whoever took the CPU.
197        self.trace_failure_or_owe(
198            caller,
199            OwedTrace::StreamBufferCreate {
200                buffer: handle,
201                is_message_buffer: is_message,
202            },
203        );
204        Ok(handle)
205    }
206
207    /// Take `length` bytes of the arena: first fit from what deleted
208    /// buffers gave back, and only then from the untouched end.
209    ///
210    /// First fit rather than best fit because the pattern that needs an
211    /// allocator at all is create-then-delete of the *same size*, which
212    /// first fit serves exactly and without fragmenting.
213    fn take_bytes(&mut self, length: usize) -> Option<usize> {
214        for i in 0..self.free_count {
215            let (base, free) = *self.free_blocks.get(i)?;
216            if free < length {
217                continue;
218            }
219            if free == length {
220                self.drop_free_block(i);
221            } else if let Some(slot) = self.free_blocks.get_mut(i) {
222                *slot = (base.saturating_add(length), free.wrapping_sub(length));
223            }
224            return Some(base);
225        }
226        let end = self.bytes_used.checked_add(length)?;
227        if end > BYTES {
228            return None;
229        }
230        let base = self.bytes_used;
231        self.bytes_used = end;
232        Some(base)
233    }
234
235    /// Give a block back, coalescing with whichever neighbours touch it so
236    /// the list cannot grow past one entry per hole.
237    fn give_bytes(&mut self, base: usize, length: usize) {
238        let mut base = base;
239        let mut length = length;
240        let mut i = 0;
241        while i < self.free_count {
242            let Some(&(other_base, other_len)) = self.free_blocks.get(i) else {
243                break;
244            };
245            if other_base.saturating_add(other_len) == base {
246                base = other_base;
247                length = length.saturating_add(other_len);
248                self.drop_free_block(i);
249                continue;
250            }
251            if base.saturating_add(length) == other_base {
252                length = length.saturating_add(other_len);
253                self.drop_free_block(i);
254                continue;
255            }
256            i = i.wrapping_add(1);
257        }
258        // A block at the very end goes back to the bump pointer instead of
259        // the list, which is what keeps a create/delete loop free.
260        if base.saturating_add(length) == self.bytes_used {
261            self.bytes_used = base;
262            return;
263        }
264        if let Some(slot) = self.free_blocks.get_mut(self.free_count) {
265            *slot = (base, length);
266            self.free_count = self.free_count.wrapping_add(1);
267        }
268    }
269
270    fn drop_free_block(&mut self, index: usize) {
271        let last = self.free_count.saturating_sub(1);
272        if index < last {
273            if let Some(&moved) = self.free_blocks.get(last) {
274                if let Some(slot) = self.free_blocks.get_mut(index) {
275                    *slot = moved;
276                }
277            }
278        }
279        self.free_count = last;
280    }
281
282    /// `vStreamBufferDelete`: the handle goes stale and the ring's bytes go
283    /// back to the arena.
284    ///
285    /// # Errors
286    /// [`Error::Gone`] for a stale handle.
287    pub fn stream_buffer_delete(&mut self, buffer: StreamBufferHandle) -> Result<()> {
288        let b = *self.buffers.resolve(buffer)?;
289        let _ = self.buffers.discard(buffer);
290        self.give_bytes(b.base, b.length);
291        // `vStreamBufferDelete` ends in `vPortFree` (stream_buffer.c:582),
292        // and `heap_4` brackets that with `vTaskSuspendAll` /
293        // `xTaskResumeAll` -- which takes a critical section, and on the sim
294        // a critical-section exit is the clock. The create paid for its
295        // `pvPortMalloc` and the delete did not, so every deleted buffer
296        // lost one exit. `StreamBufferDemo`'s trigger-level test deletes one
297        // per pass and drifted by exactly 1 at its second `vTaskDelay`.
298        //
299        // The timer service's `Delete` arm had the identical defect.
300        self.account_for_allocation();
301        Ok(())
302    }
303
304    /// `xStreamBufferBytesAvailable`. No critical section, as in the C.
305    ///
306    /// # Errors
307    /// [`Error::Gone`] for a stale handle.
308    pub fn stream_buffer_bytes_available(&self, buffer: StreamBufferHandle) -> Result<usize> {
309        Ok(self.buffers.resolve(buffer)?.bytes_in_buffer())
310    }
311
312    /// `xStreamBufferSpacesAvailable`. No critical section, as in the C.
313    ///
314    /// # Errors
315    /// [`Error::Gone`] for a stale handle.
316    pub fn stream_buffer_spaces_available(&self, buffer: StreamBufferHandle) -> Result<usize> {
317        Ok(self.buffers.resolve(buffer)?.spaces_available())
318    }
319
320    /// `xStreamBufferIsEmpty`: head and tail in the same place.
321    ///
322    /// # Errors
323    /// [`Error::Gone`] for a stale handle.
324    pub fn stream_buffer_is_empty(&self, buffer: StreamBufferHandle) -> Result<bool> {
325        let b = self.buffers.resolve(buffer)?;
326        Ok(b.head == b.tail)
327    }
328
329    /// `xStreamBufferIsFull`: no room for another message.
330    ///
331    /// For a message buffer "another message" means at least one more byte
332    /// than its length prefix, so a buffer with exactly a prefix's worth of
333    /// room left is already full. A stream buffer compares against zero.
334    ///
335    /// # Errors
336    /// [`Error::Gone`] for a stale handle.
337    pub fn stream_buffer_is_full(&self, buffer: StreamBufferHandle) -> Result<bool> {
338        let b = self.buffers.resolve(buffer)?;
339        let prefix = if b.is_message {
340            Self::MESSAGE_LENGTH_BYTES
341        } else {
342            0
343        };
344        Ok(b.spaces_available() <= prefix)
345    }
346
347    /// `xStreamBufferSetTriggerLevel`.
348    ///
349    /// # Errors
350    /// [`Error::Gone`] for a stale handle.
351    pub fn stream_buffer_set_trigger_level(
352        &mut self,
353        buffer: StreamBufferHandle,
354        trigger: usize,
355    ) -> Result<bool> {
356        let length = self.buffers.resolve(buffer)?.length;
357        // Coerce first, then bounds-check, which is the order the C uses:
358        //
359        //     if( xTriggerLevel == ( size_t ) 0 ) { xTriggerLevel = 1; }
360        //     if( xTriggerLevel < pxStreamBuffer->xLength ) { ...pdPASS }
361        //     else { xReturn = pdFALSE; }
362        //
363        // The two orders disagree on exactly one input: a zero trigger
364        // against a length of ONE. Coercing first makes it 1, finds `1 < 1`
365        // false, and refuses without storing; bounds-checking first lets 0
366        // through and stores the coerced 1.
367        //
368        // THAT INPUT IS UNREACHABLE HERE, and the ordering is matched anyway
369        // rather than left to depend on it. `length` is `size + 1` -- the
370        // spare byte a ring buffer needs to tell full from empty, the C's
371        // own `xBufferSizeBytes++` -- and `size == 0` is refused at
372        // creation, so no buffer has a length of 1 and the orders agree on
373        // every input a caller can construct.
374        //
375        // Written down because the first version of this comment claimed a
376        // live divergence. It is not one; it is an inconsistency with the C
377        // that one arithmetic detail in a different function is keeping
378        // harmless.
379        let trigger = if trigger == 0 { 1 } else { trigger };
380        if trigger >= length {
381            return Ok(false);
382        }
383        self.buffers.resolve_mut(buffer)?.trigger = trigger;
384        Ok(true)
385    }
386
387    /// `xStreamBufferReset`: empty it, unless a task is waiting on it.
388    ///
389    /// # Errors
390    /// [`Error::Gone`] for a stale handle.
391    pub fn stream_buffer_reset(&mut self, buffer: StreamBufferHandle) -> Result<bool> {
392        self.enter_critical();
393        let done = match self.buffers.resolve_mut(buffer) {
394            Ok(b) if b.waiting_to_receive.is_null() && b.waiting_to_send.is_null() => {
395                b.head = 0;
396                b.tail = 0;
397                true
398            }
399            _ => false,
400        };
401        self.exit_critical();
402        Ok(done)
403    }
404
405    /// `xStreamBufferNextMessageLengthBytes`.
406    ///
407    /// # Errors
408    /// [`Error::Gone`] for a stale handle.
409    pub fn stream_buffer_next_message_length(&self, buffer: StreamBufferHandle) -> Result<usize> {
410        let b = *self.buffers.resolve(buffer)?;
411        if !b.is_message {
412            return Ok(0);
413        }
414        let available = b.bytes_in_buffer();
415        if available <= Self::MESSAGE_LENGTH_BYTES {
416            return Ok(0);
417        }
418        Ok(Self::read_length_prefix_from(&self.bytes, b.base, b.length, b.tail).0)
419    }
420
421    // ---------------------------------------------------------- sending --
422
423    /// `xStreamBufferSend`.
424    ///
425    /// Returns how many bytes went in. `Blocked` means the caller must
426    /// make the same call again: the C loops here waiting for space, and a
427    /// kernel with no stacks returns between passes.
428    ///
429    /// # Errors
430    /// [`Error::Gone`] for a stale handle.
431    /// Sim contract v2: what a kernel call costs when it took no critical
432    /// section.
433    ///
434    /// v1 had two tick sources, the idle hook and every 16th outermost
435    /// critical-section exit. Both are kernel-visible points, and between
436    /// them they left one hole: a task that is always ready and whose
437    /// no-progress path takes no critical section takes NO TIME, never
438    /// yields, and stops the clock for every other task.
439    ///
440    /// `xStreamBufferSend` and `xStreamBufferReceive` are the only calls in
441    /// this corpus that can return that way -- the zero-wait path reads the
442    /// ring and leaves. Every other object closes the hole by accident:
443    /// `uxQueueMessagesWaiting`, `eTaskGetState` and `uxTaskPriorityGet`
444    /// all take a section. `StreamBufferDemo`'s `prvNonBlockingReceiverTask`
445    /// is the task that found it, and under v1 the whole run froze at
446    /// `ticks=1 exits=16` (`docs/HOLES.md`, H9).
447    ///
448    /// So a blind call costs exactly one empty critical section. Not a new
449    /// clock -- the SAME one, so the count, the every-16th rule, the
450    /// running-task test and the switch all reuse paths v1 already proved,
451    /// and `exits` keeps its meaning: the number of kernel-visible points.
452    /// The C port does the identical thing from
453    /// `traceRETURN_xStreamBufferSend` / `..._Receive`; see
454    /// `vPortKairosApiReturn`.
455    ///
456    /// A call that BLOCKED is not blind: the C's thread stops inside it,
457    /// other tasks run, and the counter has moved by the time the return
458    /// hook is reached. Comparing the count is what says so on both sides.
459    ///
460    /// Gated on `T::EMITS`, for the same reason [`Kernel::note_exits`] is, and
461    /// to MATCH the C rather than diverge from it. In the C this bracket is
462    /// `traceRETURN_xStreamBufferSend`, which `FreeRTOS.h` defines as **empty**
463    /// unless a config wires it. Only `oracle/harness/FreeRTOSConfig.h` does --
464    /// the sim. `bench/kernel-ram/c/FreeRTOSConfig.h`, which the rv32 flash arm
465    /// compiles against, defines no `traceRETURN_*` at all, so **C pays zero
466    /// bytes for it in the arm we measure** while we were paying for it
467    /// unconditionally. Same defect class as relaxation being off on our arm
468    /// only (scorecard 14).
469    ///
470    /// Nothing observes the bracket under a silent sink: the exits counter it
471    /// samples is read by no one, and the critical section it takes is a closed
472    /// window that restores the mask it found. Under an emitting sink -- which
473    /// is every `conform` scenario -- the gate is true and the behaviour is
474    /// exactly as before, which is why 26/26 is unchanged.
475    fn blind_call(&mut self, exits_at_entry: u64) {
476        if !T::EMITS {
477            return;
478        }
479        if self.port.exits() != exits_at_entry {
480            return;
481        }
482        self.enter_critical();
483        self.exit_critical();
484    }
485
486    /// `xStreamBufferSend`, with the contract-v2 bracket around it.
487    ///
488    /// # Errors
489    /// As [`Kernel::stream_buffer_send_inner`].
490    pub fn stream_buffer_send(
491        &mut self,
492        buffer: StreamBufferHandle,
493        data: &[u8],
494        ticks: u64,
495    ) -> Result<Wait<usize>> {
496        let entry = if T::EMITS { self.port.exits() } else { 0 };
497        let out = self.stream_buffer_send_inner(buffer, data, ticks);
498        self.blind_call(entry);
499        out
500    }
501
502    fn stream_buffer_send_inner(
503        &mut self,
504        buffer: StreamBufferHandle,
505        data: &[u8],
506        ticks: u64,
507    ) -> Result<Wait<usize>> {
508        let caller = self.cur();
509        // ONLY the fields this body reads. It was `*self.buffers.resolve(..)`
510        // -- the whole nine-field descriptor, about thirty-two bytes on rv32 --
511        // to reach three of them. `notify_index` is read at four
512        // points spread across the body, each behind an `&mut self` call, so
513        // the descriptor had to stay LIVE across all of them and was spilled
514        // for it. Two scalars live in registers. Same finding as `queue_take`:
515        // the cost was the live range, not the copy.
516        let (is_message, length, notify_index) = {
517            let b = self.buffers.resolve(buffer)?;
518            (b.is_message, b.length, b.notify_index)
519        };
520        let max_reported = length.saturating_sub(1);
521        let mut required = data.len();
522        let mut ticks = ticks;
523        if is_message {
524            required = required.saturating_add(Self::MESSAGE_LENGTH_BYTES);
525            if required > max_reported {
526                // It will never fit, so do not wait for it to.
527                ticks = 0;
528            }
529        } else if required > max_reported {
530            required = max_reported;
531        }
532
533        // The do-while's condition, `xTaskCheckForTimeOut(..) == pdFALSE`:
534        // `Some(left)` goes round again with what is left of the block time,
535        // `None` leaves the loop. Set by whichever arm finished a wait.
536        let mut again: Option<u64> = None;
537        let mut sampled = self.take_stream_resume(caller);
538        if let Some(space) = sampled {
539            // Resuming after the exit that sampled the space. The same
540            // point as in `stream_buffer_receive`: the C tests `xSpace <
541            // xRequiredSpace` below the exit, against the sample taken
542            // inside it, so a task preempted there still blocks.
543            if space < required {
544                // What is left of the block time: the frame is this call's,
545                // so `begin_wait` answers it without touching it.
546                let left = self
547                    .begin_wait(caller, Self::STREAM_SEND_WAIT, ticks)
548                    .unwrap_or(0);
549                match self.notify_wait(notify_index, 0, 0, left)? {
550                    Blocked => {
551                        self.park_stream_sample(caller, space);
552                        return Ok(Blocked);
553                    }
554                    Ready(_) => {
555                        self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
556                        again = self.check_for_timeout(caller).map(NonZeroU64::get);
557                    }
558                }
559            }
560        } else if self.notify_wait_pending(caller) {
561            match self.notify_wait(notify_index, 0, 0, ticks)? {
562                Blocked => return Ok(Blocked),
563                Ready(_) => {}
564            }
565            // Spelled out at both resume arms and in the loop rather than
566            // factored into a helper the way the receive side's
567            // `after_stream_wait` is. Factoring it measured **+28 B** on
568            // 2026-09-25, identical with and without `#[inline(never)]` -- so
569            // LLVM outlines it either way, and one shared body plus three
570            // calls costs more than three copies that each fold against their
571            // own arm.
572            self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
573            sampled = Some(self.stream_sample(caller));
574            again = self.check_for_timeout(caller).map(NonZeroU64::get);
575        } else if ticks > 0 {
576            // `vTaskSetTimeOutState( &xTimeOut )` (stream_buffer.c:878),
577            // which the C runs before it looks at the buffer at all.
578            //
579            // It is the PUBLIC entry point, so it takes a critical section
580            // of its own -- unlike the queue calls, which reach the same
581            // state through `vTaskInternalSetTimeOutState` from inside one.
582            // One exit per blocking send, and `StreamBufferDemo` makes the
583            // first of them 350 ticks in.
584            //
585            // ... and only once per call: a task preempted at this very
586            // exit resumes BELOW it, so re-entry must not buy it again.
587            if !self.take_stream_timed(caller) {
588                self.enter_critical();
589                // A fresh `TimeOut_t` every call, as the C's is a local:
590                // a frame an erroring call left behind must not be reused.
591                self.end_wait(caller);
592                let _ = self.begin_wait(caller, Self::STREAM_SEND_WAIT, ticks);
593                self.exit_critical();
594                if self.cur() != caller {
595                    self.set_stream_timed(caller);
596                    return Ok(Blocked);
597                }
598            }
599            again = Some(ticks);
600        }
601
602        // `do { ... } while( xTaskCheckForTimeOut( &xTimeOut, &xTicksToWait )
603        // == pdFALSE )`. A wake is not a verdict: the receiver notifies on
604        // every read, and if that freed too little the C samples again and
605        // blocks again for what is left. One pass and a partial write was
606        // what the API differential caught (one core, step 9106).
607        while let Some(left) = again {
608            self.enter_critical();
609            let space = self.buffers.resolve(buffer)?.spaces_available();
610            let must_block = space < required;
611            if must_block {
612                let _ = self.notify_state_clear(None, notify_index);
613                self.buffers.resolve_mut(buffer)?.waiting_to_send = caller;
614            }
615            self.exit_critical();
616            sampled = Some(space);
617            // That exit can release a tick, and a tick can switch this task
618            // away. The C's thread stops inside the exit and everything
619            // below it runs when the task is resumed — with the sample it
620            // already took, and without paying for the section twice.
621            if self.cur() != caller {
622                self.set_stream_resume(caller, space);
623                return Ok(Blocked);
624            }
625            if !must_block {
626                break;
627            }
628            // `traceBLOCKING_ON_STREAM_BUFFER_SEND` is not one of the
629            // harness's hooks, so blocking says nothing on either side.
630            match self.notify_wait(notify_index, 0, 0, left)? {
631                Blocked => {
632                    self.park_stream_sample(caller, space);
633                    return Ok(Blocked);
634                }
635                Ready(_) => {
636                    self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
637                    again = self.check_for_timeout(caller).map(NonZeroU64::get);
638                }
639            }
640        }
641        self.end_wait(caller);
642
643        // `if( xSpace == 0 ) xSpace = xStreamBufferSpacesAvailable(..)`: the
644        // last sample stands, stale or not, unless it was zero -- which a
645        // send that never sampled (no block time) always is.
646        let space = match sampled.take() {
647            Some(space) if space != 0 => space,
648            _ => self.buffers.resolve(buffer)?.spaces_available(),
649        };
650        let written = self.write_message(buffer, data, space, required)?;
651        if written > 0 {
652            let tick = self.tick;
653            self.note_exits();
654            self.trace.event(
655                tick,
656                Event::StreamBufferSend {
657                    buffer,
658                    bytes: written,
659                },
660            );
661            // One resolve, not two: nothing moves between the byte count and
662            // the trigger test, and both read the same buffer. The block ends
663            // the borrow before the completion call needs `self` mutably.
664            let trigger = {
665                let b = self.buffers.resolve(buffer)?;
666                b.meets_trigger(b.bytes_in_buffer())
667            };
668            if trigger {
669                self.send_completed(buffer)?;
670            }
671        }
672        Ok(Ready(written))
673    }
674
675    /// `xStreamBufferSendFromISR`.
676    ///
677    /// # Errors
678    /// [`Error::Gone`] for a stale handle.
679    pub fn stream_buffer_send_from_isr(
680        &mut self,
681        buffer: StreamBufferHandle,
682        data: &[u8],
683    ) -> Result<(usize, Woken)> {
684        let snapshot = *self.buffers.resolve(buffer)?;
685        let max_reported = snapshot.length.saturating_sub(1);
686        let mut required = data.len();
687        if snapshot.is_message {
688            required = required.saturating_add(Self::MESSAGE_LENGTH_BYTES);
689        } else if required > max_reported {
690            required = max_reported;
691        }
692        let space = snapshot.spaces_available();
693        let written = self.write_message(buffer, data, space, required)?;
694        let mut woken = Woken::NO;
695        if written > 0 {
696            // `traceSTREAM_BUFFER_SEND_FROM_ISR` is a different macro from
697            // `traceSTREAM_BUFFER_SEND`, and the harness hooks only the
698            // latter — so an interrupt's send says nothing on either side.
699            // One resolve, not two: nothing moves between the byte count and
700            // the trigger test, and both read the same buffer. The block ends
701            // the borrow before the completion call needs `self` mutably.
702            let trigger = {
703                let b = self.buffers.resolve(buffer)?;
704                b.meets_trigger(b.bytes_in_buffer())
705            };
706            if trigger {
707                woken = self.send_completed_from_isr(buffer)?;
708            }
709        }
710        Ok((written, woken))
711    }
712
713    // -------------------------------------------------------- receiving --
714
715    /// What `xStreamBufferReceive` runs once its notify wait returns.
716    ///
717    /// `xTaskNotifyWaitIndexed`'s own trailing critical section can release
718    /// a tick and switch the caller away, and the C's thread then stops
719    /// THERE -- with `prvReadMessageFromBuffer` and
720    /// `traceSTREAM_BUFFER_RECEIVE` still ahead of it. So the bytes move,
721    /// and the line appears, on this task's next run and not inside
722    /// whoever took the CPU. `StreamBufferDemo`'s echo clients showed it
723    /// four times in a 2,000-tick run, each a receive traced six exits
724    /// early.
725    ///
726    /// `None` means "stop here"; the caller returns `Blocked` and the body
727    /// makes the same call again, which then takes the resume path.
728    // In line at all THREE callers, which are all inside
729    // `stream_buffer_receive_inner`.
730    //
731    // This said "A3: ONE caller in the linked kernel, so this pays a prologue
732    // and epilogue for a single call" until 2026-09-25. The caller count was
733    // simply wrong -- there are three -- so the A3 argument did not apply, and
734    // with three callers `#[inline]` DUPLICATES the body rather than moving it,
735    // which is the opposite of what the comment claimed.
736    //
737    // The decision survives the correction, measured: `#[inline(never)]` costs
738    // **+100 B** (receive 732 -> 686, but a 146 B symbol appears). Each inlined
739    // copy folds to roughly fifteen bytes against the surrounding control flow,
740    // while a standalone body pays a frame and two real handle resolves. Right
741    // answer, wrong reason, now with a number.
742    #[inline(always)]
743    fn after_stream_wait(
744        &mut self,
745        caller: TaskHandle,
746        buffer: StreamBufferHandle,
747    ) -> Result<Option<usize>> {
748        self.buffers.resolve_mut(buffer)?.waiting_to_receive = TaskHandle::NULL;
749        let available = self.buffers.resolve(buffer)?.bytes_in_buffer();
750        if self.cur() != caller {
751            // Merging these two into one accessor that resolves the TCB once
752            // measured **0 B** on 2026-09-25: `&mut self` is `noalias`, so LLVM
753            // had already shared the resolve across both setters. `list.rs`'s
754            // fourth pass says exactly this, and it applies to the TCB flag
755            // accessors too. Merging adjacent accessors only pays when an
756            // `&mut self` call stands BETWEEN them.
757            self.set_stream_waited(caller);
758            self.set_stream_resume(caller, available);
759            return Ok(None);
760        }
761        Ok(Some(available))
762    }
763
764    /// `xStreamBufferReceive`: bytes into `out`, and how many arrived.
765    ///
766    /// # Errors
767    /// [`Error::Gone`] for a stale handle.
768    /// `xStreamBufferReceive`, with the contract-v2 bracket around it.
769    /// See [`Kernel::blind_call`].
770    ///
771    /// # Errors
772    /// As [`Kernel::stream_buffer_receive_inner`].
773    pub fn stream_buffer_receive(
774        &mut self,
775        buffer: StreamBufferHandle,
776        out: &mut [u8],
777        ticks: u64,
778    ) -> Result<Wait<usize>> {
779        let entry = if T::EMITS { self.port.exits() } else { 0 };
780        let received = self.stream_buffer_receive_inner(buffer, out, ticks);
781        self.blind_call(entry);
782        received
783    }
784
785    fn stream_buffer_receive_inner(
786        &mut self,
787        buffer: StreamBufferHandle,
788        out: &mut [u8],
789        ticks: u64,
790    ) -> Result<Wait<usize>> {
791        let caller = self.cur();
792        // ONLY the fields this body reads. It was `*self.buffers.resolve(..)`
793        // -- the whole nine-field descriptor, about thirty-two bytes on rv32 --
794        // to reach two of them. `notify_index` is read at four
795        // points spread across the body, each behind an `&mut self` call, so
796        // the descriptor had to stay LIVE across all of them and was spilled
797        // for it. Two scalars live in registers. Same finding as `queue_take`:
798        // the cost was the live range, not the copy.
799        let (is_message, notify_index) = {
800            let b = self.buffers.resolve(buffer)?;
801            (b.is_message, b.notify_index)
802        };
803        let prefix = if is_message {
804            Self::MESSAGE_LENGTH_BYTES
805        } else {
806            0
807        };
808        let mut available;
809        if let Some(local) = self.take_stream_resume(caller) {
810            // Resuming after the exit that sampled the buffer.
811            //
812            // The C's thread stops inside `taskEXIT_CRITICAL`, and when it
813            // runs again it still evaluates the `if( xBytesAvailable <=
814            // xBytesToStoreMessageLength )` BELOW that exit -- against the
815            // sample it took inside the section. So a task preempted there
816            // goes on to block exactly like one that was not.
817            //
818            // Falling straight through to the read instead returns 0 from a
819            // call that was told to wait 350 ticks, which is what
820            // `StreamBufferDemo`'s lower-priority echo server caught: the C
821            // blocked at tick 1 and the sim created its client instead.
822            available = local;
823            if !self.take_stream_waited(caller) && available <= prefix {
824                match self.notify_wait(notify_index, 0, 0, ticks)? {
825                    Blocked => return Ok(Blocked),
826                    Ready(_) => match self.after_stream_wait(caller, buffer)? {
827                        Some(now) => available = now,
828                        None => return Ok(Blocked),
829                    },
830                }
831            }
832        } else if self.notify_wait_pending(caller) {
833            // Resuming: the C's wait returns here, so its second half runs
834            // whatever the buffer now holds.
835            match self.notify_wait(notify_index, 0, 0, ticks)? {
836                Blocked => return Ok(Blocked),
837                Ready(_) => {}
838            }
839            match self.after_stream_wait(caller, buffer)? {
840                Some(now) => available = now,
841                None => return Ok(Blocked),
842            }
843        } else if ticks > 0 {
844            self.enter_critical();
845            available = self.buffers.resolve(buffer)?.bytes_in_buffer();
846            let must_block = available <= prefix;
847            if must_block {
848                let _ = self.notify_state_clear(None, notify_index);
849                self.buffers.resolve_mut(buffer)?.waiting_to_receive = caller;
850            }
851            self.exit_critical();
852            // That exit can release a tick, and a tick can switch this task
853            // away. The C's thread stops inside the exit and everything
854            // below it runs when the task is resumed — with the sample it
855            // already took, and without paying for the section twice.
856            if self.cur() != caller {
857                self.set_stream_resume(caller, available);
858                return Ok(Blocked);
859            }
860            if must_block {
861                match self.notify_wait(notify_index, 0, 0, ticks)? {
862                    Blocked => return Ok(Blocked),
863                    Ready(_) => match self.after_stream_wait(caller, buffer)? {
864                        Some(now) => available = now,
865                        None => return Ok(Blocked),
866                    },
867                }
868            }
869        } else {
870            available = self.buffers.resolve(buffer)?.bytes_in_buffer();
871        }
872
873        let mut received = 0;
874        if available > prefix {
875            received = self.read_message(buffer, out, available)?;
876            if received != 0 {
877                let tick = self.tick;
878                self.note_exits();
879                self.trace.event(
880                    tick,
881                    Event::StreamBufferReceive {
882                        buffer,
883                        bytes: received,
884                    },
885                );
886                self.receive_completed(buffer)?;
887            }
888        }
889        Ok(Ready(received))
890    }
891
892    /// `xStreamBufferReceiveFromISR`.
893    ///
894    /// # Errors
895    /// [`Error::Gone`] for a stale handle.
896    pub fn stream_buffer_receive_from_isr(
897        &mut self,
898        buffer: StreamBufferHandle,
899        out: &mut [u8],
900    ) -> Result<(usize, Woken)> {
901        let snapshot = *self.buffers.resolve(buffer)?;
902        let prefix = if snapshot.is_message {
903            Self::MESSAGE_LENGTH_BYTES
904        } else {
905            0
906        };
907        let available = snapshot.bytes_in_buffer();
908        let mut received = 0;
909        let mut woken = Woken::NO;
910        if available > prefix {
911            received = self.read_message(buffer, out, available)?;
912            if received != 0 {
913                // `traceSTREAM_BUFFER_RECEIVE_FROM_ISR`, likewise unhooked.
914                woken = self.receive_completed_from_isr(buffer)?;
915            }
916        }
917        Ok((received, woken))
918    }
919
920    // --------------------------------------------------- the completions --
921
922    /// `sbSEND_COMPLETED`: tell a waiting reader, with the scheduler
923    /// suspended so the notify cannot switch away mid-update.
924    ///
925    /// The application may replace it — that is what the macro is for, and
926    /// `MessageBufferAMP` is the demo that does — so the hook gets first
927    /// refusal and `true` means it handled the whole thing.
928    // No `inline`: one was tried and cost 323,801 instructions on
929    // `StreamBufferDemo`. The body is small but it is reached from inside
930    // `stream_buffer_send`, which is already large.
931    // A3: ONE caller in the linked kernel, so this pays a prologue and epilogue
932    // for a single call. Inlining moves the body rather than duplicating it.
933    #[inline(always)]
934    fn send_completed(&mut self, buffer: StreamBufferHandle) -> Result<()> {
935        if H::send_completed(self, buffer) {
936            return Ok(());
937        }
938        self.suspend_all();
939        let waiting = self.buffers.resolve(buffer)?.waiting_to_receive;
940        if !waiting.is_null() {
941            let index = self.buffers.resolve(buffer)?.notify_index;
942            let _ = self.notify(waiting, index, 0, NotifyAction::None)?;
943            self.buffers.resolve_mut(buffer)?.waiting_to_receive = TaskHandle::NULL;
944        }
945        let _ = self.resume_all();
946        Ok(())
947    }
948
949    /// `xStreamBufferSendCompletedFromISR` / `sbSEND_COMPLETED_FROM_ISR`.
950    ///
951    /// Public because an application that replaced [`TickHook::send_completed`]
952    /// has to be able to do the notify itself, later and from interrupt
953    /// context — which is exactly what `MessageBufferAMP` does once its
954    /// stand-in interrupt has read the handle back off the control buffer.
955    ///
956    /// # Errors
957    /// [`Error::Gone`] for a stale handle.
958    pub fn send_completed_from_isr(&mut self, buffer: StreamBufferHandle) -> Result<Woken> {
959        let waiting = self.buffers.resolve(buffer)?.waiting_to_receive;
960        if waiting.is_null() {
961            return Ok(Woken::NO);
962        }
963        let index = self.buffers.resolve(buffer)?.notify_index;
964        let (_, woken) = self.notify_from_isr(waiting, index, 0, NotifyAction::None)?;
965        self.buffers.resolve_mut(buffer)?.waiting_to_receive = TaskHandle::NULL;
966        Ok(woken)
967    }
968
969    /// `xStreamBufferSendCompletedFromISR` with the C's ANSWER: whether a task
970    /// was waiting to receive (and so was notified), and whether waking it
971    /// wants a switch.
972    ///
973    /// [`Kernel::send_completed_from_isr`] does the same work but answers
974    /// only the second, which is all a `sbSEND_COMPLETED` replacement needs;
975    /// the C function's own return value had no Rust spelling until the API
976    /// differential (P1.6) asked for it.
977    ///
978    /// # Errors
979    /// [`Error::Gone`] for a stale handle.
980    pub fn stream_buffer_send_completed_from_isr(
981        &mut self,
982        buffer: StreamBufferHandle,
983    ) -> Result<(bool, Woken)> {
984        let waiting = !self.buffers.resolve(buffer)?.waiting_to_receive.is_null();
985        let woken = self.send_completed_from_isr(buffer)?;
986        Ok((waiting, woken))
987    }
988
989    /// `sbRECEIVE_COMPLETED`.
990    fn receive_completed(&mut self, buffer: StreamBufferHandle) -> Result<()> {
991        self.suspend_all();
992        let waiting = self.buffers.resolve(buffer)?.waiting_to_send;
993        if !waiting.is_null() {
994            let index = self.buffers.resolve(buffer)?.notify_index;
995            let _ = self.notify(waiting, index, 0, NotifyAction::None)?;
996            self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
997        }
998        let _ = self.resume_all();
999        Ok(())
1000    }
1001
1002    /// `sbRECEIVE_COMPLETED_FROM_ISR`.
1003    fn receive_completed_from_isr(&mut self, buffer: StreamBufferHandle) -> Result<Woken> {
1004        let waiting = self.buffers.resolve(buffer)?.waiting_to_send;
1005        if waiting.is_null() {
1006            return Ok(Woken::NO);
1007        }
1008        let index = self.buffers.resolve(buffer)?.notify_index;
1009        let (_, woken) = self.notify_from_isr(waiting, index, 0, NotifyAction::None)?;
1010        self.buffers.resolve_mut(buffer)?.waiting_to_send = TaskHandle::NULL;
1011        Ok(woken)
1012    }
1013
1014    // ------------------------------------------------ the ring itself --
1015
1016    /// `prvWriteMessageToBuffer`.
1017    fn write_message(
1018        &mut self,
1019        buffer: StreamBufferHandle,
1020        data: &[u8],
1021        space: usize,
1022        required: usize,
1023    ) -> Result<usize> {
1024        // ONE resolve, and the descriptor is written through in place.
1025        //
1026        // This used to copy the whole nine-field descriptor out
1027        // (`*self.buffers.resolve(..)`) and then resolve a SECOND time to store
1028        // the new head, because `write_bytes` wanted `&mut self` and so nothing
1029        // borrowed from `self` could be alive across it. Destructuring `self`
1030        // into disjoint field borrows removes both the copy and the second
1031        // resolve: `buffers` and `bytes` are different fields, so the borrow
1032        // checker allows what C does with one pointer.
1033        let Self { buffers, bytes, .. } = self;
1034        let b = buffers.resolve_mut(buffer)?;
1035        let (base, ring, is_message) = (b.base, b.length, b.is_message);
1036        let mut next_head = b.head;
1037        let mut length = data.len();
1038        let mut space = space;
1039        if is_message {
1040            if space >= required {
1041                // `write_length_prefix`, folded in: it was a one-caller wrapper
1042                // whose whole body was this.
1043                // `length.to_le_bytes()`, not `(length as u64).to_le_bytes()`:
1044                // the widening wrote eight bytes on a target whose `size_t` is
1045                // four, and the top half was never sent.
1046                next_head = if Self::MESSAGE_LENGTH_BYTES <= core::mem::size_of::<usize>() {
1047                    let raw = length.to_le_bytes();
1048                    let prefix = raw.get(..Self::MESSAGE_LENGTH_BYTES).unwrap_or(&raw);
1049                    Self::write_bytes_into(bytes, base, ring, prefix, next_head)
1050                } else {
1051                    // A length type wider than `size_t` -- a configuration
1052                    // the C allows -- is written zero-extended, every byte
1053                    // of it. Writing only `usize`'s bytes here, while the
1054                    // space arithmetic counted the whole prefix, left the
1055                    // next message misread on a 32-bit target (plan P5, the
1056                    // API differential's `-m32` twin). The branch is on
1057                    // constants, so a prefix that fits `usize` pays nothing.
1058                    let raw = (length as u64).to_le_bytes();
1059                    let prefix = raw.get(..Self::MESSAGE_LENGTH_BYTES).unwrap_or(&raw);
1060                    Self::write_bytes_into(bytes, base, ring, prefix, next_head)
1061                };
1062            } else {
1063                length = 0;
1064            }
1065            space = space.saturating_sub(Self::MESSAGE_LENGTH_BYTES);
1066        }
1067        let length = length.min(space);
1068        if length != 0 {
1069            let chunk = data.get(..length).unwrap_or(data);
1070            b.head = Self::write_bytes_into(bytes, base, ring, chunk, next_head);
1071        }
1072        Ok(length)
1073    }
1074
1075    /// `prvReadMessageFromBuffer`.
1076    fn read_message(
1077        &mut self,
1078        buffer: StreamBufferHandle,
1079        out: &mut [u8],
1080        available: usize,
1081    ) -> Result<usize> {
1082        // ONE resolve, and the descriptor is written through in place -- the
1083        // mirror of `write_message`. Two resolves and a nine-field copy were
1084        // needed only while the helpers took `&self`/`&mut self`; giving them
1085        // the arena as a SLICE lets `buffers` and `bytes` be borrowed disjointly.
1086        let Self { buffers, bytes, .. } = self;
1087        let b = buffers.resolve_mut(buffer)?;
1088        let (base, ring, is_message) = (b.base, b.length, b.is_message);
1089        let mut next_tail = b.tail;
1090        let mut available = available;
1091        let next_length;
1092        if is_message {
1093            let (message_length, tail) =
1094                Self::read_length_prefix_from(bytes, base, ring, next_tail);
1095            next_tail = tail;
1096            available = available.saturating_sub(Self::MESSAGE_LENGTH_BYTES);
1097            next_length = if message_length > out.len() {
1098                // The C returns nothing rather than half a message.
1099                0
1100            } else {
1101                message_length
1102            };
1103        } else {
1104            next_length = out.len();
1105        }
1106        let count = next_length.min(available);
1107        if count != 0 {
1108            b.tail = match out.get_mut(..count) {
1109                Some(slot) => Self::read_bytes_from(bytes, base, ring, slot, next_tail),
1110                None => next_tail,
1111            };
1112        }
1113        Ok(count)
1114    }
1115
1116    /// `prvWriteBytesToBuffer`: the ring wrap, in two `memcpy`s.
1117    ///
1118    /// The index arithmetic here is `wrapping_*`, because the geometry has
1119    /// already bounded every term: `head` is below `length`, `base + length`
1120    /// is at most `BYTES`, `first` is `min(len, upto)` so `len - first`
1121    /// cannot go below zero, and `head + first` is at most `length` -- which
1122    /// the fold on the line after turns back into 0, exactly as `wrap_next`
1123    /// does. Each index then passes through a `get_mut` that refuses
1124    /// anything the ring does not own.
1125    /// Takes the byte arena as a SLICE rather than `&mut self`, so a caller can
1126    /// hold `&mut` to a descriptor in `self.buffers` at the same time. It asked
1127    /// for `&mut self` until 2026-09-25, and that is why `write_message` had to
1128    /// copy the whole descriptor out before calling it: under `forbid(unsafe)`
1129    /// a `&StreamBuffer` borrowed from `self` cannot coexist with `&mut self`.
1130    /// Destructuring `self` into disjoint field borrows is the safe form of what
1131    /// C gets for free by holding one pointer.
1132    fn write_bytes_into(
1133        bytes: &mut [u8],
1134        base: usize,
1135        ring: usize,
1136        data: &[u8],
1137        head: usize,
1138    ) -> usize {
1139        // The two copies, and the two the C makes. A payload longer than the
1140        // ring is refused before this, so that case cannot arrive.
1141        if data.len() <= ring {
1142            let upto = ring.wrapping_sub(head);
1143            let first = data.len().min(upto);
1144            let from = base.wrapping_add(head);
1145            if let (Some(dst), Some(src)) = (
1146                bytes.get_mut(from..from.wrapping_add(first)),
1147                data.get(..first),
1148            ) {
1149                dst.copy_from_slice(src);
1150            }
1151            let rest = data.len().wrapping_sub(first);
1152            if rest > 0 {
1153                if let (Some(dst), Some(src)) = (
1154                    bytes.get_mut(base..base.wrapping_add(rest)),
1155                    data.get(first..),
1156                ) {
1157                    dst.copy_from_slice(src);
1158                }
1159                return rest;
1160            }
1161            let next = head.wrapping_add(first);
1162            return if next >= ring { 0 } else { next };
1163        }
1164        head
1165    }
1166
1167    /// `prvReadBytesFromBuffer`.
1168    ///
1169    /// Bounded as [`Kernel::write_bytes`] is, and for the same reasons.
1170    /// The mirror of [`Self::write_bytes_into`], and takes the arena the same
1171    /// way -- as a slice, so a caller can hold `&mut` to a descriptor in
1172    /// `self.buffers` across it. A request longer than the ring cannot arrive:
1173    /// `read_message` clamps `count` to `available`, which the ring's spare byte
1174    /// holds below `ring`.
1175    ///
1176    /// It asked for `&mut self` until 2026-09-25 while only ever READING the
1177    /// arena, and that single word is why `read_length_prefix` carried its own
1178    /// copy of this whole ring walk: with `&self` it could not call this.
1179    ///
1180    /// In line at both callers: out of line it became a shared symbol and cost
1181    /// +12 B, because each caller freezes a different length.
1182    #[inline(always)]
1183    fn read_bytes_from(
1184        bytes: &[u8],
1185        base: usize,
1186        ring: usize,
1187        out: &mut [u8],
1188        tail: usize,
1189    ) -> usize {
1190        if out.len() <= ring {
1191            let upto = ring.wrapping_sub(tail);
1192            let first = out.len().min(upto);
1193            let from = base.wrapping_add(tail);
1194            if let (Some(dst), Some(src)) = (
1195                out.get_mut(..first),
1196                bytes.get(from..from.wrapping_add(first)),
1197            ) {
1198                dst.copy_from_slice(src);
1199            }
1200            let rest = out.len().wrapping_sub(first);
1201            if rest > 0 {
1202                if let (Some(dst), Some(src)) = (
1203                    out.get_mut(first..),
1204                    bytes.get(base..base.wrapping_add(rest)),
1205                ) {
1206                    dst.copy_from_slice(src);
1207                }
1208                return rest;
1209            }
1210            let next = tail.wrapping_add(first);
1211            return if next >= ring { 0 } else { next };
1212        }
1213        tail
1214    }
1215
1216    /// The message length back out, and where the message starts.
1217    /// Bounded as [`Kernel::read_bytes`] is, and converted for the same
1218    /// reasons: `tail` is below `length`, `base + length` is at most
1219    /// `BYTES`, `first` is `min(want, upto)`, and every index passes through
1220    /// a `get` that refuses anything the ring does not own.
1221    /// The prefix is converted at the TARGET's width, not always through `u64`.
1222    ///
1223    /// This used `[0_u8; 8]` and `u64::from_le_bytes(..) as usize`. On rv32 that
1224    /// reads eight bytes as two words and throws the top one away, because
1225    /// `configMESSAGE_BUFFER_LENGTH_TYPE` is `size_t` and `size_t` is FOUR bytes
1226    /// there. `usize` is the width the C's type actually has on whichever target
1227    /// this is, so it is the right one to build.
1228    fn read_length_prefix_from(
1229        bytes: &[u8],
1230        base: usize,
1231        ring: usize,
1232        tail: usize,
1233    ) -> (usize, usize) {
1234        if Self::MESSAGE_LENGTH_BYTES > core::mem::size_of::<usize>() {
1235            // The wide prefix `write_message` writes zero-extended: read all
1236            // of it, so the ring advances past it, and keep the value -- a
1237            // length this kernel wrote, so it fits `usize`.
1238            let mut wide = [0_u8; 8];
1239            let next = match wide.get_mut(..Self::MESSAGE_LENGTH_BYTES) {
1240                Some(slot) => Self::read_bytes_from(bytes, base, ring, slot, tail),
1241                None => tail,
1242            };
1243            return (
1244                usize::try_from(u64::from_le_bytes(wide)).unwrap_or(usize::MAX),
1245                next,
1246            );
1247        }
1248        let mut raw = [0_u8; core::mem::size_of::<usize>()];
1249        // Delegated. This held its OWN two-copy ring walk plus a byte-at-a-time
1250        // fallback -- a third hand-rolled version of the same walk -- and the
1251        // only reason was that `read_bytes` asked for `&mut self` when it never
1252        // needed it.
1253        // A prefix wider than the target's `usize` cannot be represented, and
1254        // on the oracle host the two are equal, so this clamp is the identity
1255        // wherever the arms are matched.
1256        let want = Self::MESSAGE_LENGTH_BYTES.min(raw.len());
1257        let next = match raw.get_mut(..want) {
1258            Some(slot) => Self::read_bytes_from(bytes, base, ring, slot, tail),
1259            None => tail,
1260        };
1261        (usize::from_le_bytes(raw), next)
1262    }
1263}
1264
1265// ================================================================ tests ==
1266
1267/// `stream.rs` had no unit test at all, and six of its APIs are also the
1268/// ones no conformance scenario reaches (`docs/HOLES.md`, H2 and H3). For
1269/// those, the only evidence available is a semantic audit against the C
1270/// source plus tests that pin what it says.
1271///
1272/// So every test here quotes the `stream_buffer.c` line it is pinning, and
1273/// pins **the C's contract** rather than this kernel's behaviour. A test
1274/// written the other way round proves only that the code still does what it
1275/// did, which is worth having and is not evidence of conformance.
1276#[cfg(test)]
1277#[allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
1278mod tests {
1279    use rusty_rtos_core::config::Config;
1280    use rusty_rtos_core::hooks::NoTickHook;
1281
1282    use crate::queue::Wait;
1283    use crate::system::tests::{NoTrace, TestConfig, TestPort};
1284
1285    /// A kernel with buffers, which `system!` never declares: the macro
1286    /// sizes `BUFFERS` and `BYTES` at zero. Four tasks is the idle task,
1287    /// the timer daemon and one of our own, with room to spare.
1288    type K = crate::Kernel<
1289        TestConfig,
1290        TestPort,
1291        NoTrace,
1292        NoTickHook,
1293        4,
1294        { crate::list_slots_for(4, 0, crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0)) },
1295        { crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0) },
1296        1,
1297        1,
1298        2,
1299        64,
1300        0,
1301        0,
1302        { <TestConfig as ::rusty_rtos_core::config::Config>::TIMER_QUEUE_LENGTH },
1303    >;
1304
1305    fn kernel() -> K {
1306        K::new(TestPort::default(), NoTrace).expect("the declared geometry adds up")
1307    }
1308
1309    /// The header a message buffer writes in front of every message.
1310    const HDR: usize = K::MESSAGE_LENGTH_BYTES;
1311
1312    /// `xStreamBufferIsEmpty`:
1313    ///
1314    /// ```c
1315    /// if( pxStreamBuffer->xHead == xTail ) { xReturn = pdTRUE; }
1316    /// ```
1317    ///
1318    /// Head-equals-tail, which is emptiness and NOT "nothing readable" --
1319    /// the two differ on a message buffer holding only a header, which the
1320    /// zero-length-message test below pins.
1321    #[test]
1322    fn is_empty_is_head_equals_tail() {
1323        let mut k = kernel();
1324        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1325        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1326
1327        k.stream_buffer_send(b, b"abc", 0).expect("send");
1328        assert_eq!(k.stream_buffer_is_empty(b), Ok(false));
1329
1330        let mut out = [0_u8; 8];
1331        k.stream_buffer_receive(b, &mut out, 0).expect("receive");
1332        assert_eq!(
1333            k.stream_buffer_is_empty(b),
1334            Ok(true),
1335            "drained is empty again, wherever head and tail have walked to"
1336        );
1337    }
1338
1339    /// `xStreamBufferIsFull` on a STREAM buffer:
1340    ///
1341    /// ```c
1342    /// xBytesToStoreMessageLength = 0;   /* not a message buffer */
1343    /// if( xStreamBufferSpacesAvailable( xStreamBuffer ) <= xBytesToStoreMessageLength )
1344    /// ```
1345    ///
1346    /// so full is exactly "no spaces left".
1347    #[test]
1348    fn is_full_on_a_stream_buffer_means_no_spaces_at_all() {
1349        let mut k = kernel();
1350        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1351        assert_eq!(k.stream_buffer_spaces_available(b), Ok(8));
1352        assert_eq!(k.stream_buffer_is_full(b), Ok(false));
1353
1354        k.stream_buffer_send(b, b"1234567", 0).expect("send seven");
1355        assert_eq!(k.stream_buffer_spaces_available(b), Ok(1));
1356        assert_eq!(
1357            k.stream_buffer_is_full(b),
1358            Ok(false),
1359            "one free byte is not full on a STREAM buffer"
1360        );
1361
1362        k.stream_buffer_send(b, b"8", 0).expect("send the last");
1363        assert_eq!(k.stream_buffer_spaces_available(b), Ok(0));
1364        assert_eq!(k.stream_buffer_is_full(b), Ok(true));
1365    }
1366
1367    /// `xStreamBufferIsFull` on a MESSAGE buffer, which is the one that
1368    /// surprises:
1369    ///
1370    /// ```c
1371    /// if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != 0 )
1372    ///     xBytesToStoreMessageLength = sbBYTES_TO_STORE_MESSAGE_LENGTH;
1373    /// if( xStreamBufferSpacesAvailable( xStreamBuffer ) <= xBytesToStoreMessageLength )
1374    /// ```
1375    ///
1376    /// `<=`, against the size of the LENGTH HEADER rather than against
1377    /// zero. So a message buffer reports FULL while it still has free
1378    /// bytes, because those bytes could not hold even a zero-length
1379    /// message's header.
1380    ///
1381    /// A caller that polls `is_full` and expects `spaces_available() == 0`
1382    /// is wrong by up to a header, and only on message buffers.
1383    #[test]
1384    fn is_full_on_a_message_buffer_leaves_a_header_of_bytes_free() {
1385        let mut k = kernel();
1386        let b = k.message_buffer_create(8).expect("a message buffer");
1387        assert_eq!(k.stream_buffer_spaces_available(b), Ok(8));
1388        assert_eq!(k.stream_buffer_is_full(b), Ok(false));
1389
1390        // One three-byte message costs the header plus the payload.
1391        k.stream_buffer_send(b, b"abc", 0).expect("send");
1392        let spaces = k.stream_buffer_spaces_available(b).expect("spaces");
1393        assert_eq!(spaces, 8 - (HDR + 3));
1394        assert!(spaces > 0, "there ARE free bytes");
1395        assert!(spaces <= HDR, "but not enough for another header");
1396        assert_eq!(
1397            k.stream_buffer_is_full(b),
1398            Ok(true),
1399            "full with {spaces} byte(s) free: the C compares against the header, not zero"
1400        );
1401    }
1402
1403    /// `xStreamBufferNextMessageLengthBytes` on a stream buffer:
1404    ///
1405    /// ```c
1406    /// if( ( pxStreamBuffer->ucFlags & sbFLAGS_IS_MESSAGE_BUFFER ) != 0 ) { ... }
1407    /// else { xReturn = 0; }
1408    /// ```
1409    ///
1410    /// Zero for a stream buffer NO MATTER WHAT IT HOLDS. That is not "no
1411    /// message waiting", it is "the question does not apply" -- and the
1412    /// return type cannot tell a caller which of the two it got.
1413    #[test]
1414    fn next_message_length_is_zero_on_a_stream_buffer_however_full() {
1415        let mut k = kernel();
1416        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1417        assert_eq!(k.stream_buffer_next_message_length(b), Ok(0));
1418
1419        k.stream_buffer_send(b, b"abcde", 0).expect("send");
1420        assert_eq!(k.stream_buffer_bytes_available(b), Ok(5));
1421        assert_eq!(
1422            k.stream_buffer_next_message_length(b),
1423            Ok(0),
1424            "five bytes waiting and still zero, because it is not a message buffer"
1425        );
1426    }
1427
1428    /// The same call on a message buffer PEEKS:
1429    ///
1430    /// ```c
1431    /// ( void ) prvReadBytesFromBuffer( pxStreamBuffer, ..., pxStreamBuffer->xTail );
1432    /// ```
1433    ///
1434    /// It reads at the tail without advancing it, so asking twice answers
1435    /// twice and the message is still there to be received.
1436    #[test]
1437    fn next_message_length_peeks_and_does_not_consume() {
1438        let mut k = kernel();
1439        let b = k.message_buffer_create(16).expect("a message buffer");
1440        k.stream_buffer_send(b, b"hello", 0).expect("send");
1441
1442        assert_eq!(k.stream_buffer_next_message_length(b), Ok(5));
1443        assert_eq!(
1444            k.stream_buffer_next_message_length(b),
1445            Ok(5),
1446            "asking did not consume it"
1447        );
1448
1449        let mut out = [0_u8; 16];
1450        assert_eq!(k.stream_buffer_receive(b, &mut out, 0), Ok(Wait::Ready(5)));
1451        assert_eq!(&out[..5], b"hello");
1452        assert_eq!(k.stream_buffer_next_message_length(b), Ok(0), "drained");
1453    }
1454
1455    /// A zero-length message is a NO-OP that is indistinguishable from a
1456    /// send that failed -- which is not visible from the call site, and is
1457    /// the sort of thing only a source audit finds.
1458    ///
1459    /// `prvWriteMessageToBuffer`:
1460    ///
1461    /// ```c
1462    /// if( message buffer ) {
1463    ///     xMessageLength = ( configMESSAGE_BUFFER_LENGTH_TYPE ) xDataLengthBytes;  /* 0 */
1464    ///     if( xSpace >= xRequiredSpace ) {
1465    ///         xNextHead = prvWriteBytesToBuffer( pxStreamBuffer, &xMessageLength,
1466    ///                                            sbBYTES_TO_STORE_MESSAGE_LENGTH, xNextHead );
1467    ///     }
1468    /// }
1469    /// if( xDataLengthBytes != ( size_t ) 0 ) {
1470    ///     pxStreamBuffer->xHead = prvWriteBytesToBuffer( ..., xNextHead );
1471    /// }
1472    /// return xDataLengthBytes;
1473    /// ```
1474    ///
1475    /// The header IS written into the storage array -- but the new position
1476    /// goes into `xNextHead`, a LOCAL. `pxStreamBuffer->xHead` is only
1477    /// committed inside the `xDataLengthBytes != 0` branch, which a
1478    /// zero-length message does not take.
1479    ///
1480    /// So the bytes are in the array and the buffer does not know it: the
1481    /// head never moves, the buffer stays empty, the call returns 0, and
1482    /// the next send writes over them. A caller cannot tell this apart from
1483    /// a send that was refused for want of space.
1484    ///
1485    /// Pinned because the earlier version of this test asserted the
1486    /// opposite -- that the header would show up in `bytes_available` --
1487    /// and the kernel was right.
1488    #[test]
1489    fn a_zero_length_message_is_a_no_op_that_looks_like_a_failed_send() {
1490        let mut k = kernel();
1491        let b = k.message_buffer_create(16).expect("a message buffer");
1492        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1493
1494        assert_eq!(
1495            k.stream_buffer_send(b, b"", 0),
1496            Ok(Wait::Ready(0)),
1497            "zero bytes written, which is also what a refused send answers"
1498        );
1499        assert_eq!(
1500            k.stream_buffer_bytes_available(b),
1501            Ok(0),
1502            "the header went into the array and the head was never committed"
1503        );
1504        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1505        assert_eq!(k.stream_buffer_next_message_length(b), Ok(0));
1506
1507        // And a real message lands in the same place, over the top of it.
1508        k.stream_buffer_send(b, b"ok", 0).expect("a real message");
1509        assert_eq!(k.stream_buffer_next_message_length(b), Ok(2));
1510        let mut out = [0_u8; 16];
1511        assert_eq!(k.stream_buffer_receive(b, &mut out, 0), Ok(Wait::Ready(2)));
1512        assert_eq!(&out[..2], b"ok");
1513        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1514    }
1515
1516    /// `xStreamBufferReset`:
1517    ///
1518    /// ```c
1519    /// if( ( pxStreamBuffer->xTaskWaitingToReceive == NULL ) &&
1520    ///     ( pxStreamBuffer->xTaskWaitingToSend == NULL ) )
1521    /// {
1522    ///     prvInitialiseNewStreamBuffer( ..., pxStreamBuffer->xTriggerLevelBytes, ... );
1523    ///     xReturn = pdPASS;
1524    /// }
1525    /// ```
1526    ///
1527    /// The buffer's own trigger level is passed straight back in, so a
1528    /// reset empties the buffer and KEEPS the trigger. It is not a return
1529    /// to the creation default, which is what the name suggests.
1530    #[test]
1531    fn reset_empties_the_buffer_and_keeps_the_trigger_level() {
1532        let mut k = kernel();
1533        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1534        assert_eq!(k.stream_buffer_set_trigger_level(b, 5), Ok(true));
1535        k.stream_buffer_send(b, b"abcd", 0).expect("send");
1536        assert_eq!(k.stream_buffer_bytes_available(b), Ok(4));
1537
1538        assert_eq!(k.stream_buffer_reset(b), Ok(true));
1539        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1540        assert_eq!(k.stream_buffer_bytes_available(b), Ok(0));
1541        assert_eq!(
1542            k.stream_buffer_spaces_available(b),
1543            Ok(8),
1544            "the whole usable length is back"
1545        );
1546    }
1547
1548    /// The other half of that guard: a reset must REFUSE while a task is
1549    /// blocked on the buffer, because reinitialising would drop the handle
1550    /// that task is waiting on.
1551    #[test]
1552    fn reset_refuses_while_a_task_is_waiting_to_receive() {
1553        let mut k = kernel();
1554        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1555        k.create_task("rx", 1).expect("a task");
1556        let started = k.start_scheduler().expect("start");
1557        k.suspend(Some(started.timer)).expect("park the daemon");
1558
1559        // Run until our task is the one on the CPU, then block it.
1560        let mut out = [0_u8; 8];
1561        let mut blocked = false;
1562        for _ in 0..50_u32 {
1563            let running = k.name_of(k.current()).expect("a running task has a name");
1564            if running.as_str() == "rx" {
1565                assert_eq!(
1566                    k.stream_buffer_receive(b, &mut out, 20),
1567                    Ok(Wait::Blocked),
1568                    "an empty buffer with a timeout blocks"
1569                );
1570                blocked = true;
1571                break;
1572            }
1573            k.switch_context();
1574        }
1575        assert!(blocked, "never got the task onto the CPU");
1576
1577        assert_eq!(
1578            k.stream_buffer_reset(b),
1579            Ok(false),
1580            "a waiting receiver refuses the reset"
1581        );
1582    }
1583
1584    /// `xStreamBufferReceiveFromISR` never blocks: it takes a whole
1585    /// message, or nothing.
1586    #[test]
1587    fn receive_from_isr_takes_a_whole_message_or_nothing() {
1588        let mut k = kernel();
1589        let b = k.message_buffer_create(16).expect("a message buffer");
1590        let mut out = [0_u8; 16];
1591
1592        let (n, _) = k.stream_buffer_receive_from_isr(b, &mut out).expect("isr");
1593        assert_eq!(n, 0, "nothing waiting, and it did not block");
1594
1595        k.stream_buffer_send(b, b"xy", 0).expect("send");
1596        let (n, _) = k.stream_buffer_receive_from_isr(b, &mut out).expect("isr");
1597        assert_eq!(n, 2);
1598        assert_eq!(&out[..2], b"xy");
1599        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1600    }
1601
1602    /// `bytes_available` and `spaces_available` partition the USABLE
1603    /// length, which is one less than the ring's own -- the spare byte that
1604    /// tells full from empty, the C's `xBufferSizeBytes++` at creation.
1605    #[test]
1606    fn bytes_and_spaces_partition_the_usable_length() {
1607        let mut k = kernel();
1608        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1609        for n in 0..=8_usize {
1610            let bytes = k.stream_buffer_bytes_available(b).expect("bytes");
1611            let spaces = k.stream_buffer_spaces_available(b).expect("spaces");
1612            assert_eq!(
1613                bytes.saturating_add(spaces),
1614                8,
1615                "at {n} byte(s) in: {bytes} + {spaces} should be the usable 8"
1616            );
1617            if n < 8 {
1618                k.stream_buffer_send(b, b"z", 0).expect("send one");
1619            }
1620        }
1621    }
1622    /// A STREAM buffer takes a partial write; a MESSAGE buffer is
1623    /// all-or-nothing. `prvWriteMessageToBuffer`:
1624    ///
1625    /// ```c
1626    /// if( message buffer ) {
1627    ///     if( xSpace >= xRequiredSpace ) { ...write the header... }
1628    ///     else { xDataLengthBytes = 0; }          /* nothing at all */
1629    /// } else {
1630    ///     xDataLengthBytes = configMIN( xDataLengthBytes, xSpace );   /* as much as fits */
1631    /// }
1632    /// ```
1633    ///
1634    /// So the same call with the same arguments loses the tail on one kind
1635    /// and loses everything on the other, and the return value is the only
1636    /// way to tell which happened.
1637    #[test]
1638    fn a_stream_takes_a_partial_write_and_a_message_is_all_or_nothing() {
1639        let mut k = kernel();
1640        let s = k.stream_buffer_create(8, 1).expect("a stream buffer");
1641        k.stream_buffer_send(s, b"123456", 0).expect("six");
1642        assert_eq!(
1643            k.stream_buffer_send(s, b"789", 0),
1644            Ok(Wait::Ready(2)),
1645            "two of the three fit, and two is what it took"
1646        );
1647        assert_eq!(k.stream_buffer_spaces_available(s), Ok(0));
1648
1649        let mut k = kernel();
1650        let m = k.message_buffer_create(8).expect("a message buffer");
1651        // One message of two costs the header plus two: six of the eight.
1652        k.stream_buffer_send(m, b"xy", 0)
1653            .expect("the first message");
1654        assert_eq!(
1655            k.stream_buffer_send(m, b"zzz", 0),
1656            Ok(Wait::Ready(0)),
1657            "the header plus three does not fit, so NOTHING was written"
1658        );
1659        assert_eq!(
1660            k.stream_buffer_next_message_length(m),
1661            Ok(2),
1662            "and the message already there is untouched"
1663        );
1664    }
1665
1666    /// `xStreamBufferSendFromISR` writes what fits and never blocks -- the
1667    /// same body as the task-side send with the block time forced to zero.
1668    #[test]
1669    fn send_from_isr_writes_what_fits_and_never_blocks() {
1670        let mut k = kernel();
1671        let b = k.stream_buffer_create(8, 1).expect("a buffer");
1672
1673        let (n, _) = k.stream_buffer_send_from_isr(b, b"abc").expect("isr");
1674        assert_eq!(n, 3);
1675        assert_eq!(k.stream_buffer_bytes_available(b), Ok(3));
1676
1677        // Past the end: it takes the five that fit rather than waiting.
1678        let (n, _) = k.stream_buffer_send_from_isr(b, b"defghijkl").expect("isr");
1679        assert_eq!(n, 5, "five of the nine fit");
1680        assert_eq!(k.stream_buffer_is_full(b), Ok(true));
1681
1682        let (n, _) = k.stream_buffer_send_from_isr(b, b"m").expect("isr");
1683        assert_eq!(n, 0, "full, and it still did not block");
1684    }
1685
1686    /// A round trip through the two ISR halves, which is what an
1687    /// interrupt-driven driver actually does.
1688    #[test]
1689    fn a_message_survives_a_round_trip_through_both_isr_halves() {
1690        let mut k = kernel();
1691        let b = k.message_buffer_create(16).expect("a message buffer");
1692        let (n, _) = k.stream_buffer_send_from_isr(b, b"ping").expect("isr");
1693        assert_eq!(n, 4);
1694
1695        let mut out = [0_u8; 16];
1696        let (n, _) = k.stream_buffer_receive_from_isr(b, &mut out).expect("isr");
1697        assert_eq!(n, 4);
1698        assert_eq!(&out[..4], b"ping");
1699        assert_eq!(k.stream_buffer_is_empty(b), Ok(true));
1700    }
1701
1702    /// Four buffers over a 64-byte arena: room to fill it exactly, punch a
1703    /// hole and refill it -- which the geometry above (two buffers) cannot.
1704    type K4 = crate::Kernel<
1705        TestConfig,
1706        TestPort,
1707        NoTrace,
1708        NoTickHook,
1709        4,
1710        { crate::list_slots_for(4, 0, crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0)) },
1711        { crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0) },
1712        1,
1713        1,
1714        4,
1715        64,
1716        0,
1717        0,
1718        { <TestConfig as ::rusty_rtos_core::config::Config>::TIMER_QUEUE_LENGTH },
1719    >;
1720
1721    fn arena() -> K4 {
1722        K4::new(TestPort::default(), NoTrace).expect("the declared geometry adds up")
1723    }
1724
1725    /// The byte arena is Kairos storage -- the C mallocs -- so no compared
1726    /// run judges it, and no run filled it: its exact-fill, exact-fit and
1727    /// split boundaries all survived plan P5's mutants. A buffer of `n`
1728    /// takes `n + 1` bytes (the spare byte), so two of 31 fill 64 exactly.
1729    #[test]
1730    fn the_byte_arena_fills_exactly_and_a_hole_refits_exactly() {
1731        use rusty_rtos_core::error::Error;
1732        let mut k = arena();
1733        let a = k.stream_buffer_create(31, 1).expect("the first half");
1734        let _b = k
1735            .stream_buffer_create(31, 1)
1736            .expect("the second half fills the arena to its last byte");
1737        assert_eq!(
1738            k.stream_buffer_create(1, 1),
1739            Err(Error::Full),
1740            "and nothing more fits"
1741        );
1742
1743        k.stream_buffer_delete(a).expect("delete");
1744        k.stream_buffer_create(31, 1)
1745            .expect("the same size refits the hole exactly");
1746        assert_eq!(k.stream_buffer_create(1, 1), Err(Error::Full));
1747    }
1748
1749    /// A smaller buffer splits a hole and the remainder stays usable; two
1750    /// freed neighbours coalesce, whichever of them is freed first.
1751    #[test]
1752    fn a_split_hole_keeps_its_remainder_and_freed_neighbours_coalesce() {
1753        use rusty_rtos_core::error::Error;
1754        let mut k = arena();
1755        let a = k.stream_buffer_create(31, 1).expect("a");
1756        let _b = k.stream_buffer_create(31, 1).expect("b: full");
1757        k.stream_buffer_delete(a).expect("delete a");
1758
1759        // The lower neighbour freed first, then the upper.
1760        let c = k.stream_buffer_create(15, 1).expect("half the hole");
1761        let d = k.stream_buffer_create(15, 1).expect("the remainder of it");
1762        assert_eq!(k.stream_buffer_create(1, 1), Err(Error::Full));
1763        k.stream_buffer_delete(c).expect("delete c");
1764        k.stream_buffer_delete(d).expect("delete d");
1765        let e = k
1766            .stream_buffer_create(31, 1)
1767            .expect("the halves coalesced, lower freed first");
1768
1769        // The upper neighbour freed first, then the lower.
1770        k.stream_buffer_delete(e).expect("delete e");
1771        let c = k.stream_buffer_create(15, 1).expect("c again");
1772        let d = k.stream_buffer_create(15, 1).expect("d again");
1773        k.stream_buffer_delete(d).expect("delete d");
1774        k.stream_buffer_delete(c).expect("delete c");
1775        k.stream_buffer_create(31, 1)
1776            .expect("the halves coalesced, upper freed first");
1777    }
1778
1779    /// `xStreamBufferCreate` refuses a zero size, and a trigger above the
1780    /// size, each on its own (plan P5: `||` -> `&&` survived).
1781    #[test]
1782    fn a_zero_size_or_a_trigger_above_the_size_is_refused() {
1783        use rusty_rtos_core::error::Error;
1784        let mut k = kernel();
1785        assert_eq!(k.stream_buffer_create(0, 0), Err(Error::InvalidArgument));
1786        assert_eq!(k.stream_buffer_create(4, 5), Err(Error::InvalidArgument));
1787        assert!(k.stream_buffer_create(4, 4).is_ok());
1788    }
1789
1790    /// [`TestConfig`] with an eight-byte message length: a
1791    /// `configMESSAGE_BUFFER_LENGTH_TYPE` wider than a 32-bit target's
1792    /// `size_t`, which the C allows.
1793    struct WidePrefixConfig;
1794    impl Config for WidePrefixConfig {
1795        type Tick = rusty_rtos_core::tick::Bits32;
1796        const TICK_RATE_HZ: u32 = 100;
1797        const MAX_PRIORITIES: u8 = 4;
1798        const MINIMAL_STACK_SIZE: usize = 1;
1799        const MAX_TASK_NAME_LEN: usize = 8;
1800        const TIMER_TASK_PRIORITY: u8 = 3;
1801        const TIMER_TASK_STACK_DEPTH: usize = 1;
1802        const TIMER_QUEUE_LENGTH: usize = 1;
1803        const NOTIFICATION_ARRAY_ENTRIES: usize = 1;
1804        const MESSAGE_LENGTH_BYTES: usize = 8;
1805    }
1806
1807    /// A message survives a round trip under a prefix wider than `usize`.
1808    /// On a 32-bit target this was broken (plan P5, found by the API
1809    /// differential's `-m32` twin): the send wrote four bytes of prefix and
1810    /// counted eight, so the receive took the message's first byte and
1811    /// nothing more. Run it at the targets' width with
1812    /// `cargo test --target i686-pc-windows-msvc`; on a 64-bit host the
1813    /// prefix fits `usize` and this is the ordinary path.
1814    #[test]
1815    fn a_message_round_trips_under_a_prefix_wider_than_usize() {
1816        type KW = crate::Kernel<
1817            WidePrefixConfig,
1818            TestPort,
1819            NoTrace,
1820            NoTickHook,
1821            4,
1822            { crate::list_slots_for(4, 0, crate::lists_for(4, 1, 0)) },
1823            { crate::lists_for(4, 1, 0) },
1824            1,
1825            1,
1826            2,
1827            64,
1828            0,
1829            0,
1830            1,
1831        >;
1832        let mut k = KW::new(TestPort::default(), NoTrace).expect("the declared geometry adds up");
1833        let b = k.message_buffer_create(32).expect("a message buffer");
1834        k.stream_buffer_send(b, b"hello", 0).expect("send");
1835        assert_eq!(
1836            k.stream_buffer_bytes_available(b),
1837            Ok(13),
1838            "eight of prefix, five of message"
1839        );
1840        assert_eq!(k.stream_buffer_next_message_length(b), Ok(5));
1841        let mut out = [0_u8; 16];
1842        assert_eq!(k.stream_buffer_receive(b, &mut out, 0), Ok(Wait::Ready(5)));
1843        assert_eq!(out.get(..5), Some(&b"hello"[..]));
1844    }
1845
1846    /// A port that raises ONE tick, at a chosen outermost critical-section
1847    /// exit -- the sim contract's clock (`ORACLES.md`), aimed. `TestPort`
1848    /// never ticks, so nothing in this file could switch a task away inside
1849    /// a kernel call, and the stream's resume-after-wait arm had no test.
1850    #[derive(Debug, Default)]
1851    struct TickAt {
1852        nesting: core::cell::Cell<u32>,
1853        exits: core::cell::Cell<u64>,
1854        at: core::cell::Cell<u64>,
1855        pending: core::cell::Cell<bool>,
1856        counting: core::cell::Cell<bool>,
1857        in_tick: core::cell::Cell<bool>,
1858    }
1859
1860    impl rusty_rtos_core::port::Port for TickAt {
1861        fn yield_now(&self) {}
1862        fn yield_from_isr(&self, _woken: rusty_rtos_core::isr::Woken) {}
1863        fn enter_critical(&self) {
1864            self.nesting.set(self.nesting.get().saturating_add(1));
1865        }
1866        fn exit_critical(&self) {
1867            let n = self.nesting.get().saturating_sub(1);
1868            self.nesting.set(n);
1869            if n == 0 && self.counting.get() && !self.in_tick.get() {
1870                let exits = self.exits.get().wrapping_add(1);
1871                self.exits.set(exits);
1872                if exits == self.at.get() {
1873                    self.pending.set(true);
1874                }
1875            }
1876        }
1877        fn set_interrupt_mask_from_isr(&self) -> u32 {
1878            0
1879        }
1880        fn clear_interrupt_mask_from_isr(&self, _saved: u32) {}
1881        fn in_isr(&self) -> bool {
1882            self.in_tick.get()
1883        }
1884        fn set_in_tick_entry(&self, yes: bool) {
1885            self.in_tick.set(yes);
1886        }
1887        fn take_pending_tick(&self) -> bool {
1888            self.pending.replace(false)
1889        }
1890        fn exits(&self) -> u64 {
1891            self.exits.get()
1892        }
1893        fn scheduler_started(&self) {
1894            self.counting.set(true);
1895        }
1896    }
1897
1898    type KT = crate::Kernel<
1899        TestConfig,
1900        TickAt,
1901        NoTrace,
1902        NoTickHook,
1903        4,
1904        { crate::list_slots_for(4, 0, crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0)) },
1905        { crate::lists_for(TestConfig::MAX_PRIORITIES, 1, 0) },
1906        1,
1907        1,
1908        2,
1909        64,
1910        0,
1911        0,
1912        { <TestConfig as ::rusty_rtos_core::config::Config>::TIMER_QUEUE_LENGTH },
1913    >;
1914
1915    /// `xStreamBufferReceive` that timed out, preempted at the exit ending
1916    /// its wait, returns 0 when it runs again -- it does not wait a second
1917    /// time. The C's thread is stopped INSIDE that exit and goes on to read
1918    /// what the buffer holds; the stackless call records that the wait is
1919    /// done (`set_stream_waited`) and the resumed call reads it
1920    /// (`take_stream_waited`). Neither half had an oracle (HOLES.md H14): the
1921    /// differential delivers ticks between calls, and no corpus scenario
1922    /// lands a tick on that exit in 100,000 ticks.
1923    ///
1924    /// R (priority 2) receives on an empty buffer with a one-tick timeout; H
1925    /// (priority 3) delays two ticks, so it wakes on the tick AFTER R's
1926    /// timeout. That tick is raised at each exit of R's resumed call in turn:
1927    /// wherever it lands, H preempts, and R's next call must answer 0.
1928    #[test]
1929    fn a_receive_preempted_as_its_wait_ends_does_not_wait_again() {
1930        let mut preempted_inside = 0;
1931        for k in 1..=12_u64 {
1932            let mut kx =
1933                KT::new(TickAt::default(), NoTrace).expect("the declared geometry adds up");
1934            let sb = kx.stream_buffer_create(16, 1).expect("a stream buffer");
1935            let r = kx.create_task("R", 2).expect("R");
1936            let h = kx.create_task("H", 3).expect("H");
1937            let start = kx.start_scheduler().expect("start");
1938            kx.suspend(Some(start.timer)).expect("park the daemon");
1939            // H runs first and sleeps past R's timeout.
1940            while kx.current() != h {
1941                kx.switch_context();
1942            }
1943            kx.delay(2).expect("H delays");
1944            while kx.current() != r {
1945                kx.switch_context();
1946            }
1947            let mut out = [0u8; 4];
1948            assert_eq!(kx.stream_buffer_receive(sb, &mut out, 1), Ok(Wait::Blocked));
1949            // One tick: R times out and is the highest ready task.
1950            if kx.increment_tick() {
1951                kx.switch_context();
1952            }
1953            while kx.current() != r {
1954                kx.switch_context();
1955            }
1956            // Now R's call resumes; the next tick -- H's -- lands at the
1957            // k-th exit inside it.
1958            let base = kx.port().exits.get();
1959            kx.port().at.set(base.wrapping_add(k));
1960            let first = kx.stream_buffer_receive(sb, &mut out, 1);
1961            if first == Ok(Wait::Blocked) {
1962                if kx.current() == h {
1963                    preempted_inside += 1;
1964                }
1965                // H runs and sleeps again; R runs again and finishes its call.
1966                while kx.current() != h {
1967                    kx.switch_context();
1968                }
1969                kx.delay(50).expect("H delays");
1970                while kx.current() != r {
1971                    kx.switch_context();
1972                }
1973                assert_eq!(
1974                    kx.stream_buffer_receive(sb, &mut out, 1),
1975                    Ok(Wait::Ready(0)),
1976                    "tick at exit {k} of the resumed call: the timed-out receive must answer 0, \
1977                     not wait again"
1978                );
1979            } else {
1980                assert_eq!(first, Ok(Wait::Ready(0)), "tick at exit {k}");
1981            }
1982        }
1983        assert!(
1984            preempted_inside > 0,
1985            "no alignment preempted R inside its resumed call: the test reached nothing"
1986        );
1987    }
1988}