Skip to content

Commit

Permalink
Documentation/rv: Add docs for the sched monitors
Browse files Browse the repository at this point in the history 
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>
  • Loading branch information
Gabriele Monaco authored and Steven Rostedt (Google) committed Mar 24, 2025
1 parent 2334cf7 commit 03abeaa
Show file tree
Hide file tree
Showing 2 changed files with 240 additions and 0 deletions.
69 changes: 69 additions & 0 deletions Documentation/tools/rv/rv-mon-sched.rst
View file
Original file line number Diff line number Diff line change
@@ -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 changes: 171 additions & 0 deletions Documentation/trace/rv/monitor_sched.rst
View file
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 03abeaa

Please sign in to comment.