This document describes the protocol used between the gldb debugger and the libbugle library debugger filterset. As this is still alpha software, the protocol is subject to change at any time, and there is no guarantee that it will be possible to mix versions of gldb and libbugle. The protocol is a simple binary protocol. This makes it easier to use with the read() and write() system calls, rather than using the C stdio layer. The former are easier to use with features like select(), but are not very for text-based protocols. Values are all 32-bit except where otherwise specified. Strings are a 32-bit count followed by the characters (no explicit terminator). At present values are not byte-ordered consistently. However, they are all run through TO_NETWORK() and TO_HOST() so that these macros may later map to htonl and ntohl for network transparency. The protocol is partially asynchronous. gldb may send requests at any time, but the library will answer them as soon as possible and in the order that they are received. The library may also asynchronously send notifications to gldb. All requests begin with a request code and a request ID. Responses carry a response code and the corresponding request ID. Asynchronous responses use the request ID of the last command that (re)started program execution. The possible requests are as follows (#defines in common/protocol.h) REQ_RUN: Start running. This is sent once at start-up, after setting the initial breakpoints and similar state. Its effect is the same as REQ_CONT. REQ_CONT: Continue running. Behaviour is undefined if received while the program is already running. REQ_STEP: Like REQ_CONT, but stop at the next call. Note that if a breakpoint is set on the next call, the response is RESP_BREAK, and if an error occurs before reaching the next call then the response is RESP_BREAK_ERROR. Behaviour is undefined if received while the program is already running. REQ_BREAK: Set or clear a breakpoint on the named function. Followed by a name then either 1 or 0 (for set/clear). Response RESP_ANS has undefined value. REQ_BREAK_ERROR: Enable or disable breaking on error. Followed by either 1 or 0 (for set/clear). Response RESP_ANS has undefined value. REQ_ASYNC: Requests the program to stop at the next available point. To facilitate correct operation in the face of race conditions, this request is ignored if the program is already stopped. It does not generate an explicit response, but will cause a RESP_STOP response. REQ_QUIT: Requests that the program exit. REQ_STATE_TREE: Requests the state tree. No parameters. REQ_STATE_TREE_RAW: Requests the state tree with binary (not string) data. REQ_DATA: Requests a readback of some large chunk of state, such as a texture, framebuffer, buffer object etc. The first parameter is a type code, which determines the remaining parameters: REQ_DATA_TEXTURE: followed by id target face (only used for cube maps) level format type REQ_DATA_FRAMEBUFFER: followed by id target buffer (GL_FRONT etc) format type The following responses are defined RESP_ANS: A generic response, containing a single number. The request determines the meaning. RESP_BREAK (async): Break on a particular function (before execution). Followed by a dump of the function call. RESP_BREAK_ERROR (async): Break on an error condition (after execution) Followed by the function call (string), then the (textual) name of the error. RESP_STOP (async): A stop by request of the debugger. Same data as for RESP_BREAK. RESP_ERROR: The request was illegal. Followed by an error code (always 0 for now) and an error string. RESP_RUNNING: Sent at initialisation, in response to REQ_RUN. No extra data. This response aids in separating the responses to the initialisation commands from everything else. RESP_STATE_NODE_BEGIN RESP_STATE_NODE_END: New-style state response. BEGIN is followed by - (str) The name of the state (empty for root state), - (int32) A numeric name for the state. This is usually an object ID, or 0, or occasionally a GLenum. - (uint32) A GLenum name for the state. This is usually a pname parameter to a get function. - (str) the value (empty if there is no value) - the children, recursively (separate responses) - RESP_STATE_NODE_END response (no parameters) The entire tree will be sent as a contiguous block, without interruption from asynchronous responses. RESP_STATE_NODE_BEGIN_RAW RESP_STATE_NODE_END_RAW: Similar to RESP_STATE_NODE_BEGIN, but in response to REQ_STATE_TREE_RAW. The string field is replaced by: - (uint32) type code - (int32) number of elements, or -1 for non-array - (str) the raw data If the data could not be obtained, the number of elements is given as -2. RESP_DATA: The response depends on the subtype of the request. In every case though, the data itself is returned as a binary string. GL_PACK_ALIGNMENT is 1, other state is default, and the data is as returned by the appropriate glGet call. The first parameter is the subtype itself, for convenience, and the second is the data. The rest are REQ_DATA_TEXTURE: width, height, depth (all present even for 1D, 2D etc) REQ_DATA_FRAMEBUFFER: width, height REQ_DATA_SHADER: none Each request has a certain set of legal responses, as described below. Note that requests that start the program running (the first three) will receive asynchronous responses. REQ_RUN: RESP_RUNNING (will precede any async response) REQ_CONT: none REQ_STEP: none REQ_BREAK: RESP_ANS, RESP_ERROR REQ_BREAK_ERROR: RESP_ANS REQ_ASYNC: none REQ_STATE_TREE: RESP_STATE_BEGIN, RESP_STATE_END (multiple) REQ_STATE_TREE_RAW: RESP_STATE_BEGIN_RAW, RESP_STATE_END_RAW (multiple) REQ_QUIT: none REQ_DATA: RESP_DATA, RESP_ERROR