let README generation grep asciidoc comments out coverage coverage_signature
authorChristian Thaeter <ct@pipapo.org>
Sat, 7 Aug 2010 08:14:05 +0000 (10:14 +0200)
committerChristian Thaeter <ct@pipapo.org>
Sat, 7 Aug 2010 08:14:05 +0000 (10:14 +0200)
also include updated README

Makefile.am
README

index 7075365..5f14f38 100644 (file)
@@ -119,7 +119,7 @@ doc: nobug_manual.html nobug_manual.pdf
 
 
 README: nobug_manual.txt
-       cp nobug_manual.txt $(top_srcdir)/README || true
+       grep -v '^//[^/]' < nobug_manual.txt > $(top_srcdir)/README || true
        git add $(top_srcdir)/README
 
 ChangeLog.new:
@@ -172,3 +172,8 @@ release:
        $(MAKE) dist
        $(MAKE) dist-sign
        @cd $(top_srcdir); rm .newline NEWS.new NEWS.old ChangeLog.new ChangeLog.bak;
+
+
+
+# TODO filter a nobug_lgpl out, take care for macros which can't be nop (inject goodbad must inject good)
+#( echo -e "#ifndef NOBUG_LGPL_H\n#define NOBUG_LGPL_H\n"; sed 's/^\(#define NOBUG_[^(]*([^)]*)\).*/\1/p;  s/^\(#define [^( ]* [^( ]*\).*/\1/p   ;d' ../src/nobug.h; echo "#endif"; )
diff --git a/README b/README
index 37956aa..56e4906 100644 (file)
--- a/README
+++ b/README
@@ -2,7 +2,6 @@ NoBug
 =====
 Christian_Th├Ąter,_Benny_Lyons
 
-// doc/overview.txt:1 //
 ____
 Everyone makes mistakes, but with NoBug you won't make them twice!
 ____
@@ -43,7 +42,6 @@ part of the program itself it is affected by memory corruption,
 certain kinds of misuse may introduce new bugs (test expressions with
 side effects for example).
 
-// doc/buildinstall.txt:1 //
 Building and Installing
 -----------------------
 
@@ -67,9 +65,11 @@ x86     OpenSolaris     mostly          Builds, but target check fails
         *BSD            planned         Need volunteer for testing
 -------------------------------------------------------------------------------
 
-NoBug has no mandatory dependencies on other software and libraries,
+NoBug has few mandatory dependencies on other software and libraries,
 some things such as valgrind support are optional and should be automatially
-detected during the build, i.e., when ./configure is called.
+detected during the build, i.e., when ./configure is called. Nevertheless it
+requires 'pkg-config' to be installed, you get some weird errors already at
+bootstrapping (autoreconf) when this is not available.
 
 
 Release Tarballs
@@ -159,8 +159,9 @@ following does what you may expect:
 building the documentation has quite some more dependencies than building
 NoBug itself. Unless you are a packager you may want to refer to the online
 doc or the shipped 'README' which is actually this full nobug manual.
+Generating the documentation requires: gawk, asciidoc, graphviz and some
+toolchains to further process docbook (dblatex, ...).
 
-// doc/using.txt:1 //
 Using NoBug
 -----------
 
@@ -283,7 +284,6 @@ PKG_CHECK_MODULES(NOBUGMT_LUMIERA, [nobugmt >= 0.3rc1],
 )
 ----------------
 
-// doc/additional.txt:1 //
 Checking for Additional Tools
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -325,7 +325,6 @@ provides the associated `HAVE_*` macros, but can then be overridden by the user,
 depending on the user's requirements.
 
 
-// doc/whichlibrary.txt:1 //
 Link Appropriate Library
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -350,7 +349,6 @@ and will not provide good bug reports anyway. If there is a problem in
 a release build, try to track down the cause using a beta build from
 the same source.
 
-// doc/initialization.txt:1 //
 Initialization
 --------------
 
@@ -430,7 +428,6 @@ int main()
 }
 -------------------------------------------------------
 
-// doc/buildlevels.txt:1 //
 [[buildlevel]]
 Debugging Information Granuality: The Build Levels
 --------------------------------------------------
@@ -464,7 +461,6 @@ to the compiler:
 If none of the above switches has been set, NoBug will abort the
 compilation with an error.
 
-// doc/logging.txt:1 //
 Logging
 -------
 
