Porting guide: Add fans part

Signed-off-by: Lei YU <[email protected]>

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<int64_t, uint64_t>
+          - name: set_ceiling_from_average_sensor_value
+            map:
+                value:
+                    - 25000: 175
+                    - 27000: 255
+                type: std::map<int64_t, uint64_t>
+   ```
+   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