document the fault-coverage checker
[nobug] / src / nobug.h
index 7edf816..fb1a257 100644 (file)
@@ -873,24 +873,20 @@ NOTREACHED      abort           abort           nothing
 #define NOBUG_INJECT_LEVEL LOG_NOTICE
 #endif
 
-/*
-  temporary disabling/enabling
-
-  sometimes fault injection yields false positives, errors which may never happen in real life
-  (and are possibly enforced with a ENSURE afterwards). For this cases coverage fault injection can be
-  disabled temporarly and reenabled later. disabling/enabling may nest.
- */
 
-#define NOBUG_COVERAGE_DISABLE                                  \
-  NOBUG_IF_ALPHA(unsigned nobug_coverage_disable_check =        \
-                 nobug_thread_get ()->coverage_disable_cnt;)    \
-  NOBUG_IF_ALPHA(++ nobug_thread_get ()->coverage_disable_cnt)
-
-#define NOBUG_COVERAGE_ENABLE                                   \
-  NOBUG_IF_ALPHA(-- nobug_thread_get ()->coverage_disable_cnt); \
-  ENSURE(nobug_coverage_disable_check ==                        \
-         nobug_thread_get ()->coverage_disable_cnt,             \
-         "COVERAGE ENABLE/DISABLE does not match")
+/*
+//coverage HEAD- Coverage checking Macros;;
+//coverage
+//coverage PARA COVERAGE_FAULT; COVERAGE_FAULT; coverage fault injection, statement
+//coverage  COVERAGE_FAULT(flag, ...)
+//coverage
+//coverage Injects the statement at `...` when simulating an failure. Only active in
+//coverage ALPHA builds.
+//coverage
+*/
+#define NOBUG_COVERAGE_FAULT(flag, ...)                                 \
+  NOBUG_IF_ALPHA(NOBUG_COVERAGE_FAULT_(flag, __VA_ARGS__))              \
+  NOBUG_IF_NOT_ALPHA(__VA_ARGS__)
 
 
 #define NOBUG_COVERAGE_FAULT_(flag, ...)                                \
@@ -910,10 +906,18 @@ NOTREACHED      abort           abort           nothing
   } while (0)
 
 
-#define NOBUG_COVERAGE_FAULT(flag, ...)                                 \
-  NOBUG_IF_ALPHA(NOBUG_COVERAGE_FAULT_(flag, __VA_ARGS__))              \
-  NOBUG_IF_NOT_ALPHA(__VA_ARGS__)
 
+/*
+//coverage PARA COVERAGE_GOODBAD; COVERAGE_GOODBAD; coverage fault injection, expression
+//coverage  COVERAGE_GOODBAD(flag, good, bad)
+//coverage
+//coverage Substitutes to an expression and injects `bad` when simulating an failure and `good`
+//coverage otherwise. Only active in ALPHA builds.
+//coverage
+*/
+#define NOBUG_COVERAGE_GOODBAD(flag, good, bad)                         \
+  NOBUG_IF_ALPHA(NOBUG_COVERAGE_GOODBAD_(flag, good, bad))              \
+  NOBUG_IF_NOT_ALPHA((good))
 
 #define NOBUG_COVERAGE_GOODBAD_(flag, good, bad)                        \
   ({                                                                    \
@@ -928,9 +932,6 @@ NOTREACHED      abort           abort           nothing
   })
 
 
-#define NOBUG_COVERAGE_GOODBAD(flag, good, bad)                         \
-  NOBUG_IF_ALPHA(NOBUG_COVERAGE_GOODBAD_(flag, good, bad))              \
-  NOBUG_IF_NOT_ALPHA((good))
 
 
 #define NOBUG_COVERAGE_LOG(flag, record)                \
@@ -940,12 +941,49 @@ NOTREACHED      abort           abort           nothing
               record.hash,                              \
               record.state == 'F'?"FAILURE":"PASS")
 
+
+/*
+//coverage PARA COVERAGE_LEVEL; COVERAGE_LEVEL; coverage fault injection log level
+//coverage  #define NOBUG_COVERAGE_LEVEL ...
+//coverage
+//coverage Logging level at what fault-coverage logging is emitted.
+//coverage
+//coverage NOTE: Supressing log output with this level will not supress fault injection,
+//coverage       actually the opposite is true since every new seen failure path gets injected.
+//coverage       This might be changed in future releases.
+//coverage
+// TODO see above, disable fault injection when not logged
+//       if (NOBUG_EXPECT_FALSE(NOBUG_COVERAGE_LEVEL <= flag->limits[NOBUG_TARGET_???]))
+*/
+
 #ifndef NOBUG_COVERAGE_LEVEL
 #define NOBUG_COVERAGE_LEVEL LOG_NOTICE
 #endif
 
 
 
+/*
+//coverage PARA Disabling and enabling fault-coverage checks; COVERAGE_DISABLE; handle false positives
+//coverage  NOBUG_COVERAGE_DISABLE
+//coverage  NOBUG_COVERAGE_ENABLE
+//coverage
+//coverage Sometimes fault injection yields false positives, errors which may never happen in real life
+//coverage (and are possibly enforced with a ENSURE afterwards). For this cases coverage fault injection can be
+//coverage disabled temporarly and reenabled later. Disabling/enabling may nest and must properly match.
+//coverage
+*/
+
+#define NOBUG_COVERAGE_DISABLE                                  \
+  NOBUG_IF_ALPHA(unsigned nobug_coverage_disable_check =        \
+                 nobug_thread_get ()->coverage_disable_cnt;)    \
+  NOBUG_IF_ALPHA(++ nobug_thread_get ()->coverage_disable_cnt)
+
+#define NOBUG_COVERAGE_ENABLE                                   \
+  NOBUG_IF_ALPHA(-- nobug_thread_get ()->coverage_disable_cnt); \
+  ENSURE(nobug_coverage_disable_check ==                        \
+         nobug_thread_get ()->coverage_disable_cnt,             \
+         "COVERAGE ENABLE/DISABLE does not match")
+
 
 /*
   Flag handling
@@ -2696,7 +2734,10 @@ nobug_section_cleaned (int* self)
 }
 
 
-//faultcoverage
+/*
+  fault coverage checking
+*/
+
 struct nobug_coverage_record
 {
   uint64_t hash;