trap.gml

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

Request to write the overlay table state.
This request maps onto the
overlay manager's SET_OVERLAY_STATE request. See the Overlay Manager
Interface document for more information on the contents of the return
message.
:P.
Request message:
:XMP.
    access_req      req
    --------------------
    bytes           data
:eXMP.
:PC.
The :F.data:eF. field contains the overlay state information to be restored.
:P.
Return message:
:XMP.
    NONE
:eXMP.
.section REQ_OVL_TRANS_VECT_ADDR (4)
Request to check if the input overlay address is actually an overlay
vector.
This request maps onto the
overlay manager's TRANSLATE_VECTOR_ADDR request. See the Overlay Manager
Interface document for more information on the contents of the
messages.
:P.
Request message:
:XMP.
    access_req      req
    ovl_address     ovl_addr
:eXMP.
:PC.
The :F.ovl_addr:eF. field contains the overlay address. The :F.ovl_addr:eF.
field is defined as follows:
:XMP.
    typedef struct {
        addr32_ptr  mach;
        unsigned_16 sect_id;
    }
:eXMP.
:PC.
The :F.mach:eF. field is the machine address. The :F.sect_id:eF.
field stores the number of entries down in the overlay stack.
:P.
Return message:
:XMP.
    ovl_address     ovl_addr
:eXMP.
:PC.
The translated address will be returned in the :F.ovl_addr:eF. field.
If the address is not an overlay vector, then the input address will be
returned and the :F.section_id:eF. field will be zero.
.section REQ_OVL_TRANS_RET_ADDR (5)
Request to check if the address is the overlay manager parallel return
code.
This request maps onto the
overlay manager's TRANSLATE_RETURN_ADDR request. See the Overlay Manager
Interface document for more information on the contents of the
messages.
:P.
Request message:
:XMP.
    access_req      req
    ovl_address     ovl_addr
:eXMP.
:P.
Return message:
:XMP.
    ovl_address     ovl_addr
:eXMP.
:PC.
The translated address will be returned in the :F.ovl_addr:eF. field.
If the address is not an parallel return code, then the input address will be
returned and the :F.section_id:eF. field in the structure :F.ovl_addr:eF. will
be zero.
.section REQ_OVL_GET_REMAP_ENTRY (6)
Request to check if the overlay address needs to be remapped.
This request maps onto the
overlay manager's GET_MOVED_SECTION request. See the Overlay Manager
Interface document for more information on the contents of the
messages.
:P.
Request message:
:XMP.
    access_req      req
    ovl_address     ovl_addr
:eXMP.
:PC.
The :F.ovl_addr:eF. field contains the overlay address.
:P.
Return message:
:XMP.
    unsigned_8      remapped
    ovl_address     ovl_addr
:eXMP.
:PC.
If the address gets remapped the :F.remapped:eF. field will return one.
The remapped address will be returned in the :F.ovl_addr:eF. field.
The input address will be unchanged if the address has not been remapped.
.endlevel
.*
.*
.*
.section Thread requests
This section descibes requests that deal with threads.
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
"Threads".
:P.
The thread requests use a new basic type in addition to the ones already
described:
:DL.
:DTHD.Type
:DDHD.Definition
:DT.trap_thandle
:DD.This is an :F.unsigned_32:eF. which holds a thread handle.
:eDL.
.beglevel
.section REQ_THREAD_GET_NEXT (0)
Request to get next thread.
:P.
Request message:
:XMP.
    access_req      req
    trap_thandle    thread
:eXMP.
:PC.
The :F.thread:eF. contains the either a zero to get information on the
first thread, or the value of the :F.thread:eF. field in the
return message of a previous request.
:P.
Return message:
:XMP.
    trap_thandle    thread
    unsigned_8      state
:eXMP.
:PC.
The :F.thread:eF. field returns the thread ID. There are no more threads in
the list, it will contain zero.
The :F.state:eF. field can have two values:
:XMP.
    THREAD_THAWED = 0
    THREAD_FROZEN = 1
:eXMP.
.section REQ_THREAD_SET (1)
Request to set a given thread ID to be the current thread.
:P.
Request message:
:XMP.
    access_req      req
    trap_thandle    thread
:eXMP.
:PC.
The :F.thread:eF. contains the thread number to set. If it's zero, do not
attempt to set the thread, just return the current thread ID.
:P.
Return message:
:XMP.
    trap_error      error
    trap_thandle    old_thread
:eXMP.
:PC.
The :F.old_thread:eF. field returns the previous thread ID. If the set fails, the
:F.err:eF. field will be non-zero.
.section REQ_THREAD_FREEZE (2)
Request to freeze a thread so that it will not be run next time when executing
the task program.
:P.
Request message:
:XMP.
    access_req      req
    trap_thandle    thread
