test: performance: improve test application documentations

Include short description in Doxygen output for each performance test
application.

Signed-off-by: Matias Elo <matias.elo@nokia.com>
Reviewed-by: Tuomas Taipale <tuomas.taipale@nokia.com>

32 files changed, 211 insertions, 19 deletions

diff --git a/doc/application-api-guide/Doxyfile b/doc/application-api-guide/Doxyfile
index 13a365c72..9c718f203 100644
--- a/doc/application-api-guide/Doxyfile
+++ b/doc/application-api-guide/Doxyfile
@@ -6,6 +6,8 @@ PROJECT_LOGO = $(SRCDIR)/doc/images/ODP-Logo-HQ.svg
 INPUT = $(SRCDIR)/doc/application-api-guide \
 	include \
 	$(SRCDIR)/include \
-	$(SRCDIR)/example
-EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/CONTRIBUTING $(SRCDIR)/include/README
+	$(SRCDIR)/example \
+	$(SRCDIR)/test/performance
+EXAMPLE_PATH = $(SRCDIR)/example $(SRCDIR)/CONTRIBUTING $(SRCDIR)/include/README \
+	       $(SRCDIR)/test/performance
 WARNINGS = NO
diff --git a/test/performance/bench_common.c b/test/performance/bench_common.c
index f838954ab..640889503 100644
--- a/test/performance/bench_common.c
+++ b/test/performance/bench_common.c
@@ -2,6 +2,8 @@
  * Copyright (c) 2023 Nokia
  */
 
+/** @cond _ODP_HIDE_FROM_DOXYGEN_ */
+
 #include <odp_api.h>
 #include <odp/helper/odph_api.h>
 
diff --git a/test/performance/bench_common.h b/test/performance/bench_common.h
index bd611878d..4b59c941f 100644
--- a/test/performance/bench_common.h
+++ b/test/performance/bench_common.h
@@ -2,6 +2,8 @@
  * Copyright (c) 2023 Nokia
  */
 
+/** @cond _ODP_HIDE_FROM_DOXYGEN_ */
+
 #ifndef BENCH_COMMON_H
 #define BENCH_COMMON_H
 
diff --git a/test/performance/dummy_crc.h b/test/performance/dummy_crc.h
index 68928abee..01e6c2433 100644
--- a/test/performance/dummy_crc.h
+++ b/test/performance/dummy_crc.h
@@ -37,6 +37,8 @@
  *   OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  */
 
+/** @cond _ODP_HIDE_FROM_DOXYGEN_ */
+
 /**
  * @file
  *
diff --git a/test/performance/odp_atomic_perf.c b/test/performance/odp_atomic_perf.c
index 28217f5d7..b87a5666c 100644
--- a/test/performance/odp_atomic_perf.c
+++ b/test/performance/odp_atomic_perf.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_atomic_perf.c
+ *
+ * Performance test application for atomic operation APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_bench_buffer.c b/test/performance/odp_bench_buffer.c
index 8b041eee0..c85340d92 100644
--- a/test/performance/odp_bench_buffer.c
+++ b/test/performance/odp_bench_buffer.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_bench_buffer.c
+ *
+ * Microbenchmark application for buffer API functions
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <odp_api.h>
 #include <odp/helper/odph_api.h>
 
diff --git a/test/performance/odp_bench_misc.c b/test/performance/odp_bench_misc.c
index c9c9f0d75..61afdc398 100644
--- a/test/performance/odp_bench_misc.c
+++ b/test/performance/odp_bench_misc.c
@@ -4,6 +4,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_bench_misc.c
+ *
+ * Microbenchmark application for miscellaneous API functions
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE /* Needed for sigaction */
 #endif
