1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_tracer_set, tracefs_tracer_clear - Enable or disable a tracer in an instance or the top level 7 8SYNOPSIS 9-------- 10[verse] 11-- 12*#include <tracefs.h>* 13 14int *tracefs_tracer_set*(struct tracefs_instance pass:[*]_instance_, enum tracefs_tracers _tracer_); 15int *tracefs_tracer_set*(struct tracefs_instance pass:[*]_instance_, enum tracefs_tracers _tracer_, const char pass:[*]_name_); 16int *tracefs_tracer_clear*(struct tracefs_instance pass:[*]_instance_); 17-- 18 19DESCRIPTION 20----------- 21*tracefs_tracer_set* enables a tracer in the given instance, defined by the 22_instance_ parameter. If _instance_ is NULL, then the top level instance is 23changed. If _tracer_ is set to *TRACFES_TRACER_CUSTOM* then a _name_ 24string must be passed in as the third parameter, and that is written into the 25instance to enable the tracer with that name. This is useful for newer or 26custom kernels that contain tracers that are not yet identified by the 27tracefs_tracers enum. 28 29*tracefs_tracer_clear* disables the tracer for the given instance defined by 30the _instance_ variable, or the top level instance if it is NULL. 31This is the same as calling *tracefs_tracer_set* with TRACEFS_TRACER_NOP as 32the _tracer_ parameter. 33 34TRACEFS_TRACER ENUMS 35-------------------- 36 37The currently defined enums that are accepted are: 38 39*TRACEFS_TRACER_NOP* : 40This is the idle tracer, which does nothing and is used to clear any 41active tracer. 42 43*TRACEFS_TRACER_FUNCTION* : 44Enables most functions in the kernel to be traced. 45 46*TRACEFS_TRACER_FUNCTION_GRAPH* : 47Enables most functions in the kernel to be traced as well as the return 48of the function. 49 50*TRACEFS_TRACER_IRQSOFF* : 51Tracers the latency of interrupts disabled. 52 53*TRACEFS_TRACER_PREEMPTOFF* : 54Tracers the latency of preemption disabled (the time in the kernel that 55tasks can not be scheduled from the CPU). 56 57*TRACEFS_TRACER_PREEMPTIRQSOFF* : 58Traces the combined total latency of when interrupts are disabled as well as when 59preemption is disabled. 60 61*TRACEFS_TRACER_WAKEUP* : 62Traces the latency of when the highest priority task takes to wake up. 63 64*TRACEFS_TRACER_WAKEUP_RT* : 65Traces the latency of when the highest priority real-time task takes to wake up. 66All other tasks are ignored. 67 68*TRACEFS_TRACER_WAKEUP_DL* : 69Traces the latency of when the highest priority DEADLINE task takes to wake up. 70All other tasks are ignored. 71 72*TRACEFS_TRACER_MMIOTRACE* : 73Traces the interaction of devices with the kernel. 74 75*TRACEFS_TRACER_HWLAT* : 76Detects latency caused by the hardware that is outside the scope of the kernel. 77 78*TRACEFS_TRACER_BRANCH* : 79Traces when likely or unlikely branches are taken. 80 81*TRACEFS_TRACER_BLOCK* : 82Special tracer for the block devices. 83 84Note that the above tracers may not be available in the kernel and 85*tracefs_tracer_set()* will return an error with errno set to ENODEV, 86if the kernel does not support the _tracer_ option, or the custom one 87if TRACEFS_TRACER_CUSTOM is used. 88 89RETURN VALUE 90------------ 91Returns 0 on success, or -1 on error. 92 93ERRORS 94------ 95 96*tracefs_tracer_set*() can fail with the following errors: 97 98*EINVAL* The _tracer_ parameter is outside the scope of what is defined. 99 100*ENOMEM* Memory allocation error. 101 102*ENOENT* Tracers are not supported on the running kernel. 103 104*ENODEV* The specified tracer is not supported on the running kernel. 105 106Other errors may also happen caused by internal system calls. 107 108EXAMPLE 109------- 110[source,c] 111-- 112#include <stdlib.h> 113#include <stdio.h> 114#include <getopt.h> 115#include <errno.h> 116#include <tracefs.h> 117 118int main(int argc, char *argv[]) 119{ 120 struct tracefs_instance *inst = NULL; 121 enum tracefs_tracers t = TRACEFS_TRACER_NOP; 122 const char *buf = NULL; 123 const char *cust; 124 int ret; 125 int ch; 126 127 while ((ch = getopt(argc, argv, "nfgiwdc:B:")) > 0) { 128 switch (ch) { 129 case 'f': t = TRACEFS_TRACER_FUNCTION; break; 130 case 'g': t = TRACEFS_TRACER_FUNCTION_GRAPH; break; 131 case 'i': t = TRACEFS_TRACER_PREEMPTIRQSOFF; break; 132 case 'w': t = TRACEFS_TRACER_WAKEUP_RT; break; 133 case 'd': t = TRACEFS_TRACER_WAKEUP_DL; break; 134 case 'c': 135 t = TRACEFS_TRACER_CUSTOM; 136 cust = optarg; 137 break; 138 case 'B': 139 buf = optarg; 140 break; 141 case 'n': 142 /* nop */ 143 break; 144 default: 145 printf("Unknow arg %c\n", ch); 146 exit(-1); 147 } 148 } 149 150 if (buf) { 151 inst = tracefs_instance_create(buf); 152 if (!inst) { 153 printf("failed to create instance\n"); 154 exit(-1); 155 } 156 } 157 158 if (t == TRACEFS_TRACER_CUSTOM) 159 ret = tracefs_tracer_set(inst, t, cust); 160 else 161 ret = tracefs_tracer_set(inst, t); 162 163 if (ret < 0) { 164 if (inst) { 165 tracefs_instance_destroy(inst); 166 tracefs_instance_free(inst); 167 } 168 if (errno == ENODEV) 169 printf("Tracer not supported by kernel\n"); 170 else 171 perror("Error"); 172 exit(-1); 173 } 174 175 if (inst) 176 tracefs_instance_free(inst); 177 178 exit(0); 179} 180-- 181 182FILES 183----- 184[verse] 185-- 186*tracefs.h* 187 Header file to include in order to have access to the library APIs. 188*-ltracefs* 189 Linker switch to add when building a program that uses the library. 190-- 191 192SEE ALSO 193-------- 194*libtracefs*(3), 195*libtraceevent*(3), 196*trace-cmd*(1) 197 198AUTHOR 199------ 200[verse] 201-- 202*Steven Rostedt* <[email protected]> 203*Tzvetomir Stoyanov* <[email protected]> 204*sameeruddin shaik* <[email protected]> 205-- 206REPORTING BUGS 207-------------- 208Report bugs to <[email protected]> 209 210LICENSE 211------- 212libtracefs is Free Software licensed under the GNU LGPL 2.1 213 214RESOURCES 215--------- 216https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 217 218COPYING 219------- 220Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 221the terms of the GNU Public License (GPL). 222