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];
}

// 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 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];
  // Gain for extended state observer.
  // It determines the speed of the observer relative to the controller.
  double coeff_eso = 4 [default = 0];
  // Actuator saturation limits
  double u_limit_max = 5 [default = 0];
  double u_limit_min = 6 [default = 0];
}

// 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];
  // Gain for extended state observer.
  // It determines the speed of the observer relative to the controller.
  double coeff_eso = 4 [default = 0];
  // Actuator saturation limits
  double u_limit_max = 5 [default = 0];
  double u_limit_min = 6 [default = 0];
}

// 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;
}

// 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 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 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;

  PidControllerConfigs pid_controllers = 2;
  StepwiseControllerConfigs stepwise_controllers = 3;
  FanPidControllerConfigs fan_pid_controllers = 4;
  DffControllerConfigs dff_controllers = 5;
  EatControllerConfigs eat_controllers = 7;

  FailsafeLoggerConfig failsafe_logger_config = 6;

  string sample_data_file_path = 10 [default = "/tmp/tlbmc_thermal_data.txt"];
}