tools: bpf: improve comments in libbpf.h

int libbpf_strerror(int err, char *buf, size_t size);

int libbpf_strerror(int err, char *buf, size_t size);

/*

/*

 * In include/linux/compiler-gcc.h, __printf is defined. However

 * __printf is defined in include/linux/compiler-gcc.h. However,

 * it should be better if libbpf.h doesn't depend on Linux header file.

 * it would be better if libbpf.h didn't depend on Linux header files.

 * So instead of __printf, here we use gcc attribute directly.

 * So instead of __printf, here we use gcc attribute directly.

 */

 */

typedef int (*libbpf_print_fn_t)(const char *, ...)

typedef int (*libbpf_print_fn_t)(const char *, ...)

			 bpf_object_clear_priv_t clear_priv);

			 bpf_object_clear_priv_t clear_priv);

void *bpf_object__priv(struct bpf_object *prog);

void *bpf_object__priv(struct bpf_object *prog);

/* Accessors of bpf_program. */

/* Accessors of bpf_program */

struct bpf_program;

struct bpf_program;

struct bpf_program *bpf_program__next(struct bpf_program *prog,

struct bpf_program *bpf_program__next(struct bpf_program *prog,

				      struct bpf_object *obj);

				      struct bpf_object *obj);

/*

/*

 * Libbpf allows callers to adjust BPF programs before being loaded

 * Libbpf allows callers to adjust BPF programs before being loaded

 * into kernel. One program in an object file can be transform into

 * into kernel. One program in an object file can be transformed into

 * multiple variants to be attached to different code.

 * multiple variants to be attached to different hooks.

 *

 *

 * bpf_program_prep_t, bpf_program__set_prep and bpf_program__nth_fd

 * bpf_program_prep_t, bpf_program__set_prep and bpf_program__nth_fd

 * are APIs for this propose.

 * form an API for this purpose.

 *

 *

 * - bpf_program_prep_t:

 * - bpf_program_prep_t:

 *   It defines 'preprocessor', which is a caller defined function

 *   Defines a 'preprocessor', which is a caller defined function

 *   passed to libbpf through bpf_program__set_prep(), and will be

 *   passed to libbpf through bpf_program__set_prep(), and will be

 *   called before program is loaded. The processor should adjust

 *   called before program is loaded. The processor should adjust

 *   the program one time for each instances according to the number

 *   the program one time for each instance according to the instance id

 *   passed to it.

 *   passed to it.

 *

 *

 * - bpf_program__set_prep:

 * - bpf_program__set_prep:

 *   Attachs a preprocessor to a BPF program. The number of instances

 *   Attaches a preprocessor to a BPF program. The number of instances

 *   whould be created is also passed through this function.

 *   that should be created is also passed through this function.

 *

 *

 * - bpf_program__nth_fd:

 * - bpf_program__nth_fd:

 *   After the program is loaded, get resuling fds from bpf program for

 *   After the program is loaded, get resulting FD of a given instance

 *   each instances.

 *   of the BPF program.

 *

 *

 * If bpf_program__set_prep() is not used, the program whould be loaded

 * If bpf_program__set_prep() is not used, the program would be loaded

 * without adjustment during bpf_object__load(). The program has only

 * without adjustment during bpf_object__load(). The program has only

 * one instance. In this case bpf_program__fd(prog) is equal to

 * one instance. In this case bpf_program__fd(prog) is equal to

 * bpf_program__nth_fd(prog, 0).

 * bpf_program__nth_fd(prog, 0).

	struct bpf_insn *new_insn_ptr;

	struct bpf_insn *new_insn_ptr;

	int new_insn_cnt;

	int new_insn_cnt;

	/* If not NULL, result fd is set to it */

	/* If not NULL, result FD is written to it. */

	int *pfd;

	int *pfd;

};

};

 *

 *

 * Return value:

 * Return value:

 *  - Zero:	pre-processing success.

 *  - Zero:	pre-processing success.

 *  - Non-zero: pre-processing, stop loading.

 *  - Non-zero:	pre-processing error, stop loading.

 */

 */

typedef int (*bpf_program_prep_t)(struct bpf_program *prog, int n,

typedef int (*bpf_program_prep_t)(struct bpf_program *prog, int n,

				  struct bpf_insn *insns, int insns_cnt,

				  struct bpf_insn *insns, int insns_cnt,

int bpf_program__nth_fd(struct bpf_program *prog, int n);

int bpf_program__nth_fd(struct bpf_program *prog, int n);

/*

/*

 * Adjust type of bpf program. Default is kprobe.

 * Adjust type of BPF program. Default is kprobe.

 */

 */

int bpf_program__set_socket_filter(struct bpf_program *prog);

int bpf_program__set_socket_filter(struct bpf_program *prog);

int bpf_program__set_tracepoint(struct bpf_program *prog);

int bpf_program__set_tracepoint(struct bpf_program *prog);

bool bpf_program__is_perf_event(struct bpf_program *prog);

bool bpf_program__is_perf_event(struct bpf_program *prog);

/*

/*

 * We don't need __attribute__((packed)) now since it is

 * No need for __attribute__((packed)), all members of 'bpf_map_def'

 * unnecessary for 'bpf_map_def' because they are all aligned.

 * are all aligned.  In addition, using __attribute__((packed))

 * In addition, using it will trigger -Wpacked warning message,

 * would trigger a -Wpacked warning message, and lead to an error

 * and will be treated as an error due to -Werror.

 * if -Werror is set.

 */

 */

struct bpf_map_def {

struct bpf_map_def {

	unsigned int type;

	unsigned int type;

};

};

/*

/*

 * There is another 'struct bpf_map' in include/linux/map.h. However,

 * The 'struct bpf_map' in include/linux/bpf.h is internal to the kernel,

 * it is not a uapi header so no need to consider name clash.

 * so no need to worry about a name clash.

 */

 */

struct bpf_map;

struct bpf_map;

struct bpf_map *

struct bpf_map *

/*

/*

 * Get bpf_map through the offset of corresponding struct bpf_map_def

 * Get bpf_map through the offset of corresponding struct bpf_map_def

 * in the bpf object file.

 * in the BPF object file.

 */

 */

struct bpf_map *

struct bpf_map *

bpf_object__find_map_by_offset(struct bpf_object *obj, size_t offset);

bpf_object__find_map_by_offset(struct bpf_object *obj, size_t offset);