Added xassert doc

module_xassert/doc/Makefile

@@ -0,0 +1 @@
+SOURCE_INCLUDE_DIRS = ..

module_xassert/doc/xassert.rst

@@ -0,0 +1,2 @@
+.. code_rst_include:: src/xassert.h
+

module_xassert/src/xassert.h

@@ -1,6 +1,109 @@
 #ifndef __xassert_h__
 #define __xassert_h__
 
+/****
+xassert Module
+==============
+
+This module provides a lightweight and flexible replacement for the
+standard C header ``assert.h``.
+
+The assertions in this module can be be enabled/disabled
+and configured as to how much debug information they show. This
+configuration can be per "debug unit" (i.e. for sets of files).
+
+To use the module you need to use ``module_xassert`` in your application and
+include the ``xassert.h`` header.
+
+Assertions
+----------
+
+An assertion can be inserted into code with the ``assert`` macro e.g.::
+
+   assert(i < n);
+
+Optionally a debug message can be added with the ``_msg`` function::
+
+   assert(i < n && _msg("i must be less than the array bound"));
+
+If assertions are enabled and the expression in the assertion is false than a
+trap will occur.
+
+Unreachable
+-----------
+
+If the logic of a program dictates that certain code cannot be reached, the
+``unreachable`` macro can be used e.g.::
+
+  switch (message) {
+  case 0:
+     ...
+  case 1:
+     ...
+  default:
+    unreachable("message must be 0 or 1");
+    break;
+  }
+
+If assertions are enabled then this macro will cause a trap if executed.
+
+Fail
+----
+
+A failure can be indicated with the ``fail`` macro e.g.::
+
+  if (reg_value != 0xA5)
+    fail("device not connected properly")
+
+A fail will always cause a trap if executed. A failure differs from
+unreachable in that an unreachable macro should never execute in a
+correct program whereas a fail could happen in catastrophic circumstances
+even if the program is correct.
+
+Controlling assertions
+----------------------
+
+Assertions can be enabled/disabled in ``debug_conf.h`` in your application with the following defines.
+
+XASSERT_ENABLE_ASSERTIONS
+  This define can be used to turn assertions on or off (defaults to 1).
+
+XASSERT_ENABLE_DEBUG
+  This define will cause assertions to print out the failing expression before
+  trapping (defaults to 0).
+
+XASSERT_ENABLE_LINE_NUMBERS
+  This define will cause assertions to print the file and line number of the
+  assertion before trapping.
+
+If ``DEBUG_UNIT`` is defined when ``xassert.h`` is included then all the
+assertions in that file belong to that unit. Assertions can then be
+controlled per debug unit. The mechanism is similar to that used in
+``module_logging``.
+
+XASSERT_ENABLE_ASSERTIONS_[debug unit]
+   Enable asserts for a particular debug unit. If set to 1,
+   this overrides the default set by ``XASSERT_ENABLE_ASSERTIONS`` for
+   that debug unit.
+
+XASSERT_ENABLE_DEBUG_[debug unit]
+   Enable debug messages for a particular debug unit.  If set to 1,
+   this overrides the default set by ``XASSERT_ENABLE_DEBUG`` for that
+   debug unit .
+
+XASSERT_DISABLE_ASSERTIONS_[debug unit]
+   Disable asserts for a particular debug unit. If set to 1,
+   this overrides the default set by ``XASSERT_ENABLE_ASSERTIONS`` for
+   that debug unit.
+
+XASSERT_DISABLE_DEBUG_[debug unit]
+   Disable debug messages for a particular debug unit.  If set to 1,
+   this overrides the default set by ``XASSERT_ENABLE_DEBUG`` for that
+   debug unit .
+
+
+ ****/
+
 #ifdef __xassert_conf_h_exists__
 #include "xassert_conf.h"
 #endif
@@ -40,7 +143,6 @@
 #  define XASSERT_ENABLE_ASSERTIONS0 XASSERT_ENABLE_ASSERTIONS
 #endif
 
