This debug server uses a largely text-based protocol, except for
certain bulk data transfer operations. All text is in single-byte
US-ASCII except for the strings returned in "proclist".

NOTE that the character '|' (vertical bar) is used as an escape
character to switch the incoming data stream to the debug server into
binary mode, so no text command may contain that character.

Commands understood:

ascii <EOL>                 ::=

    Changes to ASCII mode. This affects all outgoing strings. At
    startup the system is in unicode mode.

unicode <EOL>               ::=

    Changes to UNICODE mode. This affects all outgoing strings. This
    is the default mode upon startup.

proclist <EOL>              ::=
      <int num> [<unsigned int pid> <int charSize> <int numChars> [<binary char_t name>]...]... <EOL>

    Returns integer indicating number of processes to follow, followed
    by (pid, name) pairs. Names are given by (charSize, numChars,
    [char_t]...) tuples; charSize indicates the size of each character
    in bytes, numChars the number of characters in the string, and
    name the raw data for the string. Each individual character of the
    string, if multi-byte, is transmitted in network byte order.
    numChars and name are guaranteed to be separated by precisely one
    US-ASCII space. If process list is not available because of
    limitations of the underlying operating system, number of
    processes returned is 0.

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

    Attempts to attach to the specified process. Returns 1 if
    successful, 0 if not. Will fail if already attached or if the
    process ID does not exist. Attaching to a process causes the
    process to be suspended.

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

    Detaches from the given process. Attaching and detaching multiple
    times during a debugging session is allowed. Detaching causes the
    process to resume execution.

libinfo <EOL>               ::=
      <int numLibs> [<int charSize> <int numChars> [<binary char_t name>]... <address baseAddr>]... <EOL>

    May only be called once attached and the target process must be
    suspended; otherwise, returns 0. Returns list of the full path
    names of all of the loaded modules (including the executable
    image) in the target process, as well as the base address at which
    each module was relocated. See proclist for format of strings, but
    NOTE that charSize is ALWAYS 1 for this particular routine,
    regardless of the setting of ASCII/UNICODE.

peek <address addr> <unsigned int numBytes> <EOL> ::=
     B<binary char success>
      [<binary unsigned int len> <binary char isMapped> [<binary char data>]...]...

    NOTE that the binary portion of this message is prefixed by the
    uppercase US-ASCII letter 'B', allowing easier synchronization by
    clients. There is no data between the 'B' and the rest of the
    message.

    May only be called once attached. Reads the address space of the
    target process starting at the given address (see below for format
    specifications) and extending the given number of bytes. Whether
    the read succeeded is indicated by a single byte containing a 1 or
    0 (success or failure). If successful, the return result is given
    in a sequence of ranges. _len_, the length of each range, is
    indicated by a 32-bit unsigned integer transmitted with big-endian
    byte ordering (i.e., most significant byte first).  _isMapped_
    indicates whether the range is mapped or unmapped in the target
    process's address space, and will contain the value 1 or 0 for
    mapped or unmapped, respectively. If the range is mapped,
    _isMapped_ is followed by _data_, containing the raw binary data
    for the range. The sum of all ranges' lengths is guaranteed to be
    equivalent to the number of bytes requested.

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

    NOTE that the binary portion of this message is prefixed by the
    uppercase US-ASCII character '|' (vertical bar), allowing easier
    synchronization by the server. There is no data between the '|'
    and the rest of the message. ('B' is not used here because
    addresses can contain that letter; no alphanumeric characters are
    used because some of the parsing routines are used by the Solaris
    SA port, and in that port any alphanumeric character can show up
    as a part of a symbol being looked up.)

    May only be called once attached. Writes the address space of the
    target process starting at the given address (see below for format
    specifications), extending the given number of bytes, and
    containing the given data. The number of bytes is a 32-bit
    unsigned integer transmitted with big-endian byte ordering (i.e.,
    most significant byte first). This is followed by the raw binary
    data to be placed at that address. The number of bytes of data
    must match the number of bytes specified in the message.

    Returns true if the write succeeded; false if it failed, for
    example because a portion of the region was not mapped in the
    target address space.

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

    May only be called once attached and the target process must be
    suspended; otherwise, returns 0. If available, returns handles for
    all of the threads in the target process. These handles may be
    used as arguments to the getcontext and selectorentry
    commands. They do not need to be (and should not be) duplicated
    via the duphandle command and must not be closed via the
    closehandle command.

