debug.proto

// This file is part of arduino-cli.
//
// Copyright 2023 ARDUINO SA (http://www.arduino.cc/)
//
// This software is released under the GNU General Public License version 3,
// which covers the main part of arduino-cli.
// The terms of this license can be found at:
// https://www.gnu.org/licenses/gpl-3.0.en.html
//
// You can be released from the requirements of the above licenses by purchasing
// a commercial license. Buying such a license is mandatory if you want to
// modify or otherwise use the software for commercial activities involving the
// Arduino software without disclosing the source code of your own applications.
// To purchase a commercial license, send an email to license@arduino.cc.

syntax = "proto3";

package cc.arduino.cli.commands.v1;

option go_package = "github.com/arduino/arduino-cli/rpc/cc/arduino/cli/commands/v1;commands";

import "cc/arduino/cli/commands/v1/common.proto";
import "cc/arduino/cli/commands/v1/port.proto";
import "google/protobuf/any.proto";

// The top-level message sent by the client for the `Debug` method.
// Multiple `DebugRequest` messages can be sent but the first message
// must contain a `GetDebugConfigRequest` message to initialize the debug
// session. All subsequent messages must contain bytes to be sent to the debug
// session and must not contain a `GetDebugConfigRequest` message.
message DebugRequest {
  // Content must be either a debug session config or data to be sent.

  // Provides information to the debug that specifies which is the target.
  // The first `DebugRequest` message must contain a `GetDebugConfigRequest`
  // message.
  GetDebugConfigRequest debug_request = 1;

  // The data to be sent to the target being monitored.
  bytes data = 2;

  // Set this to true to send and Interrupt signal to the debugger process
  bool send_interrupt = 3;
}

message GetDebugConfigRequest {
  // Arduino Core Service instance from the `Init` response.
  Instance instance = 1;
  // Fully qualified board name of the board in use
  // (e.g., `arduino:samd:mkr1000`). If this is omitted, the FQBN attached to
  // the sketch will be used.
  string fqbn = 2;
  // Path to the sketch that is running on the board. The compiled executable
  // is expected to be located under this path.
  string sketch_path = 3;
  // Port of the debugger (optional).
  Port port = 4;
  // Which GDB command interpreter to use.
  string interpreter = 5;
  // Directory containing the compiled executable. If `import_dir` is not
  // specified, the executable is assumed to be in
  // `{sketch_path}/build/{fqbn}/`.
  string import_dir = 8;
  // The programmer to use for debugging.
  string programmer = 9;
}

//
message DebugResponse {
  // Incoming data from the debugger tool.
  bytes data = 1;
  // Incoming error output from the debugger tool.
  string error = 2;
}

message GetDebugConfigResponse {
  // The executable binary to debug
  string executable = 1;
  // The toolchain type used for the build (for example "gcc")
  string toolchain = 2;
  // The toolchain directory
  string toolchain_path = 3;
  // The toolchain architecture prefix (for example "arm-none-eabi-")
  string toolchain_prefix = 4;
  // The GDB server type used to connect to the programmer/board (for example
  // "openocd")
  string server = 5;
  // The GDB server directory
  string server_path = 6;
  // Extra configuration parameters wrt toolchain
  google.protobuf.Any toolchain_configuration = 7;
  // Extra configuration parameters wrt GDB server
  google.protobuf.Any server_configuration = 8;
  // cortex-debug custom JSON configuration, it is provided as is from
  // the platform developers.
  string cortex_debug_custom_json = 9;
  // the SVD file to use
  string svd_file = 10;
  // The programmer specified in the request
  string programmer = 11;
}

// Configurations specific for the 'gcc' toolchain
message DebugGCCToolchainConfiguration {}

// Configuration specific for the 'openocd` server
message DebugOpenOCDServerConfiguration {
  // path to openocd
  string path = 1;
  // path to openocd scripts
  string scripts_dir = 2;
  // list of scripts to execute by openocd
  repeated string scripts = 3;
}