€•      Œ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/events”Œ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/events”Œ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/events”Œ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/events”Œ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/events”Œ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/events”Œ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Œsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒEvent Tracing”h]”hŒEvent Tracing”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒ:/var/lib/git/docbuild/linux/Documentation/trace/events.rst”h KubhŒ
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ŒTheodore Ts'o”h]”hŒ	paragraph”“”)”}”(hhÕh]”hŒTheodore Tsâ€™o”…””}”(hhÙhžhhŸNh Nubah}”(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žhubh½)”}”(hhh]”(hÂ)”}”(hŒUpdated”h]”hŒUpdated”…””}”(hhõhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÁhhòhŸh¶h K ubhÒ)”}”(hŒLi Zefan and Tom Zanussi
”h]”hØ)”}”(hŒLi Zefan and Tom Zanussi”h]”hŒLi Zefan and Tom Zanussi”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1hÑhhòubeh}”(h]”h ]”h"]”h$]”h&]”uh1h¼hŸh¶h Khh¹hžhubeh}”(h]”h ]”h"]”h$]”h&]”uh1h·hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ1. Introduction”h]”hŒ1. Introduction”…””}”(hj*  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj'  hžhhŸh¶h K	ubhØ)”}”(hŒ¬Tracepoints (see Documentation/trace/tracepoints.rst) can be used
without creating custom kernel modules to register probe functions
using the event tracing infrastructure.”h]”hŒ¬Tracepoints (see Documentation/trace/tracepoints.rst) can be used
without creating custom kernel modules to register probe functions
using the event tracing infrastructure.”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj'  hžhubhØ)”}”(hŒïNot all tracepoints can be traced using the event tracing system;
the kernel developer must provide code snippets which define how the
tracing information is saved into the tracing buffer, and how the
tracing information should be printed.”h]”hŒïNot all tracepoints can be traced using the event tracing system;
the kernel developer must provide code snippets which define how the
tracing information is saved into the tracing buffer, and how the
tracing information should be printed.”…””}”(hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj'  hžhubeh}”(h]”Œintroduction”ah ]”h"]”Œ1. introduction”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K	ubh¢)”}”(hhh]”(h§)”}”(hŒ2. Using Event Tracing”h]”hŒ2. Using Event Tracing”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj\  hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ!2.1 Via the 'set_event' interface”h]”hŒ%2.1 Via the â€˜set_eventâ€™ interface”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjm  hžhhŸh¶h KubhØ)”}”(hŒiThe events which are available for tracing can be found in the file
/sys/kernel/tracing/available_events.”h]”hŒiThe events which are available for tracing can be found in the file
/sys/kernel/tracing/available_events.”…””}”(hj~  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khjm  hžhubhØ)”}”(hŒtTo enable a particular event, such as 'sched_wakeup', simply echo it
to /sys/kernel/tracing/set_event. For example::”h]”hŒwTo enable a particular event, such as â€˜sched_wakeupâ€™, simply echo it
to /sys/kernel/tracing/set_event. For example:”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khjm  hžhubhŒliteral_block”“”)”}”(hŒ4# echo sched_wakeup >> /sys/kernel/tracing/set_event”h]”hŒ4# echo sched_wakeup >> /sys/kernel/tracing/set_event”…””}”hjœ  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jš  hŸh¶h K hjm  hžhubhŒnote”“”)”}”(hŒD'>>' is necessary, otherwise it will firstly disable all the events.”h]”hØ)”}”(hj°  h]”hŒHâ€˜>>â€™ is necessary, otherwise it will firstly disable all the events.”…””}”(hj²  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K"hj®  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¬  hjm  hžhhŸh¶h NubhØ)”}”(hŒcTo disable an event, echo the event name to the set_event file prefixed
with an exclamation point::”h]”hŒbTo disable an event, echo the event name to the set_event file prefixed
with an exclamation point:”…””}”(hjÅ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K$hjm  hžhubj›  )”}”(hŒ7# echo '!sched_wakeup' >> /sys/kernel/tracing/set_event”h]”hŒ7# echo '!sched_wakeup' >> /sys/kernel/tracing/set_event”…””}”hjÓ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K'hjm  hžhubhØ)”}”(hŒATo disable all events, echo an empty line to the set_event file::”h]”hŒ@To disable all events, echo an empty line to the set_event file:”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K)hjm  hžhubj›  )”}”(hŒ&# echo > /sys/kernel/tracing/set_event”h]”hŒ&# echo > /sys/kernel/tracing/set_event”…””}”hjï  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K+hjm  hžhubhØ)”}”(hŒDTo enable all events, echo ``*:*`` or ``*:`` to the set_event file::”h]”(hŒTo enable all events, echo ”…””}”(hjý  hžhhŸNh NubhŒliteral”“”)”}”(hŒ``*:*``”h]”hŒ*:*”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjý  ubhŒ or ”…””}”(hjý  hžhhŸNh Nubj  )”}”(hŒ``*:``”h]”hŒ*:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjý  ubhŒ to the set_event file:”…””}”(hjý  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K-hjm  hžhubj›  )”}”(hŒ*# echo *:* > /sys/kernel/tracing/set_event”h]”hŒ*# echo *:* > /sys/kernel/tracing/set_event”…””}”hj1  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K/hjm  hžhubhØ)”}”(hXn  The events are organized into subsystems, such as ext4, irq, sched,
etc., and a full event name looks like this: <subsystem>:<event>.  The
subsystem name is optional, but it is displayed in the available_events
file.  All of the events in a subsystem can be specified via the syntax
``<subsystem>:*``; for example, to enable all irq events, you can use the
command::”h]”(hX  The events are organized into subsystems, such as ext4, irq, sched,
etc., and a full event name looks like this: <subsystem>:<event>.  The
subsystem name is optional, but it is displayed in the available_events
file.  All of the events in a subsystem can be specified via the syntax
”…””}”(hj?  hžhhŸNh Nubj  )”}”(hŒ``<subsystem>:*``”h]”hŒ<subsystem>:*”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj?  ubhŒA; for example, to enable all irq events, you can use the
command:”…””}”(hj?  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K1hjm  hžhubj›  )”}”(hŒ.# echo 'irq:*' > /sys/kernel/tracing/set_event”h]”hŒ.# echo 'irq:*' > /sys/kernel/tracing/set_event”…””}”hj_  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K8hjm  hžhubhØ)”}”(hŒ[The set_event file may also be used to enable events associated to only
a specific module::”h]”hŒZThe set_event file may also be used to enable events associated to only
a specific module:”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K:hjm  hžhubj›  )”}”(hŒ6# echo ':mod:<module>' > /sys/kernel/tracing/set_event”h]”hŒ6# echo ':mod:<module>' > /sys/kernel/tracing/set_event”…””}”hj{  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K=hjm  hžhubhØ)”}”(hŒ×Will enable all events in the module ``<module>``.  If the module is not yet
loaded, the string will be saved and when a module is that matches ``<module>``
is loaded, then it will apply the enabling of events then.”h]”(hŒ%Will enable all events in the module ”…””}”(hj‰  hžhhŸNh Nubj  )”}”(hŒ``<module>``”h]”hŒ<module>”…””}”(hj‘  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj‰  ubhŒ_.  If the module is not yet
loaded, the string will be saved and when a module is that matches ”…””}”(hj‰  hžhhŸNh Nubj  )”}”(hŒ``<module>``”h]”hŒ<module>”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj‰  ubhŒ;
is loaded, then it will apply the enabling of events then.”…””}”(hj‰  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K?hjm  hžhubhØ)”}”(hŒ]The text before ``:mod:`` will be parsed to specify specific events that the
module creates::”h]”(hŒThe text before ”…””}”(hj»  hžhhŸNh Nubj  )”}”(hŒ	``:mod:``”h]”hŒ:mod:”…””}”(hjÃ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj»  ubhŒC will be parsed to specify specific events that the
module creates:”…””}”(hj»  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KChjm  hžhubj›  )”}”(hŒ=# echo '<match>:mod:<module>' > /sys/kernel/tracing/set_event”h]”hŒ=# echo '<match>:mod:<module>' > /sys/kernel/tracing/set_event”…””}”hjÛ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h KFhjm  hžhubhØ)”}”(hŒ|The above will enable any system or event that ``<match>`` matches. If
``<match>`` is ``"*"`` then it will match all events.”h]”(hŒ/The above will enable any system or event that ”…””}”(hjé  hžhhŸNh Nubj  )”}”(hŒ``<match>``”h]”hŒ<match>”…””}”(hjñ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubhŒ matches. If
”…””}”(hjé  hžhhŸNh Nubj  )”}”(hŒ``<match>``”h]”hŒ<match>”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubhŒ is ”…””}”(hjé  hžhhŸNh Nubj  )”}”(hŒ``"*"``”h]”hŒ"*"”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjé  ubhŒ then it will match all events.”…””}”(hjé  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KHhjm  hžhubhØ)”}”(hŒ1To enable only a specific event within a system::”h]”hŒ0To enable only a specific event within a system:”…””}”(hj-  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KKhjm  hžhubj›  )”}”(hŒF# echo '<system>:<event>:mod:<module>' > /sys/kernel/tracing/set_event”h]”hŒF# echo '<system>:<event>:mod:<module>' > /sys/kernel/tracing/set_event”…””}”hj;  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h KMhjm  hžhubhØ)”}”(hŒ]If ``<event>`` is ``"*"`` then it will match all events within the system
for a given module.”h]”(hŒIf ”…””}”(hjI  hžhhŸNh Nubj  )”}”(hŒ``<event>``”h]”hŒ<event>”…””}”(hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjI  ubhŒ is ”…””}”(hjI  hžhhŸNh Nubj  )”}”(hŒ``"*"``”h]”hŒ"*"”…””}”(hjc  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjI  ubhŒD then it will match all events within the system
for a given module.”…””}”(hjI  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KOhjm  hžhubeh}”(h]”Œvia-the-set-event-interface”ah ]”h"]”Œ!2.1 via the 'set_event' interface”ah$]”h&]”uh1h¡hj\  hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ2.2 Via the 'enable' toggle”h]”hŒ2.2 Via the â€˜enableâ€™ toggle”…””}”(hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjƒ  hžhhŸh¶h KSubhØ)”}”(hŒ]The events available are also listed in /sys/kernel/tracing/events/ hierarchy
of directories.”h]”hŒ]The events available are also listed in /sys/kernel/tracing/events/ hierarchy
of directories.”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KUhjƒ  hžhubhØ)”}”(hŒ To enable event 'sched_wakeup'::”h]”hŒ#To enable event â€˜sched_wakeupâ€™:”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KXhjƒ  hžhubj›  )”}”(hŒ?# echo 1 > /sys/kernel/tracing/events/sched/sched_wakeup/enable”h]”hŒ?# echo 1 > /sys/kernel/tracing/events/sched/sched_wakeup/enable”…””}”hj°  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h KZhjƒ  hžhubhØ)”}”(hŒTo disable it::”h]”hŒTo disable it:”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K\hjƒ  hžhubj›  )”}”(hŒ?# echo 0 > /sys/kernel/tracing/events/sched/sched_wakeup/enable”h]”hŒ?# echo 0 > /sys/kernel/tracing/events/sched/sched_wakeup/enable”…””}”hjÌ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K^hjƒ  hžhubhØ)”}”(hŒ)To enable all events in sched subsystem::”h]”hŒ(To enable all events in sched subsystem:”…””}”(hjÚ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K`hjƒ  hžhubj›  )”}”(hŒ2# echo 1 > /sys/kernel/tracing/events/sched/enable”h]”hŒ2# echo 1 > /sys/kernel/tracing/events/sched/enable”…””}”hjè  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Kbhjƒ  hžhubhØ)”}”(hŒTo enable all events::”h]”hŒTo enable all events:”…””}”(hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kdhjƒ  hžhubj›  )”}”(hŒ,# echo 1 > /sys/kernel/tracing/events/enable”h]”hŒ,# echo 1 > /sys/kernel/tracing/events/enable”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Kfhjƒ  hžhubhØ)”}”(hŒ?When reading one of these enable files, there are four results:”h]”hŒ?When reading one of these enable files, there are four results:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khhjƒ  hžhubhŒblock_quote”“”)”}”(hŒÁ- 0 - all events this file affects are disabled
- 1 - all events this file affects are enabled
- X - there is a mixture of events enabled and disabled
- ? - this file does not affect any event
”h]”hŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(hŒ-0 - all events this file affects are disabled”h]”hØ)”}”(hj/  h]”hŒ-0 - all events this file affects are disabled”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kjhj-  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hj(  ubj,  )”}”(hŒ,1 - all events this file affects are enabled”h]”hØ)”}”(hjF  h]”hŒ,1 - all events this file affects are enabled”…””}”(hjH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KkhjD  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hj(  ubj,  )”}”(hŒ5X - there is a mixture of events enabled and disabled”h]”hØ)”}”(hj]  h]”hŒ5X - there is a mixture of events enabled and disabled”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Klhj[  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hj(  ubj,  )”}”(hŒ(? - this file does not affect any event
”h]”hØ)”}”(hŒ'? - this file does not affect any event”h]”hŒ'? - this file does not affect any event”…””}”(hjv  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kmhjr  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hj(  ubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1j&  hŸh¶h Kjhj"  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hŸh¶h Kjhjƒ  hžhubeh}”(h]”Œvia-the-enable-toggle”ah ]”h"]”Œ2.2 via the 'enable' toggle”ah$]”h&]”uh1h¡hj\  hžhhŸh¶h KSubh¢)”}”(hhh]”(h§)”}”(hŒ2.3 Boot option”h]”hŒ2.3 Boot option”…””}”(hj£  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj   hžhhŸh¶h KpubhØ)”}”(hŒ>In order to facilitate early boot debugging, use boot option::”h]”hŒ=In order to facilitate early boot debugging, use boot option:”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Krhj   hžhubj›  )”}”(hŒtrace_event=[event-list]”h]”hŒtrace_event=[event-list]”…””}”hj¿  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Kthj   hžhubhØ)”}”(hŒQevent-list is a comma separated list of events. See section 2.1 for event
format.”h]”hŒQevent-list is a comma separated list of events. See section 2.1 for event
format.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kvhj   hžhubeh}”(h]”Œboot-option”ah ]”h"]”Œ2.3 boot option”ah$]”h&]”uh1h¡hj\  hžhhŸh¶h Kpubeh}”(h]”Œusing-event-tracing”ah ]”h"]”Œ2. using event tracing”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ'3. Defining an event-enabled tracepoint”h]”hŒ'3. Defining an event-enabled tracepoint”…””}”(hjî  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjë  hžhhŸh¶h KzubhØ)”}”(hŒ0See The example provided in samples/trace_events”h]”hŒ0See The example provided in samples/trace_events”…””}”(hjü  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K|hjë  hžhubeh}”(h]”Œ$defining-an-event-enabled-tracepoint”ah ]”h"]”Œ'3. defining an event-enabled tracepoint”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kzubh¢)”}”(hhh]”(h§)”}”(hŒ4. Event formats”h]”hŒ4. Event formats”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h KubhØ)”}”(hX  Each trace event has a 'format' file associated with it that contains
a description of each field in a logged event.  This information can
be used to parse the binary trace stream, and is also the place to
find the field names that can be used in event filters (see section 5).”h]”hX  Each trace event has a â€˜formatâ€™ file associated with it that contains
a description of each field in a logged event.  This information can
be used to parse the binary trace stream, and is also the place to
find the field names that can be used in event filters (see section 5).”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj  hžhubhØ)”}”(hŒŠIt also displays the format string that will be used to print the
event in text mode, along with the event name and ID used for
profiling.”h]”hŒŠIt also displays the format string that will be used to print the
event in text mode, along with the event name and ID used for
profiling.”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K†hj  hžhubhØ)”}”(hŒçEvery event has a set of ``common`` fields associated with it; these are
the fields prefixed with ``common_``.  The other fields vary between
events and correspond to the fields defined in the TRACE_EVENT
definition for that event.”h]”(hŒEvery event has a set of ”…””}”(hj?  hžhhŸNh Nubj  )”}”(hŒ
``common``”h]”hŒcommon”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj?  ubhŒ? fields associated with it; these are
the fields prefixed with ”…””}”(hj?  hžhhŸNh Nubj  )”}”(hŒ``common_``”h]”hŒcommon_”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hj?  ubhŒz.  The other fields vary between
events and correspond to the fields defined in the TRACE_EVENT
definition for that event.”…””}”(hj?  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KŠhj  hžhubhØ)”}”(hŒ'Each field in the format has the form::”h]”hŒ&Each field in the format has the form:”…””}”(hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Khj  hžhubj›  )”}”(hŒ.field:field-type field-name; offset:N; size:N;”h]”hŒ.field:field-type field-name; offset:N; size:N;”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K‘hj  hžhubhØ)”}”(hŒlwhere offset is the offset of the field in the trace record and size
is the size of the data item, in bytes.”h]”hŒlwhere offset is the offset of the field in the trace record and size
is the size of the data item, in bytes.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K“hj  hžhubhØ)”}”(hŒLFor example, here's the information displayed for the 'sched_wakeup'
event::”h]”hŒQFor example, hereâ€™s the information displayed for the â€˜sched_wakeupâ€™
event:”…””}”(hj›  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K–hj  hžhubj›  )”}”(hX2  # cat /sys/kernel/tracing/events/sched/sched_wakeup/format

name: sched_wakeup
ID: 60
format:
        field:unsigned short common_type;       offset:0;       size:2;
        field:unsigned char common_flags;       offset:2;       size:1;
        field:unsigned char common_preempt_count;       offset:3;       size:1;
        field:int common_pid;   offset:4;       size:4;
        field:int common_tgid;  offset:8;       size:4;

        field:char comm[TASK_COMM_LEN]; offset:12;      size:16;
        field:pid_t pid;        offset:28;      size:4;
        field:int prio; offset:32;      size:4;
        field:int success;      offset:36;      size:4;
        field:int cpu;  offset:40;      size:4;

print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid,
           REC->prio, REC->success, REC->cpu”h]”hX2  # cat /sys/kernel/tracing/events/sched/sched_wakeup/format

