RFC: SMF add return code to signal event has been handled

[glenn-andrews]

Overview

SMF implements a hierarchical state machine (HSM) if CONFIG_SMF_ANCESTOR_SUPPORT is enabled.

In an HSM, if the most-nested leaf state does not handle an event, parent state handlers are executed until one of them does handle it or the outermost state has been called. smf_set_handled() is called to indicate a state has handled the event and to stop propagation to parent states.

Problem

The problem with this is it is very easy to forget smf_set_handled() and accidentally propagate the event to the parents.

Most state machine frameworks use a return code from the handler function to indicate if the state handled the event, or not. Frameworks like Quantum Platforms go further and handle transitions as part of the return code.

SMF did not do this because the original version did not allow for events not to be propagated, and smf_set_handled() was an attempt at providing correct HSM behavior without breaking existing code.

Proposal:

Remove the smf_set_handled() function and modify the state handler functions to take a return code with two options:

enum smf_event_result {
        SMF_EVENT_HANDLED,
        SMF_EVENT_PROPAGATE,
};

By changing the return value from void to enum smf_event_result, the users will be forced to specify if the event has been handled or not, removing the error of omitting smf_set_handled().

Options

If preferred, we could also add an SMF_EVENT_TRANSITIONED to signal the event caused a transition and to execute the exit and entry actions associated with the transition. smf_set_state() would simply sets the destination function pointer but would not execute the entry/exit actions. My concern with that would be returning SMF_EVENT_TRANSITIONED without calling smf_set_state() is an error, and also breaks any code that does cleanup after calling smf_set_state().

An alternate idiom would be to have smf_set_state() return SMF_EVENT_HANDLED on success and use return smf_set_state() to transition. Again this breaks any code that performs actions after calling smf_set_state() that are currently allowed.

Ramifications:

All code currently using SMF would break, including USB-C and hawkBit, as well as tests and samples. The PR would have to refactor these services, tests and samples as well.