duphandle <address handle> <EOL> ::=
    <bool success> [<address duplicate>] <EOL>

    Duplicates a HANDLE read from the target process's address space.
    HANDLE is a Windows construct (typically typedef'd to void *).
    The returned handle should ultimately be closed via the
    closehandle command; failing to do so can cause resource leaks.

    The purpose of this command is to allow the debugger to read the
    value of a thread handle from the target process and query its
    register set and thread selector entries via the getcontext and
    selectorentry commands, below; such use implies that the target
    program has its own notion of the thread list, and further, that
    the debugger has a way of locating that thread list.

closehandle <address handle> <EOL> ::=

    Closes a handle retrieved via the duphandle command, above.

getcontext <address threadHandle> <EOL> ::= <bool success> [<context>] <EOL>
    
    Returns the context for the given thread. The handle must either
    be one of the handles returned from the threadlist command or the
    result of duplicating a thread handle out of the target process
    via the duphandle command. The target process must be suspended.

    The context is returned as a series of hex values which represent
    the following x86 registers in the following order:
      EAX, EBX, ECX, EDX, ESI, EDI, EBP, ESP, EIP, DS, ES, FS, GS,
      CS, SS, EFLAGS, DR0, DR1, DR2, DR3, DR6, DR7

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

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

    Sets the context of the given thread. The target process must be
    suspended. See the getcontext command for the ordering of the
    registers in the context.

    Even if the setcontext command succeeds, some of the bits in some
    of the registers (like the global enable bits in the debug
    registers) may be overridden by the operating system. To ensure
    the debugger's notion of the register set is up to date, it is
    recommended to follow up a setcontext with a getcontext.

selectorentry <address threadHandle> <int selector> <EOL> ::=
    <bool success>
    [<address limitLow> <address baseLow>
     <address baseMid>  <address flags1>
     <address flags2>   <address baseHi>] <EOL>

    Retrieves a descriptor table entry for the given thread and
    selector. This data structure allows conversion of a
    segment-relative address to a linear virtual address. It is most
    useful for locating the Thread Information Block for a given
    thread handle to be able to find that thread's ID, to be able to
    understand whether two different thread handles in fact refer to
    the same underlying thread.

    This command will only work on the X86 architecture and will
    return false for the success flag (with no additional information
    sent) on other architectures.

suspend                     ::=

    Suspends the target process. Must be attached to a target process.
    A process is suspended when attached to via the attach command. If
    the target process is already suspended then this command has no
    effect.

resume                      ::=

    Resumes the target process without detaching from it. Must be
    attached to a target process. After resuming a target process, the
    debugger client must be prepared to poll for events from the
    target process fairly frequently in order for execution in the
    target process to proceed normally. If the target process is
    already resumed then this command has no effect.

pollevent                   ::=
    <bool eventPresent> [<address threadHandle> <unsigned int eventCode>]

  Additional entries in result for given eventCode:

    LOAD/UNLOAD_DLL_DEBUG_EVENT: <address baseOfDLL>
    EXCEPTION_DEBUG_EVENT:       <unsigned int exceptionCode> <address faultingPC>

      Additional entries for given exceptionCode:

         EXCEPTION_ACCESS_VIOLATION: <bool wasWrite> <address faultingAddress>

    <EOL>

    Polls once to see whether a debug event has been generated by the
    target process. If none is present, returns 0 immediately.
    Otherwise, returns 1 along with a series of textual information
    about the event. The event is not cleared, and the thread resumed,
    until the continueevent command is sent, or the debugger client
    detaches from the target process.

    Typically a debugger client will suspend the target process upon
    reception of a debug event. Otherwise, it is not guaranteed that
    all threads will be suspended upon reception of a debug event, and
    any operations requiring that threads be suspended (including
    fetching the context for the thread which generated the event)
    will fail.

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

    Indicates that the current debug event has been used by the
    debugger client and that the target process should be resumed. The
    passEventToClient flag indicates whether the event should be
    propagated to the target process. Breakpoint and single-step
    events should not be propagated to the target. Returns false if
    there was no pending event, true otherwise.

exit <EOL>

    Exits this debugger session.

Format specifications:

// Data formats and example values:
<EOL>          ::=   end of line (typically \n on Unix platforms, or \n\r on Windows)
<address>      ::=   0x12345678[9ABCDEF0] /* up to 64-bit hex value */
<unsigned int> ::=   5                    /* up to 32-bit integer number; no leading sign */
<bool>         ::=   1                    /* ASCII '0' or '1' */
<context>      ::=   <address> ...