M]sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget1/translations/zh_CN/trace/rv/da_monitor_synthesismodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget1/translations/zh_TW/trace/rv/da_monitor_synthesismodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget1/translations/it_IT/trace/rv/da_monitor_synthesismodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget1/translations/ja_JP/trace/rv/da_monitor_synthesismodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget1/translations/ko_KR/trace/rv/da_monitor_synthesismodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget1/translations/sp_SP/trace/rv/da_monitor_synthesismodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(h(Deterministic Automata Monitor Synthesish]h(Deterministic Automata Monitor Synthesis}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhK/var/lib/git/docbuild/linux/Documentation/trace/rv/da_monitor_synthesis.rsthKubh paragraph)}(hThe starting point for the application of runtime verification (RV) techniques is the *specification* or *modeling* of the desired (or undesired) behavior of the system under scrutiny.h](hVThe starting point for the application of runtime verification (RV) techniques is the }(hhhhhNhNubhemphasis)}(h*specification*h]h specification}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh or }(hhhhhNhNubh)}(h *modeling*h]hmodeling}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubhE of the desired (or undesired) behavior of the system under scrutiny.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXThe formal representation needs to be then *synthesized* into a *monitor* that can then be used in the analysis of the trace of the system. The *monitor* connects to the system via an *instrumentation* that converts the events from the *system* to the events of the *specification*.h](h+The formal representation needs to be then }(hhhhhNhNubh)}(h *synthesized*h]h synthesized}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh into a }(hhhhhNhNubh)}(h *monitor*h]hmonitor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubhG that can then be used in the analysis of the trace of the system. The }(hhhhhNhNubh)}(h *monitor*h]hmonitor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh connects to the system via an }(hhhhhNhNubh)}(h*instrumentation*h]hinstrumentation}(hj+hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh# that converts the events from the }(hhhhhNhNubh)}(h*system*h]hsystem}(hj=hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh to the events of the }(hhhhhNhNubh)}(h*specification*h]h specification}(hjOhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhubh.}(hhhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hXsIn Linux terms, the runtime verification monitors are encapsulated inside the *RV monitor* abstraction. The RV monitor includes a set of instances of the monitor (per-cpu monitor, per-task monitor, and so on), the helper functions that glue the monitor to the system reference model, and the trace output as a reaction to event parsing and exceptions, as depicted below::h](hNIn Linux terms, the runtime verification monitors are encapsulated inside the }(hjghhhNhNubh)}(h *RV monitor*h]h RV monitor}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhjgubhX abstraction. The RV monitor includes a set of instances of the monitor (per-cpu monitor, per-task monitor, and so on), the helper functions that glue the monitor to the system reference model, and the trace output as a reaction to event parsing and exceptions, as depicted below:}(hjghhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh literal_block)}(hX<Linux +----- RV Monitor ----------------------------------+ Formal Realm | | Realm +-------------------+ +----------------+ +-----------------+ | Linux kernel | | Monitor | | Reference | | Tracing | -> | Instance(s) | <- | Model | | (instrumentation) | | (verification) | | (specification) | +-------------------+ +----------------+ +-----------------+ | | | | V | | +----------+ | | | Reaction | | | +--+--+--+-+ | | | | | | | | | +-> trace output ? | +------------------------|--|----------------------+ | +----> panic ? +-------> h]hX<Linux +----- RV Monitor ----------------------------------+ Formal Realm | | Realm +-------------------+ +----------------+ +-----------------+ | Linux kernel | | Monitor | | Reference | | Tracing | -> | Instance(s) | <- | Model | | (instrumentation) | | (verification) | | (specification) | +-------------------+ +----------------+ +-----------------+ | | | | V | | +----------+ | | | Reaction | | | +--+--+--+-+ | | | | | | | | | +-> trace output ? | +------------------------|--|----------------------+ | +----> panic ? +-------> }hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhKhhhhubh)}(hhh](h)}(hDA monitor synthesish]hDA monitor synthesis}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK(ubh)}(hThe synthesis of automata-based models into the Linux *RV monitor* abstraction is automated by the dot2k tool and the rv/da_monitor.h header file that contains a set of macros that automatically generate the monitor's code.h](h6The synthesis of automata-based models into the Linux }(hjhhhNhNubh)}(h *RV monitor*h]h RV monitor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh abstraction is automated by the dot2k tool and the rv/da_monitor.h header file that contains a set of macros that automatically generate the monitor’s code.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK*hjhhubeh}(h]da-monitor-synthesisah ]h"]da monitor synthesisah$]h&]uh1hhhhhhhhK(ubh)}(hhh](h)}(hdot2kh]hdot2k}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhK/ubh)}(hThe dot2k utility leverages dot2c by converting an automaton model in the DOT format into the C representation [1] and creating the skeleton of a kernel monitor in C.h]hThe dot2k utility leverages dot2c by converting an automaton model in the DOT format into the C representation [1] and creating the skeleton of a kernel monitor in C.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK1hjhhubh)}(h}For example, it is possible to transform the wip.dot model present in [1] into a per-cpu monitor with the following command::h]h|For example, it is possible to transform the wip.dot model present in [1] into a per-cpu monitor with the following command:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK5hjhhubj)}(h$ dot2k -d wip.dot -t per_cpuh]h$ dot2k -d wip.dot -t per_cpu}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhK8hjhhubh)}(hAThis will create a directory named wip/ with the following files:h]hAThis will create a directory named wip/ with the following files:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK:hjhhubh bullet_list)}(hhh](h list_item)}(hwip.h: the wip model in Ch]h)}(hj$h]hwip.h: the wip model in C}(hj&hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKThe rv/da_monitor.h enables automatic code generation for the }(hjhhhNhNubh)}(h*Monitor Instance(s)*h]hMonitor Instance(s)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh using C macros.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKEhjohhubh)}(hJThe benefits of the usage of macro for monitor synthesis are 3-fold as it:h]hJThe benefits of the usage of macro for monitor synthesis are 3-fold as it:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjohhubj)}(hhh](j!)}(hReduces the code duplication;h]h)}(hjh]hReduces the code duplication;}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKJhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj!)}(h$Facilitates the bug fix/improvement;h]h)}(hjh]h$Facilitates the bug fix/improvement;}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKKhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubj!)}(hAvoids the case of developers changing the core of the monitor code to manipulate the model in a (let's say) non-standard way. h]h)}(h~Avoids the case of developers changing the core of the monitor code to manipulate the model in a (let's say) non-standard way.h]hAvoids the case of developers changing the core of the monitor code to manipulate the model in a (let’s say) non-standard way.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhjubah}(h]h ]h"]h$]h&]uh1j hjhhhhhNubeh}(h]h ]h"]h$]h&]jWjXuh1jhhhKJhjohhubh)}(hPThis initial implementation presents three different types of monitor instances:h]hPThis initial implementation presents three different types of monitor instances:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjohhubj)}(hhh](j!)}(h-``#define DECLARE_DA_MON_GLOBAL(name, type)``h]h)}(hjh]hliteral)}(hjh]h)#define DECLARE_DA_MON_GLOBAL(name, type)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubah}(h]h ]h"]h$]h&]uh1hhhhKQhjubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj!)}(h.``#define DECLARE_DA_MON_PER_CPU(name, type)``h]h)}(hj2h]j)}(hj2h]h*#define DECLARE_DA_MON_PER_CPU(name, type)}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj4ubah}(h]h ]h"]h$]h&]uh1hhhhKRhj0ubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubj!)}(h0``#define DECLARE_DA_MON_PER_TASK(name, type)`` h]h)}(h/``#define DECLARE_DA_MON_PER_TASK(name, type)``h]j)}(hjVh]h+#define DECLARE_DA_MON_PER_TASK(name, type)}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjTubah}(h]h ]h"]h$]h&]uh1hhhhKShjPubah}(h]h ]h"]h$]h&]uh1j hj hhhhhNubeh}(h]h ]h"]h$]h&]jWjXuh1jhhhKQhjohhubh)}(hThe first declares the functions for a global deterministic automata monitor, the second for monitors with per-cpu instances, and the third with per-task instances.h]hThe first declares the functions for a global deterministic automata monitor, the second for monitors with per-cpu instances, and the third with per-task instances.}(hjwhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKUhjohhubh)}(hIn all cases, the 'name' argument is a string that identifies the monitor, and the 'type' argument is the data type used by dot2k on the representation of the model in C.h]hIn all cases, the ‘name’ argument is a string that identifies the monitor, and the ‘type’ argument is the data type used by dot2k on the representation of the model in C.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKYhjohhubh)}(hFor example, the wip model with two states and three events can be stored in an 'unsigned char' type. Considering that the preemption control is a per-cpu behavior, the monitor declaration in the 'wip.c' file is::h]hFor example, the wip model with two states and three events can be stored in an ‘unsigned char’ type. Considering that the preemption control is a per-cpu behavior, the monitor declaration in the ‘wip.c’ file is:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK]hjohhubj)}(h+DECLARE_DA_MON_PER_CPU(wip, unsigned char);h]h+DECLARE_DA_MON_PER_CPU(wip, unsigned char);}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKahjohhubh)}(h]The monitor is executed by sending events to be processed via the functions presented below::h]h\The monitor is executed by sending events to be processed via the functions presented below:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKchjohhubj)}(hda_handle_event_$(MONITOR_NAME)($(event from event enum)); da_handle_start_event_$(MONITOR_NAME)($(event from event enum)); da_handle_start_run_event_$(MONITOR_NAME)($(event from event enum));h]hda_handle_event_$(MONITOR_NAME)($(event from event enum)); da_handle_start_event_$(MONITOR_NAME)($(event from event enum)); da_handle_start_run_event_$(MONITOR_NAME)($(event from event enum));}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKfhjohhubh)}(hThe function ``da_handle_event_$(MONITOR_NAME)()`` is the regular case where the event will be processed if the monitor is processing events.h](h The function }(hjhhhNhNubj)}(h%``da_handle_event_$(MONITOR_NAME)()``h]h!da_handle_event_$(MONITOR_NAME)()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh[ is the regular case where the event will be processed if the monitor is processing events.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKjhjohhubh)}(hWhen a monitor is enabled, it is placed in the initial state of the automata. However, the monitor does not know if the system is in the *initial state*.h](hWhen a monitor is enabled, it is placed in the initial state of the automata. However, the monitor does not know if the system is in the }(hjhhhNhNubh)}(h*initial state*h]h initial state}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKmhjohhubh)}(hThe ``da_handle_start_event_$(MONITOR_NAME)()`` function is used to notify the monitor that the system is returning to the initial state, so the monitor can start monitoring the next event.h](hThe }(hj hhhNhNubj)}(h+``da_handle_start_event_$(MONITOR_NAME)()``h]h'da_handle_start_event_$(MONITOR_NAME)()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh function is used to notify the monitor that the system is returning to the initial state, so the monitor can start monitoring the next event.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKphjohhubh)}(hThe ``da_handle_start_run_event_$(MONITOR_NAME)()`` function is used to notify the monitor that the system is known to be in the initial state, so the monitor can start monitoring and monitor the current event.h](hThe }(hj+hhhNhNubj)}(h/``da_handle_start_run_event_$(MONITOR_NAME)()``h]h+da_handle_start_run_event_$(MONITOR_NAME)()}(hj3hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj+ubh function is used to notify the monitor that the system is known to be in the initial state, so the monitor can start monitoring and monitor the current event.}(hj+hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKthjohhubh)}(hUsing the wip model as example, the events "preempt_disable" and "sched_waking" should be sent to monitor, respectively, via [2]::h]hUsing the wip model as example, the events “preempt_disable” and “sched_waking” should be sent to monitor, respectively, via [2]:}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKxhjohhubj)}(hPda_handle_event_wip(preempt_disable_wip); da_handle_event_wip(sched_waking_wip);h]hPda_handle_event_wip(preempt_disable_wip); da_handle_event_wip(sched_waking_wip);}hjYsbah}(h]h ]h"]h$]h&]jjuh1jhhhK{hjohhubh)}(h,While the event "preempt_enabled" will use::h]h/While the event “preempt_enabled” will use:}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK~hjohhubj)}(h.da_handle_start_event_wip(preempt_enable_wip);h]h.da_handle_start_event_wip(preempt_enable_wip);}hjusbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjohhubh)}(h~To notify the monitor that the system will be returning to the initial state, so the system and the monitor should be in sync.h]h~To notify the monitor that the system will be returning to the initial state, so the system and the monitor should be in sync.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjohhubeh}(h]monitor-macrosah ]h"]monitor macrosah$]h&]uh1hhhhhhhhKCubh)}(hhh](h)}(h Final remarksh]h Final remarks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hWith the monitor synthesis in place using the rv/da_monitor.h and dot2k, the developer's work should be limited to the instrumentation of the system, increasing the confidence in the overall approach.h]hWith the monitor synthesis in place using the rv/da_monitor.h and dot2k, the developer’s work should be limited to the instrumentation of the system, increasing the confidence in the overall approach.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hq[1] For details about deterministic automata format and the translation from one representation to another, see::h]hp[1] For details about deterministic automata format and the translation from one representation to another, see:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(h1Documentation/trace/rv/deterministic_automata.rsth]h1Documentation/trace/rv/deterministic_automata.rst}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(h[2] dot2k appends the monitor's name suffix to the events enums to avoid conflicting variables when exporting the global vmlinux.h use by BPF programs.h]h[2] dot2k appends the monitor’s name suffix to the events enums to avoid conflicting variables when exporting the global vmlinux.h use by BPF programs.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h] final-remarksah ]h"] final remarksah$]h&]uh1hhhhhhhhKubeh}(h](deterministic-automata-monitor-synthesisah ]h"](deterministic automata monitor synthesisah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourceh _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjjjjljijjjju nametypes}(jjjljjuh}(jhjjjijjjojju footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.