Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                              MiNT  Debugging


MiNT allows a processes' TEXT, DATA, and BSS space to be read and written
to with standard GEMDOS file commands by opening the process on 'U:\PROC\'
A file named "TEST" with a MiNT identification of 10 could be opened by
specifying the name as 'U:\PROC\TEST.10' or 'U:\PROC\.10'. Opening a file
to 'U:\PROC\.-1' will open your own process whereas opening a file to
'U:\PROC\.-2' will open your parent process.

Tracing

A process may be setup for tracing in a number of ways. A child process
may be started in trace mode by OR'ing 0x8000 with the Pexec() mode number
in a Pexec() call. A process may also trace another process by opening it
as described above and using the Fcntl() call with a parameter of
PTRACESFLAGS. Processes may start tracing on themselves if their parent is
prepared for it.

When in trace mode, the process being traced halts and generates a SIGCHLD
signal to its tracer after every instruction (unless this action is
modified). The example below shows how to obtain the process ID of the
stopped child and the signal that caused the child to stop.

#define WIFSTOPPED(x) (((int)((x) & 0xFF)==0x7F) && ((int)(((x)>>8)&0xFF)!=0))
#define WSTOPSIG(x)   ((int)(((x)>>8) & 0xFF))

void
HandleSignal( LONG signo )
{
    WORD pid;
    WORD childsignal;
    ULONG r;

    if( signo == SIGCHLD )
    {
            r = Pwait3( 0x2, 0L );
            if( WIFSTOPPED( r ) )
            {
                    pid = r >> 16;
                    childsignal = WSTOPSIG( r );
            }
    }
}


After reception of this signal, the child process may be restarted with
Fcntl() using either the PTRACEGO, PTRACEFLOW, or PTRACESTEP commands.
Setting PTRACEFLOW or PTRACESTEP causes a SIGTRAP signal to be raised on
the next program flow change (ex: BRA or JMP) or the instruction
respectively.

Modifying the Process Context

A processes' registers may be modified during tracing using the method as
illustrated in the following example:

struct context
{
    LONG      regs[15];       // Registers d0-d7, a0-a6
    LONG      usp;            // User stack pointer
    WORD      sr;             // Status register
    LONG      pc;             // Program counter
    LONG      ssp;            // Supervisor stack pointer
    LONG      tvec;           // GEMDOS terminate vector
    char      fstate[216];    // Internal FPU state
    LONG      fregs[3*8];     // Registers FP0-FP7
    LONG      fctrl[3]        // Registers FPCR/FPSR/FPIAR

    // More undocumented fields exist here
} c;

void
ModifyContext( LONG handle )
{
    LONG curprocaddr, ctxtsize;

    Fcntl( handle, &curprocaddr, PPROCADDR );
    Fcntl( handle, &ctxtsize, PCTXTSIZE );

    curprocaddr -= 2 * ctxtsize;

    Fseek( curprocaddr, handle, SEEK_SET );
    Fread( handle, (LONG)sizeof(struct context), &c );

    /* Modify context c here */

    Fseek( curprocaddr, handle, SEEK_SET );
    Fwrite( handle, (LONG)sizeof(struct context), &c );
}

MiNT Debugging Keys

MiNT may be programmed to output special debugging messages to the
debugging device through the use of special system keys. The supported
system keys are shown in the table below:

Key Combination  Meaning

ctrl-alt-F1      Increase the system debugging level by one.

ctrl-alt-F2      Decrease the system debugging level by one.

ctrl-alt-F3      Cycle the BIOS output device number used for system
                 debugging messages. This key cycles BIOS devices in the
                 order 1-6-7-8-9-2.

ctrl-alt-F4      Restore debugging output to the console device.

ctrl-alt-F5      Output a memory usage map to the debugging device.

ctrl-alt-F6      Output a list of all system processes to the debugging
                 device.

ctrl-alt-F7      Toggles debug 'logging' off and on. When debug logging is
                 on, a 50-line buffer is maintained which contains recent
                 debugging messages. Each time a new debugging message is
                 output, the entire 50 line buffer is output as well.

ctrl-alt-F8      Outputs the 50-line debug log to the debugging device.

ctrl-alt-F9      Outputs the system memory map to the debugging device.
                 The memory protection flags of each page are shown.

ctrl-alt-F10     Outputs an extended system memory map to the debugging
                 device. The memory protection status, owner's PID, and
                 format of each memory block are output to the debugging
                 device.

MiNT Debugging Levels

CTRL-ALT-F1 and CTRL-ALT-F2 alter the current system debugging level.
MiNT supports four debugging levels as follows:

Level   Meaning

  0     Only fatal OS errors are reported to the debugging device (this is
        the default mode).

  1     Processor exceptions are output to the debugging device.

  2     Processor exceptions and failed system calls are output to the
        debugging device.

  3     Constant MiNT status reports, processor exceptions, and failed
        system calls are output to the debugging device.