Part IX — Software Architecture: Level 2 (High-Level Design) and Level 3 (Detailed Component Design)¶

---
type: PartDef
name: KernelSoftware
domain: software
asilLevel: D
satisfies:
  - REQ-SYS-KERNEL-001
  - REQ-SYS-KERNEL-002
allocatedTo: Hardware::CortexM33Core
custom_fields:
  mg_cell: W3
  mg_layer: logical
  mg_soi: true
---

Top-level software container for the sabaton-rt kernel. All subsystems
are owned by this block. Allocated to Cortex-M33 Core 0 in the SMP/AMP variants.

---
type: PartDef
name: Scheduler
domain: software
asilLevel: D
supertype: Architecture::Logical::KernelSoftware
satisfies:
  - REQ-SCHED-001
  - REQ-SCHED-002
  - REQ-SCHED-003
features:
  - name: readyQueue
    type: Port
    typedBy: Interfaces::ReadyQueuePortDef
    direction: inout
  - name: tickInput
    type: Port
    typedBy: Interfaces::TickPortDef
    direction: in
custom_fields:
  mg_cell: W3
  mg_layer: logical
---

Priority-preemptive scheduler subsystem. Maintains one heapless bitmap-indexed
ready queue per priority level. Scheduling decision is O(1) in thread count
(REQ-SCHED-WCET-001). Context-switch initiation via the `contextSwitch` port.

---
type: PortDef
name: ReadyQueuePortDef
conjugates: Architecture::Interfaces::ReadyQueuePortDef
---

The ready-queue interface. Exported by the Scheduler; consumed by the PortAdapter
when building the initial stack frame and by the IPC layer when unblocking threads.
Operations: enqueue(priority, tcb_ptr), dequeue() → tcb_ptr, peek() → tcb_ptr.

---
type: InterfaceDef
name: SchedulerIpcInterfaceDef
ends:
  - name: scheduler
    typedBy: Architecture::Interfaces::ReadyQueuePortDef
    direction: out
  - name: ipcLayer
    typedBy: Architecture::Interfaces::ReadyQueuePortDef
    direction: in
    isConjugated: true
---

The contract between Scheduler and IpcLayer. The IPC layer calls into the
scheduler to enqueue a newly unblocked thread; the scheduler provides the
`dequeue` operation for the context-switch path.

---
type: PartDef
name: KernelSoftware
connections:
  - from: scheduler.readyQueue
    to: ipcLayer.readyQueueOut
    typedBy: Architecture::Interfaces::SchedulerIpcInterfaceDef
  - from: scheduler.tickInput
    to: portAdapter.tickOut
  - from: safetyLayer.watchdogTickle
    to: portAdapter.watchdogIn
---

---
type: ItemDef
name: ThreadControlBlockRef
domain: software
---

A reference (pointer or index) to a Thread Control Block. The item that flows
on the ready-queue interface. Safety property: integrity — a corrupted TCB ref
is the primary failure mode in FTE-KERNEL-101.

---
type: ItemDef
name: TickEvent
domain: software
---

A tick event signalling the passage of one scheduler quantum. Sourced by the
SysTick ISR via the PortAdapter; consumed by the Scheduler (WCET budgeting)
and TimerSubsystem (software timer expiry check).

---
type: PartDef
name: KernelSoftware
flowConnections:
  - from: portAdapter.tickOut
    to: scheduler.tickInput
    itemType: Architecture::Data::TickEvent
  - from: ipcLayer.unblockOut
    to: scheduler.enqueueIn
    itemType: Architecture::Data::ThreadControlBlockRef
---

---
type: ActionDef
name: HandleContextSwitch
refines:
  - REQ-SCHED-001
allocatedTo: Architecture::Logical::Scheduler
custom_fields:
  mg_cell: W2
---

