Skip to content

Requirements Mapping

antoniogiacomelli edited this page Jul 27, 2026 · 10 revisions

Requirements

This page records requirements currently exercised by the Unity and QEMU test harnesses, plus explicitly marked requirements whose contracts were added after the architectural conformance review and still need dedicated private-harness coverage. Requirement IDs come from QEMU UT_CASE tags where the harness provides them. Host-side Unity tests are treated as parity coverage for matching test names.

Current through RK0 0.42.0.

Functional Module

Harness Notes

  • This harness is still not public. This aids understanding the CI log.
  • QEMU cases use ut_framework.h, UT_CHECK, UT_CASE, and module-level pass/fail markers.
  • utRunCases_ sanitises scheduler-facing globals, fault state, forced ISR state, timeout lists, and deferred post-processing state between cases.
  • QEMU cases use synthetic task contexts for branch-level kernel API testing, unless a case explicitly creates tasks and relies on real dispatch.
  • Rows marked as QEMU semantic coverage are requirement IDs recorded by the QEMU harness or changelog when the public repository does not expose the exact private test function body.
  • Rows marked as coverage pending are contract rows, not evidence claims; add the named QEMU/Unity case before treating them as verified coverage.

Kernel Version

Requirements

ID Requirement Covered by
VER_RQ_01 kGetVersion shall return the encoded version value compiled into the kernel. test_kGetVersion_returns_expected_encoded_value
VER_RQ_02 kIsValidVersion shall report true when the compiled kernel version matches RK_VALID_VERSION. test_kIsValidVersion_matches_compiled_version

Memory Partition

Requirements

ID Requirement Covered by
MEM_RQ_01 kMemPartitionInit shall align partition blocks and initialise partition metadata for a valid pool. test_kMemPartitionInit_aligns_and_initialises_metadata
MEM_RQ_02 kMemPartitionInit shall reject a null partition object and record the invalid-object fault. test_kMemPartitionInit_rejects_null_object_and_records_fault
MEM_RQ_03 kMemPartitionInit shall reject double initialisation of an already initialised partition. test_kMemPartitionInit_prevents_double_initialisation
MEM_RQ_04 kMemPartitionAlloc shall remove allocated blocks from the partition free list. test_kMemPartitionAlloc_and_free_manage_free_list_correctly
MEM_RQ_05 kMemPartitionFree shall return freed blocks to the partition free list. test_kMemPartitionAlloc_and_free_manage_free_list_correctly
MEM_RQ_06 kMemPartitionFree shall make the most recently freed block the next block reused by allocation. test_kMemPartitionFree_reuses_most_recently_freed_block_first
MEM_RQ_07 kMemPartitionAlloc shall reject invalid or uninitialised partition objects without corrupting allocator state. test_kMemPartitionAlloc_detects_invalid_object
MEM_RQ_08 kMemPartitionFree shall reject pointers outside the partition range and preserve allocator state. test_kMemPartitionFree_rejects_pointer_outside_partition_range

Most-Recent-Message Buffer

Requirements

ID Requirement Covered by
MRM_RQ_01 kMRMInit shall initialise the control block and reject double initialisation. test_kMRMInit_initialises_control_block_and_prevents_double_init
MRM_RQ_02 Reserve, publish, get, and unget operations shall preserve the most recently published message. test_kMRMReserve_publish_get_unget_roundtrip_preserves_most_recent_message
MRM_RQ_03 kMRMReserve shall reuse the current buffer when there are no active readers. test_kMRMReserve_reuses_current_buffer_when_no_active_readers
MRM_RQ_04 kMRMReserve shall allocate a new buffer when the current buffer is still in use by readers. test_kMRMReserve_allocates_new_buffer_when_current_is_in_use
MRM_RQ_05 kMRMUnget shall release stale buffers back to the backing memory pool. test_kMRMUnget_releases_stale_buffer_to_pool
MRM_RQ_06 MRM APIs shall reject null, uninitialised, and invalid objects with the expected error paths. test_kMRM_api_rejects_null_uninitialised_and_invalid_objects

Semaphore

Requirements

