Skip to main content

rusty_rtos_kernel_core/
events.rs

1//! Event groups: `event_groups.c`.
2//!
3//! An event group is a word of bits and a list of the tasks waiting on some
4//! of them. It is the one FreeRTOS primitive with no queue underneath — a
5//! waiter's *condition* lives in its own event list item, so setting a bit
6//! is one walk of that list asking each waiter whether it is satisfied.
7//!
8//! # The item value is the condition
9//!
10//! `vTaskPlaceOnUnorderedEventList` writes the bits a task is waiting for
11//! into `xEventListItem`, where a priority-ordered event list would have
12//! kept `configMAX_PRIORITIES - uxPriority`. The top byte carries three
13//! flags with it — clear-on-exit, wait-for-all, and the one the unblocker
14//! sets to say *why* the task woke — which is why the usable bits are the
15//! bottom 24 and every comparison masks first.
16//!
17//! A task that times out is taken off the event list by the tick, so its
18//! item value keeps the flags it blocked with and *not* the
19//! unblocked-due-to-bit-set one. That difference is the whole of the C's
20//! timeout test, and it is why this module needs no timeout flag of its own.
21
22use rusty_rtos_core::config::Config;
23use rusty_rtos_core::error::{Error, Result};
24use rusty_rtos_core::handle::{EventGroupHandle, TaskHandle};
25use rusty_rtos_core::hooks::TickHook;
26use rusty_rtos_core::isr::Woken;
27use rusty_rtos_core::list::ListId;
28use rusty_rtos_core::port::Port;
29use rusty_rtos_core::trace::{Event, Trace};
30
31use crate::kernel::{Kernel, OwedTrace};
32use crate::lists_for;
33use crate::queue::Wait::{self, Ready};
34
35/// `EventGroup_t`: the bits, and nothing else — the list of waiting tasks
36/// is one of the kernel's, named by the group's arena index.
37#[derive(Debug, Clone, Copy, Default, PartialEq, Eq)]
38pub struct EventGroup {
39    /// `uxEventBits`.
40    pub(crate) bits: u32,
41}
42
43/// `eventCLEAR_EVENTS_ON_EXIT_BIT`.
44const CLEAR_EVENTS_ON_EXIT: u64 = 0x0100_0000;
45/// `eventUNBLOCKED_DUE_TO_BIT_SET`.
46const UNBLOCKED_DUE_TO_BIT_SET: u64 = 0x0200_0000;
47/// `eventWAIT_FOR_ALL_BITS`.
48const WAIT_FOR_ALL_BITS: u64 = 0x0400_0000;
49/// `eventEVENT_BITS_CONTROL_BYTES`: the top byte of a 32-bit `EventBits_t`,
50/// which the three flags and `taskEVENT_LIST_ITEM_VALUE_IN_USE` share.
51pub(crate) const EVENT_BITS_CONTROL_BYTES: u64 = 0xff00_0000;
52
53/// The `function` a `TickHook::pended` sees for `xEventGroupSetBitsFromISR`.
54pub const PENDED_SET_BITS: u16 = u16::MAX;
55/// The `function` a `TickHook::pended` sees for
56/// `xEventGroupClearBitsFromISR`.
57pub const PENDED_CLEAR_BITS: u16 = u16::MAX - 1;
58
59impl<
60    C: Config,
61    P: Port,
62    T: Trace,
63    H,
64    const TASKS: usize,
65    const ITEMS: usize,
66    const LISTS: usize,
67    const QUEUES: usize,
68    const SLOTS: usize,
69    const BUFFERS: usize,
70    const BYTES: usize,
71    const TIMERS: usize,
72    const GROUPS: usize,
73> Kernel<C, P, T, H, TASKS, ITEMS, LISTS, QUEUES, SLOTS, BUFFERS, BYTES, TIMERS, GROUPS>
74where
75    H: TickHook<Self>,
76{
77    /// `xTasksWaitingForBits` of one group.
78    pub(crate) fn event_group_list(group: EventGroupHandle) -> ListId {
79        let base = u8::try_from(lists_for(C::MAX_PRIORITIES, QUEUES, 0)).unwrap_or(u8::MAX);
80        base.saturating_add(u8::try_from(group.index()).unwrap_or(u8::MAX))
81    }
82
83    /// `prvTestWaitCondition`.
84    const fn wait_condition_met(current: u32, wait_for: u32, all: bool) -> bool {
85        if all {
86            current & wait_for == wait_for
87        } else {
88            current & wait_for != 0
89        }
90    }
91
92    /// `xEventGroupCreate`.
93    ///
94    /// # Errors
95    /// [`Error::Full`] when the arena is full, which is `NULL` in the C.
96    pub fn event_group_create(&mut self) -> Result<EventGroupHandle> {
97        self.account_for_allocation();
98        let group = self
99            .groups
100            .try_insert(EventGroup::default())
101            .map_err(|_| Error::Full)?;
102        // `vListInitialise( &( pxEventBits->xTasksWaitingForBits ) )`. The
103        // arena hands slots back out, so a group's list is whatever the
104        // last group at that index left behind.
105        let list = Self::event_group_list(group);
106        while let Ok(Some(item)) = self.lists.head(list) {
107            let _ = self.lists.remove(item);
108        }
109        let tick = self.tick;
110        self.trace.note_exits(self.port.exits());
111        self.trace.event(tick, Event::EventGroupCreate { group });
112        Ok(group)
113    }
114
115    /// `vEventGroupDelete`.
116    ///
117    /// Every waiter is unblocked with a value of zero and the bit-set flag,
118    /// so each wakes, finds its condition unmet, and reports what the C
119    /// reports: a timeout.
120    ///
121    /// # Errors
122    /// [`Error::Gone`] for a stale handle.
123    pub fn event_group_delete(&mut self, group: EventGroupHandle) -> Result<()> {
124        self.groups.resolve(group)?;
125        self.suspend_all();
126        let list = Self::event_group_list(group);
127        while let Ok(Some(item)) = self.lists.head(list) {
128            self.remove_from_unordered_event_list(item, UNBLOCKED_DUE_TO_BIT_SET)?;
129        }
130        let _ = self.groups.remove(group);
131        let _ = self.resume_all();
132        // `vPortFree( pxEventBits )`, outside the resume — and every
133        // `heap_N.c` wraps free the same way it wraps malloc, so it costs
134        // its own outermost exit.
135        self.account_for_allocation();
136        Ok(())
137    }
138
139    /// `xEventGroupGetBits`, which the C defines as
140    /// `xEventGroupClearBits( xEventGroup, 0 )` — so it costs the same
141    /// critical section a clear does.
142    ///
143    /// # Errors
144    /// [`Error::Gone`] for a stale handle.
145    pub fn event_group_bits(&mut self, group: EventGroupHandle) -> Result<u32> {
146        self.event_group_clear_bits(group, 0)
147    }
148
149    /// `xEventGroupGetBitsFromISR`. The Posix port's interrupt mask costs
150    /// nothing, so neither does this.
151    ///
152    /// # Errors
153    /// [`Error::Gone`] for a stale handle.
154    pub fn event_group_bits_from_isr(&self, group: EventGroupHandle) -> Result<u32> {
155        Ok(self.groups.resolve(group)?.bits)
156    }
157
158    /// `xEventGroupClearBits`: the bits as they were, then cleared.
159    ///
160    /// # Errors
161    /// [`Error::Gone`] for a stale handle.
162    pub fn event_group_clear_bits(&mut self, group: EventGroupHandle, bits: u32) -> Result<u32> {
163        self.enter_critical();
164        // `traceEVENT_GROUP_CLEAR_BITS` is not one of the harness's hooks.
165        let result = self.groups.resolve_mut(group).map(|g| {
166            let before = g.bits;
167            g.bits &= !bits;
168            before
169        });
170        self.exit_critical();
171        result
172    }
173
174    /// `xEventGroupSetBits`: set them, then wake every waiter the new value
175    /// satisfies and clear whatever those waiters asked to have cleared.
176    ///
177    /// # Errors
178    /// [`Error::Gone`] for a stale handle.
179    pub fn event_group_set_bits(&mut self, group: EventGroupHandle, bits: u32) -> Result<u32> {
180        self.groups.resolve(group)?;
181        let list = Self::event_group_list(group);
182        self.suspend_all();
183        let tick = self.tick;
184        self.trace.note_exits(self.port.exits());
185        self.trace
186            .event(tick, Event::EventGroupSetBits { group, bits });
187        if let Ok(g) = self.groups.resolve_mut(group) {
188            g.bits |= bits;
189        }
190        let mut to_clear: u32 = 0;
191        let mut item = self.lists.head(list)?;
192        while let Some(this) = item {
193            // The next one is read before this one is unblocked, because
194            // unblocking takes it off the list this walk is standing in.
195            let next = self.lists.next(this)?;
196            let value = self.lists.value(this)?;
197            let control = value & EVENT_BITS_CONTROL_BYTES;
198            let waited_for = (value & !EVENT_BITS_CONTROL_BYTES) as u32;
199            let current = self.groups.resolve(group)?.bits;
200            if Self::wait_condition_met(current, waited_for, control & WAIT_FOR_ALL_BITS != 0) {
201                if control & CLEAR_EVENTS_ON_EXIT != 0 {
202                    to_clear |= waited_for;
203                }
204                self.remove_from_unordered_event_list(
205                    this,
206                    u64::from(current) | UNBLOCKED_DUE_TO_BIT_SET,
207                )?;
208            }
209            item = next;
210        }
211        let result = match self.groups.resolve_mut(group) {
212            Ok(g) => {
213                g.bits &= !to_clear;
214                g.bits
215            }
216            Err(_) => 0,
217        };
218        let _ = self.resume_all();
219        Ok(result)
220    }
221
222    /// `xEventGroupSetBitsFromISR`.
223    ///
224    /// An interrupt cannot walk the waiting list, so the C hands the job to
225    /// the daemon task through `xTimerPendFunctionCallFromISR` and answers
226    /// whether the daemon took it, not what the bits became.
227    ///
228    /// # Errors
229    /// As the queue send behind `xTimerPendFunctionCallFromISR`.
230    pub fn event_group_set_bits_from_isr(
231        &mut self,
232        group: EventGroupHandle,
233        bits: u32,
234    ) -> Result<(bool, Woken)> {
235        self.pend_group_call(PENDED_SET_BITS, group, bits)
236    }
237
238    /// `xEventGroupClearBitsFromISR`, deferred the same way.
239    ///
240    /// # Errors
241    /// As the queue send behind `xTimerPendFunctionCallFromISR`.
242    pub fn event_group_clear_bits_from_isr(
243        &mut self,
244        group: EventGroupHandle,
245        bits: u32,
246    ) -> Result<(bool, Woken)> {
247        self.pend_group_call(PENDED_CLEAR_BITS, group, bits)
248    }
249
250    /// The group's handle is `pvParameter1` and the bits are
251    /// `ulParameter2`, exactly as the C passes them.
252    fn pend_group_call(
253        &mut self,
254        function: u16,
255        group: EventGroupHandle,
256        bits: u32,
257    ) -> Result<(bool, Woken)> {
258        self.timer_pend_function_call_from_isr(function, u64::from(group.index()), u64::from(bits))
259    }
260
261    /// The daemon task's half of those two: `vEventGroupSetBitsCallback`
262    /// and `vEventGroupClearBitsCallback`.
263    ///
264    /// A [`TickHook::pended`] implementation routes [`PENDED_SET_BITS`] and
265    /// [`PENDED_CLEAR_BITS`] here; every other `function` is the
266    /// application's own.
267    ///
268    /// # Errors
269    /// [`Error::Gone`] when the group has been deleted since.
270    pub fn event_group_pended_call(
271        &mut self,
272        function: u16,
273        param1: u64,
274        param2: u64,
275    ) -> Result<()> {
276        let Some(group) = self.groups.handle_at(param1 as u16) else {
277            return Err(Error::Gone);
278        };
279        let bits = param2 as u32;
280        match function {
281            PENDED_SET_BITS => {
282                self.event_group_set_bits(group, bits)?;
283            }
284            PENDED_CLEAR_BITS => {
285                self.event_group_clear_bits(group, bits)?;
286            }
287            _ => {}
288        }
289        Ok(())
290    }
291
292    /// `xEventGroupWaitBits`.
293    ///
294    /// The C blocks in the middle of this function and finishes it on the
295    /// far side of the switch. A kernel with no stacks cannot, so a call
296    /// that has to block answers [`Wait::Blocked`] and is called again; the
297    /// second call *is* the far side, and starts at
298    /// `uxTaskResetEventItemValue`.
299    ///
300    /// # Errors
301    /// [`Error::Gone`] for a stale handle.
302    pub fn event_group_wait_bits(
303        &mut self,
304        group: EventGroupHandle,
305        wait_for: u32,
306        clear_on_exit: bool,
307        wait_for_all: bool,
308        ticks: u64,
309    ) -> Result<Wait<u32>> {
310        let caller = self.current();
311        if self.take_event_resume(caller) {
312            let value = self.reset_event_item_value(caller)?;
313            let bits = self.finish_wait(group, value, wait_for, clear_on_exit, wait_for_all)?;
314            self.trace_wait_bits_end(
315                caller,
316                group,
317                wait_for,
318                value & UNBLOCKED_DUE_TO_BIT_SET == 0,
319            );
320            return Ok(Ready(bits));
321        }
322
323        self.groups.resolve(group)?;
324        self.suspend_all();
325        let current = self.groups.resolve(group)?.bits;
326        let mut blocked = false;
327        let mut timed_out = false;
328        let mut result = current;
329        if Self::wait_condition_met(current, wait_for, wait_for_all) {
330            if clear_on_exit {
331                if let Ok(g) = self.groups.resolve_mut(group) {
332                    g.bits &= !wait_for;
333                }
334            }
335        } else if ticks == 0 {
336            timed_out = true;
337        } else {
338            let mut control = 0;
339            if clear_on_exit {
340                control |= CLEAR_EVENTS_ON_EXIT;
341            }
342            if wait_for_all {
343                control |= WAIT_FOR_ALL_BITS;
344            }
345            self.place_on_unordered_event_list(
346                Self::event_group_list(group),
347                u64::from(wait_for) | control,
348                ticks,
349            )?;
350            result = 0;
351            let tick = self.tick;
352            self.trace.note_exits(self.port.exits());
353            self.trace.event(
354                tick,
355                Event::EventGroupWaitBitsBlock {
356                    group,
357                    bits: wait_for,
358                },
359            );
360            blocked = true;
361        }
362        let already_yielded = self.resume_all();
363        if blocked {
364            if !already_yielded {
365                self.yield_or_owe(caller);
366            }
367            self.set_event_resume(caller);
368            return Ok(Wait::Blocked);
369        }
370        self.trace_wait_bits_end(caller, group, wait_for, timed_out);
371        Ok(Ready(result))
372    }
373
374    /// `xEventGroupSync`: set some bits, then wait for a set that usually
375    /// includes them — the rendezvous every task in a group must reach.
376    ///
377    /// It has its own two trace points, `traceEVENT_GROUP_SYNC_BLOCK` and
378    /// `traceEVENT_GROUP_SYNC_END`, which the Kairos harness does not hook.
379    /// The `xEventGroupSetBits` inside it traces as itself, and that is the
380    /// only line a sync puts in the trace.
381    ///
382    /// # Errors
383    /// [`Error::Gone`] for a stale handle.
384    pub fn event_group_sync(
385        &mut self,
386        group: EventGroupHandle,
387        set: u32,
388        wait_for: u32,
389        ticks: u64,
390    ) -> Result<Wait<u32>> {
391        let caller = self.current();
392        if self.take_event_resume(caller) {
393            let value = self.reset_event_item_value(caller)?;
394            return Ok(Ready(self.finish_sync(group, value, wait_for)?));
395        }
396
397        self.groups.resolve(group)?;
398        self.suspend_all();
399        let original = self.groups.resolve(group)?.bits;
400        self.event_group_set_bits(group, set)?;
401        let mut blocked = false;
402        let result;
403        if (original | set) & wait_for == wait_for {
404            result = original | set;
405            if let Ok(g) = self.groups.resolve_mut(group) {
406                g.bits &= !wait_for;
407            }
408        } else if ticks == 0 {
409            result = self.groups.resolve(group)?.bits;
410        } else {
411            self.place_on_unordered_event_list(
412                Self::event_group_list(group),
413                u64::from(wait_for) | CLEAR_EVENTS_ON_EXIT | WAIT_FOR_ALL_BITS,
414                ticks,
415            )?;
416            result = 0;
417            blocked = true;
418        }
419        let already_yielded = self.resume_all();
420        if blocked {
421            if !already_yielded {
422                self.yield_or_owe(caller);
423            }
424            self.set_event_resume(caller);
425            return Ok(Wait::Blocked);
426        }
427        Ok(Ready(result))
428    }
429
430    /// The tail of `xEventGroupWaitBits` past the switch: a task woken by
431    /// the unblocker already has its answer in the item value, and one
432    /// woken by the tick has to look at the group again.
433    fn finish_wait(
434        &mut self,
435        group: EventGroupHandle,
436        value: u64,
437        wait_for: u32,
438        clear_on_exit: bool,
439        wait_for_all: bool,
440    ) -> Result<u32> {
441        if value & UNBLOCKED_DUE_TO_BIT_SET != 0 {
442            return Ok((value & !EVENT_BITS_CONTROL_BYTES) as u32);
443        }
444        self.enter_critical();
445        let bits = self.groups.resolve(group).map(|g| g.bits);
446        if let Ok(bits) = bits {
447            if Self::wait_condition_met(bits, wait_for, wait_for_all) && clear_on_exit {
448                if let Ok(g) = self.groups.resolve_mut(group) {
449                    g.bits &= !wait_for;
450                }
451            }
452        }
453        self.exit_critical();
454        Ok((u64::from(bits?) & !EVENT_BITS_CONTROL_BYTES) as u32)
455    }
456
457    /// The same tail for `xEventGroupSync`, whose re-test is always
458    /// wait-for-all and whose clear is not conditional on a flag.
459    fn finish_sync(&mut self, group: EventGroupHandle, value: u64, wait_for: u32) -> Result<u32> {
460        if value & UNBLOCKED_DUE_TO_BIT_SET != 0 {
461            return Ok((value & !EVENT_BITS_CONTROL_BYTES) as u32);
462        }
463        self.enter_critical();
464        let bits = self.groups.resolve(group).map(|g| g.bits);
465        if let Ok(bits) = bits {
466            if bits & wait_for == wait_for {
467                if let Ok(g) = self.groups.resolve_mut(group) {
468                    g.bits &= !wait_for;
469                }
470            }
471        }
472        self.exit_critical();
473        Ok((u64::from(bits?) & !EVENT_BITS_CONTROL_BYTES) as u32)
474    }
475
476    /// `traceEVENT_GROUP_WAIT_BITS_END`, owed to `caller` when the
477    /// `xTaskResumeAll` before it has already handed the CPU on.
478    fn trace_wait_bits_end(
479        &mut self,
480        caller: TaskHandle,
481        group: EventGroupHandle,
482        bits: u32,
483        timed_out: bool,
484    ) {
485        self.trace_failure_or_owe(
486            caller,
487            OwedTrace::EventGroupWaitBitsEnd {
488                group,
489                bits,
490                timed_out,
491            },
492        );
493    }
494}