control:docs:events: Start adding actions
Describe the net_target_increase and net_target_decrease actions.
Signed-off-by: Matt Spinler <spinler@us.ibm.com>
Change-Id: I7de18b4cad79767079daef3e8a48e355999a9d4e
diff --git a/docs/control/events.md b/docs/control/events.md
index a91aa0a..01a88a2 100644
--- a/docs/control/events.md
+++ b/docs/control/events.md
@@ -215,3 +215,146 @@
#### method
The methods are the same as with the init trigger.
+
+## Actions
+Actions can either operate on the groups listed with the event, or on the
+groups listed within the action's JSON config.
+
+Most actions set fan targets or floors. This can be done by requesting a
+target value explicitly, or by requesting an increase or decrease delta.
+Targets and floors can also be set with a hold, meaning another action can't
+set a floor/target below the one that is held.
+
+Some actions set or read a key/value pair called a parameter. These can be
+created, updated, and deleted as necessary. For example, one action may
+calculate and set a `floor_index` parameter, and another action may then read
+that parameter to help choose a fan floor.
+
+The available actions are:
+
+- [set_net_increase_target](#set_net_increase_target)
+- [set_net_decrease_target](#set_net_decrease_target)
+- [count_state_floor](#count_state_floor)
+- [count_state_before_target](#count_state_before_target)
+- [default_floor_on_missing_owner](#default_floor_on_missing_owner)
+- [mapped_floor](#mapped_floor)
+- [set_target_on_missing_owner](#set_target_on_missing_owner)
+- [override_fan_target](#override_fan_target)
+- [pcie_card_floors](#pcie_card_floors)
+- [set_request_target_base_with_max](#set_request_target_base_with_max)
+- [set_parameter_from_group_max](#set_parameter_from_group_max)
+- [call_actions_based_on_timer](#call_actions_based_on_timer)
+- [get_managed_objects](#get_managed_objects)
+
+### set_net_increase_target
+
+Calculates the net target increase to be requested based on the value of each
+property given within a group. The net target increase is based on the maximum
+difference between the `delta` JSON value and all of the properties of the group.
+The final result is the increase change that's requested to the current target
+of a zone.
+
+The group values can be compared to either a value hardcoded in the JSON, or a
+parameter value.
+
+```
+{
+ "name": "set_net_increase_target",
+ "groups": [{
+ "name": "pcie temps",
+ "interface": "xyz.openbmc_project.Sensor.Value",
+ "property": { "name": "Value" }
+ }],
+ "state": 70.0,
+ "delta": 255
+}
+```
+
+The above config uses a hardcoded state value:
+1. For each member of the 'pcie temps' group:
+ - Read its 'Value' D-Bus property.
+ - If that property value is greater than the 'state' value of 70.0:
+ - Subtracts 70.0 from the property value.
+ - Multiplies that difference by the 'delta' value of 255.
+2. Requests an increase of the largest calculated delta value, if there is
+ one.
+
+```
+{
+ "name": "set_net_increase_target",
+ "groups": [{
+ "name": "proc0 core temps",
+ "interface": "xyz.openbmc_project.Sensor.Value",
+ "property": { "name": "Value" }
+ }],
+ "state_parameter_name": "proc_0_core_dvfs_increase_temp",
+ "delta": 300
+}
+```
+
+The above config uses a parameter as the state value:
+1. For each member of the 'proc 0 core temps' group:
+ - Read its 'Value' D-Bus property.
+ - If that property value is greater than the value of the parameter listed in
+ the 'state_parameter_name' field, in this case
+ 'proc_0_core_dvfs_increase_temp':
+ - Subtracts that parameter value from the property value.
+ - Multiplies that difference by the 'delta' value of 300.
+2. Requests an increase of the largest calculated delta value, if there is one.
+
+### set_net_decrease_target
+Calculates the net target decrease to be requested based on the value of each
+property given within a group. The net target decrease is based on the minimum
+difference between the `delta` JSON value and all properties in the group. The
+final result is the decrease change that's requested to the current target of a
+zone.
+
+The group values can be compared to either a value hardcoded in the JSON, or a
+parameter value.
+
+```
+{
+ "name": "set_net_decrease_target",
+ "groups": [{
+ "name": "pcie temps",
+ "interface": "xyz.openbmc_project.Sensor.Value",
+ "property": { "name": "Value" }
+ }],
+ "state": 65.0,
+ "delta": 80
+}
+
+```
+
+The above config uses a hardcoded state value:
+1. For each member of the 'pcie temps' group:
+ - Read its 'Value' D-Bus property.
+ - If that property value is less than the 'state' value of 65.0:
+ - Subtracts the property value from 65.0.
+ - Multiplies that difference by the 'delta' value of 80.
+2. Requests a decrease of the smallest calculated delta value, if there is
+ one.
+
+```
+{
+ "name": "set_net_decrease_target",
+ "groups": [{
+ "name": "proc 0 core temps",
+ "interface": "xyz.openbmc_project.Sensor.Value",
+ "property": { "name": "Value" }
+ }],
+ "state_parameter_name": "proc_0_core_dvfs_decrease_temp",
+ "delta": 50
+}
+```
+
+The above config uses a parameter as the state value:
+1. For each member of the 'proc 0 core temps' group:
+ - Read its 'Value' D-Bus property.
+ - If that property value is less than the value of the parameter listed
+ the 'state_parameter_name' field, in this case
+ 'proc_0_core_dvfs_decrease_temp':
+ - Subtracts the property value from the parameter value.
+ - Multiplies that difference by the 'delta' value of 50.
+2. Requests a decrease of the smallest calculated delta value, if there is
+ one.