Keyronex Keyronex manual pages

RCU(9) Kernel Developer's Manual RCU(9)

rcu, ke_rcu_read_lock, ke_rcu_read_unlock, ke_rcu_call, ke_rcu_synchronise — read-copy-update work deferral mechanism

#include <kdk/kern.h>

ipl_t
ke_rcu_read_lock(void);

void
ke_rcu_read_unlock(ipl_t ipl);

void
ke_rcu_call(rcu_entry_t *entry, void (*callback)(void *), void *arg);

void
ke_rcu_synchronise(void);

The Read-Copy-Update (RCU) mechanism is a mechanism for scheduling work to be done after a grace period has passed. This is useful for updating or freeing data structures by guaranteeing that no readers are accessing the data structure by the time it is freed.

Readers enter an RCU critical section by calling () and leave it by calling (). These very cheap functions raise and lower the IPL respectively - the IPL is raised to kIPLDPC. It is forbidden to sleep while within an RCU critical section. (See ipl(9) for further restrictions incurred by the raised IPL.)

Writers may schedule work by calling () with a pointer to an RCU entry embedded somewhere. This schedules a callback to be called with the given argument after a grace period has elapsed; this grace period is however long it takes until every reader who entered an RCU critical section has left it. The callback callback will be called with the argument given in arg. Note that the RCU entry cannot be used for anything else until the callback has ran.

The () function synchronously awaits the end of the grace period.

Readers and writers must take care to use appropriate operations on data subject to RCU reclamation. See ke_rcu_dereference(9) for routines that readers can use to safely read and writers to safely update pointers. These may not be necessary in certain cases, particularly when using suitable atomic operations, for example when using RCU to provide a fallible reference-count retain function.

An RCU critical section may be explicitly entered from any context at or below DPC level, and a critical section is implicit in DPC and interrupt context.

Writers may schedule work from any context at or below DPC level, but may only use ke_rcu_synchronise() from thread context at IPL < DPC level.

RCU is implemented in kernel/kern/rcu.c

The RCU interface is declared in kernel/include/kdk/kern.h

ipl(9), ke_rcu_dereference(9)

The RCU interface appeared in Keyronex in 2023.

October 5, 2024 Debian