diagnostics/mojo/cros_healthd_diagnostics.mojom

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

// Definitions for the diagnostics API exposed by the cros_healthd daemon. This
// API is normally consumed by the browser and the diag command-line tool.

// NOTE: This mojom should be kept in sync with the copy in Chromium's repo in
// src/chrome/services/cros_healthd/public/mojom/cros_healthd_diagnostics.mojom.

module chromeos.cros_healthd.mojom;

// Special uuid that will be returned if a routine was unable to be created.
const int32 kFailedToStartUuid = 0;

// Enumeration of each of the diagnostics routines the platform may support.
[Extensible]
enum DiagnosticRoutineEnum {
  kBattery = 0,
  kBatterySysfs = 1,
  kUrandom = 2,
};

// Enumeration of each of the possible statuses for a diagnostics routine.
[Extensible]
enum DiagnosticRoutineStatusEnum {
  kReady = 0,  // Routine is ready to start.
  kRunning = 1,  // Routine is currently running.
  kWaiting = 2,  // Routine needs user input to continue.
  kPassed = 3,  // Routine completed and passed.
  kFailed = 4,  // Routine completed and failed.
  kError = 5,  // An error prevented the routine from completing.
  kCancelled = 6,  // Routine was cancelled before completion. A cancelled
                   // routine's information can still be accessed with a
                   // GetRoutineUpdateRequest.
  kFailedToStart = 7,  // Routine could not be created.
  kRemoved = 8,  // Routine has been removed and is no longer valid.
};

// Enumeration of each of the messages a diagnostics routine can pass back.
// These messages prompt interaction from the user of the routine.
[Extensible]
enum DiagnosticRoutineUserMessageEnum {
  kUnplugACPower = 0,  // The user needs to unplug the AC power cord.
};

// Enumeration of the possible commands to send a diagnostics routine.
[Extensible]
enum DiagnosticRoutineCommandEnum {
  kContinue = 0,  // Resume a routine that is waiting.
  kCancel = 1,  // Cancelled routines must still be removed before the routine
                // is destroyed.
  kGetStatus = 2,  // Used to get status but not otherwise control a routine.
  kRemove = 3,  // All routines which started successfully must be removed,
                // otherwise they will persist on the system. This makes sure
                // the routine is terminated before removing it.
};

// Parameters for the battery diagnostics routine.
struct BatteryRoutineParameters {
  // Lower and upper bounds for the battery's design capacity, in mAh. The test
  // will pass if the design capacity of the battery read from the platform is
  // inclusively within these bounds.
  int32 low_mah@0;
  int32 high_mah@1;
};

// Parameters for the battery_sysfs diagnostics routine.
struct BatterySysfsRoutineParameters {
  // Maximum cycle count allowed for the routine to pass.
  int32 maximum_cycle_count@0;
  // Maximum percent battery wear allowed for the routine to pass.
  int32 percent_battery_wear_allowed@1;
};

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

// Union of all possible routine parameters.
union RoutineParameters {
  BatteryRoutineParameters battery_params@0;
  BatterySysfsRoutineParameters battery_sysfs_params@1;
  UrandomRoutineParameters urandom_params@2;
};

// Status fields specific to interactive routine.
struct InteractiveRoutineUpdate {
  // Request for user action. This message should be localized and displayed to
  // the user.
  DiagnosticRoutineUserMessageEnum user_message@0;
};

// Status fields specific to noninteractive routines.
struct NonInteractiveRoutineUpdate {
  // Current status of the routine.
  DiagnosticRoutineStatusEnum status@0;
  // More detailed status - for example, if |status| was ROUTINE_STATUS_ERROR,
  // |status_message| would describe the error encountered, like "failed to
  // read file."
  string status_message@1;
};

// Responses will be either interactive or noninteractive.
union RoutineUpdateUnion {
  InteractiveRoutineUpdate interactive_update@0;
  NonInteractiveRoutineUpdate noninteractive_update@1;
};

// Response type for GetRoutineUpdate.
struct RoutineUpdate {
  // Percent complete, must be between 0 and 100, inclusive.
  int32 progress_percent@0;
  // Any accumulated output, like logs, from the routine. This field is only
  // valid when GetRoutineUpdate (see cros_healthd.mojom) is called with
  // include_output = true.
  handle? output@1;

  // Information specific to the type of response - interactive or
  // noninteractive.
  RoutineUpdateUnion routine_update_union@2;
};