trap.gml

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

:eXMP.
:PC.
The :F.info_type:eF. field specifies what kind of information should be
returned and :F.addr:eF. determines the address for which the information
is requested. The remainder of the message is MAD specific.
:P.
Return message:
:XMP.
    addr48_off      cache_start;
    addr48_off      cache_end;
    -----------------------------
    unspecified
:eXMP.
:PC.
The return message content is specific to the MAD in use.
.endlevel
.*
.*
.*
.section File I/O requests
This section describes requests that deal with file input/output on the
target (debuggee) machine.
These requests are actually performed by the
core request REQ_PERFORM_SUPPLEMENTARY_SERVICE and appropriate service ID.
The following descriptions do not show that "prefix" to the
request messages.
:P.
The service name to be used in the REQ_GET_SUPPLEMENTARY_SERVICE is
"Files".
:P.
The file requests use a new basic type in addition to the ones already
described:
:DL.
:DTHD.Type
:DDHD.Definition
:DT.trap_fhandle
:DD.This is an :F.unsigned_32:eF. which holds a debuggee file handle.
:eDL.
.beglevel
.section REQ_FILE_GET_CONFIG (0)
Request to retreive characteristics of the remote file system.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:P.
Return message:
:XMP.
    char            ext_separator;
    char            path_separator[3];
    char            newline[2];
:eXMP.
:PC.
The
:F.ext_separator:eF. contains the separator for file name extensions. The possible
path separators can be found in array :F.path_separator:eF.. The first one is the
"preferred" path separator for that operating system.
This is the path separator that the debugger will use if it needs to construct
a file name for the remote system.
The new line control
characters are stored in array :F.newline:eF.. If the operating system uses only
a single character for newline, put a zero in the second element.
.section REQ_FILE_OPEN (1)
Request to create/open a file.
:P.
Request message:
:XMP.
    access_req          req
    unsigned_8          mode
    ------------------------
    string              name
:eXMP.
:PC.
The name of the file to be opened is given by :F.name:eF..
The :F.mode:eF. field stores the access mode of the
file. The following bits are defined:
:XMP.
    Bit 0      :  TF_READ
    Bit 1      :  TF_WRITE
    Bit 2      :  TF_CREATE
    Bit 3      :  TF_EXEC
    Bit 4 - 7  :  not used
:eXMP.
:PC.
For read/write mode, turn both :F.TF_READ:eF. and :F.TF_WRITE:eF. bits on.
The :F.TF_EXEC:eF. bit should only be used together with :F.TF_CREATE:eF. and
indicates that the created file needs executable permission (if relevant on
the target platform).
:P.
Return message:
:XMP.
    trap_error      err
    trap_fhandle    handle
:eXMP.
:PC.
If successful, the :F.handle:eF. returns a handle for the file. When an error
has occurred, the :F.err:eF. field contains a value indicating the type
of error that has been detected.
.section REQ_FILE_SEEK (2)
Request to seek to a particular file position.
:P.
Request message:
:XMP.
    access_req      req
    trap_fhandle    handle
    unsigned_8      mode
    unsigned_32     pos
:eXMP.
:PC.
The handle of the file is given by the :F.handle:eF. field. The :F.mode:eF.
field stores the seek mode. There are three seek modes:
:XMP.
    TF_SEEK_ORG = 0  - Relative to the start of file
    TF_SEEK_CUR = 1  - Relative to the current file position
    TF_SEEK_END = 2  - Rrelative to the end of file
:eXMP.
:PC.
The position to seek to is in the :F.pos:eF. field.
:P.
Return message:
:XMP.
    trap_error      err
    unsigned_32     pos
:eXMP.
:PC.
If an error has occurred, the :F.err:eF. field contains a value indicating
the type of error that has been detected. The :F.pos:eF. field returns the current
position of the file.
.section REQ_FILE_READ (3)
Request to read a block of data from a file.
:P.
Request message:
:XMP.
    access_req          req
    trap_fhandle        handle
    unsigned_16         len
:eXMP.
:PC.
The handle of the file is given by the :F.handle:eF. field. The :F.len:eF.
field stores the number of bytes to be transmitted.
:P.
Return message:
:XMP.
    trap_error          err
    --------------------------
    bytes               data
:eXMP.
:PC.
If successful, the :F.data:eF. returns the block of data.
The length of returned data is given by the return value of TrapRequest
minus 4 (to account for the size of :F.err:eF.).
The length will normally be equal to the :F.len:eF.
field. If the end of file is encountered before the read completes, the return
value will be less than the number of bytes requested. When an error has
occurred, the :F.err:eF. field contains a value indicating the type of
error that has been detected.
.section REQ_FILE_WRITE (4)
Request to write a block of data to a file.
:P.
Request message:
:XMP.
    access_req      req
    trap_fhandle    handle
    ------------------------
    bytes           data
:eXMP.
:PC.
The handle of the file is given by the :F.handle:eF. field. The data is given in
:F.data:eF. field.
:P.
Return message:
:XMP.
    trap_error      err
    unsigned_16     len
:eXMP.
:PC.
If there is no error, :F.len:eF. will equal to that in the :F.data_len:eF.
field. When an error has occurred, the :F.err:eF. field contains a value
indicating the type of error that has been detected.
.section REQ_FILE_WRITE_CONSOLE (5)
Request to write a block of data to the debuggee's screen.
:P.
Request message:
:XMP.
    access_req      req
    ------------------------
    bytes           data
