diagnostics/grpc/diagnosticsd.proto

// Copyright 2018 The Chromium OS Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// gRPC API exposed by the diagnosticsd daemon. Normally the consumer of the API
// is the diagnostics_processor daemon.

syntax = "proto3";

package diagnostics.grpc_api;

service Diagnosticsd {
  // Sends a message to the diagnostics UI extension (hosted by the browser).
  // Delivery of the message is not guaranteed (for example, if the diagnostics
  // UI extension isn't running at the moment).
  rpc SendMessageToUi(SendMessageToUiRequest)
      returns (SendMessageToUiResponse) {}

  // Returns the specified data from the proc filesystem.
  rpc GetProcData(GetProcDataRequest) returns (GetProcDataResponse) {}

  // Returns the specified data from the sysfs filesystem.
  rpc GetSysfsData(GetSysfsDataRequest) returns (GetSysfsDataResponse) {}

  // Performs a web request to the specified HTTPS URL. Returns only whether the
  // request succeeded and the HTTP status code.
  //
  // It is implementation-defined which network, proxy and VPN settings are used
  // for making the request.
  rpc PerformWebRequest(PerformWebRequestParameter)
      returns (PerformWebRequestResponse) {}

  // Runs EC command using the EC driver and returns the command response.
  rpc RunEcCommand(RunEcCommandRequest) returns (RunEcCommandResponse) {}

  // Retrieves EC property.
  rpc GetEcProperty(GetEcPropertyRequest) returns (GetEcPropertyResponse) {}

  // Retrieves a list of diagnostic routines which diagnosticsd can run.
  rpc GetAvailableRoutines(GetAvailableRoutinesRequest)
      returns (GetAvailableRoutinesResponse) {}

  // Requests that diagnosticsd start a particular diagnostics routine.
  rpc RunRoutine(RunRoutineRequest) returns (RunRoutineResponse) {}

  // Requests an update on a particular diagnostics routine's status.
  rpc GetRoutineUpdate(GetRoutineUpdateRequest)
      returns (GetRoutineUpdateResponse) {}
}

// Parameters for the SendMessageToUi RPC.
message SendMessageToUiRequest {
  // Message contents. Must be a valid JSON string.
  string json_message = 1;
}

// Return value of the SendMessageToUi RPC.
message SendMessageToUiResponse {
  // Response message contents, as returned by the diagnostics UI extension.
  // Will be unset when the request was not delivered to any extension or the
  // extension(s) that received the message completed the request without any
  // reply.
  string response_json_message = 1;
}

// Holds a dump of a file contents.
message FileDump {
  // Absolute path to the file.
  string path = 1;

  // Canonicalized path to the file. Unlike |path|, this path never contains
  // symbolic links.
  string canonical_path = 2;

  // Contents of the file.
  bytes contents = 3;
}

// Parameters for the GetProcData RPC.
message GetProcDataRequest {
  // Type of information to be retrieved from the proc filesystem.
  //
  // NOTE: The following enums correspond to hardcoded file paths on the proc
  // filesystem provided by the OS kernel. There's NO guarantee that these files
  // will continue to be present after the OS kernel version changes.
  enum Type {
    TYPE_UNSET = 0;
    FILE_UPTIME = 1;   // request contents of "/proc/uptime"
    FILE_MEMINFO = 2;  // request contents of “/proc/meminfo"
    FILE_LOADAVG = 3;  // request contents of “/proc/loadavg"
    FILE_STAT = 4;     // request contents of “/proc/stat"
    DIRECTORY_ACPI_BUTTON =
        5;  // request contents of files under “/proc/acpi/button/"
    FILE_NET_NETSTAT = 6;  // request contents of “/proc/net/netstat"
    FILE_NET_DEV = 7;      // request contents of “/proc/net/dev"
  };

  // Must not be |TYPE_UNSET|.
  Type type = 1;
}

