Differences

This shows you the differences between two versions of the page.

--- realtime:documentation:howto:debugging:cyclictest:details [2018/07/17 13:11]
ebugden Move application examples to use cases
+++ — (current)
@@ Line 1: / Line 1: @@
-====== Cyclictest ======
-Cyclictest accurately and repeatedly measures the difference between a thread's intended wake-up time and the time at which it actually wakes up in order to provide statistics about the system's latencies. It can measure latencies in real-time systems caused by the hardware, the firmware, and the operating system.
-The original test was written by Thomas Gleixner (tglx), but several people have subsequently contributed modifications. Cyclictest is currently maintained by Clark Williams and John Kacur and is part of the test suite [[realtime:documentation:howto:tools:rt-tests|rt-tests]].
-----
-===== Use Cases =====
-  * System benchmarking: [[realtime:documentation:howto:tools:rteval|RTEval]], [[realtime:documentation:howto:tools:worstcaselatency|Worst case latency test scenarios]]
-  * [[realtime:documentation:howto:debugging:cyclictest:debugging|Latency debugging]]
-  * [[realtime:documentation:howto:debugging:cyclictest:app-performance|Approximating application performance]]
-===== Installation =====
-Cyclictest can be installed by following the instructions on the [[realtime:documentation:howto:tools:rt-tests#compile-and-install|rt-tests page]].
-===== Execution =====
-Cyclictest must be run as root, with sudo, or as a member of the realtime group. Here is a test case that is relevant for most SMP real-time systems:
-<code bash>
-# cyclictest --mlockall --smp --priority=80 --interval=200 --distance=0
-</code>
-The options above are not relevant for every situation on every system. The following section goes into more detail about how to choose the right options for measuring a specific latency on a given system. Additionally, ''cyclictest -h'' provides a quick description of the different program options and more detailed explanations can be found by running ''man ./src/cyclictest/cyclictest.8'' from the root of the [[realtime:documentation:howto:tools:rt-tests|rt-tests]] files.
-Running Cyclictest without any options is not recommended as it will not necessarily measure anything useful. Without parameters cyclictest creates one thread with an intended wake up period of 1 ms.
-===== Test Design =====
-Cyclictest can be used to detect latencies that occur in a variety of different systems and situations. However, when measuring the latency of a specific situation, the test set-up and the parameters passed to the tool need to be carefully considered and chosen based on this situation. If these elements are not considered thoughtfully, the Cyclictest results will not accurately represent the latencies that occur in the situation that was supposed to be measured. In other words, it is relatively easy to accidentally not measure what a test was intended to measure.
-<WRAP rightalign>[[realtime:documentation:howto:debugging:cyclictest:test-design|Read more about how to design a test]]</WRAP>
-===== Results =====
-Here is an example of what the Cyclictest results could look like:
-<code>
-T: 0 (821)  P: 80  I: 200  C: 518063  Min: 1  Act: 1  Avg: 1  Max: 15
-T: 1 (822)  P: 80  I: 200  C: 518050  Min: 1  Act: 2  Avg: 1  Max: 23
-</code>
-These results were obtained by running the example command given above in the execution section for a short time on a 2 CPU machine running an RT patched version of the 4.9 kernel. The whitespace in the results above has been adjusted for formatting reasons.
-The most important value in the results is the maximum detected latency as this value can give an idea of what the worst case latency in the measured situation. These results should always be evaluated critically, as the maximum measured value does not necessarily represent the system's worst case. More details about this can be found on the Cyclictest Test Design page [[realtime:documentation:howto:debugging:cyclictest:test-design|here]].
-The table below contains a description of the abbreviated labels in the results:
-<WRAP center 400px>
-^Abbreviation ^ Label    ^ Description                                                       |
-|T            | Thread   | Thread index and thread ID                                        |
-|P            | Priority | RT thread priority                                                |
-|I            | Interval | Intended wake up period for the latency measuring threads (in us) |
-|C            | Count    | Number of times the latency was measured i.e. iteration count     |
-|Min          | Minimum  | Minimum latency that was measured (in us)                         |
-|Act          | Actual   | Latency measured during the latest completed iteration (in us)    |
-|Max          | Maximum  | Maximum latency that was measured (in us)                         |
-</WRAP>
-==== Presentation ====
-The default unit used to present the latency values is microseconds (us), but this can be changed to nanoseconds using the --nsecs option.
-The program options --histogram and --histofall can be used to output a histogram of the latencies to stdout at the end of the test. A more detailed description of these options can be found in the help menu (--help) or in the Cyclictest man page. Alternatively, an [[https://www.osadl.org/Create-a-latency-plot-from-cyclictest-hi.bash-script-for-latency-plot.0.html?&no_cache=1&sword_list[0]=script|OSADL script]] can be used to run Cyclictest and produce a latency plot with the resulting histogram data. Before running the script, it should be modified so that the options passed to Cyclictest match the intended test case.
-==== Analysis ====
-It is not possible to specify a universally applicable recommended limit for latency length. The Cyclictest results should be analyzed based on the system's timing requirements for the latency of what was being measured. For example, if the latency of a specific real-time task was measured, then the results should be compared with the timing requirements for that specific task. The requirements will determine whether the latencies observed in a system are acceptable or too long.
-An interesting way of seeing how the tested system compares to other real-time platforms is to run Cyclictest with the same options that are used by OSADL to benchmark systems in their [[https://www.osadl.org/Latency-plots.latency-plots.0.html|Real-time QA Farm]] and to then compare the results with the results produced by their tested systems. The exact Cyclictest command used for a system is specified next to that system's latency plot. It is also possible to see a latency plot with the combined results of all the real-time devices that are currently being tested.
-===== Expected Results =====
-<WRAP center round todo 60%>
-TODO: Run all the tests run in Expected results section of https://rt.wiki.kernel.org/index.php/Cyclictest and update here. We need to rerun the tests because they were run in 2006 on a Pentium III system running 2.6.16 kernel. Things have probably changed a bit now. :)
-</WRAP>
-===== FAQ =====
-<WRAP rightalign>[[realtime:documentation:howto:debugging:cyclictest:faq|Read the Cyclictest FAQ]]</WRAP>

Wiki

User Tools

Site Tools

Differences

Page Tools