twb_schedule.h File Reference

Thread With Budget (TWB) scheduler interface and cycle accounting. More...

Include dependency graph for twb_schedule.h:

Go to the source code of this file.

Macros
#define	ZEPHYR_TWB_STACK_SIZE   8192
	Default static stack size in bytes for each TWB worker thread.
#define	ZEPHYR_TWB_BUDGET_MAX   (CONFIG_SYS_CLOCK_TICKS_PER_SEC / 1000)
	Maximum budget limit in system clock ticks per period.
#define	SYS_TICKS_TO_HW_CYCLES(x)   (x * CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC / CONFIG_SYS_CLOCK_TICKS_PER_SEC)
	Convert Zephyr system clock ticks to DSP hardware clock cycles.
#define	HW_CYCLES_TO_SYS_TICKS(x)   (x * CONFIG_SYS_CLOCK_TICKS_PER_SEC / CONFIG_SYS_CLOCK_HW_CYCLES_PER_SEC)
	Convert DSP hardware clock cycles to Zephyr system clock ticks.

Functions
int	scheduler_twb_init (void)
	Initialize the Thread With Budget (TWB) scheduler on the calling core.
int	scheduler_twb_task_init (struct task **task, const struct sof_uuid_entry *uid, const struct task_ops *ops, void *data, int32_t core, const char *name, size_t stack_size, int32_t thread_priority, uint32_t cycles_granted)
	Initialize a TWB task with a dedicated Zephyr worker thread and cycle budget.

Detailed Description

Thread With Budget (TWB) scheduler interface and cycle accounting.

The Thread With Budget (TWB) scheduler creates a separate preemptible Zephyr thread for each SOF task that has a pre-allocated MCPS budget renewed with every system tick.

Key Architectural Properties

• Dynamic Priority Switching: The TWB scheduler assigns either MEDIUM_PRIORITY or LOW_PRIORITY to the task thread based on the budget remaining in the current system tick.
• Opportunistic Execution: If there is no higher-priority ready task, the thread can continue executing at low priority even after its budget is exhausted.
• Cycle & Tick Accounting:
  • cycles_granted: Budget in Zephyr system clock ticks per period (passed to k_thread_time_slice_set()).
  • cycles_consumed: Actual execution time consumed during the current period, measured in DSP hardware clock cycles.
• Budget Exhaustion & Replenishment:
  • When consumed cycles exceed granted cycles, Zephyr time slicing triggers scheduler_twb_task_cb(), which lowers thread priority to CONFIG_TWB_THREAD_LOW_PRIORITY.
  • On the next Low-Latency tick (scheduler_twb_ll_tick()), consumed cycles are reset to 0, and the original thread priority is restored. Unused budget is not carried over.