--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/agent/src/os/win32/README-commands.txt	Sat Dec 01 00:00:00 2007 +0000
@@ -0,0 +1,246 @@
+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> ...