diagnostics/mojo/cros_healthd_probe.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 probe API exposed by the cros_healthd daemon. This API is
// normally consumed by the browser.

// 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_probe.mojom.

module chromeos.cros_healthd.mojom;

import "mojo/network_health.mojom";
import "mojo/nullable_primitives.mojom";

// An enumeration of CPU architectures.
[Extensible]
enum CpuArchitectureEnum {
  kUnknown,
  kX86_64,
  kAArch64,
  kArmv7l,
};

// An enumeration of each category of information that cros_healthd can report.
[Extensible]
enum ProbeCategoryEnum {
  kBattery,
  kNonRemovableBlockDevices,
  kCpu,
  kTimezone,
  kMemory,
  kBacklight,
  kFan,
  kStatefulPartition,
  kBluetooth,
  kSystem,
  kNetwork,
};

// An enumeration of the different categories of errors that can occur when
// probing telemetry information.
[Extensible]
enum ErrorType {
  // An error reading a system file.
  kFileReadError,
  // An error parsing data into a consumable form.
  kParseError,
  // An error using a system utility.
  kSystemUtilityError,
  // The external service used to probe the information is not available.
  kServiceUnavailable,
};

// Structure that contains error information for a telemetry probe.
struct ProbeError {
  // The type of error that occurred.
  ErrorType type;
  // A debug message with more information about the error. This string is not
  // intended to be shown to the user.
  string msg;
};

// An enumeration of states a process can be in.
[Extensible]
enum ProcessState {
  // The process is running.
  kRunning,
  // The process is sleeping in an interruptible wait.
  kSleeping,
  // The process is waiting in an uninterruptible disk sleep.
  kWaiting,
  // The process is a zombie.
  kZombie,
  // The process is stopped on a signal.
  kStopped,
  // The process is stopped by tracing.
  kTracingStop,
  // The process is dead.
  kDead,
};

// Process probe result. Can either be populated with the ProcessInfo or an
// error retrieving the information.
union ProcessResult {
  // Valid ProcessInfo.
  ProcessInfo process_info;
  // The error that occurred attempting to retrieve the ProcessInfo.
  ProbeError error;
};

// Information related to a particular process.
struct ProcessInfo {
  // Command which started the process.
  string command;
  // User the process is running as.
  uint32 user_id;
  // If the process is running a real-time scheduling policy, this field is the
  // negated scheduling priority, minus one. Real-time priorities range from 1
  // to 99, so this will range from -2 to -100. If the process is not running a
  // real-time scheduling priority, this field will be the raw nice value, where
  // 0 corresponds to the user-visible high priority nice value of -20, and 39
  // corresponds to the user-visible low priority nice value of 19.
  int8 priority;
  // User-visible nice value of the process, from a low priority of 19 to a high
  // priority of -20.
  int8 nice;
  // Uptime of the process, in clock ticks.
  uint64 uptime_ticks;
  // State of the process.
  ProcessState state;
  // Total memory allocated to the process, in KiB.
  uint32 total_memory_kib;
  // Amount of resident memory currently used by the process, in KiB.
  uint32 resident_memory_kib;
  // Unused memory available to the process, in KiB. This will always be
  // |total_memory_kib| - |resident_memory_kib|.
  uint32 free_memory_kib;
};

// Battery probe result. Can either be populated with the BatteryInfo or an
// error retrieving the information.
union BatteryResult {
  // Valid BatteryInfo. Null value if a battery is not present.
  BatteryInfo? battery_info;
  // The error that occurred attempting to retrieve the BatteryInfo.
  ProbeError error;
};

// Information related to the main battery.
struct BatteryInfo {
  // TODO(https://crbug.com/979245): Update "smart" cycle count.
  int64 cycle_count;
  // Current battery voltage (V)
  double voltage_now;
  // Manufacturer of the battery
  string vendor;
  // Serial number of the battery
  string serial_number;
  // Design capacity (Ah)
  double charge_full_design;
  // Full capacity (Ah)
  double charge_full;
  // Desired minimum output voltage (V)
  double voltage_min_design;
  // Model name.
  string model_name;
  // Current battery charge (Ah)
  double charge_now;
  // Current battery current (A)
  double current_now;
  // Technology of the battery
  string technology;
  // Status of the battery
  string status;

  // The fields below are optionally included if the main battery is a Smart
  // Battery as defined in http://sbs-forum.org/specs/sbdat110.pdf.

