trap.gml

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

Request to perform a supplementary service.
:P.
Request message:
:XMP.
    access_req  req
    unsigned_32 service_id
    ------------------------
    unspecified
:eXMP.
:PC.
The :F.req:eF. field contains the request. The :F.service_id:eF field
indicates which service is being requested. The remainder of the request
is specified by the individual supplementary service provider.
:P.
Return message:
:XMP.
    unspecified
:eXMP.
:PC.
The return message is specified by the individual supplementary service
provider.
.section REQ_GET_SYS_CONFIG (6)
Request to get system information from the remote machine.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:PC.
The :F.req:eF. field contains the request.
:P.
Return message:
:XMP.
    unsigned_8  cpu;
    unsigned_8  fpu;
    unsigned_8  osmajor;
    unsigned_8  osminor;
    unsigned_8  os;
    unsigned_8  huge_shift;
    mad_handle  mad;
:eXMP.
:PC.
The :F.mad:eF. field specifies the MAD (Machine Architecture Description) in use
and determines how the other fields will be interpreted. Currently the following
MADs are used:
:XMP.
    MAD_X86 - Intel IA-32 compatible
    MAD_AXP - Alpha AXP
    MAD_PPC - PowerPC
:eXMP.
:PC.
The :F.cpu:eF. fields returns the type of the remote CPU. The size of that field
is unsigned_8. Possible CPU types for MAD_X86 are:
:XMP.
    bits 0-3
       X86_86  = 0   - 8086
       X86_186 = 1   - 80186
       X86_286 = 2   - 80286
       X86_386 = 3   - 80386
       X86_486 = 4   - 80486
       X86_586 = 5   - Pentium
       X86_686 = 6   - Pentium Pro/II/III
       X86_P4  = 15  - Pentium 4
    bit  4           - MM registers
    bit  5           - XMM registers
    bits 6,7         - unused
:eXMP.
:PC.
The :F.fpu:eF. fields tells the type of FPU. The size of the field is unsigned_8.
FPU types for MAD_X86 include:
:XMP.
    X86_EMU = -1     - Software emulated FPU
    X86_NO  =  0     - No FPU
    X86_87  =  1     - 8087
    X86_287 =  2     - 80287
    X86_387 =  3     - 80387
    X86_487 =  4     - 486 integrated FPU
    X86_587 =  5     - Pentium integrated FPU
    X86_587 =  6     - Pentium Pro/II/III integrated FPU
    X86_P47 =  15    - Pentium 4 integrated FPU
:eXMP.
:PC.
The :F.osmajor:eF. and :F.osminor:eF. contains the major and minor version
number for the operating system of the remote machine. The type of operating
system can be found in
:F.os:eF. field. The size of this field is unsigned_8. The OS can be :
:XMP.
    OS_IDUNNO    =  0   - Unknown operating system
    OS_DOS       =  1   - DOS
    OS_OS2       =  2   - OS/2
    OS_PHAR      =  3   - Phar Lap 386 DOS Extender
    OS_ECLIPSE   =  4   - Eclipse 386 DOS Extender (obsolete)
    OS_NW386     =  5   - NetWare 386
    OS_QNX       =  6   - QNX 4.x
    OS_RATIONAL  =  7   - DOS/4G or compatible
    OS_WINDOWS   =  8   - Windows 3.x
    OS_PENPOINT  =  9   - PenPoint (obsolete)
    OS_NT        = 10   - Win32
    OS_AUTOCAD   = 11   - ADS/ADI development (obsolete)
    OS_NEUTRINO  = 12   - QNX 6.x
    OS_LINUX     = 13   - Linux
:eXMP.
:PC.
The :F.huge_shift:eF. field is used to determine the shift needed for huge
arithmetic in that system. It stores the number of left shifts required in order
to calculate the next segment correctly. It is 12 for real mode programs. The
value in a protect mode environment must be obtained from the OS of the debuggee
machine. This field is only relevant for 16-bit segmented architectures.
.section REQ_MAP_ADDR (7)
Request to map the input address to the actual address of the remote machine.
The addresses in the symbolic information provided by the linker do not
reflect any relocation performed on the executable by the system loader. This
request obtains that relocation information so that the debugger can update
its addresses.
:P.
Request message:
:XMP.
    access_req      req;
    addr48_ptr      in_addr;
    trap_mhandle    handle;
