xref: /aosp_15_r20/external/libtraceevent/Documentation/libtraceevent.txt (revision 436bf2bcd5202612ffffe471bbcc1f277cc8d28e)

libtraceevent(3)
================

NAME
----
libtraceevent - Linux kernel trace event library

SYNOPSIS
--------
[verse]
--
*#include <event-parse.h>*

Management of tep handler data structure and access of its members:
	struct tep_handle pass:[*]*tep_alloc*(void);
	void *tep_free*(struct tep_handle pass:[*]_tep_);
	void *tep_ref*(struct tep_handle pass:[*]_tep_);
	void *tep_unref*(struct tep_handle pass:[*]_tep_);
	int *tep_get_ref*(struct tep_handle pass:[*]_tep_);
	void *tep_set_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_);
	void *tep_clear_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flag_);
	bool *tep_test_flag*(struct tep_handle pass:[*]_tep_, enum tep_flag _flags_);
	int *tep_get_cpus*(struct tep_handle pass:[*]_tep_);
	void *tep_set_cpus*(struct tep_handle pass:[*]_tep_, int _cpus_);
	int *tep_get_long_size*(strucqt tep_handle pass:[*]_tep_);
	void *tep_set_long_size*(struct tep_handle pass:[*]_tep_, int _long_size_);
	int *tep_get_page_size*(struct tep_handle pass:[*]_tep_);
	void *tep_set_page_size*(struct tep_handle pass:[*]_tep_, int _page_size_);
	int *tep_get_sub_buffer_size*(struct tep_handle pass:[*]_tep_);
	int *tep_get_sub_buffer_data_size*(struct tep_handle pass:[*]_tep_);
	int *tep_get_sub_buffer_commit_offset*(struct tep_handle pass:[*]_tep_);
	int *tep_get_header_page_size*(struct tep_handle pass:[*]_tep_);
	int *tep_get_header_timestamp_size*(struct tep_handle pass:[*]_tep_);
	bool *tep_is_old_format*(struct tep_handle pass:[*]_tep_);
	int *tep_strerror*(struct tep_handle pass:[*]_tep_, enum tep_errno _errnum_, char pass:[*]_buf_, size_t _buflen_);
	struct kbuffer pass:[*]*tep_kbuffer*(struct tep_handle pass:[*]_tep_);

Register / unregister APIs:
	int *tep_register_function*(struct tep_handle pass:[*]_tep_, char pass:[*]_name_, unsigned long long _addr_, char pass:[*]_mod_);
	int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_);
	int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_);
	int *tep_register_print_string*(struct tep_handle pass:[*]_tep_, const char pass:[*]_fmt_, unsigned long long _addr_);
	int *tep_register_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, enum tep_func_arg_type _ret_type_, char pass:[*]_name_, _..._);
	int *tep_unregister_print_function*(struct tep_handle pass:[*]_tep_, tep_func_handler _func_, char pass:[*]_name_);
	int *tep_get_function_count*(struct tep_handle *_tep_);

Trace printk parsing:
	void *tep_print_printk*(struct tep_handle pass:[*]tep);
	void *tep_print_funcs*(struct tep_handle pass:[*]tep);
	void *tep_set_test_filters*(struct tep_handle pass:[*]tep, int test_filters);
	void *tep_plugin_print_options*(struct trace_seq pass:[*]s);
	int *tep_plugin_add_option*(const char pass:[*]_name_, const char pass:[*]_val_);

Meta data parsing:
	int *tep_parse_saved_cmdlines*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_);
	int *tep_parse_printk_formats*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_);
	int *tep_parse_kallsyms*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_);

Plugins management:
	struct tep_plugin_list pass:[*]*tep_load_plugins*(struct tep_handle pass:[*]_tep_);
	void *tep_unload_plugins*(struct tep_plugin_list pass:[*]_plugin_list_, struct tep_handle pass:[*]_tep_);
	char pass:[*]pass:[*]*tep_plugin_list_options*(void);
	void *tep_plugin_free_options_list*(char pass:[*]pass:[*]_list_);
	int *tep_plugin_add_options*(const char pass:[*]_name_, struct tep_plugin_option pass:[*]_options_);
	void *tep_plugin_remove_options*(struct tep_plugin_option pass:[*]_options_);
	void *tep_print_plugins*(struct trace_seq pass:[*]_s_, const char pass:[*]_prefix_, const char pass:[*]_suffix_, const struct tep_plugin_list pass:[*]_list_);
	void *tep_load_plugins_hook*(struct tep_handle pass:[*]_tep_, const char pass:[*]_suffix_,
			   void (pass:[*]_load_plugin_)(struct tep_handle pass:[*]tep,
					       const char pass:[*]path,
					       const char pass:[*]name,
					       void pass:[*]data),
			   void pass:[*]_data_);
	int *tep_add_plugin_path*(struct tep_handle pass:[*]tep, char pass:[*]path,
			  enum tep_plugin_load_priority prio);