// Return value of the GetProcData RPC.
message GetProcDataResponse {
  // Contents of the requested file(s) from the proc filesystem, as specified by
  // the |type| field of the request. The file paths are guaranteed to belong to
  // the /proc/ directory. Symlinks will NOT be followed.
  //
  // Example value: an entry with |path| and |canonical_path| equal to
  // "/proc/acpi/button/lid/LID0/state" and |contents| equal to "state: open".
  //
  // In case of failure to read some file(s), their entries will be omitted from
  // the |file_dump| field.
  //
  // NOTE: There's NO guarantee that the file names or formats of the file
  // contents will stay the same after the OS kernel version changes.
  repeated FileDump file_dump = 1;
}

// Parameters for the GetSysfsData RPC.
message GetSysfsDataRequest {
  // Type of information to be retrieved from the sysfs filesystem.
  enum Type {
    TYPE_UNSET = 0;
    CLASS_HWMON = 1;    // request information about hwmon devices (contents of
                        // files under /sys/class/hwmon/)
    CLASS_THERMAL = 2;  // request information about thermal zone devices and
                        // cooling devices (contents of files under
                        // /sys/class/thermal/)
    FIRMWARE_DMI_TABLES = 3;  // request SMBIOS information as raw DMI tables
                              // (contents of files under
                              // /sys/firmware/dmi/tables/)
  };

  // Must not be |TYPE_UNSET|.
  Type type = 1;
}

// Return value of the GetSysfsData RPC.
message GetSysfsDataResponse {
  // Contents of the requested file(s) from the sysfs filesystem, as specified
  // by the |type| field of the request. The file paths are guaranteed to belong
  // to the /sys/ directory. Whether symlinks in the reported directories are
  // followed depends on |type|-specific handling.
  //
  // Example value - two entries:
  // 1. The first entry having |path| equal to "/sys/class/hwmon/hwmon0/name",
  //    |canonical_path| to "/sys/devices/platform/coretemp.0/hwmon/hwmon0/name"
  //    and |contents| to "coretemp".
  // 2. The second one having |path| equal to
  //    "/sys/class/hwmon/hwmon0/power/control", |canonical_path| to
  //    "/sys/devices/platform/coretemp.0/hwmon/hwmon0/power/control" and
  //    |contents| to "auto".
  //
  // In case of failure to read some file(s), their entries will be omitted from
  // the |file_dump| field.
  //
  // NOTE: The set of files present here is determined by the information
  // returned by the host kernel through the sysfs interface.
  // NOTE: There's NO guarantee that the file names or formats of the file
  // contents will stay the same after the OS kernel version changes.
  repeated FileDump file_dump = 1;
}

// Parameters for the PerformWebRequest RPC.
//
// NOTE: The total size of all "string" and "bytes" fields in the request must
// not exceed 1 MB (1'000'000 bytes).
message PerformWebRequestParameter {
  // HTTP request method.
  enum HttpMethod {
    HTTP_METHOD_UNSET = 0;
    HTTP_METHOD_GET = 1;
    HTTP_METHOD_HEAD = 2;
    HTTP_METHOD_POST = 3;
    HTTP_METHOD_PUT = 4;
  }

  // Must be distinct from |HTTP_METHOD_UNSET|.
  HttpMethod http_method = 1;
  // Must have the "https" scheme.
  string url = 2;
  // List of HTTP headers.
  repeated string headers = 3;
  // Body of the HTTP request.
  bytes request_body = 4;
}

// Return value of the PerformWebRequest RPC.
message PerformWebRequestResponse {
  // Status of the finished request.
  enum Status {
    STATUS_UNSET = 0;
    // The request was successfully completed with a 2xx HTTP status.
    STATUS_OK = 1;
    // The request was rejected due to some required field being missing.
    STATUS_ERROR_REQUIRED_FIELD_MISSING = 2;
    // The request was rejected due to the |url| being invalid.
    STATUS_ERROR_INVALID_URL = 3;
    // The request was rejected due to the request being too large.
    STATUS_ERROR_MAX_SIZE_EXCEEDED = 4;
    // Failed to make the web request. This covers such cases when the network
    // is unavailable, or connection attempt failed, or TLS handshake failed,
    // or too many pending requests, etc.
    STATUS_NETWORK_ERROR = 5;
    // HTTP request finished with a non-2xx status.
    STATUS_HTTP_ERROR = 6;
    // Other errors that prevented a request with valid parameters from being
    // sent over the network.
    // E.g. the diagnosticsd daemon is unable to talk to the OS component that
    // hosts the network stack.
    STATUS_INTERNAL_ERROR = 7;
  }

  // Is guaranteed to be distinct from |STATUS_UNSET|.
  Status status = 1;
  // HTTP status code. This field is set when |status| is |STATUS_OK| or
  // |STATUS_HTTP_ERROR|.
  int32 http_status = 2;
  // Body of the HTTP response.
  // The length does not exceed 1MB (1'000'000 bytes). This field is set when
  // |status| is |STATUS_OK| or |STATUS_HTTP_ERROR|.
  bytes response_body = 3;
}

