chromeos/crosapi/mojom/diagnostics_service.mojom

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

// API and definitions exposed by the Telemetry Services. This API is normally
// consumed by the Telemetry Extension APIs implementation.

// Note: This is a subset of the cros_healthd diagnostics service interface
// which is located in
// //chromeos/ash/services/cros_healthd/public/mojom/cros_healthd.mojom.
// This interface serves as PII filtering and data post-processing service
// between the source (cros_healthd) and the clients
// (third-party telemetry extensions).

module crosapi.mojom;

// Interface for exposing diagnostics service. Implemented in ash-chrome.
//
// Next ID: 22
[Stable, Uuid="14bc6194-c059-4048-9bea-ca6823eeda82",
RenamedFrom="ash.health.mojom.DiagnosticsService"]
interface DiagnosticsService {
  // Returns an array of all diagnostic routines that the platform supports.
  GetAvailableRoutines@0()
      => (array<DiagnosticsRoutineEnum> available_routines);

  // Sends commands to an existing routine. Also returns status information for
  // the routine.
  //
  // The request:
  // * |id| - specifies which routine the command will be sent to. This must be
  //          the same id that was returned from the RunSomeRoutine function
  //          call used to create the routine.
  // * |command| - command to send the routine.
  // * |include_output| - whether or not the response should include any output
  //                      accumulated from the routine.
  //
  // The response:
  // * |routine_update| - status information for the specified routine. See
  //                      cros_healthd_diagnostics.mojom for the structure.
  GetRoutineUpdate@1(int32 id, DiagnosticsRoutineCommandEnum command,
                   bool include_output)
      => (DiagnosticsRoutineUpdate routine_update);

  // Requests that the BatteryCapacity routine is created and started on the
  // platform. This routine checks the battery's design capacity against inputs
  // configured in cros_config. If no configuration data is present in
  // cros_config, the routine will fall back to fleet-wide default values of
  // [1000, 10000]. The routine will pass if the design capacity of the battery
  // read from the platform is inclusively within these bounds.
  // The availability of this routine can be determined by checking that
  // kBatteryCapacity is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunBatteryCapacityRoutine@2() => (DiagnosticsRunRoutineResponse response);

  // Requests that the BatteryHealth routine is created and started on the
  // platform. This routine checks the cycle count and percent wear of the
  // battery against inputs configured in cros_config. If no configuration data
  // is present in cros_config, the routine will fall back to fleet-wide default
  // values of 1000 for the maximum allowable cycle count and 50% for maximum
  // battery wear percentage allowed.
  // The availability of this routine can be determined by checking that
  // kBatteryHealth is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunBatteryHealthRoutine@3() => (DiagnosticsRunRoutineResponse response);

  // Requests that the SmartctlCheck routine is created and started on the
  // platform. This routine checks available spare NVMe capacity against the
  // threshold.
  // The availability of this routine can be determined by checking that
  // kSmartctlCheck is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunSmartctlCheckRoutine@4() => (DiagnosticsRunRoutineResponse response);

