Mercurial > hg > truffle
view agent/src/os/win32/README-commands.txt @ 2585:3e0e65161345
new node layout: Op2
author | Lukas Stadler <lukas.stadler@jku.at> |
---|---|
date | Thu, 05 May 2011 14:12:19 +0200 |
parents | a61af66fc99e |
children |
line wrap: on
line source
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> ...