@@ -507,7 +503,6 @@ Putting this all together: A user can define which source/flag will be logged at
 what priority level and to which destination. To make this all easier, NoBug
 tries to provide reasonable defaults.
 
-// doc/logconfiguration.txt:1 //
 [[logconfig]]
 Configuration
 ~~~~~~~~~~~~~
@@ -554,7 +549,6 @@ You can override all these values with your own values. As an alternative,
 `NOBUG_LOG_LIMIT` and `NOBUG_LOG_TARGET` can be defined before
 including "nobug.h" to override all defaults.
 
-// doc/logflags.txt:1 //
 [[logflags]]
 Log Flags
 ~~~~~~~~~
@@ -674,7 +668,6 @@ as in the xref:logdefaults[table above], while
 `NOBUG_DEFINE_FLAG_LIMIT(flagname, level)` is used to initialize the
 default target (depending on build level) to `level`.
 
-// doc/logflagsenv.txt:1 //
 [[NOBUG_ENV]]
 Control what gets logged
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -778,7 +771,6 @@ $ NOBUG_LOG=test:TRACE ./a.out
 0000000002: TRACE: example.c:11: main: Always on
 ----
 
-// src/nobug.c:38 //
 Predefined Flags
 ~~~~~~~~~~~~~~~~
 
@@ -805,7 +797,6 @@ Actions on NoBug itself will be logged under the `nobug` flag itself.
 When you want to see whats going on (useful to check if you call
 `NOBUG_INIT_FLAG()` on all flags) you can enable it with `NOBUG_LOG=nobug:TRACE`.
 
-// doc/macros.txt:1 //
 Macros
 ------
 
@@ -850,7 +841,6 @@ form then the suffix of the macros is always `..._IF_CTX`.
 The macros which take a context have no short form and must always be
 prefixed with `NOBUG_...`.
 
-// doc/parametertable.txt:1 //
 Parameters types
 ~~~~~~~~~~~~~~~~
 
@@ -870,7 +860,6 @@ orthogonal through all macro definitions.
 `...`     printf-like format string followed by its arguments
 ---------------------------------------------------------------------------
 
-// src/nobug.h:632 //
 [[NOBUG_CONTEXT]]
 Source Contexts
 ~~~~~~~~~~~~~~~
@@ -883,7 +872,6 @@ NoBug passes information about the source location of a given statement in
 function name and must be used when the function context is not available
 like in static initialization etc..
 
-// src/nobug.h:104 //
 Assertions
 ----------
 
@@ -957,7 +945,6 @@ otherwise optimized out.
 
  TODO: describe how to create invariant checks
 
-// src/nobug.h:366 //
 Logging Macros
 --------------
 
@@ -1063,7 +1050,6 @@ builds to log the application progress only coarsely then.
 This macros can be defined before including 'nobug.h' to some other
 log level (as defined in 'syslog.h').
 
-// doc/dumping.txt:1 //
 [[dumping]]
 Dumping Datastructures
 ----------------------
@@ -1076,7 +1062,23 @@ datastructure to be dumped which may recursively call other dumping
 functions. There are macros for logging within such a dumper function
 and for initiating a dump of a given datastructure.
 
-// src/nobug.h:308 //
+A dump function has the prototype:
+
+[source,c]
+-------------------------------------------------------
+void
+nobug_NAME_dump (const struct NAME* POINTER,
+                 const int DEPTH,
+                 const struct nobug_context CONTEXT,
+                 void* EXTRA);
+-------------------------------------------------------
+
+where NAME is the identifier for what you want to dump, POINTER is a pointer
+to the data to be dumped, DEPTH is a integer which will be decremented when
+recursing into the datastructure dumper (your dump function does that, see
+below) to limit the recursion depth, CONTEXT is a source context generated by
+nobug when you call DUMP() and EXTRA is a pointer transparently passed around
+you can use to store some extra state.
 [[DUMP]]
 .DUMP
  DUMP(flag, type, pointer, depth, extra)
@@ -1086,7 +1088,8 @@ This macros call a datastructure dump of the object (`pointer`) in question.
 `DUMP` is only available in *ALPHA* and *BETA* builds, `DUMP_IF` is also
 enabled for the RELEASE builds.
 
-`extra` is a void* which is transparently passed around
+`extra` is a void* which is transparently passed around and can be used to
+pass some state around. NoBug does not touch it.
 
 [[DUMP_LOG]]
 .DUMP_LOG
