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