forked from mirrors/linux
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 <mingo@redhat.com> To: Peter Zijlstra <peterz@infradead.org> Cc: Juri Lelli <juri.lelli@redhat.com> Cc: Ingo Molnar <mingo@redhat.com> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Jonathan Corbet <corbet@lwn.net> Cc: John Kacur <jkacur@redhat.com> Cc: Clark Williams <williams@redhat.com> Link: https://lore.kernel.org/20250305140406.350227-9-gmonaco@redhat.com Signed-off-by: Gabriele Monaco <gmonaco@redhat.com> Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
This commit is contained in:
Gabriele Monaco
Steven Rostedt (Google)
parent
2334cf7d09
commit
03abeaa63c
2 changed files with 240 additions and 0 deletions
69
Documentation/tools/rv/rv-mon-sched.rst
Normal file
69
Documentation/tools/rv/rv-mon-sched.rst
Normal file
|
|
@ -0,0 +1,69 @@
|
||||||
|
.. SPDX-License-Identifier: GPL-2.0
|
||||||
|
|
||||||
|
============
|
||||||
|
rv-mon-sched
|
||||||
|
============
|
||||||
|
-----------------------------
|
||||||
|
Scheduler monitors collection
|
||||||
|
-----------------------------
|
||||||
|
|
||||||
|
:Manual section: 1
|
||||||
|
|
||||||
|
SYNOPSIS
|
||||||
|
========
|
||||||
|
|
||||||
|
**rv mon sched** [*OPTIONS*]
|
||||||
|
|
||||||
|
**rv mon <NESTED_MONITOR>** [*OPTIONS*]
|
||||||
|
|
||||||
|
**rv mon sched:<NESTED_MONITOR>** [*OPTIONS*]
|
||||||
|
|
||||||
|
DESCRIPTION
|
||||||
|
===========
|
||||||
|
|
||||||
|
The scheduler monitor collection is a container for several monitors to model
|
||||||
|
the behaviour of the scheduler. Each monitor describes a specification that
|
||||||
|
the scheduler should follow.
|
||||||
|
|
||||||
|
As a monitor container, it will enable all nested monitors and set them
|
||||||
|
according to OPTIONS.
|
||||||
|
Nevertheless nested monitors can also be activated independently both by name
|
||||||
|
and by specifying sched: , e.g. to enable only monitor tss you can do any of:
|
||||||
|
|
||||||
|
# rv mon sched:tss
|
||||||
|
|
||||||
|
# rv mon tss
|
||||||
|
|
||||||
|
See kernel documentation for further information about this monitor:
|
||||||
|
<https://docs.kernel.org/trace/rv/monitor_sched.html>
|
||||||
|
|
||||||
|
OPTIONS
|
||||||
|
=======
|
||||||
|
|
||||||
|
.. include:: common_ikm.rst
|
||||||
|
|
||||||
|
NESTED MONITOR
|
||||||
|
==============
|
||||||
|
|
||||||
|
The available nested monitors are:
|
||||||
|
* scpd: schedule called with preemption disabled
|
||||||
|
* snep: schedule does not enable preempt
|
||||||
|
* sncid: schedule not called with interrupt disabled
|
||||||
|
* snroc: set non runnable on its own context
|
||||||
|
* sco: scheduling context operations
|
||||||
|
* tss: task switch while scheduling
|
||||||
|
|
||||||
|
SEE ALSO
|
||||||
|
========
|
||||||
|
|
||||||
|
**rv**\(1), **rv-mon**\(1)
|
||||||
|
|
||||||
|
Linux kernel *RV* documentation:
|
||||||
|
<https://www.kernel.org/doc/html/latest/trace/rv/index.html>
|
||||||
|
|
||||||
|
AUTHOR
|
||||||
|
======
|
||||||
|
|
||||||
|
Written by Gabriele Monaco <gmonaco@redhat.com>
|
||||||
|
|
||||||
|
.. include:: common_appendix.rst
|
||||||
171
Documentation/trace/rv/monitor_sched.rst
Normal file
171
Documentation/trace/rv/monitor_sched.rst
Normal file
|
|
@ -0,0 +1,171 @@
|
||||||
|
Scheduler monitors
|
||||||
|
==================
|
||||||
|
|
||||||
|
- Name: sched
|
||||||
|
- Type: container for multiple monitors
|
||||||
|
- Author: Gabriele Monaco <gmonaco@redhat.com>, Daniel Bristot de Oliveira <bristot@kernel.org>
|
||||||
|
|
||||||
|
Description
|
||||||
|
-----------
|
||||||
|
|
||||||
|
Monitors describing complex systems, such as the scheduler, can easily grow to
|
||||||
|
the point where they are just hard to understand because of the many possible
|
||||||
|
state transitions.
|
||||||
|
Often it is possible to break such descriptions into smaller monitors,
|
||||||
|
sharing some or all events. Enabling those smaller monitors concurrently is,
|
||||||
|
in fact, testing the system as if we had one single larger monitor.
|
||||||
|
Splitting models into multiple specification is not only easier to
|
||||||
|
understand, but gives some more clues when we see errors.
|
||||||
|
|
||||||
|
The sched monitor is a set of specifications to describe the scheduler behaviour.
|
||||||
|
It includes several per-cpu and per-task monitors that work independently to verify
|
||||||
|
different specifications the scheduler should follow.
|
||||||
|
|
||||||
|
To make this system as straightforward as possible, sched specifications are *nested*
|
||||||
|
monitors, whereas sched itself is a *container*.
|
||||||
|
From the interface perspective, sched includes other monitors as sub-directories,
|
||||||
|
enabling/disabling or setting reactors to sched, propagates the change to all monitors,
|
||||||
|
however single monitors can be used independently as well.
|
||||||
|
|
||||||
|
It is important that future modules are built after their container (sched, in
|
||||||
|
this case), otherwise the linker would not respect the order and the nesting
|
||||||
|
wouldn't work as expected.
|
||||||
|
To do so, simply add them after sched in the Makefile.
|
||||||
|
|
||||||
|
Specifications
|
||||||
|
--------------
|
||||||
|
|
||||||
|
The specifications included in sched are currently a work in progress, adapting the ones
|
||||||
|
defined in by Daniel Bristot in [1].
|
||||||
|
|
||||||
|
Currently we included the following:
|
||||||
|
|
||||||
|
Monitor tss
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
The task switch while scheduling (tss) monitor ensures a task switch happens
|
||||||
|
only in scheduling context, that is inside a call to `__schedule`::
|
||||||
|
|
||||||
|
|
|
||||||
|
|
|
||||||
|
v
|
||||||
|
+-----------------+
|
||||||
|
| thread | <+
|
||||||
|
+-----------------+ |
|
||||||
|
| |
|
||||||
|
| schedule_entry | schedule_exit
|
||||||
|
v |
|
||||||
|
sched_switch |
|
||||||
|
+--------------- |
|
||||||
|
| sched |
|
||||||
|
+--------------> -+
|
||||||
|
|
||||||
|
Monitor sco
|
||||||
|
~~~~~~~~~~~
|
||||||
|
|
||||||
|
The scheduling context operations (sco) monitor ensures changes in a task state
|
||||||
|
happen only in thread context::
|
||||||
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
|
||||||
|
v
|
||||||
|
sched_set_state +------------------+
|
||||||
|
+------------------ | |
|
||||||
|
| | thread_context |
|
||||||
|
+-----------------> | | <+
|
||||||
|
+------------------+ |
|
||||||
|
| |
|
||||||
|
| schedule_entry | schedule_exit
|
||||||
|
v |
|
||||||
|
|
|
||||||
|
scheduling_context -+
|
||||||
|
|
||||||
|
Monitor snroc
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The set non runnable on its own context (snroc) monitor ensures changes in a
|
||||||
|
task state happens only in the respective task's context. This is a per-task
|
||||||
|
monitor::
|
||||||
|
|
||||||
|
|
|
||||||
|
|
|
||||||
|
v
|
||||||
|
+------------------+
|
||||||
|
| other_context | <+
|
||||||
|
+------------------+ |
|
||||||
|
| |
|
||||||
|
| sched_switch_in | sched_switch_out
|
||||||
|
v |
|
||||||
|
sched_set_state |
|
||||||
|
+------------------ |
|
||||||
|
| own_context |
|
||||||
|
+-----------------> -+
|
||||||
|
|
||||||
|
Monitor scpd
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The schedule called with preemption disabled (scpd) monitor ensures schedule is
|
||||||
|
called with preemption disabled::
|
||||||
|
|
||||||
|
|
|
||||||
|
|
|
||||||
|
v
|
||||||
|
+------------------+
|
||||||
|
| cant_sched | <+
|
||||||
|
+------------------+ |
|
||||||
|
| |
|
||||||
|
| preempt_disable | preempt_enable
|
||||||
|
v |
|
||||||
|
schedule_entry |
|
||||||
|
schedule_exit |
|
||||||
|
+----------------- can_sched |
|
||||||
|
| |
|
||||||
|
+----------------> -+
|
||||||
|
|
||||||
|
Monitor snep
|
||||||
|
~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The schedule does not enable preempt (snep) monitor ensures a schedule call
|
||||||
|
does not enable preemption::
|
||||||
|
|
||||||
|
|
|
||||||
|
|
|
||||||
|
v
|
||||||
|
preempt_disable +------------------------+
|
||||||
|
preempt_enable | |
|
||||||
|
+------------------ | non_scheduling_context |
|
||||||
|
| | |
|
||||||
|
+-----------------> | | <+
|
||||||
|
+------------------------+ |
|
||||||
|
| |
|
||||||
|
| schedule_entry | schedule_exit
|
||||||
|
v |
|
||||||
|
|
|
||||||
|
scheduling_contex -+
|
||||||
|
|
||||||
|
Monitor sncid
|
||||||
|
~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
The schedule not called with interrupt disabled (sncid) monitor ensures
|
||||||
|
schedule is not called with interrupt disabled::
|
||||||
|
|
||||||
|
|
|
||||||
|
|
|
||||||
|
v
|
||||||
|
schedule_entry +--------------+
|
||||||
|
schedule_exit | |
|
||||||
|
+----------------- | can_sched |
|
||||||
|
| | |
|
||||||
|
+----------------> | | <+
|
||||||
|
+--------------+ |
|
||||||
|
| |
|
||||||
|
| irq_disable | irq_enable
|
||||||
|
v |
|
||||||
|
|
|
||||||
|
cant_sched -+
|
||||||
|
|
||||||
|
References
|
||||||
|
----------
|
||||||
|
|
||||||
|
[1] - https://bristot.me/linux-task-model
|
||||||
Loading…
Reference in a new issue