  // Manufacture date converted to yyyy-mm-dd format.
  string? manufacture_date;
  // Temperature in 0.1K. Included when the main battery is a Smart Battery.
  NullableUint64? temperature;
};

// Non-removable block device probe result. Can either be populated with the
// NonRemovableBlockDeviceInfo or an error retrieving the information.
union NonRemovableBlockDeviceResult {
  // Valid NonRemovableBlockDeviceInfo.
  array<NonRemovableBlockDeviceInfo> block_device_info;
  // The error that occurred attempting to retrieve the
  // NonRemovableBlockDeviceInfo.
  ProbeError error;
};

// Unions for device-specific data fields. |other| is provided by the default
// data adapter and filled with a default value for the unknown device type.

// The manufacturer of the block device.
union BlockDeviceVendor {
  uint32 nvme_subsystem_vendor;
  uint16 emmc_oemid;
  uint16 other;
};

// The manufacturer-specific product identifier.
union BlockDeviceProduct {
  uint32 nvme_subsystem_device;
  uint64 emmc_pnm;
  uint16 other;
};

// The revision of the device's hardware.
union BlockDeviceRevision {
  uint8 nvme_pcie_rev;
  uint8 emmc_prv;
  uint16 other;
};

// The revision of the device's firmware.
union BlockDeviceFirmware {
  uint64 nvme_firmware_rev;
  uint64 emmc_fwrev;
  uint16 other;
};

// Purpose of the storage device.
[Extensible]
enum StorageDevicePurpose {
  kUnknown,
  kBootDevice,
  kSwapDevice,
};

// Information related to a specific non-removable block device.
struct NonRemovableBlockDeviceInfo {
  // IO statistics

  // Bytes read since last boot.
  uint64 bytes_read_since_last_boot;
  // Bytes written since last boot.
  uint64 bytes_written_since_last_boot;
  // Time spent reading since last boot.
  uint64 read_time_seconds_since_last_boot;
  // Time spent writing since last boot.
  uint64 write_time_seconds_since_last_boot;
  // Time spent doing I/O since last boot. Counts the time the disk and queue
  // were busy, so unlike the fields above, parallel requests are not counted
  // multiple times.
  uint64 io_time_seconds_since_last_boot;
  // Time spent discarding since last boot. Discarding is writing to clear
  // blocks which are no longer in use. Supported on kernels 4.18+.
  NullableUint64? discard_time_seconds_since_last_boot;

  // Device identification.

  // Device vendor identification.
  BlockDeviceVendor vendor_id;
  // Device product identification.
  BlockDeviceProduct product_id;
  // Device revision.
  BlockDeviceRevision revision;
  // Device model.
  string name;
  // Device size in bytes.
  uint64 size;
  // Firmware version.
  BlockDeviceFirmware firmware_version;
  // Storage type, could be MMC / NVMe / ATA, based on udev subsystem.
  string type;
  // Purpose of the device e.g. "boot", "swap".
  StorageDevicePurpose purpose;

  // Additional identification.

  // The path of this storage on the system. It is useful if caller needs to
  // correlate with other information.
  string path;
  // Manufacturer ID, 8 bits.
  uint8 manufacturer_id;
  // PSN: Product serial number, 32 bits
  uint32 serial;
};

// CPU probe result. Can either be populated with the CpuInfo or an error
// retrieving the information.
union CpuResult {
  // Valid CpuInfo.
  CpuInfo cpu_info;
  // The error that occurred attempting to retrieve the CpuInfo.
  ProbeError error;
};

// Information about the device's CPUs.
struct CpuInfo {
  // Number of total threads available.
  uint32 num_total_threads;
  // The CPU architecture - it's assumed all of a device's CPUs share an
  // architecture.
  CpuArchitectureEnum architecture;
  // Information about the device's physical CPUs.
  array<PhysicalCpuInfo> physical_cpus;
  // Information about the CPU temperature channels.
  array<CpuTemperatureChannel> temperature_channels;
};

// Information related to a particular physical CPU.
struct PhysicalCpuInfo {
  // The CPU model name, if available.
  string? model_name;
  // Logical CPUs corresponding to this physical CPU.
  array<LogicalCpuInfo> logical_cpus;
};

