src/chromiumos/common.proto

syntax = "proto3";

package chromiumos;

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

// Common message definitions.

// BuildTarget encapsulates a number of related arguments. At the moment, the
// usage of specific arguments is on a per endpoint basis, but will converge
// to support a standard set as time goes on.
// BuildTarget is a more appropriate name going forward for what we currently
// call "board".
message BuildTarget {
  // The name of the build target (a.k.a. board name).
  string name = 1;
}

// Chroot is used to define how to enter a chroot.
message Chroot {
  // Deprecated fields.
  reserved 5;

  message ChrootEnv {
    // USE flags to set.
    repeated UseFlag use_flags = 1;
    // FEATURES flags to set.
    repeated Feature features = 2;
  }

  // The directory containing the chroot.
  string path = 1;
  // The cache directory override.
  string cache_dir = 2;
  // Environment configuration.
  ChrootEnv env = 3;
  // The directory where the chrome source should be mounted.
  string chrome_dir = 4;
}

// FEATURES environment variable component message.
message Feature {
  string feature = 1;
}

message GomaConfig {
  // The goma install location.
  // Required.
  string goma_dir = 1;
  // The goma client credentials file.
  string goma_client_json = 2;
  // Path to the Goma client used for build package.
  // If None, goma_dir will be used instead.
  string chromeos_goma_dir = 3;

  // Facilitates testing new Goma approaches before rolling them out
  // more widely.
  enum GomaApproach {
    GOMA_APPROACH_UNSPECIFIED = 0;
    DEFAULT = 1;
    RBE_PROD = 2;
    RBE_STAGING = 3;
  }
  GomaApproach goma_approach = 4;

  // The directory where the goma logs will be extracted.
  SyncedDir log_dir = 5;
  // The name of the goma stats file. It will be dumped inside log_dir.
  string stats_file = 6;
  // The name of the goma counterz file. It will be dumped inside log_dir.
  string counterz_file = 7;
}

message GomaArtifacts {
  // The Goma artifacts (stats file, counterz file, and log files) are placed
  // in the directory specified by the GomaConfig.log_dir.

  // Goma stats file.
  string stats_file = 1;
  // Goma counterz file.
  string counterz_file = 2;
  // Goma log files.
  repeated string log_files = 3;
}


// Message describing a package, The corresponding variable names are from
// https://devmanual.gentoo.org/ebuild-writing/variables/index.html
message PackageInfo {
  // The package name (PN variable).
  string package_name = 1;

  // The package category (CATEGORY variable).
  string category = 2;

  // The package version and revision (PVR variable).
  string version = 3;
}

// A message to clarify inside/outside chroot paths.
message Path {
  // Location enum; whether the resource is inside or outside of the chroot.
  enum Location {
    NO_LOCATION = 0;
    INSIDE = 1;
    OUTSIDE = 2;
  }

  // The path to the resource.
  string path = 1;
  // The path location.
  Location location = 2;
}

// A message used to indicate an output location for results. Specifically,
// this is used to automatically transfer files out of the chroot when needed.
// Note: No more than one ResultPath per message can be supported.
message ResultPath {
  // Required.
  // The result directory information.
  Path path = 1;
}

// A SyncedDir will have all of its contents transferred into a tmp directory
// in the chroot before the endpoint is called, and afterwords its contents
// will be exactly what was in the tmp directory when the endpoint completed.
message SyncedDir {
  // Required.
  // The directory being synced.
  string dir = 1;
}

// See also crrev.com/c/1929452 and:
//   https://cs.corp.google.com/piper///depot/google3/third_party/luci/buildbucket/proto/common.proto?l=147-176&rcl=257714215
// A Gerrit patchset.
message GerritChange {
  // Gerrit hostname, e.g. "chromium-review.googlesource.com".
  string host = 1;
  // Gerrit project, e.g. "chromium/src".
  string project = 2;
  // Change number, e.g. 12345.
  int64 change = 3;
  // Patch set number, e.g. 1.
  int64 patchset = 4;
}