// Parameters for the RunEcCommand RPC.
message RunEcCommandRequest {
  // Data blob with encoded EC command. The maximum allowed size is 32 bytes.
  // Should to be non-empty.
  bytes payload = 1;
}

// Return value of the RunEcCommand RPC.
message RunEcCommandResponse {
  // Status of the EC command run request.
  enum Status {
    STATUS_UNSET = 0;
    // The EC command run was successfully completed.
    STATUS_OK = 1;
    // The EC command run was rejected due to the empty request payload.
    STATUS_ERROR_INPUT_PAYLOAD_EMPTY = 2;
    // The EC command run was rejected due to the request payload being too
    // large.
    STATUS_ERROR_INPUT_PAYLOAD_MAX_SIZE_EXCEEDED = 3;
    // The EC command run was failed due to EC driver error.
    STATUS_ERROR_ACCESSING_DRIVER = 4;
  }

  // Is guaranteed to be distinct from |STATUS_UNSET|.
  Status status = 1;

  // Data blob with encoded EC command response. This field is set when
  // |status| is |STATUS_OK|.
  bytes payload = 2;
}

// Parameters for the GetEcProperty RPC.
message GetEcPropertyRequest {
  // EC properties. Each value corresponds to a specific sysfs file exposed by
  // the EC driver.
  //
  // TODO(lamzin): add full list of properties.
  enum Property {
    PROPERTY_UNSET = 0;
    // Relative file path is "properties/global_mic_mute_led".
    PROPERTY_GLOBAL_MIC_MUTE_LED = 1;
    // Relative file path is "properties/fn_lock".
    PROPERTY_FN_LOCK = 2;
    // Relative file path is "properties/nic".
    PROPERTY_NIC = 3;
    // Relative file path is "properties/ext_usb_port_en".
    PROPERTY_EXT_USB_PORT_EN = 4;
    // Relative file path is "properties/wireless_sw_wlan".
    PROPERTY_WIRELESS_SW_WLAN = 5;
    // Relative file path is "properties/auto_boot_on_trinity_dock_attach".
    PROPERTY_AUTO_BOOT_ON_TRINITY_DOCK_ATTACH = 6;
    // Relative file path is "properties/ich_azalia_en".
    PROPERTY_ICH_AZALIA_EN = 7;
    // Relative file path is "properties/sign_of_life_kbbl".
    PROPERTY_SIGN_OF_LIFE_KBBL = 8;
  }

  // Must be distinct from |PROPERTY_UNSET|.
  Property property = 1;
}

// Return value of the GetEcProperty RPC.
message GetEcPropertyResponse {
  enum Status {
    STATUS_UNSET = 0;
    // The EC property was successfully retrieved.
    STATUS_OK = 1;
    // The request was rejected due to some required field being missing.
    STATUS_ERROR_REQUIRED_FIELD_MISSING = 2;
    // The EC property retrieving failed due to EC driver error.
    STATUS_ERROR_ACCESSING_DRIVER = 3;
  }

  // Is guaranteed to be distinct from |STATUS_UNSET|.
  Status status = 1;

  // Data blob with the value of the EC property specified by the |property|
  // request field.
  // This field is set when |status| is |STATUS_OK|.
  bytes payload = 2;
}

// Enumeration of each of the diagnostics routines the platform may support.
enum DiagnosticRoutine {
  ROUTINE_UNSET = 0;
  ROUTINE_BATTERY = 1;
  ROUTINE_BATTERY_SYSFS = 2;
  ROUTINE_BAD_BLOCKS = 3;
  ROUTINE_URANDOM = 4;
}

