Scalable Remote Debugger Protocol - Revision history

Parasyte: Update protocol to HTTPS

2020-12-28T05:23:24Z

Update protocol to HTTPS

Parasyte: Fix external links

2020-12-28T05:19:54Z

Fix external links

Parasyte: /* info() */

2010-01-13T05:01:36Z

‎info()

Parasyte: /* Command Reference */

2010-01-13T04:59:33Z

‎Command Reference

Parasyte: /* Requests, Responses, Alerts */

2010-01-13T03:24:42Z

‎Requests, Responses, Alerts

Parasyte: /* Underlying Protocols */

2010-01-13T03:21:40Z

‎Underlying Protocols

Parasyte: /* Operation Groups */

2010-01-13T03:08:17Z

‎Operation Groups

Parasyte: /* Operation Groups */

2010-01-13T03:06:54Z

‎Operation Groups

Parasyte: /* Protocol Packet Data Structure */

2010-01-13T03:00:59Z

‎Protocol Packet Data Structure

Parasyte: /* Protocol Packet Data Structure */

2010-01-13T02:55:05Z

‎Protocol Packet Data Structure

@@ Line 25: / Line 25: @@
 This section represents my ([[User:Parasyte|Parasyte]]) own personal opinions and ideas, and should not be taken as advocacy for standardization.