message GitilesCommit {
  // Gitiles hostname, e.g. "chromium.googlesource.com".
  string host = 1;
  // Repository name on the host, e.g. "chromium/src".
  string project = 2;
  // Commit HEX SHA1.
  string id = 3;
  // Commit ref, e.g. "refs/heads/master".
  // NOT a branch name: if specified, must start with "refs/".
  string ref = 4;
  // Defines a total order of commits on the ref. Requires ref field.
  uint32 position = 5;
}

// Message for USE flags.
message UseFlag {
  // The use flag.
  string flag = 1;
}

// The types of images that can be built.
// These correspond to support types in lib/constants.py such
// as IMAGE_TYPE_BASE, IMAGE_TYPE_RECOVERY, and so on.
enum ImageType {
  IMAGE_TYPE_UNDEFINED = 0;
  BASE = 1;
  DEV = 2;
  TEST = 3;
  BASE_VM = 4;
  TEST_VM = 5;
  RECOVERY = 6;
  FACTORY = 7;
  FIRMWARE = 8;
  CR50_FIRMWARE = 9;
  BASE_GUEST_VM = 10;
  TEST_GUEST_VM = 11;
}

// The various channels that we release through.
enum Channel {
  CHANNEL_UNSPECIFIED = 0;
  CHANNEL_STABLE = 1;
  CHANNEL_BETA = 2;
  CHANNEL_DEV = 3;
  CHANNEL_CANARY = 4;
}

// A wrapper around a serialized protocol buffer.
message ProtoBytes {
  bytes serialized_proto = 1;
}

// TODO(crbug/1019868): Consider migrating
// chromite.api.toolchain.PrepareForToolchainBuildRequest as well.
message PrepareForBuildResponse {
  // Does this artifact require a build?
  enum BuildRelevance {
    UNSPECIFIED = 0;
    // Build is necessary to generate artifacts.
    NEEDED = 1;
    // Defer to other artifacts.  Used primarily for aggregation of artifact
    // results.
    UNKNOWN = 2;
    // Artifacts are already generated.  The build is pointless.
    POINTLESS = 3;
  }
  BuildRelevance build_relevance = 1;
}

// TODO(crbug.com/1020615): Drop this from chromite/api/toolchain.proto (and
// here) once usage has migrated to BuilderConfig.Artifacts.ArtifactType.
// Meanwhile, keep this in sync with chromite/api/toolchain.proto.  The various
// toolchain optimization artifact types.
enum AFDOArtifactType {
  // No AFDO artifact type specified.
  NONE_TYPE = 0;

  // The type is orderfile.
  ORDERFILE = 1;

  // The type is Chrome AFDO files generated by benchmarks.
  BENCHMARK_AFDO = 2;

  // The type is kernel AFDO files.
  KERNEL_AFDO = 3;

  // The type is Chrome AFDO used in release builders.
  CHROME_AFDO = 4;
}

// Additional information about artifacts used by PrepareForBuild endpoints.
// TODO(crbug/1019868): This is migrating to ArtifactProfileInfo.
message PrepareForBuildAdditionalArgs {
  oneof prepare_for_build_args {
    // ToolchainService Chrome AFDO artifacts require profile name.
    string chrome_cwp_profile = 1;

    // ToolchainService Kernel AFDO artifacts require a kernel version.
    string kernel_version = 2;
  }
}

// ToolchainService Unverified Release AFDO artifacts require information
// about the builder that created the image used to generate the unverified
// chrome benchmark perf file.
message AfdoRelease {
  // ToolchainService Chrome AFDO artifacts require profile name.
  string chrome_cwp_profile = 1;

  // The build id of the image_build.  Used to generate the location for the
  // image archive.
  int64 image_build_id = 2;
}

// Artifact profile information used by artifact prepare/bundle endpoints in
// addition to input_artifacts.
message ArtifactProfileInfo {
  oneof artifact_profile_info {
    // ToolchainService Chrome AFDO artifacts require profile name.
    string chrome_cwp_profile = 1;

    // ToolchainService Kernel AFDO artifacts require a kernel version.
    string kernel_version = 2;

    // ToolchainService Unverified Release AFDO artifacts require more.
    AfdoRelease afdo_relase = 3;
  }
}