KFunc scx_bpf_sub_kill_bstr

v7.3

Kill a direct child sub-scheduler.

Definition

Evict the direct child sub-scheduler attached to cGroup cgroup_id, disabling it with the given reason. The child and its sub-tree are torn down asynchronously through the usual disable path, with exit kind SCX_EXIT_PARENT_KILL. The formatted reason is passed to the child's struct scx_exit_info.

Unlike scx_bpf_exit_bstr, no exit code is taken. The child is a separate scheduler with its own exit code semantics, so an exit code chosen by the parent would have no defined meaning. The reason string carries the intent instead.

Intended to be called through the scx_bpf_sub_kill helper macro.

Parameters

cgroup_id: cGroup ID of the direct child sub-scheduler to kill.

fmt: reason message format string

data: format string parameters packaged using ___bpf_fill macro

data__sz: data len, must end in '__sz' for the verifier

Returns

• 0: Success.
• -ENODEV: The calling program is not associated with a scheduler, or cgroup_id does not name a sub-scheduler. The latter can race with the child detaching on its own, so it is not treated as a scheduler error.
• -EOPNOTSUPP: The calling scheduler is not a cid-form scheduler, or the kernel was built without sub-scheduler support (CONFIG_EXT_SUB_SCHED).
• -EINVAL: cgroup_id names a scheduler that is not a direct child.

The -EINVAL error, and the -EOPNOTSUPP error for schedulers that are not cid-form, also abort the calling scheduler with an error.

Signature

s32 scx_bpf_sub_kill_bstr(u64 cgroup_id, char *fmt, long long unsigned int *data, u32 data__sz)

Usage

A cid-form parent scheduler can delegate cids to and take them back from its child sub-schedulers with scx_bpf_sub_grant and scx_bpf_sub_revoke. This kfunc allows the parent to tear down a child altogether, for example when the parent has no cids left to give to it.

The scx_bpf_sub_kill macro from scx/common.bpf.h takes a printf-style format string with variadic arguments and packs them for this kfunc. When the kernel does not support this kfunc, the macro returns -EOPNOTSUPP.

Program types

The following program types can make use of this kfunc:

• BPF_PROG_TYPE_LSM
• BPF_PROG_TYPE_PERF_EVENT v6.12 -
• BPF_PROG_TYPE_STRUCT_OPS
• BPF_PROG_TYPE_SYSCALL
• BPF_PROG_TYPE_TRACEPOINT v6.12 -
• BPF_PROG_TYPE_TRACING

Example

This snippet, from the scx_qmap example scheduler, kills all child sub-schedulers when the scheduler holds no exclusive cids to distribute.

Example from tools/sched_ext/scx_qmap.bpf.c

Example

/* no excl cpu: run own tasks on the held shares, evict children */
if (!qa.part.nr_excl) {
    cmask_copy(&qa.self_cids.mask, &qa.held_shared.mask);
    refresh_usable();
    bpf_for(i, 0, MAX_SUB_SCHEDS)
        if (qa.sub_sched_ctxs[i].cgroup_id)
            scx_bpf_sub_kill(qa.sub_sched_ctxs[i].cgroup_id,
                     "parent holds no excl cpu to distribute");
    return;
}