:eXMP.
:PC.
The :F.req:eF. field contains the request. The :F.in_addr:eF. tells the address
to map. The :F.handle:eF. field identifies the module which the address is
from. The value from this field is obtained by REQ_PROG_LOAD or
REQ_GET_LIB_NAME. There are two magical values for the :F.in_addr.segment:eF.
field.
:XMP.
    MAP_FLAT_CODE_SELECTOR  = -1
    MAP_FLAT_DATA_SELECTOR  = -2
:eXMP.
:PC.
When the :F.in_addr.segment:eF. equals one of these values, the debugger
does not have a map segment value and is requesting that the trap file
performs the mapping as if the given offset was in the flat address space.
:P.
Return message:
:XMP.
    addr48_ptr      out_addr
    addr48_off      lo_bound;
    addr48_off      hi_bound;
:eXMP.
:PC.
The mapped address is returned in :F.out_addr:eF.. Note that in addition
to the segment portion being modified, the offset of the portion of the
address may be adjusted as well if the loader performs offset relocations
(like OS/2 2.x or Windows NT). The :F.lo_bound:eF. and :F.hi_bound:eF. fields
identify the lowest and highest input offsets for which this mapping is
valid. If the debugger needs to map another address whose input segment value
is the same as a previous request, and the input offset falls within the
valid range identified by the return of that previous request, it can
perform the mapping itself and not bother sending the request to the trap
file.
.section REQ_ADDR_INFO (8)
This request is x86 specific and obsolete; REQ_MACHINE_DATA should be used
instead. It needs to be provided only for backwards compatibility.
:P.
Request to check if a given address is using 32-bit addressing (the
386 compatible CPU's current selector's B-bit is on) by
default. The debugger requires this information to properly disassemble
instructions.
:P.
Request message:
:XMP.
    access_req      req
    addr48_ptr      in_addr
:eXMP.
:PC.
The :F.req:eF. field contains the request and the :F.in_addr:eF. tells the input
address.
:P.
Return message:
:XMP.
    unsigned_8      is_32
:eXMP.
:PC.
The field returns one if the address is a USE32 segment, zero otherwise.
.section REQ_CHECKSUM_MEM (9)
Request to calculate the checksum for a block of memory in the debuggee's
address space.
This is used by the debugger to determine if the contents of the memory block
have changed since the last time it was read. Since only a four byte
checksum has to be transmitted back, it is more efficient than actually
reading the memory again. The debugger does not care how the checksum
is calculated.
:P.
Request message:
:XMP.
    access_req      req;
    addr48_ptr      in_addr;
    unsigned_16     len;
:eXMP.
:PC.
The :F.req:eF. field stores the request. The :F.in_addr:eF. contains the
starting address and the :F.len:eF. field tells how large the block of memory is.
:P.
Return message:
:XMP.
    unsigned_32     result
:eXMP.
:PC.
The checksum will be returned in :F.result:eF..
.section REQ_READ_MEM (10)
Request to read a block of memory.
:P.
Request message:
:XMP.
    access_req      req;
    addr48_ptr      mem_addr;
    unsigned_16     len;
:eXMP.
:PC.
The :F.mem_addr:eF. contains the address of the memory block to read from the
remote machine. The length of the block is determined by :F.len:eF.. The
memory data will be copied to output message.
:P.
Return message:
:XMP.
    bytes       data
:eXMP.
:PC.
The :F.data:eF. field stores the memory block read in. The length of this memory
block is given by the return value from TrapRequest. If error has occurred in reading
memory, the length of the data returns will not be equal to the number of bytes
requested.
.section REQ_WRITE_MEM (11)
Request to write a block of memory.
:P.
Request message:
:XMP.
    access_req      req
    addr48_ptr      mem_addr
    ------------------------
    bytes           data
:eXMP.
:PC.
The :F.data:eF. field stores the memory data to be transferred. The data will be
stored in the debuggee's address space starting at the address in the
:F.mem_addr:eF. field.
:P.
Return message:
:XMP.
    unsigned_16 len
:eXMP.
:PC.
The :F.len:eF. field tells the length of memory block actually written to the
debuggee machine. If error has occurred in writing the memory, the length
returned will not be equal to the number of bytes requested.
.section REQ_READ_IO (12)
Request to read data from I/O address space of the debuggee.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_32     IO_offset
    unsigned_8      len
