====== Documentation ======

In order to fulfill the requirements of a real-time system, a system
must react to an external event like an interrupt within a defined time
frame. Therefore several mechanisms, configurations and implementation
rules have to be considered.

----

<WRAP half column>
===== HOWTOs =====

There are three categories of HOWTOs:

  * [[realtime:documentation:howto:applications:start|RTOS and RT application]]
  * [[realtime:documentation:howto:debugging:start|RT latency debugging]]
  * [[realtime:documentation:howto:tools:start|RT tools and utilities]]

===== Technical Basics =====

Currently running tasks with low priority must be preempted to allow
the real-time critical task to run. Preemption depends on the rules of
the task’s scheduling policy. Another important aspect in a real-time
system is the guaranteeing the exclusive use of certain resources for
real-time tasks.

<WRAP rightalign>[[realtime:documentation:technical_basics:start|Read more about technical basics]]</WRAP>

===== Technical details of PREEMPT_RT patch =====

The main aim of the PREEMPT_RT patch is to //minimize the amount of kernel code that is non-preemptible// ((Paul McKenney. A realtime preemption overview. [[https://lwn.net/Articles/146861/]])). Therefore several substitution mechanisms and new mechanisms are implemented.

<WRAP rightalign>[[realtime:documentation:technical_details:start|Read more about technical details]]</WRAP>

===== Publications =====

Several real-time related publications can help broaden your knowledge
about real-time systems. Regarding PREEMPT_RT, a recent survey of available scientific works
[[https://dl.acm.org/citation.cfm?id=3297714|have been published]] ([[https://re.public.polimi.it/handle/11311/1076057|open access link]]).

<WRAP rightalign>[[realtime:documentation:publications|Read more about publications]]</WRAP>


===== Known Limitations =====

Some functionality is not available on RT because its implementation
is not compatible with RT. Those limitations may apply to the to the
kernel as a whole or may apply to specific architecture or platforms.

<WRAP rightalign>[[realtime:documentation:known_limitations|Read more about known limitations]]</WRAP>


</WRAP>

<WRAP half column>
===== Stable RT Releases =====

If the PREEMPT_RT patch was ported to a Linux kernel version that is flagged as a [[https://kernel.org|stable release at kernel.org]], then that port will continue to be forward ported with each new stable release for that kernel version. The stable kernels can be cloned from the [[https://git.kernel.org/pub/scm/linux/kernel/git/rt/linux-stable-rt.git/|stable git repository]] as well as downloaded as [[https://mirrors.edge.kernel.org/pub/linux/kernel/projects/rt/|single patches or a tarball of a quilt series of patches]].

The PREEMPT_RT stable releases are updated in two fashions.

  * Merged with the upstream Linux stable kernel.

  * Backports of commits from the [[https://git.kernel.org/pub/scm/linux/kernel/git/rt/linux-rt-devel.git/|current PREEMPT_RT development repository]]

Tagging policy of the PREEMPT_RT stable releases. Each PREEMPT_RT stable release is tagged with the version number of the upstream Linux stable kernel as well as its own "-rt" counter that is appended. The -rt counter will increment for the following:

  * When forward ported to the latest upstream Linux stable version.

  * When any merge with a upstream Linux stable causes a conflict.

  * When a backport of the PREEMPT_RT development branch is done.

A backport will not be done with a forward port of a stable version. They will be done separately, and tagged separately.

The "-rebase" branch is how the series of patches are created. The "-rebase" is only done for forward ports to the latest upstream Linux stable versions, and for backports of the PREEMPT_RT development branch. It is not done for a conflict with a upstream Linux stable merge, unless that stable version is the latest one. As the name suggests, the "-rebase" branch will rebase, to allow each commit added by the PREEMPT_RT code to be applied in the order to the upstream Linux stable version it is based on. This is not the case with the normal "-rt" branch, which is never rebased.

</WRAP>

----

<WRAP rightalign>Go back to [[realtime:start|Real-Time Main Page]]</WRAP>