GCDebRTrc Files

 D C g c R T r c
=================

### content
+ overview
+ release-notes
+ features
+ work flow
+/+



### overview

--- DCgcRTrc ---				A debug-feature for near-Real-Time traces in RAM


Debug-Conditional (global-C-code) RAM Trace.

What could it be used for?
It's only - sorry - a framework to save a value in an array and afterwards the 
array-index is incremented.
This could be printed out.
In newer versions of DCgcDebRTrc you also could insert small strings in this 
array.
-
You could insert values -for-debug- in different places in your source-code 
e.g. IDs to identify the place in code and more. Of course you could use 
also Line-Number for this (has to be enabled before compilation -> 
automatic insertion for every Trace-Macro call).
- 
The aim is to get one or more values in one trace-function and this will be 
printed out with the print function in the same order, chronologically.
Additionally you could insert a Line-Number and/or a Time-Stamp for each 
insert-in-array Macro call. (fix via define)
-
Also it should not use much runtime to do this. Hence at 1st i try to avoid 
mutexes; you must decide for yourself if it is ok. But in worst case you must 
use a mutex for this feature (already prepared in h-file), although this may 
alter your runtime behaviour a little.

The main code is in programming language  C  ! 
(Folders inc/ & src/, synonym for C feature: DCgcRTrc)
NO  "Additional Support" for further programming languages;
should work in CPP either.


One of the beginner versions, not all features yet available.

For  function-overview  see readme-section in  "gcdebrtrc.c".

For inhere given C-tests the sub-folders inc/, src/ and test/ are valid, 
"make maintest" for instance and 
run tests with "./maintest <test-number>".  (In folder ..GCDebRtrc/code/ o.c.) 
An additional argument  [help]  behind the test-number may gave information, 
currently in german only (may someone want to translate..?). 
test-~number~ 't' for temporary tests  -- NYI.
make maintestXYZ    -> make a variant of maintest, XYZ -> see makefile (C)


Folder test/ do not contain files which are necessary to use gcdebrtrc 
feature in your own code.

First OS: Linux (pthread_mutex). In single-thread environment it should 
work always.



Basics - used libraries for DCgcRTrc (usual standard, std):
- stdlib.h                      {exit..}
- stdarg.h                      {var-arg-list..}
- pthread.h  -opt-nonstd-       {just for DCgcRTRC_LOCKTYPE==1 <-> POSIX}
- uwsutil.h  -nonstd-           {own unsigned 32b integer and little more}
- windows.h  -nonstd-           {win std for timing function}
- stdint.h   -opt-              {sub of uwsutil.h, if CC is new enough, else adapt uwsutil.h}
- intsafe.h  -nonstd-           {win std for types..}
- BaseTsd.h  -nonstd-           {win std for types..}
--- only-for-C-file
- stdio.h                       {printf..}
- string.h                      {memset..}
( stdlib.h )
- Winbase.h  -nonstd-           {win std}
- unistd.h   -GNUC-             {sleep..}
- limits.h    
- time.h     -GNUC- o -std-     {at least std for 1s precision of timestamp, GNUC upto 1ns}
- math.h     -opt-              
-/-
Hint: further libs for DCgcFSTrc used.


Additional Support:

* 	C++      <=> NYI (usage should work without changes, no CPP calls, no Objs)

*   java     <=> NYI