name: sched_wakeup
ID: 60
format:
        field:unsigned short common_type;       offset:0;       size:2;
        field:unsigned char common_flags;       offset:2;       size:1;
        field:unsigned char common_preempt_count;       offset:3;       size:1;
        field:int common_pid;   offset:4;       size:4;
        field:int common_tgid;  offset:8;       size:4;

        field:char comm[TASK_COMM_LEN]; offset:12;      size:16;
        field:pid_t pid;        offset:28;      size:4;
        field:int prio; offset:32;      size:4;
        field:int success;      offset:36;      size:4;
        field:int cpu;  offset:40;      size:4;

print fmt: "task %s:%d [%d] success=%d [%03d]", REC->comm, REC->pid,
           REC->prio, REC->success, REC->cpu”…””}”hj©  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h K™hj  hžhubhØ)”}”(hŒÓThis event contains 10 fields, the first 5 common and the remaining 5
event-specific.  All the fields for this event are numeric, except for
'comm' which is a string, a distinction important for event filtering.”h]”hŒ×This event contains 10 fields, the first 5 common and the remaining 5
event-specific.  All the fields for this event are numeric, except for
â€˜commâ€™ which is a string, a distinction important for event filtering.”…””}”(hj·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K­hj  hžhubeh}”(h]”Œevent-formats”ah ]”h"]”Œ4. event formats”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒ5. Event filtering”h]”hŒ5. Event filtering”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÍ  hžhhŸh¶h K²ubhØ)”}”(hXø  Trace events can be filtered in the kernel by associating boolean
'filter expressions' with them.  As soon as an event is logged into
the trace buffer, its fields are checked against the filter expression
associated with that event type.  An event with field values that
'match' the filter will appear in the trace output, and an event whose
values don't match will be discarded.  An event with no filter
associated with it matches everything, and is the default when no
filter has been set for an event.”h]”hX  Trace events can be filtered in the kernel by associating boolean
â€˜filter expressionsâ€™ with them.  As soon as an event is logged into
the trace buffer, its fields are checked against the filter expression
associated with that event type.  An event with field values that
â€˜matchâ€™ the filter will appear in the trace output, and an event whose
values donâ€™t match will be discarded.  An event with no filter
associated with it matches everything, and is the default when no
filter has been set for an event.”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K´hjÍ  hžhubh¢)”}”(hhh]”(h§)”}”(hŒ5.1 Expression syntax”h]”hŒ5.1 Expression syntax”…””}”(hjï  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjì  hžhhŸh¶h K¾ubhØ)”}”(hXR  A filter expression consists of one or more 'predicates' that can be
combined using the logical operators '&&' and '||'.  A predicate is
simply a clause that compares the value of a field contained within a
logged event with a constant value and returns either 0 or 1 depending
on whether the field value matched (1) or didn't match (0)::”h]”hX_  A filter expression consists of one or more â€˜predicatesâ€™ that can be
combined using the logical operators â€˜&&â€™ and â€˜||â€™.  A predicate is
simply a clause that compares the value of a field contained within a
logged event with a constant value and returns either 0 or 1 depending
on whether the field value matched (1) or didnâ€™t match (0):”…””}”(hjý  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÀhjì  hžhubj›  )”}”(hŒ$field-name relational-operator value”h]”hŒ$field-name relational-operator value”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h KÆhjì  hžhubhØ)”}”(hŒ¦Parentheses can be used to provide arbitrary logical groupings and
double-quotes can be used to prevent the shell from interpreting
operators as shell metacharacters.”h]”hŒ¦Parentheses can be used to provide arbitrary logical groupings and
double-quotes can be used to prevent the shell from interpreting
operators as shell metacharacters.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÈhjì  hžhubhØ)”}”(hŒqThe field-names available for use in filters can be found in the
'format' files for trace events (see section 4).”h]”hŒuThe field-names available for use in filters can be found in the
â€˜formatâ€™ files for trace events (see section 4).”…””}”(hj'  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÌhjì  hžhubhØ)”}”(hŒFThe relational-operators depend on the type of the field being tested:”h]”hŒFThe relational-operators depend on the type of the field being tested:”…””}”(hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÏhjì  hžhubhØ)”}”(hŒ/The operators available for numeric fields are:”h]”hŒ/The operators available for numeric fields are:”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÑhjì  hžhubhØ)”}”(hŒ==, !=, <, <=, >, >=, &”h]”hŒ==, !=, <, <=, >, >=, &”…””}”(hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÓhjì  hžhubhØ)”}”(hŒAnd for string fields they are:”h]”hŒAnd for string fields they are:”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÕhjì  hžhubhØ)”}”(hŒ	==, !=, ~”h]”hŒ	==, !=, ~”…””}”(hjm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h K×hjì  hžhubhØ)”}”(hŒZThe glob (~) accepts a wild card character (\*,?) and character classes
([). For example::”h]”hŒYThe glob (~) accepts a wild card character ( *,?) and character classes
([). For example:”…””}”(hj{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h KÙhjì  hžhubj›  )”}”(hŒJprev_comm ~ "*sh"
prev_comm ~ "sh*"
prev_comm ~ "*sh*"
prev_comm ~ "ba*sh"”h]”hŒJprev_comm ~ "*sh"
prev_comm ~ "sh*"
prev_comm ~ "*sh*"
prev_comm ~ "ba*sh"”…””}”hj‰  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h KÜhjì  hžhubhØ)”}”(hŒœIf the field is a pointer that points into user space (for example
"filename" from sys_enter_openat), then you have to append ".ustring" to the
field name::”h]”hŒ£If the field is a pointer that points into user space (for example
â€œfilenameâ€ from sys_enter_openat), then you have to append â€œ.ustringâ€ to the
field name:”…””}”(hj—  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Káhjì  hžhubj›  )”}”(hŒfilename.ustring ~ "password"”h]”hŒfilename.ustring ~ "password"”…””}”hj¥  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Kåhjì  hžhubhØ)”}”(hŒbAs the kernel will have to know how to retrieve the memory that the pointer
is at from user space.”h]”hŒbAs the kernel will have to know how to retrieve the memory that the pointer
is at from user space.”…””}”(hj³  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kçhjì  hžhubhØ)”}”(hŒQYou can convert any long type to a function address and search by function name::”h]”hŒPYou can convert any long type to a function address and search by function name:”…””}”(hjÁ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kêhjì  hžhubj›  )”}”(hŒ,call_site.function == security_prepare_creds”h]”hŒ,call_site.function == security_prepare_creds”…””}”hjÏ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Kìhjì  hžhubhØ)”}”(hX5  The above will filter when the field "call_site" falls on the address within
"security_prepare_creds". That is, it will compare the value of "call_site" and
the filter will return true if it is greater than or equal to the start of
the function "security_prepare_creds" and less than the end of that function.”h]”hXE  The above will filter when the field â€œcall_siteâ€ falls on the address within
â€œsecurity_prepare_credsâ€. That is, it will compare the value of â€œcall_siteâ€ and
the filter will return true if it is greater than or equal to the start of
the function â€œsecurity_prepare_credsâ€ and less than the end of that function.”…””}”(hjÝ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kîhjì  hžhubhØ)”}”(hŒpThe ".function" postfix can only be attached to values of size long, and can only
be compared with "==" or "!=".”h]”hŒ|The â€œ.functionâ€ postfix can only be attached to values of size long, and can only
be compared with â€œ==â€ or â€œ!=â€.”…””}”(hjë  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kóhjì  hžhubhØ)”}”(hŒ”Cpumask fields or scalar fields that encode a CPU number can be filtered using
a user-provided cpumask in cpulist format. The format is as follows::”h]”hŒ“Cpumask fields or scalar fields that encode a CPU number can be filtered using
a user-provided cpumask in cpulist format. The format is as follows:”…””}”(hjù  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Köhjì  hžhubj›  )”}”(hŒCPUS{$cpulist}”h]”hŒCPUS{$cpulist}”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Kùhjì  hžhubhØ)”}”(hŒ-Operators available to cpumask filtering are:”h]”hŒ-Operators available to cpumask filtering are:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kûhjì  hžhubhØ)”}”(hŒ& (intersection), ==, !=”h]”hŒ& (intersection), ==, !=”…””}”(hj#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kýhjì  hžhubhØ)”}”(hŒeFor example, this will filter events that have their .target_cpu field present
in the given cpumask::”h]”hŒdFor example, this will filter events that have their .target_cpu field present
in the given cpumask:”…””}”(hj1  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Kÿhjì  hžhubj›  )”}”(hŒtarget_cpu & CPUS{17-42}”h]”hŒtarget_cpu & CPUS{17-42}”…””}”hj?  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mhjì  hžhubeh}”(h]”Œexpression-syntax”ah ]”h"]”Œ5.1 expression syntax”ah$]”h&]”uh1h¡hjÍ  hžhhŸh¶h K¾ubh¢)”}”(hhh]”(h§)”}”(hŒ5.2 Setting filters”h]”hŒ5.2 Setting filters”…””}”(hjX  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjU  hžhhŸh¶h MubhØ)”}”(hŒpA filter for an individual event is set by writing a filter expression
to the 'filter' file for the given event.”h]”hŒtA filter for an individual event is set by writing a filter expression
to the â€˜filterâ€™ file for the given event.”…””}”(hjf  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MhjU  hžhubhØ)”}”(hŒFor example::”h]”hŒFor example:”…””}”(hjt  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M
hjU  hžhubj›  )”}”(hŒ]# cd /sys/kernel/tracing/events/sched/sched_wakeup
# echo "common_preempt_count > 4" > filter”h]”hŒ]# cd /sys/kernel/tracing/events/sched/sched_wakeup
# echo "common_preempt_count > 4" > filter”…””}”hj‚  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MhjU  hžhubhØ)”}”(hŒ"A slightly more involved example::”h]”hŒ!A slightly more involved example:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MhjU  hžhubj›  )”}”(hŒ# cd /sys/kernel/tracing/events/signal/signal_generate
# echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter”h]”hŒ# cd /sys/kernel/tracing/events/signal/signal_generate
# echo "((sig >= 10 && sig < 15) || sig == 17) && comm != bash" > filter”…””}”hjž  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MhjU  hžhubhØ)”}”(hŒÀIf there is an error in the expression, you'll get an 'Invalid
argument' error when setting it, and the erroneous string along with
an error message can be seen by looking at the filter e.g.::”h]”hŒÅIf there is an error in the expression, youâ€™ll get an â€˜Invalid
argumentâ€™ error when setting it, and the erroneous string along with
an error message can be seen by looking at the filter e.g.:”…””}”(hj¬  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MhjU  hžhubj›  )”}”(hX  # cd /sys/kernel/tracing/events/signal/signal_generate
# echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter
-bash: echo: write error: Invalid argument
# cat filter
((sig >= 10 && sig < 15) || dsig == 17) && comm != bash
^
parse_error: Field not found”h]”hX  # cd /sys/kernel/tracing/events/signal/signal_generate
# echo "((sig >= 10 && sig < 15) || dsig == 17) && comm != bash" > filter
-bash: echo: write error: Invalid argument
# cat filter
((sig >= 10 && sig < 15) || dsig == 17) && comm != bash
^
parse_error: Field not found”…””}”hjº  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MhjU  hžhubhØ)”}”(hŒ¶Currently the caret ('^') for an error always appears at the beginning of
the filter string; the error message should still be useful though
even without more accurate position info.”h]”hŒºCurrently the caret (â€˜^â€™) for an error always appears at the beginning of
the filter string; the error message should still be useful though
even without more accurate position info.”…””}”(hjÈ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M hjU  hžhubeh}”(h]”Œsetting-filters”ah ]”h"]”Œ5.2 setting filters”ah$]”h&]”uh1h¡hjÍ  hžhhŸh¶h Mubh¢)”}”(hhh]”(h§)”}”(hŒ5.2.1 Filter limitations”h]”hŒ5.2.1 Filter limitations”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÞ  hžhhŸh¶h M%ubhØ)”}”(hX¤  If a filter is placed on a string pointer ``(char *)`` that does not point
to a string on the ring buffer, but instead points to kernel or user space
memory, then, for safety reasons, at most 1024 bytes of the content is
copied onto a temporary buffer to do the compare. If the copy of the memory
faults (the pointer points to memory that should not be accessed), then the
string compare will be treated as not matching.”h]”(hŒ*If a filter is placed on a string pointer ”…””}”(hjï  hžhhŸNh Nubj  )”}”(hŒ``(char *)``”h]”hŒ(char *)”…””}”(hj÷  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1j  hjï  ubhXn   that does not point
to a string on the ring buffer, but instead points to kernel or user space
memory, then, for safety reasons, at most 1024 bytes of the content is
copied onto a temporary buffer to do the compare. If the copy of the memory
faults (the pointer points to memory that should not be accessed), then the
string compare will be treated as not matching.”…””}”(hjï  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M'hjÞ  hžhubeh}”(h]”Œfilter-limitations”ah ]”h"]”Œ5.2.1 filter limitations”ah$]”h&]”uh1h¡hjÍ  hžhhŸh¶h M%ubh¢)”}”(hhh]”(h§)”}”(hŒ5.3 Clearing filters”h]”hŒ5.3 Clearing filters”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h M/ubhØ)”}”(hŒITo clear the filter for an event, write a '0' to the event's filter
file.”h]”hŒOTo clear the filter for an event, write a â€˜0â€™ to the eventâ€™s filter
file.”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M1hj  hžhubhØ)”}”(hŒ_To clear the filters for all events in a subsystem, write a '0' to the
subsystem's filter file.”h]”hŒeTo clear the filters for all events in a subsystem, write a â€˜0â€™ to the
subsystemâ€™s filter file.”…””}”(hj6  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M4hj  hžhubeh}”(h]”Œclearing-filters”ah ]”h"]”Œ5.3 clearing filters”ah$]”h&]”uh1h¡hjÍ  hžhhŸh¶h M/ubh¢)”}”(hhh]”(h§)”}”(hŒ5.4 Subsystem filters”h]”hŒ5.4 Subsystem filters”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjL  hžhhŸh¶h M8ubhØ)”}”(hX   For convenience, filters for every event in a subsystem can be set or
cleared as a group by writing a filter expression into the filter file
at the root of the subsystem.  Note however, that if a filter for any
event within the subsystem lacks a field specified in the subsystem
filter, or if the filter can't be applied for any other reason, the
filter for that event will retain its previous setting.  This can
result in an unintended mixture of filters which could lead to
confusing (to the user who might think different filters are in
effect) trace output.  Only filters that reference just the common
fields can be guaranteed to propagate successfully to all events.”h]”hX¢  For convenience, filters for every event in a subsystem can be set or
cleared as a group by writing a filter expression into the filter file
at the root of the subsystem.  Note however, that if a filter for any
event within the subsystem lacks a field specified in the subsystem
filter, or if the filter canâ€™t be applied for any other reason, the
filter for that event will retain its previous setting.  This can
result in an unintended mixture of filters which could lead to
confusing (to the user who might think different filters are in
effect) trace output.  Only filters that reference just the common
fields can be guaranteed to propagate successfully to all events.”…””}”(hj]  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M:hjL  hžhubhØ)”}”(hŒOHere are a few subsystem filter examples that also illustrate the
above points:”h]”hŒOHere are a few subsystem filter examples that also illustrate the
above points:”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MEhjL  hžhubhØ)”}”(hŒ8Clear the filters on all events in the sched subsystem::”h]”hŒ7Clear the filters on all events in the sched subsystem:”…””}”(hjy  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MHhjL  hžhubj›  )”}”(hŒu# cd /sys/kernel/tracing/events/sched
# echo 0 > filter
# cat sched_switch/filter
none
# cat sched_wakeup/filter
none”h]”hŒu# cd /sys/kernel/tracing/events/sched
# echo 0 > filter
# cat sched_switch/filter
none
# cat sched_wakeup/filter
none”…””}”hj‡  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MJhjL  hžhubhØ)”}”(hŒvSet a filter using only common fields for all events in the sched
subsystem (all events end up with the same filter)::”h]”hŒuSet a filter using only common fields for all events in the sched
subsystem (all events end up with the same filter):”…””}”(hj•  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MQhjL  hžhubj›  )”}”(hŒ™# cd /sys/kernel/tracing/events/sched
# echo common_pid == 0 > filter
# cat sched_switch/filter
common_pid == 0
# cat sched_wakeup/filter
common_pid == 0”h]”hŒ™# cd /sys/kernel/tracing/events/sched
# echo common_pid == 0 > filter
# cat sched_switch/filter
common_pid == 0
# cat sched_wakeup/filter
common_pid == 0”…””}”hj£  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MThjL  hžhubhØ)”}”(hŒ£Attempt to set a filter using a non-common field for all events in the
sched subsystem (all events but those that have a prev_pid field retain
their old filters)::”h]”hŒ¢Attempt to set a filter using a non-common field for all events in the
sched subsystem (all events but those that have a prev_pid field retain
their old filters):”…””}”(hj±  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M[hjL  hžhubj›  )”}”(hŒ•# cd /sys/kernel/tracing/events/sched
# echo prev_pid == 0 > filter
# cat sched_switch/filter
prev_pid == 0
# cat sched_wakeup/filter
common_pid == 0”h]”hŒ•# cd /sys/kernel/tracing/events/sched
# echo prev_pid == 0 > filter
# cat sched_switch/filter
prev_pid == 0
# cat sched_wakeup/filter
common_pid == 0”…””}”hj¿  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M_hjL  hžhubeh}”(h]”Œsubsystem-filters”ah ]”h"]”Œ5.4 subsystem filters”ah$]”h&]”uh1h¡hjÍ  hžhhŸh¶h M8ubh¢)”}”(hhh]”(h§)”}”(hŒ5.5 PID filtering”h]”hŒ5.5 PID filtering”…””}”(hjØ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÕ  hžhhŸh¶h MgubhØ)”}”(hŒ½The set_event_pid file in the same directory as the top events directory
exists, will filter all events from tracing any task that does not have the
PID listed in the set_event_pid file.
::”h]”hŒºThe set_event_pid file in the same directory as the top events directory
exists, will filter all events from tracing any task that does not have the
PID listed in the set_event_pid file.”…””}”(hjæ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MihjÕ  hžhubj›  )”}”(hŒK# cd /sys/kernel/tracing
# echo $$ > set_event_pid
# echo 1 > events/enable”h]”hŒK# cd /sys/kernel/tracing
# echo $$ > set_event_pid
# echo 1 > events/enable”…””}”hjô  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MnhjÕ  hžhubhØ)”}”(hŒ,Will only trace events for the current task.”h]”hŒ,Will only trace events for the current task.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MrhjÕ  hžhubhØ)”}”(hŒGTo add more PIDs without losing the PIDs already included, use '>>'.
::”h]”hŒHTo add more PIDs without losing the PIDs already included, use â€˜>>â€™.”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MthjÕ  hžhubj›  )”}”(hŒ!# echo 123 244 1 >> set_event_pid”h]”hŒ!# echo 123 244 1 >> set_event_pid”…””}”hj	  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MwhjÕ  hžhubeh}”(h]”Œpid-filtering”ah ]”h"]”Œ5.5 pid filtering”ah$]”h&]”uh1h¡hjÍ  hžhhŸh¶h Mgubeh}”(h]”Œevent-filtering”ah ]”h"]”Œ5. event filtering”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K²ubh¢)”}”(hhh]”(h§)”}”(hŒ6. Event triggers”h]”hŒ6. Event triggers”…””}”(hj?	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj<	  hžhhŸh¶h M{ubhØ)”}”(hX›  Trace events can be made to conditionally invoke trigger 'commands'
which can take various forms and are described in detail below;
examples would be enabling or disabling other trace events or invoking
a stack trace whenever the trace event is hit.  Whenever a trace event
with attached triggers is invoked, the set of trigger commands
associated with that event is invoked.  Any given trigger can
additionally have an event filter of the same form as described in
section 5 (Event filtering) associated with it - the command will only
be invoked if the event being invoked passes the associated filter.
If no filter is associated with the trigger, it always passes.”h]”hXŸ  Trace events can be made to conditionally invoke trigger â€˜commandsâ€™
which can take various forms and are described in detail below;
examples would be enabling or disabling other trace events or invoking
a stack trace whenever the trace event is hit.  Whenever a trace event
with attached triggers is invoked, the set of trigger commands
associated with that event is invoked.  Any given trigger can
additionally have an event filter of the same form as described in
section 5 (Event filtering) associated with it - the command will only
be invoked if the event being invoked passes the associated filter.
If no filter is associated with the trigger, it always passes.”…””}”(hjM	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M}hj<	  hžhubhØ)”}”(hŒƒTriggers are added to and removed from a particular event by writing
trigger expressions to the 'trigger' file for the given event.”h]”hŒ‡Triggers are added to and removed from a particular event by writing
trigger expressions to the â€˜triggerâ€™ file for the given event.”…””}”(hj[	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mˆhj<	  hžhubhØ)”}”(hŒA given event can have any number of triggers associated with it,
subject to any restrictions that individual commands may have in that
regard.”h]”hŒA given event can have any number of triggers associated with it,
subject to any restrictions that individual commands may have in that
regard.”…””}”(hji	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M‹hj<	  hžhubhØ)”}”(hX  Event triggers are implemented on top of "soft" mode, which means that
whenever a trace event has one or more triggers associated with it,
the event is activated even if it isn't actually enabled, but is
disabled in a "soft" mode.  That is, the tracepoint will be called,
but just will not be traced, unless of course it's actually enabled.
This scheme allows triggers to be invoked even for events that aren't
enabled, and also allows the current event filter implementation to be
used for conditionally invoking triggers.”h]”hX  Event triggers are implemented on top of â€œsoftâ€ mode, which means that
whenever a trace event has one or more triggers associated with it,
the event is activated even if it isnâ€™t actually enabled, but is
disabled in a â€œsoftâ€ mode.  That is, the tracepoint will be called,
but just will not be traced, unless of course itâ€™s actually enabled.
This scheme allows triggers to be invoked even for events that arenâ€™t
enabled, and also allows the current event filter implementation to be
used for conditionally invoking triggers.”…””}”(hjw	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhj<	  hžhubhØ)”}”(hXH  The syntax for event triggers is roughly based on the syntax for
set_ftrace_filter 'ftrace filter commands' (see the 'Filter commands'
section of Documentation/trace/ftrace.rst), but there are major
differences and the implementation isn't currently tied to it in any
way, so beware about making generalizations between the two.”h]”hXR  The syntax for event triggers is roughly based on the syntax for
set_ftrace_filter â€˜ftrace filter commandsâ€™ (see the â€˜Filter commandsâ€™
section of Documentation/trace/ftrace.rst), but there are major
differences and the implementation isnâ€™t currently tied to it in any
way, so beware about making generalizations between the two.”…””}”(hj…	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M˜hj<	  hžhubj­  )”}”(hŒWriting into trace_marker (See Documentation/trace/ftrace.rst)
can also enable triggers that are written into
/sys/kernel/tracing/events/ftrace/print/trigger”h]”hØ)”}”(hŒWriting into trace_marker (See Documentation/trace/ftrace.rst)
can also enable triggers that are written into
/sys/kernel/tracing/events/ftrace/print/trigger”h]”hŒWriting into trace_marker (See Documentation/trace/ftrace.rst)
can also enable triggers that are written into
/sys/kernel/tracing/events/ftrace/print/trigger”…””}”(hj—	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MŸhj“	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j¬  hj<	  hžhhŸh¶h Nubh¢)”}”(hhh]”(h§)”}”(hŒ6.1 Expression syntax”h]”hŒ6.1 Expression syntax”…””}”(hj®	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj«	  hžhhŸh¶h M¤ubhØ)”}”(hŒATriggers are added by echoing the command to the 'trigger' file::”h]”hŒDTriggers are added by echoing the command to the â€˜triggerâ€™ file:”…””}”(hj¼	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¦hj«	  hžhubj›  )”}”(hŒ.# echo 'command[:count] [if filter]' > trigger”h]”hŒ.# echo 'command[:count] [if filter]' > trigger”…””}”hjÊ	  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M¨hj«	  hžhubhØ)”}”(hŒ^Triggers are removed by echoing the same command but starting with '!'
to the 'trigger' file::”h]”hŒeTriggers are removed by echoing the same command but starting with â€˜!â€™
to the â€˜triggerâ€™ file:”…””}”(hjØ	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mªhj«	  hžhubj›  )”}”(hŒ/# echo '!command[:count] [if filter]' > trigger”h]”hŒ/# echo '!command[:count] [if filter]' > trigger”…””}”hjæ	  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M­hj«	  hžhubhØ)”}”(hŒ˜The [if filter] part isn't used in matching commands when removing, so
leaving that off in a '!' command will accomplish the same thing as
having it in.”h]”hŒžThe [if filter] part isnâ€™t used in matching commands when removing, so
leaving that off in a â€˜!â€™ command will accomplish the same thing as
having it in.”…””}”(hjô	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¯hj«	  hžhubhØ)”}”(hŒWThe filter syntax is the same as that described in the 'Event
filtering' section above.”h]”hŒ[The filter syntax is the same as that described in the â€˜Event
filteringâ€™ section above.”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M³hj«	  hžhubhØ)”}”(hX  For ease of use, writing to the trigger file using '>' currently just
adds or removes a single trigger and there's no explicit '>>' support
('>' actually behaves like '>>') or truncation support to remove all
triggers (you have to use '!' for each one added.)”h]”hX  For ease of use, writing to the trigger file using â€˜>â€™ currently just
adds or removes a single trigger and thereâ€™s no explicit â€˜>>â€™ support
(â€˜>â€™ actually behaves like â€˜>>â€™) or truncation support to remove all
triggers (you have to use â€˜!â€™ for each one added.)”…””}”(hj
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¶hj«	  hžhubeh}”(h]”Œid1”ah ]”h"]”Œ6.1 expression syntax”ah$]”h&]”uh1h¡hj<	  hžhhŸh¶h M¤ubh¢)”}”(hhh]”(h§)”}”(hŒ6.2 Supported trigger commands”h]”hŒ6.2 Supported trigger commands”…””}”(hj)
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj&
  hžhhŸh¶h M¼ubhØ)”}”(hŒ%The following commands are supported:”h]”hŒ%The following commands are supported:”…””}”(hj7
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¾hj&
  hžhubj'  )”}”(hhh]”(j,  )”}”(hX  enable_event/disable_event

These commands can enable or disable another trace event whenever
the triggering event is hit.  When these commands are registered,
the other trace event is activated, but disabled in a "soft" mode.
That is, the tracepoint will be called, but just will not be traced.
The event tracepoint stays in this mode as long as there's a trigger
in effect that can trigger it.

For example, the following trigger causes kmalloc events to be
traced when a read system call is entered, and the :1 at the end
specifies that this enablement happens only once::

        # echo 'enable_event:kmem:kmalloc:1' > \
            /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger

The following trigger causes kmalloc events to stop being traced
when a read system call exits.  This disablement happens on every
read system call exit::

        # echo 'disable_event:kmem:kmalloc' > \
            /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger

The format is::

    enable_event:<system>:<event>[:count]
    disable_event:<system>:<event>[:count]

To remove the above commands::

        # echo '!enable_event:kmem:kmalloc:1' > \
            /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger

        # echo '!disable_event:kmem:kmalloc' > \
            /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger

Note that there can be any number of enable/disable_event triggers
per triggering event, but there can only be one trigger per
triggered event. e.g. sys_enter_read can have triggers enabling both
kmem:kmalloc and sched:sched_switch, but can't have two kmem:kmalloc
versions such as kmem:kmalloc and kmem:kmalloc:1 or 'kmem:kmalloc if
bytes_req == 256' and 'kmem:kmalloc if bytes_alloc == 256' (they
could be combined into a single filter on kmem:kmalloc though).
”h]”(hØ)”}”(hŒenable_event/disable_event”h]”hŒenable_event/disable_event”…””}”(hjL
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÀhjH
  ubhØ)”}”(hXo  These commands can enable or disable another trace event whenever
the triggering event is hit.  When these commands are registered,
the other trace event is activated, but disabled in a "soft" mode.
That is, the tracepoint will be called, but just will not be traced.
The event tracepoint stays in this mode as long as there's a trigger
in effect that can trigger it.”h]”hXu  These commands can enable or disable another trace event whenever
the triggering event is hit.  When these commands are registered,
the other trace event is activated, but disabled in a â€œsoftâ€ mode.
That is, the tracepoint will be called, but just will not be traced.
The event tracepoint stays in this mode as long as thereâ€™s a trigger
in effect that can trigger it.”…””}”(hjZ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÂhjH
  ubhØ)”}”(hŒ²For example, the following trigger causes kmalloc events to be
traced when a read system call is entered, and the :1 at the end
specifies that this enablement happens only once::”h]”hŒ±For example, the following trigger causes kmalloc events to be
traced when a read system call is entered, and the :1 at the end
specifies that this enablement happens only once:”…””}”(hjh
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÉhjH
  ubj›  )”}”(hŒg# echo 'enable_event:kmem:kmalloc:1' > \
    /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger”h]”hŒg# echo 'enable_event:kmem:kmalloc:1' > \
    /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger”…””}”hjv
  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÍhjH
  ubhØ)”}”(hŒšThe following trigger causes kmalloc events to stop being traced
when a read system call exits.  This disablement happens on every
read system call exit::”h]”hŒ™The following trigger causes kmalloc events to stop being traced
when a read system call exits.  This disablement happens on every
read system call exit:”…””}”(hj„
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÐhjH
  ubj›  )”}”(hŒe# echo 'disable_event:kmem:kmalloc' > \
    /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger”h]”hŒe# echo 'disable_event:kmem:kmalloc' > \
    /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger”…””}”hj’
  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÔhjH
  ubhØ)”}”(hŒThe format is::”h]”hŒThe format is:”…””}”(hj 
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M×hjH
  ubj›  )”}”(hŒLenable_event:<system>:<event>[:count]
disable_event:<system>:<event>[:count]”h]”hŒLenable_event:<system>:<event>[:count]
disable_event:<system>:<event>[:count]”…””}”hj®
  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÙhjH
  ubhØ)”}”(hŒTo remove the above commands::”h]”hŒTo remove the above commands:”…””}”(hj¼
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÜhjH
  ubj›  )”}”(hŒÐ# echo '!enable_event:kmem:kmalloc:1' > \
    /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger

# echo '!disable_event:kmem:kmalloc' > \
    /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger”h]”hŒÐ# echo '!enable_event:kmem:kmalloc:1' > \
    /sys/kernel/tracing/events/syscalls/sys_enter_read/trigger

