Short:        Library to generate simple call traces
Author:       morgoth6@box43.pl (Marcin 'Morgoth' Kurek)
Uploader:     morgoth6@box43.pl (Marcin 'Morgoth' Kurek)
Type:         dev/c
Version:      0.3
Architecture: MorphOS

Introduction:
==============

Sometimes it's hard to find a reason of the crash. For example if it's random or cause system
freeze. As MorphOS have no real debuger we can't use it to find the problem. 

One solution is to add some kprintf() calls, but what if we are porting huge project and we doesn't 
want (Or have no time) to add ~1000 kprintf's to find a place where our program crash ? We can use this
library to get a full call graph for our program as with libprofile, but in to the serial console in realtime
not in to file.

This way is not perfect as libctrace can give us only function offsets not names directly, but using for
example prf-analyser (Version 0.5 required) from libprofile package we can convert offsets in to real names. 

Example output from libctrace looks like:

[CT] : >> Shell Process->0x000006b8  [test.db:0x1]
[CT] : << Shell Process->0x000006b8  [test.db:0x1]
[CT] : >> Shell Process->0x00000728  [test.db:0x1]
[CT] : << Shell Process->0x00000728  [test.db:0x1]
[CT] : >> Shell Process->0x00000798  [test.db:0x1]
[CT] : << Shell Process->0x00000798  [test.db:0x1]
[CT] : >> Shell Process->0x00000808  [test.db:0x1]
[CT] : << Shell Process->0x00000808  [test.db:0x1]
...

The format is:

[CT] <Prefix>: <Task name>-><Offset> []

Starting from version 0.3 loging to console is disabled by default and may be enabled by
ctrace_log anytime. Also do not try to modify any other ctrace variables if you need to customize
it just declare own.

This version introduce Backtrace() function. Using it you can generate backtrace with ctrace_depth depth
on demand. Can be quite handy to get backtrace only if something wrong happend. Backtrace looks like that:

[BT] : Shell Process->[-1] = 0x00000878  [test.db:0x1]
[BT] : Shell Process->[-2] = 0x00000808  [test.db:0x1]
[BT] : Shell Process->[-3] = 0x00000798  [test.db:0x1]
[BT] : Shell Process->[-4] = 0x00000728  [test.db:0x1]
[BT] : Shell Process->[-5] = 0x000006b8  [test.db:0x1]
[BT] : Shell Process->[-6] = 0x000008e8  [test.db:0x1]
[BT] : Shell Process->[-7] = 0x000008e8  [test.db:0x1]
[BT] : Shell Process->[-8] = 0x00000878  [test.db:0x1]

Usage:
=======

This library is based on libprofile skeleton then usage is similar. Basicly you
need to compile your program with -finstrument-functions and link with libctrace.a

Refer to libprofile readme for more informations.

History:
=========

0.1 - First released version
0.2 - Introduce CTRACE_ENABLE to enable/disable tracing in runtime
0.3 - Make ctrace_flags, ctrace_prefix read only. Do not try to modify it by hand !
      CTRACE_ENABLE removed and transformed to new variable ctrace_log (May be changed anytime)
      Added Backtrace() and ctrace_depth
      Removed potential deadlock

ToDo:
======

None.

Bugs:
======

Who knows.

Author:
=========

Marcin 'Morgoth' Kurek (morgoth6@box43.pl)

ThX:
=====

Gunnar von Boehn