ID Requirement Covered by
SEMA_RQ_01 kSemaphoreInit shall initialise semaphore fields for valid binary and counting semaphore inputs. test_kSemaphoreInit_sets_expected_fields
SEMA_RQ_02 kSemaphoreInit shall validate object, type, initial count, and maximum count inputs and set the matching fault IDs. test_kSemaphoreInit_validates_inputs_and_sets_faults
SEMA_RQ_03 kSemaphorePend shall consume an available count without blocking. test_kSemaphorePend_consumes_available_count
SEMA_RQ_04 kSemaphorePend with RK_NO_WAIT shall return immediately when no count is available. test_kSemaphorePend_respects_no_wait_and_isr_rules
SEMA_RQ_05 kSemaphorePend shall enforce ISR usage rules. test_kSemaphorePend_respects_no_wait_and_isr_rules
SEMA_RQ_06 kSemaphorePend with a bounded timeout shall time out when no post arrives. test_kSemaphorePend_can_time_out
SEMA_RQ_07 kSemaphorePost shall release waiting tasks before incrementing the stored semaphore count. test_kSemaphorePost_wakes_highest_priority_waiter, test_kSemaphorePost_waiters_take_precedence_over_counter_increment
SEMA_RQ_08 Binary semaphores shall saturate at a count of one when posted without waiters. test_kSemaphorePost_binary_saturates_without_waiters
SEMA_RQ_09 Counting semaphores shall saturate at their configured maximum count when posted without waiters. test_kSemaphorePost_counting_saturates_at_max_without_waiters
SEMA_RQ_10 kSemaphorePost shall wake the highest-priority waiting task. test_kSemaphorePost_wakes_highest_priority_waiter
SEMA_RQ_14 kSemaphorePend shall reject invalid timeout values before blocking. test_kSemaphorePend_rejects_invalid_timeout
SEMA_RQ_15 kSemaphoreQuery shall report available count when no tasks wait and a negative waiter magnitude when tasks are blocked. test_kSemaphoreQuery_reports_waiters_or_count, test_kSemaphoreQuery_reports_negative_waiter_count_magnitude
SEMA_RQ_16 kSemaphorePost shall reject invalid semaphore objects. test_kSemaphorePost_rejects_invalid_objects

Mutex

Requirements

ID Requirement Covered by
MUTX_RQ_01 kMutexInit shall accept supported protocol flags, initialise mutex fields, and reject invalid protocol combinations. test_kMutexInit_accepts_valid_protocol_and_initialises_fields, test_kMutexInit_rejects_invalid_protocol_flags
MUTX_RQ_02 kMutexLock with RK_NO_WAIT shall report the mutex as locked when another task owns it. test_kMutexLock_nowait_reports_mutex_locked
MUTX_RQ_03 kMutexLock shall reject recursive locking by the current owner. test_kMutexLock_rejects_recursive_lock
MUTX_RQ_04 kMutexUnlock shall reject unlock requests when the mutex is not locked. test_kMutexUnlock_rejects_unlock_when_mutex_not_locked
MUTX_RQ_05 kMutexUnlock shall reject unlock requests from a task that does not own the mutex. test_kMutexUnlock_rejects_non_owner
MUTX_RQ_06 kMutexLock shall reject invalid timeout values before blocking on a contended mutex. test_kMutexLock_rejects_invalid_timeout_when_contended
MUTX_RQ_07 Priority inheritance mutexes shall apply transitive priority inheritance across blocked owner chains. test_kMutexLock_applies_transitive_priority_inheritance
MUTX_RQ_08 Mutexes without priority inheritance shall not raise the owner priority when a higher-priority waiter blocks. test_kMutexLock_without_inheritance_does_not_raise_owner_priority
MUTX_RQ_09 kMutexUnlock shall hand ownership to the next waiter and restore the previous owner's priority as appropriate. test_kMutexUnlock_handover_transfers_ownership_and_restores_priority
MUTX_RQ_10 kMutexQuery shall report whether the mutex is currently locked. test_kMutexQuery_reports_lock_state

Scheduler and Task Lifecycle

Requirements

