Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
Documentation/rv: Adapt documentation after da_monitor refactoring
Previous changes refactored the da_monitor header file to avoid using
macros. This implies a few changes in how to import and use da_monitor
helpers:
DECLARE_DA_MON_<TYPE>(name, type) is substituted by
#define RV_MON_TYPE RV_MON_<TYPE>
da_handle_event_<name>() is substituted by
da_handle_event()
Update the documentation to reflect the changes.
Reviewed-by: Nam Cao <namcao@linutronix.de>
Link: https://lore.kernel.org/r/20251126104241.291258-4-gmonaco@redhat.com
Signed-off-by: Gabriele Monaco <gmonaco@redhat.com>
+21
-23
+21
-23
Documentation/trace/rv/monitor_synthesis.rst
+21
-23
Documentation/trace/rv/monitor_synthesis.rst
···
100
100
101
101
This initial implementation presents three different types of monitor instances:
102
102
103
-
- ``#define DECLARE_DA_MON_GLOBAL(name, type)``
104
-
- ``#define DECLARE_DA_MON_PER_CPU(name, type)``
105
-
- ``#define DECLARE_DA_MON_PER_TASK(name, type)``
103
+
- ``#define RV_MON_TYPE RV_MON_GLOBAL``
104
+
- ``#define RV_MON_TYPE RV_MON_PER_CPU``
105
+
- ``#define RV_MON_TYPE RV_MON_PER_TASK``
106
106
107
-
The first declares the functions for a global deterministic automata monitor,
108
-
the second for monitors with per-cpu instances, and the third with per-task
109
-
instances.
107
+
The first sets up functions declaration for a global deterministic automata
108
+
monitor, the second for monitors with per-cpu instances, and the third with
109
+
per-task instances.
110
110
111
-
In all cases, the 'name' argument is a string that identifies the monitor, and
112
-
the 'type' argument is the data type used by rvgen on the representation of
113
-
the model in C.
111
+
In all cases, the C file must include the $(MODEL_NAME).h file (generated by
112
+
`rvgen`), for example, to define the per-cpu 'wip' monitor, the `wip.c` source
113
+
file must include::
114
114
115
-
For example, the wip model with two states and three events can be
116
-
stored in an 'unsigned char' type. Considering that the preemption control
117
-
is a per-cpu behavior, the monitor declaration in the 'wip.c' file is::
118
-
119
-
DECLARE_DA_MON_PER_CPU(wip, unsigned char);
115
+
#define RV_MON_TYPE RV_MON_PER_CPU
116
+
#include "wip.h"
117
+
#include <rv/da_monitor.h>
120
118
121
119
The monitor is executed by sending events to be processed via the functions
122
120
presented below::
123
121
124
-
da_handle_event_$(MONITOR_NAME)($(event from event enum));
125
-
da_handle_start_event_$(MONITOR_NAME)($(event from event enum));
126
-
da_handle_start_run_event_$(MONITOR_NAME)($(event from event enum));
122
+
da_handle_event($(event from event enum));
123
+
da_handle_start_event($(event from event enum));
124
+
da_handle_start_run_event($(event from event enum));
127
125
128
-
The function ``da_handle_event_$(MONITOR_NAME)()`` is the regular case where
126
+
The function ``da_handle_event()`` is the regular case where
129
127
the event will be processed if the monitor is processing events.
130
128
131
129
When a monitor is enabled, it is placed in the initial state of the automata.
132
130
However, the monitor does not know if the system is in the *initial state*.
133
131
134
-
The ``da_handle_start_event_$(MONITOR_NAME)()`` function is used to notify the
132
+
The ``da_handle_start_event()`` function is used to notify the
135
133
monitor that the system is returning to the initial state, so the monitor can
136
134
start monitoring the next event.
137
135
138
-
The ``da_handle_start_run_event_$(MONITOR_NAME)()`` function is used to notify
136
+
The ``da_handle_start_run_event()`` function is used to notify
139
137
the monitor that the system is known to be in the initial state, so the
140
138
monitor can start monitoring and monitor the current event.
141
139
142
140
Using the wip model as example, the events "preempt_disable" and
143
141
"sched_waking" should be sent to monitor, respectively, via [2]::
144
142
145
-
da_handle_event_wip(preempt_disable_wip);
146
-
da_handle_event_wip(sched_waking_wip);
143
+
da_handle_event(preempt_disable_wip);
144
+
da_handle_event(sched_waking_wip);
147
145
148
146
While the event "preempt_enabled" will use::
149
147
150
-
da_handle_start_event_wip(preempt_enable_wip);
148
+
da_handle_start_event(preempt_enable_wip);
151
149
152
150
To notify the monitor that the system will be returning to the initial state,
153
151
so the system and the monitor should be in sync.