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;

import "common.proto";

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) {}
}

// 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| having a non-HTTPS scheme.
    STATUS_ERROR_NON_HTTPS_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,
    // etc.
    STATUS_NETWORK_ERROR = 5;
    // HTTP request finished with a non-2xx status.
    STATUS_HTTP_ERROR = 6;
  }

  // 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;
}

// 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.
  //
  // TODO(lamzin): add payload filtering.
  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;
  }

  // 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;
}