Documentation/trace/ring-buffer-map.rst

1 .. SPDX-License-Identifier: GPL-2.0
4 Tracefs ring-buffer memory mapping
11 Tracefs ring-buffer memory map provides an efficient method to stream data
12 as no memory copy is necessary. The application mapping the ring-buffer becomes
13 then a consumer for that ring-buffer, in a similar fashion to trace_pipe.
15 Memory mapping setup
17 The mapping works with a mmap() of the trace_pipe_raw interface.
19 The first system page of the mapping contains ring-buffer statistics and
20 description. It is referred to as the meta-page. One of the most important
21 fields of the meta-page is the reader. It contains the sub-buffer ID which can
22 be safely read by the mapper (see ring-buffer-design.rst).
24 The meta-page is followed by all the sub-buffers, ordered by ascending ID. It is
25 therefore effortless to know where the reader starts in the mapping:
27 .. code-block:: c
29         reader_id = meta->reader->id;
30         reader_offset = meta->meta_page_size + reader_id * meta->subbuf_size;
34 the meta-page fields.
38 When a mapping is in place on a Tracefs ring-buffer, it is not possible to
39 either resize it (either by increasing the entire size of the ring-buffer or
41 the ring buffer data instead of using the copyless swap from the ring buffer.
43 Concurrent readers (either another application mapping that ring-buffer or the
45 the ring-buffer and the output is unpredictable, just like concurrent readers on
51 .. code-block:: c
70                 void *map, *reader, *data;
81                 meta_len = meta->meta_page_size;
83                 printf("entries:        %llu\n", meta->entries);
84                 printf("overrun:        %llu\n", meta->overrun);
85                 printf("read:           %llu\n", meta->read);
86                 printf("nr_subbufs:     %u\n", meta->nr_subbufs);
88                 data_len = meta->subbuf_size * meta->nr_subbufs;
89                 data = mmap(NULL, data_len, PROT_READ, MAP_SHARED, fd, meta_len);
90                 if (data == MAP_FAILED)
96                 reader_id = meta->reader.id;
97                 reader = data + meta->subbuf_size * reader_id;
101                 munmap(data, data_len);