# echo '!disable_event:kmem:kmalloc' > \
    /sys/kernel/tracing/events/syscalls/sys_exit_read/trigger”…””}”hjÊ
  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÞhjH
  ubhØ)”}”(hXÎ  Note that there can be any number of enable/disable_event triggers
per triggering event, but there can only be one trigger per
triggered event. e.g. sys_enter_read can have triggers enabling both
kmem:kmalloc and sched:sched_switch, but can't have two kmem:kmalloc
versions such as kmem:kmalloc and kmem:kmalloc:1 or 'kmem:kmalloc if
bytes_req == 256' and 'kmem:kmalloc if bytes_alloc == 256' (they
could be combined into a single filter on kmem:kmalloc though).”h]”hXØ  Note that there can be any number of enable/disable_event triggers
per triggering event, but there can only be one trigger per
triggered event. e.g. sys_enter_read can have triggers enabling both
kmem:kmalloc and sched:sched_switch, but canâ€™t have two kmem:kmalloc
versions such as kmem:kmalloc and kmem:kmalloc:1 or â€˜kmem:kmalloc if
bytes_req == 256â€™ and â€˜kmem:kmalloc if bytes_alloc == 256â€™ (they
could be combined into a single filter on kmem:kmalloc though).”…””}”(hjØ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MähjH
  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j+  hjE
  hžhhŸh¶h Nubj,  )”}”(hX*  stacktrace

This command dumps a stacktrace in the trace buffer whenever the
triggering event occurs.

For example, the following trigger dumps a stacktrace every time the
kmalloc tracepoint is hit::

        # echo 'stacktrace' > \
              /sys/kernel/tracing/events/kmem/kmalloc/trigger

The following trigger dumps a stacktrace the first 5 times a kmalloc
request happens with a size >= 64K::

        # echo 'stacktrace:5 if bytes_req >= 65536' > \
              /sys/kernel/tracing/events/kmem/kmalloc/trigger

The format is::

    stacktrace[:count]

To remove the above commands::

        # echo '!stacktrace' > \
              /sys/kernel/tracing/events/kmem/kmalloc/trigger

        # echo '!stacktrace:5 if bytes_req >= 65536' > \
              /sys/kernel/tracing/events/kmem/kmalloc/trigger

The latter can also be removed more simply by the following (without
the filter)::

        # echo '!stacktrace:5' > \
              /sys/kernel/tracing/events/kmem/kmalloc/trigger

Note that there can be only one stacktrace trigger per triggering
event.
”h]”(hØ)”}”(hŒ
stacktrace”h]”hŒ
stacktrace”…””}”(hjð
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mìhjì
  ubhØ)”}”(hŒYThis command dumps a stacktrace in the trace buffer whenever the
triggering event occurs.”h]”hŒYThis command dumps a stacktrace in the trace buffer whenever the
triggering event occurs.”…””}”(hjþ
  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mîhjì
  ubhØ)”}”(hŒ`For example, the following trigger dumps a stacktrace every time the
kmalloc tracepoint is hit::”h]”hŒ_For example, the following trigger dumps a stacktrace every time the
kmalloc tracepoint is hit:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mñhjì
  ubj›  )”}”(hŒM# echo 'stacktrace' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”h]”hŒM# echo 'stacktrace' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Môhjì
  ubhØ)”}”(hŒiThe following trigger dumps a stacktrace the first 5 times a kmalloc
request happens with a size >= 64K::”h]”hŒhThe following trigger dumps a stacktrace the first 5 times a kmalloc
request happens with a size >= 64K:”…””}”(hj(  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M÷hjì
  ubj›  )”}”(hŒe# echo 'stacktrace:5 if bytes_req >= 65536' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”h]”hŒe# echo 'stacktrace:5 if bytes_req >= 65536' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”…””}”hj6  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Múhjì
  ubhØ)”}”(hŒThe format is::”h]”hŒThe format is:”…””}”(hjD  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mýhjì
  ubj›  )”}”(hŒstacktrace[:count]”h]”hŒstacktrace[:count]”…””}”hjR  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mÿhjì
  ubhØ)”}”(hŒTo remove the above commands::”h]”hŒTo remove the above commands:”…””}”(hj`  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjì
  ubj›  )”}”(hŒ¶# echo '!stacktrace' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger

# echo '!stacktrace:5 if bytes_req >= 65536' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”h]”hŒ¶# echo '!stacktrace' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger

# echo '!stacktrace:5 if bytes_req >= 65536' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”…””}”hjn  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mhjì
  ubhØ)”}”(hŒRThe latter can also be removed more simply by the following (without
the filter)::”h]”hŒQThe latter can also be removed more simply by the following (without
the filter):”…””}”(hj|  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M	hjì
  ubj›  )”}”(hŒP# echo '!stacktrace:5' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”h]”hŒP# echo '!stacktrace:5' > \
      /sys/kernel/tracing/events/kmem/kmalloc/trigger”…””}”hjŠ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mhjì
  ubhØ)”}”(hŒHNote that there can be only one stacktrace trigger per triggering
event.”h]”hŒHNote that there can be only one stacktrace trigger per triggering
event.”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjì
  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j+  hjE
  hžhhŸh¶h Nubj,  )”}”(hX¦  snapshot

This command causes a snapshot to be triggered whenever the
triggering event occurs.

The following command creates a snapshot every time a block request
queue is unplugged with a depth > 1.  If you were tracing a set of
events or functions at the time, the snapshot trace buffer would
capture those events when the trigger event occurred::

        # echo 'snapshot if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

To only snapshot once::

        # echo 'snapshot:1 if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

To remove the above commands::

        # echo '!snapshot if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

        # echo '!snapshot:1 if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

Note that there can be only one snapshot trigger per triggering
event.
”h]”(hØ)”}”(hŒsnapshot”h]”hŒsnapshot”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhj¬  ubhØ)”}”(hŒTThis command causes a snapshot to be triggered whenever the
triggering event occurs.”h]”hŒTThis command causes a snapshot to be triggered whenever the
triggering event occurs.”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhj¬  ubhØ)”}”(hŒþThe following command creates a snapshot every time a block request
queue is unplugged with a depth > 1.  If you were tracing a set of
events or functions at the time, the snapshot trace buffer would
capture those events when the trigger event occurred::”h]”hŒýThe following command creates a snapshot every time a block request
queue is unplugged with a depth > 1.  If you were tracing a set of
events or functions at the time, the snapshot trace buffer would
capture those events when the trigger event occurred:”…””}”(hjÌ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhj¬  ubj›  )”}”(hŒ^# echo 'snapshot if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”h]”hŒ^# echo 'snapshot if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”…””}”hjÚ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mhj¬  ubhØ)”}”(hŒTo only snapshot once::”h]”hŒTo only snapshot once:”…””}”(hjè  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhj¬  ubj›  )”}”(hŒ`# echo 'snapshot:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”h]”hŒ`# echo 'snapshot:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”…””}”hjö  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M!hj¬  ubhØ)”}”(hŒTo remove the above commands::”h]”hŒTo remove the above commands:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M$hj¬  ubj›  )”}”(hŒÂ# echo '!snapshot if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger

# echo '!snapshot:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”h]”hŒÂ# echo '!snapshot if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger

# echo '!snapshot:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M&hj¬  ubhØ)”}”(hŒFNote that there can be only one snapshot trigger per triggering
event.”h]”hŒFNote that there can be only one snapshot trigger per triggering
event.”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M,hj¬  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j+  hjE
  hžhhŸh¶h Nubj,  )”}”(hXK  traceon/traceoff

These commands turn tracing on and off when the specified events are
hit. The parameter determines how many times the tracing system is
turned on and off. If unspecified, there is no limit.

The following command turns tracing off the first time a block
request queue is unplugged with a depth > 1.  If you were tracing a
set of events or functions at the time, you could then examine the
trace buffer to see the sequence of events that led up to the
trigger event::

        # echo 'traceoff:1 if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

To always disable tracing when nr_rq  > 1::

        # echo 'traceoff if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

To remove the above commands::

        # echo '!traceoff:1 if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

        # echo '!traceoff if nr_rq > 1' > \
              /sys/kernel/tracing/events/block/block_unplug/trigger

Note that there can be only one traceon or traceoff trigger per
triggering event.
”h]”(hØ)”}”(hŒtraceon/traceoff”h]”hŒtraceon/traceoff”…””}”(hj8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M/hj4  ubhØ)”}”(hŒ½These commands turn tracing on and off when the specified events are
hit. The parameter determines how many times the tracing system is
turned on and off. If unspecified, there is no limit.”•xö      h]”hŒ½These commands turn tracing on and off when the specified events are
hit. The parameter determines how many times the tracing system is
turned on and off. If unspecified, there is no limit.”…””}”(hjF  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M1hj4  ubhØ)”}”(hX  The following command turns tracing off the first time a block
request queue is unplugged with a depth > 1.  If you were tracing a
set of events or functions at the time, you could then examine the
trace buffer to see the sequence of events that led up to the
trigger event::”h]”hX  The following command turns tracing off the first time a block
request queue is unplugged with a depth > 1.  If you were tracing a
set of events or functions at the time, you could then examine the
trace buffer to see the sequence of events that led up to the
trigger event:”…””}”(hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M5hj4  ubj›  )”}”(hŒ`# echo 'traceoff:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”h]”hŒ`# echo 'traceoff:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”…””}”hjb  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M;hj4  ubhØ)”}”(hŒ+To always disable tracing when nr_rq  > 1::”h]”hŒ*To always disable tracing when nr_rq  > 1:”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M>hj4  ubj›  )”}”(hŒ^# echo 'traceoff if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”h]”hŒ^# echo 'traceoff if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”…””}”hj~  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M@hj4  ubhØ)”}”(hŒTo remove the above commands::”h]”hŒTo remove the above commands:”…””}”(hjŒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MChj4  ubj›  )”}”(hŒÂ# echo '!traceoff:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger

# echo '!traceoff if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”h]”hŒÂ# echo '!traceoff:1 if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger

# echo '!traceoff if nr_rq > 1' > \
      /sys/kernel/tracing/events/block/block_unplug/trigger”…””}”hjš  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MEhj4  ubhØ)”}”(hŒQNote that there can be only one traceon or traceoff trigger per
triggering event.”h]”hŒQNote that there can be only one traceon or traceoff trigger per
triggering event.”…””}”(hj¨  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MKhj4  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j+  hjE
  hžhhŸh¶h Nubj,  )”}”(hX*  hist

This command aggregates event hits into a hash table keyed on one or
more trace event format fields (or stacktrace) and a set of running
totals derived from one or more trace event format fields and/or
event counts (hitcount).

See Documentation/trace/histogram.rst for details and examples.
”h]”(hØ)”}”(hŒhist”h]”hŒhist”…””}”(hjÀ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MNhj¼  ubhØ)”}”(hŒâThis command aggregates event hits into a hash table keyed on one or
more trace event format fields (or stacktrace) and a set of running
totals derived from one or more trace event format fields and/or
event counts (hitcount).”h]”hŒâThis command aggregates event hits into a hash table keyed on one or
more trace event format fields (or stacktrace) and a set of running
totals derived from one or more trace event format fields and/or
event counts (hitcount).”…””}”(hjÎ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MPhj¼  ubhØ)”}”(hŒ?See Documentation/trace/histogram.rst for details and examples.”h]”hŒ?See Documentation/trace/histogram.rst for details and examples.”…””}”(hjÜ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MUhj¼  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1j+  hjE
  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”j  j‘  uh1j&  hŸh¶h MÀhj&
  hžhubeh}”(h]”Œsupported-trigger-commands”ah ]”h"]”Œ6.2 supported trigger commands”ah$]”h&]”uh1h¡hj<	  hžhhŸh¶h M¼ubeh}”(h]”Œevent-triggers”ah ]”h"]”Œ6. event triggers”ah$]”h&]”uh1h¡hh£hžhhŸh¶h M{ubh¢)”}”(hhh]”(h§)”}”(hŒ7. In-kernel trace event API”h]”hŒ7. In-kernel trace event API”…””}”(hj	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj  hžhhŸh¶h MXubhØ)”}”(hX
  In most cases, the command-line interface to trace events is more than
sufficient.  Sometimes, however, applications might find the need for
more complex relationships than can be expressed through a simple
series of linked command-line expressions, or putting together sets of
commands may be simply too cumbersome.  An example might be an
application that needs to 'listen' to the trace stream in order to
maintain an in-kernel state machine detecting, for instance, when an
illegal kernel state occurs in the scheduler.”h]”hX  In most cases, the command-line interface to trace events is more than
sufficient.  Sometimes, however, applications might find the need for
more complex relationships than can be expressed through a simple
series of linked command-line expressions, or putting together sets of
commands may be simply too cumbersome.  An example might be an
application that needs to â€˜listenâ€™ to the trace stream in order to
maintain an in-kernel state machine detecting, for instance, when an
illegal kernel state occurs in the scheduler.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MZhj  hžhubhØ)”}”(hX
  The trace event subsystem provides an in-kernel API allowing modules
or other kernel code to generate user-defined 'synthetic' events at
will, which can be used to either augment the existing trace stream
and/or signal that a particular important state has occurred.”h]”hX  The trace event subsystem provides an in-kernel API allowing modules
or other kernel code to generate user-defined â€˜syntheticâ€™ events at
will, which can be used to either augment the existing trace stream
and/or signal that a particular important state has occurred.”…””}”(hj%  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mchj  hžhubhØ)”}”(hŒSA similar in-kernel API is also available for creating kprobe and
kretprobe events.”h]”hŒSA similar in-kernel API is also available for creating kprobe and
kretprobe events.”…””}”(hj3  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhhj  hžhubhØ)”}”(hŒêBoth the synthetic event and k/ret/probe event APIs are built on top
of a lower-level "dynevent_cmd" event command API, which is also
available for more specialized applications, or as the basis of other
higher-level trace event APIs.”h]”hŒîBoth the synthetic event and k/ret/probe event APIs are built on top
of a lower-level â€œdynevent_cmdâ€ event command API, which is also
available for more specialized applications, or as the basis of other
higher-level trace event APIs.”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mkhj  hžhubhØ)”}”(hŒOThe API provided for these purposes is describe below and allows the
following:”h]”hŒOThe API provided for these purposes is describe below and allows the
following:”…””}”(hjO  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mphj  hžhubj!  )”}”(hŒÃ- dynamically creating synthetic event definitions
- dynamically creating kprobe and kretprobe event definitions
- tracing synthetic events from in-kernel code
- the low-level "dynevent_cmd" API
”h]”j'  )”}”(hhh]”(j,  )”}”(hŒ0dynamically creating synthetic event definitions”h]”hØ)”}”(hjf  h]”hŒ0dynamically creating synthetic event definitions”…””}”(hjh  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mshjd  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hja  ubj,  )”}”(hŒ;dynamically creating kprobe and kretprobe event definitions”h]”hØ)”}”(hj}  h]”hŒ;dynamically creating kprobe and kretprobe event definitions”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mthj{  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hja  ubj,  )”}”(hŒ,tracing synthetic events from in-kernel code”h]”hØ)”}”(hj”  h]”hŒ,tracing synthetic events from in-kernel code”…””}”(hj–  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Muhj’  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hja  ubj,  )”}”(hŒ!the low-level "dynevent_cmd" API
”h]”hØ)”}”(hŒ the low-level "dynevent_cmd" API”h]”hŒ$the low-level â€œdynevent_cmdâ€ API”…””}”(hj­  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mvhj©  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j+  hja  ubeh}”(h]”h ]”h"]”h$]”h&]”j  j‘  uh1j&  hŸh¶h Mshj]  ubah}”(h]”h ]”h"]”h$]”h&]”uh1j   hŸh¶h Mshj  hžhubh¢)”}”(hhh]”(h§)”}”(hŒ37.1 Dyamically creating synthetic event definitions”h]”hŒ37.1 Dyamically creating synthetic event definitions”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjÍ  hžhhŸh¶h MyubhØ)”}”(hŒbThere are a couple ways to create a new synthetic event from a kernel
module or other kernel code.”h]”hŒbThere are a couple ways to create a new synthetic event from a kernel
module or other kernel code.”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M{hjÍ  hžhubhØ)”}”(hXR  The first creates the event in one step, using synth_event_create().
In this method, the name of the event to create and an array defining
the fields is supplied to synth_event_create().  If successful, a
synthetic event with that name and fields will exist following that
call.  For example, to create a new "schedtest" synthetic event::”h]”hXU  The first creates the event in one step, using synth_event_create().
In this method, the name of the event to create and an array defining
the fields is supplied to synth_event_create().  If successful, a
synthetic event with that name and fields will exist following that
call.  For example, to create a new â€œschedtestâ€ synthetic event:”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M~hjÍ  hžhubj›  )”}”(hŒtret = synth_event_create("schedtest", sched_fields,
                         ARRAY_SIZE(sched_fields), THIS_MODULE);”h]”hŒtret = synth_event_create("schedtest", sched_fields,
                         ARRAY_SIZE(sched_fields), THIS_MODULE);”…””}”hjú  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M„hjÍ  hžhubhØ)”}”(hŒThe sched_fields param in this example points to an array of struct
synth_field_desc, each of which describes an event field by type and
name::”h]”hŒŽThe sched_fields param in this example points to an array of struct
synth_field_desc, each of which describes an event field by type and
name:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M‡hjÍ  hžhubj›  )”}”(hXå  static struct synth_field_desc sched_fields[] = {
      { .type = "pid_t",              .name = "next_pid_field" },
      { .type = "char[16]",           .name = "next_comm_field" },
      { .type = "u64",                .name = "ts_ns" },
      { .type = "u64",                .name = "ts_ms" },
      { .type = "unsigned int",       .name = "cpu" },
      { .type = "char[64]",           .name = "my_string_field" },
      { .type = "int",                .name = "my_int_field" },
};”h]”hXå  static struct synth_field_desc sched_fields[] = {
      { .type = "pid_t",              .name = "next_pid_field" },
      { .type = "char[16]",           .name = "next_comm_field" },
      { .type = "u64",                .name = "ts_ns" },
      { .type = "u64",                .name = "ts_ms" },
      { .type = "unsigned int",       .name = "cpu" },
      { .type = "char[64]",           .name = "my_string_field" },
      { .type = "int",                .name = "my_int_field" },
};”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M‹hjÍ  hžhubhØ)”}”(hŒ+See synth_field_size() for available types.”h]”hŒ+See synth_field_size() for available types.”…””}”(hj$  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M•hjÍ  hžhubhØ)”}”(hŒIIf field_name contains [n], the field is considered to be a static array.”h]”hŒIIf field_name contains [n], the field is considered to be a static array.”…””}”(hj2  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M—hjÍ  hžhubhØ)”}”(hŒªIf field_names contains[] (no subscript), the field is considered to
be a dynamic array, which will only take as much space in the event as
is required to hold the array.”h]”hŒªIf field_names contains[] (no subscript), the field is considered to
be a dynamic array, which will only take as much space in the event as
is required to hold the array.”…””}”(hj@  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M™hjÍ  hžhubhØ)”}”(hX  Because space for an event is reserved before assigning field values
to the event, using dynamic arrays implies that the piecewise
in-kernel API described below can't be used with dynamic arrays.  The
other non-piecewise in-kernel APIs can, however, be used with dynamic
arrays.”h]”hX  Because space for an event is reserved before assigning field values
to the event, using dynamic arrays implies that the piecewise
in-kernel API described below canâ€™t be used with dynamic arrays.  The
other non-piecewise in-kernel APIs can, however, be used with dynamic
arrays.”…””}”(hjN  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MhjÍ  hžhubhØ)”}”(hŒÑIf the event is created from within a module, a pointer to the module
must be passed to synth_event_create().  This will ensure that the
trace buffer won't contain unreadable events when the module is
removed.”h]”hŒÓIf the event is created from within a module, a pointer to the module
must be passed to synth_event_create().  This will ensure that the
trace buffer wonâ€™t contain unreadable events when the module is
removed.”…””}”(hj\  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M£hjÍ  hžhubhØ)”}”(hŒNAt this point, the event object is ready to be used for generating new
events.”h]”hŒNAt this point, the event object is ready to be used for generating new
events.”…””}”(hjj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¨hjÍ  hžhubhØ)”}”(hŒµIn the second method, the event is created in several steps.  This
allows events to be created dynamically and without the need to create
and populate an array of fields beforehand.”h]”hŒµIn the second method, the event is created in several steps.  This
allows events to be created dynamically and without the need to create
and populate an array of fields beforehand.”…””}”(hjx  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M«hjÍ  hžhubhØ)”}”(hX|  To use this method, an empty or partially empty synthetic event should
first be created using synth_event_gen_cmd_start() or
synth_event_gen_cmd_array_start().  For synth_event_gen_cmd_start(),
the name of the event along with one or more pairs of args each pair
representing a 'type field_name;' field specification should be
supplied.  For synth_event_gen_cmd_array_start(), the name of the
event along with an array of struct synth_field_desc should be
supplied. Before calling synth_event_gen_cmd_start() or
synth_event_gen_cmd_array_start(), the user should create and
initialize a dynevent_cmd object using synth_event_cmd_init().”h]”hX€  To use this method, an empty or partially empty synthetic event should
first be created using synth_event_gen_cmd_start() or
synth_event_gen_cmd_array_start().  For synth_event_gen_cmd_start(),
the name of the event along with one or more pairs of args each pair
representing a â€˜type field_name;â€™ field specification should be
supplied.  For synth_event_gen_cmd_array_start(), the name of the
event along with an array of struct synth_field_desc should be
supplied. Before calling synth_event_gen_cmd_start() or
synth_event_gen_cmd_array_start(), the user should create and
initialize a dynevent_cmd object using synth_event_cmd_init().”…””}”(hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¯hjÍ  hžhubhØ)”}”(hŒJFor example, to create a new "schedtest" synthetic event with two
fields::”h]”hŒMFor example, to create a new â€œschedtestâ€ synthetic event with two
fields:”…””}”(hj”  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MºhjÍ  hžhubj›  )”}”(hX­  struct dynevent_cmd cmd;
char *buf;

/* Create a buffer to hold the generated command */
buf = kzalloc(MAX_DYNEVENT_CMD_LEN, GFP_KERNEL);

/* Before generating the command, initialize the cmd object */
synth_event_cmd_init(&cmd, buf, MAX_DYNEVENT_CMD_LEN);

ret = synth_event_gen_cmd_start(&cmd, "schedtest", THIS_MODULE,
                                "pid_t", "next_pid_field",
                                "u64", "ts_ns");”h]”hX­  struct dynevent_cmd cmd;