Event related APIs:
	struct tep_event pass:[*]*tep_get_event*(struct tep_handle pass:[*]_tep_, int _index_);
	struct tep_event pass:[*]*tep_get_first_event*(struct tep_handle pass:[*]_tep_);
	int *tep_get_events_count*(struct tep_handle pass:[*]_tep_);
	struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
	struct tep_event pass:[*]pass:[*]*tep_list_events_copy*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
	void *tep_print_event*(struct tep_handle pass:[*]_tep_, struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, const char pass:[*]_fmt_, _..._);

Event finding:
	struct tep_event pass:[*]*tep_find_event*(struct tep_handle pass:[*]_tep_, int _id_);
	struct tep_event pass:[*]*tep_find_event_by_name*(struct tep_handle pass:[*]_tep_, const char pass:[*]_sys_, const char pass:[*]_name_);
	struct tep_event pass:[*]*tep_find_event_by_record*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_record_);
	bool *tep_record_is_event*(struct tep_record pass:[*]record, struct tep_event pass:[*]event);

Parsing of event files:
	int *tep_parse_header_page*(struct tep_handle pass:[*]_tep_, char pass:[*]_buf_, unsigned long _size_, int _long_size_);
	enum tep_errno *tep_parse_event*(struct tep_handle pass:[*]_tep_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_);
	enum tep_errno *tep_parse_format*(struct tep_handle pass:[*]_tep_, struct tep_event pass:[*]pass:[*]_eventp_, const char pass:[*]_buf_, unsigned long _size_, const char pass:[*]_sys_);

APIs related to fields from event's format files:
	struct tep_format_field pass:[*]pass:[*]*tep_event_common_fields*(struct tep_event pass:[*]_event_);
	struct tep_format_field pass:[*]pass:[*]*tep_event_fields*(struct tep_event pass:[*]_event_);
	void pass:[*]*tep_get_field_raw*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int pass:[*]_len_, int _err_);
	int *tep_get_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
	int *tep_get_common_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
	int *tep_get_any_field_val*(struct trace_seq pass:[*]_s_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, unsigned long long pass:[*]_val_, int _err_);
	int *tep_read_number_field*(struct tep_format_field pass:[*]_field_, const void pass:[*]_data_, unsigned long long pass:[*]_value_);

Event fields printing:
	void *tep_print_field_content*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int size, struct tep_format_field pass:[*]_field_);
	void *tep_print_fields*(struct trace_seq pass:[*]_s_, void pass:[*]_data_, int _size_, struct tep_event pass:[*]_event_);
	int *tep_print_num_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
	int *tep_print_func_field*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, struct tep_event pass:[*]_event_, const char pass:[*]_name_, struct tep_record pass:[*]_record_, int _err_);
	void *tep_record_print_fields*(struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, struct tep_event pass:[*]_event_);
	void *tep_record_print_selected_fields*(struct trace_seq pass:[*]_s_, struct tep_record pass:[*]_record_, struct tep_event pass:[*]_event_, int _select_mask_);

Event fields finding:
	struct tep_format_field pass:[*]*tep_find_common_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);
	struct tep_format_field pass:[*]*tep_find_field*(struct tep_event_ormat pass:[*]_event_, const char pass:[*]_name_);
	struct tep_format_field pass:[*]*tep_find_any_field*(struct tep_event pass:[*]_event_, const char pass:[*]_name_);

Functions resolver:
	int *tep_set_function_resolver*(struct tep_handle pass:[*]_tep_, tep_func_resolver_t pass:[*]_func_, void pass:[*]_priv_);
	void *tep_reset_function_resolver*(struct tep_handle pass:[*]_tep_);
	const char pass:[*]*tep_find_function*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
	unsigned long long *tep_find_function_address*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_);
	int *tep_find_function_info*(struct tep_handle pass:[*]_tep_, unsigned long long _addr_, const char pass:[**]_name_,
			   unsigned long long pass:[*]_start_, unsigned long pass:[*]_size_);

Filter management:
	struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
	enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_);
	enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_);
	int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_);
	int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
	void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
	void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
	char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
	int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
	int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_);
	int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_);

Parsing various data from the records:
	int *tep_data_type*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
	int *tep_data_pid*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
	int *tep_data_preempt_count*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);
	int *tep_data_flags*(struct tep_handle pass:[*]_tep_, struct tep_record pass:[*]_rec_);

Command and task related APIs:
	const char pass:[*]*tep_data_comm_from_pid*(struct tep_handle pass:[*]_tep_, int _pid_);
	struct cmdline pass:[*]*tep_data_pid_from_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, struct cmdline pass:[*]_next_);
	int *tep_register_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);
	int *tep_override_comm*(struct tep_handle pass:[*]_tep_, const char pass:[*]_comm_, int _pid_);
	bool *tep_is_pid_registered*(struct tep_handle pass:[*]_tep_, int _pid_);
	int *tep_cmdline_pid*(struct tep_handle pass:[*]_tep_, struct cmdline pass:[*]_cmdline_);

