Skip to content

Commit 03abeaa

Browse files
glemcorostedt
glemco
authored and
rostedt
committed
Documentation/rv: Add docs for the sched monitors
Add man page and kernel documentation for the sched monitors, as sched is a container of other monitors, document all in the same page. sched is the first nested monitor, also explain what is a nested monitor and how enabling containers or children monitors work. To: Ingo Molnar <[email protected]> To: Peter Zijlstra <[email protected]> Cc: Juri Lelli <[email protected]> Cc: Ingo Molnar <[email protected]> Cc: Peter Zijlstra <[email protected]> Cc: Jonathan Corbet <[email protected]> Cc: John Kacur <[email protected]> Cc: Clark Williams <[email protected]> Link: https://lore.kernel.org/[email protected] Signed-off-by: Gabriele Monaco <[email protected]> Signed-off-by: Steven Rostedt (Google) <[email protected]>
1 parent 2334cf7 commit 03abeaa

File tree

2 files changed

+240
-0
lines changed

2 files changed

+240
-0
lines changed

‎Documentation/tools/rv/rv-mon-sched.rst

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
.. SPDX-License-Identifier: GPL-2.0
2+
3+
============
4+
rv-mon-sched
5+
============
6+
-----------------------------
7+
Scheduler monitors collection
8+
-----------------------------
9+
10+
:Manual section: 1
11+
12+
SYNOPSIS
13+
========
14+
15+
**rv mon sched** [*OPTIONS*]
16+
17+
**rv mon <NESTED_MONITOR>** [*OPTIONS*]
18+
19+
**rv mon sched:<NESTED_MONITOR>** [*OPTIONS*]
20+
21+
DESCRIPTION
22+
===========
23+
24+
The scheduler monitor collection is a container for several monitors to model
25+
the behaviour of the scheduler. Each monitor describes a specification that
26+
the scheduler should follow.
27+
28+
As a monitor container, it will enable all nested monitors and set them
29+
according to OPTIONS.
30+
Nevertheless nested monitors can also be activated independently both by name
31+
and by specifying sched: , e.g. to enable only monitor tss you can do any of:
32+
33+
# rv mon sched:tss
34+
35+
# rv mon tss
36+
37+
See kernel documentation for further information about this monitor:
38+
<https://docs.kernel.org/trace/rv/monitor_sched.html>
39+
40+
OPTIONS
41+
=======
42+
43+
.. include:: common_ikm.rst
44+
45+
NESTED MONITOR
46+
==============
47+
48+
The available nested monitors are:
49+
* scpd: schedule called with preemption disabled
50+
* snep: schedule does not enable preempt
51+
* sncid: schedule not called with interrupt disabled
52+
* snroc: set non runnable on its own context
53+
* sco: scheduling context operations
54+
* tss: task switch while scheduling
55+
56+
SEE ALSO
57+
========
58+
59+
**rv**\(1), **rv-mon**\(1)
60+
61+
Linux kernel *RV* documentation:
62+
<https://www.kernel.org/doc/html/latest/trace/rv/index.html>
63+
64+
AUTHOR
65+
======
66+
67+
Written by Gabriele Monaco <[email protected]>
68+
69+
.. include:: common_appendix.rst

‎Documentation/trace/rv/monitor_sched.rst