diff --git a/test/performance/odp_bench_packet.c b/test/performance/odp_bench_packet.c
index 67b6b9cfc..57f9ef4b9 100644
--- a/test/performance/odp_bench_packet.c
+++ b/test/performance/odp_bench_packet.c
@@ -6,9 +6,11 @@
  */
 
 /**
- * @file
+ * @example odp_bench_packet.c
  *
- * @example odp_bench_packet.c  Microbenchmarks for packet functions
+ * Microbenchmark application for packet API functions
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
  */
 
 #include <stdlib.h>
diff --git a/test/performance/odp_bench_pktio_sp.c b/test/performance/odp_bench_pktio_sp.c
index 65d85a062..017e7565f 100644
--- a/test/performance/odp_bench_pktio_sp.c
+++ b/test/performance/odp_bench_pktio_sp.c
@@ -2,6 +2,14 @@
  * Copyright (c) 2023 Nokia
  */
 
+/**
+ * @example odp_bench_pktio_sp.c
+ *
+ * Microbenchmark application for packet IO slow path functions
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE /* Needed for sigaction */
 #endif
diff --git a/test/performance/odp_bench_timer.c b/test/performance/odp_bench_timer.c
index 78dd9e2d2..65c7a9168 100644
--- a/test/performance/odp_bench_timer.c
+++ b/test/performance/odp_bench_timer.c
@@ -4,6 +4,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_bench_timer.c
+ *
+ * Microbenchmark application for timer API functions
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE /* Needed for sigaction */
 #endif
diff --git a/test/performance/odp_cpu_bench.c b/test/performance/odp_cpu_bench.c
index 7ef12dc30..0ce8aa3fb 100644
--- a/test/performance/odp_cpu_bench.c
+++ b/test/performance/odp_cpu_bench.c
@@ -4,6 +4,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_cpu_bench.c
+ *
+ * Application for CPU stress testing
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <odp_api.h>
 #include <odp/helper/odph_api.h>
 
diff --git a/test/performance/odp_crc.c b/test/performance/odp_crc.c
index 89e8af837..89e2e971f 100644
--- a/test/performance/odp_crc.c
+++ b/test/performance/odp_crc.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_crc.c
+ *
+ * Performance test application for CRC hash APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_crypto.c b/test/performance/odp_crypto.c
index 93315ce05..1ae09abab 100644
--- a/test/performance/odp_crypto.c
+++ b/test/performance/odp_crypto.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:	BSD-3-Clause
  */
 
+/**
+ * @example odp_crypto.c
+ *
+ * Performance test application for crypto APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif /* _GNU_SOURCE */
diff --git a/test/performance/odp_dma_perf.c b/test/performance/odp_dma_perf.c
index 21c9c0558..f843843c8 100644
--- a/test/performance/odp_dma_perf.c
+++ b/test/performance/odp_dma_perf.c
@@ -3,12 +3,14 @@
  */
 
 /**
- * DMA performance tester
+ * @example odp_dma_perf.c
  *
  * This tester application can be used to profile the performance of an ODP DMA implementation.
  * Tester workflow is simple and consists of issuing as many back-to-back DMA transfers as the
  * implementation allows and then recording key performance statistics (such as function overhead,
  * latencies etc.).
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
  */
 
 #ifndef _GNU_SOURCE
diff --git a/test/performance/odp_dmafwd.c b/test/performance/odp_dmafwd.c
index 188a8e358..088fc69e2 100644
--- a/test/performance/odp_dmafwd.c
+++ b/test/performance/odp_dmafwd.c
@@ -3,12 +3,14 @@
  */
 
 /**
- * DMA forwarder
+ * @example odp_dmafwd.c
  *
  * This tester application can be used to profile the performance of an ODP DMA implementation.
  * Tester workflow consists of packet reception, copy and forwarding steps. Packets are first
  * received from configured interfaces after which packets are copied, either with plain SW memory
  * copy or with DMA offload copy. Finally, copied packets are echoed back to the sender(s).
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
  */
 
 #ifndef _GNU_SOURCE