ID Requirement Covered by
SCH_RQ_01 kSwtch shall dispatch the highest-priority ready task when it outranks the current task. test_kSwtch_dispatches_highest_ready_task_when_higher_priority_is_available
SCH_RQ_02 A pre-empted running task shall be returned to the head of its ready queue. test_kSwtch_preempted_running_task_is_jammed_to_ready_head
SCH_RQ_03 kSwtch shall not requeue a running task whose status changed to a blocked state. test_kSwtch_does_not_requeue_blocked_running_task
SCH_RQ_04 kYield shall move the current task to the tail of its ready queue when a same-priority peer is ready. test_kYield_moves_running_task_to_ready_tail_when_peer_is_ready
SCH_RQ_05 kYield shall be a no-op when only lower-priority tasks are ready. test_kYield_is_noop_when_only_lower_priority_tasks_are_ready
SCH_RQ_06 kSchLock shall increment scheduler lock depth for a pre-emptible running task. test_kSchLock_increments_depth_for_preemptible_running_task
SCH_RQ_07 kSchLock shall not change lock depth for a non-pre-emptible running task. test_kSchLock_is_noop_for_non_preemptible_running_task
SCH_RQ_08 kSchUnlock shall release a pending context switch only when the outermost scheduler lock is released. test_kSchUnlock_releases_pending_context_switch_only_on_outermost_unlock
SCH_RQ_09 kSchUnlock shall be a no-op when scheduler lock depth is already zero. test_kSchUnlock_is_noop_when_scheduler_is_not_locked
SCH_RQ_10 kSwtch shall route a selected task with pending signals through the signal-handler task. test_kSwtch_signal_queue_intercepts_selected_task_with_sighandler
SCH_RQ_11 kSwtch shall run a selected signal-capable task normally when it has no pending signals. test_kSwtch_signal_queue_task_without_pending_signals_runs_normally
SCH_RQ_12 kTaskTerminate shall reject static tasks and preserve their handles. test_kTaskTerminate_rejects_static_task_and_preserves_handle
SCH_RQ_13 kCreateTask shall map to the kTaskInit task-creation behaviour. test_kCreateTask_alias_maps_to_kTaskInit_symbol, test_kTaskInit_alias_kCreateTask_creates_non_runtime_spawned_task
SCH_RQ_14 kTaskSpawn shall allocate a dynamic stack block and release it when the spawned task terminates. test_kTaskSpawn_allocates_and_releases_dynamic_stack_block, test_kTaskSpawn_allocates_stack_block_and_terminate_releases_it
SCH_RQ_15 kTaskSpawn shall report pool exhaustion when the dynamic stack partition has no free block. test_kTaskSpawn_returns_pool_empty_when_dynamic_pool_is_exhausted, test_kTaskSpawn_returns_pool_empty_when_stack_partition_is_exhausted
SCH_RQ_16 kPendCtxSwtch shall switch immediately for a non-running task and preserve scheduler lock ownership and depth for the dispatched task. test_kPendCtxSwtch_switches_non_running_task_and_preserves_lock_depth, test_kPendCtxSwtch_switches_immediately_for_non_running_task_and_preserves_lock_ownership
SCH_RQ_17 A task that blocks itself while holding kSchLock shall dispatch another ready task, preserve its owned scheduler-lock depth while blocked, and restore that depth when it resumes. test_self_block_inside_kSchLock_dispatches_peer_and_restores_lock_on_resume
SCH_RQ_18 When scheduler unlock readies multiple higher-priority tasks, dispatch shall select the highest-priority task before lower-priority ready tasks. qemu_sched_preempt_unlock.c
SCH_RQ_19 kTaskSpawn shall reject an uninitialised dynamic stack partition. test_kTaskSpawn_rejects_uninitialised_stack_partition
SCH_RQ_20 After the RUNNING task's effective priority is demoted in place, dispatch shall be re-evaluated and a higher-priority READY task shall preempt when pre-emption is enabled. test_kReschedRunning_dispatches_ready_task_after_running_priority_demotion

Message Queue

Requirements

