Documentation/bpf/kfuncs.rst

   1 =============================
   2 BPF Kernel Functions (kfuncs)
   3 =============================
   4
   5 1. Introduction
   6 ===============
   7
   8 BPF Kernel Functions or more commonly known as kfuncs are functions in the Linux
   9 kernel which are exposed for use by BPF programs. Unlike normal BPF helpers,
  10 kfuncs do not have a stable interface and can change from one kernel release to
  11 another. Hence, BPF programs need to be updated in response to changes in the
  12 kernel.
  13
  14 2. Defining a kfunc
  15 ===================
  16
  17 There are two ways to expose a kernel function to BPF programs, either make an
  18 existing function in the kernel visible, or add a new wrapper for BPF. In both
  19 cases, care must be taken that BPF program can only call such function in a
  20 valid context. To enforce this, visibility of a kfunc can be per program type.
  21
  22 If you are not creating a BPF wrapper for existing kernel function, skip ahead
  23 to :ref:`BPF_kfunc_nodef`.
  24
  25 2.1 Creating a wrapper kfunc
  26 ----------------------------
  27
  28 When defining a wrapper kfunc, the wrapper function should have extern linkage.
  29 This prevents the compiler from optimizing away dead code, as this wrapper kfunc
  30 is not invoked anywhere in the kernel itself. It is not necessary to provide a
  31 prototype in a header for the wrapper kfunc.
  32
  33 An example is given below::
  34
  35         /* Disables missing prototype warnings */
  36         __diag_push();
  37         __diag_ignore_all("-Wmissing-prototypes",
  38                           "Global kfuncs as their definitions will be in BTF");
  39
  40         struct task_struct *bpf_find_get_task_by_vpid(pid_t nr)
  41         {
  42                 return find_get_task_by_vpid(nr);
  43         }
  44
  45         __diag_pop();
  46
  47 A wrapper kfunc is often needed when we need to annotate parameters of the
  48 kfunc. Otherwise one may directly make the kfunc visible to the BPF program by
  49 registering it with the BPF subsystem. See :ref:`BPF_kfunc_nodef`.
  50
  51 2.2 Annotating kfunc parameters
  52 -------------------------------
  53
  54 Similar to BPF helpers, there is sometime need for additional context required
  55 by the verifier to make the usage of kernel functions safer and more useful.
  56 Hence, we can annotate a parameter by suffixing the name of the argument of the
  57 kfunc with a __tag, where tag may be one of the supported annotations.
  58
  59 2.2.1 __sz Annotation
  60 ---------------------
  61
  62 This annotation is used to indicate a memory and size pair in the argument list.
  63 An example is given below::
  64
  65         void bpf_memzero(void *mem, int mem__sz)
  66         {
  67         ...
  68         }
  69
  70 Here, the verifier will treat first argument as a PTR_TO_MEM, and second
  71 argument as its size. By default, without __sz annotation, the size of the type
  72 of the pointer is used. Without __sz annotation, a kfunc cannot accept a void
  73 pointer.
  74
  75 .. _BPF_kfunc_nodef:
  76
  77 2.3 Using an existing kernel function
  78 -------------------------------------
  79
  80 When an existing function in the kernel is fit for consumption by BPF programs,
  81 it can be directly registered with the BPF subsystem. However, care must still
  82 be taken to review the context in which it will be invoked by the BPF program
  83 and whether it is safe to do so.
  84
  85 2.4 Annotating kfuncs
  86 ---------------------
  87
  88 In addition to kfuncs' arguments, verifier may need more information about the
  89 type of kfunc(s) being registered with the BPF subsystem. To do so, we define
  90 flags on a set of kfuncs as follows::
  91
  92         BTF_SET8_START(bpf_task_set)
  93         BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL)
  94         BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE)
  95         BTF_SET8_END(bpf_task_set)
  96
  97 This set encodes the BTF ID of each kfunc listed above, and encodes the flags
  98 along with it. Ofcourse, it is also allowed to specify no flags.
  99
 100 2.4.1 KF_ACQUIRE flag
 101 ---------------------
 102
 103 The KF_ACQUIRE flag is used to indicate that the kfunc returns a pointer to a
 104 refcounted object. The verifier will then ensure that the pointer to the object
 105 is eventually released using a release kfunc, or transferred to a map using a
 106 referenced kptr (by invoking bpf_kptr_xchg). If not, the verifier fails the
 107 loading of the BPF program until no lingering references remain in all possible
 108 explored states of the program.
 109
 110 2.4.2 KF_RET_NULL flag
 111 ----------------------
 112
 113 The KF_RET_NULL flag is used to indicate that the pointer returned by the kfunc
 114 may be NULL. Hence, it forces the user to do a NULL check on the pointer
 115 returned from the kfunc before making use of it (dereferencing or passing to
 116 another helper). This flag is often used in pairing with KF_ACQUIRE flag, but
 117 both are orthogonal to each other.
 118
 119 2.4.3 KF_RELEASE flag
 120 ---------------------
 121
 122 The KF_RELEASE flag is used to indicate that the kfunc releases the pointer
 123 passed in to it. There can be only one referenced pointer that can be passed in.
 124 All copies of the pointer being released are invalidated as a result of invoking
 125 kfunc with this flag.
 126
 127 2.4.4 KF_KPTR_GET flag
 128 ----------------------
 129
 130 The KF_KPTR_GET flag is used to indicate that the kfunc takes the first argument
 131 as a pointer to kptr, safely increments the refcount of the object it points to,
 132 and returns a reference to the user. The rest of the arguments may be normal
 133 arguments of a kfunc. The KF_KPTR_GET flag should be used in conjunction with
 134 KF_ACQUIRE and KF_RET_NULL flags.
 135
 136 2.4.5 KF_TRUSTED_ARGS flag
 137 --------------------------
 138
 139 The KF_TRUSTED_ARGS flag is used for kfuncs taking pointer arguments. It
 140 indicates that the all pointer arguments will always be refcounted, and have
 141 their offset set to 0. It can be used to enforce that a pointer to a refcounted
 142 object acquired from a kfunc or BPF helper is passed as an argument to this
 143 kfunc without any modifications (e.g. pointer arithmetic) such that it is
 144 trusted and points to the original object. This flag is often used for kfuncs
 145 that operate (change some property, perform some operation) on an object that
 146 was obtained using an acquire kfunc. Such kfuncs need an unchanged pointer to
 147 ensure the integrity of the operation being performed on the expected object.
 148
 149 2.5 Registering the kfuncs
 150 --------------------------
 151
 152 Once the kfunc is prepared for use, the final step to making it visible is
 153 registering it with the BPF subsystem. Registration is done per BPF program
 154 type. An example is shown below::
 155
 156         BTF_SET8_START(bpf_task_set)
 157         BTF_ID_FLAGS(func, bpf_get_task_pid, KF_ACQUIRE | KF_RET_NULL)
 158         BTF_ID_FLAGS(func, bpf_put_pid, KF_RELEASE)
 159         BTF_SET8_END(bpf_task_set)
 160
 161         static const struct btf_kfunc_id_set bpf_task_kfunc_set = {
 162                 .owner = THIS_MODULE,
 163                 .set   = &bpf_task_set,
 164         };
 165
 166         static int init_subsystem(void)
 167         {
 168                 return register_btf_kfunc_id_set(BPF_PROG_TYPE_TRACING, &bpf_task_kfunc_set);
 169         }
 170         late_initcall(init_subsystem);