@@ -1098,7 +1101,6 @@ Any output from `DUMP` handlers should be done by these macros.
 Dumping is by default done on level `LOG_DEBUG`, this can be overridden by
 defining `NOBUG_DUMP_LEVEL` to some other level.
 
-// doc/dumpexample.txt:1 //
 .How to use the DUMP facilities
 
 [source,c]
@@ -1118,20 +1120,24 @@ then you define a function like:
 void
 nobug_STRUCTNAME_dump (const struct STRUCTNAME* self,
                        const int depth,
-                       const char* file,
-                       const int line,
-                       const char* func)
+                       const struct nobug_context context,
+                       void* extra)
 {
   // check for self != NULL and that the depth
   // limit did not exceed in recursive datastructures
   if (self && depth)
   {
+    // you may or may not do something with the extra parameter here
+    // extra is transparently passed around
+    (void) extra;
+
     // use DUMP_LOG not LOG to print the data
     DUMP_LOG("STRUCTNAME %p: int is %d, string is %s", self,
                              self->INTEGER_MEMBER,
                              self->STRING_MEMBER);
+
     // now recurse with decremented depth
-    nobug_STRUCTNAME_dump (self->next, depth-1, file, line, func);
+    nobug_STRUCTNAME_dump (self->next, depth-1, context, extra);
   }
 }
 -------------------------------------------------------
@@ -1144,11 +1150,12 @@ example()
 {
   struct STRUCTNAME foo;
   init(&foo);
-  DUMP (my_flag, STRUCTNAME, &foo, 2);
+
+  // extra can be anything, NULL is suggested when you don't use it
+  DUMP (my_flag, STRUCTNAME, &foo, 2, NULL);
 }
 -------------------------------------------------------
 
-// src/nobug.h:652 //
 Source Annotations
 ------------------
 
@@ -1196,7 +1203,6 @@ used to tag code-path which shall be never executed.
 
 same as `else NOTREACHED()`, but wholly optimized out in release builds.
 
-// doc/annotationtable.txt:1 //
 
 The advantage of this tagging over plain source comments is that we can take
 some actions if we run in such a tag at compile or runtime:
@@ -1223,7 +1229,6 @@ Legend:
   * nothing optimized out, sane way
   * removed optimized out for performance reasons
 
-// doc/scopechecks.txt:1 //
 [[CHECKED]]
 Scope Checks
 ------------
@@ -1233,7 +1238,6 @@ The programmer can tag any scope as `UNCHECKED` or `CHECKED`. In *ALPHA* and *BE
 builds, a global `UNCHECKED` is implied. In *RELEASE* builds, `UNCHECKED` scopes are
 not allowed.
 
-// doc/assertiontable.txt:1 //
 .Assertions active depending on Build level and Scope
 [grid="all"]
 `-----------`-----------------------------------------`-----------------------------`-------------------
@@ -1242,7 +1246,6 @@ not allowed.
 *CHECKED*   Preconditions, Postconditions             Preconditions
 ------------------------------------------------------------------------------------------------------
 
-// src/nobug.h:779 //
 Fault injection
 ---------------
 
@@ -1268,7 +1271,88 @@ In both cases, when a fault is injected it will be logged at
 `NOBUG_INJECT_LEVEL` (default: `LOG_NOTICE`). This can be defined
 before including 'nobug.h' to override it.
 
