tlbmc/thermal_config.proto

edition = "2023";

package milotic_tlbmc;

// The config of thermal zone debug mode.
message ThermalDebugModeConfig {
  bool tuning_enabled = 1 [deprecated = true];
  bool debug_enabled = 2 [default = false];
  bool debug_pid_enabled = 3 [default = false];
  bool debug_dff_enabled = 4 [default = false];
}

// The sensor info needed by a PID controller.
message PidControllerSensorInfo {
  string sensor_key = 1;
  // `max_junction_temperature` is `Tjmax`, the hottest temperature a CPU can
  // operate at before it begins thermal throttling to reduce performance and
  // prevent damage. It must be explicitly specified for a margin PID sensor.
  double max_junction_temperature = 2 [default = 0];
  bool convert_temperature_to_margin = 3 [default = false];
}

// The sensor info needed by a zone manager.
message ZoneManagerSensorInfo {
  string sensor_key = 1;
  bool is_missing_acceptable = 2 [default = false];
  // The scale factor to apply to sensor readings. The eventual sensor reading
  // value used by the thermal loop will be: `reading * pow(10, scale)`.
  double scale = 3 [default = 0];
  double failsafe_percent = 4 [default = 100];
  // For a sensor reading outside the critical thresholds, failsafe mode will be
  // triggered for the zones owning that sensor.
  double max_threshold_critical = 5;
  double min_threshold_critical = 6;
}

message ZoneManagerFanInfo {
  string fan_name = 1;
  double failsafe_percent = 2 [default = 100];
  // If the fan speed to be written is outside the critical thresholds, failsafe
  // mode will be triggered for the zone try to write that fan speed.
  double max_threshold_critical = 3 [default = 255];
  double min_threshold_critical = 4 [default = 0];
}

// The config of thermal zone managers.
message ZoneManagerConfig {
  int32 id = 1;
  double setpoint_upper_bound = 2;
  double setpoint_lower_bound = 3;
  double minimum_thermal_setpoint = 4;
  double zone_failsafe_percent = 5 [default = 100];
  ThermalDebugModeConfig debug_mode = 6;
  // The time interval in milliseconds between two fan cycles.
  uint64 ms_per_fan_cycle = 7 [default = 100];
  // The time interval in milliseconds between two thermal cycles.
  uint64 ms_per_thermal_cycle = 8 [default = 1000];
  repeated ZoneManagerSensorInfo input_sensors = 9;
  repeated ZoneManagerFanInfo output_fans = 10;
}

// The config of nonlinear tracking differentiator (NTD).
message NonlinearTrackingDifferentiatorConfig {
  // Sample time in seconds.
  double sample_time_sec = 1 [default = 1];
  // `r` is the tracking speed of the NTD.
  double r = 2;
  // `h0` is the filtering chronometer of the NTD.
  double h0 = 3;
  double initial_filtered_output = 4 [default = 0];
  double initial_filtered_derivative = 5 [default = 0];
}

// The config of explicitly quantifiable disturbances in ADRC to improve control
// accuracy.
message QuantifiableDisturbance {
  // Control gain for this disturbance.
  double d = 1 [default = 0];
  double reference_setpoint = 2 [default = 0];
  // Source sensors for this disturbance.
  repeated string input_sensors = 3;
}

// The config of 1st-Order Active Disturbance Rejection Control (ADRC) thermal
// loops.
message FirstOrderAdrcLoopConfig {
  // Sample time in seconds.
  double sample_time_sec = 1 [default = 1];
  // Settling time in seconds.
  // The target time for the closed-loop system to reach the reference value
  // within a 2% error margin.
  double settle_time_sec = 2 [default = 1];
  // Control gain for current disturbance.
  double b0 = 3 [default = 0];
  // The observer bandwidth factor.
  // 5 by default, so that the algorithm will have, normally, enough time to
  // react to the disturbance.
  double observer_bandwidth_factor = 4 [default = 5];
  // Actuator saturation limits
  double u_limit_max = 5 [default = 0];
  double u_limit_min = 6 [default = 0];
  // Note that NTD is optional to be used in the ADRC loop.
  NonlinearTrackingDifferentiatorConfig
      nonlinear_tracking_differentiator_config = 7;
}