diff --git a/test/performance/odp_ipsec.c b/test/performance/odp_ipsec.c
index 8a0bc2989..77437a918 100644
--- a/test/performance/odp_ipsec.c
+++ b/test/performance/odp_ipsec.c
@@ -6,6 +6,14 @@
  * SPDX-License-Identifier:	BSD-3-Clause
  */
 
+/**
+ * @example odp_ipsec.c
+ *
+ * Performance test application for IPsec APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif /* _GNU_SOURCE */
diff --git a/test/performance/odp_ipsecfwd.c b/test/performance/odp_ipsecfwd.c
index 5c35d67f7..0220cf6ae 100644
--- a/test/performance/odp_ipsecfwd.c
+++ b/test/performance/odp_ipsecfwd.c
@@ -2,6 +2,15 @@
  * Copyright (c) 2022-2023 Nokia
  */
 
+/**
+ * @example odp_ipsecfwd.c
+ *
+ * Simple IPsec performance tester application which forwards and processes
+ * plain and IPsec packets.
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
 #endif
diff --git a/test/performance/odp_lock_perf.c b/test/performance/odp_lock_perf.c
index c12f8c950..0f78db3b8 100644
--- a/test/performance/odp_lock_perf.c
+++ b/test/performance/odp_lock_perf.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_lock_perf.c
+ *
+ * Performance test application for lock APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_mem_perf.c b/test/performance/odp_mem_perf.c
index 56a3cdf9a..241128b1f 100644
--- a/test/performance/odp_mem_perf.c
+++ b/test/performance/odp_mem_perf.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_mem_perf.c
+ *
+ * Test application for measuring memory system bandwidth
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_packet_gen.c b/test/performance/odp_packet_gen.c
index 247ea2eb6..c88535791 100644
--- a/test/performance/odp_packet_gen.c
+++ b/test/performance/odp_packet_gen.c
@@ -4,6 +4,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_packet_gen.c
+ *
+ * Performance optimized packet generator application
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 /* enable usleep */
 #ifndef _GNU_SOURCE
 #define _GNU_SOURCE
diff --git a/test/performance/odp_pktio_ordered.c b/test/performance/odp_pktio_ordered.c
index bd43ad53d..6177a8160 100644
--- a/test/performance/odp_pktio_ordered.c
+++ b/test/performance/odp_pktio_ordered.c
@@ -5,9 +5,11 @@
  */
 
 /**
- * @file
+ * @example odp_pktio_ordered.c
  *
- * @example odp_pktio_ordered.c  ODP ordered pktio test application
+ * Test application for ordered packet IO
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
  */
 
 /** enable strtok */
diff --git a/test/performance/odp_pktio_perf.c b/test/performance/odp_pktio_perf.c
index 06620fd27..4cfeb50cf 100644
--- a/test/performance/odp_pktio_perf.c
+++ b/test/performance/odp_pktio_perf.c
@@ -2,14 +2,16 @@
  * All rights reserved.
  *
  * SPDX-License-Identifier:     BSD-3-Clause
+ */
+
+/**
+ * @example odp_pktio_perf.c
  *
- * ODP Packet IO basic performance test application.
- *
- * Runs a number of transmit and receive workers on separate cores, the
- * transmitters generate packets at a defined rate and the receivers consume
- * them. Generated packets are UDP and each packet is marked with a magic
- * number in the UDP payload allowing receiver to distinguish them from other
- * traffic.
+ * Packet IO basic performance test application. Runs a number of transmit and
+ * receive workers on separate cores, the transmitters generate packets at a
+ * defined rate and the receivers consume them. Generated packets are UDP and
+ * each packet is marked with a magic number in the UDP payload allowing
+ * receiver to distinguish them from other traffic.
  *
  * Each test iteration runs for a fixed period, at the end of the iteration
  * it is verified that the number of packets transmitted was as expected and
@@ -19,6 +21,7 @@
  * determine the maximum rate at which no packet loss occurs. Alternatively
  * a single packet rate can be specified on the command line.
  *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
  */
 
 #include <odp_api.h>
