diff options
| -rw-r--r-- | os/kernel/src/chevents.c | 1 | ||||
| -rw-r--r-- | readme.txt | 1 | ||||
| -rw-r--r-- | test/test.c | 60 | ||||
| -rw-r--r-- | test/test.dox | 6 | ||||
| -rw-r--r-- | test/test.h | 80 | ||||
| -rw-r--r-- | test/testbmk.c | 6 | ||||
| -rw-r--r-- | test/testdyn.c | 6 | ||||
| -rw-r--r-- | test/testevt.c | 6 | ||||
| -rw-r--r-- | test/testheap.c | 6 | ||||
| -rw-r--r-- | test/testmbox.c | 6 | ||||
| -rw-r--r-- | test/testmsg.c | 6 | ||||
| -rw-r--r-- | test/testmtx.c | 6 | ||||
| -rw-r--r-- | test/testpools.c | 4 | ||||
| -rw-r--r-- | test/testqueues.c | 6 | ||||
| -rw-r--r-- | test/testsem.c | 6 | ||||
| -rw-r--r-- | test/testthd.c | 6 |
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,
|