// The config of 2nd-Order Active Disturbance Rejection Control (ADRC) thermal
// loops.
message SecondOrderAdrcLoopConfig {
  // Sample time in seconds.
  double sample_time_sec = 1 [default = 1];
  // Settling time in seconds.
  // The target time for the closed-loop system to reach the reference value
  // within a 2% error margin.
  double settle_time_sec = 2 [default = 1];
  // Control gain for current disturbance.
  double b0 = 3 [default = 0];
  // The observer bandwidth factor.
  // 5 by default, so that the algorithm will have, normally, enough time to
  // react to the disturbance.
  double observer_bandwidth_factor = 4 [default = 5];
  // Actuator saturation limits
  double u_limit_max = 5 [default = 0];
  double u_limit_min = 6 [default = 0];
  // Note that NTD is optional to be used in the ADRC loop.
  NonlinearTrackingDifferentiatorConfig
      nonlinear_tracking_differentiator_config = 7;
}

// The config of Proportional-Integral-Derivative (PID) thermal loops.
message PidLoopConfig {
  // Sample time in seconds.
  double sample_time_sec = 1 [default = 1];
  // Coefficient for P (proportional gain), aka Kp.
  double coeff_proportional = 2 [default = 0];
  // Coefficient for I (integral gain), aka Ki.
  double coeff_integral = 3 [default = 0];
  // Coefficient for D (derivative gain), aka Kd.
  double coeff_derivative = 4 [default = 0];
  // Offset coeff for feed-forward term.
  double feed_forward_offset = 5 [default = 0];
  // Gain for feed-forward term.
  double feed_forward_gain = 6 [default = 0];
  // Clamp of integral value upper bound.
  double integral_limit_max = 7 [default = 0];
  // Clamp of integral value lower bound.
  double integral_limit_min = 8 [default = 0];
  // Clamp of output value upper bound.
  double output_limit_max = 9 [default = 0];
  // Clamp of output value lower bound.
  double output_limit_min = 10 [default = 0];
  // Negative slew rate.
  double slew_neg = 11 [default = 0];
  // Positive slew rate.
  double slew_pos = 12 [default = 0];
  // Negative hysteresis.
  double hysteresis_neg = 13 [default = 0];
  // Positive hysteresis.
  double hysteresis_pos = 14 [default = 0];
  // Compare current input and setpoint to check hysteresis.
  // If this is true, the hysteresis check will be performed regardless of the
  // value of `hysteresis_pos` and `hysteresis_neg`. If this is false, input
  // hysteresis check will be performed if any of `hysteresis_pos` and
  // `hysteresis_neg` is significant.
  bool check_hysteresis_with_setpoint = 15 [default = false];
}

// The the input process type of PID thermal controllers.
enum PidControllerInputProcessType {
  UNSUPPORTED_PID = 0;
  MARGIN_PID = 1;
  TEMP_PID = 2;
  POWER_PID = 3;
  POWERSUM_PID = 4;
}

// The config of PID thermal controllers.
message PidControllerConfig {
  // The ID of the PID controller.
  string id = 1;
  // The config of the PID loop.
  PidLoopConfig pid_loop_config = 2;
  // The ID of the owner zone manager.
  repeated int32 zone_manager_id = 3;
  double setpoint = 4;
  PidControllerInputProcessType input_process_type = 5;
  repeated PidControllerSensorInfo input_sensors = 6;
  PidTunerConfig pid_autotuner_config = 7;
}

// The config of fan PID thermal controllers.
message FanPidControllerConfig {
  // The ID of the fan PID controller.
  string id = 1;
  // The config of the PID loop.
  PidLoopConfig pid_loop_config = 2;
  // The ID of the owner zone manager.
  repeated int32 zone_manager_id = 3;
  repeated string input_fans = 4;
  repeated string output_fans = 5;
}