// Enumeration of each of the possible statuses for a diagnostics routine.
enum DiagnosticRoutineStatus {
  ROUTINE_STATUS_READY = 0;    // Routine is ready to start.
  ROUTINE_STATUS_RUNNING = 1;  // Routine is currently running.
  ROUTINE_STATUS_WAITING = 2;  // Routine needs user input to continue.
  ROUTINE_STATUS_PASSED = 3;   // Routine completed and passed.
  ROUTINE_STATUS_FAILED = 4;   // Routine completed and failed.
  ROUTINE_STATUS_ERROR = 5;  // An error prevented the routine from completing.
  ROUTINE_STATUS_CANCELLED = 6;  // Routine was cancelled before completion.
}

// Enumeration of each of the messages a diagnostics routine can pass back.
// These messages prompt interaction from the user of the routine.
enum DiagnosticRoutineUserMessage {
  ROUTINE_USER_MESSAGE_UNSET = 0;  // No user interaction needed.
}

// Parameters for the GetAvailableRoutines RPC. Although the message is
// currently empty, we may decide to add parameters in the future.
message GetAvailableRoutinesRequest {}

// Return value of the GetAvailableRoutines RPC.
message GetAvailableRoutinesResponse {
  repeated DiagnosticRoutine routines = 1;
}

// Parameters for the RunRoutine RPC.
message RunRoutineRequest {
  // Must be distinct from |ROUTINE_UNSET|.
  DiagnosticRoutine routine = 1;

  oneof parameters {
    BatteryRoutineParameters battery_params = 2;
    UrandomRoutineParameters urandom_params = 3;
  }
}

// Parameters for the battery diagnostics routine.
message BatteryRoutineParameters {
  // Lower and upper bounds for the battery's design capacity, in mAh. The test
  // will pass if the design capactity of the battery read from the platform is
  // inclusively within these bounds. Neither parameter needs to be set - they
  // will default to low_mah = 1000 and high_mah = 10000 if unset.
  int32 low_mah = 1;
  int32 high_mah = 2;
}

// Parameters for the urandom diagnostics routine.
message UrandomRoutineParameters {
  // Length of time, in seconds, to run the urandom routine for. If all reads
  // from /dev/urandom for this length of time are succesful, then the test
  // will pass. This parameter needs to be set and strictly greater than zero.
  int32 length_seconds = 1;
}

// Return value of the RunRoutine RPC.
message RunRoutineResponse {
  // Can be used to request status or control the routine by sending a
  // GetRoutineUpdateRequest with the same uuid that was returned from
  // the RunRoutineResponse.
  int32 uuid = 1;

  DiagnosticRoutineStatus status = 2;
}

// Parameters for the GetRoutineUpdate RPC.
message GetRoutineUpdateRequest {
  // Must be the same uuid that was returned from a RunRoutineResponse.
  int32 uuid = 1;

  enum Command {
    COMMAND_UNSET = 0;
    PAUSE = 1;
    RESUME = 2;
    CANCEL = 3;
    GET_STATUS = 4;
    STOP = 5;
  }

  // Must be distinct from |COMMAND_UNSET|.
  Command command = 2;
  // Whether or not the GetRoutineUpdateResponse should include all
  // output accumulated from the routine so far.
  bool include_output = 3;
}

// Return value for the GetRoutineUpdate RPC. All fields are populated
// regardless of |command| in the GetRoutineUpdateRequest, except output, which
// is only populated when |include_output| was true in the
// GetRoutineUpdateRequest.
message GetRoutineUpdateResponse {
  // Same uuid that was sent in the GetRoutineUpdateRequest.
  int32 uuid = 1;
  // Guaranteed to be distinct from |ROUTINE_STATUS_UNSET|.
  DiagnosticRoutineStatus status = 2;
  // Progress of the running routine, from 0-100.
  int32 progress_percent = 3;
  // Request for the user to take action in an interactive routine.
  DiagnosticRoutineUserMessage user_message = 4;
  // Accumulated output from the routine, e.g. logs. Output is not
  // flushed when returned.
  string output = 5;
}