*/*

-------------------------------------------------------------------------------







### release-notes

* 0.0.1   
    C: start with C-code; could be used in CPP code too (afait).

* 0.0.2   
    C: include test02.c for straight feature test and 
       small opt. integral test. 
    C: include timestamping for OS linux {POSIX} and win
    C: Integrate automatic printBuf at exit, conditionally 
       after registering (or always).
    C: some _WIN32 win-OS support for timestamps (1us), no locks yet
       (ONLY for command-line applications of win <-> printBuf fn).
       Also support base RTrc types for _WIN32.
    C: initialization function resets the timestamp to 0; various time-units 
       available and time-unit 1us for timestamp results im max. 
       approx. 1h time before overrun timestamp-counter.

* 0.0.3         - just more info -
    I:  create this file - directly readable in source-forge (uws.rmt obsolete)
    C:  rename own fix-type typedefs (UINT1 -> UINT_1...)
    A:  insert new macro for easy use of a fix short-string 
        (string-literal in C, use without length in macro
        DCgcRTRC_TRACE_IDaU4aU4aCSS())
    C:  rename of initialization function

* 0.1.0         - add FSTrc -
    I:  test-scripts for automatic testing (autotest-C.sh, 
        multivaricall.sh, all-autotest.sh, option "--getconfig",..)
        Restriction: These test now belongs on existant of Lnkdlst feature 
        to use thread for maintest #3.
        Additionally support fast pass through the tests via cmd-line 
        argument/option "fast" (e.g. >maintest 2 fast<)
    I:  gcdebfstrc.c/.h - FSTrc: support saving of current RAM-trace buffer 
        into a file (binary) and support of a function (and opt. a small 
        cmd-line program) to convert these binary-files into a csv formatted 
        file.
    A:  support of a smaller base trace-element size (usual/default: 4byte,
        supported if specific config def is set: 2byte - this is not supported 
        by FSTrc yet). This is for smaller systems or for a bigger trace 
        "space" (doubled space in RTrc buffer). ((DCgcRTRC_TRACE_EL_SIZE))
        Hint: timestamp will be, if not otherwise set, 4byte. ShortStr 
        feature is not available for 2byte trace-element size. "u4" prefix 
        is not changed for variable (..) names, although is does not mean yet 
        in any config-case that this belongs to a 4byte variable/type/..
    A:  Timestamp size of 2 byte (belonging to the previous config support 
        you can choose a smaller timestamp too, if timestamp is needed 
        {timestamping is not the default}). ((DCgcRTRC_TIMESTAMP = 2))
    I:  add a new feature "trace-buffer reset blocking" for FSTrc, but could be 
        used also in own programs too. avoid inconstent buffer states or 
        invalid readings of the buffer.
        ((DCgcRTRC_RESET_BLOCKING_EN != 0))
    C:  The specific pseudo lock (detect race-condition only) gets a pseudo
        LOCKTYPE ID 0xFEDC
    I:  support of a buffer trace obj reader (base for FSTrc because config 
        settings has to be supported dynamically via infos in file header).
        (( DCgcRTrc_getNextElFromBuf() ..))
    C:  use traceam.h externally from Lnkdlst - it should be possible to use 
        the old traceam.h, located in the code/test/ folder.
    A:  make: integrate CC-switch as var. input for make-file (1:1); base 
        for auto-tests (e.g. > DCgcRTRC_TIMESTAMP=2 make maintest <).
    I:  add test03, a test-feature for FSTrc
    !!: Lnkdlst in parallel needed for tests; could be changed to integrate 
        the Lnkdlst files into the code/test/ folder and change pathes in 
        makefile.
    I:  make: add target 'fstrc1' (integrated small DCgcFSTrc test) and 
        'fstrc_convert', the simple converter tool 
        bin-files -> csv-file (now only stdout used).
    A:  make: add target 'rtrc1' (integrated small DCgcRTrc test with options) 
    A:  make: add an OS-select sub-make file ((makeosdefs.mi))
    

-------------------------------------------------------------------------------







### features

Yet integrated features in DCgcRTrc (gcdebrtc-files,
Trace means here: RAM-Trace):

+   general mutex support (POSIX), could be disable or changed; enhanceable 
    via _LOCKTYPE number (0=no locks, 1=pthread_mutex)

+   optional (CC-switch) serving a timestamp for every Trace-Macro call
    (format choosable in CC-time, CC-switch defs "DCGCRTRC_TIMESTAMP_*")

+   optional (CC-switch) including a linenumber belonging to every Trace-Macro 
    call (if you can identify the file by ID this will show 100% the place 
    of the macro in code)

+   support auto-printing of the Trace-Buffer if program is exited
    (using std. atexit() function; always or after switching it on)
    (optional via CC-switch)

+   free configurable Trace-Buffer size (CC-define).
    Attention:  RAM-Trace is available only in one instance per program and
                if RAM-trace-buffer is full, the program could not trace 
                furthermore.

+   linear Buffer, dimension only for a one-shot; not circular yet!
    Trace-Buffer willB full if only putting smth. in via Trace-Macros!
    To avoid this you could make a Reset of the Buffer from time-to-time 
    and pre-print contents.
    TODO : print-contents and clear after-wards feature to do not have 
    leaks in buffer-prints; background buffer-printing with low prio threads;
    circular buffering for permanent tracing without printing but overwriting 
    last entries if max.size is reached.
    
+   Some actions choosable if Trace-Buffer is full (CC-set):
    - print Buffer-Full info
    - print Trace-Buffer
    - exit program
    -/-

+   Various buffer-access control mechs:
    - none  (for single threading only)
    - detection  (for use without system locks but without full fn guarantee)
    - direct lock (blocks another process completely)
    - lock-by-var
    -/-

+   Includes own DC abort fn. (macro DCgcRTRC_ABif())

+   Various Trace Macros, yet supporting base type UINT32 only:
    - with ID only  (upto 24bit)
    - with ID and one 32bit value
    - with ID and two 32bit values
    - with ID and two 32bit values and a short-string (till 15 chars, although 
      not very good for real-time)
    -/-

+   Trace-Buffer reset Macro. Clears buffer completely in a very short time 
    (now: just reset index, V0.0.2)

+   Option to use an own print-function; default is print-to-stdout.
    Attention: must be at least like printf() in prototype.
    (use DCgcRTRC_tfnOwnPrintf here)
    Hint: If print-function is called, real-time is broken, of course.

+   Enable Trace-Buffer print at program exit.

+   Enable Trace-Buffer print at Trace-Buffer full.

+   (Support of an own 32bit Time-Stamp function, unit variable - CC-time)

+   FileSystem Trace add-on to save the current RAM-trace continously

+ / + 

-------------------------------------------------------------------------------







### work flow

* step-1
Setup your "CC-switches" in the header file, e.g. if you do not wish to 
print the buffer on program-exit set >>
#define DCgcRTRC_USE_ATEXIT_PRINT (0)
<<.
-
Insert a fn call of fn "DCgcRTrc_initialize()" for a one-time initialization.
(Although this is only necessary yet/V0.0.2 if you have time stamps enabled
or if you want to enable printBuf at exit always). But to be sure it should 
be done always.

* step-2
Insert DCgcRTRC_TRACE_ID*() macros in your code, were you want to know 
how it is running through.
E.g. to show the function calling flow from the fns of one C- or 
CPP-module/file.

* step-3
Call the print-buffer function when you will show a result of the tracing.
Use function DCgcRTrc_printBuf().
You could call this as often as you want, may be controlled via your 
own user-interface.
-
Also you could reset the Trace-Buffer, if you want to start tracing again 
without checking the current trace (if not already printed; here is an 
open issue (V0.02): after printing some insertion could be done by the 
program before the Reset-TraceBuffer is done; this must be done in the 
print-routine as an option).

* optional - auto-reset of trace-buffer
May be you had a trigger to reset the buffer; the tracing will be starting 
at the front of the buffer again and other, previous trace info is lost.
Do this with macro DCgcRTRC_RESET_RAMBUF().
-
Hint:
This RAM-Trace buffer is now not cyclic used; if it is full the tracing ends!
So you could decide how big the buffer should be (DCgcRTRC_MAX_RAMTRACE_BUF) 
and for permanent tracing you had to reset the buffer from time to time.
(May be saving the previous content or it will be lost).

* optional - file-system trace addition
Use gcdebfstrc.c/.h files and init/write/deinit functions to save RAM trace-
buffer from time-to-time in a file.
(Not usable without RTrc i.e. gcdebrtrc.c/.h!)

-------------------------------------------------------------------------------