Invoked by PendSV ISR (via PortAdapter). Saves outgoing thread registers to
its TCB stack frame; selects highest-priority ready thread via `dequeue()`;
restores incoming thread registers from its TCB. Total WCET bounded by
REQ-SCHED-WCET-001.

---
type: StateDef
name: ThreadLifecycle
subStates:
  - name: Ready
    isInitial: true
    transitions:
      - accept: ContextSwitchIn
        target: Running
  - name: Running
    transitions:
      - accept: ContextSwitchOut
        target: Ready
      - accept: BlockingCall
        target: Blocked
      - accept: Terminate
        target: Terminated
  - name: Blocked
    transitions:
      - accept: Unblock
        target: Ready
  - name: Terminated
    isFinal: true
---

Thread state machine — the subsystem-level view. Unit-level transitions
(internal scheduler queue manipulations) are at L3.

# on the Scheduler PartDef:
exhibitsStates:
  - Architecture::Behavior::ThreadLifecycle

---
type: ADR
id: ADR-ASIL-DECOMP-001
name: "ASIL D decomposed as ASIL B + ASIL B for stack limit enforcement"
status: accepted
---

## Context

REQ-STKLIM-001 (ASIL D) requires stack overflow detection. ARMv8-M provides
PSPLIM (hardware, ASIL B channel) and the watchdog deadman (firmware, ASIL B
channel). Both channels are independent: the PSPLIM failure mode (FTE-KERNEL-103)
and the watchdog failure mode (FTE-KERNEL-104) have no shared cause.

## Decision

Decompose ASIL D → ASIL B (channel A: PSPLIM) + ASIL B (channel B: watchdog),
per ISO 26262-9 §5. Each channel satisfies one half of the original ASIL D demand.

## Consequences

Each channel must be verified independently. FTE-KERNEL-103 and FTE-KERNEL-104
must remain independent (no common-cause failure path).

---
type: Allocation
name: SafetyLayerToTimerSubsystem
allocatedFrom: Architecture::Logical::SafetyLayer
allocatedTo: Architecture::Logical::TimerSubsystem
---

SafetyLayer (ASIL D) calls into TimerSubsystem (ASIL B) for watchdog tickle.
FFI argument: the call is unidirectional (SafetyLayer → TimerSubsystem); the
TimerSubsystem cannot corrupt SafetyLayer data. Spatial isolation enforced by
MPU domain (REQ-MPU-DOMAIN-001). Temporal isolation enforced by PSPLIM.
See ARG-KERNEL-403 for the full freedom-from-interference argument.

---
type: PartDef
name: ReadyQueue
domain: software
supertype: Architecture::Logical::Scheduler     # L2 parent
asilLevel: D
custom_fields:
  mg_cell: S3
  mg_layer: physical
satisfies:
  - REQ-SCHED-001
implementedBy: kernel/src/scheduler/ready_queue.rs
---

The bitmap-indexed, fixed-size ready queue. Provides O(1) `enqueue`, `dequeue`,
and `peek_highest` operations. No heap allocation — all state is in the statically
allocated `ReadyQueueHarness` struct.

**Resource usage**: 8 bytes per priority level (32-bit bitmap + pointer).
At 32 priority levels: 256 bytes in `.bss`.
**Stack depth**: 4 words (enqueue); 3 words (dequeue/peek). No recursion.

---
type: PartDef
name: ContextSwitchEngine
domain: software
supertype: Architecture::Logical::Scheduler
asilLevel: D
custom_fields:
  mg_cell: S3
  mg_layer: physical
satisfies:
  - REQ-SCHED-WCET-001
implementedBy: ports/cortex-m/src/context_switch.rs
---

The PendSV handler and register save/restore sequence. Implemented in naked
assembly with an explicit stack frame layout documented in REQ-PORT-FRAME-001.

---
type: PortDef
name: ReadyQueueEnqueuePortDef
---

**Operation**: `enqueue(priority: u8, tcb: *mut Tcb) -> Result<(), QueueFull>`

