lib: smf: add API to get the current leaf and executing state

Retrieve the current leaf state by calling `smf_get_current_leaf_state`
and the state which is currently-executing by calling
`smf_get_current_executing_state`.

Signed-off-by: Siwei Yang <[email protected]>

Author: ysway

doc/releases/release-notes-4.3.rst

@@ -253,6 +253,11 @@ New APIs and options
       * :kconfig:option:`CONFIG_SHELL_MQTT_WORK_DELAY_MS`
       * :kconfig:option:`CONFIG_SHELL_MQTT_LISTEN_TIMEOUT_MS`
 
+* State Machine Framework
+
+  * :c:func:`smf_get_current_leaf_state`
+  * :c:func:`smf_get_current_executing_state`
+
 * Storage
 
     * :kconfig:option:`CONFIG_FILE_SYSTEM_SHELL_LS_SIZE`

doc/services/smf/index.rst

@@ -130,6 +130,33 @@ should be called. It can be called from the entry, run, or exit actions. The
 function takes a non-zero user defined value that will be returned by the
 :c:func:`smf_run_state` function.
 
+Retrieving the Current State
+====================================
+
+**Leaf State**: In the context of a hierarchical state machine, a *leaf state*
+is a state that does not contain any child states. It represents the most granular
+level of state in the hierarchy, where no further decomposition is possible.
+
+**Executing State**: The *executing state* refers to the state whose entry,
+run, or exit action is currently being executed by the state machine. This
+may be a parent or leaf state, depending on the current operation.
+
+To retrieve the current leaf state, the :c:func:`smf_get_current_leaf_state`
+function should be called.
+For example::
+
+   const struct smf_state *leaf_state = smf_get_current_leaf_state(SMF_CTX(&s_obj));
+
+.. note:: If :kconfig:option:`CONFIG_SMF_INITIAL_TRANSITION` is not enabled, or
+	if the initial state of a parent state is not defined, always set the state
+	to a leaf state. Otherwise, the state machine may enter a parent state directly,
+	and :c:func:`smf_get_current_leaf_state` may return a parent state instead of
+	a leaf state. Ensure initial transitions are properly configured for all parent
+	states to avoid malformed hierarchical state machines.
+
+To retrieve the state whose entry, run, or exit action is currently being executed,
+use the :c:func:`smf_get_current_executing_state` function.
+
 UML State Machines
 ==================
 
@@ -380,6 +407,9 @@ When designing hierarchical state machines, the following should be considered:
    function is called.
  - The parent_run function only executes if the child_run function does not
    call either :c:func:`smf_set_state` or return :c:enum:`SMF_EVENT_HANDLED`.
+ - Avoid malformed hierarchical state machines by ensuring the state always
+   transitions to a leaf state when :kconfig:option:`CONFIG_SMF_INITIAL_TRANSITION`
+   is not enabled, or when a parent state's initial state is undefined.
 
 Event Driven State Machine Example
 **********************************

include/zephyr/smf.h

@@ -180,6 +180,36 @@ void smf_set_terminate(struct smf_ctx *ctx, int32_t val);
  */
 int32_t smf_run_state(struct smf_ctx *ctx);
 
+/**
+ * @brief Get the current leaf state.
+ *
+ * @note This may be a PARENT state if the HSM is malformed
+ *		 (i.e. the initial transitions are not set up correctly).
+ *
+ * @param ctx State machine context
+ * @return    The current leaf state.
+ */
+static inline const struct smf_state *smf_get_current_leaf_state(const struct smf_ctx *const ctx)
+{
+	return ctx->current;
+}
+
+/**
+ * @brief Get the state that is currently executing. This may be a parent state.
+ *
+ * @param ctx State machine context
+ * @return    The state that is currently executing.
+ */
+static inline const struct smf_state *
+smf_get_current_executing_state(const struct smf_ctx *const ctx)
+{
+#ifdef CONFIG_SMF_ANCESTOR_SUPPORT
+	return ctx->executing;
+#else
+	return ctx->current;
+#endif /* CONFIG_SMF_ANCESTOR_SUPPORT */
+}
+
 #ifdef __cplusplus
 }
 #endif

lib/smf/smf.c

@@ -110,6 +110,7 @@ static bool smf_execute_all_entry_actions(struct smf_ctx *const ctx,
 
 			/* No need to continue if terminate was set */
 			if (internal->terminate) {
+				ctx->executing = ctx->current;
 				return true;
 			}
 		}
@@ -122,10 +123,13 @@ static bool smf_execute_all_entry_actions(struct smf_ctx *const ctx,
 
 		/* No need to continue if terminate was set */
 		if (internal->terminate) {
+			ctx->executing = ctx->current;
 			return true;
 		}
 	}
 
