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".
   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.
   9 Commands understood:
  11 ascii <EOL>                 ::=
  13     Changes to ASCII mode. This affects all outgoing strings. At
  14     startup the system is in unicode mode.
  16 unicode <EOL>               ::=
  18     Changes to UNICODE mode. This affects all outgoing strings. This
  19     is the default mode upon startup.
  21 proclist <EOL>              ::=
  22       <int num> [<unsigned int pid> <int charSize> <int numChars> [<binary char_t name>]...]... <EOL>
  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.
  35 attach <int pid> <EOL>      ::= <bool result> <EOL>
  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.
  42 detach <EOL>                ::= <bool result> <EOL>
  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.
  48 libinfo <EOL>               ::=
  49       <int numLibs> [<int charSize> <int numChars> [<binary char_t name>]... <address baseAddr>]... <EOL>
  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.
  59 peek <address addr> <unsigned int numBytes> <EOL> ::=
  60      B<binary char success>
  61       [<binary unsigned int len> <binary char isMapped> [<binary char data>]...]...
  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.
  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.
  83 poke <address addr> |[<binary unsigned int len> [<binary char data>]] <EOL> ::=
  84      <bool result> <EOL>
  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.)
  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.
 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.
 108 threadlist <EOL>            ::= <int numThreads> [<address threadHandle>...] <EOL>
 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.
 118 duphandle <address handle> <EOL> ::=
 119     <bool success> [<address duplicate>] <EOL>
 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.
 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.
 133 closehandle <address handle> <EOL> ::=
 135     Closes a handle retrieved via the duphandle command, above.
 137 getcontext <address threadHandle> <EOL> ::= <bool success> [<context>] <EOL>
 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.
 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
 149     FIXME: needs to be generalized and/or specified for other
 150     architectures.
 152 setcontext <address threadHandle> <context> ::= <bool success> <EOL>
 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.
 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.
 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>
 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.
 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.
 182 suspend                     ::=
 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.
 189 resume                      ::=
 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.
 198 pollevent                   ::=
 199     <bool eventPresent> [<address threadHandle> <unsigned int eventCode>]
 201   Additional entries in result for given eventCode:
 203     LOAD/UNLOAD_DLL_DEBUG_EVENT: <address baseOfDLL>
 204     EXCEPTION_DEBUG_EVENT:       <unsigned int exceptionCode> <address faultingPC>
 206       Additional entries for given exceptionCode:
 208          EXCEPTION_ACCESS_VIOLATION: <bool wasWrite> <address faultingAddress>
 210     <EOL>
 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.
 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.
 226 continueevent <bool passEventToClient> ::= <bool success> <EOL>
 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.
 235 exit <EOL>
 237     Exits this debugger session.
 239 Format specifications:
 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> ...