trap.gml

来自「开放源码的编译器open watcom 1.6.0版的源代码」· GML 代码 · 共 2,053 行 · 第 1/5 页

:eXMP.
:PC.
The :F.stack_pointer:eF. and :F.program_counter:eF. fields store the latest
values of SS:ESP and CS:EIP (or their non-x86 equivalents) respectively.
The :F.conditions:eF. informs the debugger what conditions have changed since
execution began. It contains the following flags:
:XMP.
    Bit 0   : COND_CONFIG           - Configurations change
    Bit 1   : COND_SECTIONS         - Program overlays change
    Bit 2   : COND_LIBRARIES        - Libraries (DLL) change
    Bit 3   : COND_ALIASING         - Alias change
    Bit 4   : COND_THREAD           - Thread change
    Bit 5   : COND_THREAD_EXTRA     - Thread extra change
    Bit 6   : COND_TRACE            - Trace point occurred
    Bit 7   : COND_BREAK            - Break point occurred
    Bit 8   : COND_WATCH            - Watch point occurred
    Bit 9   : COND_USER             - User interrupt
    Bit 10  : COND_TERMINATE        - Program terminated
    Bit 11  : COND_EXCEPTION        - Machine exception
    Bit 12  : COND_MESSAGE          - Message to be displayed
    Bit 13  : COND_STOP             - Debuggee wants to stop
    Bit 14-15  :  not used
:eXMP.
When a bit is off, the debugger avoids having to make additional requests
to determine the new state of the debuggee. If the trap file is not sure
that a particular item has changed, or if it is expensive to find out, it
should just turn the bit on.
.section REQ_PROG_LOAD (20)
Request to load a program.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_8      true_argv
    -------------------------
    bytes           argv
:eXMP.
:PC.
The :F.true_argv:eF. field indicates whether the argument consists of a
single string, or a true C-style argument vector. This field is set to
be one for a true argument vector and zero otherwise.
The :F.argv:eF. is a set of zero-terminated strings, one following each
other. The first string gives the name of the
program to be loaded. The remainder of the :F.argv:eF. field contains
the program's arguments. The arguments can be a single string or an array
of strings.
:P.
Return message:
:XMP.
    trap_error      err
    trap_phandle    task_id
    trap_mhandle    mod_handle
    unsigned_8      flags
:eXMP.
:PC.
The :F.err:eF. field returns the error code while loading the program.
The :F.task_id:eF. shows the task (process) ID for the program loaded.
The :F.mod_handle:eF. is the system module identification for the executable
image. It is used as input to the REQ_MAP_ADDR request.
The :F.flags:eF. field contains the following
information:
:XMP.
    Bit 0      :  LD_FLAG_IS_32             - 32-bit program (obsolete)
    Bit 1      :  LD_FLAG_IS_PROT           - Protected mode (obsolete)
    Bit 2      :  LD_FLAG_IS_STARTED        - Program already started
    Bit 3      :  LD_FLAG_IGNORE_SEGMENTS   - Ignore segments (flat)
    Bit 4      :  LD_FLAG_HAVE_RUNTIME_DLLS - DLL load breaks supported
    Bit 5      :  LD_FLAG_DISPLAY_DAMAGED   - Debugger must repaint screen
    Bit 6 - 7  :  not used
:eXMP.
.section REQ_PROG_KILL (21)
Request to kill the program.
:P.
Request message:
:XMP.
    access_req      req
    trap_phandle    task_id
:eXMP.
:PC.
The :F.req:eF. field contains the request. The :F.task_id:eF. field (obtained
from REQ_PROG_LOAD) identifies the program to be killed.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
The :F.err:eF. field returns the error code of the OS kill program
operation.
.section REQ_SET_WATCH (22)
Request to set a watchpoint at the address given.
:P.
Request message:
:XMP.
    access_req      req
    addr48_ptr      watch_addr
    unsigned_8      size
:eXMP.
:PC.
The address of the watchpoint is given by the :F.watch_addr:eF. field. The
:F.size:eF. field gives the number of bytes to be watched.
:P.
Return message:
:XMP.
    trap_error      err
    unsigned_32     multiplier