-One of the main goals of developing a "universal" protocol for debugging is that it must be usable everywhere; in small embedded devices, and some of the most powerful machines in the world. This kind of flexibility must be designed around multiple layers of abstraction. See [http://en.wikipedia.org/wiki/OSI_Model OSI Model] and [http://en.wikipedia.org/wiki/Internet_Protocol_Suite Internet Protocol Suite] for examples of abstraction layers used in communications technologies.
+One of the main goals of developing a "universal" protocol for debugging is that it must be usable everywhere; in small embedded devices, and some of the most powerful machines in the world. This kind of flexibility must be designed around multiple layers of abstraction. See [https://en.wikipedia.org/wiki/OSI_Model OSI Model] and [https://en.wikipedia.org/wiki/Internet_Protocol_Suite Internet Protocol Suite] for examples of abstraction layers used in communications technologies.
 At the lowest layer, you find the ''wire''; the physical means of transmitting information over distance. For our purposes, we should not limit ourselves to a single wire. Instead, we should allow the use of multiple wires, user-selectable, but never more than one at a time.
@@ Line 39: / Line 39: @@
 Thinking about this led to a conundrum; If we support multiple wires, we have to support multiple transport protocols which are compatible with those wires. And if we support multiple transport protocols, we have to know which one our target implements. To make the API as simple as possible, we must not force clients to choose from configurable options (for a bad example) that requires a large degree of changes for each different type of connection made. How do we simplify the API so that a user can just plain connect without doing any pre-setup work?
-Answer: The [http://en.wikipedia.org/wiki/URI_scheme URI scheme]. The unfortunate downside to this solution is that it is undesired to use URI schemes without registering them with IANA. However, an argument could be made that these schemes would not be used for general network/internet communication. A few popular examples of similarly non-networked schemes are the file: and about: URI schemes. (The exception here is that at least one physical layer (LAN) could be used for over-the-internet communication; but this has great benefits in its own right.)
+Answer: The [https://en.wikipedia.org/wiki/URI_scheme URI scheme]. The unfortunate downside to this solution is that it is undesired to use URI schemes without registering them with IANA. However, an argument could be made that these schemes would not be used for general network/internet communication. A few popular examples of similarly non-networked schemes are the file: and about: URI schemes. (The exception here is that at least one physical layer (LAN) could be used for over-the-internet communication; but this has great benefits in its own right.)
 ===Example URI Schemes===
@@ Line 117: / Line 117: @@
 ===Underlying Protocols===
-There are no reservations on any underlying protocols (protocols used to move data from the client to the server, and back again -- SRDP is not one of these protocols). The only requirement is that they provide hand-shaking (transmission control), sequential ordering of packet data arrival, and data integrity checking. Some examples of suitable underlying protocols include [http://en.wikipedia.org/wiki/Internet_Protocol_Suite TCP/UDP/IP], and [http://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter UART].
+There are no reservations on any underlying protocols (protocols used to move data from the client to the server, and back again -- SRDP is not one of these protocols). The only requirement is that they provide hand-shaking (transmission control), sequential ordering of packet data arrival, and data integrity checking. Some examples of suitable underlying protocols include [https://en.wikipedia.org/wiki/Internet_Protocol_Suite TCP/UDP/IP], and [https://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter UART].
 The initial reference implementation will use TCP/IP for remote connections. For local-listening servers, the reference implementation will use UNIX Domain Sockets on UNIX-like operating systems, and Named Pipes on Windows.
@@ Line 154: / Line 154: @@
 ===Protocol Packet Data Structure===
-The "goals" section outlines the major features which formed the following data structure. Inspiration comes mainly from [http://en.wikipedia.org/wiki/JSON JSON], the JavaScript Object Notation. As JSON is a serialization [text format] of JavaScript objects, the SRDP data structure is a serialization of the data being transmitted.
+The "goals" section outlines the major features which formed the following data structure. Inspiration comes mainly from [https://en.wikipedia.org/wiki/JSON JSON], the JavaScript Object Notation. As JSON is a serialization [text format] of JavaScript objects, the SRDP data structure is a serialization of the data being transmitted.
-The structure also shares some inspiration from [http://en.wikipedia.org/wiki/Remote_procedure_call RPC]; An example is that your client may want to read work RAM from the target. The SRDP request for "read memory" is technically similar to remotely running a "read memory" function on the server, invoked by the client. For this reason, each SRDP packet contains one or more "arguments" which you could imagine are passed directly to a plain old function.
+The structure also shares some inspiration from [https://en.wikipedia.org/wiki/Remote_procedure_call RPC]; An example is that your client may want to read work RAM from the target. The SRDP request for "read memory" is technically similar to remotely running a "read memory" function on the server, invoked by the client. For this reason, each SRDP packet contains one or more "arguments" which you could imagine are passed directly to a plain old function.
 Each packet is sent as a series of 8-bit bytes. Packets are broken down into a "request/response/alert" name (called a command), encapsulating a series of "arguments". You can think of it like a C function call. The "info" command, for example, requests information about the target machine architecture; it requires no arguments. The info command looks like this, and is a complete and valid SRDP packet:
@@ Line 164: / Line 164: @@
 Each argument has a name (made of one or more characters: alpha-numeric, underscore (_), or hyphen (-). The argument name is followed by a colon (:) and then a single byte representing the data type of the argument, then an equals sign (=) and the argument's value. All arguments are separated with a comma (,).
-The argument syntax is similar to that of [http://en.wikipedia.org/wiki/Cascading_Style_Sheets CSS]. In pseudo-form, it looks something like this:
+The argument syntax is similar to that of [https://en.wikipedia.org/wiki/Cascading_Style_Sheets CSS]. In pseudo-form, it looks something like this:
 {| style="border-collapse: collapse; width: 100%;"
@@ Line 185: / Line 185: @@
 | style="border: 1px solid #000000;" | s
 | style="border: 1px solid #000000;" | Signed Number
-| style="border: 1px solid #000000;" | Any negative integer, encoded as a [http://en.wikipedia.org/wiki/Signed_number_representations#Ones.27_complement one's complement] VLI
+| style="border: 1px solid #000000;" | Any negative integer, encoded as a [https://en.wikipedia.org/wiki/Signed_number_representations#Ones.27_complement one's complement] VLI
 |-
 | style="border: 1px solid #000000;" | f
 | style="border: 1px solid #000000;" | Floating Point Number
-| style="border: 1px solid #000000;" | Any non-integer number, Infinity, or [http://en.wikipedia.org/wiki/NaN NaN], encoded as a null-terminated UTF-8 string, or null-terminated UTF-16 or UTF-32 string with BOM; To be decoded by [http://en.wikipedia.org/wiki/Scanf#Format_string_specifications sscanf]
+| style="border: 1px solid #000000;" | Any non-integer number, Infinity, or [https://en.wikipedia.org/wiki/NaN NaN], encoded as a null-terminated UTF-8 string, or null-terminated UTF-16 or UTF-32 string with BOM; To be decoded by [https://en.wikipedia.org/wiki/Scanf#Format_string_specifications sscanf]
 |-
 | style="border: 1px solid #000000;" | a
@@ Line 197: / Line 197: @@
 | style="border: 1px solid #000000;" | c
 | style="border: 1px solid #000000;" | Compressed Array
-| style="border: 1px solid #000000;" | Byte-array (binary blob) with [http://en.wikipedia.org/wiki/Run-length_encoding RLE] compression. See [[#Compressed Array Data Type]]
+| style="border: 1px solid #000000;" | Byte-array (binary blob) with [https://en.wikipedia.org/wiki/Run-length_encoding RLE] compression. See [[#Compressed Array Data Type]]
 |-
 | style="border: 1px solid #000000;" | t
 | style="border: 1px solid #000000;" | Text
-| style="border: 1px solid #000000;" | Null-terminated UTF-8 string without [http://en.wikipedia.org/wiki/Byte-order_mark BOM], or null-terminated UTF-16 or UTF-32 string with BOM
+| style="border: 1px solid #000000;" | Null-terminated UTF-8 string without [https://en.wikipedia.org/wiki/Byte-order_mark BOM], or null-terminated UTF-16 or UTF-32 string with BOM
 |}

@@ Line 5: / Line 5: @@
 These references are listed in order of relevance; most relevant first.
-# [ftp://ftp.rfc-editor.org/in-notes/rfc909.txt RFC-909: Loader Debugger Protocol]
+# [https://tools.ietf.org/html/rfc909 RFC-909: Loader Debugger Protocol]
-# [http://sourceware.org/gdb/download/onlinedocs/gdb_33.html GDB Remote Serial Protocol]
+# [https://sourceware.org/gdb/onlinedocs/gdb/Remote-Protocol.html GDB Remote Serial Protocol]
-# [ftp://ftp.rfc-editor.org/in-notes/rfc643.txt RFC-643: Network Debugging Protocol]
+# [https://tools.ietf.org/html/rfc643 RFC-643: Network Debugging Protocol]
-# [ftp://ftp.rfc-editor.org/in-notes/ien/ien158.txt IEN-158: XNET Debugging Protocol]
+# [http://networksorcery.com/enp/ien/ien158.txt IEN-158: XNET Debugging Protocol]
-# [http://www.xdebug.org/docs-dbgp.php DBGp: A common debugger protocol for languages and debugger UI communication]
+# [https://xdebug.org/docs/dbgp DBGp: A common debugger protocol for languages and debugger UI communication]
 The relevancy I've determined for this list is due to interest in these specs, as well as potential generic uses and protocol extension.

@@ Line 419: / Line 419: @@
 * '''<u>SGB</u>''': Nintendo Super GameBoy
 * '''<u>CDI</u>''': Philips CD-i
 * '''<u>PS3</u>''': Sony Playstation 3
 * '''<u>SV</u>''': SuperVision
 ===Proposal Comments===

@@ Line 346: / Line 346: @@
 |}
-===Comments===
+===Command Reference===
 The "Protocol Goals" have lead much of the motivation for developing this proposal. This presents what seems to be several very strange choices, at first glance. The choice of representing floating point numbers as a string of text seems extremely odd, until you consider that using the target-native floating point data format would make no sense when sending that data to a remote client (which is most likely running on a different architecture, and may have totally different native floating point formats). In order to express floating points with arbitrary precision in a data format-agnostic way, it is necessary to use a non-native format like text.

← Older revision		Revision as of 03:24, 13 January 2010
Line 147:		Line 147:

	Not all alerts are initiated by requests from clients, but most will be. Log messages are typically spewed by programs without explicit requests; SRDP can allow listening for and capturing these messages.		Not all alerts are initiated by requests from clients, but most will be. Log messages are typically spewed by programs without explicit requests; SRDP can allow listening for and capturing these messages.
		+
		+	====Commands====
		+
		+	The all-encompassing term for requests, responses and alerts is "commands". Any time a "command" is mentioned, it refers to any combination of requests, responses, or alerts.

	===Protocol Packet Data Structure===		===Protocol Packet Data Structure===

← Older revision		Revision as of 03:21, 13 January 2010
Line 120:		Line 120:

	The initial reference implementation will use TCP/IP for remote connections. For local-listening servers, the reference implementation will use UNIX Domain Sockets on UNIX-like operating systems, and Named Pipes on Windows.		The initial reference implementation will use TCP/IP for remote connections. For local-listening servers, the reference implementation will use UNIX Domain Sockets on UNIX-like operating systems, and Named Pipes on Windows.
		+
		+	===Requests, Responses, Alerts===
		+
		+	Packets are given different names depending on their transmission direction (client -> server, or server -> client) and intended recipient (server, specific client, or all clients).
		+
		+	Response, requests, and alerts must have a unique identifier associated with them. This will allow clients and servers to stay in sync, knowing which responses are for which requests, for example.
		+
		+	====Requests====
		+
		+	A packet is called a request if it is from a client to the server. The name "request" comes from the idea that the client is requesting information or a specific action to be performed by the server.
		+
		+	====Responses====
		+
		+	Responses are packets from a server to a specific client. Responses are always sent in response to a request (hence the name). However, not all requests are required to send responses (which is why "requests" are not called "commands"). Responses are only sent to the client which initiated the specific request being handled.
		+
		+	====Alerts====
		+
		+	An alert is a special type of response (a packet from the server to clients); an alert is sent to all connected/listening clients. This is synonymous with network "broadcast" packets, and it useful for notifying all clients of information they might like to know.
		+
		+	A few examples of information that all clients might like to know are:
		+
		+	* Breakpoint hits
		+	* Pausing/resuming execution
		+	* Resets
		+	* Debugging messages (log messages)
		+
		+	Not all alerts are initiated by requests from clients, but most will be. Log messages are typically spewed by programs without explicit requests; SRDP can allow listening for and capturing these messages.

	===Protocol Packet Data Structure===		===Protocol Packet Data Structure===

@@ Line 82: / Line 82: @@
 |-
 | style="border: 1px solid #000000;" | 1)
-| style="border: 1px solid #000000;" | Diagnostics (Connect, Disconnect, Info, Ping/Pong, Reset, ...)
+| style="border: 1px solid #000000;" | Diagnostics (Info, Ping/Pong, Reset, ...)
 |-
 | style="border: 1px solid #000000;" | 2)

@@ Line 82: / Line 82: @@
 |-
 | style="border: 1px solid #000000;" | 1)
-| style="border: 1px solid #000000;" | Diagnostics (Init, Shutdown, Ping/Pong, Reset, ...)
+| style="border: 1px solid #000000;" | Diagnostics (Connect, Disconnect, Info, Ping/Pong, Reset, ...)
 |-
 | style="border: 1px solid #000000;" | 2)
-| style="border: 1px solid #000000;" | CPU handling (Get/set process states, register read/write, arbitrary code execution, general CPU control, ...)
+| style="border: 1px solid #000000;" | CPU handling (Register read/write, Arbitrary code execution, General CPU control, General process/thread control...)
 |-
 | style="border: 1px solid #000000;" | 3)
-| style="border: 1px solid #000000;" | Memory handling (read, write, address conversion, hardware I/O, cache control, ...)
+| style="border: 1px solid #000000;" | Memory handling (Read, Write, Address conversion, Hardware I/O, Cache control, ...)
 |-
 | style="border: 1px solid #000000;" | 4)
-| style="border: 1px solid #000000;" | Breakpoint handling (add, delete, edit, get, ...)
+| style="border: 1px solid #000000;" | Breakpoint handling (Add, Delete, Edit, Get, ...)
 |-
 | style="border: 1px solid #000000;" | 5)
-| style="border: 1px solid #000000;" | Stream handling (stdin/stdout/stderr, debugger-specific messages, ...)
+| style="border: 1px solid #000000;" | Stream handling (stdin/stdout/stderr, Debugger-specific messages, ...)
 |-
 | style="border: 1px solid #000000;" | 6)
-| style="border: 1px solid #000000;" | Vendor-specific (custom command sets, should be discouraged unless absolutely necessary)
+| style="border: 1px solid #000000;" | Vendor-specific (Custom command sets; should be discouraged unless absolutely necessary)
 |}

@@ Line 127: / Line 127: @@
 The structure also shares some inspiration from [http://en.wikipedia.org/wiki/Remote_procedure_call RPC]; An example is that your client may want to read work RAM from the target. The SRDP request for "read memory" is technically similar to remotely running a "read memory" function on the server, invoked by the client. For this reason, each SRDP packet contains one or more "arguments" which you could imagine are passed directly to a plain old function.
-Each packet is sent as a series of 8-bit bytes. Packets are broken down into a series of "arguments". Each argument has a name (made of one or more characters: alpha-numeric, underscore (_), or hyphen (-). The argument name is followed by a colon (:) and then a single byte representing the data type of the argument, then an equals sign (=) and the argument's value. All arguments are "closed" with a semi-colon (;).
+Each packet is sent as a series of 8-bit bytes. Packets are broken down into a series of "arguments". Each argument has a name (made of one or more characters: alpha-numeric, underscore (_), or hyphen (-). The argument name is followed by a colon (:) and then a single byte representing the data type of the argument, then an equals sign (=) and the argument's value. All arguments are separated with a comma (,).
 The argument syntax is similar to that of [http://en.wikipedia.org/wiki/Cascading_Style_Sheets CSS]. In pseudo-form, it looks something like this:
@@ Line 133: / Line 133: @@
 {| style="border-collapse: collapse; width: 100%;"
 |-
-| style="border: 1px solid #000000;" | {name}:{type}={value};
+| style="border: 1px solid #000000;" | {name}:{type}={value}
 |}
@@ Line 173: / Line 173: @@
 {| style="border-collapse: collapse; width: 100%;"
 |-
-| style="border: 1px solid #000000;" | msg:t=Hello, World!␀;
+| style="border: 1px solid #000000;" | msg:t=Hello, World!␀
 |-
-| style="border: 1px solid #000000;" | num:n=□;
+| style="border: 1px solid #000000;" | num:n=□
 |-
-| style="border: 1px solid #000000;" | pi:f=3.141592␀;
+| style="border: 1px solid #000000;" | pi:f=3.141592␀
 |-
-| style="border: 1px solid #000000;" | ram_dump:a=□■■■■;
+| style="border: 1px solid #000000;" | ram_dump:a=□■■■■
 |-
-| style="border: 1px solid #000000;" | my-compressed-data:c=□□■■■■□■□■■■;
+| style="border: 1px solid #000000;" | my-compressed-data:c=□□■■■■□■□■■■
 |}
@@ Line 194: / Line 194: @@
 {| style="border-collapse: collapse; width: 100%;"
 |-
-| style="border: 1px solid #000000; padding: 10px;" | '''''One suggestion is making this data-type optional, and changing this spec to use a standard library, like zlib. In this way, slow machines with few resources can adhere to the SRDP spec without wasting precious footprint space and computational power implementing such "heavy" libraries.'''''
+| style="border: 1px solid #000000; padding: 10px;" | '''''One suggestion is making this data-type optional, and changing this spec to use a standard library, like zlib. In this way, slow machines with few resources can adhere to the SRDP spec without wasting precious footprint space and computational power implementing such "heavy" libraries.
 |}
@@ Line 249: / Line 251: @@
 {| style="border-collapse: collapse; width: 100%;"
 |-
-| style="border: 1px solid #000000;" | {name}:[...];
+| style="border: 1px solid #000000;" | {name}:[...]
 |}
@@ Line 257: / Line 259: @@
 |-
 | style="border: 1px solid #000000;" | <tt>cpu:[
-:arch:t=ARM␀;
+:arch:t=ARM␀,
-:name:t=ARM946E-S␀;
+:name:t=ARM946E-S␀
-];</tt>
+]</tt>
 |}
 (Note the white-space is for readability only; it is not meant to be transferred as part of the protocol data.)
@@ Line 267: / Line 269: @@
 But there are also times when you will want your server to send that same information for two [or more] CPU architectures on a single target. Some platforms may have multiple CPUs, each with its own individual set of resources (memory maps and the like), as well as shared resources between the CPUs. For this, the packet data structure needs a more advanced method of communicating these kinds of details.
-For this case, you can optionally create arrays of objects by including a comma (,) after the closing square bracket, followed by another series of arguments enclosed in their own square brackets, ''ad infinitum''.
+For this case, you can optionally create arrays of objects by including a comma (,) after the closing square bracket, followed by another series of arguments enclosed in their own square brackets, ''ad infinitum''. In other words, any leading object definitions without explicit names will be treated as additional array elements for the previously named object.
 {| style="border-collapse: collapse; width: 100%;"
 |-
 | style="border: 1px solid #000000;" | <tt>cpu:[
-:arch:t=ARM␀;
+:arch:t=ARM␀,
-:name:t=ARM946E-S␀;
+:name:t=ARM946E-S␀
 ],<br/>
+[
-:arch:t=ARM␀;
+:arch:t=ARM␀,
-:name:t=ARM7TDMI␀;
+:name:t=ARM7TDMI␀
-];</tt>
+]</tt>
 |}
@@ Line 288: / Line 290: @@
 |-
 | style="border: 1px solid #000000;" | <tt>memory:[
-:name:t=Work RAM␀;
+:name:t=Work RAM␀,
 :range:[
-::start:n=□;
+::start:n=□,
-::end:n=□;
+::end:n=□
 :],<br/>
 :[
-::start:n=□;
+::start:n=□,
-::end:n=□;
+::end:n=□
-:];
+:],
-:flags:t=RWX␀;
+:flags:t=RWX␀
 ],<br/>
+[
-:name:t=ROM␀;
+:name:t=ROM␀,
 :range:[
-::start:n=□;
+::start:n=□,
-::end:n=□;
+::end:n=□
-:];
+:],
-:flags:t=RX␀;
+:flags:t=RX␀
-];</tt>
+]</tt>
 |}