char *buf;

/* Create a buffer to hold the generated command */
buf = kzalloc(MAX_DYNEVENT_CMD_LEN, GFP_KERNEL);

/* Before generating the command, initialize the cmd object */
synth_event_cmd_init(&cmd, buf, MAX_DYNEVENT_CMD_LEN);

ret = synth_event_gen_cmd_start(&cmd, "schedtest", THIS_MODULE,
                                "pid_t", "next_pid_field",
                                "u64", "ts_ns");”…””}”hj¢  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M½hjÍ  hžhubhØ)”}”(hŒaAlternatively, using an array of struct synth_field_desc fields
containing the same information::”h]”hŒ`Alternatively, using an array of struct synth_field_desc fields
containing the same information:”…””}”(hj°  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÊhjÍ  hžhubj›  )”}”(hŒ~ret = synth_event_gen_cmd_array_start(&cmd, "schedtest", THIS_MODULE,
                                      fields, n_fields);”h]”hŒ~ret = synth_event_gen_cmd_array_start(&cmd, "schedtest", THIS_MODULE,
                                      fields, n_fields);”…””}”hj¾  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÍhjÍ  hžhubhØ)”}”(hX6  Once the synthetic event object has been created, it can then be
populated with more fields.  Fields are added one by one using
synth_event_add_field(), supplying the dynevent_cmd object, a field
type, and a field name.  For example, to add a new int field named
"intfield", the following call should be made::”h]”hX9  Once the synthetic event object has been created, it can then be
populated with more fields.  Fields are added one by one using
synth_event_add_field(), supplying the dynevent_cmd object, a field
type, and a field name.  For example, to add a new int field named
â€œintfieldâ€, the following call should be made:”…””}”(hjÌ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÐhjÍ  hžhubj›  )”}”(hŒ5ret = synth_event_add_field(&cmd, "int", "intfield");”h]”hŒ5ret = synth_event_add_field(&cmd, "int", "intfield");”…””}”hjÚ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÖhjÍ  hžhubhØ)”}”(hŒnSee synth_field_size() for available types. If field_name contains [n]
the field is considered to be an array.”h]”hŒnSee synth_field_size() for available types. If field_name contains [n]
the field is considered to be an array.”…””}”(hjè  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MØhjÍ  hžhubhØ)”}”(hŒ«A group of fields can also be added all at once using an array of
synth_field_desc with add_synth_fields().  For example, this would add
just the first four sched_fields::”h]”hŒªA group of fields can also be added all at once using an array of
synth_field_desc with add_synth_fields().  For example, this would add
just the first four sched_fields:”…””}”(hjö  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÛhjÍ  hžhubj›  )”}”(hŒ4ret = synth_event_add_fields(&cmd, sched_fields, 4);”h]”hŒ4ret = synth_event_add_fields(&cmd, sched_fields, 4);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MßhjÍ  hžhubhØ)”}”(hŒ«If you already have a string of the form 'type field_name',
synth_event_add_field_str() can be used to add it as-is; it will
also automatically append a ';' to the string.”h]”hŒ³If you already have a string of the form â€˜type field_nameâ€™,
synth_event_add_field_str() can be used to add it as-is; it will
also automatically append a â€˜;â€™ to the string.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MáhjÍ  hžhubhØ)”}”(hŒ…Once all the fields have been added, the event should be finalized and
registered by calling the synth_event_gen_cmd_end() function::”h]”hŒ„Once all the fields have been added, the event should be finalized and
registered by calling the synth_event_gen_cmd_end() function:”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MåhjÍ  hžhubj›  )”}”(hŒ$ret = synth_event_gen_cmd_end(&cmd);”h]”hŒ$ret = synth_event_gen_cmd_end(&cmd);”…””}”hj.  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MèhjÍ  hžhubhØ)”}”(hŒKAt this point, the event object is ready to be used for tracing new
events.”h]”hŒKAt this point, the event object is ready to be used for tracing new
events.”…””}”(hj<  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MêhjÍ  hžhubeh}”(h]”Œ/dyamically-creating-synthetic-event-definitions”ah ]”h"]”Œ37.1 dyamically creating synthetic event definitions”ah$]”h&]”uh1h¡hj  hžhhŸh¶h Myubh¢)”}”(hhh]”(h§)”}”(hŒ07.2 Tracing synthetic events from in-kernel code”h]”hŒ07.2 Tracing synthetic events from in-kernel code”…””}”(hjU  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjR  hžhhŸh¶h MîubhØ)”}”(hXã  To trace a synthetic event, there are several options.  The first
option is to trace the event in one call, using synth_event_trace()
with a variable number of values, or synth_event_trace_array() with an
array of values to be set.  A second option can be used to avoid the
need for a pre-formed array of values or list of arguments, via
synth_event_trace_start() and synth_event_trace_end() along with
synth_event_add_next_val() or synth_event_add_val() to add the values
piecewise.”h]”hXã  To trace a synthetic event, there are several options.  The first
option is to trace the event in one call, using synth_event_trace()
with a variable number of values, or synth_event_trace_array() with an
array of values to be set.  A second option can be used to avoid the
need for a pre-formed array of values or list of arguments, via
synth_event_trace_start() and synth_event_trace_end() along with
synth_event_add_next_val() or synth_event_add_val() to add the values
piecewise.”…””}”(hjc  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MðhjR  hžhubeh}”(h]”Œ,tracing-synthetic-events-from-in-kernel-code”ah ]”h"]”Œ07.2 tracing synthetic events from in-kernel code”ah$]”h&]”uh1h¡hj  hžhhŸh¶h Mîubh¢)”}”(hhh]”(h§)”}”(hŒ+7.2.1 Tracing a synthetic event all at once”h]”hŒ+7.2.1 Tracing a synthetic event all at once”…””}”(hj|  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjy  hžhhŸh¶h MúubhØ)”}”(hŒsTo trace a synthetic event all at once, the synth_event_trace() or
synth_event_trace_array() functions can be used.”h]”hŒsTo trace a synthetic event all at once, the synth_event_trace() or
synth_event_trace_array() functions can be used.”…””}”(hjŠ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mühjy  hžhubhØ)”}”(hX  The synth_event_trace() function is passed the trace_event_file
representing the synthetic event (which can be retrieved using
trace_get_event_file() using the synthetic event name, "synthetic" as
the system name, and the trace instance name (NULL if using the global
trace array)), along with an variable number of u64 args, one for each
synthetic event field, and the number of values being passed.”h]”hX”  The synth_event_trace() function is passed the trace_event_file
representing the synthetic event (which can be retrieved using
trace_get_event_file() using the synthetic event name, â€œsyntheticâ€ as
the system name, and the trace instance name (NULL if using the global
trace array)), along with an variable number of u64 args, one for each
synthetic event field, and the number of values being passed.”…””}”(hj˜  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mÿhjy  hžhubhØ)”}”(hŒtSo, to trace an event corresponding to the synthetic event definition
above, code like the following could be used::”h]”hŒsSo, to trace an event corresponding to the synthetic event definition
above, code like the following could be used:”…””}”(hj¦  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjy  hžhubj›  )”}”(hXÛ  ret = synth_event_trace(create_synth_test, 7, /* number of values */
                        444,             /* next_pid_field */
                        (u64)"clackers", /* next_comm_field */
                        1000000,         /* ts_ns */
                        1000,            /* ts_ms */
                        smp_processor_id(),/* cpu */
                        (u64)"Thneed",   /* my_string_field */
                        999);            /* my_int_field */”h]”hXÛ  ret = synth_event_trace(create_synth_test, 7, /* number of values */
                        444,             /* next_pid_field */
                        (u64)"clackers", /* next_comm_field */
                        1000000,         /* ts_ns */
                        1000,            /* ts_ms */
                        smp_processor_id(),/* cpu */
                        (u64)"Thneed",   /* my_string_field */
                        999);            /* my_int_field */”…””}”hj´  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M	hjy  hžhubhØ)”}”(hŒ¹All vals should be cast to u64, and string vals are just pointers to
strings, cast to u64.  Strings will be copied into space reserved in
the event for the string, using these pointers.”h]”hŒ¹All vals should be cast to u64, and string vals are just pointers to
strings, cast to u64.  Strings will be copied into space reserved in
the event for the string, using these pointers.”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjy  hžhubhØ)”}”(hX  Alternatively, the synth_event_trace_array() function can be used to
accomplish the same thing.  It is passed the trace_event_file
representing the synthetic event (which can be retrieved using
trace_get_event_file() using the synthetic event name, "synthetic" as
the system name, and the trace instance name (NULL if using the global
trace array)), along with an array of u64, one for each synthetic
event field.”h]”hX¡  Alternatively, the synth_event_trace_array() function can be used to
accomplish the same thing.  It is passed the trace_event_file
representing the synthetic event (which can be retrieved using
trace_get_event_file() using the synthetic event name, â€œsyntheticâ€ as
the system name, and the trace instance name (NULL if using the global
trace array)), along with an array of u64, one for each synthetic
event field.”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjy  hžhubhØ)”}”(hŒpTo trace an event corresponding to the synthetic event definition
above, code like the following could be used::”h]”hŒoTo trace an event corresponding to the synthetic event definition
above, code like the following could be used:”…””}”(hjÞ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjy  hžhubj›  )”}”(hXc  u64 vals[7];

vals[0] = 777;                  /* next_pid_field */
vals[1] = (u64)"tiddlywinks";   /* next_comm_field */
vals[2] = 1000000;              /* ts_ns */
vals[3] = 1000;                 /* ts_ms */
vals[4] = smp_processor_id();   /* cpu */
vals[5] = (u64)"thneed";        /* my_string_field */
vals[6] = 398;                  /* my_int_field */”h]”hXc  u64 vals[7];

vals[0] = 777;                  /* next_pid_field */
vals[1] = (u64)"tiddlywinks";   /* next_comm_field */
vals[2] = 1000000;              /* ts_ns */
vals[3] = 1000;                 /* ts_ms */
vals[4] = smp_processor_id();   /* cpu */
vals[5] = (u64)"thneed";        /* my_string_field */
vals[6] = 398;                  /* my_int_field */”…””}”hjì  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M!hjy  hžhubhØ)”}”(hŒ·The 'vals' array is just an array of u64, the number of which must
match the number of field in the synthetic event, and which must be in
the same order as the synthetic event fields.”h]”hŒ»The â€˜valsâ€™ array is just an array of u64, the number of which must
match the number of field in the synthetic event, and which must be in
the same order as the synthetic event fields.”…””}”(hjú  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M+hjy  hžhubhØ)”}”(hŒ¹All vals should be cast to u64, and string vals are just pointers to
strings, cast to u64.  Strings will be copied into space reserved in
the event for the string, using these pointers.”h]”hŒ¹All vals should be cast to u64, and string vals are just pointers to
strings, cast to u64.  Strings will be copied into space reserved in
the event for the string, using these pointers.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M/hjy  hžhubhØ)”}”(hXK  In order to trace a synthetic event, a pointer to the trace event file
is needed.  The trace_get_event_file() function can be used to get
it - it will find the file in the given trace instance (in this case
NULL since the top trace array is being used) while at the same time
preventing the instance containing it from going away::”h]”hXJ  In order to trace a synthetic event, a pointer to the trace event file
is needed.  The trace_get_event_file() function can be used to get
it - it will find the file in the given trace instance (in this case
NULL since the top trace array is being used) while at the same time
preventing the instance containing it from going away:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M3hjy  hžhubj›  )”}”(hŒxschedtest_event_file = trace_get_event_file(NULL, "synthetic",
                                            "schedtest");”h]”hŒxschedtest_event_file = trace_get_event_file(NULL, "synthetic",
                                            "schedtest");”…””}”hj$  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M9hjy  hžhubhØ)”}”(hŒ…Before tracing the event, it should be enabled in some way, otherwise
the synthetic event won't actually show up in the trace buffer.”h]”hŒ‡Before tracing the event, it should be enabled in some way, otherwise
the synthetic event wonâ€™t actually show up in the trace buffer.”…””}”(hj2  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M<hjy  hžhubhØ)”}”(hŒÆTo enable a synthetic event from the kernel, trace_array_set_clr_event()
can be used (which is not specific to synthetic events, so does need
the "synthetic" system name to be specified explicitly).”h]”hŒÊTo enable a synthetic event from the kernel, trace_array_set_clr_event()
can be used (which is not specific to synthetic events, so does need
the â€œsyntheticâ€ system name to be specified explicitly).”…””}”(hj@  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M?hjy  hžhubhØ)”}”(hŒ(To enable the event, pass 'true' to it::”h]”hŒ+To enable the event, pass â€˜trueâ€™ to it:”…””}”(hjN  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MChjy  hžhubj›  )”}”(hŒntrace_array_set_clr_event(schedtest_event_file->tr,
                          "synthetic", "schedtest", true);”h]”hŒntrace_array_set_clr_event(schedtest_event_file->tr,
                          "synthetic", "schedtest", true);”…””}”hj\  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MEhjy  hžhubhØ)”}”(hŒTo disable it pass false::”h]”hŒTo disable it pass false:”…””}”(hjj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MHhjy  hžhubj›  )”}”(hŒotrace_array_set_clr_event(schedtest_event_file->tr,
                          "synthetic", "schedtest", false);”h]”hŒotrace_array_set_clr_event(schedtest_event_file->tr,
                          "synthetic", "schedtest", false);”…””}”hjx  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MJhjy  hžhubhØ)”}”(hŒ„Finally, synth_event_trace_array() can be used to actually trace the
event, which should be visible in the trace buffer afterwards::”h]”hŒƒFinally, synth_event_trace_array() can be used to actually trace the
event, which should be visible in the trace buffer afterwards:”…””}”(hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MMhjy  hžhubj›  )”}”(hŒjret = synth_event_trace_array(schedtest_event_file, vals,
                              ARRAY_SIZE(vals));”h]”hŒjret = synth_event_trace_array(schedtest_event_file, vals,
                              ARRAY_SIZE(vals));”…””}”hj”  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MPhjy  hžhubhØ)”}”(hŒ‡To remove the synthetic event, the event should be disabled, and the
trace instance should be 'put' back using trace_put_event_file()::”h]”hŒŠTo remove the synthetic event, the event should be disabled, and the
trace instance should be â€˜putâ€™ back using trace_put_event_file():”…””}”(hj¢  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MShjy  hžhubj›  )”}”(hŒ›trace_array_set_clr_event(schedtest_event_file->tr,
                          "synthetic", "schedtest", false);
trace_put_event_file(schedtest_event_file);”h]”hŒ›trace_array_set_clr_event(schedtest_event_file->tr,
                          "synthetic", "schedtest", false);
trace_put_event_file(schedtest_event_file);”…””}”hj°  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MVhjy  hžhubhØ)”}”(hŒWIf those have been successful, synth_event_delete() can be called to
remove the event::”h]”hŒVIf those have been successful, synth_event_delete() can be called to
remove the event:”…””}”(hj¾  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MZhjy  hžhubj›  )”}”(hŒ&ret = synth_event_delete("schedtest");”h]”hŒ&ret = synth_event_delete("schedtest");”…””}”hjÌ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M]hjy  hžhubeh}”(h]”Œ%tracing-a-synthetic-event-all-at-once”ah ]”h"]”Œ+7.2.1 tracing a synthetic event all at once”ah$]”h&]”uh1h¡hj  hžhhŸh¶h Múubh¢)”}”(hhh]”(h§)”}”(hŒ)7.2.2 Tracing a synthetic event piecewise”h]”hŒ)7.2.2 Tracing a synthetic event piecewise”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjâ  hžhhŸh¶h M`ubhØ)”}”(hŒ•To trace a synthetic using the piecewise method described above, the
synth_event_trace_start() function is used to 'open' the synthetic
event trace::”h]”hŒ˜To trace a synthetic using the piecewise method described above, the
synth_event_trace_start() function is used to â€˜openâ€™ the synthetic
event trace:”…””}”(hjó  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mbhjâ  hžhubj›  )”}”(hŒostruct synth_event_trace_state trace_state;

ret = synth_event_trace_start(schedtest_event_file, &trace_state);”h]”hŒostruct synth_event_trace_state trace_state;

