From 71c05b3a2b56ea303253140b30d176f4fb739b38 Mon Sep 17 00:00:00 2001 From: Matteo Golin Date: Wed, 10 Sep 2025 10:49:28 -0400 Subject: [PATCH] docs/calib_udelay: Added documentation for the `calib_udelay` example. This commit adds documentation to the almost empty `calib_udelay` page as part of #11081. It provides reasoning for the example, an explanation of what it does and why `CONFIG_BOARD_LOOPSPERMSEC` is necessary, and also shows some example console output of the program. Signed-off-by: Matteo Golin --- .../examples/calib_udelay/index.rst | 49 ++++++++++++++++++- 1 file changed, 48 insertions(+), 1 deletion(-) diff --git a/Documentation/applications/examples/calib_udelay/index.rst b/Documentation/applications/examples/calib_udelay/index.rst index d5390fbe697..2c5b1e5402e 100644 --- a/Documentation/applications/examples/calib_udelay/index.rst +++ b/Documentation/applications/examples/calib_udelay/index.rst @@ -2,4 +2,51 @@ ``calib_udelay`` Calibration tool for udelay ============================================= -Calibration tool for udelay. +This tool is used for calibrating the configuration option +``CONFIG_BOARD_LOOPSPERMSEC``. This option is used by NuttX to perform +busy-waiting (i.e., spinning in a loop) when a very basic busy-wait sleep is +needed in board logic. This is also sometimes used when the timer-based sleep +functions do not have a low enough resolution for shorter timings (i.e. system +tick every 1ms but you want to sleep for 100us). + +When porting NuttX a new board, this example program is very useful to get a +calibrated value for ``CONFIG_BOARD_LOOPSPERMSEC``. + +.. note:: + + If you are testing any drivers and have unexpected issues with them, make + sure that this configuration option has been calibrated. It can cause + bad/incorrect timings in drivers if not calibrated. + +Here is the example output from running the application: + +.. code-block:: console + + nsh> calib_udelay + + Calibrating timer for main calibration... + Performing main calibration for udelay.This will take approx. 17.280 seconds. + Calibration slope for udelay: + Y = m*X + b, where + X is loop iterations, + Y is time in nanoseconds, + b is base overhead, + m is nanoseconds per loop iteration. + + m = 5.33333333 nsec/iter + b = -199999.99999995 nsec + + Correlation coefficient, R² = 1.0000 + + Without overhead, 0.18750000 iterations per nanosecond and 187500.00 iterations per millis. + + Recommended setting for CONFIG_BOARD_LOOPSPERMSEC: + CONFIG_BOARD_LOOPSPERMSEC=187500 + +You can simply copy paste the value from the console output and use it as the +value for your board by setting it in the Kconfig menu. + +The program is run without any arguments. Configuration options for how the +program runs (taking more measurements, etc.) can be seen in its Kconfig menu. +Press ``h`` with the configuration option highlighted under your cursor to read +the help text about what each option does.