ID Requirement Covered by
MSGQ_RQ_01 kMesgQueueInit shall validate supported message sizes and reject invalid queue configurations. test_kMesgQueueInit_validates_supported_message_sizes
MSGQ_RQ_02 Message queue send/receive operations shall transfer message payloads by copy. test_kMesgQueueSendRecv_is_by_copy_and_preserves_fifo_order
MSGQ_RQ_03 Message queues shall preserve FIFO order across queued messages. test_kMesgQueueSendRecv_is_by_copy_and_preserves_fifo_order
MSGQ_RQ_04 Receive with RK_NO_WAIT on an empty queue shall return empty without blocking. test_kMesgQueue_no_wait_returns_empty_and_full_without_blocking
MSGQ_RQ_05 Send with RK_NO_WAIT on a full queue shall return full without blocking. test_kMesgQueue_no_wait_returns_empty_and_full_without_blocking
MSGQ_RQ_06 Owner-only receive shall be enforced when a message queue has an owner. test_kMesgQueue_owner_only_receiver_is_enforced
MSGQ_RQ_07 The configured notify callback shall run on successful send. test_kMesgQueue_notify_callback_runs_on_successful_send
MSGQ_RQ_08 kMesgQueueReset shall clear queued messages and wake a waiting task. test_kMesgQueueReset_clears_queue_and_wakes_waiter
MSGQ_RQ_09 kMesgQueueReset from ISR context shall defer processing when waiters exist. test_kMesgQueueReset_in_isr_defers_when_waiters_exist
MSGQ_RQ_10 Single-slot message queue initialisation shall configure an empty, mailbox-like queue. test_kMesgQueueSingleSlotInit_configures_queue_and_empty_state
MSGQ_RQ_11 Single-slot send/receive shall preserve copy semantics and empty the slot after receive. test_kMesgQueueSingleSlotSendRecv_roundtrip_is_by_copy
MSGQ_RQ_12 kMesgQueuePeek shall read a single-slot message without consuming it. test_kMesgQueueSingleSlotPeek_is_non_destructive
MSGQ_RQ_13 Single-slot overwrite post shall replace the currently queued message. test_kMesgQueueSingleSlotPostOvw_overwrites_existing_message
MSGQ_RQ_14 Single-slot owner assignment shall be single-shot and shall gate receive-side access. test_kMesgQueueSingleSlotOwner_enforces_single_assignment_and_owner_only_receive
MSGQ_RQ_15 Single-slot reset shall empty the queue while preserving owner routing. test_kMesgQueueSingleSlotReset_empties_queue_and_keeps_owner
MSGQ_RQ_16 When a sender blocks on a full owned queue, the owner effective priority shall be raised to the head waiting-sender priority. test_kMesgQueueRecv_boosts_owner_to_head_waiting_sender_priority
MSGQ_RQ_17 Owned-queue receive and sender-release paths shall recompute owner priority and restore nominal priority when no sender boost remains. test_kMesgQueueRecv_owner_priority_tracks_remaining_waiters
MSGQ_RQ_18 Reset shall wake waiting senders and restore owner effective priority to nominal. test_kMesgQueueReset_restores_owner_priority_after_waiting_senders_clear
MSGQ_RQ_19 Port and owned-message-queue operations shall reject entry when the running task owns any mutex, preserving a single coordination authority for the dependency path. QEMU semantic coverage for single-authority mutex/Port rejection

Channel

Requirements

