1libtraceevent(3) 2================ 3 4NAME 5---- 6kbuffer_alloc, kbuffer_free, kbuffer_load_subbuffer, kbuffer_subbuffer_size, kbuffer_start_of_data - Creating of kbuffer element to parse 7the Linux kernel tracing ring buffer 8 9SYNOPSIS 10-------- 11[verse] 12-- 13*#include <kbuffer.h>* 14 15enum kbuffer_endian { 16 KBUFFER_ENDIAN_BIG, 17 KBUFFER_ENDIAN_LITTLE, 18 KBUFFER_ENDIAN_SAME_AS_HOST, 19}; 20 21enum kbuffer_long_size { 22 KBUFFER_LSIZE_4, 23 KBUFFER_LSIZE_8, 24 KBUFFER_LSIZE_SAME_AS_HOST, 25}; 26 27struct kbuffer; 28struct tep_handle; 29 30struct kbuffer pass:[*]*kbuffer_alloc*(enum kbuffer_long_size _size_, enum kbuffer_endian _endian_); 31void *kbuffer_free*(struct kbuffer pass:[*]_kbuf_); 32int *kbuffer_load_subbuffer*(struct kbuffer pass:[*]_kbuf_, void pass:[*]_subbuffer_); 33int *kbuffer_subbuffer_size*(struct kbuffer pass:[*]_kbuf); 34int *kbuffer_start_of_data*(struct kbuffer pass:[*]_kbuf_); 35-- 36 37DESCRIPTION 38----------- 39These functions create a _kbuffer_ handle that can be used to parse the raw sub buffers 40of the Linux kernel tracing ring buffer. The ring buffer is found in the tracefs 41directory, and can be retrieved by *tracefs_instance_get_file(3)* at 42*per_cpu/cpuX/trace_pipe_raw* where *X* is replaced by the per CPU number of 43the specified ring buffer. The ring buffer inside the kernel is split up per 44CPU, such that the raw ring buffer must be retrieved per CPU as well. 45 46The *kbuffer_alloc()* will create a descriptor that can be used to manage a sub buffer 47read by the ring buffer. The _size_ parameter denotes what the word size is 48for the given buffer (note, this works from reading raw data from machines other 49than the machine that is calling this function). The _endian_ denotes the endian 50for the machine. 51 52If _endian_ is set to _KBUFFER_ENDIAN_SAME_AS_HOST_ the endian will be set to the same 53as the host endianess, which is useful when the application is reading the 54ring buffer data directly from the same machine it is running on. 55 56If _size_ is set to _KBUFFER_LSIZE_SAME_AS_HOST_, if the word size is 8, it will 57set the kbuffer descriptor to long size of 8. But if the size is 4, then it 58will then perform a *uname(2)* call, and if the _machine_ field has the string "64" 59in it, it will be set to 8 byte long size and not 4 byte. This is because the 60ring buffer long size is dependent on the kernel and not user space. 61 62The *kbuffer_free()* function will free the resources created by *kbuffer_alloc()*. 63 64The *kbuffer_load_subbuffer()* will take a _subbuffer_ which is a raw data blob 65from the tracefs *trace_pipe_raw* file. The Linux tracing ring buffer is broken up 66into sub buffers. Each sub buffer is as stand alone data segment that has all the 67information to split out the individual events and time stamps. This sub buffer 68is what kbuffer uses to walk the events. 69 70The *kbuffer_subbuffer_size()* returns the location of the end of the last event 71on the sub-buffer. It does not return the size of the sub-buffer itself. 72 73The *kbuffer_start_of_data()* function returns the offset of where the actual 74data load of the sub-buffer begins. 75 76RETURN VALUE 77------------ 78*kbuffer_alloc()* returns an allocated kbuffer descriptor or NULL on error. 79The returned descriptor must be freed with *kbuffer_free()* 80 81*kbuffer_load_subbuffer()* returns 0 on success and -1 on error. 82 83*kbuffer_subbuffer_size()* returns the index on the subbuffer where the end 84of the last event is located. 85 86*kbuffer_start_of_data()* returns the offset of where the data begins on the 87sub-buffer loaded in _kbuf_. 88 89EXAMPLE 90------- 91[source,c] 92-- 93#include <stdio.h> 94#include <stdlib.h> 95#include <fcntl.h> 96#include <unistd.h> 97#include <sys/stat.h> 98 99#include <kbuffer.h> 100 101int main (int argc, char **argv) 102{ 103 unsigned long long ts; 104 struct kbuffer *kbuf; 105 struct stat st; 106 char *buf; 107 void *event; 108 int ret; 109 int fd; 110 int i = 0; 111 112 if (argc < 2) { 113 printf("usage: %s raw-subbuffer-page\n", argv[0]); 114 printf(" Try: dd count=1 bs=4096 if=/sys/kernel/tracing/per_cpu/cpu0/trace_pipe_raw of=/tmp/file\n"); 115 exit(0); 116 } 117 118 if (stat(argv[1], &st) < 0) { 119 perror("stat"); 120 exit(-1); 121 } 122 123 buf = malloc(st.st_size); 124 if (!buf) { 125 perror("Allocating buffer"); 126 exit(-1); 127 } 128 129 fd = open(argv[1], O_RDONLY); 130 if (fd < 0) { 131 perror(argv[1]); 132 exit(-1); 133 } 134 135 ret = read(fd, buf, st.st_size); 136 if (ret < 0) { 137 perror("Reading buffer"); 138 exit(-1); 139 } 140 close(fd); 141 142 kbuf = kbuffer_alloc(KBUFFER_ENDIAN_SAME_AS_HOST, 143 KBUFFER_LSIZE_SAME_AS_HOST); 144 if (!kbuf) { 145 perror("Creating kbuffer"); 146 exit(-1); 147 } 148 ret = kbuffer_load_subbuffer(kbuf, buf); 149 if (ret < 0) { 150 perror("Loading sub bufer"); 151 exit(-1); 152 } 153 154 if (kbuffer_subbuffer_size(kbuf) > st.st_size) { 155 fprintf(stderr, "kbuffer is bigger than raw size %d > %ld\n", 156 kbuffer_subbuffer_size(kbuf), st.st_size); 157 exit(-1); 158 } 159 160 printf("Kbuffer data starts at %d\n", kbuffer_start_of_data(kbuf)); 161 do { 162 event = kbuffer_read_event(kbuf, &ts); 163 if (event) { 164 printf(" event %3d ts:%lld\n", i++, ts); 165 event = kbuffer_next_event(kbuf, NULL); 166 } 167 } while (event); 168 169 if (!event) 170 printf("Finished sub buffer\n"); 171 172 kbuffer_free(kbuf); 173 174 return 0; 175} 176-- 177FILES 178----- 179[verse] 180-- 181*event-parse.h* 182 Header file to include in order to have access to the library APIs. 183*-ltraceevent* 184 Linker switch to add when building a program that uses the library. 185-- 186 187SEE ALSO 188-------- 189*libtraceevent*(3), *trace-cmd*(1) 190 191AUTHOR 192------ 193[verse] 194-- 195*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*. 196-- 197REPORTING BUGS 198-------------- 199Report bugs to <linux-trace-devel@vger.kernel.org> 200 201LICENSE 202------- 203libtraceevent is Free Software licensed under the GNU LGPL 2.1 204 205RESOURCES 206--------- 207https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/ 208