:eXMP.
:PC.
The :F.thread:eF. contains the thread number to freeze.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
If the thread cannot be frozen, the :F.err:eF. field returns non-zero value.
.section REQ_THREAD_THAW (3)
Request to allow a thread to run next time when executing the program.
:P.
Request message:
:XMP.
    access_req      req
    trap_thandle    thread
:eXMP.
:PC.
The :F.thread:eF. contains the thread number to thaw.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
If the thread cannot be thawed, the :F.err:eF. field returns non zero value.
.section REQ_THREAD_GET_EXTRA (4)
Request to get extra information about a thread. This is arbitrary textual
data which the debugger merely displays in its thread window. The trap
file can place any information in the return message which it feels would
be useful for the user to know.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_32     thread
:eXMP.
:PC.
The :F.thread:eF. field contains the thread ID. A zero value means to get the
title string for the thread extra information. This is displayed at the
top of the thread window.
:P.
Return message:
:XMP.
    string          extra
:eXMP.
:PC.
The extra information of the thread will be returned in :F.extra:eF. field.
.endlevel
.section RFX requests
This section deals with requests that are only used by the RFX (Remote
File Xfer) program. 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
"RFX".
.beglevel
.section REQ_RFX_RENAME (0)
Request to rename a file on the debuggee's system.
:P.
Request message:
:XMP.
    access_req      req
    -------------------------
    string          from_name
    -------------------------
    string          to_name
:eXMP.
:PC.
The file whose name is indicated by the field :F.from_name:eF. will be renamed
to the name given by the field :F.to_name:eF.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
If error has occurred, the :F.err:eF. field will return the error code
number.
.section REQ_RFX_MKDIR (1)
Request to create a directory on the target (debuggee) system.
:P.
Request message:
:XMP.
    access_req      req
    ------------------------
    string          dir_name
:eXMP.
:PC.
The :F.dir_name:eF field contains the name of the directory to be created.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
If error has occurred when creating the directory, the :F.err:eF. field
will return the error code number.
.section REQ_RFX_RMDIR (2)
Request to remove a directory on the target system.
:P.
Request message:
:XMP.
    access_req      req
    ------------------------
    string          dir_name
:eXMP.
:PC.
The :F.dir_name:eF field contains the name of the directory to be removed.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
If error has occurred, the :F.err:eF. field will return the error code
number.
.section REQ_RFX_SETDRIVE (3)
Request to set the current drive on the target system.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_8      drive
:eXMP.
:PC.
The :F.drive:eF field contains the drive number to be set on the target system.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
If error has occurred, the :F.err:eF. field will return the error code
number.
.section REQ_RFX_GETDRIVE (4)
Request to get the current drive on the target system.
:P.
Request message:
:XMP.
    access_req      req
:eXMP.
:PC.
The :F.req:eF. field contains the request.
:P.
Return message:
:XMP.
    unsigned_8      drive
:eXMP.
:PC.
The :F.drive:eF field returns the current drive number on the target system.
.section REQ_RFX_SETCWD (5)
Request to set a directory on the target system.
:P.
Request message:
:XMP.
    access_req      req
    ------------------------
    string          dir_name
:eXMP.
:PC.
The :F.dir_name:eF field contains the name of the directory to be set.
:P.
Return message:
:XMP.
    trap_error      err
:eXMP.
:PC.
If error has occurred, the :F.err:eF. field will return the error code
number.
.section REQ_RFX_GETCWD (6)
Request to get the current directory name on the target system.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_8      drive
:eXMP.
:PC.
The :F.drive:eF field contains the target drive number.
:P.
Return message:
:XMP.
    trap_error      err
    --------------------------
    string          dir_name
:eXMP.
:PC.
The :F.dir_name:eF field contains the name of the directory to be set. If error
has occurred, the :F.err:eF. field will return the error code number.
.section REQ_RFX_SETDATETIME (7)
Request to set a file's date and time information on the target system.
:P.
Request message:
:XMP.
    access_req      req
    trap_fhandle    handle
    time_t          time
:eXMP.
:PC.
The :F.handle:eF. contains the file handle. The :F.time:eF. field follows
the UNIX time format. The :F.time:eF. represents the time since January 1, 1970
(UTC).
:P.
Return message:
:XMP.
    NONE
:eXMP.
.section REQ_RFX_GETDATETIME (8)
Request to get the date and time information for a file on the target system.
:P.
Request message:
:XMP.
    access_req      req
    trap_fhandle    handle
:eXMP.
:PC.
The :F.handle:eF. contains the file handle.
:P.
Return message:
:XMP.
    time_t          time
:eXMP.
:PC.
The :F.time:eF. field follows the UNIX time format. The :F.time:eF.
represents the time since January 1, 1970 (UTC).
.section REQ_RFX_GETFREESPACE (9)
Request to get the amount of free space left on the drive.
:P.
Request message:
:XMP.
    access_req      req
    unsigned_8