tools/lib/bpf/libbpf.h

   1 /*
   2  * Common eBPF ELF object loading operations.
   3  *
   4  * Copyright (C) 2013-2015 Alexei Starovoitov <ast@kernel.org>
   5  * Copyright (C) 2015 Wang Nan <wangnan0@huawei.com>
   6  * Copyright (C) 2015 Huawei Inc.
   7  */
   8 #ifndef __BPF_LIBBPF_H
   9 #define __BPF_LIBBPF_H
  10
  11 #include <stdio.h>
  12 #include <stdbool.h>
  13 #include <linux/err.h>
  14
  15 enum libbpf_errno {
  16         __LIBBPF_ERRNO__START = 4000,
  17
  18         /* Something wrong in libelf */
  19         LIBBPF_ERRNO__LIBELF = __LIBBPF_ERRNO__START,
  20         LIBBPF_ERRNO__FORMAT,   /* BPF object format invalid */
  21         LIBBPF_ERRNO__KVERSION, /* Incorrect or no 'version' section */
  22         LIBBPF_ERRNO__ENDIAN,   /* Endian missmatch */
  23         LIBBPF_ERRNO__INTERNAL, /* Internal error in libbpf */
  24         LIBBPF_ERRNO__RELOC,    /* Relocation failed */
  25         LIBBPF_ERRNO__LOAD,     /* Load program failure for unknown reason */
  26         LIBBPF_ERRNO__VERIFY,   /* Kernel verifier blocks program loading */
  27         LIBBPF_ERRNO__PROG2BIG, /* Program too big */
  28         LIBBPF_ERRNO__KVER,     /* Incorrect kernel version */
  29         __LIBBPF_ERRNO__END,
  30 };
  31
  32 int libbpf_strerror(int err, char *buf, size_t size);
  33
  34 /*
  35  * In include/linux/compiler-gcc.h, __printf is defined. However
  36  * it should be better if libbpf.h doesn't depend on Linux header file.
  37  * So instead of __printf, here we use gcc attribute directly.
  38  */
  39 typedef int (*libbpf_print_fn_t)(const char *, ...)
  40         __attribute__((format(printf, 1, 2)));
  41
  42 void libbpf_set_print(libbpf_print_fn_t warn,
  43                       libbpf_print_fn_t info,
  44                       libbpf_print_fn_t debug);
  45
  46 /* Hide internal to user */
  47 struct bpf_object;
  48
  49 struct bpf_object *bpf_object__open(const char *path);
  50 struct bpf_object *bpf_object__open_buffer(void *obj_buf,
  51                                            size_t obj_buf_sz,
  52                                            const char *name);
  53 void bpf_object__close(struct bpf_object *object);
  54
  55 /* Load/unload object into/from kernel */
  56 int bpf_object__load(struct bpf_object *obj);
  57 int bpf_object__unload(struct bpf_object *obj);
  58 const char *bpf_object__get_name(struct bpf_object *obj);
  59 unsigned int bpf_object__get_kversion(struct bpf_object *obj);
  60
  61 struct bpf_object *bpf_object__next(struct bpf_object *prev);
  62 #define bpf_object__for_each_safe(pos, tmp)                     \
  63         for ((pos) = bpf_object__next(NULL),            \
  64                 (tmp) = bpf_object__next(pos);          \
  65              (pos) != NULL;                             \
  66              (pos) = (tmp), (tmp) = bpf_object__next(tmp))
  67
  68 /* Accessors of bpf_program. */
  69 struct bpf_program;
  70 struct bpf_program *bpf_program__next(struct bpf_program *prog,
  71                                       struct bpf_object *obj);
  72
  73 #define bpf_object__for_each_program(pos, obj)          \
  74         for ((pos) = bpf_program__next(NULL, (obj));    \
  75              (pos) != NULL;                             \
  76              (pos) = bpf_program__next((pos), (obj)))
  77
  78 typedef void (*bpf_program_clear_priv_t)(struct bpf_program *,
  79                                          void *);
  80
  81 int bpf_program__set_private(struct bpf_program *prog, void *priv,
  82                              bpf_program_clear_priv_t clear_priv);
  83
  84 int bpf_program__get_private(struct bpf_program *prog,
  85                              void **ppriv);
  86
  87 const char *bpf_program__title(struct bpf_program *prog, bool needs_copy);
  88
  89 int bpf_program__fd(struct bpf_program *prog);
  90
  91 struct bpf_insn;
  92
  93 /*
  94  * Libbpf allows callers to adjust BPF programs before being loaded
  95  * into kernel. One program in an object file can be transform into
  96  * multiple variants to be attached to different code.
  97  *
  98  * bpf_program_prep_t, bpf_program__set_prep and bpf_program__nth_fd
  99  * are APIs for this propose.
 100  *
 101  * - bpf_program_prep_t:
 102  *   It defines 'preprocessor', which is a caller defined function
 103  *   passed to libbpf through bpf_program__set_prep(), and will be
 104  *   called before program is loaded. The processor should adjust
 105  *   the program one time for each instances according to the number
 106  *   passed to it.
 107  *
 108  * - bpf_program__set_prep:
 109  *   Attachs a preprocessor to a BPF program. The number of instances
 110  *   whould be created is also passed through this function.
 111  *
 112  * - bpf_program__nth_fd:
 113  *   After the program is loaded, get resuling fds from bpf program for
 114  *   each instances.
 115  *
 116  * If bpf_program__set_prep() is not used, the program whould be loaded
 117  * without adjustment during bpf_object__load(). The program has only
 118  * one instance. In this case bpf_program__fd(prog) is equal to
 119  * bpf_program__nth_fd(prog, 0).
 120  */
 121
 122 struct bpf_prog_prep_result {
 123         /*
 124          * If not NULL, load new instruction array.
 125          * If set to NULL, don't load this instance.
 126          */
 127         struct bpf_insn *new_insn_ptr;
 128         int new_insn_cnt;
 129
 130         /* If not NULL, result fd is set to it */
 131         int *pfd;
 132 };
 133
 134 /*
 135  * Parameters of bpf_program_prep_t:
 136  *  - prog:     The bpf_program being loaded.
 137  *  - n:        Index of instance being generated.
 138  *  - insns:    BPF instructions array.
 139  *  - insns_cnt:Number of instructions in insns.
 140  *  - res:      Output parameter, result of transformation.
 141  *
 142  * Return value:
 143  *  - Zero: pre-processing success.
 144  *  - Non-zero: pre-processing, stop loading.
 145  */
 146 typedef int (*bpf_program_prep_t)(struct bpf_program *prog, int n,
 147                                   struct bpf_insn *insns, int insns_cnt,
 148                                   struct bpf_prog_prep_result *res);
 149
 150 int bpf_program__set_prep(struct bpf_program *prog, int nr_instance,
 151                           bpf_program_prep_t prep);
 152
 153 int bpf_program__nth_fd(struct bpf_program *prog, int n);
 154
 155 /*
 156  * We don't need __attribute__((packed)) now since it is
 157  * unnecessary for 'bpf_map_def' because they are all aligned.
 158  * In addition, using it will trigger -Wpacked warning message,
 159  * and will be treated as an error due to -Werror.
 160  */
 161 struct bpf_map_def {
 162         unsigned int type;
 163         unsigned int key_size;
 164         unsigned int value_size;
 165         unsigned int max_entries;
 166 };
 167
 168 /*
 169  * There is another 'struct bpf_map' in include/linux/map.h. However,
 170  * it is not a uapi header so no need to consider name clash.
 171  */
 172 struct bpf_map;
 173 struct bpf_map *
 174 bpf_object__get_map_by_name(struct bpf_object *obj, const char *name);
 175
 176 struct bpf_map *
 177 bpf_map__next(struct bpf_map *map, struct bpf_object *obj);
 178 #define bpf_map__for_each(pos, obj)             \
 179         for ((pos) = bpf_map__next(NULL, (obj));        \
 180              (pos) != NULL;                             \
 181              (pos) = bpf_map__next((pos), (obj)))
 182
 183 int bpf_map__get_fd(struct bpf_map *map);
 184 int bpf_map__get_def(struct bpf_map *map, struct bpf_map_def *pdef);
 185 const char *bpf_map__get_name(struct bpf_map *map);
 186
 187 typedef void (*bpf_map_clear_priv_t)(struct bpf_map *, void *);
 188 int bpf_map__set_private(struct bpf_map *map, void *priv,
 189                          bpf_map_clear_priv_t clear_priv);
 190 int bpf_map__get_private(struct bpf_map *map, void **ppriv);
 191
 192 #endif