**Preconditions**:
  - `priority` ∈ [0, MAX_PRIORITY)  (else: panic in debug, UB in release — AOU)
  - `tcb` is non-null and aligned to `align_of::<Tcb>()`
  - Caller holds the scheduler critical section (not called from thread context)

**Postconditions**:
  - `peek_highest()` returns a thread with priority ≥ the enqueued thread's priority
  - The enqueued thread is reachable by `dequeue()` after any number of higher-priority
    `enqueue` / `dequeue` operations

**Error**: `QueueFull` when the priority level's slot is already occupied (this is a
design invariant violation — `safety_assert!` triggers the safety reaction).

**WCET**: O(1) — one bitmap write + one linked-list insert; ≤ 12 cycles at 120 MHz
(measured in TC-SCHED-WCET-001).

# on ReadyQueue PartDef:
features:
  - name: enqueuePort
    type: Port
    typedBy: Architecture::Interfaces::L3::ReadyQueueEnqueuePortDef
    direction: out

---
type: EnumerationDef
name: ThreadState
values:
  - name: Ready
    description: "Thread is in the ready queue, eligible for scheduling"
  - name: Running
    description: "Thread holds the CPU — exactly one thread per core"
  - name: Blocked
    description: "Thread is waiting on an IPC object or timer"
  - name: Suspended
    description: "Thread is suspended by the application"
  - name: Terminated
    description: "Thread has returned from its entry function"
---

---
type: PartDef
name: ThreadControlBlock
domain: software
asilLevel: D
custom_fields:
  mg_cell: S3
  mg_layer: physical
features:
  - name: savedSp
    type: Attribute
    typedBy: Architecture::Data::StackPointer
    description: "Saved stack pointer; valid when state ≠ Running"
  - name: priority
    type: Attribute
    typedBy: Architecture::Data::Priority
    description: "Static priority in [0, MAX_PRIORITY); immutable after creation"
  - name: state
    type: Attribute
    typedBy: Architecture::Data::ThreadState
    description: "Current lifecycle state — transitions per ThreadLifecycle state machine"
  - name: stackBase
    type: Attribute
    typedBy: Architecture::Data::StackPointer
    description: "Base of the thread stack; used for PSPLIM initialisation"
  - name: stackSize
    type: Attribute
    typedBy: Architecture::Data::ByteCount
    description: "Size in bytes; used for MPU region calculation"
  - name: canary
    type: Attribute
    typedBy: Architecture::Data::U32
    description: "Stack canary at the top of the stack (lowest address); checked by SC-KERNEL-004"
  - name: nextReady
    type: Attribute
    typedBy: Architecture::Data::TcbRef
    description: "Intrusive linked-list link within the ready queue; null if not ready"
---

The Thread Control Block is the central data structure. Integrity of this struct is
ASIL D — corruption is the failure mode in FTE-KERNEL-101 (stack overflow), FTE-KERNEL-201
(MPU misconfiguration). The `canary` field is the primary detection mechanism (SC-KERNEL-004).

---
type: ActionDef
name: ScheduleNext
refines:
  - REQ-SCHED-001
allocatedTo: Architecture::Physical::ReadyQueue
custom_fields:
  mg_cell: S2          # behaviour lives in column 2 (S3 is for structure — MG021)
parameters:
  - name: currentThread
    typedBy: Architecture::Data::TcbRef
    direction: in
subActions:
  - name: selectNext
    typedBy: Architecture::Behavior::SelectNext       # O(1) CLZ on the ready bitmap
  - name: saveContext
    typedBy: Architecture::Behavior::SaveContext      # {r4-r11, lr} → currentThread.savedSp
  - name: loadContext
    typedBy: Architecture::Behavior::LoadContext      # restore from selectedThread.savedSp
controlNodes:
  - name: sameThread
    kind: DecisionNode   # selectedThread == currentThread → skip save/load
  - name: done
    kind: MergeNode
