// This file is part of arduino-cli.
//
// Copyright 2020 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.debug.v1;

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

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

// DebugService abstracts a debug Session usage
service DebugService {
  // Start a debug session and communicate with the debugger tool.
  rpc Debug(stream DebugRequest) returns (stream DebugResponse) {}

  rpc GetDebugConfig(DebugConfigRequest) returns (GetDebugConfigResponse) {}
}

// The top-level message sent by the client for the `Debug` method.
// Multiple `DebugReq` messages can be sent but the first message
// must contain a `DebugConfigReq` message to initialize the debug session.
// All subsequent messages must contain bytes to be sent to the debug session
// and must not contain a `DebugReq` 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 `StreamingOpenReq` message must contain a `DebugReq`
  // message.
  DebugConfigRequest 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 DebugConfigRequest {
  // Arduino Core Service instance from the `Init` response.
  cc.arduino.cli.commands.v1.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).
  cc.arduino.cli.commands.v1.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
  map<string, string> toolchain_configuration = 7;
  // Extra configuration parameters wrt GDB server
  map<string, string> server_configuration = 8;
}