Lines changed: 171 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,171 @@
1+
Scheduler monitors
2+
==================
3+
4+
- Name: sched
5+
- Type: container for multiple monitors
6+
- Author: Gabriele Monaco <[email protected]>, Daniel Bristot de Oliveira <[email protected]>
7+
8+
Description
9+
-----------
10+
11+
Monitors describing complex systems, such as the scheduler, can easily grow to
12+
the point where they are just hard to understand because of the many possible
13+
state transitions.
14+
Often it is possible to break such descriptions into smaller monitors,
15+
sharing some or all events. Enabling those smaller monitors concurrently is,
16+
in fact, testing the system as if we had one single larger monitor.
17+
Splitting models into multiple specification is not only easier to
18+
understand, but gives some more clues when we see errors.
19+
20+
The sched monitor is a set of specifications to describe the scheduler behaviour.
21+
It includes several per-cpu and per-task monitors that work independently to verify
22+
different specifications the scheduler should follow.
23+
24+
To make this system as straightforward as possible, sched specifications are *nested*
25+
monitors, whereas sched itself is a *container*.
26+
From the interface perspective, sched includes other monitors as sub-directories,
27+
enabling/disabling or setting reactors to sched, propagates the change to all monitors,
28+
however single monitors can be used independently as well.
29+
30+
It is important that future modules are built after their container (sched, in
31+
this case), otherwise the linker would not respect the order and the nesting
32+
wouldn't work as expected.
33+
To do so, simply add them after sched in the Makefile.
34+
35+
Specifications
36+
--------------
37+
38+
The specifications included in sched are currently a work in progress, adapting the ones
39+
defined in by Daniel Bristot in [1].
40+
41+
Currently we included the following:
42+
43+
Monitor tss
44+
~~~~~~~~~~~
45+
46+
The task switch while scheduling (tss) monitor ensures a task switch happens
47+
only in scheduling context, that is inside a call to `__schedule`::
48+
49+
|
50+
|
51+
v
52+
+-----------------+
53+
| thread | <+
54+
+-----------------+ |
55+
| |
56+
| schedule_entry | schedule_exit
57+
v |
58+
sched_switch |
59+
+--------------- |
60+
| sched |
61+
+--------------> -+
62+
63+
Monitor sco
64+
~~~~~~~~~~~
65+
66+
The scheduling context operations (sco) monitor ensures changes in a task state
67+
happen only in thread context::
68+
69+
70+
|
71+
|
72+
v
73+
sched_set_state +------------------+
74+
+------------------ | |
75+
| | thread_context |
76+
+-----------------> | | <+
77+
+------------------+ |
78+
| |
79+
| schedule_entry | schedule_exit
80+
v |
81+
|
82+
scheduling_context -+
83+
84+
Monitor snroc
85+
~~~~~~~~~~~~~
86+
87+
The set non runnable on its own context (snroc) monitor ensures changes in a
88+
task state happens only in the respective task's context. This is a per-task
89+
monitor::
90+
91+
|
92+
|
93+
v
94+
+------------------+
95+
| other_context | <+
96+
+------------------+ |
97+
| |
98+
| sched_switch_in | sched_switch_out
99+
v |
100+
sched_set_state |
101+
+------------------ |
102+
| own_context |
103+
+-----------------> -+
104+
105+
Monitor scpd
106+
~~~~~~~~~~~~
107+
108+
The schedule called with preemption disabled (scpd) monitor ensures schedule is
109+
called with preemption disabled::
110+
111+
|
112+
|
113+
v
114+
+------------------+
115+
| cant_sched | <+
116+
+------------------+ |
117+
| |
118+
| preempt_disable | preempt_enable
119+
v |
120+
schedule_entry |
121+
schedule_exit |
122+
+----------------- can_sched |
123+
| |
124+
+----------------> -+
125+
126+
Monitor snep
127+
~~~~~~~~~~~~
128+
129+
The schedule does not enable preempt (snep) monitor ensures a schedule call
130+
does not enable preemption::
131+
132+
|
133+
|
134+
v
135+
preempt_disable +------------------------+
136+
preempt_enable | |
137+
+------------------ | non_scheduling_context |
138+
| | |
139+
+-----------------> | | <+
140+
+------------------------+ |
141+
| |
142+
| schedule_entry | schedule_exit
143+
v |
144+
|
145+
scheduling_contex -+
146+
147+
Monitor sncid
148+
~~~~~~~~~~~~~
149+
150+
The schedule not called with interrupt disabled (sncid) monitor ensures
151+
schedule is not called with interrupt disabled::
152+
153+
|
154+
|
155+
v
156+
schedule_entry +--------------+
157+
schedule_exit | |
158+
+----------------- | can_sched |
159+
| | |
160+
+----------------> | | <+
161+
+--------------+ |
162+
| |
163+
| irq_disable | irq_enable
164+
v |
165+
|
166+
cant_sched -+
167+
168+
References
169+
----------
170+
171+
[1] - https://bristot.me/linux-task-model

0 commit comments

Comments
 (0)