ret = synth_event_trace_start(schedtest_event_file, &trace_state);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mfhjâ  hžhubhØ)”}”(hX
  It's passed the trace_event_file representing the synthetic event
using the same methods as described above, along with a pointer to a
struct synth_event_trace_state object, which will be zeroed before use and
used to maintain state between this and following calls.”h]”hX  Itâ€™s passed the trace_event_file representing the synthetic event
using the same methods as described above, along with a pointer to a
struct synth_event_trace_state object, which will be zeroed before use and
used to maintain state between this and following calls.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mjhjâ  hžhubhØ)”}”(hXc  Once the event has been opened, which means space for it has been
reserved in the trace buffer, the individual fields can be set.  There
are two ways to do that, either one after another for each field in
the event, which requires no lookups, or by name, which does.  The
tradeoff is flexibility in doing the assignments vs the cost of a
lookup per field.”h]”hXc  Once the event has been opened, which means space for it has been
reserved in the trace buffer, the individual fields can be set.  There
are two ways to do that, either one after another for each field in
the event, which requires no lookups, or by name, which does.  The
tradeoff is flexibility in doing the assignments vs the cost of a
lookup per field.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mohjâ  hžhubhØ)”}”(hX  To assign the values one after the other without lookups,
synth_event_add_next_val() should be used.  Each call is passed the
same synth_event_trace_state object used in the synth_event_trace_start(),
along with the value to set the next field in the event.  After each
field is set, the 'cursor' points to the next field, which will be set
by the subsequent call, continuing until all the fields have been set
in order.  The same sequence of calls as in the above examples using
this method would be (without error-handling code)::”h]”hX  To assign the values one after the other without lookups,
synth_event_add_next_val() should be used.  Each call is passed the
same synth_event_trace_state object used in the synth_event_trace_start(),
along with the value to set the next field in the event.  After each
field is set, the â€˜cursorâ€™ points to the next field, which will be set
by the subsequent call, continuing until all the fields have been set
in order.  The same sequence of calls as in the above examples using
this method would be (without error-handling code):”…””}”(hj+  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mvhjâ  hžhubj›  )”}”(hX  /* next_pid_field */
ret = synth_event_add_next_val(777, &trace_state);

/* next_comm_field */
ret = synth_event_add_next_val((u64)"slinky", &trace_state);

/* ts_ns */
ret = synth_event_add_next_val(1000000, &trace_state);

/* ts_ms */
ret = synth_event_add_next_val(1000, &trace_state);

/* cpu */
ret = synth_event_add_next_val(smp_processor_id(), &trace_state);

/* my_string_field */
ret = synth_event_add_next_val((u64)"thneed_2.01", &trace_state);

/* my_int_field */
ret = synth_event_add_next_val(395, &trace_state);”h]”hX  /* next_pid_field */
ret = synth_event_add_next_val(777, &trace_state);

