blob: b4a1374210161ac6d2970b25df674d5f999143d5 [file] [log] [blame]
<!--
Documentation/_templates/layout.html
Licensed to the Apache Software Foundation (ASF) under one or more
contributor license agreements. See the NOTICE file distributed with
this work for additional information regarding copyright ownership. The
ASF licenses this file to you under the Apache License, Version 2.0 (the
"License"); you may not use this file except in compliance with the
License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
-->
<!DOCTYPE html>
<html class="writer-html5" lang="en">
<head>
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Cyclictest benchmark utility &mdash; NuttX latest documentation</title>
<link rel="stylesheet" type="text/css" href="../../../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/css/theme.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/copybutton.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/sphinx_collapse.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/design-style.1e8bd061cd6da7fc9cf755528e8ffc24.min.css" />
<link rel="stylesheet" type="text/css" href="../../../_static/custom.css" />
<link rel="shortcut icon" href="../../../_static/favicon.ico"/>
<script src="../../../_static/jquery.js"></script>
<script src="../../../_static/_sphinx_javascript_frameworks_compat.js"></script>
<script data-url_root="../../../" id="documentation_options" src="../../../_static/documentation_options.js"></script>
<script src="../../../_static/doctools.js"></script>
<script src="../../../_static/sphinx_highlight.js"></script>
<script src="../../../_static/clipboard.min.js"></script>
<script src="../../../_static/copybutton.js"></script>
<script src="../../../_static/design-tabs.js"></script>
<script src="../../../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../../../genindex.html" />
<link rel="search" title="Search" href="../../../search.html" />
<link rel="next" title="Dhrystone Dhrystone" href="../dhrystone/index.html" />
<link rel="prev" title="coremark CoreMark Benchmark" href="../coremark/index.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../../../index.html" class="icon icon-home"> NuttX
</a>
<!-- this version selector is quite ugly, should be probably replaced by something
more modern -->
<div class="version-selector">
<select onchange="javascript:location.href = this.value;">
<option value="../../../../latest" selected="selected">latest</option>
<option value="../../../../10.0.0" >10.0.0</option>
<option value="../../../../10.0.1" >10.0.1</option>
<option value="../../../../10.1.0" >10.1.0</option>
<option value="../../../../10.2.0" >10.2.0</option>
<option value="../../../../10.3.0" >10.3.0</option>
<option value="../../../../11.0.0" >11.0.0</option>
<option value="../../../../12.0.0" >12.0.0</option>
<option value="../../../../12.1.0" >12.1.0</option>
<option value="../../../../12.2.0" >12.2.0</option>
<option value="../../../../12.2.1" >12.2.1</option>
<option value="../../../../12.3.0" >12.3.0</option>
<option value="../../../../12.4.0" >12.4.0</option>
<option value="../../../../12.5.0" >12.5.0</option>
<option value="../../../../12.5.1" >12.5.1</option>
<option value="../../../../12.6.0" >12.6.0</option>
<option value="../../../../12.7.0" >12.7.0</option>
<option value="../../../../12.8.0" >12.8.0</option>
<option value="../../../../12.9.0" >12.9.0</option>
<option value="../../../../12.10.0" >12.10.0</option>
<option value="../../../../12.11.0" >12.11.0</option>
</select>
</div>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Table of Contents</span></p>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../../index.html">Home</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../introduction/index.html">Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../quickstart/index.html">Getting Started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../contributing/index.html">Contributing</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../introduction/inviolables.html">The Inviolable Principles of NuttX</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../platforms/index.html">Supported Platforms</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../components/index.html">OS Components</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="../../index.html">Applications</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="../../audioutils/index.html">Audio Utility libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../boot/index.html">Bootloader Utilities</a></li>
<li class="toctree-l2 current"><a class="reference internal" href="../index.html">Benchmark Applications</a><ul class="current">
<li class="toctree-l3"><a class="reference internal" href="../cachespeed/index.html"><code class="docutils literal notranslate"><span class="pre">cachespeed</span></code> CACHE Speed Test</a></li>
<li class="toctree-l3"><a class="reference internal" href="../coremark-pro/index.html"><code class="docutils literal notranslate"><span class="pre">coremark-pro</span></code> CoreMark-PRO</a></li>
<li class="toctree-l3"><a class="reference internal" href="../coremark/index.html"><code class="docutils literal notranslate"><span class="pre">coremark</span></code> CoreMark Benchmark</a></li>
<li class="toctree-l3 current"><a class="current reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">Cyclictest</span></code> benchmark utility</a><ul>
<li class="toctree-l4"><a class="reference internal" href="#replacement-for-clock-gettime-and-clock-nanosleep-in-nuttx">Replacement for <code class="docutils literal notranslate"><span class="pre">clock_gettime</span></code> and <code class="docutils literal notranslate"><span class="pre">clock_nanosleep</span></code> in NuttX</a></li>
<li class="toctree-l4"><a class="reference internal" href="#usage-of-this-program">Usage of this program</a></li>
<li class="toctree-l4"><a class="reference internal" href="#example-usage">Example usage</a></li>
</ul>
</li>
<li class="toctree-l3"><a class="reference internal" href="../dhrystone/index.html"><code class="docutils literal notranslate"><span class="pre">Dhrystone</span></code> Dhrystone</a></li>
<li class="toctree-l3"><a class="reference internal" href="../fio/index.html"><code class="docutils literal notranslate"><span class="pre">FIO</span></code> FIO Benchmark</a></li>
<li class="toctree-l3"><a class="reference internal" href="../iozone/index.html"><code class="docutils literal notranslate"><span class="pre">iozone</span></code> IOzone, filesystem benchmark tool</a></li>
<li class="toctree-l3"><a class="reference internal" href="../mtd/index.html"><code class="docutils literal notranslate"><span class="pre">mtd</span></code> MTD test and transfer rate benchmark</a></li>
<li class="toctree-l3"><a class="reference internal" href="../osperf/index.html"><code class="docutils literal notranslate"><span class="pre">osperf</span></code> System performance profiling</a></li>
<li class="toctree-l3"><a class="reference internal" href="../ramspeed/index.html"><code class="docutils literal notranslate"><span class="pre">ramspeed</span></code> RAM Speed Test</a></li>
<li class="toctree-l3"><a class="reference internal" href="../superpi/index.html"><code class="docutils literal notranslate"><span class="pre">superpi</span></code> SuperPI test</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="../../canutils/index.html">CAN Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../crypto/index.html">Cryptography Library Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../fsutils/index.html">File System Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../games/index.html">Games</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../graphics/index.html">Graphics Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../industry/index.html">Industrial Applications</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../inertial/index.html">Inertial Libraries Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../interpreters/index.html">Interpreters</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../logging/index.html">Logging Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../lte/index.html">LTE Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../math/index.html">Math Library Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../mlearing/index.html">Machine Learning Support</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../netutils/index.html">Network Utilities</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../nsh/index.html">NuttShell (NSH)</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../sdr/index.html">Software Defined Radio Libraries</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../system/index.html">System Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../testing/index.html">Testing</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../tools/index.html">Host Side Tools</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../wireless/index.html">Wireless Libraries and NSH Add-Ons</a></li>
<li class="toctree-l2"><a class="reference internal" href="../../examples/index.html">Examples</a></li>
</ul>
</li>
<li class="toctree-l1"><a class="reference internal" href="../../../implementation/index.html">Implementation Details</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../reference/index.html">API Reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../faq/index.html">FAQ</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../debugging/index.html">Debugging</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../guides/index.html">Guides</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../standards/index.html">Standards</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../glossary.html">Glossary</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../logos/index.html">NuttX Logos</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../../_tags/tagsindex.html">Tags</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../../../index.html">NuttX</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item"><a href="../../index.html">Applications</a></li>
<li class="breadcrumb-item"><a href="../index.html">Benchmark Applications</a></li>
<li class="breadcrumb-item active"><code class="docutils literal notranslate"><span class="pre">Cyclictest</span></code> benchmark utility</li>
<li class="wy-breadcrumbs-aside">
<a href="https://github.com/apache/nuttx/blob/master/Documentation/applications/benchmarks/cyclictest/index.rst" class="fa fa-github"> Edit on GitHub</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="cyclictest-benchmark-utility">
<h1><code class="docutils literal notranslate"><span class="pre">Cyclictest</span></code> benchmark utility<a class="headerlink" href="#cyclictest-benchmark-utility" title="Permalink to this heading"></a></h1>
<p>Cyclictest is a simple program used to measure the real-time capabilities
of a RTOS. Originally, this program comes from the Linux <code class="docutils literal notranslate"><span class="pre">rt-tests</span></code>.
However, NuttX features its own cyclictest utility which is heavily inspired
by the original program but does not use some advanced features, while adding
features that are NuttX related.</p>
<p>The creation of the new cyclictest arose from the fact that as of February
2025, POSIX time functions (such as <code class="docutils literal notranslate"><span class="pre">clock_gettime</span></code> and <code class="docutils literal notranslate"><span class="pre">clock_nanosleep</span></code>)
depend on the systemtick (if the system is not compiled in the Tickless mode)
which makes small delays practically impossible. However, if we utilize
a hardware device timer, small periodic delays can be achieved with some <code class="docutils literal notranslate"><span class="pre">ioctl</span></code>
calls.</p>
<p>The documentation needs to be revisited to see how cyclictest performs
when NuttX is compiled in tickless mode.</p>
<section id="replacement-for-clock-gettime-and-clock-nanosleep-in-nuttx">
<h2>Replacement for <code class="docutils literal notranslate"><span class="pre">clock_gettime</span></code> and <code class="docutils literal notranslate"><span class="pre">clock_nanosleep</span></code> in NuttX<a class="headerlink" href="#replacement-for-clock-gettime-and-clock-nanosleep-in-nuttx" title="Permalink to this heading"></a></h2>
<p>Configuring such device timer is simple: firstly, the timer’s timeout is set using
the <code class="docutils literal notranslate"><span class="pre">TCIOC_SETTIMEOUT</span></code> <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> call. Then the <code class="docutils literal notranslate"><span class="pre">TCIOC_NOTIFICATION</span></code> <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> call
is performed. Afterwards, the timer can be polled using the <code class="docutils literal notranslate"><span class="pre">poll</span></code> function
which returns when the timer timeouts.</p>
<p>The thread latency wakeup can be measured using this timer by calling
<code class="docutils literal notranslate"><span class="pre">TCIOC_GETSTATUS</span></code> <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> call after the <code class="docutils literal notranslate"><span class="pre">poll</span></code> function has returned.
The <code class="docutils literal notranslate"><span class="pre">ioctl</span></code> call fills the <code class="docutils literal notranslate"><span class="pre">timer_status_s</span></code> struct which contains two important
fields: <code class="docutils literal notranslate"><span class="pre">uint32_t</span> <span class="pre">timeleft</span></code> and <code class="docutils literal notranslate"><span class="pre">uint32_t</span> <span class="pre">timeout</span></code>. The latency of the thread can
then be calculated as <code class="docutils literal notranslate"><span class="pre">timeout</span> <span class="pre">-</span> <span class="pre">timeleft</span></code>.</p>
</section>
<section id="usage-of-this-program">
<h2>Usage of this program<a class="headerlink" href="#usage-of-this-program" title="Permalink to this heading"></a></h2>
<p>Despite some differences, the NuttX port stays as faithful as possible to the original
program, keeping the most important command-line parameters the same.
The user can choose one of two “waiting methods”:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">clock_nanosleep</span></code> (<code class="docutils literal notranslate"><span class="pre">W_NANOSLEEP</span></code>),</p></li>
<li><p>polling the device (<code class="docutils literal notranslate"><span class="pre">W_DEVTIMER</span></code>).</p></li>
</ul>
<p>The user can also choose one of two “measuring methods”:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">clock_gettime</span></code> (<code class="docutils literal notranslate"><span class="pre">M_GETTIME</span></code>),</p></li>
<li><p>utilizing the device timer (<code class="docutils literal notranslate"><span class="pre">M_TIMER_API</span></code>).</p></li>
</ul>
<p>It is possible to combine the waiting and measuring methods. As of February 2025,
using <code class="docutils literal notranslate"><span class="pre">W_DEVTIMER</span></code> and <code class="docutils literal notranslate"><span class="pre">M_TIMER_API</span></code> produces the best results.
However, it requires a timer device to be registered by your BSP (such as <code class="docutils literal notranslate"><span class="pre">/dev/timer1</span></code>).
Be also advised that when <code class="docutils literal notranslate"><span class="pre">W_DEVTIMER</span></code> is used, only one thread can poll the timer.</p>
<p>Following command-line parameters can be supplied:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">-c</span> <span class="pre">--clock</span> <span class="pre">[CLOCK]</span></code>: 0 selects <code class="docutils literal notranslate"><span class="pre">CLOCK_REALTIME</span></code>, 1 selects <code class="docutils literal notranslate"><span class="pre">CLOCK_MONOTONIC</span></code> (default)</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-d</span> <span class="pre">--distance</span> <span class="pre">[US]</span></code>: The distance of thread intervals. Default is 500 us.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-D</span> <span class="pre">--duration</span> <span class="pre">[TIME]</span></code>: Set the test duration in seconds. Default is 0 (endless).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-e</span> <span class="pre">--help</span></code>: Displays help and exits.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-h</span> <span class="pre">--histogram</span> <span class="pre">[US]</span></code>: Output the histogram data to stdout. US is the maximum value to be printed.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-H</span> <span class="pre">--histofall</span></code>: Same as <code class="docutils literal notranslate"><span class="pre">-h</span></code> except that an additional histogram column is displayed at the right that contains summary data of all thread histograms. If cyclictest runs a single thread only, the <code class="docutils literal notranslate"><span class="pre">-H</span></code> option is equivalent to <code class="docutils literal notranslate"><span class="pre">-h</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-i</span> <span class="pre">--interval</span> <span class="pre">[US]</span></code>: The thread interval. Default is 1000 us.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-l</span> <span class="pre">--loops</span> <span class="pre">[N]</span></code>: The number of measurement loops. Default is 0 (endless).</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-m</span> <span class="pre">--measurement</span> <span class="pre">[METHODS]</span></code>: Sets the time measurement method. 0 selects <code class="docutils literal notranslate"><span class="pre">clock_gettime</span></code>, 1 uses the NuttX timer API. Be advised that if 1 is selected, you need to specify a timer device (e.g. <code class="docutils literal notranslate"><span class="pre">/dev/timer0</span></code>) in <code class="docutils literal notranslate"><span class="pre">-T</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-n</span> <span class="pre">--nanosleep</span> <span class="pre">[METHOD]</span></code>: Sets the waiting method: 0 selects <code class="docutils literal notranslate"><span class="pre">clock_nanosleep</span></code>, 1 waits for the POLLIN flag on a timer device. Default is 0. Choosing 1 works only with one thread, the <code class="docutils literal notranslate"><span class="pre">-t</span></code> value is therefore set to 1. If METHOD 1 is selected, you need to specify a timer device (e.g. <code class="docutils literal notranslate"><span class="pre">/dev/timer0</span></code>) in <code class="docutils literal notranslate"><span class="pre">-T</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-q</span> <span class="pre">--quiet</span></code>: Prints a summary only on exit.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-p</span> <span class="pre">--prio</span></code>: Sets the priority of the first thread.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-t</span> <span class="pre">--threads</span> <span class="pre">[N]</span></code>: The number of test threads to be created. Default is 1.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-T</span> <span class="pre">--timer-device</span> <span class="pre">[DEV]</span></code>: The measuring timer device. Must be specified when <code class="docutils literal notranslate"><span class="pre">-m=1</span></code> or <code class="docutils literal notranslate"><span class="pre">-n=1</span></code>.</p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">-y</span> <span class="pre">--policy</span> <span class="pre">[NAME]</span></code>: Set the scheduler policy, where NAME is fifo, rr, batch, idle, normal, other.</p></li>
</ul>
</section>
<section id="example-usage">
<h2>Example usage<a class="headerlink" href="#example-usage" title="Permalink to this heading"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">cyclictest</span> <span class="pre">-p</span> <span class="pre">150</span> <span class="pre">-T</span> <span class="pre">/dev/timer1</span> <span class="pre">-m</span> <span class="pre">1</span> <span class="pre">-n</span> <span class="pre">1</span> <span class="pre">-h</span> <span class="pre">20</span> <span class="pre">-D</span> <span class="pre">100</span> <span class="pre">-i</span> <span class="pre">50</span></code></p>
<p>Since <code class="docutils literal notranslate"><span class="pre">W_DEVTIMER</span></code> is used, only one thread runs every 50 us.
The measurement method is the device timer itself, specified in <code class="docutils literal notranslate"><span class="pre">-T</span></code>.
The test runs for 100 seconds. The priority is boosted to 150, so the
measurement is not affected by other tasks or communication.</p>
<p>Output of the command (tested on Microchip ATSAMV71Q21B &#64; 300 MHz):</p>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span># Histogram
000000 000000
000001 000000
000002 000000
000003 000000
000004 000000
000005 000000
000006 000000
000007 000000
000008 000000
000009 000000
000010 603045
000011 1395782
000012 000804
000013 000153
000014 000034
000015 000083
000016 000030
000017 000000
000018 000000
000019 000000
# Total: 001999931
# Min Latencies: 00010
# Avg Latencies: 00010
# Max Latencies: 00016
# Histogram Overflows: 00000
</pre></div>
</div>
</section>
</section>
</div>
</div>
<footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
<a href="../coremark/index.html" class="btn btn-neutral float-left" title="coremark CoreMark Benchmark" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
<a href="../dhrystone/index.html" class="btn btn-neutral float-right" title="Dhrystone Dhrystone" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
</div>
<hr/>
<div role="contentinfo">
<p>&#169; Copyright 2023, The Apache Software Foundation.</p>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>