-
 #if XASSERT_JOIN(XASSERT_ENABLE_DEBUG_,DEBUG_UNIT)
 #  define XASSERT_ENABLE_DEBUG0 1
 #endif

tests/app_xassert_test/Makefile

@@ -18,19 +18,19 @@ APP_NAME =
 # If the variable XCC_MAP_FLAGS is set it overrides the flags passed to 
 # xcc for the final link (mapping) stage.
 
-XCC_FLAGS_test_assert = -g -DTEST_ASSERT=1
-XCC_FLAGS_test_fail = -g -DTEST_FAIL=1
-XCC_FLAGS_test_unreachable = -g -DTEST_UNREACHABLE=1
-XCC_FLAGS_test_assert_disabled = -g -DTEST_ASSERT=1 -DXASSERT_ENABLE_ASSERTIONS=0
-XCC_FLAGS_test_fail_disabled = -g -DTEST_FAIL=1 -DXASSERT_ENABLE_ASSERTIONS=0
-XCC_FLAGS_test_unreachable_disabled = -g -DTEST_UNREACHABLE=1  -DXASSERT_ENABLE_ASSERTIONS=0
-XCC_FLAGS_test_assert_with_debug = -g -DTEST_ASSERT=1 -DXASSERT_ENABLE_DEBUG=1
-XCC_FLAGS_test_fail_with_debug = -g -DTEST_FAIL=1 -DXASSERT_ENABLE_DEBUG=1
-XCC_FLAGS_test_unreachable_with_debug = -g -DTEST_UNREACHABLE=1 -DXASSERT_ENABLE_DEBUG=1
-XCC_FLAGS_test_unitB_disabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_DISABLE_ASSERTIONS_UNITB=1
-XCC_FLAGS_test_unitA_disabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_DISABLE_ASSERTIONS_UNITA=1
-XCC_FLAGS_test_unitB_enabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_ENABLE_ASSERTIONS=0 -DXASSERT_ENABLE_ASSERTIONS_UNITB=1
-XCC_FLAGS_test_unitA_enabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_ENABLE_ASSERTIONS=0 -DXASSERT_ENABLE_ASSERTIONS_UNITA=1
+XCC_FLAGS_assert = -g -DTEST_ASSERT=1
+XCC_FLAGS_fail = -g -DTEST_FAIL=1
+XCC_FLAGS_unreachable = -g -DTEST_UNREACHABLE=1
+XCC_FLAGS_assert_disabled = -g -DTEST_ASSERT=1 -DXASSERT_ENABLE_ASSERTIONS=0
+XCC_FLAGS_fail_disabled = -g -DTEST_FAIL=1 -DXASSERT_ENABLE_ASSERTIONS=0
+XCC_FLAGS_unreachable_disabled = -g -DTEST_UNREACHABLE=1  -DXASSERT_ENABLE_ASSERTIONS=0
+XCC_FLAGS_assert_with_debug = -g -DTEST_ASSERT=1 -DXASSERT_ENABLE_DEBUG=1
+XCC_FLAGS_fail_with_debug = -g -DTEST_FAIL=1 -DXASSERT_ENABLE_DEBUG=1
+XCC_FLAGS_unreachable_with_debug = -g -DTEST_UNREACHABLE=1 -DXASSERT_ENABLE_DEBUG=1
+XCC_FLAGS_unitB_disabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_DISABLE_ASSERTIONS_UNITB=1
+XCC_FLAGS_unitA_disabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_DISABLE_ASSERTIONS_UNITA=1
+XCC_FLAGS_unitB_enabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_ENABLE_ASSERTIONS=0 -DXASSERT_ENABLE_ASSERTIONS_UNITB=1
+XCC_FLAGS_unitA_enabled = -g -DTEST_ASSERT=1 -DTEST_MULTI_UNIT -DXASSERT_ENABLE_ASSERTIONS=0 -DXASSERT_ENABLE_ASSERTIONS_UNITA=1
 
 XCC_FLAGS_unitA.xc = $(XCC_FLAGS) -DDEBUG_UNIT=UNITA
 XCC_FLAGS_unitB.c = $(XCC_FLAGS) -DDEBUG_UNIT=UNITB