  // Requests that the AcPower routine is created and started on the
  // platform. This routine checks the status of the power supply, and if
  // |expected_power_type| is specified, checks to see that
  // |expected_power_type| matches the type reported by the power supply.
  // The availability of this routine can be determined by checking that
  // kAcPower is returned by GetAvailableRoutines.
  //
  // The request:
  // * |expected_status| - whether or not the adapter is expected to be online.
  // * |expected_power_type| - if specified, must match the type of the power
  //                           supply for the routine to succeed.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunAcPowerRoutine@5(DiagnosticsAcPowerStatusEnum expected_status,
                    string? expected_power_type)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the CPU cache routine is created and started on the
  // platform. This routine runs the stressapptest to test the CPU caches.
  // The routine will pass if the stressapptest returns zero.
  // The availability of this routine can be determined by checking that
  // kCpuCache is returned by GetAvailableRoutines.
  //
  // The request:
  // * |length_seconds| - length of time, in seconds, to run the CPU cache
  //                      routine. This parameter needs to be strictly greater
  //                      than zero.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunCpuCacheRoutine@6(uint32 length_seconds)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the CPU stress routine is created and started on the
  // platform. This routine runs the stressapptest to stress test the CPU.
  // The routine will pass if the stressapptest returns zero.
  // The availability of this routine can be determined by checking that
  // kCpuStress is returned by GetAvailableRoutines.
  //
  // The request:
  // * |length_seconds| - length of time, in seconds, to run the CPU stress
  //                      routine. This parameter needs to be strictly greater
  //                      than zero.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunCpuStressRoutine@7(uint32 length_seconds)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the FloatingPointAccuracy routine is created and started
  // on the platform. This routine executes millions of floating-point
  // operations by SSE instructions for a specified amount of time. The routine
  // will pass if the result values of the operations and known accurate result
  // are the same.
  // The availability of this routine can be determined by checking that
  // kFloatingPointAccuracy is returned by GetAvailableRoutines.
  //
  // The request:
  // * |length_seconds| - length of time, in seconds, to run the floating-point
  //                      routine for. Test will executes millions of
  //                      floating-point operations in length seconds and get
  //                      the result to compare with known accurate results.
  //                      This parameter needs to be strictly greater than zero.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunFloatingPointAccuracyRoutine@8(uint32 length_seconds)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the NvmeWearLevel routine is created and started on the
  // platform. This routine examines wear level of NVMe against input
  // threshold.
  // The availability of this routine can be determined by checking that
  // kNvmeWearLevel is returned by GetAvailableRoutines.
  //
  // The request:
  // * |wear_level_threshold| - threshold number in percentage which routine
  //                            examines wear level status against.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunNvmeWearLevelRoutine@9(uint32 wear_level_threshold)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the NvmeSelfTest routine is created and started on the
  // platform. This routine launches the NVMe self-test, a tool to perform
  // necessary tests to observe the performance and the parameters.
  // The availability of this routine can be determined by checking that
  // kNvmeSelfTest is returned by GetAvailableRoutines.
  //
  // The request:
  // * |nvme_self_test_type| - specifies the type of test for short period or
  //                           extended version.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunNvmeSelfTestRoutine@10(DiagnosticsNvmeSelfTestTypeEnum nvme_self_test_type)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the DiskRead routine is created and started on the platform.
  // The routine will create a test file with md5 checksum, read the test file
  // either randomly or linearly, repeatedly for a dedicated duration. If the
  // md5 checksum of read back is validated, then the test will pass.
  // The availability of this routine can be determined by checking that
  // kDiskRead is returned by GetAvailableRoutines.
  //
  // The request:
  // * |type| - type of how disk reading is performed, either linear or random.
  //
  // * |length_seconds| - length of time, in seconds, to run the DiskRead
  //                      routine for. This parameter needs to be strictly
  //                      greater than zero.
  //                    - TODO(b:167963397) - limit routine duration.
  // * |file_size_mb| - test file size, in mega bytes, to test with DiskRead
  //                    routine. Maximum file size is 10 GB.
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunDiskReadRoutine@11(DiagnosticsDiskReadRoutineTypeEnum type,
                    uint32 length_seconds, uint32 file_size_mb)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the PrimeSearch routine is created and started on the
  // platform. Calculate prime numbers and verifies the calculation repeatedly
  // in a duration.
  // The availability of this routine can be determined by checking that
  // kPrimeSearch is returned by GetAvailableRoutines.
  //
  // The request:
  // * |length_seconds| - length of time, in seconds, to run the PrimeSearch
  //                      routine for. This parameter needs to be strictly
  //                      greater than zero.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunPrimeSearchRoutine@12(uint32 length_seconds)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the BatteryDischarge routine is created and started on the
  // platform. This routine checks the battery's discharge rate over a period of
  // time.
  // The availability of this routine can be determined by checking that
  // kBatteryDischarge is returned by GetAvailableRoutines.
  //
  // The request:
  // * |length_seconds| - length of time to run the routine for.
  // * |maximum_discharge_percent_allowed| - the routine will fail if the
  //                                         battery discharges by more than
  //                                         this percentage.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunBatteryDischargeRoutine@13(uint32 length_seconds,
                             uint32 maximum_discharge_percent_allowed)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the BatteryCharge routine is created and started on the
  // platform. This routine checks the battery's charge rate over a period of
  // time.
  // The availability of this routine can be determined by checking that
  // kBatteryCharge is returned by GetAvailableRoutines.
  //
  // The request:
  // * |length_seconds| - length of time to run the routine for.
  // * |minimum_charge_percent_required| - the routine will fail if the battery
  //                                       charges by less than this percentage.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunBatteryChargeRoutine@14(uint32 length_seconds,
                          uint32 minimum_charge_percent_required)
      => (DiagnosticsRunRoutineResponse response);

  // Requests that the Memory routine is created and started on the platform.
  // This routine checks that the device's memory is working correctly.
  // The availability of this routine can be determined by checking that
  // kMemory is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunMemoryRoutine@15() => (DiagnosticsRunRoutineResponse response);

  // Requests that the LanConnectivity routine is created and started on the
  // platform. This routine checks whether the device is connected to a LAN.
  // The availability of this routine can be determined by checking that
  // kLanConnectivity is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunLanConnectivityRoutine@16() => (DiagnosticsRunRoutineResponse response);

  // TODO(b/245293243): Rephrase to express sufficiency instead of necessity.
  // Requests that the DnsResolution routine is created and started on the
  // platform. This routine checks whether a DNS resolution can be completed
  // successfully.
  // The availability of this routine can be determined by checking that
  // kDnsResolution is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunDnsResolutionRoutine@17() => (DiagnosticsRunRoutineResponse response);
  
  // Requests that the SignalStrength routine is created and started on the
  // platform. This routine checks whether there is an acceptable signal
  // strength on wireless networks.
  // The availability of this routine can be determined by checking that
  // kSignalStrength is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunSignalStrengthRoutine@18() => (DiagnosticsRunRoutineResponse response);

  // TODO(b/245293243): Rephrase to express sufficiency instead of necessity.
  // Requests that the GatewayCanBePinged routine is created and started on the
  // platform. This routine checks whether the gateway of connected networks is
  // pingable.
  // The availability of this routine can be determined by checking that
  // kGatewayCanBePinged is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunGatewayCanBePingedRoutine@19() => (DiagnosticsRunRoutineResponse response);

  // TODO(b/245293243): Rephrase to express sufficiency instead of necessity.
  // Requests that the DnsResolverPresent routine is created and started on the
  // platform. This routine checks whether a DNS resolver is available to the
  // browser.
  // The availability of this routine can be determined by checking that
  // kDnsResolverPresent is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunDnsResolverPresentRoutine@20() => (DiagnosticsRunRoutineResponse response);

  // Requests that the SensitiveSensor routine is created and started on the
  // platform. This routine checks that the device's sensors are working
  // correctly by monitoring the sensor sample data without user interaction.
  // This routine only support sensitive sensors including accelerometers,
  // gyro sensors, gravity sensors and magnetometers.
  // The availability of this routine can be determined by checking that
  // kSensitiveSensor is returned by GetAvailableRoutines.
  //
  // The response:
  // * |response| - contains a unique identifier and status for the created
  //                routine.
  RunSensitiveSensorRoutine@21()
      => (DiagnosticsRunRoutineResponse response);
};

