1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_instance_set_affinity, tracefs_instance_set_affinity_set, tracefs_instance_set_affinity_raw, 7tracefs_instance_get_affinity, tracefs_instance_get_affinity_set, tracefs_instance_get_affinity_raw 8- Sets or retrieves the affinity for an instance or top level for what CPUs enable tracing. 9 10SYNOPSIS 11-------- 12[verse] 13-- 14*#include <tracefs.h>* 15 16int *tracefs_instance_set_affinity*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_cpu_str_); 17int *tracefs_instance_set_affinity_set*(struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_set_, size_t _set_size_); 18int *tracefs_instance_set_affinity_raw*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_mask_); 19 20char pass:[*]*tracefs_instance_get_affinity*(struct tracefs_instance pass:[*]_instance_); 21int *tracefs_instance_get_affinity_set*(struct tracefs_instance pass:[*]_instance_, cpu_set_t pass:[*]_set_, size_t _set_size_); 22char pass:[*]*tracefs_instance_get_affinity_raw*(struct tracefs_instance pass:[*]_instance_); 23-- 24 25DESCRIPTION 26----------- 27These functions set or retrieve the CPU affinity that limits what CPUs will have tracing enabled 28for a given instance defined by the _instance_ parameter. If _instance_ is NULL, then 29the top level instance is affected. 30 31The *tracefs_instance_set_affinity()* function takes a string _cpu_str_ that is a 32list of CPUs to set the affinity for. If _cpu_str_ is NULL, then all the CPUs in 33the system will be set. The format of _cpu_str_ is a comma delimited string of 34decimal numbers with no spaces. A range may be specified by a hyphen. 35 36For example: "1,4,6-8" 37 38The numbers do not need to be in order except for ranges, where the second number 39must be equal to or greater than the first. 40 41The *tracefs_instance_set_affinity_set()* function takes a CPU set defined by 42*CPU_SET*(3). The size of the set defined by _set_size_ is the size in bytes of 43_set_. If _set_ is NULL then all the CPUs on the system will be set, and _set_size_ 44is ignored. 45 46The *tracefs_instance_set_affinity_raw()* function takes a string that holds 47a hexidecimal bitmask, where each 32 bits is separated by a comma. For a 48machine with more that 32 CPUs, to set CPUS 1-10 and CPU 40: 49 50 "100,000007fe" 51 52Where the above is a hex representation of bits 1-10 and bit 40 being set. 53 54The *tracefs_instance_get_affinity()* will retrieve the affinity in a human readable 55form. 56 57For example: "1,4,6-8" 58 59The string returned must be freed with *free*(3). 60 61The *tracefs_instance_get_affinity_set()* will set all the bits in the passed in 62cpu set (from *CPU_SET*(3)). Note it will not clear any bits that are already set 63in the set but the CPUs are not. If only the bits for the CPUs that are enabled 64should be set, a CPU_ZERO_S() should be performed on the set before calling this 65function. 66 67The *tracefs_instance_get_affinity_raw()* will simply read the instance tracing_cpumask 68and return that string. The returned string must be freed with *free*(3). 69 70RETURN VALUE 71------------ 72All the set functions return 0 on success and -1 on error. 73 74The functions *tracefs_instance_get_affinity()* and *tracefs_instance_get_affinity_raw()* 75returns an allocated string that must be freed with *free*(3), or NULL on error. 76 77The function *tracefs_instance_get_affinity_set()* returns the number of CPUs that 78were found set, or -1 on error. 79 80 81ERRORS 82------ 83The following errors are for all the above calls: 84 85*EFBIG* if a CPU is set that is greater than what is in the system. 86 87*EINVAL* One of the parameters was invalid. 88 89The following errors are for *tracefs_instance_set_affinity*() and *tracefs_instance_set_affinity_set*(): 90 91*ENOMEM* Memory allocation error. 92 93*ENODEV* dynamic events of requested type are not configured for the running kernel. 94 95The following errors are just for *tracefs_instance_set_affinity*() 96 97*EACCES* The _cpu_str_ was modified by another thread when processing it. 98 99EXAMPLE 100------- 101[source,c] 102-- 103#include <sched.h> 104#include <stdio.h> 105#include <stdlib.h> 106#include <tracefs.h> 107 108int main (int argc, char **argv) 109{ 110 struct trace_seq seq; 111 cpu_set_t *set; 112 size_t set_size; 113 char *c; 114 int cpu1; 115 int cpu2; 116 int i; 117 118 c = tracefs_instance_get_affinity(NULL); 119 printf("The affinity was %s\n", c); 120 free(c); 121 122 if (argc < 2) { 123 tracefs_instance_set_affinity(NULL, NULL); 124 exit(0); 125 } 126 /* Show example using a set */ 127 if (argc == 2 && !strchr(argv[1],',')) { 128 cpu1 = atoi(argv[1]); 129 c = strchr(argv[1], '-'); 130 if (c++) 131 cpu2 = atoi(c); 132 else 133 cpu2 = cpu1; 134 if (cpu2 < cpu1) { 135 fprintf(stderr, "Invalid CPU range\n"); 136 exit(-1); 137 } 138 set = CPU_ALLOC(cpu2 + 1); 139 set_size = CPU_ALLOC_SIZE(cpu2 + 1); 140 CPU_ZERO_S(set_size, set); 141 for ( ; cpu1 <= cpu2; cpu1++) 142 CPU_SET(cpu1, set); 143 tracefs_instance_set_affinity_set(NULL, set, set_size); 144 CPU_FREE(set); 145 exit(0); 146 } 147 148 trace_seq_init(&seq); 149 for (i = 1; i < argc; i++) { 150 if (i > 1) 151 trace_seq_putc(&seq, ','); 152 trace_seq_puts(&seq, argv[i]); 153 } 154 trace_seq_terminate(&seq); 155 tracefs_instance_set_affinity(NULL, seq.buffer); 156 trace_seq_destroy(&seq); 157 exit(0); 158 159 return 0; 160} 161-- 162FILES 163----- 164[verse] 165-- 166*tracefs.h* 167 Header file to include in order to have access to the library APIs. 168*-ltracefs* 169 Linker switch to add when building a program that uses the library. 170-- 171 172SEE ALSO 173-------- 174*libtracefs*(3), 175*libtraceevent*(3), 176*trace-cmd*(1) 177 178AUTHOR 179------ 180[verse] 181-- 182*Steven Rostedt* <[email protected]> 183*Tzvetomir Stoyanov* <[email protected]> 184-- 185REPORTING BUGS 186-------------- 187Report bugs to <[email protected]> 188 189LICENSE 190------- 191libtracefs is Free Software licensed under the GNU LGPL 2.1 192 193RESOURCES 194--------- 195https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 196 197COPYING 198------- 199Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under 200the terms of the GNU Public License (GPL). 201