successionConnections:
  - after: selectNext
    before: sameThread
  - after: sameThread
    before: saveContext
    guard: "selectedThread != currentThread"
  - after: sameThread
    before: done
    guard: "selectedThread == currentThread"
  - after: saveContext
    before: loadContext
  - after: loadContext
    before: done
---

**Error path**: if the ready queue bitmap is zero (no ready thread), the kernel panics via
`safety_assert!(false, IDLE_CORRUPTION)` — this should never occur because the idle thread
is always ready.

---
type: StateDef
name: SchedulerUnitStateMachine
subStates:
  - name: Ready
    isInitial: true
    entryAction: Architecture::Behavior::EnqueueSelf
    exitAction: Architecture::Behavior::RemoveSelf
    transitions:
      - accept: Dispatch
        guard: "self.priority == ready_queue.peek_highest().priority"
        target: Running
        effect: Architecture::Behavior::RestorePsp
  - name: Running
    entryAction: Architecture::Behavior::SetCurrentThread
    exitAction: Architecture::Behavior::SavePsp
    transitions:
      - accept: Preempt
        target: Ready
        effect: Architecture::Behavior::PendContextSwitch
      - accept: IpcBlock
        target: Blocked
        effect: Architecture::Behavior::PushWaitlist
      - accept: ThreadReturn
        target: Terminated
        effect: Architecture::Behavior::TerminateThread
  - name: Blocked
    transitions:
      - accept: Unblock
        target: Ready
      - accept: Timeout
        guard: "self.timeout_ticks == 0"
        target: Ready
        effect: Architecture::Behavior::SetTimeoutResult
  - name: Terminated
    isFinal: true
    entryAction: Architecture::Behavior::ReleaseTcb
---

Scheduler state machine — unit level. Refines Architecture::Behavior::ThreadLifecycle.

# on the ReadyQueue or Scheduler PartDef at L3:
exhibitsStates:
  - Architecture::Behavior::SchedulerUnitStateMachine

---
type: Requirement
id: REQ-SCHED-WCET-001
name: "Scheduler context-switch shall complete within bounded WCET"
status: approved
asilLevel: D
wcet: "≤ 200 cycles at 120 MHz on Cortex-M33 (< 1.7 µs) measured at L5"
reqDomain: software
verificationMethod: test
---

---
type: PartDef
name: ReadyQueue
custom_fields:
  wcet_enqueue: "≤ 6 cycles (CLZ + 2× list ops)"
  wcet_dequeue: "≤ 8 cycles (CLZ + list dequeue + bitmap clear)"
  wcet_peek:    "≤ 3 cycles (CLZ only)"
---

---
type: ActionDef
name: HandleEnqueueError
---

Error handling for `ReadyQueue::enqueue` invariant violations.

**Detected conditions**:
- Priority out of range → `safety_assert!(priority < MAX_PRIORITY, PRIORITY_RANGE)`
- Double-enqueue (thread already ready) → `safety_assert!(!self.is_ready(), DOUBLE_ENQUEUE)`
- Null TCB pointer → `safety_assert!(!tcb.is_null(), NULL_TCB)`

**Safety reaction**: `safety_assert!` invokes the registered safety reaction callback
(see SafetyLayer; REQ-SAFETY-REACT-001). If no callback is registered, the system
panics via the port's default handler.

**Relationship to FMEA**: FM-KERNEL-001 (ready-queue pointer corruption) is caught
post-hoc by the canary check. The `safety_assert!` checks above catch precondition
violations at the call site — they are the primary detection mechanism (SC-KERNEL-001)
that gives FM-KERNEL-001 its DC = 0.93.

entries:
  - id: FM-KERNEL-001
    component: Architecture::Physical::ThreadControlBlock   # QName or display name
    failureMode: "nextReady pointer corruption"
    faultTreeRef: FTE-KERNEL-101