Endian related APIs:
	int *tep_is_bigendian*(void);
	unsigned long long *tep_read_number*(struct tep_handle pass:[*]_tep_, const void pass:[*]_ptr_, int _size_);
	bool *tep_is_file_bigendian*(struct tep_handle pass:[*]_tep_);
	void *tep_set_file_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);
	bool *tep_is_local_bigendian*(struct tep_handle pass:[*]_tep_);
	void *tep_set_local_bigendian*(struct tep_handle pass:[*]_tep_, enum tep_endian _endian_);

Control library logs:
	int *tep_set_loglevel*(enum tep_loglevel _level_);

KVM plugin calllbacks: (Defined by the application and complied with -rdynamic)
	const char pass:[*]*tep_plugin_kvm_get_func*(struct tep_event pass:[*]event,
				    struct tep_record pass:[*]record,
				    unsigned long long pass:[*]paddr);
	void *tep_plugin_kvm_put_func*(const char pass:[*]func);

Trace sequences:
*#include <trace-seq.h>*
	void *trace_seq_init*(struct trace_seq pass:[*]_s_);
	void *trace_seq_reset*(struct trace_seq pass:[*]_s_);
	void *trace_seq_destroy*(struct trace_seq pass:[*]_s_);
	int *trace_seq_printf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, ...);
	int *trace_seq_vprintf*(struct trace_seq pass:[*]_s_, const char pass:[*]_fmt_, va_list _args_);
	int *trace_seq_puts*(struct trace_seq pass:[*]_s_, const char pass:[*]_str_);
	int *trace_seq_putc*(struct trace_seq pass:[*]_s_, unsigned char _c_);
	void *trace_seq_terminate*(struct trace_seq pass:[*]_s_);
	int *trace_seq_do_fprintf*(struct trace_seq pass:[*]_s_, FILE pass:[*]_fp_);
	int *trace_seq_do_printf*(struct trace_seq pass:[*]_s_);

kbuffer parsing:
#include <kbuffer.h>
	struct kbuffer pass:[*]*kbuffer_alloc*(enum kbuffer_long_size _size_, enum kbuffer_endian _endian_);
	struct kbuffer pass:[*]*kbuffer_dup*(struct kbuffer pass:[*]_kbuf_);
	void *kbuffer_free*(struct kbuffer pass:[*]_kbuf_);
	int *kbuffer_load_subbuffer*(struct kbuffer pass:[*]_kbuf_, void pass:[*]_subbuffer_);
	int *kbuffer_subbuffer_size*(struct kbuffer pass:[*]_kbuf);
	void pass:[*]*kbuffer_subbuffer*(struct kbuffer pass:[*]_kbuf);
	int *kbuffer_refresh*(struct kbuffer pass:[*]_kbuf_);
	int *kbuffer_start_of_data*(struct kbuffer pass:[*]_kbuf_);
	unsigned long long *kbuffer_timestamp*(struct kbuffer pass:[*]_kbuf_);
	unsigned long long *kbuffer_subbuf_timestamp*(struct kbuffer pass:[*]_kbuf_, void pass:[*]_subbuf_);
	void pass:[*]*kbuffer_read_event*(struct kbuffer pass:[*]_kbuf_, unsigned long long pass:[*]_ts_);
	void pass:[*]*kbuffer_next_event*(struct kbuffer pass:[*]_kbuf_, unsigned long long pass:[*]_ts_);
	void pass:[*]*kbuffer_read_at_offset*(struct kbuffer pass:[*]_kbuf_, int _offset_, unsigned long long pass:[*]_ts_);
	int *kbuffer_missed_events*(struct kbuffer pass:[*]_kbuf_);
	int *kbuffer_event_size*(struct kbuffer pass:[*]_kbuf_);
	int *kbuffer_curr_size*(struct kbuffer pass:[*]_kbuf_);
	int *kbuffer_curr_offset*(struct kbuffer pass:[*]_kbuf_);
	int *kbuffer_curr_index*(struct kbuffer pass:[*]_kbuf_);
	int *kbuffer_read_buffer*(struct kbuffer pass:[*]_kbuf_, void pass:[*]_buffer_, int _start_, int _len_);
--

DESCRIPTION
-----------
The libtraceevent(3) library provides APIs to access kernel tracepoint events,
located in the tracefs file system under the events directory.

ENVIRONMENT
-----------
[verse]
--
TRACEEVENT_PLUGIN_DIR
	Additional plugin directory. All shared object files, located in this directory will be loaded as traceevent plugins.
--

FILES
-----
[verse]
--
*event-parse.h*
	Header file to include in order to have access to the library APIs.
*trace-seq.h*
	Header file to include in order to have access to trace sequences related APIs.
	Trace sequences are used to allow a function to call several other functions
	to create a string of data to use.
*-ltraceevent*
	Linker switch to add when building a program that uses the library.
--

SEE ALSO
--------
*trace-cmd*(1)

AUTHOR
------
[verse]
--
*Steven Rostedt* <[email protected]>, author of *libtraceevent*.
*Tzvetomir Stoyanov* <[email protected]>, author of this man page.
--
REPORTING BUGS
--------------
Report bugs to  <[email protected]>

LICENSE
-------
libtraceevent is Free Software licensed under the GNU LGPL 2.1

RESOURCES
---------
https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/