1 This debug server uses a largely text-based protocol, except for

     2 certain bulk data transfer operations. All text is in single-byte

     3 US-ASCII except for the strings returned in "proclist".

     4 

     5 NOTE that the character '|' (vertical bar) is used as an escape

     6 character to switch the incoming data stream to the debug server into

     7 binary mode, so no text command may contain that character.

     8 

     9 Commands understood:

    10 

    11 ascii <EOL>                 ::=

    12 

    13     Changes to ASCII mode. This affects all outgoing strings. At

    14     startup the system is in unicode mode.

    15 

    16 unicode <EOL>               ::=

    17 

    18     Changes to UNICODE mode. This affects all outgoing strings. This

    19     is the default mode upon startup.

    20 

    21 proclist <EOL>              ::=

    22       <int num> [<unsigned int pid> <int charSize> <int numChars> [<binary char_t name>]...]... <EOL>

    23 

    24     Returns integer indicating number of processes to follow, followed

    25     by (pid, name) pairs. Names are given by (charSize, numChars,

    26     [char_t]...) tuples; charSize indicates the size of each character

    27     in bytes, numChars the number of characters in the string, and

    28     name the raw data for the string. Each individual character of the

    29     string, if multi-byte, is transmitted in network byte order.

    30     numChars and name are guaranteed to be separated by precisely one

    31     US-ASCII space. If process list is not available because of

    32     limitations of the underlying operating system, number of

    33     processes returned is 0.

    34 

    35 attach <int pid> <EOL>      ::= <bool result> <EOL>

    36 

    37     Attempts to attach to the specified process. Returns 1 if

    38     successful, 0 if not. Will fail if already attached or if the

    39     process ID does not exist. Attaching to a process causes the

    40     process to be suspended.

    41 

    42 detach <EOL>                ::= <bool result> <EOL>

    43 

    44     Detaches from the given process. Attaching and detaching multiple

    45     times during a debugging session is allowed. Detaching causes the

    46     process to resume execution.

    47 

    48 libinfo <EOL>               ::=

    49       <int numLibs> [<int charSize> <int numChars> [<binary char_t name>]... <address baseAddr>]... <EOL>

    50 

    51     May only be called once attached and the target process must be

    52     suspended; otherwise, returns 0. Returns list of the full path

    53     names of all of the loaded modules (including the executable

    54     image) in the target process, as well as the base address at which

    55     each module was relocated. See proclist for format of strings, but

    56     NOTE that charSize is ALWAYS 1 for this particular routine,

    57     regardless of the setting of ASCII/UNICODE.

    58 

    59 peek <address addr> <unsigned int numBytes> <EOL> ::=

    60      B<binary char success>

    61       [<binary unsigned int len> <binary char isMapped> [<binary char data>]...]...

    62 

    63     NOTE that the binary portion of this message is prefixed by the

    64     uppercase US-ASCII letter 'B', allowing easier synchronization by

    65     clients. There is no data between the 'B' and the rest of the

    66     message.

    67 

    68     May only be called once attached. Reads the address space of the

    69     target process starting at the given address (see below for format

    70     specifications) and extending the given number of bytes. Whether

    71     the read succeeded is indicated by a single byte containing a 1 or

    72     0 (success or failure). If successful, the return result is given

    73     in a sequence of ranges. _len_, the length of each range, is

    74     indicated by a 32-bit unsigned integer transmitted with big-endian

    75     byte ordering (i.e., most significant byte first).  _isMapped_

    76     indicates whether the range is mapped or unmapped in the target

    77     process's address space, and will contain the value 1 or 0 for

    78     mapped or unmapped, respectively. If the range is mapped,

    79     _isMapped_ is followed by _data_, containing the raw binary data

    80     for the range. The sum of all ranges' lengths is guaranteed to be

    81     equivalent to the number of bytes requested.

    82 

    83 poke <address addr> |[<binary unsigned int len> [<binary char data>]] <EOL> ::=

    84      <bool result> <EOL>

    85 

    86     NOTE that the binary portion of this message is prefixed by the

    87     uppercase US-ASCII character '|' (vertical bar), allowing easier

    88     synchronization by the server. There is no data between the '|'

    89     and the rest of the message. ('B' is not used here because

    90     addresses can contain that letter; no alphanumeric characters are

    91     used because some of the parsing routines are used by the Solaris

    92     SA port, and in that port any alphanumeric character can show up

    93     as a part of a symbol being looked up.)

    94 

    95     May only be called once attached. Writes the address space of the

    96     target process starting at the given address (see below for format

    97     specifications), extending the given number of bytes, and

    98     containing the given data. The number of bytes is a 32-bit

    99     unsigned integer transmitted with big-endian byte ordering (i.e.,

   100     most significant byte first). This is followed by the raw binary

   101     data to be placed at that address. The number of bytes of data

   102     must match the number of bytes specified in the message.

   103 

   104     Returns true if the write succeeded; false if it failed, for

   105     example because a portion of the region was not mapped in the

   106     target address space.

   107 

   108 threadlist <EOL>            ::= <int numThreads> [<address threadHandle>...] <EOL>

   109 

   110     May only be called once attached and the target process must be

   111     suspended; otherwise, returns 0. If available, returns handles for

   112     all of the threads in the target process. These handles may be

   113     used as arguments to the getcontext and selectorentry

   114     commands. They do not need to be (and should not be) duplicated

   115     via the duphandle command and must not be closed via the

   116     closehandle command.

   117 

   118 duphandle <address handle> <EOL> ::=

   119     <bool success> [<address duplicate>] <EOL>

   120 

   121     Duplicates a HANDLE read from the target process's address space.

   122     HANDLE is a Windows construct (typically typedef'd to void *).

   123     The returned handle should ultimately be closed via the

   124     closehandle command; failing to do so can cause resource leaks.

   125 

   126     The purpose of this command is to allow the debugger to read the

   127     value of a thread handle from the target process and query its

   128     register set and thread selector entries via the getcontext and

   129     selectorentry commands, below; such use implies that the target

   130     program has its own notion of the thread list, and further, that

   131     the debugger has a way of locating that thread list.

   132 

   133 closehandle <address handle> <EOL> ::=

   134 

   135     Closes a handle retrieved via the duphandle command, above.

   136 

   137 getcontext <address threadHandle> <EOL> ::= <bool success> [<context>] <EOL>

   138     

   139     Returns the context for the given thread. The handle must either

   140     be one of the handles returned from the threadlist command or the

   141     result of duplicating a thread handle out of the target process

   142     via the duphandle command. The target process must be suspended.

   143 

   144     The context is returned as a series of hex values which represent

   145     the following x86 registers in the following order:

   146       EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, EIP, DS, ES, FS, GS,

   147       CS, SS, EFLAGS, DR0, DR1, DR2, DR3, DR6, DR7

   148 

   149     FIXME: needs to be generalized and/or specified for other

   150     architectures.

   151 

   152 setcontext <address threadHandle> <context> ::= <bool success> <EOL>

   153 

   154     Sets the context of the given thread. The target process must be

   155     suspended. See the getcontext command for the ordering of the

   156     registers in the context.

   157 

   158     Even if the setcontext command succeeds, some of the bits in some

   159     of the registers (like the global enable bits in the debug

   160     registers) may be overridden by the operating system. To ensure

   161     the debugger's notion of the register set is up to date, it is

   162     recommended to follow up a setcontext with a getcontext.

   163 

   164 selectorentry <address threadHandle> <int selector> <EOL> ::=

   165     <bool success>

   166     [<address limitLow> <address baseLow>

   167      <address baseMid>  <address flags1>

   168      <address flags2>   <address baseHi>] <EOL>

   169 

   170     Retrieves a descriptor table entry for the given thread and

   171     selector. This data structure allows conversion of a

   172     segment-relative address to a linear virtual address. It is most

   173     useful for locating the Thread Information Block for a given

   174     thread handle to be able to find that thread's ID, to be able to

   175     understand whether two different thread handles in fact refer to

   176     the same underlying thread.

   177 

   178     This command will only work on the X86 architecture and will

   179     return false for the success flag (with no additional information

   180     sent) on other architectures.

   181 

   182 suspend                     ::=

   183 

   184     Suspends the target process. Must be attached to a target process.

   185     A process is suspended when attached to via the attach command. If

   186     the target process is already suspended then this command has no

   187     effect.

   188 

   189 resume                      ::=

   190 

   191     Resumes the target process without detaching from it. Must be

   192     attached to a target process. After resuming a target process, the

   193     debugger client must be prepared to poll for events from the

   194     target process fairly frequently in order for execution in the

   195     target process to proceed normally. If the target process is

   196     already resumed then this command has no effect.

   197 

   198 pollevent                   ::=

   199     <bool eventPresent> [<address threadHandle> <unsigned int eventCode>]

   200 

   201   Additional entries in result for given eventCode:

   202 

   203     LOAD/UNLOAD_DLL_DEBUG_EVENT: <address baseOfDLL>

   204     EXCEPTION_DEBUG_EVENT:       <unsigned int exceptionCode> <address faultingPC>

   205 

   206       Additional entries for given exceptionCode:

   207 

   208          EXCEPTION_ACCESS_VIOLATION: <bool wasWrite> <address faultingAddress>

   209 

   210     <EOL>

   211 

   212     Polls once to see whether a debug event has been generated by the

   213     target process. If none is present, returns 0 immediately.

   214     Otherwise, returns 1 along with a series of textual information

   215     about the event. The event is not cleared, and the thread resumed,

   216     until the continueevent command is sent, or the debugger client

   217     detaches from the target process.

   218 

   219     Typically a debugger client will suspend the target process upon

   220     reception of a debug event. Otherwise, it is not guaranteed that

   221     all threads will be suspended upon reception of a debug event, and

   222     any operations requiring that threads be suspended (including

   223     fetching the context for the thread which generated the event)

   224     will fail.

   225 

   226 continueevent <bool passEventToClient> ::= <bool success> <EOL>

   227 

   228     Indicates that the current debug event has been used by the

   229     debugger client and that the target process should be resumed. The

   230     passEventToClient flag indicates whether the event should be

   231     propagated to the target process. Breakpoint and single-step

   232     events should not be propagated to the target. Returns false if

   233     there was no pending event, true otherwise.

   234 

   235 exit <EOL>

   236 

   237     Exits this debugger session.

   238 

   239 Format specifications:

   240 

   241 // Data formats and example values:

   242 <EOL>          ::=   end of line (typically \n on Unix platforms, or \n\r on Windows)

   243 <address>      ::=   0x12345678[9ABCDEF0] /* up to 64-bit hex value */

   244 <unsigned int> ::=   5                    /* up to 32-bit integer number; no leading sign */

   245 <bool>         ::=   1                    /* ASCII '0' or '1' */

   246 <context>      ::=   <address> ...