Documentation: Add Whetstone FPU benchmark documentation

Add documentation for the Whetstone floating-point benchmark
application which is being added to nuttx-apps.

The documentation includes:
- Overview of the benchmark
- Configuration options
- Usage examples
- Output interpretation
- Test modules description

Signed-off-by: makejian <makejian@xiaomi.com>
This commit is contained in:
makejian
2026-01-20 10:31:30 +08:00
committed by Xiang Xiao
parent 2c1e3d6ed0
commit 8309aadd69
@@ -0,0 +1,170 @@
=========================================
``whetstone`` Whetstone FPU Benchmark
=========================================
Overview
========
Whetstone is a classic synthetic benchmark program designed to evaluate
processor arithmetic performance. By executing a series of standardized
computational tasks, it provides accurate assessment of floating-point
and integer operation capabilities.
This implementation is a C converted version of the Double Precision
Whetstone benchmark, based on the work by Rich Painter (Painter Engineering,
Inc.) from the netlib.org version.
The test results help developers:
- Quantify FPU (Floating-Point Unit) performance
- Analyze the impact of compiler optimization levels (-O2, -O3, etc.)
on code execution efficiency
- Compare arithmetic performance across different hardware platforms
or system configurations
Configuration
=============
Before running the test, enable the following Kconfig options:
.. code-block:: bash
# Enable custom permissive license components
CONFIG_ALLOW_CUSTOM_PERMISSIVE_COMPONENTS=y
# Enable Whetstone benchmark
CONFIG_BENCHMARK_WHETSTONE=y
# Whetstone requires floating-point support in the C library
CONFIG_LIBC_FLOATINGPOINT=y
Additional configuration options:
- ``CONFIG_BENCHMARK_WHETSTONE_PROGNAME`` - Program name (default: "whetstone")
- ``CONFIG_BENCHMARK_WHETSTONE_PRIORITY`` - Task priority (default: 100)
- ``CONFIG_BENCHMARK_WHETSTONE_STACKSIZE`` - Stack size (default: DEFAULT_TASK_STACKSIZE)
Usage
=====
Command Syntax
--------------
.. code-block:: bash
whetstone [-c] [loops]
Parameters
----------
- ``[loops]`` - Module loop count. Sets the number of iterations for each
internal test module. Increasing this value significantly increases
computation and execution time. Default: 1000
- ``-c`` - Continuous mode. When specified, the benchmark repeats indefinitely
until interrupted. Default: disabled
Examples
--------
Run a standard test with default parameters (1000 loops):
.. code-block:: bash
nsh> whetstone
Increase computation load per module (100000 loops):
.. code-block:: bash
nsh> whetstone 100000
Run in continuous mode with custom loop count:
.. code-block:: bash
nsh> whetstone -c 100000
Output Interpretation
=====================
After completion, whetstone outputs test configuration, total duration,
and the final performance score.
Example Output
--------------
.. code-block:: bash
nsh> whetstone 100000
Loops: 100000, Iterations: 1, Duration: 5765 millisecond.
C Converted Double Precision Whetstones: 1.7 MIPS
- **Loops: 100000** - Each module executed 100,000 loop iterations
- **Iterations: 1** - The test suite ran 1 round
- **Duration: 5765 millisecond** - Total execution time
- **1.7 MIPS** - Final performance score
Performance Metrics
-------------------
**MIPS / KIPS**
- **Definition**: Whetstone performance units - MIPS (Mega Whetstone
Instructions Per Second) and KIPS (Kilo Whetstone Instructions Per Second)
- **Calculation**: ``KIPS = (100.0 * loops * iterations) / (duration_sec * 1000)``
- **Interpretation**: Higher scores indicate better processor arithmetic
performance
- **Unit conversion**: Results display as KIPS when below 1000, otherwise
as MIPS
Test Modules
============
The Whetstone benchmark consists of 11 carefully designed computational
modules covering different operation types:
.. list-table::
:header-rows: 1
* - Module
- Description
* - Module 1
- Simple identifiers - basic floating-point operations
* - Module 2
- Array elements - array-based floating-point operations
* - Module 3
- Array as parameter - procedure calls with array arguments
* - Module 4
- Conditional jumps - branch operations
* - Module 5
- (Omitted)
* - Module 6
- Integer arithmetic - complex integer operations
* - Module 7
- Trigonometric functions - sin, cos, atan calculations
* - Module 8
- Procedure calls - function call overhead
* - Module 9
- Array references - array indexing operations
* - Module 10
- Integer arithmetic - simple integer operations
* - Module 11
- Standard functions - chained math functions (sqrt, exp, log)
Notes
=====
- This benchmark uses double-precision floating-point arithmetic
- For accurate measurements, ensure the system is not under heavy load
- If "Insufficient duration" is reported, increase the loop count
- Timing precision is in milliseconds, enabling quick and accurate results
even with fewer loop iterations on high-performance embedded CPUs
References
==========
- Original Whetstone benchmark: H.J. Curnow and B.A. Wichmann,
"A Synthetic Benchmark", The Computer Journal, Vol 19, No 1,
February 1976, pp. 43-49
- netlib.org Whetstone: https://www.netlib.org/benchmark/whetstone.c