BPF cpumask kfuncs¶
1. Introduction¶
struct cpumask
is a bitmap data structure in the kernel whose indices
reflect the CPUs on the system. Commonly, cpumasks are used to track which CPUs
a task is affinitized to, but they can also be used to e.g. track which cores
are associated with a scheduling domain, which cores on a machine are idle,
etc.
BPF provides programs with a set of BPF Kernel Functions (kfuncs) that can be used to allocate, mutate, query, and free cpumasks.
2. BPF cpumask objects¶
There are two different types of cpumasks that can be used by BPF programs.
2.1 struct bpf_cpumask *
¶
struct bpf_cpumask *
is a cpumask that is allocated by BPF, on behalf of a
BPF program, and whose lifecycle is entirely controlled by BPF. These cpumasks
are RCU-protected, can be mutated, can be used as kptrs, and can be safely cast
to a struct cpumask *
.
2.1.1 struct bpf_cpumask *
lifecycle¶
A struct bpf_cpumask *
is allocated, acquired, and released, using the
following functions:
-
__bpf_kfunc struct bpf_cpumask *bpf_cpumask_create(void)¶
Create a mutable BPF cpumask.
Parameters
void
no arguments
Description
Allocates a cpumask that can be queried, mutated, acquired, and released by
a BPF program. The cpumask returned by this function must either be embedded
in a map as a kptr, or freed with bpf_cpumask_release()
.
bpf_cpumask_create()
allocates memory using the BPF memory allocator, and
will not block. It may return NULL if no memory is available.
-
__bpf_kfunc struct bpf_cpumask *bpf_cpumask_acquire(struct bpf_cpumask *cpumask)¶
Acquire a reference to a BPF cpumask.
Parameters
struct bpf_cpumask *cpumask
The BPF cpumask being acquired. The cpumask must be a trusted pointer.
Description
Acquires a reference to a BPF cpumask. The cpumask returned by this function
must either be embedded in a map as a kptr, or freed with
bpf_cpumask_release()
.
-
__bpf_kfunc void bpf_cpumask_release(struct bpf_cpumask *cpumask)¶
Release a previously acquired BPF cpumask.
Parameters
struct bpf_cpumask *cpumask
The cpumask being released.
Description
Releases a previously acquired reference to a BPF cpumask. When the final reference of the BPF cpumask has been released, it is subsequently freed in an RCU callback in the BPF memory allocator.
For example:
struct cpumask_map_value {
struct bpf_cpumask __kptr * cpumask;
};
struct array_map {
__uint(type, BPF_MAP_TYPE_ARRAY);
__type(key, int);
__type(value, struct cpumask_map_value);
__uint(max_entries, 65536);
} cpumask_map SEC(".maps");
static int cpumask_map_insert(struct bpf_cpumask *mask, u32 pid)
{
struct cpumask_map_value local, *v;
long status;
struct bpf_cpumask *old;
u32 key = pid;
local.cpumask = NULL;
status = bpf_map_update_elem(&cpumask_map, &key, &local, 0);
if (status) {
bpf_cpumask_release(mask);
return status;
}
v = bpf_map_lookup_elem(&cpumask_map, &key);
if (!v) {
bpf_cpumask_release(mask);
return -ENOENT;
}
old = bpf_kptr_xchg(&v->cpumask, mask);
if (old)
bpf_cpumask_release(old);
return 0;
}
/**
* A sample tracepoint showing how a task's cpumask can be queried and
* recorded as a kptr.
*/
SEC("tp_btf/task_newtask")
int BPF_PROG(record_task_cpumask, struct task_struct *task, u64 clone_flags)
{
struct bpf_cpumask *cpumask;
int ret;
cpumask = bpf_cpumask_create();
if (!cpumask)
return -ENOMEM;
if (!bpf_cpumask_full(task->cpus_ptr))
bpf_printk("task %s has CPU affinity", task->comm);
bpf_cpumask_copy(cpumask, task->cpus_ptr);
return cpumask_map_insert(cpumask, task->pid);
}
2.1.1 struct bpf_cpumask *
as kptrs¶
As mentioned and illustrated above, these struct bpf_cpumask *
objects can
also be stored in a map and used as kptrs. If a struct bpf_cpumask *
is in
a map, the reference can be removed from the map with bpf_kptr_xchg(), or
opportunistically acquired using RCU:
/* struct containing the struct bpf_cpumask kptr which is stored in the map. */
struct cpumasks_kfunc_map_value {
struct bpf_cpumask __kptr * bpf_cpumask;
};
/* The map containing struct cpumasks_kfunc_map_value entries. */
struct {
__uint(type, BPF_MAP_TYPE_ARRAY);
__type(key, int);
__type(value, struct cpumasks_kfunc_map_value);
__uint(max_entries, 1);
} cpumasks_kfunc_map SEC(".maps");
/* ... */
/**
* A simple example tracepoint program showing how a
* struct bpf_cpumask * kptr that is stored in a map can
* be passed to kfuncs using RCU protection.
*/
SEC("tp_btf/cgroup_mkdir")
int BPF_PROG(cgrp_ancestor_example, struct cgroup *cgrp, const char *path)
{
struct bpf_cpumask *kptr;
struct cpumasks_kfunc_map_value *v;
u32 key = 0;
/* Assume a bpf_cpumask * kptr was previously stored in the map. */
v = bpf_map_lookup_elem(&cpumasks_kfunc_map, &key);
if (!v)
return -ENOENT;
bpf_rcu_read_lock();
/* Acquire a reference to the bpf_cpumask * kptr that's already stored in the map. */
kptr = v->cpumask;
if (!kptr) {
/* If no bpf_cpumask was present in the map, it's because
* we're racing with another CPU that removed it with
* bpf_kptr_xchg() between the bpf_map_lookup_elem()
* above, and our load of the pointer from the map.
*/
bpf_rcu_read_unlock();
return -EBUSY;
}
bpf_cpumask_setall(kptr);
bpf_rcu_read_unlock();
return 0;
}
2.2 struct cpumask
¶
struct cpumask
is the object that actually contains the cpumask bitmap
being queried, mutated, etc. A struct bpf_cpumask
wraps a struct
cpumask
, which is why it's safe to cast it as such (note however that it is
not safe to cast a struct cpumask *
to a struct bpf_cpumask *
, and
the verifier will reject any program that tries to do so).
As we'll see below, any kfunc that mutates its cpumask argument will take a
struct bpf_cpumask *
as that argument. Any argument that simply queries the
cpumask will instead take a struct cpumask *
.
3. cpumask kfuncs¶
Above, we described the kfuncs that can be used to allocate, acquire, release,
etc a struct bpf_cpumask *
. This section of the document will describe the
kfuncs for mutating and querying cpumasks.
3.1 Mutating cpumasks¶
Some cpumask kfuncs are "read-only" in that they don't mutate any of their
arguments, whereas others mutate at least one argument (which means that the
argument must be a struct bpf_cpumask *
, as described above).
This section will describe all of the cpumask kfuncs which mutate at least one argument. 3.2 Querying cpumasks below describes the read-only kfuncs.
3.1.1 Setting and clearing CPUs¶
bpf_cpumask_set_cpu()
and bpf_cpumask_clear_cpu()
can be used to set and clear
a CPU in a struct bpf_cpumask
respectively:
-
__bpf_kfunc void bpf_cpumask_set_cpu(u32 cpu, struct bpf_cpumask *cpumask)¶
Set a bit for a CPU in a BPF cpumask.
Parameters
u32 cpu
The CPU to be set in the cpumask.
struct bpf_cpumask *cpumask
The BPF cpumask in which a bit is being set.
-
__bpf_kfunc void bpf_cpumask_clear_cpu(u32 cpu, struct bpf_cpumask *cpumask)¶
Clear a bit for a CPU in a BPF cpumask.
Parameters
u32 cpu
The CPU to be cleared from the cpumask.
struct bpf_cpumask *cpumask
The BPF cpumask in which a bit is being cleared.
These kfuncs are pretty straightforward, and can be used, for example, as follows:
/**
* A sample tracepoint showing how a cpumask can be queried.
*/
SEC("tp_btf/task_newtask")
int BPF_PROG(test_set_clear_cpu, struct task_struct *task, u64 clone_flags)
{
struct bpf_cpumask *cpumask;
cpumask = bpf_cpumask_create();
if (!cpumask)
return -ENOMEM;
bpf_cpumask_set_cpu(0, cpumask);
if (!bpf_cpumask_test_cpu(0, cast(cpumask)))
/* Should never happen. */
goto release_exit;
bpf_cpumask_clear_cpu(0, cpumask);
if (bpf_cpumask_test_cpu(0, cast(cpumask)))
/* Should never happen. */
goto release_exit;
/* struct cpumask * pointers such as task->cpus_ptr can also be queried. */
if (bpf_cpumask_test_cpu(0, task->cpus_ptr))
bpf_printk("task %s can use CPU %d", task->comm, 0);
release_exit:
bpf_cpumask_release(cpumask);
return 0;
}
bpf_cpumask_test_and_set_cpu()
and bpf_cpumask_test_and_clear_cpu()
are
complementary kfuncs that allow callers to atomically test and set (or clear)
CPUs:
-
__bpf_kfunc bool bpf_cpumask_test_and_set_cpu(u32 cpu, struct bpf_cpumask *cpumask)¶
Atomically test and set a CPU in a BPF cpumask.
Parameters
u32 cpu
The CPU being set and queried for.
struct bpf_cpumask *cpumask
The BPF cpumask being set and queried for containing a CPU.
Return
true - cpu is set in the cpumask
false - cpu was not set in the cpumask, or cpu is invalid.
-
__bpf_kfunc bool bpf_cpumask_test_and_clear_cpu(u32 cpu, struct bpf_cpumask *cpumask)¶
Atomically test and clear a CPU in a BPF cpumask.
Parameters
u32 cpu
The CPU being cleared and queried for.
struct bpf_cpumask *cpumask
The BPF cpumask being cleared and queried for containing a CPU.
Return
true - cpu is set in the cpumask
false - cpu was not set in the cpumask, or cpu is invalid.
We can also set and clear entire struct bpf_cpumask *
objects in one
operation using bpf_cpumask_setall()
and bpf_cpumask_clear()
:
-
__bpf_kfunc void bpf_cpumask_setall(struct bpf_cpumask *cpumask)¶
Set all of the bits in a BPF cpumask.
Parameters
struct bpf_cpumask *cpumask
The BPF cpumask having all of its bits set.
-
__bpf_kfunc void bpf_cpumask_clear(struct bpf_cpumask *cpumask)¶
Clear all of the bits in a BPF cpumask.
Parameters
struct bpf_cpumask *cpumask
The BPF cpumask being cleared.
3.1.2 Operations between cpumasks¶
In addition to setting and clearing individual CPUs in a single cpumask,
callers can also perform bitwise operations between multiple cpumasks using
bpf_cpumask_and()
, bpf_cpumask_or()
, and bpf_cpumask_xor()
:
-
__bpf_kfunc bool bpf_cpumask_and(struct bpf_cpumask *dst, const struct cpumask *src1, const struct cpumask *src2)¶
AND two cpumasks and store the result.
Parameters
struct bpf_cpumask *dst
The BPF cpumask where the result is being stored.
const struct cpumask *src1
The first input.
const struct cpumask *src2
The second input.
Return
true - dst has at least one bit set following the operation
false - dst is empty following the operation
Description
struct bpf_cpumask pointers may be safely passed to src1 and src2.
-
__bpf_kfunc void bpf_cpumask_or(struct bpf_cpumask *dst, const struct cpumask *src1, const struct cpumask *src2)¶
OR two cpumasks and store the result.
Parameters
struct bpf_cpumask *dst
The BPF cpumask where the result is being stored.
const struct cpumask *src1
The first input.
const struct cpumask *src2
The second input.
Description
struct bpf_cpumask pointers may be safely passed to src1 and src2.
-
__bpf_kfunc void bpf_cpumask_xor(struct bpf_cpumask *dst, const struct cpumask *src1, const struct cpumask *src2)¶
XOR two cpumasks and store the result.
Parameters
struct bpf_cpumask *dst
The BPF cpumask where the result is being stored.
const struct cpumask *src1
The first input.
const struct cpumask *src2
The second input.
Description
struct bpf_cpumask pointers may be safely passed to src1 and src2.
The following is an example of how they may be used. Note that some of the kfuncs shown in this example will be covered in more detail below.
/**
* A sample tracepoint showing how a cpumask can be mutated using
bitwise operators (and queried).
*/
SEC("tp_btf/task_newtask")
int BPF_PROG(test_and_or_xor, struct task_struct *task, u64 clone_flags)
{
struct bpf_cpumask *mask1, *mask2, *dst1, *dst2;
mask1 = bpf_cpumask_create();
if (!mask1)
return -ENOMEM;
mask2 = bpf_cpumask_create();
if (!mask2) {
bpf_cpumask_release(mask1);
return -ENOMEM;
}
// ...Safely create the other two masks... */
bpf_cpumask_set_cpu(0, mask1);
bpf_cpumask_set_cpu(1, mask2);
bpf_cpumask_and(dst1, (const struct cpumask *)mask1, (const struct cpumask *)mask2);
if (!bpf_cpumask_empty((const struct cpumask *)dst1))
/* Should never happen. */
goto release_exit;
bpf_cpumask_or(dst1, (const struct cpumask *)mask1, (const struct cpumask *)mask2);
if (!bpf_cpumask_test_cpu(0, (const struct cpumask *)dst1))
/* Should never happen. */
goto release_exit;
if (!bpf_cpumask_test_cpu(1, (const struct cpumask *)dst1))
/* Should never happen. */
goto release_exit;
bpf_cpumask_xor(dst2, (const struct cpumask *)mask1, (const struct cpumask *)mask2);
if (!bpf_cpumask_equal((const struct cpumask *)dst1,
(const struct cpumask *)dst2))
/* Should never happen. */
goto release_exit;
release_exit:
bpf_cpumask_release(mask1);
bpf_cpumask_release(mask2);
bpf_cpumask_release(dst1);
bpf_cpumask_release(dst2);
return 0;
}
The contents of an entire cpumask may be copied to another using
bpf_cpumask_copy()
:
-
__bpf_kfunc void bpf_cpumask_copy(struct bpf_cpumask *dst, const struct cpumask *src)¶
Copy the contents of a cpumask into a BPF cpumask.
Parameters
struct bpf_cpumask *dst
The BPF cpumask being copied into.
const struct cpumask *src
The cpumask being copied.
Description
A struct bpf_cpumask pointer may be safely passed to src.
3.2 Querying cpumasks¶
In addition to the above kfuncs, there is also a set of read-only kfuncs that can be used to query the contents of cpumasks.
-
__bpf_kfunc u32 bpf_cpumask_first(const struct cpumask *cpumask)¶
Get the index of the first nonzero bit in the cpumask.
Parameters
const struct cpumask *cpumask
The cpumask being queried.
Description
Find the index of the first nonzero bit of the cpumask. A struct bpf_cpumask pointer may be safely passed to this function.
-
__bpf_kfunc u32 bpf_cpumask_first_zero(const struct cpumask *cpumask)¶
Get the index of the first unset bit in the cpumask.
Parameters
const struct cpumask *cpumask
The cpumask being queried.
Description
Find the index of the first unset bit of the cpumask. A struct bpf_cpumask pointer may be safely passed to this function.
-
__bpf_kfunc u32 bpf_cpumask_first_and(const struct cpumask *src1, const struct cpumask *src2)¶
Return the index of the first nonzero bit from the AND of two cpumasks.
Parameters
const struct cpumask *src1
The first cpumask.
const struct cpumask *src2
The second cpumask.
Description
Find the index of the first nonzero bit of the AND of two cpumasks. struct bpf_cpumask pointers may be safely passed to src1 and src2.
-
__bpf_kfunc bool bpf_cpumask_test_cpu(u32 cpu, const struct cpumask *cpumask)¶
Test whether a CPU is set in a cpumask.
Parameters
u32 cpu
The CPU being queried for.
const struct cpumask *cpumask
The cpumask being queried for containing a CPU.
Return
true - cpu is set in the cpumask
false - cpu was not set in the cpumask, or cpu is an invalid cpu.
-
__bpf_kfunc u32 bpf_cpumask_weight(const struct cpumask *cpumask)¶
Return the number of bits in cpumask.
Parameters
const struct cpumask *cpumask
The cpumask being queried.
Description
Count the number of set bits in the given cpumask.
-
__bpf_kfunc bool bpf_cpumask_equal(const struct cpumask *src1, const struct cpumask *src2)¶
Check two cpumasks for equality.
Parameters
const struct cpumask *src1
The first input.
const struct cpumask *src2
The second input.
Return
true - src1 and src2 have the same bits set.
false - src1 and src2 differ in at least one bit.
Description
struct bpf_cpumask pointers may be safely passed to src1 and src2.
-
__bpf_kfunc bool bpf_cpumask_intersects(const struct cpumask *src1, const struct cpumask *src2)¶
Check two cpumasks for overlap.
Parameters
const struct cpumask *src1
The first input.
const struct cpumask *src2
The second input.
Return
true - src1 and src2 have at least one of the same bits set.
false - src1 and src2 don't have any of the same bits set.
Description
struct bpf_cpumask pointers may be safely passed to src1 and src2.
-
__bpf_kfunc bool bpf_cpumask_subset(const struct cpumask *src1, const struct cpumask *src2)¶
Check if a cpumask is a subset of another.
Parameters
const struct cpumask *src1
The first cpumask being checked as a subset.
const struct cpumask *src2
The second cpumask being checked as a superset.
Return
true - All of the bits of src1 are set in src2.
false - At least one bit in src1 is not set in src2.
Description
struct bpf_cpumask pointers may be safely passed to src1 and src2.
Parameters
const struct cpumask *cpumask
The cpumask being checked.
Return
true - None of the bits in cpumask are set.
false - At least one bit in cpumask is set.
Description
A struct bpf_cpumask pointer may be safely passed to cpumask.
-
__bpf_kfunc bool bpf_cpumask_full(const struct cpumask *cpumask)¶
Check if a cpumask has all bits set.
Parameters
const struct cpumask *cpumask
The cpumask being checked.
Return
true - All of the bits in cpumask are set.
false - At least one bit in cpumask is cleared.
Description
A struct bpf_cpumask pointer may be safely passed to cpumask.
-
__bpf_kfunc u32 bpf_cpumask_any_distribute(const struct cpumask *cpumask)¶
Return a random set CPU from a cpumask.
Parameters
const struct cpumask *cpumask
The cpumask being queried.
Return
A random set bit within [0, num_cpus) if at least one bit is set.
>= num_cpus if no bit is set.
Description
A struct bpf_cpumask pointer may be safely passed to src.
-
__bpf_kfunc u32 bpf_cpumask_any_and_distribute(const struct cpumask *src1, const struct cpumask *src2)¶
Return a random set CPU from the AND of two cpumasks.
Parameters
const struct cpumask *src1
The first cpumask.
const struct cpumask *src2
The second cpumask.
Return
A random set bit within [0, num_cpus) from the AND of two cpumasks, if at least one bit is set.
>= num_cpus if no bit is set.
Description
struct bpf_cpumask pointers may be safely passed to src1 and src2.
Some example usages of these querying kfuncs were shown above. We will not replicate those examples here. Note, however, that all of the aforementioned kfuncs are tested in tools/testing/selftests/bpf/progs/cpumask_success.c, so please take a look there if you're looking for more examples of how they can be used.
4. Adding BPF cpumask kfuncs¶
The set of supported BPF cpumask kfuncs are not (yet) a 1-1 match with the cpumask operations in include/linux/cpumask.h. Any of those cpumask operations could easily be encapsulated in a new kfunc if and when required. If you'd like to support a new cpumask operation, please feel free to submit a patch. If you do add a new cpumask kfunc, please document it here, and add any relevant selftest testcases to the cpumask selftest suite.