Debug bases:

Q: What is a hit?
A: If a program is accessing the zero-page (also called the low-page)  or  any
   non-available memory, it will create a hit. Basically, a hit is the  report
   of an illegal memory access.
   Hits are never harmless. They are program bugs and must be fixed.

Q: What are Enforcer, Cyberguard and all these MMU tools?
A: They are very hardware specific tools watching for illegal  memory  access.
   Do not use them! The same functionality is already built-in MorphOS and  is
   always active.

Q: What's SegTracker?
A: This tool tracks all code locations. When something is  loaded  in  memory,
   address is stored and put in a database. Then MorphOS uses it   to  display
   the name of a crashed module. It's possible to more easily  identify  where
   hits come from: libraries, devices, handlers, etc
   SegTracker functionnality is built-in MorphOS and is always active.

Q: MorphOS doesn't seem to detect read-access to address 0. Is it normal?
A: Yes, MorphOS doesn't read-protect zero  page;  yet.  It  write-protects  it
   though.


The memtracker:

Q: What is the memtracker?
A: It is a powerfull debug tool built-in MorphOS. It tracks memory allocations
   and reports wrong freeing sizes and mismatching pointers.

   Activate it by using the MorphOS' EDebugFlags boot argument.
     EDebugFlags="permmemtrack" permanently activates memtracker.
     EDebugFlags="permmemtrack memtrack" also activates memtracker's output.

   When memtracker is used (EDebugFlags="permmemtrack"),  it  is  possible  to
   disable/enable its output on the fly, using SystemSettings/Debug/MemTrack.

   When permmemtrack is not used, memtrack still toggles memtracker on/off but
   it won't notice invalid freeing of memory.

   Please note the memtracker fills  all  free  memory  using  the  0xABADCAFE
   pattern. It helps to catch uninitialised pointers, or  using  already  free
   memory.

Q: Why does the system become slower when the memtracker is enabled?
A: The memtracker involves a lot of extra operations during memory  allocation
   and deallocation. It is a pure debug tool. Only use it  when  you  need  to
   track  a  problem  or  when  you  want  to  check  your  memory  management
   correctness.


Debug tools:

Q: Objdump is slow when processing big executable files.  Is  it  possible  to
   speed it up?
A: Yes. It can be restricted to dump only a certain address  range  around  an
   offset.
   Just type "objdump" in a shell  and  read  its  argument-options.  You  are
   looking for the --start-address=addr and --stop-address=addr ones.

   Example:
     objdump program -disassemble-all --start-address=10000 --stop-address=20000 >program.dump

Q: Objdump crashed, how is it possible to debug anyway?
A: It seems there is  a  problem  with  objdump.  You  can  workaround  it  by
   restricting the dump to a smaller range. See above.

Q: How do I use FindHit?
A: You can't. Please use objdump for now.

Q: I heard about addr2line. Can it be used like FindHit?
A: There is a problem with addr2line  and  it  isn't  reliable.  But  CISC  is
   working on it. :-)


kprintf:

Q: How can I output my own debug information? I used to use kprintf().
A: You can still use kprintf(). It is in libdebug.a

Q: How do I capture kprintf() output?
A: Use sushi/sashimi or use EDebugFlags="logkprintf" MorphOS boot argument.

   Example:
     boot boot.img EDebugFlags="logkprintf"

Q: I heard about dprintf() but how can I use it?
A: You do not. There is no such a public function. Please use kprintf().


Weird error messages in the log:

Q: Why do I get "PPC Stack Ptr is not between PPCSPLower and PPCSPUpper"
   message?
A: It means the PPC stack pointer is out of bound.
   Perhaps the program used too much PPC stack and did a  stack  overflow.  Or
   the r1 register got trashed (r1 is the PPC stack pointer, as defined by the
   SystemV ABI).
   This can also happen if a program  uses  setjmp()  or  any  other  function
   playing with the stack.

Q: Why do I get "68k Stack Ptr is not between SPLower and SPUpper" messsage?
A: Perhaps the program used too much 68k stack and overflowed it.  Or  the  a7
   register got trashed (a7 is the 68k stack pointer).
   This can also happen if a program uses a non-standard way to swap the stack.
   AmigaE applications are known to do it. Then this is not a bug, of course.

Q: Why do I get "Error: TaskEmulHandle 0x00000000 is not a legal address"?
A: EmulHandle is the 68k emulation's entry-point and its address is stored  in
   r2. It must always be valid. If it is not; r2 register got trashed.


68k emulation:

Q: Why do I see offset referring to "Emulation" or "Module"?
A: If an offset is in "Emulation". It means the static  emulator  was  running
   some 68k code and you should look at the 68k part of the debug log.
   If an offset is in "Module", it simply means that it is  somewhere  in  the
   MorphOS module ROM: exec, dos, intuition, sfs...

Q: MorphOS has a JIT emulator. When 68k code crashed, what should I look  for;
   PPC or 68k code?
A: 68k code.
   But, when Trance is running, the PC register is referring to the  start  of
   the translated code-block. This is probably not exactly the point where the
   crash happened but it's the only available reference to it. You might  want
   to try disabling JIT to get the precise location of the problem.


Hardcore problems:

Q: I have a really complex crash and much more StackFrame would be  needed  to
   track the problem in my code. What is it possible to do?
A: There is a BackTraceDepth  argument  to  choose  the  amount  of  displayed
   StackFrame. See the documentation in SYS:Docs/PegasosFirmware.txt

   Example:
     boot boot.img BackTraceDepth=10

Q: The system freezes, there is no console window and I can't get the ramdebug
   log.
A: It may be possible to get the ramdebug log after a reboot if  the  firmware
   didn't clear the memory. It all depends on your hardware setup.
   But the best solution is to use serial debug.

Q: What is the meaning of "FAQ" ?
A: Frequently Asked Questions.