#gpowerd Clarify comments in safepower_agent.proto.
PiperOrigin-RevId: 831460875
Change-Id: I02bead73f00b458643849313677a120be237b88f
diff --git a/proto/safepower_agent.proto b/proto/safepower_agent.proto
index 52c62f1..f403fc6 100644
--- a/proto/safepower_agent.proto
+++ b/proto/safepower_agent.proto
@@ -18,12 +18,25 @@
// Monitor reaction
rpc MonitorAction(MonitorActionRequest) returns (stream ActionStateLog) {}
- // Monitor state.
+ // This monitors the local state as detected by this agent.
+ //
+ // Note that this is not monitoring the global state. For example, if the
+ // state is updated via SystemStateUpdate, that update will not be reflected
+ // here unless independently determined locally.
rpc MonitorState(MonitorStateRequest) returns (stream SystemState) {}
- // Update the global system state. This is used by the safepower service to
- // update the state of the system as a whole, so that nodes that don't have a
- // complete picture can synhronize with other nodes.
+ // Update the global system state.
+ //
+ // The global state is owned by the Safepower service (S4) and is used to
+ // synchronize state between nodes that may not have a complete picture of
+ // the system. The safepower agent only uses this state to match
+ // conditions for actions and does not perform any validation on the
+ // received state.
+ //
+ // For example, to confirm that a SystemStateUpdate has been durably
+ // applied across an agent restart, use MonitorAction. MonitorAction tracks
+ // the action's effects persistently, unlike MonitorState which only
+ // reflects the local agent's current view.
rpc SystemStateUpdate(SystemState) returns (SystemStateUpdateResponse) {}
}
@@ -223,10 +236,12 @@
// This is mostly useful to detect service restarts.
uint64 epoch_ms = 1 [features.field_presence = EXPLICIT]; // required
- // The contents are platform and node specific. Keys are node entity tags and
- // values are state information for the corresponding node. This includes all
- // nodes for which this node can obtain status. For example, an arena
- // controller may have power state information for other nodes in the arena.
+ // The contents are platform and node specific. Keys usually correspond to
+ // node entity tags and values are state information for the corresponding
+ // node. This includes, but is not limited to, all nodes for which this agent
+ // can obtain status locally.
+ // For example, an arena controller may have power state information for
+ // other nodes in the arena.
map<string, NodeState> node_state = 2;
}
