docs/control/events.md

3 This file defines the events that dictate how fan control operates. Each event
8 the triggers and actions should operate on.
52 The above event is an example of a method to set the fan target to 15000 when
53 one or more fans is missing. The basic behavior with this config is:
55 The trigger `init.get_properties` will, on fan control startup, read the Present
56 property on the `xyz.openbmc_project.Inventory.Item` interface from every D-Bus
57 object in the 'fan inventory' group, update those values in the object cache,
58 and then call the `count_state_before_target` action.
60 The trigger `signal.properties_changed` will watch for changes on the Present
61 property on each D-Bus object in the group, update the new value in the object
62 cache, and call the `count_state_before_target` action when the value changes.
64 The `count_state_before_target` action will look at the object cache value of
65 the Present property on each member of the group and set the fan target hold to
84 The name of a group that must be also be defined in [groups.json](groups.md).
88 The actions and triggers defined with this group will look at this D-Bus
89 interface on the members of this group.
93 The actions and triggers defined with this group will look at this D-Bus
94 property on the members of this group.
98 There are several classes of triggers, and the JSON configuration is different
104 After invoking the configured method, any actions configured for this trigger
116 1. `get_properties` - Read the property configured for the group from every
117    member of the group, and store it in fan control's object cache.
119 2. `name_has_owner` - Populates the service owned state from D-Bus for each
125 configured group. After handling the signal, any configured actions are run.
136 1. `properties_changed` - Subscribes to the PropertiesChanged signal for the
137    D-Bus interface and property specified in the group definition for each group
138    member. When the signal occurs, the new property value will be added to or
139    updated in the object cache.
141 2. `interfaces_added` - Subscribes to the InterfacesAdded signal for the D-Bus
142    interface specified in the group definition for each group member. When the
143    signal occurs, the interface and its properties will be added to the object
146 3. `interfaces_removed` - Subscribes to the InterfacesRemoved signal for the
147    D-Bus interface specified in the group definition for each group member. When
148    the signal occurs, the interface and properties will be removed from the
151 4. `name_owner_changed` - Subscribes to the NameOwnerChanged signal for the
152    services that host the D-bus interface specified in the group definition for
153    each group member. When the signal occurs, the service owned state will be
154    updated in the service cache map.
156 5. `member` - Subscribes to the signal listed on each group member. No caches
157    are updated when the signal occurs.
161 Timer triggers run actions after the configured type of timer expires.
180 The timer length in microseconds
184 Optional, if set to true, will update the D-Bus properties from the configured
185 groups in the object cache after the timer expires but before any actions run.
200 The parameter value to watch.
204 PowerOn triggers run when the power turns on. Functionally, they behave like an
216 The methods are the same as with the init trigger.
220 PowerOff triggers run when the power turns off. Functionally, they behave like
232 The methods are the same as with the init trigger.
236 Actions can either operate on the groups listed with the event, or on the groups
237 listed within the action's JSON config.
242 floor/target below the one that is held.
249 The available actions are:
268 Calculates the net target increase to be requested based on the value of each
269 property given within a group. The net target increase is based on the maximum
270 difference between the `delta` JSON value and all of the properties of the
271 group. The final result is the increase change that's requested to the current
274 The group values can be compared to either a value hardcoded in the JSON, or a
292 The above config uses a hardcoded state value:
294 - For each member of the 'pcie temps' group:
296   - If that property value is greater than the 'state' value of 70.0:
297   - Subtracts 70.0 from the property value.
298   - Multiplies that difference by the 'delta' value of 255.
300 - Requests an increase of the largest calculated delta value, if there is one.
317 The above config uses a parameter as the state value:
319 - For each member of the 'proc 0 core temps' group:
321   - If that property value is greater than the value of the parameter listed in
322     the 'state_parameter_name' field, in this case
324   - Subtracts that parameter value from the property value.
325   - Multiplies that difference by the 'delta' value of 300.
327 - Requests an increase of the largest calculated delta value, if there is one.
331 Calculates the net target decrease to be requested based on the value of each
332 property given within a group. The net target decrease is based on the minimum
333 difference between the `delta` JSON value and all properties in the group. The
334 final result is the decrease change that's requested to the current target of a
337 The group values can be compared to either a value hardcoded in the JSON, or a
355 The above config uses a hardcoded state value:
357 - For each member of the 'pcie temps' group:
359   - If that property value is less than the 'state' value of 65.0:
360   - Subtracts the property value from 65.0.
361   - Multiplies that difference by the 'delta' value of 80.
363 - Requests a decrease of the smallest calculated delta value, if there is one.
380 The above config uses a parameter as the state value:
382 - For each member of the 'proc 0 core temps' group:
384   - If that property value is less than the value of the parameter listed the
386   - Subtracts the property value from the parameter value.
387   - Multiplies that difference by the 'delta' value of 50.
389 - Requests a decrease of the smallest calculated delta value, if there is one.
393 Sets the fans to a configured floor when a number of members within the group
394 are at a configured state. Once the number of members at the given state falls
395 below the configured count, the floor hold is released.
407 The above config reads the configured D-Bus property on each group member
408 configured for the action. If two or more members have a property value of false
410 the floor hold will be released (if it was previously requested).
414 Sets the fans to a configured target when a number of members within the group
415 are at a configured state. Once the number of members at the given state falls
416 below the configured count, active fan target changes are allowed.
427 The above config reads the configured D-Bus property on each group member
428 configured for the action. If one or more members have a property value of
429 false, a target hold will be requested with a value of 18000. Otherwise, the
434 Sets the fan floor to the defined zone's default fan floor when a service
436 providing the sensors, the fan floor is allowed to be set normally again.
443 values within certain ranges, where the key group chooses the set of tables in
444 which to check the remaining group values.
477 The above config will use the maximum value of the 'ambient temp' group as the
478 key into the 'fan_floors' tables. There is one of those tables listed, and it
479 will be used when the key group has a max value of less than 25.
481 It will then traverse the contained floors arrays, keeping track of the highest
483 use the `default_floor` value of 4444, though that value is optional.
485 If no valid tables were found given the key value, the `default_floor` value of
486 5555 would be used, though that is optional and if not supplied the code would
487 default to the default floor of the zone.
489 At the end of the analysis, a floor hold will be set with the final floor value.
492 either match or not match a given value to determine if the action should run or
493 not. This requires the following in the JSON:
495 - "condition_group": The group name
498 - "condition_value": The value to check against
500 For example, the following says the single member of the 'cpu 0' group must have
501 its Model property be equal to "1234" for the action to run:
522 Sets the fans to a configured target when any service owner associated to the
523 group is missing. Once all services are functional and providing all the group
540 The above config will set a target hold of 18000 when the service associated
541 with the 'fan inventory' group is lost.
545 This action locks fans at configured targets when the configured `count` amount
546 of fans meet criterion for the particular condition. A locked fan maintains its
548 it will either revert to temperature control or activate the next-highest target
561 The above config will lock all fans in the fans array at a target of 10000 when
565 This could be used for example, to lock the rotors of a multirotor fan to a high
570 Sets the `pcie_floor_index` parameter based on the current configuration of
571 plugged and powered on PCIe cards, using data from the `pcie_cards.json` file.
573 It chooses the highest index from the active PCIe cards to set in the parameter.
575 It must be configured with the following groups and properties:
577 - The PCIe slots with the PowerState property
578 - The PCIe cards with the following properties: Function0DeviceId,
589 The `use_config_specific_files` field tells the code to look for the
590 'pcie_cards.json' files in the same system specific directories as
591 'events.json'. If missing or false, looks in the base fan control directory.
593 The `settle_time` field is the amount of time in seconds that needs to pass
594 without a call to run() from a group property value changing. As the PCIeDevice
595 attributes are written close together by the host, this allows the action to
596 wait until the writes are done before selecting the index.
598 Additional details are in the
603 Determines the maximum value from the properties of the group of D-Bus objects
604 and sets the requested target base to this value. Only positive integer or
605 floating point types are supported as these are the only valid types for a fan
608 The `requested target base` value is the base value to apply a target delta to.
609 By default, it's the current zone target unless modified by this action.
624 The above config will set the requested target base to the maximum Target
625 property value of all members of the 'fan targets' group.
629 Sets a parameter value based on the maximum group property value. The property
630 value can be modified before storing it if the JSON specifies a valid modifier
644 The above config will first find the max of its groups property values, subtract
645 4, and then store the resulting value in the `proc_0_throttle_temp` parameter.
649 The action sets target of Zone to a value corresponding to the maximum value
650 from maximum group property value. The mapping is based on a provided table. If
651 there are more than one event using this action, the maximum speed derived from
652 the mapping of all groups will be set to the zone's target.
677 The above JSON will cause the action to read the property specified in the group
678 "zone0_ambient" from all members of the group. The change in the group's members
680 it is worth taking action. "pos_hysteresis" is for the increasing case and
681 "neg_hysteresis" is for the decreasing case. The maximum property value in the
682 group will be mapped to the "map" to get the output "target". Each configured
684 mapping result. The static map will be shared across the events of this action.
685 Therefore, the updated "target" value derived from "zone0_ambient" will be
687 running for each event, after the new value is updated to the static map, the
688 maximum value from it will be used to set to the Zone's target.
692 This action starts and stops a timer that runs a list of actions whenever the
696 compared against all members within each group to start/stop the timer. When all
697 group members have a given value and it matches what's in the cache, the timer
698 is started and if any do not match, the timer is stopped.
700 When any group does not have a configured value to be compared against, the
701 groups' service owned state is used to start/stop the timer. When any service
702 providing a group member is not owned, the timer is started and if all members'
703 services are owned, the timer is stopped.
705 Consider the following action config:
732 Then a oneshot timer of 5000000us will be started when every member of the fan
733 inventory group has a value of true. Otherwise, the timer will be stopped if
736 If the group configuration has no property value listed, like:
746 Then the timer will be started when any service providing a group member isn't
747 owned (on D-Bus). Otherwise, it will stop the timer if it's running.
751 This action adds the members of its groups to the object cache by using the
752 GetManagedObjects D-Bus method to find and add the results. When that is done,
753 it then runs any actions listed in the JSON.
755 This allows an action to run with the latest values in the cache without having
778 The above config will make the GetManagedObjects call on all services that own
779 the configured groups and then add all resulting property values to the object
780 cache. After that, it will call the `set_net_increase_target` action using the
789 Subtract the `value` field from the passed in value.
798 The above config subtracts 4 from what is passed to it.
802 Returns a value from a data table that is selected when the argument passed in
803 is less than the `arg_value` entry in the table row. If there is a
804 `default_value` field supplied, then that will be returned if the argument is
805 greater than the `arg_value` of the last row.
819 The above config returns 1 if the arg passed is less than 500, 2 if less than
820 1000, and 3 if less than 1500. Otherwise returns 10000, the default value.