1# events.json 2 3This file defines the events that dictate how fan control operates. Each event 4can contain groups, triggers, and actions. 5 6Actions are where fan targets are calculated and set, among other things. 7Triggers specify when an action should run. Groups specify which D-Bus objects 8the triggers and actions should operate on. 9 10Some actions have modifiers, which help calculate a value. 11 12- [Groups](#groups) 13- [Triggers](#triggers) 14- [Actions](#actions) 15- [Modifiers](#modifiers) 16 17## Example 18 19```json 20[ 21 { 22 "name": "fan(s) missing", 23 "groups": [ 24 { 25 "name": "fan inventory", 26 "interface": "xyz.openbmc_project.Inventory.Item", 27 "property": { "name": "Present" } 28 } 29 ], 30 "triggers": [ 31 { 32 "class": "init", 33 "method": "get_properties" 34 }, 35 { 36 "class": "signal", 37 "signal": "properties_changed" 38 } 39 ], 40 "actions": [ 41 { 42 "name": "count_state_before_target", 43 "count": 1, 44 "state": false, 45 "target": 15000 46 } 47 ] 48 } 49] 50``` 51 52The above event is an example of a method to set the fan target to 15000 when 53one or more fans is missing. The basic behavior with this config is: 54 55The trigger `init.get_properties` will, on fan control startup, read the Present 56property on the `xyz.openbmc_project.Inventory.Item` interface from every D-Bus 57object in the 'fan inventory' group, update those values in the object cache, 58and then call the `count_state_before_target` action. 59 60The trigger `signal.properties_changed` will watch for changes on the Present 61property on each D-Bus object in the group, update the new value in the object 62cache, and call the `count_state_before_target` action when the value changes. 63 64The `count_state_before_target` action will look at the object cache value of 65the Present property on each member of the group and set the fan target hold to 6615000 when one or more of them is false. Otherwise, it will clear its fan target 67hold. 68 69## Groups 70 71```json 72"groups": [ 73 { 74 "name": "<name>", 75 "interface": "<interface>", 76 "property": { "name": "<name>" } 77 } 78 ... 79] 80``` 81 82### name 83 84The name of a group that must be also be defined in [groups.json](groups.md). 85 86### interface 87 88The actions and triggers defined with this group will look at this D-Bus 89interface on the members of this group. 90 91### property: name 92 93The actions and triggers defined with this group will look at this D-Bus 94property on the members of this group. 95 96## Triggers 97 98There are several classes of triggers, and the JSON configuration is different 99for each. 100 101### init 102 103Init triggers run when fan control events are enabled on fan control startup. 104After invoking the configured method, any actions configured for this trigger 105will run. 106 107```json 108{ 109 "class": "init", 110 "method": "<method>" 111} 112``` 113 114#### methods 115 1161. `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. 118 1192. `name_has_owner` - Populates the service owned state from D-Bus for each 120 group member in fan control's D-Bus service cache map. 121 122### signal 123 124Signal triggers subscribe to certain D-Bus signals for each member of its 125configured group. After handling the signal, any configured actions are run. 126 127```json 128{ 129 "class": "signal", 130 "signal": "<signal>" 131} 132``` 133 134#### signal types 135 1361. `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. 140 1412. `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 144 cache. 145 1463. `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 149 object cache. 150 1514. `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. 155 1565. `member` - Subscribes to the signal listed on each group member. No caches 157 are updated when the signal occurs. 158 159### timer 160 161Timer triggers run actions after the configured type of timer expires. 162 163```json 164{ 165 "class": "timer", 166 "type": "<type>", 167 "interval": "<interval>", 168 "preload_groups": "<true/false>" 169} 170``` 171 172#### type 173 1741. `oneshot` - Starts a timer that runs once. 175 1762. `repeating` - Starts a repeating timer. 177 178#### interval 179 180The timer length in microseconds 181 182#### preload_groups 183 184Optional, if set to true, will update the D-Bus properties from the configured 185groups in the object cache after the timer expires but before any actions run. 186 187### parameter 188 189Parameter triggers run actions after a parameter changes. 190 191```json 192{ 193 "class": "parameter", 194 "parameter": "<parameter>" 195} 196``` 197 198#### parameter 199 200The parameter value to watch. 201 202### poweron 203 204PowerOn triggers run when the power turns on. Functionally, they behave like an 205init trigger. 206 207```json 208{ 209 "class": "poweron", 210 "method": "<method>" 211} 212``` 213 214#### method 215 216The methods are the same as with the init trigger. 217 218### poweroff 219 220PowerOff triggers run when the power turns off. Functionally, they behave like 221an init trigger. 222 223```json 224{ 225 "class": "poweroff", 226 "method": "<method>" 227} 228``` 229 230#### method 231 232The methods are the same as with the init trigger. 233 234## Actions 235 236Actions can either operate on the groups listed with the event, or on the groups 237listed within the action's JSON config. 238 239Most actions set fan targets or floors. This can be done by requesting a target 240value explicitly, or by requesting an increase or decrease delta. Targets and 241floors can also be set with a hold, meaning another action can't set a 242floor/target below the one that is held. 243 244Some actions set or read a key/value pair called a parameter. These can be 245created, updated, and deleted as necessary. For example, one action may 246calculate and set a `floor_index` parameter, and another action may then read 247that parameter to help choose a fan floor. 248 249The available actions are: 250 251- [set_net_increase_target](#set_net_increase_target) 252- [set_net_decrease_target](#set_net_decrease_target) 253- [count_state_floor](#count_state_floor) 254- [count_state_before_target](#count_state_before_target) 255- [default_floor_on_missing_owner](#default_floor_on_missing_owner) 256- [mapped_floor](#mapped_floor) 257- [set_target_on_missing_owner](#set_target_on_missing_owner) 258- [override_fan_target](#override_fan_target) 259- [pcie_card_floors](#pcie_card_floors) 260- [set_request_target_base_with_max](#set_request_target_base_with_max) 261- [set_parameter_from_group_max](#set_parameter_from_group_max) 262- [target_from_group_max](#target_from_group_max) 263- [call_actions_based_on_timer](#call_actions_based_on_timer) 264- [get_managed_objects](#get_managed_objects) 265 266### set_net_increase_target 267 268Calculates the net target increase to be requested based on the value of each 269property given within a group. The net target increase is based on the maximum 270difference between the `delta` JSON value and all of the properties of the 271group. The final result is the increase change that's requested to the current 272target of a zone. 273 274The group values can be compared to either a value hardcoded in the JSON, or a 275parameter value. 276 277```json 278{ 279 "name": "set_net_increase_target", 280 "groups": [ 281 { 282 "name": "pcie temps", 283 "interface": "xyz.openbmc_project.Sensor.Value", 284 "property": { "name": "Value" } 285 } 286 ], 287 "state": 70.0, 288 "delta": 255 289} 290``` 291 292The above config uses a hardcoded state value: 293 2941. For each member of the 'pcie temps' group: 295 296- Read its 'Value' D-Bus property. 297- If that property value is greater than the 'state' value of 70.0: 298- Subtracts 70.0 from the property value. 299- Multiplies that difference by the 'delta' value of 255. 300 3012. Requests an increase of the largest calculated delta value, if there is one. 302 303```json 304{ 305 "name": "set_net_increase_target", 306 "groups": [ 307 { 308 "name": "proc0 core temps", 309 "interface": "xyz.openbmc_project.Sensor.Value", 310 "property": { "name": "Value" } 311 } 312 ], 313 "state_parameter_name": "proc_0_core_dvfs_increase_temp", 314 "delta": 300 315} 316``` 317 318The above config uses a parameter as the state value: 319 3201. For each member of the 'proc 0 core temps' group: 321 322- Read its 'Value' D-Bus property. 323- If that property value is greater than the value of the parameter listed in 324 the 'state_parameter_name' field, in this case 325 'proc_0_core_dvfs_increase_temp': 326- Subtracts that parameter value from the property value. 327- Multiplies that difference by the 'delta' value of 300. 328 3292. Requests an increase of the largest calculated delta value, if there is one. 330 331### set_net_decrease_target 332 333Calculates the net target decrease to be requested based on the value of each 334property given within a group. The net target decrease is based on the minimum 335difference between the `delta` JSON value and all properties in the group. The 336final result is the decrease change that's requested to the current target of a 337zone. 338 339The group values can be compared to either a value hardcoded in the JSON, or a 340parameter value. 341 342```json 343{ 344 "name": "set_net_decrease_target", 345 "groups": [ 346 { 347 "name": "pcie temps", 348 "interface": "xyz.openbmc_project.Sensor.Value", 349 "property": { "name": "Value" } 350 } 351 ], 352 "state": 65.0, 353 "delta": 80 354} 355``` 356 357The above config uses a hardcoded state value: 358 3591. For each member of the 'pcie temps' group: 360 361- Read its 'Value' D-Bus property. 362- If that property value is less than the 'state' value of 65.0: 363- Subtracts the property value from 65.0. 364- Multiplies that difference by the 'delta' value of 80. 365 3662. Requests a decrease of the smallest calculated delta value, if there is one. 367 368```json 369{ 370 "name": "set_net_decrease_target", 371 "groups": [ 372 { 373 "name": "proc 0 core temps", 374 "interface": "xyz.openbmc_project.Sensor.Value", 375 "property": { "name": "Value" } 376 } 377 ], 378 "state_parameter_name": "proc_0_core_dvfs_decrease_temp", 379 "delta": 50 380} 381``` 382 383The above config uses a parameter as the state value: 384 3851. For each member of the 'proc 0 core temps' group: 386 387- Read its 'Value' D-Bus property. 388- If that property value is less than the value of the parameter listed the 389 'state_parameter_name' field, in this case 'proc_0_core_dvfs_decrease_temp': 390- Subtracts the property value from the parameter value. 391- Multiplies that difference by the 'delta' value of 50. 392 3932. Requests a decrease of the smallest calculated delta value, if there is one. 394 395### count_state_floor 396 397Sets the fans to a configured floor when a number of members within the group 398are at a configured state. Once the number of members at the given state falls 399below the configured count, the floor hold is released. 400 401```json 402{ 403 "name": "count_state_floor", 404 "count": 2, 405 "state": false, 406 "floor": 18000, 407 "delay": 3 408} 409``` 410 411The above config reads the configured D-Bus property on each group member 412configured for the action. If two or more members have a property value of false 413for 3 seconds, a floor hold will be requested with a value of 18000. Otherwise, 414the floor hold will be released (if it was previously requested). 415 416### count_state_before_target 417 418Sets the fans to a configured target when a number of members within the group 419are at a configured state. Once the number of members at the given state falls 420below the configured count, active fan target changes are allowed. 421 422```json 423{ 424 "name": "count_state_before_target", 425 "count": 1, 426 "state": false, 427 "target": 18000 428} 429``` 430 431The above config reads the configured D-Bus property on each group member 432configured for the action. If one or more members have a property value of 433false, a target hold will be requested with a value of 18000. Otherwise, the 434hold will be released (if it was previously requested). 435 436### default_floor_on_missing_owner 437 438Sets the fan floor to the defined zone's default fan floor when a service 439associated to a given group has terminated. Once all services are functional and 440providing the sensors, the fan floor is allowed to be set normally again. 441 442There is no additional JSON config for this action. 443 444### mapped_floor 445 446This action can be used to set a floor value based on 2 or more groups having 447values within certain ranges, where the key group chooses the set of tables in 448which to check the remaining group values. 449 450```json 451{ 452 "name": "mapped_floor", 453 "key_group": "ambient temp", 454 "default_floor": 5555, 455 "fan_floors": [ 456 { 457 "key": 25, 458 "default_floor": 4444, 459 "floor_offset_parameter": "ambient_25_altitude_offset", 460 "floors": [ 461 { 462 "parameter": "pcie_floor_index", 463 "floors": [ 464 { "value": 1, "floor": 2000 }, 465 { "value": 2, "floor": 3000 }, 466 { "value": 3, "floor": 4000 }, 467 { "value": 4, "floor": 5000 }, 468 { "value": 5, "floor": 6000 } 469 ] 470 }, 471 { 472 "group": "power save", 473 "floors": [{ "value": true, "floor": 1000 }] 474 } 475 ] 476 } 477 ] 478} 479``` 480 481The above config will use the maximum value of the 'ambient temp' group as the 482key into the 'fan_floors' tables. There is one of those tables listed, and it 483will be used when the key group has a max value of less than 25. 484 485It will then traverse the contained floors arrays, keeping track of the highest 486valid floor value it finds. If it doesn't find any valid floor values, it will 487use the `default_floor` value of 4444, though that value is optional. 488 489If no valid tables were found given the key value, the `default_floor` value of 4905555 would be used, though that is optional and if not supplied the code would 491default to the default floor of the zone. 492 493At the end of the analysis, a floor hold will be set with the final floor value. 494 495This action can also have a condition specified where a group property must 496either match or not match a given value to determine if the action should run or 497not. This requires the following in the JSON: 498 499- "condition_group": The group name 500 - For now, this group must just have a single member. 501- "condition_op": Either "equal" or "not_equal" 502- "condition_value": The value to check against 503 504For example, the following says the single member of the 'cpu 0' group must have 505its Model property be equal to "1234" for the action to run: 506 507```json 508 "groups": [{ 509 "name": "cpu 0", 510 "interface": "xyz.openbmc_project.Inventory.Decorator.Asset", 511 "property": { "name": "Model" } 512 } 513 ... 514 ], 515 ... 516 "name": "mapped_floor", 517 "key_group": "ambient temp", 518 "condition_group": "cpu 0", 519 "condition_value": "1234", 520 "condition_op": "equal", 521 ... 522``` 523 524### set_target_on_missing_owner 525 526Sets the fans to a configured target when any service owner associated to the 527group is missing. Once all services are functional and providing all the group 528data again, active fan target changes are allowed. 529 530```json 531{ 532 "name": "set_target_on_missing_owner", 533 "groups": [ 534 { 535 "name": "fan inventory", 536 "interface": "xyz.openbmc_project.Inventory.Item", 537 "property": { "name": "Present" } 538 } 539 ], 540 "target": 18000 541} 542``` 543 544The above config will set a target hold of 18000 when the service associated 545with the 'fan inventory' group is lost. 546 547### override_fan_target 548 549This action locks fans at configured targets when the configured `count` amount 550of fans meet criterion for the particular condition. A locked fan maintains its 551override target until unlocked (or locked at a higher target). Upon unlocking, 552it will either revert to temperature control or activate the next-highest target 553remaining in its list of locks. 554 555```json 556{ 557 "name": "override_fan_target", 558 "count": 1, 559 "state": false, 560 "fans": ["fan0", "fan1", "fan2", "fan3"], 561 "target": 10000 562} 563``` 564 565The above config will lock all fans in the fans array at a target of 10000 when 566one or more members in its configured group have a group property value of 567false. 568 569This could be used for example, to lock the rotors of a multirotor fan to a high 570target when one of its rotors has a functional property equal to false. 571 572### pcie_card_floors 573 574Sets the `pcie_floor_index` parameter based on the current configuration of 575plugged and powered on PCIe cards, using data from the `pcie_cards.json` file. 576 577It chooses the highest index from the active PCIe cards to set in the parameter. 578 579It must be configured with the following groups and properties: 580 581- The PCIe slots with the PowerState property 582- The PCIe cards with the following properties: Function0DeviceId, 583 Function0VendorId, Function0SubsystemId, Function0SubsystemVendorId 584 585```json 586{ 587 "name": "pcie_card_floors", 588 "use_config_specific_files": true, 589 "settle_time": 2 590} 591``` 592 593The `use_config_specific_files` field tells the code to look for the 594'pcie_cards.json' files in the same system specific directories as 595'events.json'. If missing or false, looks in the base fan control directory. 596 597The `settle_time` field is the amount of time in seconds that needs to pass 598without a call to run() from a group property value changing. As the PCIeDevice 599attributes are written close together by the host, this allows the action to 600wait until the writes are done before selecting the index. 601 602Additional details are in the 603[header file](../../control/json/actions/pcie_card_floors.hpp) 604 605### set_request_target_base_with_max 606 607Determines the maximum value from the properties of the group of D-Bus objects 608and sets the requested target base to this value. Only positive integer or 609floating point types are supported as these are the only valid types for a fan 610target to be based off of. 611 612The `requested target base` value is the base value to apply a target delta to. 613By default, it's the current zone target unless modified by this action. 614 615```json 616{ 617 "name": "set_request_target_base_with_max", 618 "groups": [ 619 { 620 "name": "fan targets", 621 "interface": "xyz.openbmc_project.Fan.Target", 622 "property": { "name": "Target" } 623 } 624 ] 625} 626``` 627 628The above config will set the requested target base to the maximum Target 629property value of all members of the 'fan targets' group. 630 631### set_parameter_from_group_max 632 633Sets a parameter value based on the maximum group property value. The property 634value can be modified before storing it if the JSON specifies a valid modifier 635expression. 636 637```json 638{ 639 "name": "set_parameter_from_group_max", 640 "parameter_name": "proc_0_throttle_temp", 641 "modifier": { 642 "expression": "minus", 643 "value": 4 644 } 645} 646``` 647 648The above config will first find the max of its groups property values, subtract 6494, and then store the resulting value in the `proc_0_throttle_temp` parameter. 650 651### target_from_group_max 652 653The action sets target of Zone to a value corresponding to the maximum value 654from maximum group property value. The mapping is based on a provided table. If 655there are more than one event using this action, the maximum speed derived from 656the mapping of all groups will be set to the zone's target. 657 658... { "name": "target_from_group_max", "groups": [ { "name": 659"zone0_ambient", "interface": "xyz.openbmc_project.Sensor.Value", "property": 660{ "name": "Value" } } ], "neg_hysteresis": 1, "pos_hysteresis": 0, "map": [ 661{ "value": 10.0, "target": 38.0 }, ... ] } 662 663The above JSON will cause the action to read the property specified in the group 664"zone0_ambient" from all members of the group. The change in the group's members 665value will be checked against "neg_hysteresis" and "pos_hysteresis" to decide if 666it is worth taking action. "pos_hysteresis" is for the increasing case and 667"neg_hysteresis" is for the decreasing case. The maximum property value in the 668group will be mapped to the "map" to get the output "target". Each configured 669event using this action will be provided with a key in a static map to store its 670mapping result. The static map will be shared across the events of this action. 671Therefore, the updated "target" value derived from "zone0_ambient" will be 672stored in that static map with its own key. Each time it calls this action 673running for each event, after the new value is updated to the static map, the 674maximum value from it will be used to set to the Zone's target. 675 676### call_actions_based_on_timer 677 678This action starts and stops a timer that runs a list of actions whenever the 679timer expires. A timer can be either `oneshot` or `repeating`. 680 681When all groups have a configured value to compare against, that will be 682compared against all members within each group to start/stop the timer. When all 683group members have a given value and it matches what's in the cache, the timer 684is started and if any do not match, the timer is stopped. 685 686When any group does not have a configured value to be compared against, the 687groups' service owned state is used to start/stop the timer. When any service 688providing a group member is not owned, the timer is started and if all members' 689services are owned, the timer is stopped. 690 691Consider the following action config: 692 693```json 694{ 695 "name": "call_actions_based_on_timer", 696 "timer": { 697 "interval": 5000000, 698 "type": "oneshot" 699 }, 700 "actions": [ 701 { 702 "name": "test" 703 } 704 ] 705} 706``` 707 708If its group configuration has a property value listed, like: 709 710```json 711{ 712 "name": "fan inventory", 713 "interface": "xyz.openbmc_project.Inventory.Item", 714 "property": { "name": "Present", "value": true } 715} 716``` 717 718Then a oneshot timer of 5000000us will be started when every member of the fan 719inventory group has a value of true. Otherwise, the timer will be stopped if 720it's running. 721 722If the group configuration has no property value listed, like: 723 724```json 725{ 726 "name": "fan inventory", 727 "interface": "xyz.openbmc_project.Inventory.Item", 728 "property": { "name": "Present" } 729} 730``` 731 732Then the timer will be started when any service providing a group member isn't 733owned (on D-Bus). Otherwise, it will stop the timer if it's running. 734 735### get_managed_objects 736 737This action adds the members of its groups to the object cache by using the 738GetManagedObjects D-Bus method to find and add the results. When that is done, 739it then runs any actions listed in the JSON. 740 741This allows an action to run with the latest values in the cache without having 742to subscribe to propertiesChanged for them all. 743 744```json 745{ 746 "name": "get_managed_objects", 747 "groups": [ 748 { 749 "name": "proc temps", 750 "interface": "xyz.openbmc_project.Sensor.Value", 751 "property": { "name": "Value" } 752 } 753 ], 754 "actions": [ 755 { 756 "name": "set_net_increase_target", 757 "state": 30, 758 "delta": 100 759 } 760 ] 761} 762``` 763 764The above config will make the GetManagedObjects call on all services that own 765the configured groups and then add all resulting property values to the object 766cache. After that, it will call the `set_net_increase_target` action using the 767same groups. 768 769## Modifiers 770 771Modifiers are used by some actions to help calculate values. 772 773### minus 774 775Subtract the `value` field from the passed in value. 776 777```json 778"modifier": { 779 "expression": "minus", 780 "value": 4 781} 782``` 783 784The above config subtracts 4 from what is passed to it. 785 786### less_than 787 788Returns a value from a data table that is selected when the argument passed in 789is less than the `arg_value` entry in the table row. If there is a 790`default_value` field supplied, then that will be returned if the argument is 791greater than the `arg_value` of the last row. 792 793```json 794"modifier": { 795 "operator": "less_than", 796 "default_value": 10000, 797 "value": [ 798 { "arg_value": 500, "parameter_value": 1 }, 799 { "arg_value": 1000, "parameter_value": 2 }, 800 { "arg_value": 1500, "parameter_value": 3 } 801 ] 802} 803``` 804 805The above config returns 1 if the arg passed is less than 500, 2 if less than 8061000, and 3 if less than 1500. Otherwise returns 10000, the default value. 807