From 3d2fd8eb545182334b672c52acd7b8a06193bedf Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Fri, 8 May 2009 14:06:45 +0000
Subject: git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@951
 35acf78f-673a-0410-8e92-d51de3d6d3f4

---
 docs/src/main.dox |  5 ++++
 test/testbmk.c    |  3 ---
 test/testdyn.c    | 51 +++++++++++++++++++++++++++++++++++++++
 test/testevt.c    | 71 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 test/testheap.c   | 37 +++++++++++++++++++++++++++++
 test/testmbox.c   | 36 ++++++++++++++++++++++++++++
 test/testmsg.c    | 35 +++++++++++++++++++++++++++
 test/testqueues.c |  7 ++----
 test/testserial.c |  9 +++----
 test/testthd.c    |  8 ++-----
 10 files changed, 242 insertions(+), 20 deletions(-)

diff --git a/docs/src/main.dox b/docs/src/main.dox
index 59b9f3f6d..184bfab11 100644
--- a/docs/src/main.dox
+++ b/docs/src/main.dox
@@ -81,8 +81,13 @@
  *
  * <h2>Test Modules</h2>
  * - @subpage test_threads
+ * - @subpage test_dynamic
+ * - @subpage test_msg
+ * - @subpage test_events
+ * - @subpage test_mbox
  * - @subpage test_queues
  * - @subpage test_serial
+ * - @subpage test_heap
  * - @subpage test_benchmarks
  * .
  */
diff --git a/test/testbmk.c b/test/testbmk.c
index 90f49ae5d..3c82c5e0d 100644
--- a/test/testbmk.c
+++ b/test/testbmk.c
@@ -37,9 +37,6 @@
  * <h2>Preconditions</h2>
  * None.
  *
- * <h2>Waivers</h2>
- * Not applicable.
- *
  * <h2>Test Cases</h2>
  * - @subpage test_benchmarks_001
  * - @subpage test_benchmarks_002
diff --git a/test/testdyn.c b/test/testdyn.c
index bd32064e1..536bcadda 100644
--- a/test/testdyn.c
+++ b/test/testdyn.c
@@ -21,8 +21,49 @@
 
 #include "test.h"
 
+/**
+ * @page test_dynamic Dynamic Thread APIs test
+ *
+ * <h2>Description</h2>
+ * This module implements the test sequence for the dynamic thread creation
+ * APIs.
+ *
+ * <h2>Objective</h2>
+ * Objective of the test module is to cover 100% of the dynamic APIs code
+ * as a necessary step in order to assess their readyness.
+ *
+ * <h2>Preconditions</h2>
+ * The module requires the following kernel options:
+ * - @p CH_USE_DYNAMIC
+ * - @p CH_USE_HEAP
+ * - @p CH_USE_MEMPOOLS
+ * .
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
+ *
+ * <h2>Test Cases</h2>
+ * - @subpage test_dynamic_001
+ * - @subpage test_dynamic_002
+ * .
+ * @file testdyn.c
+ * @brief Dynamic thread APIs test source file
+ * @file testdyn.h
+ * @brief Dynamic thread APIs test header file
+ */
+
 #if CH_USE_DYNAMIC
 