-// doc/resourcetracking.txt:1 //
+Fault coverage checking
+-----------------------
+
+CAUTION: Fault coverage checking is a experimental feature!
+
+Nobug can automatically inject faults at instrumented points and permute
+through all potential error paths of an application by restarting it with the
+state from the former run. It can be used to give answers to the question if
+any possible error is sufficiently handled in the application. Fault coverage
+checking is only available in ALPHA builds and optimized out otherwise.
+
+NOTE: This kind of testing is very expensive.
+
+How does automatic fault injection work
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+First NoBug checks if the environment variable `NOBUG_COVERAGE` is set, if yes
+it must contain a space, comma or semicolon separated list of filename which
+are the logs from the previous run. This logs are then parsed for the states
+of the previous run, storing these in a lookup tree.
+
+After that the application proceeds as usual, when it then hits an
+instrumented coverage point it is checked against the already recorded states.
+Any so far unseen failure point injects a fault, the last seen but previously
+failed point will be pass now, all other fault injection points act like on
+their previous run. This ensures that each successive run of the application
+changes only one injection point and thus permutes through all possible code
+paths.
+
+Fault injection points are identified by a 64bit hash over the backtrace
+(return addresses on the stack) leading to it. This means each unique way to
+reach a injection point is recorded. Parameters and threads are intentionally
+not considered in this calculation.
+
+
+How to invoke fault-coverage checking
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Each fault-injection point emits a logging message about its identity and
+state, this logging uses the normal NoBug logging facilities. Thus one can
+control the logging with the `NOBUG_LOG` environment variable. Additionally
+fault coverage checking is only active when the `NOBUG_COVERAGE` environment
+variable was set to point some log files which are the results from the
+previous run. NoBug comes with a `tests/coverage.sh` example script which
+permutes through all possible error paths.
+
+Coverage checking Macros
+------------------------
+
+[[COVERAGE_FAULT]]
+.COVERAGE_FAULT
+ COVERAGE_FAULT(flag, ...)
+
+Injects the statement at `...` when simulating an failure. Only active in
+ALPHA builds.
+
+[[COVERAGE_GOODBAD]]
+.COVERAGE_GOODBAD
+ COVERAGE_GOODBAD(flag, good, bad)
+
+Substitutes to an expression and injects `bad` when simulating an failure and `good`
+otherwise. Only active in ALPHA builds.
+
+[[COVERAGE_LEVEL]]
+.COVERAGE_LEVEL
+ #define NOBUG_COVERAGE_LEVEL ...
+
+Logging level at what fault-coverage logging is emitted.
+
+NOTE: Supressing log output with this level will not supress fault injection,
+      actually the opposite is true since every new seen failure path gets injected.
+      This might be changed in future releases.
+
+[[COVERAGE_DISABLE]]
+.Disabling and enabling fault-coverage checks
+ NOBUG_COVERAGE_DISABLE
+ NOBUG_COVERAGE_ENABLE
+
+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 and must properly match.
+
 Resource Tracking
 -----------------
 
@@ -1352,7 +1436,6 @@ The Resource Tracker relies on proper announce/forget and enter/leave
 are properly pairing. The programmer should ensure that this is done
 right, otherwise the results are unpredictable.
 
-// src/nobug.h:996 //
 Resource tracking macros
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
@@ -1438,6 +1521,36 @@ error is raised.
 (block-) statement. Leaving and the user defined following statement are atomic.
 This statement must not be left by break, return or any other kind of jump.
 
+[[RESOURCE_RESETALL]]
+.RESOURCE_RESETALL
+ RESOURCE_RESETALL(flag)
+ NOBUG_RESOURCE_RESETALL_RAW(flagptr)
+ NOBUG_RESOURCE_RESETALL_RAW_CTX(flagptr, context)
+
+Sometimes the resource tracker can give false positives when it finds a locking order violation
+while the programmer knows that this will never happen in the real program, because for example
+this is only used at initialization or shutdown and never overlaps. This macro can then be used
+to reset all whats learnt about all resources and start over.
+
+`flag`::
+    the NoBug flag which turns logging on for this macro
+
+[[RESOURCE_RESET]]
+.RESOURCE_RESET
+ RESOURCE_RESET(flag, handle)
+ NOBUG_RESOURCE_RESETALL_RAW(flagptr, handle)
+ NOBUG_RESOURCE_RESETALL_RAW_CTX(flagptr, handle, context)
+
+Sometimes the resource tracker can give false positives when it finds a locking order violation
+while the programmer knows that this will never happen in the real program, because for example
+this is only used at initialization or shutdown and never overlaps. This macro can then be used
+to reset all whats learnt about a single resources and start over.
+
+`flag`::
+    the NoBug flag which turns logging on for this macro
+`handle`::
+    the `NOBUG_RESOURCE_HANDLE` used to track this resource
+
 [[RESOURCE_ENTER]]
 .RESOURCE_ENTER
  RESOURCE_ENTER(flag, announced, user, state, handle)
@@ -1591,7 +1704,6 @@ List all registered resources.
 `flag`::
     Nobug flag for the log channel
 
-// doc/resourceexample.txt:1 //
 .How to use the Resourcetracker
 [source,c]
 ----
@@ -1633,7 +1745,6 @@ void example()
 }
 ----
 
-// doc/resourcedeadlock.txt:1 //
 Deadlock Detection
 ~~~~~~~~~~~~~~~~~~
 
@@ -1646,7 +1757,6 @@ and active in ALPHA builds and optimized out on any other build level.
 For details about the deadlock detection algorithm see
 xref:deadlock_detection[Appendix: Resource Tracking Alorithm].
 