:eXMP.
:PC.
The :F.IO_offset:eF. contains the I/O address of the debuggee machine. The length
of the block is determined by :F.len:eF.. It must be 1, 2 or 4 bytes. The
data will be copied from :F.IO_offset:eF. to the return message.
:P.
Return message:
:XMP.
    bytes       data
:eXMP.
:PC.
The :F.data:eF. field stores the memory block read in. The length of this memory
block is given by the return value from TrapRequest. If an error has occurred in
reading, the length returned will not be equal to the number of bytes
requested.
.section REQ_WRITE_IO (13)
Request to write data to the I/O address space of the debuggee.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_32     IO_offset
    -------------------------
    bytes           data
:eXMP.
:PC.
The :F.IO_offset:eF. contains the I/O address of the debuggee machine.
The data stored in :F.data:eF. field will be copied to :F.IO_offset:eF. on
the debuggee machine.
:P.
Return message:
:XMP.
    unsigned_8  len
:eXMP.
:PC.
The :F.len:eF. field tells the number of bytes actually written out. If an error
has occurred in writing, the length returned will not be equal
to the number of bytes requested.
.section REQ_READ_CPU (14)
This request is x86 specific and obsolete; REQ_READ_REGS should be used
instead. It needs to be provided only for backwards compatibility.
:P.
Request to read the CPU registers.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:P.
Return message:
:XMP.
    bytes           data
:eXMP.
:PC.
The :F.data:eF.
field contains the register information requested. It contains the following
structure:
:XMP.
    struct cpu_regs {
        unsigned_32 EAX;
        unsigned_32 EBX;
        unsigned_32 ECX;
        unsigned_32 EDX;
        unsigned_32 ESI;
        unsigned_32 EDI;
        unsigned_32 EBP;
        unsigned_32 ESP;
        unsigned_32 EIP;
        unsigned_32 EFL;
        unsigned_32 CR0;
        unsigned_32 CR2;
        unsigned_32 CR3;
        unsigned_16 DS;
        unsigned_16 ES;
        unsigned_16 SS;
        unsigned_16 CS;
        unsigned_16 FS;
        unsigned_16 GS;
        };
:eXMP.
.section REQ_READ_FPU (15)
This request is x86 specific and obsolete; REQ_READ_REGS should be used
instead. It needs to be provided only for backwards compatibility.
:P.
Request to read the FPU registers.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:P.
Return message:
:XMP.
    bytes           data
:eXMP.
:PC.
The :F.data:eF. field contains the register information requested. Its format
is the same as the result of a "fsave" instruction in a 32-bit segment (the
instruction pointer and operand pointer fields take up 8 bytes each).
Implementations of trap files in 16-bit environments should expand the
instruction pointer and operand pointer fields from 4 bytes to 8 (shuffling
the data register fields down in memory) before returning the result to
the debugger.
.section REQ_WRITE_CPU (16)/REQ_WRITE_FPU (17)
These requests are x86 specific and obsolete; REQ_WRITE_REGS should be used
instead. They needs to be provided only for backwards compatibility.
:P.
Requests to write to the CPU or FPU state.
:P.
Request message:
:XMP.
    access_req          req
    ------------------------
    bytes               data
:eXMP.
:P.
Information in :F.data:eF. field will be transfered to the debuggee's
registers. The formats of data can be found in
REQ_READ_CPU/REQ_READ_FPU
:NOTE.
For the REQ_WRITE_FPU case, the data will be in a 32-bit "fsave" instruction
format,
so 16-bit environments will have to squish the instruction and operand
pointer fields back to their 4 byte forms.
:P.
Return message:
:XMP.
    NONE
:eXMP.
:PC.
.section REQ_PROG_GO (18)/REQ_PROG_STEP (19)
Requests to execute the debuggee. REQ_PROG_GO causes the debuggee to
resume execution, while REQ_PROG_STEP requests only a single machine
instruction to be executed before returning. In either case, this
request will return when a breakpoint, watchpoint, machine exception
or other significant event has been encountered. While executing, a
trap file is allowed to return spurious COND_WATCH indications.
The debugger always checks its own watchpoint table for changes before
reporting to the user. This means that a legal implementation of a trap
file (but :HP2.very:eHP2. inefficient) can just single step the program and return
COND_WATCH for every instruction when there are active watchpoints
present.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:PC.
The request is in :F.req:eF. field.
:P.
Return message:
:XMP.
    addr48_ptr      stack_pointer
    addr48_ptr      program_counter
    unsigned_16     conditions