From 83d50f08219d05f65b55f686e74e5cb4e7352092 Mon Sep 17 00:00:00 2001
From: gdisirio <gdisirio@35acf78f-673a-0410-8e92-d51de3d6d3f4>
Date: Sat, 9 May 2009 16:46:49 +0000
Subject: Finished adding tests documentation to the general documentation.

git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@963 35acf78f-673a-0410-8e92-d51de3d6d3f4
---
 test/testmtx.c    |  6 ++---
 test/testpools.c  | 37 +++++++++++++++++++++++++++++-
 test/testsem.c    | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++----
 test/testserial.c |  2 +-
 4 files changed, 104 insertions(+), 9 deletions(-)

(limited to 'test')

diff --git a/test/testmtx.c b/test/testmtx.c
index 72865e7f8..9ecf62f30 100644
--- a/test/testmtx.c
+++ b/test/testmtx.c
@@ -466,7 +466,7 @@ const struct testcase testmtx5 = {
 
 #if CH_USE_CONDVARS
 /**
- * @page test_mtx_006 Signal test
+ * @page test_mtx_006 Condition Variable signal test
  *
  * <h2>Description</h2>
  * Five threads take a mutex and then enter a conditional variable queue, the
@@ -523,7 +523,7 @@ const struct testcase testmtx6 = {
 };
 
 /**
- * @page test_mtx_007 Broadcast test
+ * @page test_mtx_007 Condition Variable broadcast test
  *
  * <h2>Description</h2>
  * Five threads take a mutex and then enter a conditional variable queue, the
@@ -564,7 +564,7 @@ const struct testcase testmtx7 = {
 };
 
 /**
- * @page test_mtx_008 Priority Inheritance boost test
+ * @page test_mtx_008 Condition Variable priority boost test
  *
  * <h2>Description</h2>
  * This test case verifies the priority boost of a thread waiting on a
diff --git a/test/testpools.c b/test/testpools.c
index abf63d700..78f19a91c 100644
--- a/test/testpools.c
+++ b/test/testpools.c
@@ -21,13 +21,48 @@
 
 #include "test.h"
 
+/**
+ * @page test_pools Memory Pools test
+ *
+ * <h2>Description</h2>
+ * This module implements the test sequence for the @ref MemoryPools subsystem.
+ *
+ * <h2>Objective</h2>
+ * Objective of the test module is to cover 100% of the @ref MemoryPools
+ * code as a necessary step in order to assess its maturity level.<br>
+ *
+ * <h2>Preconditions</h2>
+ * The module requires the following kernel options:
+ * - @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_pools_001
+ * .
+ * @file testpools.c
+ * @brief Memory Pools test source file
+ * @file testpools.h
+ * @brief Memory Pools test header file
+ */
+
 #if CH_USE_MEMPOOLS
 
 static MemoryPool mp1;
 
+/**
+ * @page test_pools_001 Allocation and enqueuing test
+ *
+ * <h2>Description</h2>
+ * Five memory blocks are added to a memory pool then removed.<br>
+ * The test expects to find the pool queue in the proper status after each
+ * operation.
+ */
+
 static char *pools1_gettest(void) {
 
-  return "Memory Pools, allocation and enqueuing test";
+  return "Memory Pools, queue/dequeue";
 }
 
 static void pools1_setup(void) {
diff --git a/test/testsem.c b/test/testsem.c
index 9471de643..7cb103789 100644
--- a/test/testsem.c
+++ b/test/testsem.c
@@ -21,15 +21,53 @@
 
 #include "test.h"
 
+/**
+ * @page test_sem Semaphores test
+ *
+ * <h2>Description</h2>
+ * This module implements the test sequence for the @ref Semaphores subsystem.
+ *
+ * <h2>Objective</h2>
+ * Objective of the test module is to cover 100% of the @ref Semaphores
+ * code as a necessary step in order to assess its maturity level.<br>
+ *
+ * <h2>Preconditions</h2>
+ * The module requires the following kernel options:
+ * - @p CH_USE_SEMAPHORES
+ * .
+ * In case some of the required options are not enabled then some or all tests
+ * may be skipped.
+ *
+ * <h2>Test Cases</h2>
+ * - @subpage test_sem_001
+ * - @subpage test_sem_002
+ * - @subpage test_sem_003
+ * .
+ * @file testsem.c
+ * @brief Semaphores test source file
+ * @file testsem.h
+ * @brief Semaphores test header file
+ */
+
 #if CH_USE_SEMAPHORES
 
 #define ALLOWED_DELAY MS2ST(5)
 
 static Semaphore sem1;
 
+/**
+ * @page test_sem_001 Enqueuing test
+ *
+ * <h2>Description</h2>
+ * Five threads with randomized priorities are enqueued to a semaphore then
+ * awakened one at time.<br>
+ * The test expects that the threads reach their goal in FIFO order or
+ * priority order depending on the CH_USE_SEMAPHORES_PRIORITY configuration
+ * setting.
+ */
 static char *sem1_gettest(void) {
 
-  return "Semaphores, enqueuing test";
+  return "Semaphores, enqueuing";
 }
 
 static void sem1_setup(void) {
@@ -64,6 +102,16 @@ static void sem1_execute(void) {
 #endif
 }
 
+/**
+ * @page test_sem_002 Timeout test
+ *
+ * <h2>Description</h2>
+ * The three possible semaphore waiting modes (do not wait, wait with timeout,
+ * wait without timeout) are explored.<br>
+ * The test expects that the semaphore wait function returns the correct value
+ * in each of the above scenario and that the semaphore structure status is
+ * correct after each operation.
+ */
 const struct testcase testsem1 = {
   sem1_gettest,
   sem1_setup,
@@ -73,7 +121,7 @@ const struct testcase testsem1 = {
 
 static char *sem2_gettest(void) {
 
-  return "Semaphores, timeout test";
+  return "Semaphores, timeout";
 }
 
 static void sem2_setup(void) {
@@ -108,7 +156,7 @@ static void sem2_execute(void) {
    * Testing not timeout condition.
    */
   threads[0] = chThdCreateStatic(wa[0], WA_SIZE, chThdGetPriority() - 1,
-                                 thread2, "A");
+                                 thread2, 0);
   msg = chSemWaitTimeout(&sem1, MS2ST(500));
   test_wait_threads();
   test_assert(4, msg == RDY_OK, "wrong wake-up message");
@@ -139,6 +187,18 @@ const struct testcase testsem2 = {
 };
 
 #if CH_USE_SEMSW
+/**
+ * @page test_sem_003 Atomic signal-wait test
+ *
+ * <h2>Description</h2>
+ * This test case explicitly address the @p chSemWaitSignal() function. A
+ * thread is created that performs a wait and a signal operations.
+ * The tester thread is awakened from an atomic wait/signal operation.<br>
+ * The test expects that the semaphore wait function returns the correct value
+ * in each of the above scenario and that the semaphore structure status is
+ * correct after each operation.
+ */
+
 static char *sem3_gettest(void) {
 
   return "Semaphores, atomic signal-wait";
@@ -158,7 +218,7 @@ static msg_t thread3(void *p) {
 
 static void sem3_execute(void) {
 
-  threads[0] = chThdCreateStatic(wa[0], WA_SIZE, chThdGetPriority()+1, thread3, "A");
+  threads[0] = chThdCreateStatic(wa[0], WA_SIZE, chThdGetPriority()+1, thread3, 0);
   chSemSignalWait(&sem1, &sem1);
   test_assert(1, isempty(&sem1.s_queue), "queue not empty");
   test_assert(2, sem1.s_cnt == 0, "counter not zero");
diff --git a/test/testserial.c b/test/testserial.c
index 19d7265ab..84db657ec 100644
--- a/test/testserial.c
+++ b/test/testserial.c
@@ -38,7 +38,7 @@
  *
  * <h2>Preconditions</h2>
  * The module requires the following kernel options:
- * - @p CH_USE_SERIAL_FULLDUPLEX (and dependent options)
+ * - @p CH_USE_SERIAL_FULLDUPLEX
  * .
  * In case some of the required options are not enabled then some or all tests
  * may be skipped.
-- 
cgit v1.2.3