€•÷2      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ)/translations/zh_CN/trace/ring-buffer-map”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/zh_TW/trace/ring-buffer-map”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/it_IT/trace/ring-buffer-map”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/ja_JP/trace/ring-buffer-map”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/ko_KR/trace/ring-buffer-map”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ)/translations/sp_SP/trace/ring-buffer-map”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1h¡hhhžhhŸŒC/var/lib/git/docbuild/linux/Documentation/trace/ring-buffer-map.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒ"Tracefs ring-buffer memory mapping”h]”hŒ"Tracefs ring-buffer memory mapping”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h KubhŒ
field_list”“”)”}”(hhh]”hŒfield”“”)”}”(hhh]”(hŒ
field_name”“”)”}”(hŒAuthor”h]”hŒAuthor”…””}”(hhÕhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÓhhÐhŸh³h K ubhŒ
field_body”“”)”}”(hŒ*Vincent Donnefort <vdonnefort@google.com>
”h]”hŒ	paragraph”“”)”}”(hŒ)Vincent Donnefort <vdonnefort@google.com>”h]”(hŒVincent Donnefort <”…””}”(hhëhžhhŸNh NubhŒ	reference”“”)”}”(hŒvdonnefort@google.com”h]”hŒvdonnefort@google.com”…””}”(hhõhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”Œmailto:vdonnefort@google.com”uh1hóhhëubhŒ>”…””}”(hhëhžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h Khhåubah}”(h]”h ]”h"]”h$]”h&]”uh1hãhhÐubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÎhŸh³h KhhËhžhubah}”(h]”h ]”h"]”h$]”h&]”uh1hÉhh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒOverview”h]”hŒOverview”…””}”(hj$  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj!  hžhhŸh³h K
ubhê)”}”(hŒäTracefs ring-buffer memory map provides an efficient method to stream data
as no memory copy is necessary. The application mapping the ring-buffer becomes
then a consumer for that ring-buffer, in a similar fashion to trace_pipe.”h]”hŒäTracefs ring-buffer memory map provides an efficient method to stream data
as no memory copy is necessary. The application mapping the ring-buffer becomes
then a consumer for that ring-buffer, in a similar fashion to trace_pipe.”…””}”(hj2  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h Khj!  hžhubeh}”(h]”Œoverview”ah ]”h"]”Œoverview”ah$]”h&]”uh1h´hh¶hžhhŸh³h K
ubhµ)”}”(hhh]”(hº)”}”(hŒMemory mapping setup”h]”hŒMemory mapping setup”…””}”(hjK  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjH  hžhhŸh³h Kubhê)”}”(hŒ@The mapping works with a mmap() of the trace_pipe_raw interface.”h]”hŒ@The mapping works with a mmap() of the trace_pipe_raw interface.”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h KhjH  hžhubhê)”}”(hX  The first system page of the mapping contains ring-buffer statistics and
description. It is referred to as the meta-page. One of the most important
fields of the meta-page is the reader. It contains the sub-buffer ID which can
be safely read by the mapper (see ring-buffer-design.rst).”h]”hX  The first system page of the mapping contains ring-buffer statistics and
description. It is referred to as the meta-page. One of the most important
fields of the meta-page is the reader. It contains the sub-buffer ID which can
be safely read by the mapper (see ring-buffer-design.rst).”…””}”(hjg  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h KhjH  hžhubhê)”}”(hŒ•The meta-page is followed by all the sub-buffers, ordered by ascending ID. It is
therefore effortless to know where the reader starts in the mapping:”h]”hŒ•The meta-page is followed by all the sub-buffers, ordered by ascending ID. It is
therefore effortless to know where the reader starts in the mapping:”…””}”(hju  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h KhjH  hžhubhŒliteral_block”“”)”}”(hŒcreader_id = meta->reader->id;
reader_offset = meta->meta_page_size + reader_id * meta->subbuf_size;”h]”hŒcreader_id = meta->reader->id;
reader_offset = meta->meta_page_size + reader_id * meta->subbuf_size;”…””}”hj…  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²Œforce”‰Œlanguage”Œc”Œhighlight_args”}”uh1jƒ  hŸh³h KhjH  hžhubhê)”}”(hŒ¶When the application is done with the current reader, it can get a new one using
the trace_pipe_raw ioctl() TRACE_MMAP_IOCTL_GET_READER. This ioctl also updates
the meta-page fields.”h]”hŒ¶When the application is done with the current reader, it can get a new one using
the trace_pipe_raw ioctl() TRACE_MMAP_IOCTL_GET_READER. This ioctl also updates
the meta-page fields.”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h K hjH  hžhubeh}”(h]”Œmemory-mapping-setup”ah ]”h"]”Œmemory mapping setup”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒLimitations”h]”hŒLimitations”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj®  hžhhŸh³h K%ubhê)”}”(hX5  When a mapping is in place on a Tracefs ring-buffer, it is not possible to
either resize it (either by increasing the entire size of the ring-buffer or
each subbuf). It is also not possible to use snapshot and causes splice to copy
the ring buffer data instead of using the copyless swap from the ring buffer.”h]”hX5  When a mapping is in place on a Tracefs ring-buffer, it is not possible to
either resize it (either by increasing the entire size of the ring-buffer or
each subbuf). It is also not possible to use snapshot and causes splice to copy
the ring buffer data instead of using the copyless swap from the ring buffer.”…””}”(hj¿  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h K&hj®  hžhubhê)”}”(hX  Concurrent readers (either another application mapping that ring-buffer or the
kernel with trace_pipe) are allowed but not recommended. They will compete for
the ring-buffer and the output is unpredictable, just like concurrent readers on
trace_pipe would be.”h]”hX  Concurrent readers (either another application mapping that ring-buffer or the
kernel with trace_pipe) are allowed but not recommended. They will compete for
the ring-buffer and the output is unpredictable, just like concurrent readers on
trace_pipe would be.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1héhŸh³h K+hj®  hžhubeh}”(h]”Œlimitations”ah ]”h"]”Œlimitations”ah$]”h&]”uh1h´hh¶hžhhŸh³h K%ubhµ)”}”(hhh]”(hº)”}”(hŒExample”h]”hŒExample”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjã  hžhhŸh³h K1ubj„  )”}”(hXý  #include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#include <linux/trace_mmap.h>

