src/chromite/api/firmware.proto

syntax = "proto3";
package chromite.api;

option go_package = "go.chromium.org/chromiumos/infra/proto/go/chromite/api";

import "chromite/api/build_api.proto";
import "chromiumos/common.proto";

// Protos for executing firmware builder functionality.  Added in R88.

// TODO(b/177907747): Drop this once the migration is complete.
// List of known location that firmware can be built from.
enum FwLocation {
  FW_LOCATION_UNKNOWN = 0;
  PLATFORM_EC = 1; // platform/ec/firmware_builder.py
  PLATFORM_ZEPHYR = 2; // platform/zephyr-chrome/firmware_builder.py
  PLATFORM_TI50 = 3; // platform/ti50/common/firmware_builder.py.  Added in R90.
}

// Added in R91.
message BcsVersionInfo {
  // Chrome OS version string, such as "R91-13844.0.0-45436".
  string version_string = 1;
  // Extend with fields that break down the version string.
  // This should come from chromiumos/common.proto.
}

// Added in R91.
message FirmwareVersionInfo {
  // Firmware version string, such as "atlas_v2.0.923-84a1d7260".
  string version_string = 1;
  // Extend with fields that break down the version string.
}

// Metrics collected on every successful firmware build.
message FwBuildMetric {
  // Lowercase name of the firmware target built. E.g. phaser.
  string target_name = 1;

  // Lowercase name of the platform the firmware target belongs to. May be
  // blank. E.g. octopus.
  string platform_name = 2;

  // List of firmware sections and their free and total sizes in bytes.
  repeated FwSection fw_section = 3;

  message FwSection {
    // Region as described in FMAP or linker script.
    // E.g. EC_RO, EC_RW, EC_NVRAM, RO_BSS, RW_BSS, SHARED_MEM.
    FwRegion region = 1;

    enum FwRegion {
      FW_REGION_UNKNOWN = 0;
      EC_RO = 1;  // The entire section protected by write protect.
      EC_RW = 2;  // Also RW_A for EFS1 systems.
      EC_RO_BSS = 3;
      EC_RW_BSS = 4;
      EC_SHARED_MEM = 5;
    }

    // The number of bytes used in this section.
    uint32 used = 2;

    // The total number of bytes available in this section.
    uint32 total = 3;
  }

  // Version number components: "major.minor.tiny".
  message Version {
    uint32 major = 1;
    uint32 minor = 2;
    uint32 tiny = 3;
  }

  // Optional information related to a specific target type.
  oneof image_type {
    ZephyrTarget zephyr = 4;
  }

  // Zephyr-base firmware target related build metrics.
  message ZephyrTarget {
    // The version of the Zephyr kernel used during build.
    Version kernel_version = 1;
  }
}

// A list of FW metrics collected on every successful firmware build
// Implementation note, this is a separate message since it serves as the
// serialization base between the build_api end point and the entry point
// in the firmware_builder.py.
message FwBuildMetricList {
  repeated FwBuildMetric value = 1;
}

// Metrics collect on successful firmware unit test runs.
message FwTestMetric {
  // Name of firmware test.
  string name = 1;
}

// A list of FW metrics collected on every successful firmware unit test.
// Implementation note, this is a separate message since it serves as the
// serialization base between the build_api end point and the entry point
// in the firmware_builder.py.
message FwTestMetricList {
  repeated FwTestMetric value = 1;
}

// TODO(b/177907747): Drop this once the migration is complete.
message BuildAllTotFirmwareRequest {
  // Location of firmware to build call into firmware_builder.py entry point.
  // The `build` subcommand will be called.
  FwLocation firmware_location = 1;

  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 2;

  // Whether to pass --code-coverage to firmware_builder.py.
  bool code_coverage = 3;
}

// TODO(b/177907747): Drop this once the migration is complete.
message BuildAllTotFirmwareResponse {
  // Metrics collected on every successful firmware build
  FwBuildMetricList metrics = 1;
}

// TODO(b/177907747): Drop this once the migration is complete.
message TestAllTotFirmwareRequest {
  // Location of firmware to build call into firmware_builder.py entry point.
  // The `test` subcommand will be called
  FwLocation firmware_location = 1;

  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 2;

  // Whether to pass --code-coverage to firmware_builder.py.
  bool code_coverage = 3;
}

// TODO(b/177907747): Drop this once the migration is complete.
message TestAllTotFirmwareResponse {
  // Metrics collect on successfuly firmware unit test runs
  FwTestMetricList metrics = 1;
}

message BuildAllFirmwareRequest {
  // Location of firmware to build call into firmware_builder.py entry point.
  // The `build` subcommand will be called
  chromiumos.FwLocation firmware_location = 1;

  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 2;

  // Whether to pass --code-coverage to firmware_builder.py.
  bool code_coverage = 3;
}

