tools/lib/bpf/libbpf_legacy.h

   1 /* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
   2
   3 /*
   4  * Libbpf legacy APIs (either discouraged or deprecated, as mentioned in [0])
   5  *
   6  *   [0] https://docs.google.com/document/d/1UyjTZuPFWiPFyKk1tV5an11_iaRuec6U-ZESZ54nNTY
   7  *
   8  * Copyright (C) 2021 Facebook
   9  */
  10 #ifndef __LIBBPF_LEGACY_BPF_H
  11 #define __LIBBPF_LEGACY_BPF_H
  12
  13 #include <linux/bpf.h>
  14 #include <stdbool.h>
  15 #include <stddef.h>
  16 #include <stdint.h>
  17 #include "libbpf_common.h"
  18
  19 #ifdef __cplusplus
  20 extern "C" {
  21 #endif
  22
  23 /* As of libbpf 1.0 libbpf_set_strict_mode() and enum libbpf_struct_mode have
  24  * no effect. But they are left in libbpf_legacy.h so that applications that
  25  * prepared for libbpf 1.0 before final release by using
  26  * libbpf_set_strict_mode() still work with libbpf 1.0+ without any changes.
  27  */
  28 enum libbpf_strict_mode {
  29         /* Turn on all supported strict features of libbpf to simulate libbpf
  30          * v1.0 behavior.
  31          * This will be the default behavior in libbpf v1.0.
  32          */
  33         LIBBPF_STRICT_ALL = 0xffffffff,
  34
  35         /*
  36          * Disable any libbpf 1.0 behaviors. This is the default before libbpf
  37          * v1.0. It won't be supported anymore in v1.0, please update your
  38          * code so that it handles LIBBPF_STRICT_ALL mode before libbpf v1.0.
  39          */
  40         LIBBPF_STRICT_NONE = 0x00,
  41         /*
  42          * Return NULL pointers on error, not ERR_PTR(err).
  43          * Additionally, libbpf also always sets errno to corresponding Exx
  44          * (positive) error code.
  45          */
  46         LIBBPF_STRICT_CLEAN_PTRS = 0x01,
  47         /*
  48          * Return actual error codes from low-level APIs directly, not just -1.
  49          * Additionally, libbpf also always sets errno to corresponding Exx
  50          * (positive) error code.
  51          */
  52         LIBBPF_STRICT_DIRECT_ERRS = 0x02,
  53         /*
  54          * Enforce strict BPF program section (SEC()) names.
  55          * E.g., while prefiously SEC("xdp_whatever") or SEC("perf_event_blah") were
  56          * allowed, with LIBBPF_STRICT_SEC_PREFIX this will become
  57          * unrecognized by libbpf and would have to be just SEC("xdp") and
  58          * SEC("xdp") and SEC("perf_event").
  59          *
  60          * Note, in this mode the program pin path will be based on the
  61          * function name instead of section name.
  62          *
  63          * Additionally, routines in the .text section are always considered
  64          * sub-programs. Legacy behavior allows for a single routine in .text
  65          * to be a program.
  66          */
  67         LIBBPF_STRICT_SEC_NAME = 0x04,
  68         /*
  69          * Disable the global 'bpf_objects_list'. Maintaining this list adds
  70          * a race condition to bpf_object__open() and bpf_object__close().
  71          * Clients can maintain it on their own if it is valuable for them.
  72          */
  73         LIBBPF_STRICT_NO_OBJECT_LIST = 0x08,
  74         /*
  75          * Automatically bump RLIMIT_MEMLOCK using setrlimit() before the
  76          * first BPF program or map creation operation. This is done only if
  77          * kernel is too old to support memcg-based memory accounting for BPF
  78          * subsystem. By default, RLIMIT_MEMLOCK limit is set to RLIM_INFINITY,
  79          * but it can be overridden with libbpf_set_memlock_rlim() API.
  80          * Note that libbpf_set_memlock_rlim() needs to be called before
  81          * the very first bpf_prog_load(), bpf_map_create() or bpf_object__load()
  82          * operation.
  83          */
  84         LIBBPF_STRICT_AUTO_RLIMIT_MEMLOCK = 0x10,
  85         /*
  86          * Error out on any SEC("maps") map definition, which are deprecated
  87          * in favor of BTF-defined map definitions in SEC(".maps").
  88          */
  89         LIBBPF_STRICT_MAP_DEFINITIONS = 0x20,
  90
  91         __LIBBPF_STRICT_LAST,
  92 };
  93
  94 LIBBPF_API int libbpf_set_strict_mode(enum libbpf_strict_mode mode);
  95
  96 /**
  97  * @brief **libbpf_get_error()** extracts the error code from the passed
  98  * pointer
  99  * @param ptr pointer returned from libbpf API function
 100  * @return error code; or 0 if no error occurred
 101  *
 102  * Note, as of libbpf 1.0 this function is not necessary and not recommended
 103  * to be used. Libbpf doesn't return error code embedded into the pointer
 104  * itself. Instead, NULL is returned on error and error code is passed through
 105  * thread-local errno variable. **libbpf_get_error()** is just returning -errno
 106  * value if it receives NULL, which is correct only if errno hasn't been
 107  * modified between libbpf API call and corresponding **libbpf_get_error()**
 108  * call. Prefer to check return for NULL and use errno directly.
 109  *
 110  * This API is left in libbpf 1.0 to allow applications that were 1.0-ready
 111  * before final libbpf 1.0 without needing to change them.
 112  */
 113 LIBBPF_API long libbpf_get_error(const void *ptr);
 114
 115 #define DECLARE_LIBBPF_OPTS LIBBPF_OPTS
 116
 117 /* "Discouraged" APIs which don't follow consistent libbpf naming patterns.
 118  * They are normally a trivial aliases or wrappers for proper APIs and are
 119  * left to minimize unnecessary disruption for users of libbpf. But they
 120  * shouldn't be used going forward.
 121  */
 122
 123 struct bpf_program;
 124 struct bpf_map;
 125 struct btf;
 126 struct btf_ext;
 127
 128 LIBBPF_API struct btf *libbpf_find_kernel_btf(void);
 129
 130 LIBBPF_API enum bpf_prog_type bpf_program__get_type(const struct bpf_program *prog);
 131 LIBBPF_API enum bpf_attach_type bpf_program__get_expected_attach_type(const struct bpf_program *prog);
 132 LIBBPF_API const char *bpf_map__get_pin_path(const struct bpf_map *map);
 133 LIBBPF_API const void *btf__get_raw_data(const struct btf *btf, __u32 *size);
 134 LIBBPF_API const void *btf_ext__get_raw_data(const struct btf_ext *btf_ext, __u32 *size);
 135
 136 #ifdef __cplusplus
 137 } /* extern "C" */
 138 #endif
 139
 140 #endif /* __LIBBPF_LEGACY_BPF_H */