From 687c122de017eb17e0cae6015b1a205adce5cee9 Mon Sep 17 00:00:00 2001 From: Lei YU Date: Tue, 17 Apr 2018 17:17:14 +0800 Subject: [PATCH] Porting guide: Add fans part Signed-off-by: Lei YU --- Porting_Guide.md | 144 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 143 insertions(+), 1 deletion(-) diff --git a/Porting_Guide.md b/Porting_Guide.md index 83275b9..9f412a0 100644 --- a/Porting_Guide.md +++ b/Porting_Guide.md @@ -286,11 +286,150 @@ The first value `0x08`, `0x1e` and `0x22` are the sensor id of IPMI, which is defined in MRW. You should follow the system's MRW to define the above config. - **Note**: The yaml configs can be automatically generated by [phosphor-mrw-tools][13] from its MRW, see example of [Witherspoon][14]. + #### Fans +[phosphor-fan-presence][16] manages all the services about fan: +* `phosphor-fan-presence` checks if a fan is present, creates the fan DBus + objects in inventory and update the `Present` property. +* `phosphor-fan-monitor` checks if a fan is functional, and update the + `Functional` property of the fan Dbus object. +* `phosphor-fan-control` controls the fan speed by setting the fan speed target + based on conditions, e.g. temperatures. +* `phosphor-cooling-type` checks and sets if the system is air-cooled or + water-cooled by setting properties of + `/xyz/openbmc_project/inventory/system/chassis` object. + +All the above services are configurable, e.g. by yaml config. +So the machine specific configs shall be written when porting OpenBMC to a new +machine. + +Taking Romulus as example, it is air-cooled and has 3 fans without GPIO +presence detection. + +##### Fan presence +Romulus has no GPIO detection for fan, so it checks fan tach sensor: +``` +- name: fan0 + path: /system/chassis/motherboard/fan0 + methods: + - type: tach + sensors: + - fan0 +``` +The yaml config tells that +* It shall create `/system/chassis/motherboard/fan0` object in inventory. +* It shall check fan0 tach sensor (`/sensors/fan_tach/fan0`) to set `Present` + property on the fan0 object. + +##### Fan monitor +Romulus fans ues pwm to control the fan speed, where pwm ranges from 0 to 255, +and the fan speed ranges from 0 to about 7000. +So it needs a factor and offset to mapping the pwm to fan speed: +``` + - inventory: /system/chassis/motherboard/fan0 + allowed_out_of_range_time: 30 + deviation: 15 + num_sensors_nonfunc_for_fan_nonfunc: 1 + sensors: + - name: fan0 + has_target: true + target_interface: xyz.openbmc_project.Control.FanPwm + factor: 21 + offset: 1600 +``` +The yaml config tells that: +1. It shall use `FanPwm` as target interface of the tach sensor; +2. It shall calculate the expected fan speed as `target * 21 + 1600` +3. The deviation is `15%`, so if the fan speed is out of the expected range + for more than 30 seconds, fan0 shall be set as non-functional. + +##### Fan control +The fan control service requires 4 yamls configs: +* `zone-condition` defines the cooling zone conditions. Romulus is always + air-cooled, so this config is as simple as define a `air_cooled_chassis` + condition based on the cooling type property. + ``` + - name: air_cooled_chassis + type: getProperty + properties: + - property: WaterCooled + interface: xyz.openbmc_project.Inventory.Decorator.CoolingType + path: /xyz/openbmc_project/inventory/system/chassis + type: bool + value: false + ``` +* `zone-config` defines the cooling zones. Romulus has only one zone: + ``` + zones: + - zone: 0 + full_speed: 255 + default_floor: 195 + increase_delay: 5 + decrease_interval: 30 + ``` + It defines that the zone full speed and default floor speed for the fans, + so the fan pwm will be set to 255 if it is in full speed, and set to 195 if + fans are in default floor speed. +* `fan-config` defines which fans are controlled in which zone and which target + interface shall be used, e.g. below yaml config defines fan0 shall be + controlled in zone0 and it shall use `FanPwm` interface. + ``` + - inventory: /system/chassis/motherboard/fan0 + cooling_zone: 0 + sensors: + - fan0 + target_interface: xyz.openbmc_project.Control.FanPwm + ... + ``` +* `events-config` defines the various events and its handlers, e.g. which fan + targets shall be set in which temperature. + This config is a bit complicated, the [exmaple event yaml][17] provides + documents and examples. + Romulus example: + ``` + - name: set_air_cooled_speed_boundaries_based_on_ambient + groups: + - name: zone0_ambient + interface: xyz.openbmc_project.Sensor.Value + property: + name: Value + type: int64_t + matches: + - name: propertiesChanged + actions: + - name: set_floor_from_average_sensor_value + map: + value: + - 27000: 85 + - 32000: 112 + - 37000: 126 + - 40000: 141 + type: std::map + - name: set_ceiling_from_average_sensor_value + map: + value: + - 25000: 175 + - 27000: 255 + type: std::map + ``` + The above yaml config defines the fan floor and ceiling speed in + `zone0_ambient`'s different temperatures. E.g. + 1. When the temperature is lower than 27 degreesC, the floor speed (pwm) + shall be set to 85. + 2. When temperature is between 27 and 32 degreesC, the floor speed (pwm) + shall be set to 112, etc. + +With above configs, phosphor-fan will run the fan presence/monitor/control +logic as configured specifically for the machine. + +**Note**: Romulus fans are simple, for a more complicated example, refer to +[Witherspoon's fan configs][18]: +* It checks GPIO for fan presnece. +* It checks GPIO to determine if the system is air or water cooled. +* It has more sensors and more events in fan control. #### GPIOs @@ -311,3 +450,6 @@ You should follow the system's MRW to define the above config. [13]: https://github.com/openbmc/phosphor-mrw-tools [14]: https://github.com/openbmc/openbmc/blob/master/meta-openbmc-machines/meta-openpower/meta-ibm/meta-witherspoon/conf/distro/openbmc-witherspoon.conf#L3 [15]: https://github.com/openbmc/openbmc/tree/master/meta-openbmc-machines/meta-openpower/meta-ibm/meta-romulus/recipes-phosphor/ipmi +[16]: https://github.com/openbmc/phosphor-fan-presence +[17]: https://github.com/openbmc/phosphor-fan-presence/blob/master/control/example/events.yaml +[18]: https://github.com/openbmc/openbmc/tree/master/meta-openbmc-machines/meta-openpower/meta-ibm/meta-witherspoon/recipes-phosphor/fans