| 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> ... |