+	ctx->executing = ctx->current;
+
 	return false;
 }
 
@@ -165,6 +169,7 @@ static bool smf_execute_ancestor_run_actions(struct smf_ctx *const ctx)
 			}
 			/* No need to continue if terminate was set */
 			if (internal->terminate) {
+				ctx->executing = ctx->current;
 				return true;
 			}
 
@@ -177,6 +182,8 @@ static bool smf_execute_ancestor_run_actions(struct smf_ctx *const ctx)
 
 	/* All done executing the run actions */
 
+	ctx->executing = ctx->current;
+
 	return false;
 }
 
@@ -190,19 +197,24 @@ static bool smf_execute_ancestor_run_actions(struct smf_ctx *const ctx)
 static bool smf_execute_all_exit_actions(struct smf_ctx *const ctx, const struct smf_state *topmost)
 {
 	struct internal_ctx *const internal = (void *)&ctx->internal;
+	const struct smf_state *tmp_state = ctx->executing;
 
 	for (const struct smf_state *to_execute = ctx->current;
 	     to_execute != NULL && to_execute != topmost; to_execute = to_execute->parent) {
 		if (to_execute->exit) {
+			ctx->executing = to_execute;
 			to_execute->exit(ctx);
 
 			/* No need to continue if terminate was set in the exit action */
 			if (internal->terminate) {
+				ctx->executing = tmp_state;
 				return true;
 			}
 		}
 	}
 
+	ctx->executing = tmp_state;
+
 	return false;
 }
 #endif /* CONFIG_SMF_ANCESTOR_SUPPORT */
@@ -250,7 +262,9 @@ void smf_set_initial(struct smf_ctx *const ctx, const struct smf_state *init_sta
 	 * doesn't
 	 */
 	if (topmost->entry) {
+		ctx->executing = topmost;
 		topmost->entry(ctx);
+		ctx->executing = init_state;
 		if (internal->terminate) {
 			/* No need to continue if terminate was set */
 			return;
@@ -345,6 +359,7 @@ void smf_set_state(struct smf_ctx *const ctx, const struct smf_state *new_state)
 	/* update the state variables */
 	ctx->previous = ctx->current;
 	ctx->current = new_state;
+	ctx->executing = new_state;
 
 	/* call all entry actions (except those of topmost) */
 	if (smf_execute_all_entry_actions(ctx, new_state, topmost)) {

tests/lib/smf/src/test_lib_flat_smf.c

@@ -10,35 +10,34 @@
 /*
  * Flat Test Transition:
  *
- *	A_ENTRY --> A_RUN --> A_EXIT --> B_ENTRY --> B_RUN --|
- *	                                                     |
- *	|----------------------------------------------------|
- *	|
- *	|--> B_EXIT --> C_ENTRY --> C_RUN --> C_EXIT
+ * A_ENTRY --> A_RUN --> A_EXIT --> B_ENTRY --> B_RUN --|
+ *                                                      |
+ * |----------------------------------------------------|
+ * |
+ * |--> B_EXIT --> C_ENTRY --> C_RUN --> C_EXIT --> D_ENTRY
  *
  */
 
-
 #define TEST_OBJECT(o) ((struct test_object *)o)
 
-#define SMF_RUN                         3
+#define SMF_RUN 3
 
-#define STATE_A_ENTRY_BIT       (1 << 0)
-#define STATE_A_RUN_BIT         (1 << 1)
-#define STATE_A_EXIT_BIT        (1 << 2)
+#define STATE_A_ENTRY_BIT (1 << 0)
+#define STATE_A_RUN_BIT   (1 << 1)
+#define STATE_A_EXIT_BIT  (1 << 2)
 
-#define STATE_B_ENTRY_BIT       (1 << 3)
-#define STATE_B_RUN_BIT         (1 << 4)
-#define STATE_B_EXIT_BIT        (1 << 5)
+#define STATE_B_ENTRY_BIT (1 << 3)
+#define STATE_B_RUN_BIT   (1 << 4)
+#define STATE_B_EXIT_BIT  (1 << 5)
 
-#define STATE_C_ENTRY_BIT       (1 << 6)
-#define STATE_C_RUN_BIT         (1 << 7)
-#define STATE_C_EXIT_BIT        (1 << 8)
+#define STATE_C_ENTRY_BIT (1 << 6)
+#define STATE_C_RUN_BIT   (1 << 7)
+#define STATE_C_EXIT_BIT  (1 << 8)
 
-#define TEST_ENTRY_VALUE_NUM     0
-#define TEST_RUN_VALUE_NUM       4
-#define TEST_EXIT_VALUE_NUM      8
-#define TEST_VALUE_NUM           9
+#define TEST_ENTRY_VALUE_NUM 0
+#define TEST_RUN_VALUE_NUM   4
+#define TEST_EXIT_VALUE_NUM  8
+#define TEST_VALUE_NUM       9
 
 static uint32_t test_value[] = {
 	0x00,  /* STATE_A_ENTRY */
@@ -80,11 +79,15 @@ static struct test_object {
 
 static void state_a_entry(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_A],
+		      "Fail to get the currently-executing state at entry. Expected: State A");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_A],
+		      "Fail to get the current leaf state at entry. Expected: State A");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx = 0;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State A entry failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State A entry failed");
 
 	if (o->terminate == ENTRY) {
 		smf_set_terminate(obj, -1);
@@ -96,11 +99,15 @@ static void state_a_entry(void *obj)
 
 static enum smf_state_result state_a_run(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_A],
+		      "Fail to get the currently-executing state at run. Expected: State A");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_A],
+		      "Fail to get the current leaf state at run. Expected: State A");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State A run failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State A run failed");
 
 	o->transition_bits |= STATE_A_RUN_BIT;
 
@@ -110,33 +117,45 @@ static enum smf_state_result state_a_run(void *obj)
 
 static void state_a_exit(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_A],
+		      "Fail to get the currently-executing state at exit. Expected: State A");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_A],
+		      "Fail to get the current leaf state at exit. Expected: State A");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State A exit failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State A exit failed");
 
 	o->transition_bits |= STATE_A_EXIT_BIT;
 }
 
 static void state_b_entry(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_B],
