--- old/agent/src/os/win32/README-commands.txt Fri Sep 9 14:17:23 2011 +++ /dev/null Fri Sep 9 14:17:02 2011 @@ -1,246 +0,0 @@ -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 ::= - - Changes to ASCII mode. This affects all outgoing strings. At - startup the system is in unicode mode. - -unicode ::= - - Changes to UNICODE mode. This affects all outgoing strings. This - is the default mode upon startup. - -proclist ::= - [ []...]... - - 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 ::= - - 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 ::= - - Detaches from the given process. Attaching and detaching multiple - times during a debugging session is allowed. Detaching causes the - process to resume execution. - -libinfo ::= - [ []...
]... - - 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
::= - B - [ []...]... - - 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
|[ []] ::= - - - 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 ::= [
...] - - 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
::= - [
] - - 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
::= - - Closes a handle retrieved via the duphandle command, above. - -getcontext
::= [] - - 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
::= - - 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
::= - - [
-
-
] - - 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 ::= - [
] - - Additional entries in result for given eventCode: - - LOAD/UNLOAD_DLL_DEBUG_EVENT:
- EXCEPTION_DEBUG_EVENT:
- - Additional entries for given exceptionCode: - - EXCEPTION_ACCESS_VIOLATION:
- - - - 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 ::= - - 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 - - Exits this debugger session. - -Format specifications: - -// Data formats and example values: - ::= end of line (typically \n on Unix platforms, or \n\r on Windows) -
::= 0x12345678[9ABCDEF0] /* up to 64-bit hex value */ - ::= 5 /* up to 32-bit integer number; no leading sign */ - ::= 1 /* ASCII '0' or '1' */ - ::=
...