/* next_comm_field */
ret = synth_event_add_next_val((u64)"slinky", &trace_state);

/* ts_ns */
ret = synth_event_add_next_val(1000000, &trace_state);

/* ts_ms */
ret = synth_event_add_next_val(1000, &trace_state);

/* cpu */
ret = synth_event_add_next_val(smp_processor_id(), &trace_state);

/* my_string_field */
ret = synth_event_add_next_val((u64)"thneed_2.01", &trace_state);

/* my_int_field */
ret = synth_event_add_next_val(395, &trace_state);”…””}”hj9  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mhjâ  hžhubhØ)”}”(hXf  To assign the values in any order, synth_event_add_val() should be
used.  Each call is passed the same synth_event_trace_state object used in
the synth_event_trace_start(), along with the field name of the field
to set and the value to set it to.  The same sequence of calls as in
the above examples using this method would be (without error-handling
code)::”h]”hXe  To assign the values in any order, synth_event_add_val() should be
used.  Each call is passed the same synth_event_trace_state object used in
the synth_event_trace_start(), along with the field name of the field
to set and the value to set it to.  The same sequence of calls as in
the above examples using this method would be (without error-handling
code):”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M”hjâ  hžhubj›  )”}”(hX  ret = synth_event_add_val("next_pid_field", 777, &trace_state);
ret = synth_event_add_val("next_comm_field", (u64)"silly putty",
                          &trace_state);
ret = synth_event_add_val("ts_ns", 1000000, &trace_state);
ret = synth_event_add_val("ts_ms", 1000, &trace_state);
ret = synth_event_add_val("cpu", smp_processor_id(), &trace_state);
ret = synth_event_add_val("my_string_field", (u64)"thneed_9",
                          &trace_state);
ret = synth_event_add_val("my_int_field", 3999, &trace_state);”h]”hX  ret = synth_event_add_val("next_pid_field", 777, &trace_state);
ret = synth_event_add_val("next_comm_field", (u64)"silly putty",
                          &trace_state);
