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. :c:func:`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 :doc:`api/ule` and :doc:`api/bsd4` 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.