diff --git a/test/performance/odp_pool_perf.c b/test/performance/odp_pool_perf.c
index 4ae2cf7d3..43a39a21e 100644
--- a/test/performance/odp_pool_perf.c
+++ b/test/performance/odp_pool_perf.c
@@ -6,6 +6,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_pool_perf.c
+ *
+ * Performance test application for pool APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_queue_perf.c b/test/performance/odp_queue_perf.c
index 4e4446610..7d4612cb8 100644
--- a/test/performance/odp_queue_perf.c
+++ b/test/performance/odp_queue_perf.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_queue_perf.c
+ *
+ * Performance test application for queue APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_random.c b/test/performance/odp_random.c
index 46134ac0c..99714d7b3 100644
--- a/test/performance/odp_random.c
+++ b/test/performance/odp_random.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_random.c
+ *
+ * Performance test application for random data APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_sched_latency.c b/test/performance/odp_sched_latency.c
index c8dc74656..0fec49fb9 100644
--- a/test/performance/odp_sched_latency.c
+++ b/test/performance/odp_sched_latency.c
@@ -6,9 +6,11 @@
  */
 
 /**
- * @file
+ * @example odp_sched_latency.c
  *
- * @example odp_sched_latency.c  ODP scheduling latency benchmark application
+ * Scheduling latency benchmark application
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
  */
 
 #include <string.h>
diff --git a/test/performance/odp_sched_perf.c b/test/performance/odp_sched_perf.c
index f89705576..4cd4c3ac4 100644
--- a/test/performance/odp_sched_perf.c
+++ b/test/performance/odp_sched_perf.c
@@ -5,6 +5,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_sched_perf.c
+ *
+ * Performance test application for scheduling
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_sched_pktio.c b/test/performance/odp_sched_pktio.c
index 3a85a91a5..d8ab1b279 100644
--- a/test/performance/odp_sched_pktio.c
+++ b/test/performance/odp_sched_pktio.c
@@ -4,6 +4,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_sched_pktio.c
+ *
+ * Test application for scheduled packet IO
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <signal.h>
diff --git a/test/performance/odp_scheduling.c b/test/performance/odp_scheduling.c
index f9c083c92..86a6be530 100644
--- a/test/performance/odp_scheduling.c
+++ b/test/performance/odp_scheduling.c
@@ -5,9 +5,11 @@
  */
 
 /**
- * @file
+ * @example odp_scheduling.c
  *
- * @example  odp_example.c ODP example application
+ * Performance test application for miscellaneous scheduling operations
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
  */
 
 #include <string.h>
diff --git a/test/performance/odp_stash_perf.c b/test/performance/odp_stash_perf.c
index ffbc92b4b..cb223999e 100644
--- a/test/performance/odp_stash_perf.c
+++ b/test/performance/odp_stash_perf.c
@@ -4,6 +4,14 @@
  * Copyright (c) 2023 Arm
  */
 
+/**
+ * @example odp_stash_perf.c
+ *
+ * Performance test application for stash APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_stress.c b/test/performance/odp_stress.c
index 84bc4fe6c..4fbc303ae 100644
--- a/test/performance/odp_stress.c
+++ b/test/performance/odp_stress.c
@@ -4,6 +4,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_stress.c
+ *
+ * Test application that can be used to stress CPU, memory, and HW accelerators.
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>
diff --git a/test/performance/odp_timer_perf.c b/test/performance/odp_timer_perf.c
index 8632fcb73..16e2cb151 100644
--- a/test/performance/odp_timer_perf.c
+++ b/test/performance/odp_timer_perf.c
@@ -4,6 +4,14 @@
  * SPDX-License-Identifier:     BSD-3-Clause
  */
 
+/**
+ * @example odp_timer_perf.c
+ *
+ * Performance test application for timer APIs
+ *
+ * @cond _ODP_HIDE_FROM_DOXYGEN_
+ */
+
 #include <stdio.h>
 #include <string.h>
 #include <stdint.h>