tests/app_xassert_test/expected.output

@@ -1,5 +1,5 @@
 ----
-app_xassert_test_test_assert.xe:
+app_xassert_test_assert.xe:
 
 
 Program received signal ET_ECALL, Application exception.
@@ -8,15 +8,15 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_assert_disabled.xe:
+app_xassert_test_assert_disabled.xe:
 
 
 Program exited normally.
 
 ----
 
 ----
-app_xassert_test_test_assert_with_debug.xe:
+app_xassert_test_assert_with_debug.xe:
 
 1 > 2 && _msg("1 is bigger than 2 isn't it?")
 
@@ -26,7 +26,7 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_fail.xe:
+app_xassert_test_fail.xe:
 
 
 Program received signal ET_ECALL, Application exception.
@@ -35,7 +35,7 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_fail_disabled.xe:
+app_xassert_test_fail_disabled.xe:
 
 
 Program received signal ET_ECALL, Application exception.
@@ -44,7 +44,7 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_fail_with_debug.xe:
+app_xassert_test_fail_with_debug.xe:
 
 This is a failure in unitA
 
@@ -54,17 +54,17 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_unitA_disabled.xe:
+app_xassert_test_unitA_disabled.xe:
 
 
 Program received signal ET_ECALL, Application exception.
-    at /home/davel/github/sc_util/tests/app_xassert_test/.build_test_unitA_disabled/../src/unitB.c:7
+    at /home/davel/github/sc_util/tests/app_xassert_test/.build_unitA_disabled/../src/unitB.c:7
 7	  assert(1 > 2 && _msg("1 is bigger than 2 isn't it? (unitB)"));
 
 ----
 
 ----
-app_xassert_test_test_unitA_enabled.xe:
+app_xassert_test_unitA_enabled.xe:
 
 
 Program received signal ET_ECALL, Application exception.
@@ -73,7 +73,7 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_unitB_disabled.xe:
+app_xassert_test_unitB_disabled.xe:
 
 
 Program received signal ET_ECALL, Application exception.
@@ -82,17 +82,17 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_unitB_enabled.xe:
+app_xassert_test_unitB_enabled.xe:
 
 
 Program received signal ET_ECALL, Application exception.
-    at /home/davel/github/sc_util/tests/app_xassert_test/.build_test_unitB_enabled/../src/unitB.c:7
+    at /home/davel/github/sc_util/tests/app_xassert_test/.build_unitB_enabled/../src/unitB.c:7
 7	  assert(1 > 2 && _msg("1 is bigger than 2 isn't it? (unitB)"));
 
 ----
 
 ----
-app_xassert_test_test_unreachable.xe:
+app_xassert_test_unreachable.xe:
 
 
 Program received signal ET_ECALL, Application exception.
@@ -101,15 +101,15 @@ Program received signal ET_ECALL, Application exception.
 ----
 
 ----
-app_xassert_test_test_unreachable_disabled.xe:
+app_xassert_test_unreachable_disabled.xe:
 
 
 Program received signal SIGBUS, Bus error.
 
 ----
 
 ----
-app_xassert_test_test_unreachable_with_debug.xe:
+app_xassert_test_unreachable_with_debug.xe:
 
 This is unreachable in unitA
 

xpd.xml

@@ -24,6 +24,7 @@
     </components>
     <description>General Utilities Repository</description>
     <docdir>module_random/doc</docdir>
+    <docdir>module_xassert/doc</docdir>
     <exclude_dir>tests</exclude_dir>
     <location>[email protected]:xcore/sc_util</location>
     <name>sc_util</name>