Scheduler selection and interface dispatch

The common interface

sys/sys/sched.h describes the interface used by kernel callers. Its SCHED_ITF_* X macros enumerate return types, names, and argument pairs for operations such as sched_add(), sched_switch(), and sched_wakeup(). These lists generate declarations, instance slots, and dispatch machinery from a common description.

The interface has several categories:

  • SCHED_ITF_DISPATCH describes calls dispatched directly to the selected instance through indirect functions.

  • SCHED_ITF_WRAP describes calls that have a common wrapper around an instance operation; initialization is an example.

  • SCHED_ITF_INTERNAL describes implementation hooks used by the framework.

  • Common functions are declared separately in the header and can build on the selected implementation.

Read the comments on the interface lists before inferring a caller contract from one implementation’s function body. Flags, lock transitions, and thread-state requirements are part of that contract.

Registration and boot selection

An implementation defines SCHED_IMPLEMENTATION and uses DECLARE_SCHEDULER to register an instance and its selection name in a linker set. The descriptor contains the implementation’s function pointers. The implementation namespace headers let the source use ordinary interface names while the linked implementation symbols have distinct prefixes.

sched_instance_select() in sched_shim.c reads the kern.sched.name boot setting and searches the registered selections. The shim’s initial requested name is ULE. If no matching selection is found, the code can fall back to the first available registration. The later initialization wrapper rejects a missing active instance.

Thus the implementations available in a particular kernel and the name requested during boot both matter. The kern.sched.name sysctl is not a runtime scheduler hot-swap interface. kern.sched.available reports the registered selection names.

Dispatch and initialization

The shim’s DEFINE_SHIM expansion uses DEFINE_IFUNC for dispatched calls. The resolver obtains the corresponding function pointer from active_sched. Other initialization hooks explicitly call through that descriptor after preparing shared state such as CPU topology.

Keep three names separate when navigating the code:

  • The interface spelling, such as sched_switch.

  • The implementation’s linked symbol, with an implementation-specific prefix.

  • A documentation scope used to distinguish implementation source listings.

The ULE implementation and 4BSD implementation references use documentation scopes scheduler.ule and scheduler.bsd4. Those scopes keep similarly named implementation functions distinct inside Sphinx; they do not add another kernel dispatch layer.

Reading a scheduling call

Start at the caller’s thread state and lock state. Find the operation in sched.h, identify its category, and then follow the selected instance’s implementation. On a system using ULE, interpreting a 4BSD queue or priority calculation does not explain the same call’s ULE behavior.

The instance framework also means a source-level function name alone may be insufficient for a debugger or symbol search. Check the namespace headers and the linked implementation prefix when locating a concrete body.