ret = synth_event_add_val("ts_ns", 1000000, &trace_state);
ret = synth_event_add_val("ts_ms", 1000, &trace_state);
ret = synth_event_add_val("cpu", smp_processor_id(), &trace_state);
ret = synth_event_add_val("my_string_field", (u64)"thneed_9",
                          &trace_state);
ret = synth_event_add_val("my_int_field", 3999, &trace_state);”…””}”hjU  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M›hjâ  hžhubhØ)”}”(hŒ±Note that synth_event_add_next_val() and synth_event_add_val() are
incompatible if used within the same trace of an event - either one
can be used but not both at the same time.”h]”hŒ±Note that synth_event_add_next_val() and synth_event_add_val() are
incompatible if used within the same trace of an event - either one
can be used but not both at the same time.”…””}”(hjc  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¥hjâ  hžhubhØ)”}”(hŒÅFinally, the event won't be actually traced until it's 'closed',
which is done using synth_event_trace_end(), which takes only the
struct synth_event_trace_state object used in the previous calls::”h]”hŒÌFinally, the event wonâ€™t be actually traced until itâ€™s â€˜closedâ€™,
which is done using synth_event_trace_end(), which takes only the
struct synth_event_trace_state object used in the previous calls:”…””}”(hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M©hjâ  hžhubj›  )”}”(hŒ*ret = synth_event_trace_end(&trace_state);”h]”hŒ*ret = synth_event_trace_end(&trace_state);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M­hjâ  hžhubhØ)”}”(hŒœNote that synth_event_trace_end() must be called at the end regardless
of whether any of the add calls failed (say due to a bad field name
being passed in).”h]”hŒœNote that synth_event_trace_end() must be called at the end regardless
of whether any of the add calls failed (say due to a bad field name
being passed in).”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¯hjâ  hžhubeh}”(h]”Œ#tracing-a-synthetic-event-piecewise”ah ]”h"]”Œ)7.2.2 tracing a synthetic event piecewise”ah$]”h&]”uh1h¡hj  hžhhŸh¶h M`ubh¢)”}”(hhh]”(h§)”}”(hŒ>7.3 Dyamically creating kprobe and kretprobe event definitions”h]”hŒ>7.3 Dyamically creating kprobe and kretprobe event definitions”…””}”(hj¦  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj£  hžhhŸh¶h M´ubhØ)”}”(hŒ˜To create a kprobe or kretprobe trace event from kernel code, the
kprobe_event_gen_cmd_start() or kretprobe_event_gen_cmd_start()
functions can be used.”h]”hŒ˜To create a kprobe or kretprobe trace event from kernel code, the
kprobe_event_gen_cmd_start() or kretprobe_event_gen_cmd_start()
functions can be used.”…””}”(hj´  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M¶hj£  hžhubhØ)”}”(hX¥  To create a kprobe event, an empty or partially empty kprobe event
should first be created using kprobe_event_gen_cmd_start().  The name
of the event and the probe location should be specified along with one
or args each representing a probe field should be supplied to this
function.  Before calling kprobe_event_gen_cmd_start(), the user
should create and initialize a dynevent_cmd object using
kprobe_event_cmd_init().”h]”hX¥  To create a kprobe event, an empty or partially empty kprobe event
should first be created using kprobe_event_gen_cmd_start().  The name
of the event and the probe location should be specified along with one
or args each representing a probe field should be supplied to this
function.  Before calling kprobe_event_gen_cmd_start(), the user
should create and initialize a dynevent_cmd object using
kprobe_event_cmd_init().”…””}”(hjÂ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mºhj£  hžhubhØ)”}”(hŒGFor example, to create a new "schedtest" kprobe event with two fields::”h]”hŒJFor example, to create a new â€œschedtestâ€ kprobe event with two fields:”…””}”(hjÐ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÂhj£  hžhubj›  )”}”(hXÖ  struct dynevent_cmd cmd;
char *buf;

/* Create a buffer to hold the generated command */
buf = kzalloc(MAX_DYNEVENT_CMD_LEN, GFP_KERNEL);

/* Before generating the command, initialize the cmd object */
kprobe_event_cmd_init(&cmd, buf, MAX_DYNEVENT_CMD_LEN);

/*
 * Define the gen_kprobe_test event with the first 2 kprobe
 * fields.
 */
ret = kprobe_event_gen_cmd_start(&cmd, "gen_kprobe_test", "do_sys_open",
                                 "dfd=%ax", "filename=%dx");”h]”hXÖ  struct dynevent_cmd cmd;
char *buf;

/* Create a buffer to hold the generated command */
buf = kzalloc(MAX_DYNEVENT_CMD_LEN, GFP_KERNEL);

/* Before generating the command, initialize the cmd object */
kprobe_event_cmd_init(&cmd, buf, MAX_DYNEVENT_CMD_LEN);

/*
 * Define the gen_kprobe_test event with the first 2 kprobe
 * fields.
 */
ret = kprobe_event_gen_cmd_start(&cmd, "gen_kprobe_test", "do_sys_open",
                                 "dfd=%ax", "filename=%dx");”…””}”hjÞ  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÄhj£  hžhubhØ)”}”(hX5  Once the kprobe event object has been created, it can then be
populated with more fields.  Fields can be added using
kprobe_event_add_fields(), supplying the dynevent_cmd object along
with a variable arg list of probe fields.  For example, to add a
couple additional fields, the following call could be made::”h]”hX4  Once the kprobe event object has been created, it can then be
populated with more fields.  Fields can be added using
kprobe_event_add_fields(), supplying the dynevent_cmd object along
with a variable arg list of probe fields.  For example, to add a
couple additional fields, the following call could be made:”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÔhj£  hžhubj›  )”}”(hŒDret = kprobe_event_add_fields(&cmd, "flags=%cx", "mode=+4($stack)");”h]”hŒDret = kprobe_event_add_fields(&cmd, "flags=%cx", "mode=+4($stack)");”…””}”hjú  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MÚhj£  hžhubhØ)”}”(hŒèOnce all the fields have been added, the event should be finalized and
registered by calling the kprobe_event_gen_cmd_end() or
kretprobe_event_gen_cmd_end() functions, depending on whether a kprobe
or kretprobe command was started::”h]”hŒçOnce all the fields have been added, the event should be finalized and
registered by calling the kprobe_event_gen_cmd_end() or
kretprobe_event_gen_cmd_end() functions, depending on whether a kprobe
or kretprobe command was started:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MÜhj£  hžhubj›  )”}”(hŒ%ret = kprobe_event_gen_cmd_end(&cmd);”h]”hŒ%ret = kprobe_event_gen_cmd_end(&cmd);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Máhj£  hžhubhØ)”}”(hŒor::”h]”hŒor:”…””}”(hj$  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mãhj£  hžhubj›  )”}”(hŒ(ret = kretprobe_event_gen_cmd_end(&cmd);”h]”hŒ(ret = kretprobe_event_gen_cmd_end(&cmd);”…””}”hj2  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Måhj£  hžhubhØ)”}”(hŒKAt this point, the event object is ready to be used for tracing new
events.”h]”hŒKAt this point, the event object is ready to be used for tracing new
events.”…””}”(hj@  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mçhj£  hžhubhØ)”}”(hŒ˜Similarly, a kretprobe event can be created using
kretprobe_event_gen_cmd_start() with a probe name and location and
additional params such as $retval::”h]”hŒ—Similarly, a kretprobe event can be created using
kretprobe_event_gen_cmd_start() with a probe name and location and
additional params such as $retval:”…””}”(hjN  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mêhj£  hžhubj›  )”}”(hŒ~ret = kretprobe_event_gen_cmd_start(&cmd, "gen_kretprobe_test",
                                    "do_sys_open", "$retval");”h]”hŒ~ret = kretprobe_event_gen_cmd_start(&cmd, "gen_kretprobe_test",
                                    "do_sys_open", "$retval");”…””}”hj\  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mîhj£  hžhubhØ)”}”(hŒsSimilar to the synthetic event case, code like the following can be
used to enable the newly created kprobe event::”h]”hŒrSimilar to the synthetic event case, code like the following can be
used to enable the newly created kprobe event:”…””}”(hjj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mñhj£  hžhubj›  )”}”(hŒÆgen_kprobe_test = trace_get_event_file(NULL, "kprobes", "gen_kprobe_test");

ret = trace_array_set_clr_event(gen_kprobe_test->tr,
                                "kprobes", "gen_kprobe_test", true);”h]”hŒÆgen_kprobe_test = trace_get_event_file(NULL, "kprobes", "gen_kprobe_test");