message BuildAllFirmwareResponse {
  // Metrics collected on every successful firmware build
  FwBuildMetricList metrics = 1;
}

message TestAllFirmwareRequest {
  // Location of firmware to build call into firmware_builder.py entry point.
  // The `test` subcommand will be called
  chromiumos.FwLocation firmware_location = 1;

  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 2;

  // Whether to pass --code-coverage to firmware_builder.py.
  bool code_coverage = 3;
}

message TestAllFirmwareResponse {
  // Metrics collect on successfuly firmware unit test runs
  FwTestMetricList metrics = 1;
}

message BundleFirmwareArtifactsRequest {
  // firmware_location was moved to artifacts.output_artifacts[].location before
  // chromite started processing it.  We could potentially reuse this number if
  // we want.
  // reserved 1;
  // reserved "firmware_location";

  // The chroot where the operations will be executed.
  // Required.
  chromiumos.Chroot chroot = 2;

  // The output directory in which to place the bundled artifacts.
  chromiumos.ResultPath result_path = 3;

  // The artifact types requested.  The firmware_location is found in
  // artifacts.output_artifacts[].location.
  chromiumos.ArtifactsByService.Firmware artifacts = 4;

  // The Chrome OS style version to use in FirmwareArtifactInfo.
  // Added and deprecated in R91.
  string bcs_version = 5 [deprecated = true];

  // BcsVersionInfo to use in (copy into) FirmwareArtifactInfo.TarballInfo.
  BcsVersionInfo bcs_version_info = 6;
}

message BundleFirmwareArtifactsResponse {
  // The artifacts that were bundled.
  chromiumos.UploadedArtifactsByService.Firmware artifacts = 1;
}

// Contents of a Firmware.FIRMWARE_TARBALL_INFO artifact.
message FirmwareArtifactInfo {
  // TODO(crbug/1176305): Use types from
  // chromiumos/config/api/software/firmware_config.proto
  message TarballInfo {
      // The Chrome OS style version.
      // Use bcs_version_info.version_string instead.
      // Deprecated since R91.
      string bcs_version = 1 [deprecated = true];

      // The name of the firmware image used by the firmware updater. Typically
      // the device name, but can differ when a device may have two or more
      // different firmware images.
      string firmware_image_name = 2;

      // The type of a firmware binary.
      message FirmwareType {
        enum Type {
            UNKNOWN = 0;
            MAIN = 1;
            EC = 2;
            PD = 3;
        }
      }
      FirmwareType.Type type = 3;

      // The firmware version from updater.sh --manifest.
      message Version {
        int32 major = 1;
        int32 minor = 2;
      }
      // Use firmware_version_info instead.
      // Deprecated since R91.
      Version version = 4 [deprecated = true];

      // Added in R91.  Required.
      FirmwareVersionInfo firmware_version_info = 5;
  }

  message ObjectInfo {
    // The name of the file.
    string file_name = 1;

    oneof firmware_object_info {
      // Info about Firmware.FIRMWARE_TARBALL.
      TarballInfo tarball_info = 2;
    }
  }
  repeated ObjectInfo objects = 1;

  // The value provided by BundleFirmwareArtifactsRequest, this is the version
  // of Chrome OS used for this build.
  // Added in R91.
  BcsVersionInfo bcs_version_info = 2;
}


// The Firmware service.  Added in R88.
service FirmwareService {
  option (service_options) = {
    module: "firmware",
    service_chroot_assert: INSIDE,
  };

  // TODO(b/177907747): Drop this once the migration is complete.
  // Builds all of the firmware targets on ToT at specified location.
  rpc BuildAllTotFirmware(BuildAllTotFirmwareRequest)
      returns (BuildAllTotFirmwareResponse);

  // TODO(b/177907747): Drop this once the migration is complete.
  // Runs all of the firmware tests on ToT at specified location.
  rpc TestAllTotFirmware(TestAllTotFirmwareRequest)
      returns (TestAllTotFirmwareResponse);

  // Builds all of the firmware targets at specified location. Added in R90.
  rpc BuildAllFirmware(BuildAllFirmwareRequest)
      returns (BuildAllFirmwareResponse);

  // Runs all of the firmware tests at specified location. Added in R90.
  rpc TestAllFirmware(TestAllFirmwareRequest)
      returns (TestAllFirmwareResponse);

  // Bundles any firmware images and other artifacts. Added in R90.
  rpc BundleFirmwareArtifacts(BundleFirmwareArtifactsRequest)
      returns (BundleFirmwareArtifactsResponse);
}