// Information related to a particular logical CPU.
struct LogicalCpuInfo {
  // The max CPU clock speed in kHz.
  uint32 max_clock_speed_khz;
  // Maximum frequency the CPU is allowed to run at, by policy.
  uint32 scaling_max_frequency_khz;
  // Current frequency the CPU is running at.
  uint32 scaling_current_frequency_khz;
  // Time spent in user mode since last boot. USER_HZ can be converted to
  // seconds with the conversion factor given by sysconf(_SC_CLK_TCK).
  uint64 user_time_user_hz;
  // Time spent in system mode since last boot. USER_HZ can be converted to
  // seconds with the conversion factor given by sysconf(_SC_CLK_TCK).
  uint64 system_time_user_hz;
  // Idle time since last boot. USER_HZ can be converted to seconds with the
  // conversion factor given by sysconf(_SC_CLK_TCK).
  uint32 idle_time_user_hz;
  // Information about the logical CPU's time in various C-states.
  array<CpuCStateInfo> c_states;
};

// Information about a CPU's C-states.
struct CpuCStateInfo {
  // Name of the state.
  string name;
  // Time spent in the state since the last reboot, in microseconds.
  uint64 time_in_state_since_last_boot_us;
};

// Information about a single CPU temperature channel.
struct CpuTemperatureChannel {
  // Temperature channel label, if found on the device.
  string? label;
  // CPU temperature in Celsius.
  int32 temperature_celsius;
};

// Timezone probe result. Can either be populated with the TimezoneInfo or an
// error retrieving the information.
union TimezoneResult {
  // Valid TimezoneInfo.
  TimezoneInfo timezone_info;
  // The error that occurred attempting to retrieve the TimezoneInfo.
  ProbeError error;
};

// Timezone information.
struct TimezoneInfo {
  // The timezone of the device in POSIX standard.
  string posix;
  // The timezone region of the device.
  string region;
};

// Memory probe result. Can either be populated with the MemoryInfo or an
// error retrieving the information.
union MemoryResult {
  // Valid MemoryInfo.
  MemoryInfo memory_info;
  // The error that occurred attempting to retrieve the MemoryInfo.
  ProbeError error;
};

// Memory information.
struct MemoryInfo {
  // Total memory, in KiB.
  uint32 total_memory_kib;
  // Free memory, in KiB.
  uint32 free_memory_kib;
  // Available memory, in KiB.
  uint32 available_memory_kib;
  // Number of page faults since the last boot.
  uint32 page_faults_since_last_boot;
};

// Backlight probe result. Can either be populated with the BacklightInfo or an
// error retrieving the information.
union BacklightResult {
  // Valid BacklightInfo.
  array<BacklightInfo> backlight_info;
  // The error that occurred attempting to retrieve the BacklightInfo.
  ProbeError error;
};

// Backlight information.
struct BacklightInfo {
  // Path to this backlight on the system. Useful if the caller needs to
  // correlate with other information.
  string path;
  // Maximum brightness for the backlight.
  uint32 max_brightness;
  // Current brightness of the backlight, between 0 and max_brightness.
  uint32 brightness;
};

// Fan probe result. Can either be populated with the FanInfo or an error
// retrieving the information
union FanResult {
  // A list of valid FanInfo.
  array<FanInfo> fan_info;
  // The error that occurred attempting to retrieve the FanInfo.
  ProbeError error;
};

// Fan information.
struct FanInfo {
  // Fan speed in RPM.
  uint32 speed_rpm;
};

// Stateful partition probe result. Can either be populated with a valid
// StatefulPartitionInfo or an error retrieving the information.
union StatefulPartitionResult {
  // A valid StatefulPartitionInfo.
  StatefulPartitionInfo partition_info;
  // The error that occurred attempting to retrieve the StatefulPartitionInfo.
  ProbeError error;
};

// Stateful partition info
struct StatefulPartitionInfo {
  // Available space for user data storage in the device in bytes.
  uint64 available_space;
  // Total space for user data storage in the device in bytes.
  uint64 total_space;
};

// Bluetooth probe result. Can either be populated with the BluetoothAdapterInfo
// or an error retrieving the information.
union BluetoothResult {
  // Valid BluetoothAdapterInfo.
  array<BluetoothAdapterInfo> bluetooth_adapter_info;
  // The error that occurred attempting to retrieve the BluetoothAdapterInfo.
  ProbeError error;
};