ret = trace_array_set_clr_event(gen_kprobe_test->tr,
                                "kprobes", "gen_kprobe_test", true);”…””}”hjx  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Môhj£  hžhubhØ)”}”(hŒƒFinally, also similar to synthetic events, the following code can be
used to give the kprobe event file back and delete the event::”h]”hŒ‚Finally, also similar to synthetic events, the following code can be
used to give the kprobe event file back and delete the event:”…””}”(hj†  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mùhj£  hžhubj›  )”}”(hŒUtrace_put_event_file(gen_kprobe_test);

ret = kprobe_event_delete("gen_kprobe_test");”h]”hŒUtrace_put_event_file(gen_kprobe_test);

ret = kprobe_event_delete("gen_kprobe_test");”…””}”hj”  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mühj£  hžhubeh}”(h]”Œ:dyamically-creating-kprobe-and-kretprobe-event-definitions”ah ]”h"]”Œ>7.3 dyamically creating kprobe and kretprobe event definitions”ah$]”h&]”uh1h¡hj  hžhhŸh¶h M´ubh¢)”}”(hhh]”(h§)”}”(hŒ$7.4 The "dynevent_cmd" low-level API”h]”hŒ(7.4 The â€œdynevent_cmdâ€ low-level API”…””}”(hj­  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjª  hžhhŸh¶h MubhØ)”}”(hX
  Both the in-kernel synthetic event and kprobe interfaces are built on
top of a lower-level "dynevent_cmd" interface.  This interface is
meant to provide the basis for higher-level interfaces such as the
synthetic and kprobe interfaces, which can be used as examples.”h]”hX  Both the in-kernel synthetic event and kprobe interfaces are built on
top of a lower-level â€œdynevent_cmdâ€ interface.  This interface is
meant to provide the basis for higher-level interfaces such as the
synthetic and kprobe interfaces, which can be used as examples.”…””}”(hj»  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjª  hžhubhØ)”}”(hX;  The basic idea is simple and amounts to providing a general-purpose
layer that can be used to generate trace event commands.  The
generated command strings can then be passed to the command-parsing
and event creation code that already exists in the trace event
subsystem for creating the corresponding trace events.”h]”hX;  The basic idea is simple and amounts to providing a general-purpose
layer that can be used to generate trace event commands.  The
generated command strings can then be passed to the command-parsing
and event creation code that already exists in the trace event
subsystem for creating the corresponding trace events.”…””}”(hjÉ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjª  hžhubhØ)”}”(hXa  In a nutshell, the way it works is that the higher-level interface
code creates a struct dynevent_cmd object, then uses a couple
functions, dynevent_arg_add() and dynevent_arg_pair_add() to build up
a command string, which finally causes the command to be executed
using the dynevent_create() function.  The details of the interface
are described below.”h]”hXa  In a nutshell, the way it works is that the higher-level interface
code creates a struct dynevent_cmd object, then uses a couple
functions, dynevent_arg_add() and dynevent_arg_pair_add() to build up
a command string, which finally causes the command to be executed
using the dynevent_create() function.  The details of the interface
are described below.”…””}”(hj×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjª  hžhubhØ)”}”(hŒ¹The first step in building a new command string is to create and
initialize an instance of a dynevent_cmd.  Here, for instance, we
create a dynevent_cmd on the stack and initialize it::”h]”hŒ¸The first step in building a new command string is to create and
initialize an instance of a dynevent_cmd.  Here, for instance, we
create a dynevent_cmd on the stack and initialize it:”…””}”(hjå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mhjª  hžhubj›  )”}”(hŒÀstruct dynevent_cmd cmd;
char *buf;
int ret;

buf = kzalloc(MAX_DYNEVENT_CMD_LEN, GFP_KERNEL);

dynevent_cmd_init(cmd, buf, maxlen, DYNEVENT_TYPE_FOO,
                  foo_event_run_command);”h]”hŒÀstruct dynevent_cmd cmd;
char *buf;
int ret;

buf = kzalloc(MAX_DYNEVENT_CMD_LEN, GFP_KERNEL);

dynevent_cmd_init(cmd, buf, maxlen, DYNEVENT_TYPE_FOO,
                  foo_event_run_command);”…””}”hjó  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h Mhjª  hžhubhØ)”}”(hXñ  The dynevent_cmd initialization needs to be given a user-specified
buffer and the length of the buffer (MAX_DYNEVENT_CMD_LEN can be used
for this purpose - at 2k it's generally too big to be comfortably put
on the stack, so is dynamically allocated), a dynevent type id, which
is meant to be used to check that further API calls are for the
correct command type, and a pointer to an event-specific run_command()
callback that will be called to actually execute the event-specific
command function.”h]”hXó  The dynevent_cmd initialization needs to be given a user-specified
buffer and the length of the buffer (MAX_DYNEVENT_CMD_LEN can be used
for this purpose - at 2k itâ€™s generally too big to be comfortably put
on the stack, so is dynamically allocated), a dynevent type id, which
is meant to be used to check that further API calls are for the
correct command type, and a pointer to an event-specific run_command()
callback that will be called to actually execute the event-specific
command function.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M"hjª  hžhubhØ)”}”(hŒfOnce that's done, the command string can by built up by successive
calls to argument-adding functions.”h]”hŒhOnce thatâ€™s done, the command string can by built up by successive
calls to argument-adding functions.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M+hjª  hžhubhØ)”}”(hX  To add a single argument, define and initialize a struct dynevent_arg
or struct dynevent_arg_pair object.  Here's an example of the simplest
possible arg addition, which is simply to append the given string as
a whitespace-separated argument to the command::”h]”hX  To add a single argument, define and initialize a struct dynevent_arg
or struct dynevent_arg_pair object.  Hereâ€™s an example of the simplest
possible arg addition, which is simply to append the given string as
a whitespace-separated argument to the command:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M.hjª  hžhubj›  )”}”(hŒpstruct dynevent_arg arg;

dynevent_arg_init(&arg, NULL, 0);

arg.str = name;

ret = dynevent_arg_add(cmd, &arg);”h]”hŒpstruct dynevent_arg arg;

dynevent_arg_init(&arg, NULL, 0);

arg.str = name;

ret = dynevent_arg_add(cmd, &arg);”…””}”hj+  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M3hjª  hžhubhØ)”}”(hŒÒThe arg object is first initialized using dynevent_arg_init() and in
this case the parameters are NULL or 0, which means there's no
optional sanity-checking function or separator appended to the end of
the arg.”h]”hŒÔThe arg object is first initialized using dynevent_arg_init() and in
this case the parameters are NULL or 0, which means thereâ€™s no
optional sanity-checking function or separator appended to the end of
the arg.”…””}”(hj9  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M;hjª  hžhubhØ)”}”(hŒóHere's another more complicated example using an 'arg pair', which is
used to create an argument that consists of a couple components added
together as a unit, for example, a 'type field_name;' arg or a simple
expression arg e.g. 'flags=%cx'::”h]”hX   Hereâ€™s another more complicated example using an â€˜arg pairâ€™, which is
used to create an argument that consists of a couple components added
together as a unit, for example, a â€˜type field_name;â€™ arg or a simple
expression arg e.g. â€˜flags=%cxâ€™:”…””}”(hjG  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M@hjª  hžhubj›  )”}”(hŒÂstruct dynevent_arg_pair arg_pair;

dynevent_arg_pair_init(&arg_pair, dynevent_foo_check_arg_fn, 0, ';');

arg_pair.lhs = type;
arg_pair.rhs = name;

ret = dynevent_arg_pair_add(cmd, &arg_pair);”h]”hŒÂstruct dynevent_arg_pair arg_pair;

dynevent_arg_pair_init(&arg_pair, dynevent_foo_check_arg_fn, 0, ';');

arg_pair.lhs = type;
arg_pair.rhs = name;

ret = dynevent_arg_pair_add(cmd, &arg_pair);”…””}”hjU  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h MEhjª  hžhubhØ)”}”(hXD  Again, the arg_pair is first initialized, in this case with a callback
function used to check the sanity of the args (for example, that
neither part of the pair is NULL), along with a character to be used
to add an operator between the pair (here none) and a separator to be
appended onto the end of the arg pair (here ';').”h]”hXH  Again, the arg_pair is first initialized, in this case with a callback
function used to check the sanity of the args (for example, that
neither part of the pair is NULL), along with a character to be used
to add an operator between the pair (here none) and a separator to be
appended onto the end of the arg pair (here â€˜;â€™).”…””}”(hjc  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MNhjª  hžhubhØ)”}”(hŒƒThere's also a dynevent_str_add() function that can be used to simply
add a string as-is, with no spaces, delimiters, or arg check.”h]”hŒ…Thereâ€™s also a dynevent_str_add() function that can be used to simply
add a string as-is, with no spaces, delimiters, or arg check.”…””}”(hjq  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MThjª  hžhubhØ)”}”(hX  Any number of dynevent_*_add() calls can be made to build up the string
(until its length surpasses cmd->maxlen).  When all the arguments have
been added and the command string is complete, the only thing left to
do is run the command, which happens by simply calling
dynevent_create()::”h]”hX  Any number of dynevent_*_add() calls can be made to build up the string
(until its length surpasses cmd->maxlen).  When all the arguments have
been added and the command string is complete, the only thing left to
do is run the command, which happens by simply calling
dynevent_create():”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h MWhjª  hžhubj›  )”}”(hŒret = dynevent_create(&cmd);”h]”hŒret = dynevent_create(&cmd);”…””}”hj  sbah}”(h]”h ]”h"]”h$]”h&]”jª  j«  uh1jš  hŸh¶h M]hjª  hžhubhØ)”}”(hŒ`At that point, if the return value is 0, the dynamic event has been
created and is ready to use.”h]”hŒ`At that point, if the return value is 0, the dynamic event has been
created and is ready to use.”…””}”(hj›  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h M_hjª  hžhubhØ)”}”(hŒPSee the dynevent_cmd function definitions themselves for the details
of the API.”h]”hŒPSee the dynevent_cmd function definitions themselves for the details
of the API.”…””}”(hj©  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hŸh¶h Mbhjª  hžhubeh}”(h]”Œthe-dynevent-cmd-low-level-api”ah ]”h"]”Œ$7.4 the "dynevent_cmd" low-level api”ah$]”h&]”uh1h¡hj  hžhhŸh¶h Mubeh}”(h]”Œin-kernel-trace-event-api”ah ]”h"]”Œ7. in-kernel trace event api”ah$]”h&]”uh1h¡hh£hžhhŸh¶h MXubeh}”(h]”Œevent-tracing”ah ]”h"]”Œevent tracing”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(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”jò  Œ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É  jY  jV  jè  jå  j€  j}  j  jš  jà  jÝ  j  j  jÊ  jÇ  j9	  j6	  jR  jO  jÛ  jØ  j  j  jI  jF  jÒ  jÏ  j1	  j.	  j  j   j#
  j 
  jû  jø  jÄ  jÁ  jO  jL  jv  js  jß  jÜ  j   j  j§  j¤  j¼  j¹  uŒ	nametypes”}”(jÌ  ‰jY  ‰jè  ‰j€  ‰j  ‰jà  ‰j  ‰jÊ  ‰j9	  ‰jR  ‰jÛ  ‰j  ‰jI  ‰jÒ  ‰j1	  ‰j  ‰j#
  ‰jû  ‰jÄ  ‰jO  ‰jv  ‰jß  ‰j   ‰j§  ‰j¼  ‰uh}”(jÉ  h£jV  j'  jå  j\  j}  jm  jš  jƒ  jÝ  j   j  jë  jÇ  j  j6	  jÍ  jO  jì  jØ  jU  j  jÞ  jF  j  jÏ  jL  j.	  jÕ  j   j<	  j 
  j«	  jø  j&
  jÁ  j  jL  jÍ  js  jR  jÜ  jy  j  jâ  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”“”}”j   Ks…”R”Œparse_messages”]”hŒsystem_message”“”)”}”(hhh]”hØ)”}”(hŒfPossible title underline, too short for the title.
Treating it as ordinary text because it's so short.”h]”hŒhPossible title underline, too short for the title.
Treating it as ordinary text because itâ€™s so short.”…””}”(hjY  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h×hjV  ubah}”(h]”h ]”h"]”h$]”h&]”Œlevel”KŒtype”ŒINFO”Œline”MuŒsource”h¶uh1jT  hjÕ  hžhhŸh¶h MuubaŒtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.