:eXMP.
The :F.err:eF. field returns the error code if the setting failed.
If the setting of the watchpoint worked, the 31 low order bits of
:F.multiplier:eF. indicate the expected slow down of the program when it's
placed into execution. The top bit of the field is set to one if a debug
register is being used for the watchpoint, and zero if the watchpoint is
being done by software.
.section REQ_CLEAR_WATCH (23)
Request to clear a watchpoint at the address given. The trap file may
assume all watch points are cleared at once.
:P.
Request message:
:XMP.
    access_req      req
    addr48_ptr      watch_addr
    unsigned_8      size
:eXMP.
:PC.
The address of the watch point is given by the :F.watch_addr:eF. field. The
:F.size:eF. field gives the size of the watch point.
:P.
Return message:
:XMP.
    NONE
:eXMP.
.section REQ_SET_BREAK (24)
Request to set a breakpoint at the address given.
:P.
Request message:
:XMP.
    access_req      req
    addr48_ptr      break_addr
:eXMP.
:PC.
The address of the break point is given by the :F.break_addr:eF. field.
:P.
Return message:
:XMP.
    unsigned_32     old
:eXMP.
:PC.
The :F.old:eF. field returns the original byte(s) at the address
:F.break_addr:eF..
.section REQ_CLEAR_BREAK (25)
Request to clear a breakpoint at the address given. The trap file may
assume all breakpoints are cleared at once.
:P.
Request message:
:XMP.
    access_req      req
    addr48_ptr      break_addr
    unsigned_32     old
:eXMP.
:PC.
The address of the break point is given by the :F.break_addr:eF. field. The
:F.old:eF. field holds the old instruction returned from the REQ_SET_BREAK
request.
:P.
Return message:
:XMP.
    NONE
:eXMP.
.section REQ_GET_NEXT_ALIAS (26)
Request to get alias information for a segment. In some protect mode
environments (typically 32-bit flat) two different selectors may refer
to the same physical memory. Which selectors do this is important to
the debugger in certain cases (so that symbolic information is properly
displayed).
:P.
Request message:
:XMP.
    access_req      req
    unsigned_16     seg
:eXMP.
:PC.
The :F.seg:eF. field contains the segment. To get the first alias, put zero
in this field.
:P.
Return message:
:XMP.
    unsigned_16     seg
    unsigned_16     alias
:eXMP.
:PC.
The :F.seg:eF. field contains the next segment where an alias appears. If this field
returns zero, it implies no more aliases can be found. The :F.alias:eF. field
returns the alias of the input segment. Zero indicates a previously set alias
should be deleted.
.section REQ_SET_USER_SCREEN (27)
Request to make the debuggee's screen visible.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:P.
Return message:
:XMP.
    NONE
:eXMP.
.section REQ_SET_DEBUG_SCREEN (28)
Request to make the debugger's screen visible.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:P.
Return message:
:XMP.
    NONE
:eXMP.
.section REQ_READ_USER_KEYBOARD (29)
Request to read the remote keyboard input.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_16     wait
:eXMP.
:PC.
The request will be time out if it waits longer than the period specifies in the
:F.wait:eF. field. The waiting period is measured in seconds. A value of zero
means to wait forever.
:P.
Return message:
:XMP.
    unsigned_8      key
:eXMP.
:PC.
The :F.key:eF. field returns the input character from remote machine.
.section REQ_GET_LIB_NAME (30)
Request to get the name of a newly loaded library (DLL).
:P.
Request message:
:XMP.
    access_req      req
    trap_mhandle    handle
:eXMP.
:PC.
The :F.handle:eF. field contains the library handle. It should be zero
to get the name of the first DLL or the value from the :F.handle:eF.
of a previous request.
:P.
Return message:
:XMP.
    trap_mhandle    handle
    ---------------------------
    string          name