// The critical point of stepwise thermal loops.
message StepwiseCriticalPoint {
  // The threshold value.
  double threshold = 1;
  // The output value.
  double stepwise_output = 2;
}

// The config of stepwise thermal loops.
message StepwiseLoopConfig {
  // Sample time in seconds.
  double sample_time_sec = 1 [default = 1];
  // Enumerated list of threshold values with its corresponding output value.
  // The threshold values must be monotonically increasing.
  repeated StepwiseCriticalPoint critical_points = 2;
  // How much the input value must raise to allow the switch to the next step.
  double positive_hysteresis = 3 [default = 0];
  // How much the input value must drop to allow the switch to the previous
  // step.
  double negative_hysteresis = 4 [default = 0];
  // Whether this controller provides a setpoint or a ceiling for the zone.
  bool is_ceiling = 5 [default = false];
}

// The config of stepwise thermal controllers.
message StepwiseControllerConfig {
  // The ID of the stepwise controller.
  string id = 1;
  // The config of the stepwise loop.
  StepwiseLoopConfig stepwise_loop_config = 2;
  // The ID of the owner zone manager.
  repeated int32 zone_manager_id = 3;
  // Whether this controller provides a setpoint or a ceiling for the zone.
  bool is_ceiling = 4;
  repeated string input_sensors = 5;
}

// The config of Dynamic Feedforward (DFF) thermal loops.
message DffLoopConfig {
  // Sample time in seconds.
  double sample_time_sec = 1 [default = 1];
  // Coefficient of disturbance when applying low pass filter.
  double coeff_h1 = 2 [default = 0];
  // Coefficient of previous disturbance when applying low pass filter.
  double coeff_h2 = 3 [default = 0];
  // Coefficient of previous filtered disturbance when applying low pass filter.
  double coeff_h3 = 4 [default = 0];
  // Coefficient of current disturbance input. This is the coefficient for the
  // current disturbance input. For example, a large positive value here will
  // cause an immediate and large response to a sudden change in chip power.
  double coeff_f1 = 5 [default = 0];
  // Coefficient of previous disturbance input. This is the coefficient for the
  // previous disturbance input. Its value and its sign are crucial for shaping
  // the output response.
  double coeff_f2 = 6 [default = 0];
  // Coefficient of previous output. This is the coefficient for the previous
  // output. It acts as a feedback term within the feedforward controller
  // itself. It determines how long the effect of a disturbance persists.
  double coeff_f3 = 7 [default = 0];
  // Clamp of output value upper bound.
  double output_limit_max = 8;
  // Clamp of output value lower bound.
  double output_limit_min = 9;
  // Refernece power is the nominal workload power. This variable acts as a
  // setpoint or baseline offset for the disturbance input in the feedforward
  // controller equation. It ensures the DFF controller only reacts to the
  // change in power relative to that baseline, not the absolute power value
  // itself.
  double reference_power = 10;
  // Negative slew rate. It has to be less than -1.0 to be significant.
  double slew_neg = 11 [default = 0];
  // Positive slew rate. It has to be greater than 1.0 to be significant.
  double slew_pos = 12 [default = 0];
}

// The config of DFF thermal controllers.
message DffControllerConfig {
  // The ID of the DFF controller.
  string id = 1;
  // The config of the DFF loop.
  DffLoopConfig dff_loop_config = 2;
  // The ID of the owner zone manager.
  repeated int32 zone_manager_id = 3;
  repeated string input_sensors = 4;
  // The IDs of the controllers affected by this DFF controller.
  repeated string affected_controller_ids = 5;
}