// Enumeration of each of the diagnostics routines the platform may support.
//
// Next ID: 21
[Stable, Extensible, RenamedFrom="ash.health.mojom.DiagnosticRoutineEnum"]
enum DiagnosticsRoutineEnum {
  [Default] kUnknown = 15,
  kBatteryCapacity = 0,
  kBatteryHealth = 1,
  kSmartctlCheck = 2,
  kAcPower = 3,
  kCpuCache = 4,
  kCpuStress = 5,
  kFloatingPointAccuracy = 6,
  kNvmeWearLevel = 7,
  kNvmeSelfTest = 8,
  kDiskRead = 9,
  kPrimeSearch = 10,
  kBatteryDischarge = 11,
  kBatteryCharge = 12,
  kMemory = 13,
  kLanConnectivity = 14,
  kDnsResolution = 16,
  kSignalStrength = 17,
  kGatewayCanBePinged = 18,
  kDnsResolverPresent = 19,
  kSensitiveSensor = 20,
};

// Enumeration of each of the possible statuses for a diagnostics routine.
//
// Next ID: 13
[Stable, Extensible, RenamedFrom="ash.health.mojom.DiagnosticRoutineStatusEnum"]
enum DiagnosticsRoutineStatusEnum {
  [Default] kUnknown = 12,
  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.
  kCancelling = 9,  // Routine is in the process of being cancelled.
  kUnsupported = 10,  // Routine is not supported by the device.
  kNotRun = 11,  // Routine was not run because it is currently not applicable.
};