-// src/nobug.h:2354 //
 Callbacks
 ---------
 
@@ -1728,7 +1838,6 @@ IMPORTANT: Errors detected by NoBug are always fatal. If one handles and possibl
            throws an exception here, the application must shut down as soon as possible.
            Most causes for aborts are optimitzed out in `RELEASE` builds.
 
-// src/nobug.h:1583 //
 Tool Macros
 -----------
 
@@ -1792,7 +1901,6 @@ This macros allow one to conditionally include the code in '(...)' only if the
 criteria on the build level is met. If not, nothing gets substituted. Mostly used
 internally, but can also be used for custom things.
 
-// doc/multithreading.txt:1 //
 [[multithreading]]
 Multithreading
 --------------
@@ -1840,7 +1948,6 @@ single global variable.
 
 Nobug initializes this variable to `NULL` and then touches it never again.
 
-// src/nobug_rbdump.c:33 //
 [[rbdump]]
 Dumping Persistent Ringbuffers
 ------------------------------
@@ -1849,7 +1956,6 @@ NoBug installs the `nobug_rbdump` tool for dumping the content of a persistent
 ringbuffer. It is invoked with the filename of the ringbuffer, the content is then
 printed to stdout.
 
-// doc/testsuite.txt:1 //
 Testsuite
 ---------
 
@@ -1858,7 +1964,6 @@ Testsuite
 NoBug maintains a `test.sh` script which drives extensive testsuites.
 Look at into the 'tests/' folder about how to apply this.
 
-// doc/bestpractices.txt:1 //
 Best Practices
 --------------
 
@@ -1898,7 +2003,6 @@ NOTE: this section is very work in progress
 Appendix
 --------
 
-// src/nobug_resources.c:333 //
 [[deadlock_detection]]
 The Resource Tracking Algorithm
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -2102,7 +2206,6 @@ create new nodes.
                                   res_stack);
 
 ---------------------------------------------------------------------
-// src/nobug_resources.c:694 //
 
 find the node pointing back to parent, create a new one if not found, rinse repeat
 
@@ -2152,6 +2255,10 @@ xref:buildlevel[Build Levels]:: selecting the build level
 xref:callback_data[passing data to callbacks]:: data to be passed to callbacks
 xref:CHECK[CHECK]:: unnconditional assertion for testsuites
 xref:CHECKED[CHECKED, Scope]:: tag scope as reviewed
+xref:COVERAGE_DISABLE[Disabling and enabling fault-coverage checks]:: handle false positives
+xref:COVERAGE_FAULT[COVERAGE_FAULT]:: coverage fault injection, statement
+xref:COVERAGE_GOODBAD[COVERAGE_GOODBAD]:: coverage fault injection, expression
+xref:COVERAGE_LEVEL[COVERAGE_LEVEL]:: coverage fault injection log level
 xref:Cplusplus_logflags[C++ support, C++ logflags]:: C++ support for log flags
 xref:CRITICAL[CRITICAL]:: can not continue
 xref:deadlock_detection[The Resource Tracking Algorithm]:: how resources are tracked
@@ -2207,6 +2314,8 @@ xref:RESOURCE_LEAVE[RESOURCE_LEAVE]:: relinquish a claimed resource
 xref:RESOURCE_LIST[RESOURCE_LIST]:: enumerate all registered resources
 xref:RESOURCE_LOG_LEVEL[RESOURCE_LOG_LEVEL]:: select the log level for resource logging
 xref:RESOURCE_LOGGING[RESOURCE_LOGGING]:: switch resource logging on and off
+xref:RESOURCE_RESET[RESOURCE_RESET]:: reset a single resource to a pristine state
+xref:RESOURCE_RESETALL[RESOURCE_RESETALL]:: reset the resource tracker to a pristine state
 xref:RESOURCE_STATE[RESOURCE_STATE]:: change the state of a resource
 xref:RESOURCE_TRY[RESOURCE_TRY]:: wait for a resource to become available
 xref:RESOURCE_WAIT[RESOURCE_WAIT]:: wait for a resource to become available
@@ -2219,7 +2328,6 @@ xref:UNCHECKED[UNCHECKED, Scope]:: tag scope as unreviewed
 xref:UNIMPLEMENTED[UNIMPLEMENTED]:: not yet implemented
 xref:WARN[WARN]:: unexpected fixable error
 
-// doc/license.txt:1 //
 License
 -------