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}