diff --git a/docs/DEVELOPER/debugging/socket-based-debugger.md b/docs/DEVELOPER/debugging/socket-based-debugger.md index 3c6200ea..caa50693 100644 --- a/docs/DEVELOPER/debugging/socket-based-debugger.md +++ b/docs/DEVELOPER/debugging/socket-based-debugger.md @@ -65,72 +65,78 @@ struct HandshakeFromDVP { }; ``` -{` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
magic_numberuint64The Roku Brightscript debug protocol identifier, which is the following 64-bit value :0x0067756265647362LU.

This is equal to 29120988069524322LU or the following little-endian value: b'bsdebug\0.
protocol_major_version
protocol_minor_version
protocol_patch_version		uint32Each Roku OS release supports only a single version of the Roku Brightscript debug protocol:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Roku OSSupported Debug Protocol Version
Roku OS 14.13.3.0
[Roku OS 12.0](doc:release-notes#roku-os-120)3.2.0
[Roku OS 11.5](doc:release-notes#roku-os-115)3.1.0
[Roku OS 11.0](doc:release-notes#roku-os-110)3.0.0
[Roku OS 9.3](doc:release-notes#roku-os-93), [9.4](doc:release-notes#roku-os-94), [10.0](doc:release-notes#roku-os-100), [10.5](doc:release-notes#roku-os-105)2.0.0
[Roku OS 9.2](doc:release-notes#roku-os-92)1.0.1

The debugger client must be updated to the protocol version number or disconnect. A change in the major version number indicates that changes that are not backwards-compatible have been made since the previous release.
remaining_packet_lengthuint32The length in bytes of the remaining data, including the remaining_packet_length itself. The debugger client must read this number of bytes.

As of BrightScript debug protocol 3.0.0 ([Roku OS 11.0](doc:release-notes#roku-os-110)), all packets from the debugging target include a packet_length. The length is always in bytes, and includes the packet_length field, itself.

This field avoids the need for changes to the major version of the protocol because it allows a debugger client to read past data it does not understand and is not critical to debugger operations.

The debug target may intentionally send a packet_length longer than the actual data, with a small number of trailing padding bytes to complete the length. Clients must read the entire packet_length before expecting the next packet.
platform_revision_timestampint64A platform-specific implementation timestamp (in milliseconds since epoch [1970-01-01T00:00:00.000Z]).

As of BrightScript debug protocol 3.0.0 ([Roku OS 11.0](doc:release-notes#roku-os-110)), a timestamp is sent to the debugger client in the initial handshake. This timestamp is platform-specific data that is included in the system software of the platform being debugged. It is changed by the platform's vendor when there is any change that affects the behavior of the debugger.

The value can be used in manners similar to a build number, and is primarily used to differentiate between pre-release builds of the platform being debugged.
FieldTypeDescription
magic_numberuint64The Roku Brightscript debug protocol identifier, which is the following 64-bit value :0x0067756265647362LU.

This is equal to 29120988069524322LU or the following little-endian value: b'bsdebug\0.
protocol_major_version
protocol_minor_version
protocol_patch_version		uint32 + Each Roku OS release supports only a single version of the Roku Brightscript debug protocol: +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Roku OSSupported Debug Protocol Version
Roku OS 14.13.3.0
[Roku OS 12.0](doc:release-notes#roku-os-120)3.2.0
[Roku OS 11.5](doc:release-notes#roku-os-115)3.1.0
[Roku OS 11.0](doc:release-notes#roku-os-110)3.0.0
[Roku OS 9.3](doc:release-notes#roku-os-93), [9.4](doc:release-notes#roku-os-94), [10.0](doc:release-notes#roku-os-100), [10.5](doc:release-notes#roku-os-105)2.0.0
[Roku OS 9.2](doc:release-notes#roku-os-92)1.0.1
+
+
+ The debugger client must be updated to the protocol version number or disconnect. A change in the major version number indicates that changes that are not backwards-compatible have been made since the previous release. +
remaining_packet_lengthuint32The length in bytes of the remaining data, including the remaining_packet_length itself. The debugger client must read this number of bytes.

As of BrightScript debug protocol 3.0.0 ([Roku OS 11.0](doc:release-notes#roku-os-110)), all packets from the debugging target include a packet_length. The length is always in bytes, and includes the packet_length field, itself.

This field avoids the need for changes to the major version of the protocol because it allows a debugger client to read past data it does not understand and is not critical to debugger operations.

The debug target may intentionally send a packet_length longer than the actual data, with a small number of trailing padding bytes to complete the length. Clients must read the entire packet_length before expecting the next packet.
platform_revision_timestampint64A platform-specific implementation timestamp (in milliseconds since epoch \[1970-01-01T00:00:00.000Z]).

As of BrightScript debug protocol 3.0.0 ([Roku OS 11.0](doc:release-notes#roku-os-110)), a timestamp is sent to the debugger client in the initial handshake. This timestamp is platform-specific data that is included in the system software of the platform being debugged. It is changed by the platform's vendor when there is any change that affects the behavior of the debugger.

The value can be used in manners similar to a build number, and is primarily used to differentiate between pre-release builds of the platform being debugged.
-`} The behavior after the handshake has been executed, depends on the version of the BrightScript debug protocol being used: @@ -150,100 +156,106 @@ struct DebuggerRequest { }; ``` -{` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
packet_lengthuint32The size of the packet to be sent.
Example: (4 + 4 + 4 + sizeof(ARGUMENTS))
request_iduint32The ID of the debugger request (must be >=1). This ID is included in the debugger response.
command_codeuint32An enum representing the debugging command being sent, which may be one of the following values:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeCommand
1STOP
2CONTINUE
3THREADS
4STACKTRACE
5VARIABLES
6STEP
7ADD_BREAKPOINTS
8LIST_BREAKPOINTS

(As of [Roku OS 11.5](doc:release-notes#roku-os-115), this command supports both conditional and non-conditional breakpoints)
9REMOVE_BREAKPOINTS
10EXECUTE
11ADD_CONDITIONAL_BREAKPOINTS
12SET_EXCEPTION_BREAKPOINTS
122EXIT_CHANNEL

See Debugging Commands for more information.
command_arguments (optional)uint8Command-specific arguments (these may not be present for some commands)
FieldTypeDescription
packet_lengthuint32The size of the packet to be sent.
Example: (4 + 4 + 4 + sizeof(ARGUMENTS))
request_iduint32The ID of the debugger request (must be >=1). This ID is included in the debugger response.
command_codeuint32 + An enum representing the debugging command being sent, which may be one of the following values: +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeCommand
1STOP
2CONTINUE
3THREADS
4STACKTRACE
5VARIABLES
6STEP
7ADD_BREAKPOINTS
8LIST_BREAKPOINTS

(As of [Roku OS 11.5](doc:release-notes#roku-os-115), this command supports both conditional and non-conditional breakpoints)
9REMOVE_BREAKPOINTS
10EXECUTE
11ADD_CONDITIONAL_BREAKPOINTS
12SET_EXCEPTION_BREAKPOINTS
122EXIT_CHANNEL
+
+
+ See [Debugging Commands](#debugging-commands) for more information. +
command_arguments (optional)uint8Command-specific arguments (these may not be present for some commands)
-`} ## Debugger Response Format @@ -260,100 +272,106 @@ struct DebuggerResponse { }; ``` -{` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
packet_lengthuint32The size of the packet to be sent.
Example: (4 + 4 + 4 + sizeof(ARGUMENTS))
request_iduint32The ID of the debugger request (must be >=1). This ID is included in the debugger response.
command_codeuint32An enum representing the debugging command being sent, which may be one of the following values:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeCommand
1STOP
2CONTINUE
3THREADS
4STACKTRACE
5VARIABLES
6STEP
7ADD_BREAKPOINTS
8LIST_BREAKPOINTS

(As of [Roku OS 11.5](doc:release-notes#roku-os-115), this command supports both conditional and non-conditional breakpoints)
9REMOVE_BREAKPOINTS
10EXECUTE
11ADD_CONDITIONAL_BREAKPOINTS
12SET_EXCEPTION_BREAKPOINTS
122EXIT_CHANNEL

See Debugging Commands for more information.
command_arguments (optional)uint8Command-specific arguments (these may not be present for some commands)
FieldTypeDescription
packet_lengthuint32The size of the packet to be sent.
Example: (4 + 4 + 4 + sizeof(ARGUMENTS))
request_iduint32The ID of the debugger request (must be >=1). This ID is included in the debugger response.
command_codeuint32 + An enum representing the debugging command being sent, which may be one of the following values: +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeCommand
1STOP
2CONTINUE
3THREADS
4STACKTRACE
5VARIABLES
6STEP
7ADD_BREAKPOINTS
8LIST_BREAKPOINTS

(As of [Roku OS 11.5](doc:release-notes#roku-os-115), this command supports both conditional and non-conditional breakpoints)
9REMOVE_BREAKPOINTS
10EXECUTE
11ADD_CONDITIONAL_BREAKPOINTS
12SET_EXCEPTION_BREAKPOINTS
122EXIT_CHANNEL
+
+
+ See [Debugging Commands](#debugging-commands) for more information. +
command_arguments (optional)uint8Command-specific arguments (these may not be present for some commands)
-`}
@@ -371,144 +389,154 @@ struct DebuggerUpdate { }; ``` -{` - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldTypeDescription
packet_lengthuint32The length of the packet in bytes, including this field
request_iduint32The ID of the debugger request, which must be 0. This ID is included in the debugger response.

0 is a reserved value for the request_id in DebuggerUpdate messages; therefore, a debugging client may not send a DebuggerRequest with a request_id of 0.
error_codeuint32An enum indicating the status of the request. If the debugger request was successful, a value of 0 is returned. This may be one of the following values:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeStatus
0OK
1OTHER_ERR
2UNDEFINED_COMMAND
3CANT_CONTINUE
4NOT_STOPPED
5INVALID_ARGS
6THREAD_DETACHED
7EXECUTION_TIMEOUT
update_typeuint32An enum representing the update being sent by the debugger, which may be one of the following values:
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
CodeUpdateDescription
0UNDEF
1IO_PORT_OPENEDThe remote debugging client should connect to the port included in the data field to retrieve the running script's output. Only reads are allowed on the I/O connection.
2ALL_THREADS_STOPPEDAll threads are stopped and an ALL_THREADS_STOPPED message is sent to the debugging client.

The data field includes information on why the threads were stopped.
3THREAD_ATTACHEDA new thread attempts to execute a script when all threads have already been stopped. The new thread is immediately stopped and is "attached" to the debugger so that the debugger can inspect the thread, its stack frames, and local variables.

Additionally, when a thread executes a step operation, that thread detaches from the debugger temporarily, and a THREAD_ATTACHED message is sent to the debugging client when the thread has completed its step operation and has re-attached to the debugger.

The data field includes information on why the threads were stopped.
4BREAKPOINT_ERRORA compilation or runtime error occurred when evaluating the cond_expr of a conditional breakpoint.
5COMPILE_ERRORA compilation error occurred.
6

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		BREAKPOINT_VERIFIEDA breakpoint has successfully been applied to an executable line of code.
7

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		PROTOCOL_ERRORAn unrecoverable error has occurred on the protocol stream. As a result, the debug target is terminated.
8

Available since Roku OS 14.1		EXCEPTION_BREAKPOINT_ERRORA compilation or runtime error has occurred when evaluating the cond_expr of an exception breakpoint.
datauint8The update data returned based on the update_type. This may be one of the following values:
    -
  • If the update_type is IO_PORT_OPENED, the data field contains the port number (uint32) to which the debugging client should connect to read the script's output.
    • -
  • If the update_type is ALL_THREADS_STOPPED, the data field contains a structure named AllThreadsStoppedUpdateData. See AllThreadsStopped for more information.
    • -
  • If the update_type is THREAD_ATTACHED, the data field contains a structure named ThreadAttachedUpdateData. See ThreadAttached for more information.
    • -
FieldTypeDescription
packet_lengthuint32The length of the packet in bytes, including this field
request_iduint32The ID of the debugger request, which must be 0. This ID is included in the debugger response.

0 is a reserved value for the request_id in DebuggerUpdate messages; therefore, a debugging client may not send a DebuggerRequest with a request_id of 0.
error_codeuint32 + An enum indicating the status of the request. If the debugger request was successful, a value of 0 is returned. This may be one of the following values: +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeStatus
0OK
1OTHER_ERR
2UNDEFINED_COMMAND
3CANT_CONTINUE
4NOT_STOPPED
5INVALID_ARGS
6THREAD_DETACHED
7EXECUTION_TIMEOUT
+
+
update_typeuint32 + An enum representing the update being sent by the debugger, which may be one of the following values: +
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
CodeUpdateDescription
0UNDEF
1IO_PORT_OPENEDThe remote debugging client should connect to the port included in the data field to retrieve the running script's output. Only reads are allowed on the I/O connection.
2ALL_THREADS_STOPPEDAll threads are stopped and an ALL_THREADS_STOPPED message is sent to the debugging client.

The data field includes information on why the threads were stopped.
3THREAD_ATTACHEDA new thread attempts to execute a script when all threads have already been stopped. The new thread is immediately stopped and is "attached" to the debugger so that the debugger can inspect the thread, its stack frames, and local variables.

Additionally, when a thread executes a step operation, that thread detaches from the debugger temporarily, and a THREAD_ATTACHED message is sent to the debugging client when the thread has completed its step operation and has re-attached to the debugger.

The data field includes information on why the threads were stopped.
4BREAKPOINT_ERRORA compilation or runtime error occurred when evaluating the cond_expr of a conditional breakpoint.
5COMPILE_ERRORA compilation error occurred.
6

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		BREAKPOINT_VERIFIEDA breakpoint has successfully been applied to an executable line of code.
7

Available since [Roku OS 12.0](doc:release-notes#roku-os-120)		PROTOCOL_ERRORAn unrecoverable error has occurred on the protocol stream. As a result, the debug target is terminated.
8

Available since Roku OS 14.1		EXCEPTION_BREAKPOINT_ERRORA compilation or runtime error has occurred when evaluating the cond_expr of an exception breakpoint.
+
+
datauint8The update data returned based on the update_type. This may be one of the following values:
    +
  • If the update_type is IO_PORT_OPENED, the data field contains the port number (uint32) to which the debugging client should connect to read the script's output.
    • +
  • If the update_type is ALL_THREADS_STOPPED, the data field contains a structure named AllThreadsStoppedUpdateData. See AllThreadsStopped for more information.
    • +
  • If the update_type is THREAD_ATTACHED, the data field contains a structure named ThreadAttachedUpdateData. See ThreadAttached for more information.
    • +
-`} ### AllThreadsStopped