// Enumeration of each of the messages a diagnostics routine can pass back.
// These messages prompt interaction from the user of the routine.
//
// Next ID: 3
[Stable, Extensible,
RenamedFrom="ash.health.mojom.DiagnosticRoutineUserMessageEnum"]
enum DiagnosticsRoutineUserMessageEnum {
  [Default] kUnknown = 2,
  kUnplugACPower = 0,  // The user needs to unplug the AC power cord.
  kPlugInACPower = 1,  // The user needs to plug in the AC power cord.
};

// Enumeration of the possible commands to send a diagnostics routine.
//
// Next ID: 5
[Stable, Extensible,
RenamedFrom="ash.health.mojom.DiagnosticRoutineCommandEnum"]
enum DiagnosticsRoutineCommandEnum {
  [Default] kUnknown = 4,
  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.
};

// Status fields specific to interactive routines.
//
// Next ID: 1
[Stable, RenamedFrom="ash.health.mojom.InteractiveRoutineUpdate"]
struct DiagnosticsInteractiveRoutineUpdate {
  // Request for user action. This message should be localized and displayed to
  // the user.
  DiagnosticsRoutineUserMessageEnum user_message@0;
};

// Status fields specific to noninteractive routines.
//
// Next ID: 2
[Stable, RenamedFrom="ash.health.mojom.NonInteractiveRoutineUpdate"]
struct DiagnosticsNonInteractiveRoutineUpdate {
  // Current status of the routine.
  DiagnosticsRoutineStatusEnum status@0;
  // More detailed status - for example, if |status| was kError,
  // |status_message| would describe the error encountered, like "failed to
  // read file."
  string status_message@1;
};

// Responses will be either interactive or noninteractive.
[Stable, RenamedFrom="ash.health.mojom.RoutineUpdateUnion"]
union DiagnosticsRoutineUpdateUnion {
  DiagnosticsInteractiveRoutineUpdate interactive_update;
  DiagnosticsNonInteractiveRoutineUpdate noninteractive_update;
};

// Response type for GetRoutineUpdate.
//
// Next ID: 3
[Stable, RenamedFrom="ash.health.mojom.RoutineUpdate"]
struct DiagnosticsRoutineUpdate {
  // Percent complete, must be between 0 and 100, inclusive.
  uint32 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.
  string? output@1;

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

// Generic return value for a RunSomeRoutine call.
//
// Next ID: 2
[Stable, RenamedFrom="ash.health.mojom.RunRoutineResponse"]
struct DiagnosticsRunRoutineResponse {
  // Unique identifier for the newly-created routine. An id of kFailedToStartId
  // means that the routine was unable to be created. Can be used in a
  // GetRoutineUpdate call to control or get the status of the created routine.
  int32 id@0;
  // Current status of the newly-created routine. A status of kFailedToStart
  // means the routine was unable to be created.
  DiagnosticsRoutineStatusEnum status@1;
};

// Enumeration of the possible statuses for a power supply in the AC power
// routine.
//
// Next ID: 3
[Stable, Extensible, RenamedFrom="ash.health.mojom.AcPowerStatusEnum"]
enum DiagnosticsAcPowerStatusEnum {
  [Default] kUnknown = 2,
  kConnected = 0,     // Power supply is connected.
  kDisconnected = 1,  // Power supply is disconnected.
};

// Enumeration of the self-test type in nvme_self_test routine
//
// Next ID: 3
[Stable, Extensible, RenamedFrom="ash.health.mojom.NvmeSelfTestTypeEnum"]
enum DiagnosticsNvmeSelfTestTypeEnum {
  [Default] kUnknown = 2,
  kShortSelfTest = 0, // Short time self-test.
  kLongSelfTest = 1,  // Long time self-test.
};

// Enumeration of the possible DiskRead routine's command type
[Stable, Extensible, RenamedFrom="ash.health.mojom.DiskReadRoutineTypeEnum"]
enum DiagnosticsDiskReadRoutineTypeEnum {
  kLinearRead = 0,
  kRandomRead = 1,
  // Sending this to the underlying cros_healthd will result in an error.
  [Default] kUnknown = 2,
};