ID Requirement Covered by
CHAN_RQ_01 kChannelInit shall validate channel depth and require a request-descriptor partition whose block size can hold RK_REQ_BUF; application payloads are referenced by reqPtr/respPtr and are not copied into the partition. test_kChannelInit_validates_depth_and_request_block_size
CHAN_RQ_02 kChannelCall shall reject RK_NO_WAIT calls and invalid request-route state. test_kChannelCall_rejects_nowait_and_invalid_route_size
CHAN_RQ_03 kChannelAccept shall enforce server ownership and report empty when no request is available. test_kChannelAccept_enforces_owner_and_reports_empty
CHAN_RQ_04 kChannelAccept followed by kChannelDone shall complete a request/reply exchange and restore server priority. test_kChannelAccept_and_done_complete_request_and_restore_priority
CHAN_RQ_05 kChannelDone shall reject invalid request contexts. test_kChannelDone_rejects_invalid_request_context
CHAN_RQ_06 Channel call, accept, and done operations shall reject entry when the running task owns any mutex, preserving a single coordination authority for the dependency path. QEMU semantic coverage for single-authority mutex/Channel rejection
CHAN_RQ_07 kChannelAccept shall accept queued request routes in FIFO route-queue order; caller priority controls scheduling and server priority adoption, not queued-route acceptance order. Coverage pending: add test_kChannelAccept_accepts_routes_in_fifo_order
CHAN_RQ_08 Channel priority adoption and completion shall re-evaluate dispatch when they demote a RUNNING server's effective priority, so a higher-priority READY caller or unrelated task can preempt immediately. test_kReschedRunning_dispatches_ready_task_after_running_priority_demotion
CHAN_RQ_09 kChannelDone shall return the accepted request descriptor to its memory partition before the waiting caller is made READY. Coverage pending: add test_kChannelDone_frees_descriptor_before_readying_caller

Task Event

Requirements

ID Requirement Covered by
TEVT_RQ_01 kEventGet shall return immediately on a matching event condition and clear required flags. test_kEventGet_immediate_match_clears_required_flags
TEVT_RQ_02 kEventGet with RK_NO_WAIT shall return flags-not-met when the requested condition is absent. test_kEventGet_nowait_when_not_met_returns_flags_not_met
TEVT_RQ_03 kEventGet shall validate option flags, required masks, and timeout values. test_kEventGet_validates_options_required_and_timeout
TEVT_RQ_04 kEventGet with a bounded wait shall time out when no matching event arrives. test_kEventGet_bounded_wait_times_out
TEVT_RQ_05 kEventSet shall OR event masks into the target task and validate inputs. test_kEventSet_ors_mask_and_validates_inputs
TEVT_RQ_06 kEventSet shall wake a pending task when the set mask satisfies its wait condition. test_kEventSet_wakes_pending_task_when_condition_matches
TEVT_RQ_07 kEventClear shall clear selected flags and enforce ISR usage rules. test_kEventClear_clears_flags_and_checks_isr_rules
TEVT_RQ_08 kEventQuery shall read task flags and reject invalid inputs or invalid ISR usage. test_kEventQuery_reads_flags_and_checks_inputs

Sleep Queue

Requirements

ID Requirement Covered by
SLPQ_RQ_01 kSleepQueueInit shall initialise sleep queue fields for a valid queue object. test_kSleepQueueInit_sets_expected_fields
SLPQ_RQ_02 kSleepQueueWait with RK_NO_WAIT shall return without enqueueing the current task. test_kSleepQueueWait_nowait_is_noop_and_does_not_enqueue
SLPQ_RQ_03 kSleepQueueWait shall validate timeout values and ISR usage rules. test_kSleepQueueWait_validates_timeout_and_isr_rules
SLPQ_RQ_04 kSleepQueueSignal shall wake the highest-priority waiter. test_kSleepQueueSignal_wakes_highest_priority_waiter
SLPQ_RQ_05 kSleepQueueWake shall wake up to the requested number of waiters and report remaining waiters. test_kSleepQueueWake_wakes_up_to_n_and_reports_remaining
SLPQ_RQ_06 kSleepQueueWake with a zero count shall flush all waiters. test_kSleepQueueWake_zero_flushes_all_waiters
SLPQ_RQ_07 kSleepQueueWake from ISR context shall defer wake processing and require a null unreleased-pointer output. test_kSleepQueueWake_from_isr_defers_and_requires_null_unreleased_ptr
SLPQ_RQ_08 kSleepQueueBlockReadyTask and kSleepQueueReady shall move READY tasks between blocked-on-queue and ready states. test_kSleepQueueBlockReadyTask_and_ready_move_task_between_states
SLPQ_RQ_09 kSleepQueueQuery shall report the number of waiting tasks. test_kSleepQueueQuery_reports_waiting_count

Sleep and Timer

Sleep Requirements

