pub struct Name { /* private fields */ }Expand description
A task name: at most NAME_CAPACITY bytes, truncated to the
configuration’s MAX_TASK_NAME_LEN exactly as C truncates it.
§Why this is aligned to eight ON A 64-BIT HOST ONLY
as_str validates a sixteen-byte window so that run_utf8_validation
takes its word-at-a-time ASCII path instead of walking the name a byte at
a time. That path has TWO conditions and the window size is only one of
them: core’s loop reads two usizes at a time and declines unless the
slice is usize-ALIGNED (align_offset(size_of::<usize>()) == 0).
Nothing said so, and on the host the alignment was absent. Tcb holds a
Name as its first field and is four-aligned deliberately – see
WaitFrame, whose Split64 fields exist to keep it that way – and
Slot<Tcb> puts a u32 generation in front of it, so bytes landed at
offset four of every slot. Measured with callgrind on a sixteen-byte
window holding CNT_INC:
| window offset | Ir per from_utf8 |
|---|---|
0 (usize-aligned) | 46 |
4 (what Slot<Tcb> gave it) | 143 |
| 1 | 161 |
bench/kernel-ir measured 142.7 in production – offset four to within a
third of an instruction. The optimisation was documented, tested, and off.
§★ And it was off only on the HOST, which is why it survived
usize is FOUR bytes on every target this kernel ships to, so offset four
is already usize-aligned there and the ASCII path was being taken all
along. The defect existed only where usize is eight – the 64-bit host
that runs the sim and the conformance suite. That is the pointer-width
asymmetry this project has paid for before (docs/LEDGER.md), and it is
why the alignment is requested with a cfg_attr rather than outright:
asking for eight unconditionally would grow Tcb on a 32-bit target, and
spend real firmware RAM to fix a host-only cost.
So this buys the sim and kairos conform --all about ten percent of their
instructions and buys firmware nothing, by design. It changes no layout a
target sees.
Implementations§
Source§impl Name
impl Name
Sourcepub fn new(name: &str, max_len: usize) -> Self
pub fn new(name: &str, max_len: usize) -> Self
Copy name, truncated the way prvInitialiseNewTask truncates:
at most max_len - 1 bytes, because the C array’s last slot is the
NUL. max_len of 0 yields an empty name, as C’s loop would.
Truncation happens on a character boundary, so the result is always valid UTF-8 — C truncates on a byte, but every name in the corpus is ASCII and a name that is not is a configuration error, not a silent mojibake.
Sourcepub fn as_str(&self) -> &str
pub fn as_str(&self) -> &str
The name as it will be printed.
In line on purpose, and with the clamp below: a trace prints two names on every context switch, and out of line each one paid a call and a frame to hand back a slice of a field the caller already had.
Sourcepub fn matches(&self, other: &str) -> bool
pub fn matches(&self, other: &str) -> bool
Whether this name is other.
Compares BYTES. Two strs are equal exactly when their bytes are, so
this answers what self.as_str() == other answered — without the
UTF-8 validation that makes a &str, which is the only thing that
pulled core::str::from_utf8 into a kernel built with NoTrace.
Measured on bench/kernel-flash: 534 bytes, 3.2 % of the arm, for
one comparison in task_get_handle.