// Information related to one of a device's Bluetooth adapters.
struct BluetoothAdapterInfo {
  // The name of the adapter.
  string name;
  // The MAC address of the adapter.
  string address;
  // Indicates whether the adapter is on or off.
  bool powered;
  // The number of devices connected to this adapter.
  uint32 num_connected_devices;
};

// System probe result. Can either be populated with the SystemInfo or an error
// retrieving the information.
union SystemResult {
  // Valid SystemInfo.
  SystemInfo system_info;
  // The error that occurred attempting to retrieve SystemInfo.
  ProbeError error;
};

// Structure containing information about the operating system version of the
// device. This structure decomposes a full version string into its parts:
// (87.13544.59.0).
struct OsVersion {
  // The OS version release milestone (87).
  string release_milestone;
  // The OS version build number (13544).
  string build_number;
  // The OS version patch number (59.0).
  string patch_number;
  // The OS release channel (stable-channel).
  string release_channel;
};

// System Information.
struct SystemInfo {
  // The date the device was first activated.
  // Format: YYYY-WW.
  string? first_power_date;
  // The date the device was manufactured (finalized in factory).
  // Format: YYYY-MM-DD.
  string? manufacture_date;
  // The product SKU number.
  string? product_sku_number;
  // The product serial number.
  string? product_serial_number;
  // The product model name.
  string? product_model_name;
  // Contents of CrosConfig in /arc/build-properties/marketing-name.
  string marketing_name;
  // The BIOS version.
  string? bios_version;
  // The product name of the motherboard.
  string? board_name;
  // The version of the motherboard.
  string? board_version;
  // The chassis type of the device. The values reported by chassis type are
  // mapped in
  // www.dmtf.org/sites/default/files/standards/documents/DSP0134_3.0.0.pdf.
  NullableUint64? chassis_type;
  // The product name (model) of the system.
  string? product_name;
  // The OS version of the system.
  OsVersion os_version;
};

// Network probe result. Can either be populated with the NetworkHealthSnapshot
// or an error retrieving the information.
union NetworkResult {
  // Valid NetworkHealthSnapshot.
  chromeos.network_health.mojom.NetworkHealthState network_health;
  // The error that occurred attempting to retrieve the NetworkHealthSnapshot.
  ProbeError error;
};

// A collection of all the device's telemetry information that cros_healthd is
// capable of reporting. Note that every field in TelemetryInfo is nullable, and
// the response for a particular ProbeTelemetryInfo request will only contain
// fields corresponding to the categories passed to the ProbeTelemetryInfo
// request. All optional array members will be null if cros_healthd did not
// attempt to fetch that information, and size zero if cros_healthd did attempt
// to fetch that information, but was unable to.
struct TelemetryInfo {
  // Information about the device's main battery. Only present when kBattery was
  // included in the categories input to ProbeTelemetryInfo.
  BatteryResult? battery_result;
  // Information about all of the device's non-removable block devices. Only
  // present when kNonRemovableBlockDevices was included in the categories input
  // to ProbeTelemetryInfo.
  NonRemovableBlockDeviceResult? block_device_result;
  // Information about each of the device's CPUs. Only present when kCpu was
  // included in the categories input to ProbeTelemetryInfo.
  CpuResult? cpu_result;
  // Information about the device's timezone. Only present when kTimezone was
  // included in the categories input to ProbeTelemetryInfo.
  TimezoneResult? timezone_result;
  // Information about the system's memory. Only present when kMemory was
  // included in the categories input to ProbeTelemetryInfo.
  MemoryResult? memory_result;
  // Information about all of the device's backlights. Only present when
  // kBacklight was included in the categories input to ProbeTelemetryInfo.
  BacklightResult? backlight_result;
  // Information about each of the device's fans. Only present when kFan was
  // included in the categories input to ProbeTelemetryInfo.
  FanResult? fan_result;
  // Information about the stateful partition. Only present when
  // kStatefulPartition was included in the categories input to
  // ProbeTelemetryInfo.
  StatefulPartitionResult? stateful_partition_result;
  // Information about the device's Bluetooth adapters and devices. Only present
  // when kBluetooth was included in the categories input to ProbeTelemetryInfo.
  BluetoothResult? bluetooth_result;
  // Information about the system. Only present when kSystem was included in the
  // categories input to ProbeTelemetryInfo.
  SystemResult? system_result;
  // Information about the networking devices and associated networks of the
  // system. Only present when kNetwork was included in the categories input to
  // ProbeTelemetryInfo.
  NetworkResult? network_result;
};