// The config of Entering Air Temperature (EAT) thermal loops.
message EatLoopConfig {
  // Negative slew rate. -1 by default.
  double slew_neg = 1 [default = -1];
  // Positive slew rate. 1 by default.
  double slew_pos = 2 [default = 1];
  // The max EAT output limit (i.e., max setpoint offset).
  double output_limit_max = 3;
  // The min EAT output limit (i.e., min setpoint offset).
  double output_limit_min = 4;
  // Calculation interval in hours. 24 by default.
  uint32 calculation_interval_hour = 5 [default = 24];
  // Reference entering air temperature.
  double reference_eat = 6;
}

// The config of EAT thermal controllers.
message EatControllerConfig {
  // The ID of the EAT controller.
  string id = 1;
  // The config of the EAT loop.
  EatLoopConfig eat_loop_config = 2;
  // The ID of the owner zone manager.
  repeated int32 zone_manager_id = 3;
  repeated string input_sensors = 4;
  // The IDs of thermal zones affected by this EAT controller.
  repeated int32 affected_zone_ids = 5;
}

// The config of 1st-order ADRC thermal controllers.
message FirstOrderAdrcControllerConfig {
  // The ID of the 1st-order ADRC controller.
  string id = 1;
  // The config of the 1st-order ADRC loop.
  FirstOrderAdrcLoopConfig first_order_adrc_loop_config = 2;
  // The ID of the owner zone manager.
  repeated int32 zone_manager_id = 3;
  double setpoint = 4;
  repeated string input_sensors = 5;
}

// The config of 2nd-order ADRC thermal controllers.
message SecondOrderAdrcControllerConfig {
  // The ID of the 2nd-order ADRC controller.
  string id = 1;
  // The config of the 2nd-order ADRC loop.
  SecondOrderAdrcLoopConfig second_order_adrc_loop_config = 2;
  // The ID of the owner zone manager.
  repeated int32 zone_manager_id = 3;
  double setpoint = 4;
  repeated string input_sensors = 5;
  repeated QuantifiableDisturbance quantifiable_disturbances = 6;
}

// The config of zone managers that does not maniopulate hardware directly.
// Such a zone manager is usually used for processing supportive thermal
// loops that does not contribute directly to the fan speed output (e.g., EAT).
message SupportiveZoneManagerConfig {
  int32 id = 1;
  ThermalDebugModeConfig debug_mode = 2;
  // The time interval in milliseconds between two thermal cycles.
  uint64 ms_per_thermal_cycle = 3;
  repeated ZoneManagerSensorInfo input_sensors = 4;
}

message FailsafeLoggerConfig {
  // The maximum number of failsafe logs to be output per zone within 1 second.
  uint32 failsafe_log_limit_per_second = 7;
}

message ZoneManagerConfigs {
  repeated ZoneManagerConfig zone_manager_configs = 1;
}

message SupportiveZoneManagerConfigs {
  repeated SupportiveZoneManagerConfig supportive_zone_manager_configs = 1;
}

message FirstOrderAdrcControllerConfigs {
  repeated FirstOrderAdrcControllerConfig first_order_adrc_controller_configs =
      1;
}

message SecondOrderAdrcControllerConfigs {
  repeated SecondOrderAdrcControllerConfig
      second_order_adrc_controller_configs = 1;
}

message PidControllerConfigs {
  repeated PidControllerConfig pid_controller_configs = 1;
}

message StepwiseControllerConfigs {
  repeated StepwiseControllerConfig stepwise_controller_configs = 1;
}

message FanPidControllerConfigs {
  repeated FanPidControllerConfig fan_pid_controller_configs = 1;
}

message DffControllerConfigs {
  repeated DffControllerConfig dff_controller_configs = 1;
}

message EatControllerConfigs {
  repeated EatControllerConfig eat_controller_configs = 1;
}

