1/* SPDX-License-Identifier: (LGPL-2.1 OR BSD-2-Clause) */
   2
   3/*
   4 * Common eBPF ELF object loading operations.
   5 *
   6 * Copyright (C) 2013-2015 Alexei Starovoitov <ast@kernel.org>
   7 * Copyright (C) 2015 Wang Nan <wangnan0@huawei.com>
   8 * Copyright (C) 2015 Huawei Inc.
   9 */
  10#ifndef __LIBBPF_LIBBPF_H
  11#define __LIBBPF_LIBBPF_H
  12
  13#include <stdarg.h>
  14#include <stdio.h>
  15#include <stdint.h>
  16#include <stdbool.h>
  17#include <sys/types.h>  // for size_t
  18#include <linux/bpf.h>
  19
  20#include "libbpf_common.h"
  21#include "libbpf_legacy.h"
  22
  23#ifdef __cplusplus
  24extern "C" {
  25#endif
  26
  27LIBBPF_API __u32 libbpf_major_version(void);
  28LIBBPF_API __u32 libbpf_minor_version(void);
  29LIBBPF_API const char *libbpf_version_string(void);
  30
  31enum libbpf_errno {
  32	__LIBBPF_ERRNO__START = 4000,
  33
  34	/* Something wrong in libelf */
  35	LIBBPF_ERRNO__LIBELF = __LIBBPF_ERRNO__START,
  36	LIBBPF_ERRNO__FORMAT,	/* BPF object format invalid */
  37	LIBBPF_ERRNO__KVERSION,	/* Incorrect or no 'version' section */
  38	LIBBPF_ERRNO__ENDIAN,	/* Endian mismatch */
  39	LIBBPF_ERRNO__INTERNAL,	/* Internal error in libbpf */
  40	LIBBPF_ERRNO__RELOC,	/* Relocation failed */
  41	LIBBPF_ERRNO__LOAD,	/* Load program failure for unknown reason */
  42	LIBBPF_ERRNO__VERIFY,	/* Kernel verifier blocks program loading */
  43	LIBBPF_ERRNO__PROG2BIG,	/* Program too big */
  44	LIBBPF_ERRNO__KVER,	/* Incorrect kernel version */
  45	LIBBPF_ERRNO__PROGTYPE,	/* Kernel doesn't support this program type */
  46	LIBBPF_ERRNO__WRNGPID,	/* Wrong pid in netlink message */
  47	LIBBPF_ERRNO__INVSEQ,	/* Invalid netlink sequence */
  48	LIBBPF_ERRNO__NLPARSE,	/* netlink parsing error */
  49	__LIBBPF_ERRNO__END,
  50};
  51
  52LIBBPF_API int libbpf_strerror(int err, char *buf, size_t size);
  53
  54/**
  55 * @brief **libbpf_bpf_attach_type_str()** converts the provided attach type
  56 * value into a textual representation.
  57 * @param t The attach type.
  58 * @return Pointer to a static string identifying the attach type. NULL is
  59 * returned for unknown **bpf_attach_type** values.
  60 */
  61LIBBPF_API const char *libbpf_bpf_attach_type_str(enum bpf_attach_type t);
  62
  63/**
  64 * @brief **libbpf_bpf_link_type_str()** converts the provided link type value
  65 * into a textual representation.
  66 * @param t The link type.
  67 * @return Pointer to a static string identifying the link type. NULL is
  68 * returned for unknown **bpf_link_type** values.
  69 */
  70LIBBPF_API const char *libbpf_bpf_link_type_str(enum bpf_link_type t);
  71
  72/**
  73 * @brief **libbpf_bpf_map_type_str()** converts the provided map type value
  74 * into a textual representation.
  75 * @param t The map type.
  76 * @return Pointer to a static string identifying the map type. NULL is
  77 * returned for unknown **bpf_map_type** values.
  78 */
  79LIBBPF_API const char *libbpf_bpf_map_type_str(enum bpf_map_type t);
  80
  81/**
  82 * @brief **libbpf_bpf_prog_type_str()** converts the provided program type
  83 * value into a textual representation.
  84 * @param t The program type.
  85 * @return Pointer to a static string identifying the program type. NULL is
  86 * returned for unknown **bpf_prog_type** values.
  87 */
  88LIBBPF_API const char *libbpf_bpf_prog_type_str(enum bpf_prog_type t);
  89
  90enum libbpf_print_level {
  91        LIBBPF_WARN,
  92        LIBBPF_INFO,
  93        LIBBPF_DEBUG,
  94};
  95
  96typedef int (*libbpf_print_fn_t)(enum libbpf_print_level level,
  97				 const char *, va_list ap);
  98
  99/**
 100 * @brief **libbpf_set_print()** sets user-provided log callback function to
 101 * be used for libbpf warnings and informational messages.
 102 * @param fn The log print function. If NULL, libbpf won't print anything.
 103 * @return Pointer to old print function.
 104 *
 105 * This function is thread-safe.
 106 */
 107LIBBPF_API libbpf_print_fn_t libbpf_set_print(libbpf_print_fn_t fn);
 108
 109/* Hide internal to user */
 110struct bpf_object;
 111
 112struct bpf_object_open_opts {
 113	/* size of this struct, for forward/backward compatibility */
 114	size_t sz;
 115	/* object name override, if provided:
 116	 * - for object open from file, this will override setting object
 117	 *   name from file path's base name;
 118	 * - for object open from memory buffer, this will specify an object
 119	 *   name and will override default "<addr>-<buf-size>" name;
 120	 */
 121	const char *object_name;
 122	/* parse map definitions non-strictly, allowing extra attributes/data */
 123	bool relaxed_maps;
 124	/* maps that set the 'pinning' attribute in their definition will have
 125	 * their pin_path attribute set to a file in this directory, and be
 126	 * auto-pinned to that path on load; defaults to "/sys/fs/bpf".
 127	 */
 128	const char *pin_root_path;
 129
 130	__u32 :32; /* stub out now removed attach_prog_fd */
 131
 132	/* Additional kernel config content that augments and overrides
 133	 * system Kconfig for CONFIG_xxx externs.
 134	 */
 135	const char *kconfig;
 136	/* Path to the custom BTF to be used for BPF CO-RE relocations.
 137	 * This custom BTF completely replaces the use of vmlinux BTF
 138	 * for the purpose of CO-RE relocations.
 139	 * NOTE: any other BPF feature (e.g., fentry/fexit programs,
 140	 * struct_ops, etc) will need actual kernel BTF at /sys/kernel/btf/vmlinux.
 141	 */
 142	const char *btf_custom_path;
 143	/* Pointer to a buffer for storing kernel logs for applicable BPF
 144	 * commands. Valid kernel_log_size has to be specified as well and are
 145	 * passed-through to bpf() syscall. Keep in mind that kernel might
 146	 * fail operation with -ENOSPC error if provided buffer is too small
 147	 * to contain entire log output.
 148	 * See the comment below for kernel_log_level for interaction between
 149	 * log_buf and log_level settings.
 150	 *
 151	 * If specified, this log buffer will be passed for:
 152	 *   - each BPF progral load (BPF_PROG_LOAD) attempt, unless overriden
 153	 *     with bpf_program__set_log() on per-program level, to get
 154	 *     BPF verifier log output.
 155	 *   - during BPF object's BTF load into kernel (BPF_BTF_LOAD) to get
 156	 *     BTF sanity checking log.
 157	 *
 158	 * Each BPF command (BPF_BTF_LOAD or BPF_PROG_LOAD) will overwrite
 159	 * previous contents, so if you need more fine-grained control, set
 160	 * per-program buffer with bpf_program__set_log_buf() to preserve each
 161	 * individual program's verification log. Keep using kernel_log_buf
 162	 * for BTF verification log, if necessary.
 163	 */
 164	char *kernel_log_buf;
 165	size_t kernel_log_size;
 166	/*
 167	 * Log level can be set independently from log buffer. Log_level=0
 168	 * means that libbpf will attempt loading BTF or program without any
 169	 * logging requested, but will retry with either its own or custom log
 170	 * buffer, if provided, and log_level=1 on any error.
 171	 * And vice versa, setting log_level>0 will request BTF or prog
 172	 * loading with verbose log from the first attempt (and as such also
 173	 * for successfully loaded BTF or program), and the actual log buffer
 174	 * could be either libbpf's own auto-allocated log buffer, if
 175	 * kernel_log_buffer is NULL, or user-provided custom kernel_log_buf.
 176	 * If user didn't provide custom log buffer, libbpf will emit captured
 177	 * logs through its print callback.
 178	 */
 179	__u32 kernel_log_level;
 180
 181	size_t :0;
 182};
 183#define bpf_object_open_opts__last_field kernel_log_level
 184
 185/**
 186 * @brief **bpf_object__open()** creates a bpf_object by opening
 187 * the BPF ELF object file pointed to by the passed path and loading it
 188 * into memory.
 189 * @param path BPF object file path.
 190 * @return pointer to the new bpf_object; or NULL is returned on error,
 191 * error code is stored in errno
 192 */
 193LIBBPF_API struct bpf_object *bpf_object__open(const char *path);
 194
 195/**
 196 * @brief **bpf_object__open_file()** creates a bpf_object by opening
 197 * the BPF ELF object file pointed to by the passed path and loading it
 198 * into memory.
 199 * @param path BPF object file path
 200 * @param opts options for how to load the bpf object, this parameter is
 201 * optional and can be set to NULL
 202 * @return pointer to the new bpf_object; or NULL is returned on error,
 203 * error code is stored in errno
 204 */
 205LIBBPF_API struct bpf_object *
 206bpf_object__open_file(const char *path, const struct bpf_object_open_opts *opts);
 207
 208/**
 209 * @brief **bpf_object__open_mem()** creates a bpf_object by reading
 210 * the BPF objects raw bytes from a memory buffer containing a valid
 211 * BPF ELF object file.
 212 * @param obj_buf pointer to the buffer containing ELF file bytes
 213 * @param obj_buf_sz number of bytes in the buffer
 214 * @param opts options for how to load the bpf object
 215 * @return pointer to the new bpf_object; or NULL is returned on error,
 216 * error code is stored in errno
 217 */
 218LIBBPF_API struct bpf_object *
 219bpf_object__open_mem(const void *obj_buf, size_t obj_buf_sz,
 220		     const struct bpf_object_open_opts *opts);
 221
 222/**
 223 * @brief **bpf_object__load()** loads BPF object into kernel.
 224 * @param obj Pointer to a valid BPF object instance returned by
 225 * **bpf_object__open*()** APIs
 226 * @return 0, on success; negative error code, otherwise, error code is
 227 * stored in errno
 228 */
 229LIBBPF_API int bpf_object__load(struct bpf_object *obj);
 230
 231/**
 232 * @brief **bpf_object__close()** closes a BPF object and releases all
 233 * resources.
 234 * @param obj Pointer to a valid BPF object
 235 */
 236LIBBPF_API void bpf_object__close(struct bpf_object *obj);
 237
 238/**
 239 * @brief **bpf_object__pin_maps()** pins each map contained within
 240 * the BPF object at the passed directory.
 241 * @param obj Pointer to a valid BPF object
 242 * @param path A directory where maps should be pinned.
 243 * @return 0, on success; negative error code, otherwise
 244 *
 245 * If `path` is NULL `bpf_map__pin` (which is being used on each map)
 246 * will use the pin_path attribute of each map. In this case, maps that
 247 * don't have a pin_path set will be ignored.
 248 */
 249LIBBPF_API int bpf_object__pin_maps(struct bpf_object *obj, const char *path);
 250
 251/**
 252 * @brief **bpf_object__unpin_maps()** unpins each map contained within
 253 * the BPF object found in the passed directory.
 254 * @param obj Pointer to a valid BPF object
 255 * @param path A directory where pinned maps should be searched for.
 256 * @return 0, on success; negative error code, otherwise
 257 *
 258 * If `path` is NULL `bpf_map__unpin` (which is being used on each map)
 259 * will use the pin_path attribute of each map. In this case, maps that
 260 * don't have a pin_path set will be ignored.
 261 */
 262LIBBPF_API int bpf_object__unpin_maps(struct bpf_object *obj,
 263				      const char *path);
 264LIBBPF_API int bpf_object__pin_programs(struct bpf_object *obj,
 265					const char *path);
 266LIBBPF_API int bpf_object__unpin_programs(struct bpf_object *obj,
 267					  const char *path);
 268LIBBPF_API int bpf_object__pin(struct bpf_object *object, const char *path);
 269LIBBPF_API int bpf_object__unpin(struct bpf_object *object, const char *path);
 270
 271LIBBPF_API const char *bpf_object__name(const struct bpf_object *obj);
 272LIBBPF_API unsigned int bpf_object__kversion(const struct bpf_object *obj);
 273LIBBPF_API int bpf_object__set_kversion(struct bpf_object *obj, __u32 kern_version);
 274
 275struct btf;
 276LIBBPF_API struct btf *bpf_object__btf(const struct bpf_object *obj);
 277LIBBPF_API int bpf_object__btf_fd(const struct bpf_object *obj);
 278
 279LIBBPF_API struct bpf_program *
 280bpf_object__find_program_by_name(const struct bpf_object *obj,
 281				 const char *name);
 282
 283LIBBPF_API int
 284libbpf_prog_type_by_name(const char *name, enum bpf_prog_type *prog_type,
 285			 enum bpf_attach_type *expected_attach_type);
 286LIBBPF_API int libbpf_attach_type_by_name(const char *name,
 287					  enum bpf_attach_type *attach_type);
 288LIBBPF_API int libbpf_find_vmlinux_btf_id(const char *name,
 289					  enum bpf_attach_type attach_type);
 290
 291/* Accessors of bpf_program */
 292struct bpf_program;
 293
 294LIBBPF_API struct bpf_program *
 295bpf_object__next_program(const struct bpf_object *obj, struct bpf_program *prog);
 296
 297#define bpf_object__for_each_program(pos, obj)			\
 298	for ((pos) = bpf_object__next_program((obj), NULL);	\
 299	     (pos) != NULL;					\
 300	     (pos) = bpf_object__next_program((obj), (pos)))
 301
 302LIBBPF_API struct bpf_program *
 303bpf_object__prev_program(const struct bpf_object *obj, struct bpf_program *prog);
 304
 305LIBBPF_API void bpf_program__set_ifindex(struct bpf_program *prog,
 306					 __u32 ifindex);
 307
 308LIBBPF_API const char *bpf_program__name(const struct bpf_program *prog);
 309LIBBPF_API const char *bpf_program__section_name(const struct bpf_program *prog);
 310LIBBPF_API bool bpf_program__autoload(const struct bpf_program *prog);
 311LIBBPF_API int bpf_program__set_autoload(struct bpf_program *prog, bool autoload);
 312LIBBPF_API bool bpf_program__autoattach(const struct bpf_program *prog);
 313LIBBPF_API void bpf_program__set_autoattach(struct bpf_program *prog, bool autoattach);
 314
 315struct bpf_insn;
 316
 317/**
 318 * @brief **bpf_program__insns()** gives read-only access to BPF program's
 319 * underlying BPF instructions.
 320 * @param prog BPF program for which to return instructions
 321 * @return a pointer to an array of BPF instructions that belong to the
 322 * specified BPF program
 323 *
 324 * Returned pointer is always valid and not NULL. Number of `struct bpf_insn`
 325 * pointed to can be fetched using **bpf_program__insn_cnt()** API.
 326 *
 327 * Keep in mind, libbpf can modify and append/delete BPF program's
 328 * instructions as it processes BPF object file and prepares everything for
 329 * uploading into the kernel. So depending on the point in BPF object
 330 * lifetime, **bpf_program__insns()** can return different sets of
 331 * instructions. As an example, during BPF object load phase BPF program
 332 * instructions will be CO-RE-relocated, BPF subprograms instructions will be
 333 * appended, ldimm64 instructions will have FDs embedded, etc. So instructions
 334 * returned before **bpf_object__load()** and after it might be quite
 335 * different.
 336 */
 337LIBBPF_API const struct bpf_insn *bpf_program__insns(const struct bpf_program *prog);
 338
 339/**
 340 * @brief **bpf_program__set_insns()** can set BPF program's underlying
 341 * BPF instructions.
 342 *
 343 * WARNING: This is a very advanced libbpf API and users need to know
 344 * what they are doing. This should be used from prog_prepare_load_fn
 345 * callback only.
 346 *
 347 * @param prog BPF program for which to return instructions
 348 * @param new_insns a pointer to an array of BPF instructions
 349 * @param new_insn_cnt number of `struct bpf_insn`'s that form
 350 * specified BPF program
 351 * @return 0, on success; negative error code, otherwise
 352 */
 353LIBBPF_API int bpf_program__set_insns(struct bpf_program *prog,
 354				      struct bpf_insn *new_insns, size_t new_insn_cnt);
 355
 356/**
 357 * @brief **bpf_program__insn_cnt()** returns number of `struct bpf_insn`'s
 358 * that form specified BPF program.
 359 * @param prog BPF program for which to return number of BPF instructions
 360 *
 361 * See **bpf_program__insns()** documentation for notes on how libbpf can
 362 * change instructions and their count during different phases of
 363 * **bpf_object** lifetime.
 364 */
 365LIBBPF_API size_t bpf_program__insn_cnt(const struct bpf_program *prog);
 366
 367LIBBPF_API int bpf_program__fd(const struct bpf_program *prog);
 368
 369/**
 370 * @brief **bpf_program__pin()** pins the BPF program to a file
 371 * in the BPF FS specified by a path. This increments the programs
 372 * reference count, allowing it to stay loaded after the process
 373 * which loaded it has exited.
 374 *
 375 * @param prog BPF program to pin, must already be loaded
 376 * @param path file path in a BPF file system
 377 * @return 0, on success; negative error code, otherwise
 378 */
 379LIBBPF_API int bpf_program__pin(struct bpf_program *prog, const char *path);
 380
 381/**
 382 * @brief **bpf_program__unpin()** unpins the BPF program from a file
 383 * in the BPFFS specified by a path. This decrements the programs
 384 * reference count.
 385 *
 386 * The file pinning the BPF program can also be unlinked by a different
 387 * process in which case this function will return an error.
 388 *
 389 * @param prog BPF program to unpin
 390 * @param path file path to the pin in a BPF file system
 391 * @return 0, on success; negative error code, otherwise
 392 */
 393LIBBPF_API int bpf_program__unpin(struct bpf_program *prog, const char *path);
 394LIBBPF_API void bpf_program__unload(struct bpf_program *prog);
 395
 396struct bpf_link;
 397
 398LIBBPF_API struct bpf_link *bpf_link__open(const char *path);
 399LIBBPF_API int bpf_link__fd(const struct bpf_link *link);
 400LIBBPF_API const char *bpf_link__pin_path(const struct bpf_link *link);
 401/**
 402 * @brief **bpf_link__pin()** pins the BPF link to a file
 403 * in the BPF FS specified by a path. This increments the links
 404 * reference count, allowing it to stay loaded after the process
 405 * which loaded it has exited.
 406 *
 407 * @param link BPF link to pin, must already be loaded
 408 * @param path file path in a BPF file system
 409 * @return 0, on success; negative error code, otherwise
 410 */
 411
 412LIBBPF_API int bpf_link__pin(struct bpf_link *link, const char *path);
 413
 414/**
 415 * @brief **bpf_link__unpin()** unpins the BPF link from a file
 416 * in the BPFFS specified by a path. This decrements the links
 417 * reference count.
 418 *
 419 * The file pinning the BPF link can also be unlinked by a different
 420 * process in which case this function will return an error.
 421 *
 422 * @param prog BPF program to unpin
 423 * @param path file path to the pin in a BPF file system
 424 * @return 0, on success; negative error code, otherwise
 425 */
 426LIBBPF_API int bpf_link__unpin(struct bpf_link *link);
 427LIBBPF_API int bpf_link__update_program(struct bpf_link *link,
 428					struct bpf_program *prog);
 429LIBBPF_API void bpf_link__disconnect(struct bpf_link *link);
 430LIBBPF_API int bpf_link__detach(struct bpf_link *link);
 431LIBBPF_API int bpf_link__destroy(struct bpf_link *link);
 432
 433/**
 434 * @brief **bpf_program__attach()** is a generic function for attaching
 435 * a BPF program based on auto-detection of program type, attach type,
 436 * and extra paremeters, where applicable.
 437 *
 438 * @param prog BPF program to attach
 439 * @return Reference to the newly created BPF link; or NULL is returned on error,
 440 * error code is stored in errno
 441 *
 442 * This is supported for:
 443 *   - kprobe/kretprobe (depends on SEC() definition)
 444 *   - uprobe/uretprobe (depends on SEC() definition)
 445 *   - tracepoint
 446 *   - raw tracepoint
 447 *   - tracing programs (typed raw TP/fentry/fexit/fmod_ret)
 448 */
 449LIBBPF_API struct bpf_link *
 450bpf_program__attach(const struct bpf_program *prog);
 451
 452struct bpf_perf_event_opts {
 453	/* size of this struct, for forward/backward compatibility */
 454	size_t sz;
 455	/* custom user-provided value fetchable through bpf_get_attach_cookie() */
 456	__u64 bpf_cookie;
 457	/* don't use BPF link when attach BPF program */
 458	bool force_ioctl_attach;
 459	size_t :0;
 460};
 461#define bpf_perf_event_opts__last_field force_ioctl_attach
 462
 463LIBBPF_API struct bpf_link *
 464bpf_program__attach_perf_event(const struct bpf_program *prog, int pfd);
 465
 466LIBBPF_API struct bpf_link *
 467bpf_program__attach_perf_event_opts(const struct bpf_program *prog, int pfd,
 468				    const struct bpf_perf_event_opts *opts);
 469
 470/**
 471 * enum probe_attach_mode - the mode to attach kprobe/uprobe
 472 *
 473 * force libbpf to attach kprobe/uprobe in specific mode, -ENOTSUP will
 474 * be returned if it is not supported by the kernel.
 475 */
 476enum probe_attach_mode {
 477	/* attach probe in latest supported mode by kernel */
 478	PROBE_ATTACH_MODE_DEFAULT = 0,
 479	/* attach probe in legacy mode, using debugfs/tracefs */
 480	PROBE_ATTACH_MODE_LEGACY,
 481	/* create perf event with perf_event_open() syscall */
 482	PROBE_ATTACH_MODE_PERF,
 483	/* attach probe with BPF link */
 484	PROBE_ATTACH_MODE_LINK,
 485};
 486
 487struct bpf_kprobe_opts {
 488	/* size of this struct, for forward/backward compatibility */
 489	size_t sz;
 490	/* custom user-provided value fetchable through bpf_get_attach_cookie() */
 491	__u64 bpf_cookie;
 492	/* function's offset to install kprobe to */
 493	size_t offset;
 494	/* kprobe is return probe */
 495	bool retprobe;
 496	/* kprobe attach mode */
 497	enum probe_attach_mode attach_mode;
 498	size_t :0;
 499};
 500#define bpf_kprobe_opts__last_field attach_mode
 501
 502LIBBPF_API struct bpf_link *
 503bpf_program__attach_kprobe(const struct bpf_program *prog, bool retprobe,
 504			   const char *func_name);
 505LIBBPF_API struct bpf_link *
 506bpf_program__attach_kprobe_opts(const struct bpf_program *prog,
 507                                const char *func_name,
 508                                const struct bpf_kprobe_opts *opts);
 509
 510struct bpf_kprobe_multi_opts {
 511	/* size of this struct, for forward/backward compatibility */
 512	size_t sz;
 513	/* array of function symbols to attach */
 514	const char **syms;
 515	/* array of function addresses to attach */
 516	const unsigned long *addrs;
 517	/* array of user-provided values fetchable through bpf_get_attach_cookie */
 518	const __u64 *cookies;
 519	/* number of elements in syms/addrs/cookies arrays */
 520	size_t cnt;
 521	/* create return kprobes */
 522	bool retprobe;
 523	size_t :0;
 524};
 525
 526#define bpf_kprobe_multi_opts__last_field retprobe
 527
 528LIBBPF_API struct bpf_link *
 529bpf_program__attach_kprobe_multi_opts(const struct bpf_program *prog,
 530				      const char *pattern,
 531				      const struct bpf_kprobe_multi_opts *opts);
 532
 533struct bpf_uprobe_multi_opts {
 534	/* size of this struct, for forward/backward compatibility */
 535	size_t sz;
 536	/* array of function symbols to attach to */
 537	const char **syms;
 538	/* array of function addresses to attach to */
 539	const unsigned long *offsets;
 540	/* optional, array of associated ref counter offsets */
 541	const unsigned long *ref_ctr_offsets;
 542	/* optional, array of associated BPF cookies */
 543	const __u64 *cookies;
 544	/* number of elements in syms/addrs/cookies arrays */
 545	size_t cnt;
 546	/* create return uprobes */
 547	bool retprobe;
 548	size_t :0;
 549};
 550
 551#define bpf_uprobe_multi_opts__last_field retprobe
 552
 553/**
 554 * @brief **bpf_program__attach_uprobe_multi()** attaches a BPF program
 555 * to multiple uprobes with uprobe_multi link.
 556 *
 557 * User can specify 2 mutually exclusive set of inputs:
 558 *
 559 *   1) use only path/func_pattern/pid arguments
 560 *
 561 *   2) use path/pid with allowed combinations of
 562 *      syms/offsets/ref_ctr_offsets/cookies/cnt
 563 *
 564 *      - syms and offsets are mutually exclusive
 565 *      - ref_ctr_offsets and cookies are optional
 566 *
 567 *
 568 * @param prog BPF program to attach
 569 * @param pid Process ID to attach the uprobe to, 0 for self (own process),
 570 * -1 for all processes
 571 * @param binary_path Path to binary
 572 * @param func_pattern Regular expression to specify functions to attach
 573 * BPF program to
 574 * @param opts Additional options (see **struct bpf_uprobe_multi_opts**)
 575 * @return 0, on success; negative error code, otherwise
 576 */
 577LIBBPF_API struct bpf_link *
 578bpf_program__attach_uprobe_multi(const struct bpf_program *prog,
 579				 pid_t pid,
 580				 const char *binary_path,
 581				 const char *func_pattern,
 582				 const struct bpf_uprobe_multi_opts *opts);
 583
 584struct bpf_ksyscall_opts {
 585	/* size of this struct, for forward/backward compatibility */
 586	size_t sz;
 587	/* custom user-provided value fetchable through bpf_get_attach_cookie() */
 588	__u64 bpf_cookie;
 589	/* attach as return probe? */
 590	bool retprobe;
 591	size_t :0;
 592};
 593#define bpf_ksyscall_opts__last_field retprobe
 594
 595/**
 596 * @brief **bpf_program__attach_ksyscall()** attaches a BPF program
 597 * to kernel syscall handler of a specified syscall. Optionally it's possible
 598 * to request to install retprobe that will be triggered at syscall exit. It's
 599 * also possible to associate BPF cookie (though options).
 600 *
 601 * Libbpf automatically will determine correct full kernel function name,
 602 * which depending on system architecture and kernel version/configuration
 603 * could be of the form __<arch>_sys_<syscall> or __se_sys_<syscall>, and will
 604 * attach specified program using kprobe/kretprobe mechanism.
 605 *
 606 * **bpf_program__attach_ksyscall()** is an API counterpart of declarative
 607 * **SEC("ksyscall/<syscall>")** annotation of BPF programs.
 608 *
 609 * At the moment **SEC("ksyscall")** and **bpf_program__attach_ksyscall()** do
 610 * not handle all the calling convention quirks for mmap(), clone() and compat
 611 * syscalls. It also only attaches to "native" syscall interfaces. If host
 612 * system supports compat syscalls or defines 32-bit syscalls in 64-bit
 613 * kernel, such syscall interfaces won't be attached to by libbpf.
 614 *
 615 * These limitations may or may not change in the future. Therefore it is
 616 * recommended to use SEC("kprobe") for these syscalls or if working with
 617 * compat and 32-bit interfaces is required.
 618 *
 619 * @param prog BPF program to attach
 620 * @param syscall_name Symbolic name of the syscall (e.g., "bpf")
 621 * @param opts Additional options (see **struct bpf_ksyscall_opts**)
 622 * @return Reference to the newly created BPF link; or NULL is returned on
 623 * error, error code is stored in errno
 624 */
 625LIBBPF_API struct bpf_link *
 626bpf_program__attach_ksyscall(const struct bpf_program *prog,
 627			     const char *syscall_name,
 628			     const struct bpf_ksyscall_opts *opts);
 629
 630struct bpf_uprobe_opts {
 631	/* size of this struct, for forward/backward compatibility */
 632	size_t sz;
 633	/* offset of kernel reference counted USDT semaphore, added in
 634	 * a6ca88b241d5 ("trace_uprobe: support reference counter in fd-based uprobe")
 635	 */
 636	size_t ref_ctr_offset;
 637	/* custom user-provided value fetchable through bpf_get_attach_cookie() */
 638	__u64 bpf_cookie;
 639	/* uprobe is return probe, invoked at function return time */
 640	bool retprobe;
 641	/* Function name to attach to.  Could be an unqualified ("abc") or library-qualified
 642	 * "abc@LIBXYZ" name.  To specify function entry, func_name should be set while
 643	 * func_offset argument to bpf_prog__attach_uprobe_opts() should be 0.  To trace an
 644	 * offset within a function, specify func_name and use func_offset argument to specify
 645	 * offset within the function.  Shared library functions must specify the shared library
 646	 * binary_path.
 647	 */
 648	const char *func_name;
 649	/* uprobe attach mode */
 650	enum probe_attach_mode attach_mode;
 651	size_t :0;
 652};
 653#define bpf_uprobe_opts__last_field attach_mode
 654
 655/**
 656 * @brief **bpf_program__attach_uprobe()** attaches a BPF program
 657 * to the userspace function which is found by binary path and
 658 * offset. You can optionally specify a particular proccess to attach
 659 * to. You can also optionally attach the program to the function
 660 * exit instead of entry.
 661 *
 662 * @param prog BPF program to attach
 663 * @param retprobe Attach to function exit
 664 * @param pid Process ID to attach the uprobe to, 0 for self (own process),
 665 * -1 for all processes
 666 * @param binary_path Path to binary that contains the function symbol
 667 * @param func_offset Offset within the binary of the function symbol
 668 * @return Reference to the newly created BPF link; or NULL is returned on error,
 669 * error code is stored in errno
 670 */
 671LIBBPF_API struct bpf_link *
 672bpf_program__attach_uprobe(const struct bpf_program *prog, bool retprobe,
 673			   pid_t pid, const char *binary_path,
 674			   size_t func_offset);
 675
 676/**
 677 * @brief **bpf_program__attach_uprobe_opts()** is just like
 678 * bpf_program__attach_uprobe() except with a options struct
 679 * for various configurations.
 680 *
 681 * @param prog BPF program to attach
 682 * @param pid Process ID to attach the uprobe to, 0 for self (own process),
 683 * -1 for all processes
 684 * @param binary_path Path to binary that contains the function symbol
 685 * @param func_offset Offset within the binary of the function symbol
 686 * @param opts Options for altering program attachment
 687 * @return Reference to the newly created BPF link; or NULL is returned on error,
 688 * error code is stored in errno
 689 */
 690LIBBPF_API struct bpf_link *
 691bpf_program__attach_uprobe_opts(const struct bpf_program *prog, pid_t pid,
 692				const char *binary_path, size_t func_offset,
 693				const struct bpf_uprobe_opts *opts);
 694
 695struct bpf_usdt_opts {
 696	/* size of this struct, for forward/backward compatibility */
 697	size_t sz;
 698	/* custom user-provided value accessible through usdt_cookie() */
 699	__u64 usdt_cookie;
 700	size_t :0;
 701};
 702#define bpf_usdt_opts__last_field usdt_cookie
 703
 704/**
 705 * @brief **bpf_program__attach_usdt()** is just like
 706 * bpf_program__attach_uprobe_opts() except it covers USDT (User-space
 707 * Statically Defined Tracepoint) attachment, instead of attaching to
 708 * user-space function entry or exit.
 709 *
 710 * @param prog BPF program to attach
 711 * @param pid Process ID to attach the uprobe to, 0 for self (own process),
 712 * -1 for all processes
 713 * @param binary_path Path to binary that contains provided USDT probe
 714 * @param usdt_provider USDT provider name
 715 * @param usdt_name USDT probe name
 716 * @param opts Options for altering program attachment
 717 * @return Reference to the newly created BPF link; or NULL is returned on error,
 718 * error code is stored in errno
 719 */
 720LIBBPF_API struct bpf_link *
 721bpf_program__attach_usdt(const struct bpf_program *prog,
 722			 pid_t pid, const char *binary_path,
 723			 const char *usdt_provider, const char *usdt_name,
 724			 const struct bpf_usdt_opts *opts);
 725
 726struct bpf_tracepoint_opts {
 727	/* size of this struct, for forward/backward compatibility */
 728	size_t sz;
 729	/* custom user-provided value fetchable through bpf_get_attach_cookie() */
 730	__u64 bpf_cookie;
 731};
 732#define bpf_tracepoint_opts__last_field bpf_cookie
 733
 734LIBBPF_API struct bpf_link *
 735bpf_program__attach_tracepoint(const struct bpf_program *prog,
 736			       const char *tp_category,
 737			       const char *tp_name);
 738LIBBPF_API struct bpf_link *
 739bpf_program__attach_tracepoint_opts(const struct bpf_program *prog,
 740				    const char *tp_category,
 741				    const char *tp_name,
 742				    const struct bpf_tracepoint_opts *opts);
 743
 744LIBBPF_API struct bpf_link *
 745bpf_program__attach_raw_tracepoint(const struct bpf_program *prog,
 746				   const char *tp_name);
 747
 748struct bpf_trace_opts {
 749	/* size of this struct, for forward/backward compatibility */
 750	size_t sz;
 751	/* custom user-provided value fetchable through bpf_get_attach_cookie() */
 752	__u64 cookie;
 753};
 754#define bpf_trace_opts__last_field cookie
 755
 756LIBBPF_API struct bpf_link *
 757bpf_program__attach_trace(const struct bpf_program *prog);
 758LIBBPF_API struct bpf_link *
 759bpf_program__attach_trace_opts(const struct bpf_program *prog, const struct bpf_trace_opts *opts);
 760
 761LIBBPF_API struct bpf_link *
 762bpf_program__attach_lsm(const struct bpf_program *prog);
 763LIBBPF_API struct bpf_link *
 764bpf_program__attach_cgroup(const struct bpf_program *prog, int cgroup_fd);
 765LIBBPF_API struct bpf_link *
 766bpf_program__attach_netns(const struct bpf_program *prog, int netns_fd);
 767LIBBPF_API struct bpf_link *
 768bpf_program__attach_xdp(const struct bpf_program *prog, int ifindex);
 769LIBBPF_API struct bpf_link *
 770bpf_program__attach_freplace(const struct bpf_program *prog,
 771			     int target_fd, const char *attach_func_name);
 772
 773struct bpf_netfilter_opts {
 774	/* size of this struct, for forward/backward compatibility */
 775	size_t sz;
 776
 777	__u32 pf;
 778	__u32 hooknum;
 779	__s32 priority;
 780	__u32 flags;
 781};
 782#define bpf_netfilter_opts__last_field flags
 783
 784LIBBPF_API struct bpf_link *
 785bpf_program__attach_netfilter(const struct bpf_program *prog,
 786			      const struct bpf_netfilter_opts *opts);
 787
 788struct bpf_tcx_opts {
 789	/* size of this struct, for forward/backward compatibility */
 790	size_t sz;
 791	__u32 flags;
 792	__u32 relative_fd;
 793	__u32 relative_id;
 794	__u64 expected_revision;
 795	size_t :0;
 796};
 797#define bpf_tcx_opts__last_field expected_revision
 798
 799LIBBPF_API struct bpf_link *
 800bpf_program__attach_tcx(const struct bpf_program *prog, int ifindex,
 801			const struct bpf_tcx_opts *opts);
 802
 803struct bpf_netkit_opts {
 804	/* size of this struct, for forward/backward compatibility */
 805	size_t sz;
 806	__u32 flags;
 807	__u32 relative_fd;
 808	__u32 relative_id;
 809	__u64 expected_revision;
 810	size_t :0;
 811};
 812#define bpf_netkit_opts__last_field expected_revision
 813
 814LIBBPF_API struct bpf_link *
 815bpf_program__attach_netkit(const struct bpf_program *prog, int ifindex,
 816			   const struct bpf_netkit_opts *opts);
 817
 818struct bpf_map;
 819
 820LIBBPF_API struct bpf_link *bpf_map__attach_struct_ops(const struct bpf_map *map);
 821LIBBPF_API int bpf_link__update_map(struct bpf_link *link, const struct bpf_map *map);
 822
 823struct bpf_iter_attach_opts {
 824	size_t sz; /* size of this struct for forward/backward compatibility */
 825	union bpf_iter_link_info *link_info;
 826	__u32 link_info_len;
 827};
 828#define bpf_iter_attach_opts__last_field link_info_len
 829
 830LIBBPF_API struct bpf_link *
 831bpf_program__attach_iter(const struct bpf_program *prog,
 832			 const struct bpf_iter_attach_opts *opts);
 833
 834LIBBPF_API enum bpf_prog_type bpf_program__type(const struct bpf_program *prog);
 835
 836/**
 837 * @brief **bpf_program__set_type()** sets the program
 838 * type of the passed BPF program.
 839 * @param prog BPF program to set the program type for
 840 * @param type program type to set the BPF map to have
 841 * @return error code; or 0 if no error. An error occurs
 842 * if the object is already loaded.
 843 *
 844 * This must be called before the BPF object is loaded,
 845 * otherwise it has no effect and an error is returned.
 846 */
 847LIBBPF_API int bpf_program__set_type(struct bpf_program *prog,
 848				     enum bpf_prog_type type);
 849
 850LIBBPF_API enum bpf_attach_type
 851bpf_program__expected_attach_type(const struct bpf_program *prog);
 852
 853/**
 854 * @brief **bpf_program__set_expected_attach_type()** sets the
 855 * attach type of the passed BPF program. This is used for
 856 * auto-detection of attachment when programs are loaded.
 857 * @param prog BPF program to set the attach type for
 858 * @param type attach type to set the BPF map to have
 859 * @return error code; or 0 if no error. An error occurs
 860 * if the object is already loaded.
 861 *
 862 * This must be called before the BPF object is loaded,
 863 * otherwise it has no effect and an error is returned.
 864 */
 865LIBBPF_API int
 866bpf_program__set_expected_attach_type(struct bpf_program *prog,
 867				      enum bpf_attach_type type);
 868
 869LIBBPF_API __u32 bpf_program__flags(const struct bpf_program *prog);
 870LIBBPF_API int bpf_program__set_flags(struct bpf_program *prog, __u32 flags);
 871
 872/* Per-program log level and log buffer getters/setters.
 873 * See bpf_object_open_opts comments regarding log_level and log_buf
 874 * interactions.
 875 */
 876LIBBPF_API __u32 bpf_program__log_level(const struct bpf_program *prog);
 877LIBBPF_API int bpf_program__set_log_level(struct bpf_program *prog, __u32 log_level);
 878LIBBPF_API const char *bpf_program__log_buf(const struct bpf_program *prog, size_t *log_size);
 879LIBBPF_API int bpf_program__set_log_buf(struct bpf_program *prog, char *log_buf, size_t log_size);
 880
 881/**
 882 * @brief **bpf_program__set_attach_target()** sets BTF-based attach target
 883 * for supported BPF program types:
 884 *   - BTF-aware raw tracepoints (tp_btf);
 885 *   - fentry/fexit/fmod_ret;
 886 *   - lsm;
 887 *   - freplace.
 888 * @param prog BPF program to set the attach type for
 889 * @param type attach type to set the BPF map to have
 890 * @return error code; or 0 if no error occurred.
 891 */
 892LIBBPF_API int
 893bpf_program__set_attach_target(struct bpf_program *prog, int attach_prog_fd,
 894			       const char *attach_func_name);
 895
 896/**
 897 * @brief **bpf_object__find_map_by_name()** returns BPF map of
 898 * the given name, if it exists within the passed BPF object
 899 * @param obj BPF object
 900 * @param name name of the BPF map
 901 * @return BPF map instance, if such map exists within the BPF object;
 902 * or NULL otherwise.
 903 */
 904LIBBPF_API struct bpf_map *
 905bpf_object__find_map_by_name(const struct bpf_object *obj, const char *name);
 906
 907LIBBPF_API int
 908bpf_object__find_map_fd_by_name(const struct bpf_object *obj, const char *name);
 909
 910LIBBPF_API struct bpf_map *
 911bpf_object__next_map(const struct bpf_object *obj, const struct bpf_map *map);
 912
 913#define bpf_object__for_each_map(pos, obj)		\
 914	for ((pos) = bpf_object__next_map((obj), NULL);	\
 915	     (pos) != NULL;				\
 916	     (pos) = bpf_object__next_map((obj), (pos)))
 917#define bpf_map__for_each bpf_object__for_each_map
 918
 919LIBBPF_API struct bpf_map *
 920bpf_object__prev_map(const struct bpf_object *obj, const struct bpf_map *map);
 921
 922/**
 923 * @brief **bpf_map__set_autocreate()** sets whether libbpf has to auto-create
 924 * BPF map during BPF object load phase.
 925 * @param map the BPF map instance
 926 * @param autocreate whether to create BPF map during BPF object load
 927 * @return 0 on success; -EBUSY if BPF object was already loaded
 928 *
 929 * **bpf_map__set_autocreate()** allows to opt-out from libbpf auto-creating
 930 * BPF map. By default, libbpf will attempt to create every single BPF map
 931 * defined in BPF object file using BPF_MAP_CREATE command of bpf() syscall
 932 * and fill in map FD in BPF instructions.
 933 *
 934 * This API allows to opt-out of this process for specific map instance. This
 935 * can be useful if host kernel doesn't support such BPF map type or used
 936 * combination of flags and user application wants to avoid creating such
 937 * a map in the first place. User is still responsible to make sure that their
 938 * BPF-side code that expects to use such missing BPF map is recognized by BPF
 939 * verifier as dead code, otherwise BPF verifier will reject such BPF program.
 940 */
 941LIBBPF_API int bpf_map__set_autocreate(struct bpf_map *map, bool autocreate);
 942LIBBPF_API bool bpf_map__autocreate(const struct bpf_map *map);
 943
 944/**
 945 * @brief **bpf_map__fd()** gets the file descriptor of the passed
 946 * BPF map
 947 * @param map the BPF map instance
 948 * @return the file descriptor; or -EINVAL in case of an error
 949 */
 950LIBBPF_API int bpf_map__fd(const struct bpf_map *map);
 951LIBBPF_API int bpf_map__reuse_fd(struct bpf_map *map, int fd);
 952/* get map name */
 953LIBBPF_API const char *bpf_map__name(const struct bpf_map *map);
 954/* get/set map type */
 955LIBBPF_API enum bpf_map_type bpf_map__type(const struct bpf_map *map);
 956LIBBPF_API int bpf_map__set_type(struct bpf_map *map, enum bpf_map_type type);
 957/* get/set map size (max_entries) */
 958LIBBPF_API __u32 bpf_map__max_entries(const struct bpf_map *map);
 959LIBBPF_API int bpf_map__set_max_entries(struct bpf_map *map, __u32 max_entries);
 960/* get/set map flags */
 961LIBBPF_API __u32 bpf_map__map_flags(const struct bpf_map *map);
 962LIBBPF_API int bpf_map__set_map_flags(struct bpf_map *map, __u32 flags);
 963/* get/set map NUMA node */
 964LIBBPF_API __u32 bpf_map__numa_node(const struct bpf_map *map);
 965LIBBPF_API int bpf_map__set_numa_node(struct bpf_map *map, __u32 numa_node);
 966/* get/set map key size */
 967LIBBPF_API __u32 bpf_map__key_size(const struct bpf_map *map);
 968LIBBPF_API int bpf_map__set_key_size(struct bpf_map *map, __u32 size);
 969/* get map value size */
 970LIBBPF_API __u32 bpf_map__value_size(const struct bpf_map *map);
 971/**
 972 * @brief **bpf_map__set_value_size()** sets map value size.
 973 * @param map the BPF map instance
 974 * @return 0, on success; negative error, otherwise
 975 *
 976 * There is a special case for maps with associated memory-mapped regions, like
 977 * the global data section maps (bss, data, rodata). When this function is used
 978 * on such a map, the mapped region is resized. Afterward, an attempt is made to
 979 * adjust the corresponding BTF info. This attempt is best-effort and can only
 980 * succeed if the last variable of the data section map is an array. The array
 981 * BTF type is replaced by a new BTF array type with a different length.
 982 * Any previously existing pointers returned from bpf_map__initial_value() or
 983 * corresponding data section skeleton pointer must be reinitialized.
 984 */
 985LIBBPF_API int bpf_map__set_value_size(struct bpf_map *map, __u32 size);
 986/* get map key/value BTF type IDs */
 987LIBBPF_API __u32 bpf_map__btf_key_type_id(const struct bpf_map *map);
 988LIBBPF_API __u32 bpf_map__btf_value_type_id(const struct bpf_map *map);
 989/* get/set map if_index */
 990LIBBPF_API __u32 bpf_map__ifindex(const struct bpf_map *map);
 991LIBBPF_API int bpf_map__set_ifindex(struct bpf_map *map, __u32 ifindex);
 992/* get/set map map_extra flags */
 993LIBBPF_API __u64 bpf_map__map_extra(const struct bpf_map *map);
 994LIBBPF_API int bpf_map__set_map_extra(struct bpf_map *map, __u64 map_extra);
 995
 996LIBBPF_API int bpf_map__set_initial_value(struct bpf_map *map,
 997					  const void *data, size_t size);
 998LIBBPF_API void *bpf_map__initial_value(struct bpf_map *map, size_t *psize);
 999
1000/**
1001 * @brief **bpf_map__is_internal()** tells the caller whether or not the
1002 * passed map is a special map created by libbpf automatically for things like
1003 * global variables, __ksym externs, Kconfig values, etc
1004 * @param map the bpf_map
1005 * @return true, if the map is an internal map; false, otherwise
1006 */
1007LIBBPF_API bool bpf_map__is_internal(const struct bpf_map *map);
1008
1009/**
1010 * @brief **bpf_map__set_pin_path()** sets the path attribute that tells where the
1011 * BPF map should be pinned. This does not actually create the 'pin'.
1012 * @param map The bpf_map
1013 * @param path The path
1014 * @return 0, on success; negative error, otherwise
1015 */
1016LIBBPF_API int bpf_map__set_pin_path(struct bpf_map *map, const char *path);
1017
1018/**
1019 * @brief **bpf_map__pin_path()** gets the path attribute that tells where the
1020 * BPF map should be pinned.
1021 * @param map The bpf_map
1022 * @return The path string; which can be NULL
1023 */
1024LIBBPF_API const char *bpf_map__pin_path(const struct bpf_map *map);
1025
1026/**
1027 * @brief **bpf_map__is_pinned()** tells the caller whether or not the
1028 * passed map has been pinned via a 'pin' file.
1029 * @param map The bpf_map
1030 * @return true, if the map is pinned; false, otherwise
1031 */
1032LIBBPF_API bool bpf_map__is_pinned(const struct bpf_map *map);
1033
1034/**
1035 * @brief **bpf_map__pin()** creates a file that serves as a 'pin'
1036 * for the BPF map. This increments the reference count on the
1037 * BPF map which will keep the BPF map loaded even after the
1038 * userspace process which loaded it has exited.
1039 * @param map The bpf_map to pin
1040 * @param path A file path for the 'pin'
1041 * @return 0, on success; negative error, otherwise
1042 *
1043 * If `path` is NULL the maps `pin_path` attribute will be used. If this is
1044 * also NULL, an error will be returned and the map will not be pinned.
1045 */
1046LIBBPF_API int bpf_map__pin(struct bpf_map *map, const char *path);
1047
1048/**
1049 * @brief **bpf_map__unpin()** removes the file that serves as a
1050 * 'pin' for the BPF map.
1051 * @param map The bpf_map to unpin
1052 * @param path A file path for the 'pin'
1053 * @return 0, on success; negative error, otherwise
1054 *
1055 * The `path` parameter can be NULL, in which case the `pin_path`
1056 * map attribute is unpinned. If both the `path` parameter and
1057 * `pin_path` map attribute are set, they must be equal.
1058 */
1059LIBBPF_API int bpf_map__unpin(struct bpf_map *map, const char *path);
1060
1061LIBBPF_API int bpf_map__set_inner_map_fd(struct bpf_map *map, int fd);
1062LIBBPF_API struct bpf_map *bpf_map__inner_map(struct bpf_map *map);
1063
1064/**
1065 * @brief **bpf_map__lookup_elem()** allows to lookup BPF map value
1066 * corresponding to provided key.
1067 * @param map BPF map to lookup element in
1068 * @param key pointer to memory containing bytes of the key used for lookup
1069 * @param key_sz size in bytes of key data, needs to match BPF map definition's **key_size**
1070 * @param value pointer to memory in which looked up value will be stored
1071 * @param value_sz size in byte of value data memory; it has to match BPF map
1072 * definition's **value_size**. For per-CPU BPF maps value size has to be
1073 * a product of BPF map value size and number of possible CPUs in the system
1074 * (could be fetched with **libbpf_num_possible_cpus()**). Note also that for
1075 * per-CPU values value size has to be aligned up to closest 8 bytes for
1076 * alignment reasons, so expected size is: `round_up(value_size, 8)
1077 * * libbpf_num_possible_cpus()`.
1078 * @flags extra flags passed to kernel for this operation
1079 * @return 0, on success; negative error, otherwise
1080 *
1081 * **bpf_map__lookup_elem()** is high-level equivalent of
1082 * **bpf_map_lookup_elem()** API with added check for key and value size.
1083 */
1084LIBBPF_API int bpf_map__lookup_elem(const struct bpf_map *map,
1085				    const void *key, size_t key_sz,
1086				    void *value, size_t value_sz, __u64 flags);
1087
1088/**
1089 * @brief **bpf_map__update_elem()** allows to insert or update value in BPF
1090 * map that corresponds to provided key.
1091 * @param map BPF map to insert to or update element in
1092 * @param key pointer to memory containing bytes of the key
1093 * @param key_sz size in bytes of key data, needs to match BPF map definition's **key_size**
1094 * @param value pointer to memory containing bytes of the value
1095 * @param value_sz size in byte of value data memory; it has to match BPF map
1096 * definition's **value_size**. For per-CPU BPF maps value size has to be
1097 * a product of BPF map value size and number of possible CPUs in the system
1098 * (could be fetched with **libbpf_num_possible_cpus()**). Note also that for
1099 * per-CPU values value size has to be aligned up to closest 8 bytes for
1100 * alignment reasons, so expected size is: `round_up(value_size, 8)
1101 * * libbpf_num_possible_cpus()`.
1102 * @flags extra flags passed to kernel for this operation
1103 * @return 0, on success; negative error, otherwise
1104 *
1105 * **bpf_map__update_elem()** is high-level equivalent of
1106 * **bpf_map_update_elem()** API with added check for key and value size.
1107 */
1108LIBBPF_API int bpf_map__update_elem(const struct bpf_map *map,
1109				    const void *key, size_t key_sz,
1110				    const void *value, size_t value_sz, __u64 flags);
1111
1112/**
1113 * @brief **bpf_map__delete_elem()** allows to delete element in BPF map that
1114 * corresponds to provided key.
1115 * @param map BPF map to delete element from
1116 * @param key pointer to memory containing bytes of the key
1117 * @param key_sz size in bytes of key data, needs to match BPF map definition's **key_size**
1118 * @flags extra flags passed to kernel for this operation
1119 * @return 0, on success; negative error, otherwise
1120 *
1121 * **bpf_map__delete_elem()** is high-level equivalent of
1122 * **bpf_map_delete_elem()** API with added check for key size.
1123 */
1124LIBBPF_API int bpf_map__delete_elem(const struct bpf_map *map,
1125				    const void *key, size_t key_sz, __u64 flags);
1126
1127/**
1128 * @brief **bpf_map__lookup_and_delete_elem()** allows to lookup BPF map value
1129 * corresponding to provided key and atomically delete it afterwards.
1130 * @param map BPF map to lookup element in
1131 * @param key pointer to memory containing bytes of the key used for lookup
1132 * @param key_sz size in bytes of key data, needs to match BPF map definition's **key_size**
1133 * @param value pointer to memory in which looked up value will be stored
1134 * @param value_sz size in byte of value data memory; it has to match BPF map
1135 * definition's **value_size**. For per-CPU BPF maps value size has to be
1136 * a product of BPF map value size and number of possible CPUs in the system
1137 * (could be fetched with **libbpf_num_possible_cpus()**). Note also that for
1138 * per-CPU values value size has to be aligned up to closest 8 bytes for
1139 * alignment reasons, so expected size is: `round_up(value_size, 8)
1140 * * libbpf_num_possible_cpus()`.
1141 * @flags extra flags passed to kernel for this operation
1142 * @return 0, on success; negative error, otherwise
1143 *
1144 * **bpf_map__lookup_and_delete_elem()** is high-level equivalent of
1145 * **bpf_map_lookup_and_delete_elem()** API with added check for key and value size.
1146 */
1147LIBBPF_API int bpf_map__lookup_and_delete_elem(const struct bpf_map *map,
1148					       const void *key, size_t key_sz,
1149					       void *value, size_t value_sz, __u64 flags);
1150
1151/**
1152 * @brief **bpf_map__get_next_key()** allows to iterate BPF map keys by
1153 * fetching next key that follows current key.
1154 * @param map BPF map to fetch next key from
1155 * @param cur_key pointer to memory containing bytes of current key or NULL to
1156 * fetch the first key
1157 * @param next_key pointer to memory to write next key into
1158 * @param key_sz size in bytes of key data, needs to match BPF map definition's **key_size**
1159 * @return 0, on success; -ENOENT if **cur_key** is the last key in BPF map;
1160 * negative error, otherwise
1161 *
1162 * **bpf_map__get_next_key()** is high-level equivalent of
1163 * **bpf_map_get_next_key()** API with added check for key size.
1164 */
1165LIBBPF_API int bpf_map__get_next_key(const struct bpf_map *map,
1166				     const void *cur_key, void *next_key, size_t key_sz);
1167
1168struct bpf_xdp_set_link_opts {
1169	size_t sz;
1170	int old_fd;
1171	size_t :0;
1172};
1173#define bpf_xdp_set_link_opts__last_field old_fd
1174
1175struct bpf_xdp_attach_opts {
1176	size_t sz;
1177	int old_prog_fd;
1178	size_t :0;
1179};
1180#define bpf_xdp_attach_opts__last_field old_prog_fd
1181
1182struct bpf_xdp_query_opts {
1183	size_t sz;
1184	__u32 prog_id;		/* output */
1185	__u32 drv_prog_id;	/* output */
1186	__u32 hw_prog_id;	/* output */
1187	__u32 skb_prog_id;	/* output */
1188	__u8 attach_mode;	/* output */
1189	__u64 feature_flags;	/* output */
1190	__u32 xdp_zc_max_segs;	/* output */
1191	size_t :0;
1192};
1193#define bpf_xdp_query_opts__last_field xdp_zc_max_segs
1194
1195LIBBPF_API int bpf_xdp_attach(int ifindex, int prog_fd, __u32 flags,
1196			      const struct bpf_xdp_attach_opts *opts);
1197LIBBPF_API int bpf_xdp_detach(int ifindex, __u32 flags,
1198			      const struct bpf_xdp_attach_opts *opts);
1199LIBBPF_API int bpf_xdp_query(int ifindex, int flags, struct bpf_xdp_query_opts *opts);
1200LIBBPF_API int bpf_xdp_query_id(int ifindex, int flags, __u32 *prog_id);
1201
1202/* TC related API */
1203enum bpf_tc_attach_point {
1204	BPF_TC_INGRESS = 1 << 0,
1205	BPF_TC_EGRESS  = 1 << 1,
1206	BPF_TC_CUSTOM  = 1 << 2,
1207};
1208
1209#define BPF_TC_PARENT(a, b) 	\
1210	((((a) << 16) & 0xFFFF0000U) | ((b) & 0x0000FFFFU))
1211
1212enum bpf_tc_flags {
1213	BPF_TC_F_REPLACE = 1 << 0,
1214};
1215
1216struct bpf_tc_hook {
1217	size_t sz;
1218	int ifindex;
1219	enum bpf_tc_attach_point attach_point;
1220	__u32 parent;
1221	size_t :0;
1222};
1223#define bpf_tc_hook__last_field parent
1224
1225struct bpf_tc_opts {
1226	size_t sz;
1227	int prog_fd;
1228	__u32 flags;
1229	__u32 prog_id;
1230	__u32 handle;
1231	__u32 priority;
1232	size_t :0;
1233};
1234#define bpf_tc_opts__last_field priority
1235
1236LIBBPF_API int bpf_tc_hook_create(struct bpf_tc_hook *hook);
1237LIBBPF_API int bpf_tc_hook_destroy(struct bpf_tc_hook *hook);
1238LIBBPF_API int bpf_tc_attach(const struct bpf_tc_hook *hook,
1239			     struct bpf_tc_opts *opts);
1240LIBBPF_API int bpf_tc_detach(const struct bpf_tc_hook *hook,
1241			     const struct bpf_tc_opts *opts);
1242LIBBPF_API int bpf_tc_query(const struct bpf_tc_hook *hook,
1243			    struct bpf_tc_opts *opts);
1244
1245/* Ring buffer APIs */
1246struct ring_buffer;
1247struct ring;
1248struct user_ring_buffer;
1249
1250typedef int (*ring_buffer_sample_fn)(void *ctx, void *data, size_t size);
1251
1252struct ring_buffer_opts {
1253	size_t sz; /* size of this struct, for forward/backward compatibility */
1254};
1255
1256#define ring_buffer_opts__last_field sz
1257
1258LIBBPF_API struct ring_buffer *
1259ring_buffer__new(int map_fd, ring_buffer_sample_fn sample_cb, void *ctx,
1260		 const struct ring_buffer_opts *opts);
1261LIBBPF_API void ring_buffer__free(struct ring_buffer *rb);
1262LIBBPF_API int ring_buffer__add(struct ring_buffer *rb, int map_fd,
1263				ring_buffer_sample_fn sample_cb, void *ctx);
1264LIBBPF_API int ring_buffer__poll(struct ring_buffer *rb, int timeout_ms);
1265LIBBPF_API int ring_buffer__consume(struct ring_buffer *rb);
1266LIBBPF_API int ring_buffer__epoll_fd(const struct ring_buffer *rb);
1267
1268/**
1269 * @brief **ring_buffer__ring()** returns the ringbuffer object inside a given
1270 * ringbuffer manager representing a single BPF_MAP_TYPE_RINGBUF map instance.
1271 *
1272 * @param rb A ringbuffer manager object.
1273 * @param idx An index into the ringbuffers contained within the ringbuffer
1274 * manager object. The index is 0-based and corresponds to the order in which
1275 * ring_buffer__add was called.
1276 * @return A ringbuffer object on success; NULL and errno set if the index is
1277 * invalid.
1278 */
1279LIBBPF_API struct ring *ring_buffer__ring(struct ring_buffer *rb,
1280					  unsigned int idx);
1281
1282/**
1283 * @brief **ring__consumer_pos()** returns the current consumer position in the
1284 * given ringbuffer.
1285 *
1286 * @param r A ringbuffer object.
1287 * @return The current consumer position.
1288 */
1289LIBBPF_API unsigned long ring__consumer_pos(const struct ring *r);
1290
1291/**
1292 * @brief **ring__producer_pos()** returns the current producer position in the
1293 * given ringbuffer.
1294 *
1295 * @param r A ringbuffer object.
1296 * @return The current producer position.
1297 */
1298LIBBPF_API unsigned long ring__producer_pos(const struct ring *r);
1299
1300/**
1301 * @brief **ring__avail_data_size()** returns the number of bytes in the
1302 * ringbuffer not yet consumed. This has no locking associated with it, so it
1303 * can be inaccurate if operations are ongoing while this is called. However, it
1304 * should still show the correct trend over the long-term.
1305 *
1306 * @param r A ringbuffer object.
1307 * @return The number of bytes not yet consumed.
1308 */
1309LIBBPF_API size_t ring__avail_data_size(const struct ring *r);
1310
1311/**
1312 * @brief **ring__size()** returns the total size of the ringbuffer's map data
1313 * area (excluding special producer/consumer pages). Effectively this gives the
1314 * amount of usable bytes of data inside the ringbuffer.
1315 *
1316 * @param r A ringbuffer object.
1317 * @return The total size of the ringbuffer map data area.
1318 */
1319LIBBPF_API size_t ring__size(const struct ring *r);
1320
1321/**
1322 * @brief **ring__map_fd()** returns the file descriptor underlying the given
1323 * ringbuffer.
1324 *
1325 * @param r A ringbuffer object.
1326 * @return The underlying ringbuffer file descriptor
1327 */
1328LIBBPF_API int ring__map_fd(const struct ring *r);
1329
1330/**
1331 * @brief **ring__consume()** consumes available ringbuffer data without event
1332 * polling.
1333 *
1334 * @param r A ringbuffer object.
1335 * @return The number of records consumed (or INT_MAX, whichever is less), or
1336 * a negative number if any of the callbacks return an error.
1337 */
1338LIBBPF_API int ring__consume(struct ring *r);
1339
1340struct user_ring_buffer_opts {
1341	size_t sz; /* size of this struct, for forward/backward compatibility */
1342};
1343
1344#define user_ring_buffer_opts__last_field sz
1345
1346/**
1347 * @brief **user_ring_buffer__new()** creates a new instance of a user ring
1348 * buffer.
1349 *
1350 * @param map_fd A file descriptor to a BPF_MAP_TYPE_USER_RINGBUF map.
1351 * @param opts Options for how the ring buffer should be created.
1352 * @return A user ring buffer on success; NULL and errno being set on a
1353 * failure.
1354 */
1355LIBBPF_API struct user_ring_buffer *
1356user_ring_buffer__new(int map_fd, const struct user_ring_buffer_opts *opts);
1357
1358/**
1359 * @brief **user_ring_buffer__reserve()** reserves a pointer to a sample in the
1360 * user ring buffer.
1361 * @param rb A pointer to a user ring buffer.
1362 * @param size The size of the sample, in bytes.
1363 * @return A pointer to an 8-byte aligned reserved region of the user ring
1364 * buffer; NULL, and errno being set if a sample could not be reserved.
1365 *
1366 * This function is *not* thread safe, and callers must synchronize accessing
1367 * this function if there are multiple producers.  If a size is requested that
1368 * is larger than the size of the entire ring buffer, errno will be set to
1369 * E2BIG and NULL is returned. If the ring buffer could accommodate the size,
1370 * but currently does not have enough space, errno is set to ENOSPC and NULL is
1371 * returned.
1372 *
1373 * After initializing the sample, callers must invoke
1374 * **user_ring_buffer__submit()** to post the sample to the kernel. Otherwise,
1375 * the sample must be freed with **user_ring_buffer__discard()**.
1376 */
1377LIBBPF_API void *user_ring_buffer__reserve(struct user_ring_buffer *rb, __u32 size);
1378
1379/**
1380 * @brief **user_ring_buffer__reserve_blocking()** reserves a record in the
1381 * ring buffer, possibly blocking for up to @timeout_ms until a sample becomes
1382 * available.
1383 * @param rb The user ring buffer.
1384 * @param size The size of the sample, in bytes.
1385 * @param timeout_ms The amount of time, in milliseconds, for which the caller
1386 * should block when waiting for a sample. -1 causes the caller to block
1387 * indefinitely.
1388 * @return A pointer to an 8-byte aligned reserved region of the user ring
1389 * buffer; NULL, and errno being set if a sample could not be reserved.
1390 *
1391 * This function is *not* thread safe, and callers must synchronize
1392 * accessing this function if there are multiple producers
1393 *
1394 * If **timeout_ms** is -1, the function will block indefinitely until a sample
1395 * becomes available. Otherwise, **timeout_ms** must be non-negative, or errno
1396 * is set to EINVAL, and NULL is returned. If **timeout_ms** is 0, no blocking
1397 * will occur and the function will return immediately after attempting to
1398 * reserve a sample.
1399 *
1400 * If **size** is larger than the size of the entire ring buffer, errno is set
1401 * to E2BIG and NULL is returned. If the ring buffer could accommodate
1402 * **size**, but currently does not have enough space, the caller will block
1403 * until at most **timeout_ms** has elapsed. If insufficient space is available
1404 * at that time, errno is set to ENOSPC, and NULL is returned.
1405 *
1406 * The kernel guarantees that it will wake up this thread to check if
1407 * sufficient space is available in the ring buffer at least once per
1408 * invocation of the **bpf_ringbuf_drain()** helper function, provided that at
1409 * least one sample is consumed, and the BPF program did not invoke the
1410 * function with BPF_RB_NO_WAKEUP. A wakeup may occur sooner than that, but the
1411 * kernel does not guarantee this. If the helper function is invoked with
1412 * BPF_RB_FORCE_WAKEUP, a wakeup event will be sent even if no sample is
1413 * consumed.
1414 *
1415 * When a sample of size **size** is found within **timeout_ms**, a pointer to
1416 * the sample is returned. After initializing the sample, callers must invoke
1417 * **user_ring_buffer__submit()** to post the sample to the ring buffer.
1418 * Otherwise, the sample must be freed with **user_ring_buffer__discard()**.
1419 */
1420LIBBPF_API void *user_ring_buffer__reserve_blocking(struct user_ring_buffer *rb,
1421						    __u32 size,
1422						    int timeout_ms);
1423
1424/**
1425 * @brief **user_ring_buffer__submit()** submits a previously reserved sample
1426 * into the ring buffer.
1427 * @param rb The user ring buffer.
1428 * @param sample A reserved sample.
1429 *
1430 * It is not necessary to synchronize amongst multiple producers when invoking
1431 * this function.
1432 */
1433LIBBPF_API void user_ring_buffer__submit(struct user_ring_buffer *rb, void *sample);
1434
1435/**
1436 * @brief **user_ring_buffer__discard()** discards a previously reserved sample.
1437 * @param rb The user ring buffer.
1438 * @param sample A reserved sample.
1439 *
1440 * It is not necessary to synchronize amongst multiple producers when invoking
1441 * this function.
1442 */
1443LIBBPF_API void user_ring_buffer__discard(struct user_ring_buffer *rb, void *sample);
1444
1445/**
1446 * @brief **user_ring_buffer__free()** frees a ring buffer that was previously
1447 * created with **user_ring_buffer__new()**.
1448 * @param rb The user ring buffer being freed.
1449 */
1450LIBBPF_API void user_ring_buffer__free(struct user_ring_buffer *rb);
1451
1452/* Perf buffer APIs */
1453struct perf_buffer;
1454
1455typedef void (*perf_buffer_sample_fn)(void *ctx, int cpu,
1456				      void *data, __u32 size);
1457typedef void (*perf_buffer_lost_fn)(void *ctx, int cpu, __u64 cnt);
1458
1459/* common use perf buffer options */
1460struct perf_buffer_opts {
1461	size_t sz;
1462	__u32 sample_period;
1463	size_t :0;
1464};
1465#define perf_buffer_opts__last_field sample_period
1466
1467/**
1468 * @brief **perf_buffer__new()** creates BPF perfbuf manager for a specified
1469 * BPF_PERF_EVENT_ARRAY map
1470 * @param map_fd FD of BPF_PERF_EVENT_ARRAY BPF map that will be used by BPF
1471 * code to send data over to user-space
1472 * @param page_cnt number of memory pages allocated for each per-CPU buffer
1473 * @param sample_cb function called on each received data record
1474 * @param lost_cb function called when record loss has occurred
1475 * @param ctx user-provided extra context passed into *sample_cb* and *lost_cb*
1476 * @return a new instance of struct perf_buffer on success, NULL on error with
1477 * *errno* containing an error code
1478 */
1479LIBBPF_API struct perf_buffer *
1480perf_buffer__new(int map_fd, size_t page_cnt,
1481		 perf_buffer_sample_fn sample_cb, perf_buffer_lost_fn lost_cb, void *ctx,
1482		 const struct perf_buffer_opts *opts);
1483
1484enum bpf_perf_event_ret {
1485	LIBBPF_PERF_EVENT_DONE	= 0,
1486	LIBBPF_PERF_EVENT_ERROR	= -1,
1487	LIBBPF_PERF_EVENT_CONT	= -2,
1488};
1489
1490struct perf_event_header;
1491
1492typedef enum bpf_perf_event_ret
1493(*perf_buffer_event_fn)(void *ctx, int cpu, struct perf_event_header *event);
1494
1495/* raw perf buffer options, giving most power and control */
1496struct perf_buffer_raw_opts {
1497	size_t sz;
1498	long :0;
1499	long :0;
1500	/* if cpu_cnt == 0, open all on all possible CPUs (up to the number of
1501	 * max_entries of given PERF_EVENT_ARRAY map)
1502	 */
1503	int cpu_cnt;
1504	/* if cpu_cnt > 0, cpus is an array of CPUs to open ring buffers on */
1505	int *cpus;
1506	/* if cpu_cnt > 0, map_keys specify map keys to set per-CPU FDs for */
1507	int *map_keys;
1508};
1509#define perf_buffer_raw_opts__last_field map_keys
1510
1511struct perf_event_attr;
1512
1513LIBBPF_API struct perf_buffer *
1514perf_buffer__new_raw(int map_fd, size_t page_cnt, struct perf_event_attr *attr,
1515		     perf_buffer_event_fn event_cb, void *ctx,
1516		     const struct perf_buffer_raw_opts *opts);
1517
1518LIBBPF_API void perf_buffer__free(struct perf_buffer *pb);
1519LIBBPF_API int perf_buffer__epoll_fd(const struct perf_buffer *pb);
1520LIBBPF_API int perf_buffer__poll(struct perf_buffer *pb, int timeout_ms);
1521LIBBPF_API int perf_buffer__consume(struct perf_buffer *pb);
1522LIBBPF_API int perf_buffer__consume_buffer(struct perf_buffer *pb, size_t buf_idx);
1523LIBBPF_API size_t perf_buffer__buffer_cnt(const struct perf_buffer *pb);
1524LIBBPF_API int perf_buffer__buffer_fd(const struct perf_buffer *pb, size_t buf_idx);
1525/**
1526 * @brief **perf_buffer__buffer()** returns the per-cpu raw mmap()'ed underlying
1527 * memory region of the ring buffer.
1528 * This ring buffer can be used to implement a custom events consumer.
1529 * The ring buffer starts with the *struct perf_event_mmap_page*, which
1530 * holds the ring buffer managment fields, when accessing the header
1531 * structure it's important to be SMP aware.
1532 * You can refer to *perf_event_read_simple* for a simple example.
1533 * @param pb the perf buffer structure
1534 * @param buf_idx the buffer index to retreive
1535 * @param buf (out) gets the base pointer of the mmap()'ed memory
1536 * @param buf_size (out) gets the size of the mmap()'ed region
1537 * @return 0 on success, negative error code for failure
1538 */
1539LIBBPF_API int perf_buffer__buffer(struct perf_buffer *pb, int buf_idx, void **buf,
1540				   size_t *buf_size);
1541
1542struct bpf_prog_linfo;
1543struct bpf_prog_info;
1544
1545LIBBPF_API void bpf_prog_linfo__free(struct bpf_prog_linfo *prog_linfo);
1546LIBBPF_API struct bpf_prog_linfo *
1547bpf_prog_linfo__new(const struct bpf_prog_info *info);
1548LIBBPF_API const struct bpf_line_info *
1549bpf_prog_linfo__lfind_addr_func(const struct bpf_prog_linfo *prog_linfo,
1550				__u64 addr, __u32 func_idx, __u32 nr_skip);
1551LIBBPF_API const struct bpf_line_info *
1552bpf_prog_linfo__lfind(const struct bpf_prog_linfo *prog_linfo,
1553		      __u32 insn_off, __u32 nr_skip);
1554
1555/*
1556 * Probe for supported system features
1557 *
1558 * Note that running many of these probes in a short amount of time can cause
1559 * the kernel to reach the maximal size of lockable memory allowed for the
1560 * user, causing subsequent probes to fail. In this case, the caller may want
1561 * to adjust that limit with setrlimit().
1562 */
1563
1564/**
1565 * @brief **libbpf_probe_bpf_prog_type()** detects if host kernel supports
1566 * BPF programs of a given type.
1567 * @param prog_type BPF program type to detect kernel support for
1568 * @param opts reserved for future extensibility, should be NULL
1569 * @return 1, if given program type is supported; 0, if given program type is
1570 * not supported; negative error code if feature detection failed or can't be
1571 * performed
1572 *
1573 * Make sure the process has required set of CAP_* permissions (or runs as
1574 * root) when performing feature checking.
1575 */
1576LIBBPF_API int libbpf_probe_bpf_prog_type(enum bpf_prog_type prog_type, const void *opts);
1577/**
1578 * @brief **libbpf_probe_bpf_map_type()** detects if host kernel supports
1579 * BPF maps of a given type.
1580 * @param map_type BPF map type to detect kernel support for
1581 * @param opts reserved for future extensibility, should be NULL
1582 * @return 1, if given map type is supported; 0, if given map type is
1583 * not supported; negative error code if feature detection failed or can't be
1584 * performed
1585 *
1586 * Make sure the process has required set of CAP_* permissions (or runs as
1587 * root) when performing feature checking.
1588 */
1589LIBBPF_API int libbpf_probe_bpf_map_type(enum bpf_map_type map_type, const void *opts);
1590/**
1591 * @brief **libbpf_probe_bpf_helper()** detects if host kernel supports the
1592 * use of a given BPF helper from specified BPF program type.
1593 * @param prog_type BPF program type used to check the support of BPF helper
1594 * @param helper_id BPF helper ID (enum bpf_func_id) to check support for
1595 * @param opts reserved for future extensibility, should be NULL
1596 * @return 1, if given combination of program type and helper is supported; 0,
1597 * if the combination is not supported; negative error code if feature
1598 * detection for provided input arguments failed or can't be performed
1599 *
1600 * Make sure the process has required set of CAP_* permissions (or runs as
1601 * root) when performing feature checking.
1602 */
1603LIBBPF_API int libbpf_probe_bpf_helper(enum bpf_prog_type prog_type,
1604				       enum bpf_func_id helper_id, const void *opts);
1605
1606/**
1607 * @brief **libbpf_num_possible_cpus()** is a helper function to get the
1608 * number of possible CPUs that the host kernel supports and expects.
1609 * @return number of possible CPUs; or error code on failure
1610 *
1611 * Example usage:
1612 *
1613 *     int ncpus = libbpf_num_possible_cpus();
1614 *     if (ncpus < 0) {
1615 *          // error handling
1616 *     }
1617 *     long values[ncpus];
1618 *     bpf_map_lookup_elem(per_cpu_map_fd, key, values);
1619 */
1620LIBBPF_API int libbpf_num_possible_cpus(void);
1621
1622struct bpf_map_skeleton {
1623	const char *name;
1624	struct bpf_map **map;
1625	void **mmaped;
1626};
1627
1628struct bpf_prog_skeleton {
1629	const char *name;
1630	struct bpf_program **prog;
1631	struct bpf_link **link;
1632};
1633
1634struct bpf_object_skeleton {
1635	size_t sz; /* size of this struct, for forward/backward compatibility */
1636
1637	const char *name;
1638	const void *data;
1639	size_t data_sz;
1640
1641	struct bpf_object **obj;
1642
1643	int map_cnt;
1644	int map_skel_sz; /* sizeof(struct bpf_map_skeleton) */
1645	struct bpf_map_skeleton *maps;
1646
1647	int prog_cnt;
1648	int prog_skel_sz; /* sizeof(struct bpf_prog_skeleton) */
1649	struct bpf_prog_skeleton *progs;
1650};
1651
1652LIBBPF_API int
1653bpf_object__open_skeleton(struct bpf_object_skeleton *s,
1654			  const struct bpf_object_open_opts *opts);
1655LIBBPF_API int bpf_object__load_skeleton(struct bpf_object_skeleton *s);
1656LIBBPF_API int bpf_object__attach_skeleton(struct bpf_object_skeleton *s);
1657LIBBPF_API void bpf_object__detach_skeleton(struct bpf_object_skeleton *s);
1658LIBBPF_API void bpf_object__destroy_skeleton(struct bpf_object_skeleton *s);
1659
1660struct bpf_var_skeleton {
1661	const char *name;
1662	struct bpf_map **map;
1663	void **addr;
1664};
1665
1666struct bpf_object_subskeleton {
1667	size_t sz; /* size of this struct, for forward/backward compatibility */
1668
1669	const struct bpf_object *obj;
1670
1671	int map_cnt;
1672	int map_skel_sz; /* sizeof(struct bpf_map_skeleton) */
1673	struct bpf_map_skeleton *maps;
1674
1675	int prog_cnt;
1676	int prog_skel_sz; /* sizeof(struct bpf_prog_skeleton) */
1677	struct bpf_prog_skeleton *progs;
1678
1679	int var_cnt;
1680	int var_skel_sz; /* sizeof(struct bpf_var_skeleton) */
1681	struct bpf_var_skeleton *vars;
1682};
1683
1684LIBBPF_API int
1685bpf_object__open_subskeleton(struct bpf_object_subskeleton *s);
1686LIBBPF_API void
1687bpf_object__destroy_subskeleton(struct bpf_object_subskeleton *s);
1688
1689struct gen_loader_opts {
1690	size_t sz; /* size of this struct, for forward/backward compatibility */
1691	const char *data;
1692	const char *insns;
1693	__u32 data_sz;
1694	__u32 insns_sz;
1695};
1696
1697#define gen_loader_opts__last_field insns_sz
1698LIBBPF_API int bpf_object__gen_loader(struct bpf_object *obj,
1699				      struct gen_loader_opts *opts);
1700
1701enum libbpf_tristate {
1702	TRI_NO = 0,
1703	TRI_YES = 1,
1704	TRI_MODULE = 2,
1705};
1706
1707struct bpf_linker_opts {
1708	/* size of this struct, for forward/backward compatibility */
1709	size_t sz;
1710};
1711#define bpf_linker_opts__last_field sz
1712
1713struct bpf_linker_file_opts {
1714	/* size of this struct, for forward/backward compatibility */
1715	size_t sz;
1716};
1717#define bpf_linker_file_opts__last_field sz
1718
1719struct bpf_linker;
1720
1721LIBBPF_API struct bpf_linker *bpf_linker__new(const char *filename, struct bpf_linker_opts *opts);
1722LIBBPF_API int bpf_linker__add_file(struct bpf_linker *linker,
1723				    const char *filename,
1724				    const struct bpf_linker_file_opts *opts);
1725LIBBPF_API int bpf_linker__finalize(struct bpf_linker *linker);
1726LIBBPF_API void bpf_linker__free(struct bpf_linker *linker);
1727
1728/*
1729 * Custom handling of BPF program's SEC() definitions
1730 */
1731
1732struct bpf_prog_load_opts; /* defined in bpf.h */
1733
1734/* Called during bpf_object__open() for each recognized BPF program. Callback
1735 * can use various bpf_program__set_*() setters to adjust whatever properties
1736 * are necessary.
1737 */
1738typedef int (*libbpf_prog_setup_fn_t)(struct bpf_program *prog, long cookie);
1739
1740/* Called right before libbpf performs bpf_prog_load() to load BPF program
1741 * into the kernel. Callback can adjust opts as necessary.
1742 */
1743typedef int (*libbpf_prog_prepare_load_fn_t)(struct bpf_program *prog,
1744					     struct bpf_prog_load_opts *opts, long cookie);
1745
1746/* Called during skeleton attach or through bpf_program__attach(). If
1747 * auto-attach is not supported, callback should return 0 and set link to
1748 * NULL (it's not considered an error during skeleton attach, but it will be
1749 * an error for bpf_program__attach() calls). On error, error should be
1750 * returned directly and link set to NULL. On success, return 0 and set link
1751 * to a valid struct bpf_link.
1752 */
1753typedef int (*libbpf_prog_attach_fn_t)(const struct bpf_program *prog, long cookie,
1754				       struct bpf_link **link);
1755
1756struct libbpf_prog_handler_opts {
1757	/* size of this struct, for forward/backward compatibility */
1758	size_t sz;
1759	/* User-provided value that is passed to prog_setup_fn,
1760	 * prog_prepare_load_fn, and prog_attach_fn callbacks. Allows user to
1761	 * register one set of callbacks for multiple SEC() definitions and
1762	 * still be able to distinguish them, if necessary. For example,
1763	 * libbpf itself is using this to pass necessary flags (e.g.,
1764	 * sleepable flag) to a common internal SEC() handler.
1765	 */
1766	long cookie;
1767	/* BPF program initialization callback (see libbpf_prog_setup_fn_t).
1768	 * Callback is optional, pass NULL if it's not necessary.
1769	 */
1770	libbpf_prog_setup_fn_t prog_setup_fn;
1771	/* BPF program loading callback (see libbpf_prog_prepare_load_fn_t).
1772	 * Callback is optional, pass NULL if it's not necessary.
1773	 */
1774	libbpf_prog_prepare_load_fn_t prog_prepare_load_fn;
1775	/* BPF program attach callback (see libbpf_prog_attach_fn_t).
1776	 * Callback is optional, pass NULL if it's not necessary.
1777	 */
1778	libbpf_prog_attach_fn_t prog_attach_fn;
1779};
1780#define libbpf_prog_handler_opts__last_field prog_attach_fn
1781
1782/**
1783 * @brief **libbpf_register_prog_handler()** registers a custom BPF program
1784 * SEC() handler.
1785 * @param sec section prefix for which custom handler is registered
1786 * @param prog_type BPF program type associated with specified section
1787 * @param exp_attach_type Expected BPF attach type associated with specified section
1788 * @param opts optional cookie, callbacks, and other extra options
1789 * @return Non-negative handler ID is returned on success. This handler ID has
1790 * to be passed to *libbpf_unregister_prog_handler()* to unregister such
1791 * custom handler. Negative error code is returned on error.
1792 *
1793 * *sec* defines which SEC() definitions are handled by this custom handler
1794 * registration. *sec* can have few different forms:
1795 *   - if *sec* is just a plain string (e.g., "abc"), it will match only
1796 *   SEC("abc"). If BPF program specifies SEC("abc/whatever") it will result
1797 *   in an error;
1798 *   - if *sec* is of the form "abc/", proper SEC() form is
1799 *   SEC("abc/something"), where acceptable "something" should be checked by
1800 *   *prog_init_fn* callback, if there are additional restrictions;
1801 *   - if *sec* is of the form "abc+", it will successfully match both
1802 *   SEC("abc") and SEC("abc/whatever") forms;
1803 *   - if *sec* is NULL, custom handler is registered for any BPF program that
1804 *   doesn't match any of the registered (custom or libbpf's own) SEC()
1805 *   handlers. There could be only one such generic custom handler registered
1806 *   at any given time.
1807 *
1808 * All custom handlers (except the one with *sec* == NULL) are processed
1809 * before libbpf's own SEC() handlers. It is allowed to "override" libbpf's
1810 * SEC() handlers by registering custom ones for the same section prefix
1811 * (i.e., it's possible to have custom SEC("perf_event/LLC-load-misses")
1812 * handler).
1813 *
1814 * Note, like much of global libbpf APIs (e.g., libbpf_set_print(),
1815 * libbpf_set_strict_mode(), etc)) these APIs are not thread-safe. User needs
1816 * to ensure synchronization if there is a risk of running this API from
1817 * multiple threads simultaneously.
1818 */
1819LIBBPF_API int libbpf_register_prog_handler(const char *sec,
1820					    enum bpf_prog_type prog_type,
1821					    enum bpf_attach_type exp_attach_type,
1822					    const struct libbpf_prog_handler_opts *opts);
1823/**
1824 * @brief *libbpf_unregister_prog_handler()* unregisters previously registered
1825 * custom BPF program SEC() handler.
1826 * @param handler_id handler ID returned by *libbpf_register_prog_handler()*
1827 * after successful registration
1828 * @return 0 on success, negative error code if handler isn't found
1829 *
1830 * Note, like much of global libbpf APIs (e.g., libbpf_set_print(),
1831 * libbpf_set_strict_mode(), etc)) these APIs are not thread-safe. User needs
1832 * to ensure synchronization if there is a risk of running this API from
1833 * multiple threads simultaneously.
1834 */
1835LIBBPF_API int libbpf_unregister_prog_handler(int handler_id);
1836
1837#ifdef __cplusplus
1838} /* extern "C" */
1839#endif
1840
1841#endif /* __LIBBPF_LIBBPF_H */