ID Requirement Covered by
SLPT_RQ_01 kSleepDelay with a zero tick delay shall return timeout. test_kSleepDelay_zero_returns_timeout
SLPT_RQ_02 kSleepDelay shall reject calls from ISR context and invalid task state. test_kSleepDelay_rejects_isr_and_invalid_task_state
SLPT_RQ_03 kSleepDelay shall reject delays above the maximum supported period. test_kSleepDelay_rejects_ticks_above_max_period
SLPT_RQ_04 kSleepDelay with a valid bounded wait shall block and return success when released by time. test_kSleepDelay_bounded_wait_returns_success
SLPT_RQ_05 kSleepUntil shall return immediately when the target period has already elapsed. test_kSleepUntil_elapsed_period_returns_immediately
SLPT_RQ_06 kSleepUntil shall wait until the next period and advance the anchor tick. test_kSleepUntil_waits_and_advances_anchor
SLPT_RQ_07 kSleepUntil shall validate input pointers, period values, and ISR usage rules. test_kSleepUntil_validates_inputs_and_isr_rules
SLPT_RQ_08 kSleepRelease shall validate period values and ISR usage rules. test_kSleepRelease_validates_period_and_isr_rules
SLPT_RQ_09 kSleepRelease shall increment the overrun counter when a periodic task is late. test_kSleepRelease_increments_overrun_counter_when_late

Timer Requirements

ID Requirement Covered by
ATMR_RQ_01 kTimerInit shall validate timer inputs and reject double initialisation. test_kTimerInit_validates_inputs_and_double_init
ATMR_RQ_02 A one-shot timer shall run its callback exactly once. test_kTimer_oneshot_callback_runs_once
ATMR_RQ_03 A reload timer shall run its callback repeatedly at the configured period. test_kTimer_reload_callback_runs_repeatedly
ATMR_RQ_04 A phased timer shall delay its first callback by the configured phase. test_kTimer_phase_delays_first_callback
ATMR_RQ_05 kTimerCancel shall remove an active timer, including a single armed head timer, and prevent cancelled callbacks. test_kTimerCancel_active_timer_prevents_cancelled_callback, test_kTimerCancel_single_head_timer_succeeds
ATMR_RQ_06 kTimerCancel shall reject a null timer object. test_kTimerCancel_rejects_null_object

Rendezvous (Unbuffered message-passing)

Requirements

ID Requirement Covered by
RDVZ_RQ_01 kRendezvousInit shall bind a single owner, configure one fixed message size, and initialise empty rendezvous state. test_kRendezvousInit_binds_single_owner_and_size
RDVZ_RQ_02 kRendezvousInit shall validate null/uninitialised inputs, zero message size, and reject double ownership/initialisation. test_kRendezvousInit_validates_inputs_size_and_ownership
RDVZ_RQ_03 kRendezvousRecv shall be owner-only, and an empty no-wait receive shall return buffer-empty. test_kRendezvousRecv_is_owner_only_and_empty_nowait
RDVZ_RQ_04 kRendezvousSend with no waiting receiver and RK_NO_WAIT shall not buffer the message. test_kRendezvousSend_nowait_without_receiver_does_not_buffer
RDVZ_RQ_05 kRendezvousSend shall copy the endpoint fixed-size payload directly into a receiver that is already waiting. test_kRendezvousSend_directly_copies_to_waiting_receiver
RDVZ_RQ_06 kRendezvousRecv shall copy the occupied slot payload and release the blocked sender. test_kRendezvousRecv_copies_slot_and_releases_sender
RDVZ_RQ_07 kRendezvousRecv shall promote the next waiting sender after consuming the current slot. test_kRendezvousRecv_promotes_next_waiting_sender
RDVZ_RQ_08 Sender-side timeout shall invalidate the timed-out message for the receiver. test_kRendezvousTimeoutSend_invalidates_timed_out_message
RDVZ_RQ_09 Rendezvous APIs shall reject invalid arguments and invalid timeout values. test_kRendezvous_api_rejects_invalid_args_and_timeout
RDVZ_RQ_10 Rendezvous send and receive operations shall reject entry when the running task owns any mutex, preserving a single coordination authority for the dependency path. QEMU semantic coverage for single-authority mutex/Rendezvous rejection

Clone this wiki locally