message ThermalConfigs {
  bool tuning_enabled = 9 [default = false];
  ZoneManagerConfigs zones = 1;
  SupportiveZoneManagerConfigs supportive_zones = 8;

  // Thermal controllers
  FirstOrderAdrcControllerConfigs first_order_adrc_controllers = 11;
  SecondOrderAdrcControllerConfigs second_order_adrc_controllers = 12;
  PidControllerConfigs pid_controllers = 2;
  StepwiseControllerConfigs stepwise_controllers = 3;
  // Supportive thermal controllers
  DffControllerConfigs dff_controllers = 5;
  EatControllerConfigs eat_controllers = 7;
  // Fan controllers
  FanPidControllerConfigs fan_pid_controllers = 4;

  FailsafeLoggerConfig failsafe_logger_config = 6;

  // The prefix of the sample data file path. The full path will be:
  // `absl::StrCat(sample_data_file_prefix, "_zone", zone_id, ".txt")`.
  // E.g., if the prefix is `/tmp/tlbmc_thermal_data`, the path for zone 1
  // will be `/tmp/tlbmc_thermal_data_zone1.txt`.
  string sample_data_file_prefix = 10 [default = "/tmp/tlbmc_thermal_data"];
}

// The tuning mode of the PID controller.
// The less the overshoot, the more conservative the coefficients will be.
enum ZieglerNicholsPidTuningMode {
  INVALID_PID = 0;
  BASIC_PID = 1;
  LESS_OVERSHOOT_PID = 2;
  NO_OVERSHOOT_PID = 3;
}

message PidTunerZieglerNicholsConfig {
  // The number of tuning iterations to be performed.
  // `tuning_cycles` must be at least 3 to perform the tuning for
  // Ziegler-Nichols auto-tuner, as the first 2 cycles of the algorithms are
  // used for initial warmup.
  uint32 tuning_cycles = 1 [default = 30];
  ZieglerNicholsPidTuningMode tuning_mode = 2 [default = NO_OVERSHOOT_PID];
  // The maximum output value (e.g., fan PWM) in the domain for the PID
  // controller.
  double max_output = 3 [default = 100];
  // The minimum output value (e.g., fan PWM) in the domain for the PID
  // controller.
  double min_output = 4 [default = 0];
}

message PidTunerDifferentiatedZieglerNicholsConfig {
  // The number of tuning iterations to be performed.
  // `tuning_cycles` must be at least 3 to perform the tuning for
  // Ziegler-Nichols auto-tuner, as the first 2 cycles of the algorithms are
  // used for initial warmup.
  uint32 tuning_cycles = 1 [default = 30];
  ZieglerNicholsPidTuningMode tuning_mode = 2 [default = NO_OVERSHOOT_PID];
  // The maximum output value (e.g., fan PWM) in the domain for the PID
  // controller.
  double max_output = 3 [default = 100];
  // The minimum output value (e.g., fan PWM) in the domain for the PID
  // controller.
  double min_output = 4 [default = 0];
}

message PidTunerFrequencyResponseEstimationConfig {
  // Target crossover frequency `\omega_c` (rad/s).
  double target_bandwidth = 1;
  // Target phase margin `\phi_m` (degrees).
  double target_phase_margin_deg = 2;
  // Perturbation signal amplitude `A_{total}`.
  double sine_amplitude = 3 [default = 5];
  // Duration of the tuning process in seconds.
  uint32 tuning_duration_sec = 4 [default = 100];
  // The maximum output value (e.g., fan PWM) in the domain for the PID
  // controller.
  double max_output = 5 [default = 100];
  // The minimum output value (e.g., fan PWM) in the domain for the PID
  // controller.
  double min_output = 6 [default = 0];
  // Baseline control output `u_0` that the perturbation is applied around.
  double nominal_output = 7 [default = 50];
  // Sign of the tuned coefficient gains. Only `1` (positive loop gain) and
  // `-1` (negative loop gain) are meaningful values.
  int32 loop_sign = 8 [default = 1];
}

message PidTunerConfig {
  oneof tuner_config {
    PidTunerZieglerNicholsConfig ziegler_nichols_config = 1;
    PidTunerDifferentiatedZieglerNicholsConfig
        differentiated_ziegler_nichols_config = 2;
    PidTunerFrequencyResponseEstimationConfig
        frequency_response_estimation_config = 3;
  }
}