#include <sys/mman.h>
#include <sys/ioctl.h>

#define TRACE_PIPE_RAW "/sys/kernel/tracing/per_cpu/cpu0/trace_pipe_raw"

int main(void)
{
        int page_size = getpagesize(), fd, reader_id;
        unsigned long meta_len, data_len;
        struct trace_buffer_meta *meta;
        void *map, *reader, *data;

        fd = open(TRACE_PIPE_RAW, O_RDONLY | O_NONBLOCK);
        if (fd < 0)
                exit(EXIT_FAILURE);

        map = mmap(NULL, page_size, PROT_READ, MAP_SHARED, fd, 0);
        if (map == MAP_FAILED)
                exit(EXIT_FAILURE);

        meta = (struct trace_buffer_meta *)map;
        meta_len = meta->meta_page_size;

        printf("entries:        %llu\n", meta->entries);
        printf("overrun:        %llu\n", meta->overrun);
        printf("read:           %llu\n", meta->read);
        printf("nr_subbufs:     %u\n", meta->nr_subbufs);

        data_len = meta->subbuf_size * meta->nr_subbufs;
        data = mmap(NULL, data_len, PROT_READ, MAP_SHARED, fd, meta_len);
        if (data == MAP_FAILED)
                exit(EXIT_FAILURE);

        if (ioctl(fd, TRACE_MMAP_IOCTL_GET_READER) < 0)
                exit(EXIT_FAILURE);

        reader_id = meta->reader.id;
        reader = data + meta->subbuf_size * reader_id;

        printf("Current reader address: %p\n", reader);

        munmap(data, data_len);
        munmap(meta, meta_len);
        close (fd);

        return 0;
}”h]”hXý  #include <fcntl.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#include <linux/trace_mmap.h>

#include <sys/mman.h>
#include <sys/ioctl.h>

#define TRACE_PIPE_RAW "/sys/kernel/tracing/per_cpu/cpu0/trace_pipe_raw"

int main(void)
{
        int page_size = getpagesize(), fd, reader_id;
        unsigned long meta_len, data_len;
        struct trace_buffer_meta *meta;
        void *map, *reader, *data;

        fd = open(TRACE_PIPE_RAW, O_RDONLY | O_NONBLOCK);
        if (fd < 0)
                exit(EXIT_FAILURE);

        map = mmap(NULL, page_size, PROT_READ, MAP_SHARED, fd, 0);
        if (map == MAP_FAILED)
                exit(EXIT_FAILURE);

        meta = (struct trace_buffer_meta *)map;
        meta_len = meta->meta_page_size;

        printf("entries:        %llu\n", meta->entries);
        printf("overrun:        %llu\n", meta->overrun);
        printf("read:           %llu\n", meta->read);
        printf("nr_subbufs:     %u\n", meta->nr_subbufs);

        data_len = meta->subbuf_size * meta->nr_subbufs;
        data = mmap(NULL, data_len, PROT_READ, MAP_SHARED, fd, meta_len);
        if (data == MAP_FAILED)
                exit(EXIT_FAILURE);

        if (ioctl(fd, TRACE_MMAP_IOCTL_GET_READER) < 0)
                exit(EXIT_FAILURE);

        reader_id = meta->reader.id;
        reader = data + meta->subbuf_size * reader_id;

        printf("Current reader address: %p\n", reader);

        munmap(data, data_len);
        munmap(meta, meta_len);
        close (fd);

        return 0;
}”…””}”hjô  sbah}”(h]”h ]”h"]”h$]”h&]”h±h²j“  ‰j”  j•  j–  }”uh1jƒ  hŸh³h K3hjã  hžhubeh}”(h]”Œexample”ah ]”h"]”Œexample”ah$]”h&]”uh1h´hh¶hžhhŸh³h K1ubeh}”(h]”Œ"tracefs-ring-buffer-memory-mapping”ah ]”h"]”Œ"tracefs ring-buffer memory mapping”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”j6  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j  j  jE  jB  j«  j¨  jà  jÝ  j  j  uŒ	nametypes”}”(j  ‰jE  ‰j«  ‰jà  ‰j  ‰uh}”(j  h¶jB  j!  j¨  jH  jÝ  j®  j  jã  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.