+/**
+ * @page test_dynamic_001 Threads creation from Memory Heap
+ *
+ * <h2>Description</h2>
+ * Two threads are started by allocating the memory from the Memory Heap then
+ * the remaining heap space is arbitrarily allocated and a third tread startup
+ * is attempted.<br>
+ * The test expects the first two threads to successfully start and the last
+ * one to fail.
+ */
+
 static msg_t thread(void *p) {
 
   test_emit_token(*(char *)p);
@@ -80,6 +121,16 @@ const struct testcase testdyn1 = {
 #endif /* CH_USE_HEAP */
 
 #if CH_USE_MEMPOOLS
+/**
+ * @page test_dynamic_002 Threads creation from Memory Pool
+ *
+ * <h2>Description</h2>
+ * Five thread creation are attempted from a pool containing only four
+ * elements.<br>
+ * The test expects the first four threads to successfully start and the last
+ * one to fail.
+ */
+
 static MemoryPool mp1;
 
 static char *dyn2_gettest(void) {
diff --git a/test/testevt.c b/test/testevt.c
index db486601e..aa0a00da6 100644
--- a/test/testevt.c
+++ b/test/testevt.c
@@ -21,12 +21,54 @@
 
 #include "test.h"
 
+/**
+ * @page test_events Events test
+ *
+ * <h2>Description</h2>
+ * This module implements the test sequence for the @ref Events subsystem.
+ *
+ * <h2>Objective</h2>
+ * Objective of the test module is to cover 100% of the @ref Events subsystem
+ * code as a necessary step in order to assess its readyness.
+ *
+ * <h2>Preconditions</h2>
+ * The module requires the following kernel options:
+ * - @p CH_USE_EVENTS
+ * - @p CH_USE_EVENTS_TIMEOUT
+ * .
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
+ *
+ * <h2>Test Cases</h2>
+ * - @subpage test_events_001
+ * - @subpage test_events_002
+ * - @subpage test_events_003
+ * .
+ * @file testevt.c
+ * @brief Events test source file
+ * @file testevt.h
+ * @brief Events test header file
+ */
+
 #if CH_USE_EVENTS
 
 #define ALLOWED_DELAY MS2ST(5)
 
 static EventSource es1, es2;
 
+/**
+ * @page test_events_001 Events registration and dispatch
+ *
+ * <h2>Description</h2>
+ * Two event listeners are registered on an event source and then unregistered
+ * in the same order.<br>
+ * The test expects that the even source has listeners after the registrations
+ * and after the first unregistration, then, after the second unegistration,
+ * the test expects no more listeners.<br>
+ * In the second part the test dispatches three event flags and verifies that
+ * the associated event handlers are invoked in LSb-first order.
+ */
+
 static char *evt1_gettest(void) {
 
   return "Events, registration and dispatch";
@@ -71,6 +113,20 @@ const struct testcase testevt1 = {
   evt1_execute
 };
 
+/**
+ * @page test_events_002 Events wait and broadcast
+ *
+ * <h2>Description</h2>
+ * In this test the following APIs are indipently tested by starting threads
+ * that signal/broadcast events after fixed delays:
+ * - @p chEvtWaitOne()
+ * - @p chEvtWaitAny()
+ * - @p chEvtWaitAll()
+ * .
+ * After each test phase the test verifies that the events have been served at
+ * the expected time and that there are no stuck event flags.
+ */
+
 static char *evt2_gettest(void) {
 
   return "Events, wait and broadcast";
@@ -179,6 +235,21 @@ const struct testcase testevt2 = {
 };
 
 #if CH_USE_EVENTS_TIMEOUT
+/**
+ * @page test_events_003 Events timeout
+ *
+ * <h2>Description</h2>
+ * In this test the following APIs are let to timeout twice: immediatly and
+ * after 10ms:
+ * In this test the following APIs are indipently tested by starting threads
+ * that broadcast events after fixed delays:
+ * - @p chEvtWaitOneTimeout()
+ * - @p chEvtWaitAnyTimeout()
+ * - @p chEvtWaitAllTimeout()
+ * .
+ * After each test phase the test verifies that there are no stuck event flags.
+ */
+
 static char *evt3_gettest(void) {
 
   return "Events, timeouts";
diff --git a/test/testheap.c b/test/testheap.c
index fd04353e5..a617c4b68 100644
--- a/test/testheap.c
+++ b/test/testheap.c
@@ -21,10 +21,47 @@
 
 #include "test.h"
 
+/**
+ * @page test_heap Memory Heap test
+ *
+ * <h2>Description</h2>
+ * This module implements the test sequence for the @ref Heap subsystem.
+ *
+ * <h2>Objective</h2>
+ * Objective of the test module is to cover 100% of the @ref Heap subsystem
+ * code as a necessary step in order to assess its readyness.
+ *
+ * <h2>Preconditions</h2>
+ * The module requires the following kernel options:
+ * - @p CH_USE_HEAP
+ * .
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
+ *
+ * <h2>Test Cases</h2>
+ * - @subpage test_heap_001
+ * .
+ * @file testheap.c
+ * @brief Heap test source file
+ * @file testevt.h
+ * @brief Heap header file
+ */
+
 #if CH_USE_HEAP
 
 #define SIZE 16
 
+/**
+ * @page test_heap_001 Allocation and fragmentation test
+ *
+ * <h2>Description</h2>
+ * Series of allocations/deallocations are performed in carefully designed
+ * sequences in order to stimulate all the possible code paths inside the
+ * allocator.<br>
+ * The test expects to find the heap back to the initial status after each
+ * sequence.
+ */
+
 static char *heap1_gettest(void) {
 
   return "Heap, allocation and fragmentation test";
diff --git a/test/testmbox.c b/test/testmbox.c
index 9e3462ad4..2fe88b2b9 100644
--- a/test/testmbox.c
+++ b/test/testmbox.c
@@ -21,6 +21,33 @@
 
 #include "test.h"
 
+/**
+ * @page test_mbox Mailboxes test
+ *
+ * <h2>Description</h2>
+ * This module implements the test sequence for the @ref Mailboxes subsystem.
+ *
+ * <h2>Objective</h2>
+ * Objective of the test module is to cover 100% of the @ref Mailboxes
+ * subsystem code as a necessary step in order to assess its readyness.
+ *
+ * <h2>Preconditions</h2>
+ * The module requires the following kernel options:
+ * - @p CH_USE_MAILBOXES
+ * - @p CH_USE_SEMAPHORES_TIMEOUT
+ * .
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
+ *
+ * <h2>Test Cases</h2>
+ * - @subpage test_mbox_001
+ * .
+ * @file testmbox.c
+ * @brief Mailboxes test source file
+ * @file testmbox.h
+ * @brief Mailboxes header file
+ */
+
 #if CH_USE_MAILBOXES && CH_USE_SEMAPHORES_TIMEOUT
 
 #define ALLOWED_DELAY MS2ST(5)
@@ -29,6 +56,15 @@
 static msg_t mb1_buf[MB_SIZE];
 static Mailbox mb1;
 
+/**
+ * @page test_mbox_001 Queuing and timeouts
+ *
+ * <h2>Description</h2>
+ * Messages are posted/fetched from a mailbox in carefully designed sequences
+ * in order to stimulate all the possible code paths inside the mailbox.<br>
+ * The test expects to find a consistent mailbox status after each operation.
+ */
+
 static char *mbox1_gettest(void) {
 
   return "Mailboxes, queuing and timeouts";
diff --git a/test/testmsg.c b/test/testmsg.c
index 978ec0d7e..87ee64231 100644
--- a/test/testmsg.c
+++ b/test/testmsg.c
@@ -21,8 +21,43 @@
 
 #include "test.h"
 
+/**
+ * @page test_msg Messages test
+ *
+ * <h2>Description</h2>
+ * This module implements the test sequence for the @ref Messages subsystem.
+ *
+ * <h2>Objective</h2>
+ * Objective of the test module is to cover 100% of the @ref Messages
+ * subsystem code as a necessary step in order to assess its readyness.
+ *
+ * <h2>Preconditions</h2>
+ * The module requires the following kernel options:
+ * - @p CH_USE_MESSAGES
+ * .
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
+ *
+ * <h2>Test Cases</h2>
+ * - @subpage test_msg_001
+ * .
+ * @file testmsg.c
+ * @brief Messages test source file
+ * @file testmsg.h
+ * @brief Messages header file
+ */
+
 #if CH_USE_MESSAGES
 
+/**
+ * @page test_msg_001 Messages Server loop
+ *
+ * <h2>Description</h2>
+ * A thread is spawned that sends four messages back to the tester thread.<br>
+ * The test expect to receive the messages in the correct sequence and to
+ * not find a fifth message waiting.
+ */
+
 static char *msg1_gettest(void) {
 
   return "Messages, loop";
diff --git a/test/testqueues.c b/test/testqueues.c
index 53f6d3840..af0ade6e6 100644
--- a/test/testqueues.c
+++ b/test/testqueues.c
@@ -40,11 +40,8 @@
  * The module requires the following kernel options:
  * - @p CH_USE_QUEUES (and dependent options)
  * .
- * In case of the required options are not enabled some or all tests may be
- * skipped.
- *
- * <h2>Waivers</h2>
- * None.
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
  *
  * <h2>Test Cases</h2>
  * - @subpage test_queues_001
diff --git a/test/testserial.c b/test/testserial.c
index 61fc0315a..818d09e21 100644
--- a/test/testserial.c
+++ b/test/testserial.c
@@ -22,7 +22,7 @@
 #include "test.h"
 
 /**
- * @page test_serial Serial Driver test
+ * @page test_serial Serial Drivers test
  *
  * <h2>Description</h2>
  * This module implements the test sequence for the @ref Serial subsystem.
@@ -40,11 +40,8 @@
  * The module requires the following kernel options:
  * - @p CH_USE_SERIAL_FULLDUPLEX (and dependent options)
  * .
- * In case of the required options are not enabled some or all tests may be
- * skipped.
- *
- * <h2>Waivers</h2>
- * None.
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
  *
  * @file testserial.c
  * @brief Kernel Serial Driver test source file
diff --git a/test/testthd.c b/test/testthd.c
index 54db5430e..daf3e2063 100644
--- a/test/testthd.c
+++ b/test/testthd.c
@@ -38,10 +38,6 @@
  * <h2>Preconditions</h2>
  * None.
  *
- * <h2>Waivers</h2>
- * - The @p chThdExit() API is not code 100% covered because it cannot return.
- *   It must work this way by design.
- * .
  * <h2>Test Cases</h2>
  * - @subpage test_threads_001
  * - @subpage test_threads_002
@@ -49,9 +45,9 @@
  * - @subpage test_threads_004
  * .
  * @file testthd.c
- * @brief Threads and Scheduler test source file
+ * @brief Threads and @ref Scheduler test source file
  * @file testthd.h
- * @brief Threads and Scheduler test header file
+ * @brief Threads and @ref Scheduler test header file
  */
 
 /**
-- 
cgit v1.2.3