:eXMP.
:PC.
The :F.handle:eF. field contains the library handle. It contains zero if
there are no more DLL names to be returned. The name of the library will be returned in
:F.name:eF. field. If the :F.name:eF. field is an empty string (consists
just of the '\0' character), then this is a indication that the DLL indicated
by the given handle has been unloaded, and the debugger should remove
any symbolic information for the image. It is an error to attempt to remove
a handle that has not been loaded in a previous REQ_GET_LIB_NAME request.
.section REQ_GET_ERR_TEXT (31)
Request to get the error message text for an error code.
:P.
Request message:
:XMP.
    access_req      req
    trap_error      err
:eXMP.
:PC.
The :F.err:eF. field contains the error code number of the error text
requested.
:P.
Return message:
:XMP.
    string          error_msg
:eXMP.
:PC.
The error message text will be returned in :F.error_msg:eF. field.
.section REQ_GET_MESSAGE_TEXT (32)
Request to retrieve generic message text. After a REQ_PROG_LOAD, REQ_PROG_GO
or REQ_PROG_STEP has returned with COND_MESSAGE or COND_EXCEPTION,
the debugger will make this request to obtain the message text. In the
case of a COND_EXCEPTION return text describing the machine exception
that caused the return to the debugger. Otherwise return whatever generic
message text that the trap file wants to display to the user.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:P.
Return message:
:XMP.
    unsigned_8      flags
    ---------------------
    string          msg
:eXMP.
:PC.
The message text will be returned in the :F.msg:eF. field.
The :F.flags:eF. contains a number of bits which control the next action
of the debugger. They are:
:XMP.
    Bit 0       : MSG_NEWLINE
    Bit 1       : MSG_MORE
    Bit 2       : MSG_WARNING
    Bit 3       : MSG_ERROR
    Bit 4 - 7   : not used
:eXMP.
:PC.
The MSG_NEWLINE bit indicates that the debugger should scroll its display
to a new line after displaying the message.
The MSG_MORE bit indicates that there is another line of output to come
and the debugger should make another REQ_GET_MESSAGE_TEXT.
MSG_WARNING indicates that the message is a warning level message while
MSG_ERROR is an error level message. If neither of these bits are on, the
message is merely informational.
.section REQ_REDIRECT_STDIN (33)/REQ_REDIRECT_STDOUT (34)
Request to redirect the standard input (REQ_REDIRECT_STDIN) or
standard output (REQ_REDIRECT_STDOUT) of the debuggee.
:P.
Request message:
:XMP.
    access_req      req
    ------------------------
    string          name
:eXMP.
:PC.
The file name to be redirected
to/from is given by the :F.name:eF. field.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
When an error has occurred, the :F.err:eF. field contains an error code
indicating the type of error that has been detected.
.section REQ_SPLIT_CMD (35)
Request to split the command line into the command name and
parameters.
:P.
Request message:
:XMP.
    access_req      req
    ------------------------
    string          cmd
:eXMP.
:PC.
The :F.cmd:eF.
field contains the command. Command can be a single command line or an array
of command strings.
:P.
Return message:
:XMP.
    unsigned_16     cmd_end
    unsigned_16     parm_start
:eXMP.
:PC.
The :F.cmd_end:eF. field tells the position in command line where the command
name ends. The :F.parm_start:eF. field stores the position where the
program arguments begin.
.section REQ_READ_REGS (36)
Request to read CPU register contents. The data returned depends on
the target architecture and is defined by the MAD file.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:PC.
:P.
Return message:
:XMP.
    unspecified
:eXMP.
:PC.
The return message content is specific to the MAD in use and will contain
a :F.mad_registers:eF. union (defined in :F.madtypes.h:eF.).
.section REQ_WRITE_REGS (37)
Request to write CPU register contents. The data is target architecture
specific.
:P.
Request message:
:XMP.
    access_req      req
    -------------------
    unspecified
:eXMP.
:PC.
The message content is specific to the MAD in use and will contain a
:F.mad_registers:eF. union.
:P.
Return message:
:XMP.
    NONE
:eXMP.
:PC.
.section REQ_MACHINE_DATA (38)
Request to retrieve machine specific data.
:P.
Request message:
:XMP.
    access_req      req;
    unsigned_8      info_type;
    addr48_ptr      addr;
    -----------------------------
    unspecified