:eXMP.
:PC.
The data is given in :F.data:eF. field.
:P.
Return message:
:XMP.
    trap_error      err
    unsigned_16     len
:eXMP.
:PC.
If there is no error, :F.len:eF. will equal to the :F.data_len:eF.
field. When an error has occurred, the :F.err:eF. field contains a value
indicating the type of error that has been detected.
.section REQ_FILE_CLOSE (6)
Request to close a file.
:P.
Request message:
:XMP.
    access_req      req
    trap_fhandle    handle
:eXMP.
:PC.
The handle of the file is given by the :F.handle:eF. field.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
When an error has occurred, the :F.err:eF. field contains a value
indicating the type of error that has been detected.
.section REQ_FILE_ERASE (7)
Request to erase a file.
:P.
Request message:
:XMP.
    access_req      req
    -------------------------
    string          file_name
:eXMP.
:PC.
The :F.file_name:eF
field contains the file name to be deleted.
:P.
Return message:
:XMP.
    trap_error  err
:eXMP.
:PC.
If error has occurred when erasing the file, the :F.err:eF. field will
return the error code number.
.section REQ_FILE_STRING_TO_FULLPATH (8)
Request to convert a file name to its full path name.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_8      file_type
    -------------------------
    string          file_name
:eXMP.
:PC.
The :F.file_type:eF. field indicates the type of the input file.
File types can be:
:XMP.
    TF_FILE_EXE  =  0
    TF_FILE_DBG  =  1
    TF_FILE_PRS  =  2
    TF_FILE_HLP  =  3
:eXMP.
:PC.
This is
so the trap file can search different paths for the different types
of files. For example, under QNX, the PATH environment variable is searched
for the FILE_EXE type, and the WD_PATH environment variable is searched
for the others.
The :F.file_name:eF
field contains the file name to be converted.
:P.
Return message:
:XMP.
    trap_error      err
    --------------------------
    string          path_name
:eXMP.
:PC.
If no error occurs the :F.err:eF. field returns a zero and the full path name
will be stored in the :F.path_name:eF. field. 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_FILE_RUN_CMD (9)
Request to run a command on the target (debuggee's) system.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_16     chk_size
    ------------------------
    string          cmd
:eXMP.
:PC.
The :F.chk_size:eF. field gives the check size in kilobytes. This field
is only useful in the DOS implementation. It contains the value of
the /CHECKSIZE debugger command line option and represents the amount of
memory the user wishes to have free for the spawned sub-shell. The :F.cmd:eF.
field stores the command to be executed.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
If error has occurred when executing the command, the :F.err:eF. field
will return the error code number.
.endlevel
.*
.*
.*
.section Overlay requests
This section describes requests that deal with overlays (supported
only under 16-bit DOS).
These requests are actually performed by the
core request REQ_PERFORM_SUPPLEMENTARY_SERVICE and appropriate service ID.
The following descriptions do not show that "prefix" to the
request messages.
:P.
The service name to be used in the REQ_GET_SUPPLEMENTARY_SERVICE is
"Overlays".
:P.
The overlay requests use a new basic type in addition to the ones already
described:
:DL.
:DTHD.Type
:DDHD.Definition
:DT.addr32_ptr
:DD.This type encapsulates the concept of a 16:16 pointer into the
debuggee's address space. Since overlays are
only useful for 16-bit environments, using the addr48_ptr type would be
inefficient.
The structure is defined as follows:
:XMP.
    typedef struct {
        unsigned_16    offset;
        unsigned_16    segment;
    } addr32_ptr;
:eXMP.
The :F.segment:eF. field contains the segment of the address and the :F.offset:eF.
field stores the offset of the address.
:eDL.
.beglevel
.section REQ_OVL_STATE_SIZE (0)
Request to return the size of the overlay state information in bytes of the
task program.
This request maps onto the
overlay manager's GET_STATE_SIZE request. See the Overlay Manager
Interface document for more information on the contents of the return
message.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:PC.
The :F.req:eF. field contains the request.
:P.
Return message:
:XMP.
    unsigned_16     size
:eXMP.
:PC.
The :F.size:eF. field returns the size in bytes. A value of zero indicates
no overlays are present in the debuggee and none of the other requests
dealing with overlays will ever be called.
.section REQ_OVL_GET_DATA (1)
:P.
Request to get the address and size of an overlay section.
This request maps onto the
overlay manager's GET_SECTION_DATA request. See the Overlay Manager
Interface document for more information on the contents of the return
message.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_16     sect_id
:eXMP.
The :F.sect_id:eF. field indicates the overlay section the information is
being requested of.
:P.
Return message:
:XMP.
    unsigned_16     segment
    unsigned_32     size
:eXMP.
:PC.
The :F.segment:eF. field contains the segment value where the overlay
section is loaded (or would be loaded if it was brought into memory).
The :F.size:eF. field gives the size, in bytes, of the overlay section.
If there is no section for the given id, the :F.segment:eF. field will be
zero.
.section REQ_OVL_READ_STATE (2)
:P.
Request to read the overlay table state.
This request maps onto the
overlay manager's GET_OVERLAY_STATE request. See the Overlay Manager
Interface document for more information on the contents of the return
message.
The size of the returned data is provided by the REQ_OVL_STATE_SIZE
trap file request.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:P.
Return message:
:XMP.
    bytes           data
:eXMP.
:PC.
The :F.data:eF. field contains the overlay state information requested.
.section REQ_OVL_WRITE_STATE (3)
:P.