cachepc-linux

Fork of AMDESE/linux with modifications for CachePC side-channel attack
git clone https://git.sinitax.com/sinitax/cachepc-linux
Log | Files | Refs | README | LICENSE | sfeed.txt

libtraceevent-filter.txt (6720B)


      1libtraceevent(3)
      2================
      3
      4NAME
      5----
      6tep_filter_alloc, tep_filter_free, tep_filter_reset, tep_filter_make_string,
      7tep_filter_copy, tep_filter_compare, tep_filter_match, tep_event_filtered,
      8tep_filter_remove_event, tep_filter_strerror, tep_filter_add_filter_str -
      9Event filter related APIs.
     10
     11SYNOPSIS
     12--------
     13[verse]
     14--
     15*#include <event-parse.h>*
     16
     17struct tep_event_filter pass:[*]*tep_filter_alloc*(struct tep_handle pass:[*]_tep_);
     18void *tep_filter_free*(struct tep_event_filter pass:[*]_filter_);
     19void *tep_filter_reset*(struct tep_event_filter pass:[*]_filter_);
     20enum tep_errno *tep_filter_add_filter_str*(struct tep_event_filter pass:[*]_filter_, const char pass:[*]_filter_str_);
     21int *tep_event_filtered*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
     22int *tep_filter_remove_event*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
     23enum tep_errno *tep_filter_match*(struct tep_event_filter pass:[*]_filter_, struct tep_record pass:[*]_record_);
     24int *tep_filter_copy*(struct tep_event_filter pass:[*]_dest_, struct tep_event_filter pass:[*]_source_);
     25int *tep_filter_compare*(struct tep_event_filter pass:[*]_filter1_, struct tep_event_filter pass:[*]_filter2_);
     26char pass:[*]*tep_filter_make_string*(struct tep_event_filter pass:[*]_filter_, int _event_id_);
     27int *tep_filter_strerror*(struct tep_event_filter pass:[*]_filter_, enum tep_errno _err_, char pass:[*]buf, size_t _buflen_);
     28--
     29
     30DESCRIPTION
     31-----------
     32Filters can be attached to traced events. They can be used to filter out various
     33events when outputting them. Each event can be filtered based on its parameters,
     34described in the event's format file. This set of functions can be used to
     35create, delete, modify and attach event filters.
     36
     37The _tep_filter_alloc()_ function creates a new event filter. The _tep_ argument
     38is the trace event parser context.
     39
     40The _tep_filter_free()_ function frees an event filter and all resources that it
     41had used.
     42
     43The _tep_filter_reset()_ function removes all rules from an event filter and
     44resets it.
     45
     46The _tep_filter_add_filter_str()_ function adds a new rule to the _filter_. The
     47_filter_str_ argument is the filter string, that contains the rule.
     48
     49The _tep_event_filtered()_ function checks if the event with _event_id_ has
     50_filter_.
     51
     52The _tep_filter_remove_event()_ function removes a _filter_ for an event with
     53_event_id_.
     54
     55The _tep_filter_match()_ function tests if a _record_ matches given _filter_.
     56
     57The _tep_filter_copy()_ function copies a _source_ filter into a _dest_ filter.
     58
     59The _tep_filter_compare()_ function compares two filers - _filter1_ and _filter2_.
     60
     61The _tep_filter_make_string()_ function constructs a string, displaying
     62the _filter_ contents for given _event_id_.
     63
     64The _tep_filter_strerror()_ function copies the _filter_ error buffer into the
     65given _buf_ with the size _buflen_. If the error buffer is empty, in the _buf_
     66is copied a string, describing the error _err_.
     67
     68RETURN VALUE
     69------------
     70The _tep_filter_alloc()_ function returns a pointer to the newly created event
     71filter, or NULL in case of an error.
     72
     73The _tep_filter_add_filter_str()_ function returns 0 if the rule was
     74successfully added or a negative error code.  Use _tep_filter_strerror()_ to see
     75actual error message in case of an error.
     76
     77The _tep_event_filtered()_ function returns 1 if the filter is found for given
     78event, or 0 otherwise.
     79
     80The _tep_filter_remove_event()_ function returns 1 if the vent was removed, or
     810 if the event was not found.
     82
     83The _tep_filter_match()_ function returns _tep_errno_, according to the result:
     84[verse]
     85--
     86_pass:[TEP_ERRNO__FILTER_MATCH]_	- filter found for event, the record matches.
     87_pass:[TEP_ERRNO__FILTER_MISS]_		- filter found for event, the record does not match.
     88_pass:[TEP_ERRNO__FILTER_NOT_FOUND]_	- no filter found for record's event.
     89_pass:[TEP_ERRNO__NO_FILTER]_		- no rules in the filter.
     90--
     91or any other _tep_errno_, if an error occurred during the test.
     92
     93The _tep_filter_copy()_ function returns 0 on success or -1 if not all rules
     94 were copied.
     95
     96The _tep_filter_compare()_ function returns 1 if the two filters hold the same
     97content, or 0 if they do not.
     98
     99The _tep_filter_make_string()_ function returns a string, which must be freed
    100with free(), or NULL in case of an error.
    101
    102The _tep_filter_strerror()_ function returns 0 if message was filled
    103successfully, or -1 in case of an error.
    104
    105EXAMPLE
    106-------
    107[source,c]
    108--
    109#include <event-parse.h>
    110...
    111struct tep_handle *tep = tep_alloc();
    112...
    113char errstr[200];
    114int ret;
    115
    116struct tep_event_filter *filter = tep_filter_alloc(tep);
    117struct tep_event_filter *filter1 = tep_filter_alloc(tep);
    118ret = tep_filter_add_filter_str(filter, "sched/sched_wakeup:target_cpu==1");
    119if(ret < 0) {
    120	tep_filter_strerror(filter, ret, errstr, sizeof(errstr));
    121	/* Failed to add a new rule to the filter, the error string is in errstr */
    122}
    123if (tep_filter_copy(filter1, filter) != 0) {
    124	/* Failed to copy filter in filter1 */
    125}
    126...
    127if (tep_filter_compare(filter, filter1) != 1) {
    128	/* Both filters are different */
    129}
    130...
    131void process_record(struct tep_handle *tep, struct tep_record *record)
    132{
    133	struct tep_event *event;
    134	char *fstring;
    135
    136	event = tep_find_event_by_record(tep, record);
    137
    138	if (tep_event_filtered(filter, event->id) == 1) {
    139		/* The event has filter */
    140		fstring = tep_filter_make_string(filter, event->id);
    141		if (fstring != NULL) {
    142			/* The filter for the event is in fstring */
    143			free(fstring);
    144		}
    145	}
    146
    147	switch (tep_filter_match(filter, record)) {
    148	case TEP_ERRNO__FILTER_MATCH:
    149		/* The filter matches the record */
    150		break;
    151	case TEP_ERRNO__FILTER_MISS:
    152		/* The filter does not match the record */
    153		break;
    154	case TEP_ERRNO__FILTER_NOT_FOUND:
    155		/* No filter found for record's event */
    156		break;
    157	case TEP_ERRNO__NO_FILTER:
    158		/* There are no rules in the filter */
    159		break
    160	default:
    161		/* An error occurred during the test */
    162		break;
    163	}
    164
    165	if (tep_filter_remove_event(filter, event->id) == 1) {
    166		/* The event was removed from the filter */
    167	}
    168}
    169
    170...
    171tep_filter_reset(filter);
    172...
    173tep_filter_free(filter);
    174tep_filter_free(filter1);
    175...
    176--
    177
    178FILES
    179-----
    180[verse]
    181--
    182*event-parse.h*
    183	Header file to include in order to have access to the library APIs.
    184*-ltraceevent*
    185	Linker switch to add when building a program that uses the library.
    186--
    187
    188SEE ALSO
    189--------
    190_libtraceevent(3)_, _trace-cmd(1)_
    191
    192AUTHOR
    193------
    194[verse]
    195--
    196*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
    197*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
    198--
    199REPORTING BUGS
    200--------------
    201Report bugs to  <linux-trace-devel@vger.kernel.org>
    202
    203LICENSE
    204-------
    205libtraceevent is Free Software licensed under the GNU LGPL 2.1
    206
    207RESOURCES
    208---------
    209https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git