+		      "Fail to get the currently-executing state at entry. Expected: State B");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_B],
+		      "Fail to get the current leaf state at entry. Expected: State B");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State B entry failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State B entry failed");
 
 	o->transition_bits |= STATE_B_ENTRY_BIT;
 }
 
 static enum smf_state_result state_b_run(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_B],
+		      "Fail to get the currently-executing state at run. Expected: State B");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_B],
+		      "Fail to get the current leaf state at run. Expected: State B");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State B run failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State B run failed");
 
 	if (o->terminate == RUN) {
 		smf_set_terminate(obj, -1);
@@ -151,31 +170,43 @@ static enum smf_state_result state_b_run(void *obj)
 
 static void state_b_exit(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_B],
+		      "Fail to get the currently-executing state at exit. Expected: State B");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_B],
+		      "Fail to get the current leaf state at exit. Expected: State B");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State B exit failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State B exit failed");
 	o->transition_bits |= STATE_B_EXIT_BIT;
 }
 
 static void state_c_entry(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_C],
+		      "Fail to get the currently-executing state at entry. Expected: State C");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_C],
+		      "Fail to get the current leaf state at entry. Expected: State C");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State C entry failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State C entry failed");
 	o->transition_bits |= STATE_C_ENTRY_BIT;
 }
 
 static enum smf_state_result state_c_run(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_C],
+		      "Fail to get the currently-executing state at run. Expected: State C");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_C],
+		      "Fail to get the current leaf state at run. Expected: State C");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State C run failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State C run failed");
 	o->transition_bits |= STATE_C_RUN_BIT;
 
 	smf_set_state(SMF_CTX(obj), &test_states[STATE_D]);
@@ -184,11 +215,15 @@ static enum smf_state_result state_c_run(void *obj)
 
 static void state_c_exit(void *obj)
 {
+	zassert_equal(smf_get_current_executing_state(SMF_CTX(obj)), &test_states[STATE_C],
+		      "Fail to get the currently-executing state at exit. Expected: State C");
+	zassert_equal(smf_get_current_leaf_state(SMF_CTX(obj)), &test_states[STATE_C],
+		      "Fail to get the current leaf state at exit. Expected: State C");
+
 	struct test_object *o = TEST_OBJECT(obj);
 
 	o->tv_idx++;
-	zassert_equal(o->transition_bits, test_value[o->tv_idx],
-		      "Test State C exit failed");
+	zassert_equal(o->transition_bits, test_value[o->tv_idx], "Test State C exit failed");
 
 	if (o->terminate == EXIT) {
 		smf_set_terminate(obj, -1);
@@ -237,8 +272,7 @@ ZTEST(smf_tests, test_smf_flat)
 		}
 	}
 
-	zassert_equal(TEST_VALUE_NUM, test_obj.tv_idx,
-		      "Incorrect test value index");
+	zassert_equal(TEST_VALUE_NUM, test_obj.tv_idx, "Incorrect test value index");
 	zassert_equal(test_obj.transition_bits, test_value[test_obj.tv_idx],
 		      "Final state not reached");