Documented test runtime code.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@1895 35acf78f-673a-0410-8e92-d51de3d6d3f4

16 files changed, 172 insertions, 40 deletions

diff --git a/os/kernel/src/chevents.c b/os/kernel/src/chevents.c
index 2bc145cac..22739443f 100644
--- a/os/kernel/src/chevents.c
+++ b/os/kernel/src/chevents.c
@@ -51,6 +51,7 @@
  *          enabled in @p chconf.h.

  * @{

  */

+

 #include "ch.h"

 

 #if CH_USE_EVENTS

diff --git a/readme.txt b/readme.txt
index c14d58b01..c05ba2de7 100644
--- a/readme.txt
+++ b/readme.txt
@@ -80,6 +80,7 @@
 - Various documentation fixes, added an article covering debugging under

   ChibiOS/RT, updated the article about interrupt handlers to cover also

   fast interrupt sources.

+- Long overdue test code cleanup and documentation.

 

 *** 1.5.5 ***

 - FIX: Removed some "dead" code in the old ARMv7-M files (there are new

diff --git a/test/test.c b/test/test.c
index 013a0b21f..0d52d479b 100644
--- a/test/test.c
+++ b/test/test.c
@@ -17,6 +17,14 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file    test.c

+ * @brief   Tests support code.

+ *

+ * @addtogroup test

+ * @{

+ */

+

 #include "ch.h"

 #include "hal.h"

 

@@ -78,6 +86,11 @@ void * const wa[5] = {test.wa.T0, test.wa.T1, test.wa.T2,
  */

 static BaseChannel *chp;

 

+/**

+ * @brief   Prints a decimal unsigned number.

+ *

+ * @param[in] n         the number to be printed

+ */

 void test_printn(uint32_t n) {

   char buf[16], *p;

 

@@ -92,12 +105,22 @@ void test_printn(uint32_t n) {
   }

 }

 

+/**

+ * @brief   Prints a line without final end-of-line.

+ *

+ * @param[in] msgp      the message

+ */

 void test_print(char *msgp) {

 

   while (*msgp)

     chIOPut(chp, *msgp++);

 }

 

+/**

+ * @brief   Prints a line.

+ *

+ * @param[in] msgp      the message

+ */

 void test_println(char *msgp) {

 

   test_print(msgp);

@@ -120,6 +143,11 @@ static void print_tokens(void) {
     chIOPut(chp, *cp++);

 }

 

+/**

+ * @brief   Emits a token into the tokens buffer.

+ *

+ * @param[in] token     the token as a char

+ */

 void test_emit_token(char token) {

 

   chSysLock();

@@ -165,6 +193,10 @@ bool_t _test_assert_time_window(unsigned point, systime_t start, systime_t end)
 /*

  * Threads utils.

  */

+

+/**

+ * @brief   Pends a termination request in all the test-spawned threads.

+ */

 void test_terminate_threads(void) {

   int i;

 

@@ -173,6 +205,9 @@ void test_terminate_threads(void) {
       chThdTerminate(threads[i]);

 }

 

+/**

+ * @brief   Waits for the completion of all the test-spawned threads.

+ */

 void test_wait_threads(void) {

   int i;

 

@@ -184,6 +219,12 @@ void test_wait_threads(void) {
 }

 

 #if CH_DBG_THREADS_PROFILING

+/**

+ * @brief   CPU pulse.

+ * @note    The current implementation is not totally reliable.

+ *

+ * @param[in] duration      CPU pulse duration in milliseconds

+ */

 void test_cpu_pulse(unsigned duration) {

   systime_t start, end, now;

 

@@ -200,6 +241,9 @@ void test_cpu_pulse(unsigned duration) {
 }

 #endif

 

+/**

+ * @brief Delays execution until next system time tick.

+ */

 systime_t test_wait_tick(void) {

 

   chThdSleep(1);

@@ -209,15 +253,22 @@ systime_t test_wait_tick(void) {
 /*

  * Timer utils.

  */

-static VirtualTimer vt;

+

+/** @brief Set to @p TRUE when the test timer reaches its deadline.*/

 bool_t test_timer_done;

 

+static VirtualTimer vt;

 static void tmr(void *p) {

   (void)p;

 

   test_timer_done = TRUE;

 }

 

+/**

+ * @brief   Starts the test timer.

+ *

+ * @param[in] ms        time in milliseconds

+ */

 void test_start_timer(unsigned ms) {

 

   systime_t duration = MS2ST(ms);

@@ -257,6 +308,11 @@ static void print_line(void) {
   chIOPut(chp, '\n');

 }

 

+/**

+ * @brief   Test execution thread function.

+ *

+ * @param[in] p         pointer to a @p BaseChannel object for test output

+ */

 msg_t TestThread(void *p) {

   int i, j;

 

@@ -326,3 +382,5 @@ msg_t TestThread(void *p) {
 

   return (msg_t)global_fail;

 }

+

+/** @} */

diff --git a/test/test.dox b/test/test.dox
index 5678e9090..beda6d0ea 100644
--- a/test/test.dox
+++ b/test/test.dox
@@ -18,6 +18,12 @@
 */

 

 /**

+ * @defgroup test Test Runtime

+ * @details Runtime code for the test suite execution, this code is not part

+ *          of the OS and should not be included in user applications.

+ */

+

+/**

  * @page testsuite Testing Strategy

  * <h2>Description</h2>

  * Most of the ChibiOS/RT demos link a set of software modules (test suite) in

diff --git a/test/test.h b/test/test.h
index 983a7b093..bcdc2e3a0 100644
--- a/test/test.h
+++ b/test/test.h
@@ -17,14 +17,28 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.

 */

 

+/**

+ * @file    test.h

+ * @brief   Tests support header.

+ *

+ * @addtogroup test

+ * @{

+ */

+

 #ifndef _TEST_H_

 #define _TEST_H_

 

-#ifndef DELAY_BETWEEN_TESTS

+/**

+ * @brief   Delay inserted between test cases.

+ */

+#if !defined(DELAY_BETWEEN_TESTS) || defined(__DOXYGEN__)

 #define DELAY_BETWEEN_TESTS     200

 #endif

 

-#ifndef TEST_NO_BENCHMARKS

+/**

+ * @brief   If @p TRUE then benchmarks are not included.

+ */

+#if !defined(TEST_NO_BENCHMARKS) || defined(__DOXYGEN__)

 #define TEST_NO_BENCHMARKS      FALSE

 #endif

 

@@ -42,11 +56,14 @@
 #endif

 #define WA_SIZE THD_WA_SIZE(THREADS_STACK_SIZE)

 

+/**

+ * @brief   Structure representing a test case.

+ */

 struct testcase {

-  char *(*gettest)(void);

-  void (*setup)(void);

-  void (*teardown)(void);

-  void (*execute)(void);

+  char *(*gettest)(void);       /**< @brief Test case name get function.    */

+  void (*setup)(void);          /**< @brief Test case preparation function. */

+  void (*teardown)(void);       /**< @brief Test case clean up function.    */

+  void (*execute)(void);        /**< @brief Test case execution function.   */

 };

 

 #ifndef __DOXYGEN__

@@ -88,29 +105,56 @@ extern "C" {
 }

 #endif

 

-#define test_fail(point) {                                              \

-  _test_fail(point);                                                    \

-  return;                                                               \

+/**

+ * @brief   Test failure enforcement.

+ */

+#define test_fail(point) {                                                  \

+  _test_fail(point);                                                        \

+  return;                                                                   \

 }

 

-#define test_assert(point, condition, msg) {                            \

-  if (_test_assert(point, condition))                                   \

-    return;                                                             \

+/**

+ * @brief   Test assertion.

+ *

+ * @param[in] point     numeric assertion identifier

+ * @param[in] condition a boolean expression that must be verified to be true

+ * @param[in] msg       failure message

+ */

+#define test_assert(point, condition, msg) {                                \

+  if (_test_assert(point, condition))                                       \

+    return;                                                                 \

 }

 

-#define test_assert_sequence(point, expected) {                         \

-  if (_test_assert_sequence(point, expected))                           \

-    return;                                                             \

+/**

+ * @brief   Test sequence assertion.

+ *

+ * @param[in] point     numeric assertion identifier

+ * @param[in] expected  string to be matched with the tokens buffer

+ */

+#define test_assert_sequence(point, expected) {                             \

+  if (_test_assert_sequence(point, expected))                               \

+    return;                                                                 \

 }

 

-#define test_assert_time_window(point, start, end) {                    \

-  if (_test_assert_time_window(point, start, end))                      \

-    return;                                                             \

+/**

+ * @brief   Test time window assertion.

+ *

+ * @param[in] point     numeric assertion identifier

+ * @param[in] start     initial time in the window (included)

+ * @param[in] end       final time in the window (not included)

+ */

+#define test_assert_time_window(point, start, end) {                        \

+  if (_test_assert_time_window(point, start, end))                          \

+    return;                                                                 \

 }

 

+#if !defined(__DOXYGEN__)

 extern Thread *threads[MAX_THREADS];

 extern union test_buffers test;

 extern void * const wa[];

 extern bool_t test_timer_done;

+#endif

 

 #endif /* _TEST_H_ */

+

+/** @} */

diff --git a/test/testbmk.c b/test/testbmk.c
index 565c0c066..9e0d687e2 100644
--- a/test/testbmk.c
+++ b/test/testbmk.c
@@ -23,6 +23,8 @@
 /**

  * @page test_benchmarks Kernel Benchmarks

  *

+ * File: @ref testbmk.c

+ *

  * <h2>Description</h2>

  * This module implements a series of system benchmarks. The benchmarks are

  * useful as a stress test and as a reference when comparing ChibiOS/RT

@@ -744,8 +746,8 @@ const struct testcase testbmk13 = {
   bmk13_execute

 };

 

-/*

- * Test sequence for benchmarks pattern.

+/**

+ * @brief   Test sequence for benchmarks.

  */

 const struct testcase * const patternbmk[] = {

 #if !TEST_NO_BENCHMARKS

diff --git a/test/testdyn.c b/test/testdyn.c
index cb6b40908..2d05f346b 100644
--- a/test/testdyn.c
+++ b/test/testdyn.c
@@ -23,6 +23,8 @@
 /**

  * @page test_dynamic Dynamic APIs test

  *

+ * File: @ref testdyn.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the dynamic thread creation

  * APIs.

@@ -189,8 +191,8 @@ const struct testcase testdyn2 = {
 

 #endif /* CH_USE_DYNAMIC */

 

-/*

- * Test sequence for dynamic APIs pattern.

+/**

+ * @brief   Test sequence for dynamic APIs.

  */

 const struct testcase * const patterndyn[] = {

 #if CH_USE_DYNAMIC

diff --git a/test/testevt.c b/test/testevt.c
index f8844d3a4..52ffc5ccd 100644
--- a/test/testevt.c
+++ b/test/testevt.c
@@ -23,6 +23,8 @@
 /**

  * @page test_events Events test

  *

+ * File: @ref testevt.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref events subsystem.

  *

@@ -293,8 +295,8 @@ const struct testcase testevt3 = {
 };

 #endif /* CH_USE_EVENTS_TIMEOUT */

 

-/*

- * Test sequence for events pattern.

+/**

+ * @brief   Test sequence for events.

  */

 const struct testcase * const patternevt[] = {

 #if CH_USE_EVENTS

diff --git a/test/testheap.c b/test/testheap.c
index 84936babc..2f4998be6 100644
--- a/test/testheap.c
+++ b/test/testheap.c
@@ -23,6 +23,8 @@
 /**

  * @page test_heap Memory Heap test

  *

+ * File: @ref testheap.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref heaps subsystem.

  *

@@ -151,8 +153,8 @@ const struct testcase testheap1 = {
 

 #endif /* CH_USE_HEAP.*/

 

-/*

- * Test sequence for heap pattern.

+/**

+ * @brief   Test sequence for heap.

  */

 const struct testcase * const patternheap[] = {

 #if CH_USE_HEAP

diff --git a/test/testmbox.c b/test/testmbox.c
index 707b112ef..b3fa57470 100644
--- a/test/testmbox.c
+++ b/test/testmbox.c
@@ -23,6 +23,8 @@
 /**

  * @page test_mbox Mailboxes test

  *

+ * File: @ref testmbox.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref mailboxes subsystem.

  *

@@ -167,8 +169,8 @@ const struct testcase testmbox1 = {
 

 #endif /* CH_USE_MAILBOXES */

 

-/*

- * Test sequence for mailboxes pattern.

+/**

+ * @brief   Test sequence for mailboxes.

  */

 const struct testcase * const patternmbox[] = {

 #if CH_USE_MAILBOXES

diff --git a/test/testmsg.c b/test/testmsg.c
index 5669f733e..3757f1de9 100644
--- a/test/testmsg.c
+++ b/test/testmsg.c
@@ -23,6 +23,8 @@
 /**

  * @page test_msg Messages test

  *

+ * File: @ref testmsg.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref messages subsystem.

  *

@@ -113,8 +115,8 @@ const struct testcase testmsg1 = {
 

 #endif /* CH_USE_MESSAGES */

 

-/*

- * Test sequence for messages pattern.

+/**

+ * @brief   Test sequence for messages.

  */

 const struct testcase * const patternmsg[] = {

 #if CH_USE_MESSAGES

diff --git a/test/testmtx.c b/test/testmtx.c
index 2ac3059b3..f1d7b6d2a 100644
--- a/test/testmtx.c
+++ b/test/testmtx.c
@@ -23,6 +23,8 @@
 /**

  * @page test_mtx Mutexes test

  *

+ * File: @ref testmtx.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref mutexes and

  * @ref condvars subsystems.<br>

@@ -643,8 +645,8 @@ const struct testcase testmtx8 = {
 #endif /* CH_USE_CONDVARS */

 #endif /* CH_USE_MUTEXES */

 

-/*

- * Test sequence for mutexes pattern.

+/**

+ * @brief   Test sequence for mutexes.

  */

 const struct testcase * const patternmtx[] = {

 #if CH_USE_MUTEXES

diff --git a/test/testpools.c b/test/testpools.c
index bed35c8f8..75b26d50f 100644
--- a/test/testpools.c
+++ b/test/testpools.c
@@ -23,6 +23,8 @@
 /**

  * @page test_pools Memory Pools test

  *

+ * File: @ref testpools.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref pools subsystem.

  *

@@ -93,7 +95,7 @@ const struct testcase testpools1 = {
 #endif /* CH_USE_MEMPOOLS */

 

 /*

- * Test sequence for pools pattern.

+ * @brief   Test sequence for pools.

  */

 const struct testcase * const patternpools[] = {

 #if CH_USE_MEMPOOLS

diff --git a/test/testqueues.c b/test/testqueues.c
index 0f2ae7a81..8247cbd07 100644
--- a/test/testqueues.c
+++ b/test/testqueues.c
@@ -23,6 +23,8 @@
 /**

  * @page test_queues I/O Queues test

  *

+ * File: @ref testqueues.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref io_queues subsystem.

  * The tests are performed by inserting and removing data from queues and by

@@ -204,8 +206,8 @@ const struct testcase testqueues2 = {
 };

 #endif /* CH_USE_QUEUES */

 

-/*

- * Test sequence for queues pattern.

+/**

+ * @brief   Test sequence for queues.

  */

 const struct testcase * const patternqueues[] = {

 #if CH_USE_QUEUES

diff --git a/test/testsem.c b/test/testsem.c
index bc7162de5..dd9db66cd 100644
--- a/test/testsem.c
+++ b/test/testsem.c
@@ -23,6 +23,8 @@
 /**

  * @page test_sem Semaphores test

  *

+ * File: @ref testsem.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref semaphores subsystem.

  *

@@ -242,8 +244,8 @@ const struct testcase testsem3 = {
 #endif /* CH_USE_SEMSW */

 #endif /* CH_USE_SEMAPHORES */

 

-/*

- * Test sequence for semaphores pattern.

+/**

+ * @brief   Test sequence for semaphores.

  */

 const struct testcase * const patternsem[] = {

 #if CH_USE_SEMAPHORES

diff --git a/test/testthd.c b/test/testthd.c
index 08b792ce4..c2150a9c1 100644
--- a/test/testthd.c
+++ b/test/testthd.c
@@ -23,6 +23,8 @@
 /**

  * @page test_threads Threads and Scheduler test

  *

+ * File: @ref testthd.c

+ *

  * <h2>Description</h2>

  * This module implements the test sequence for the @ref scheduler,

  * @ref threads and @ref time subsystems.<br>

@@ -236,8 +238,8 @@ const struct testcase testthd4 = {
   thd4_execute

 };

 

-/*

- * Test sequence for threads patterns.

+/**

+ * @brief   Test sequence for threads.

  */

 const struct testcase * const patternthd[] = {

   &testthd1,