State Machine Framework API

State Machine Framework API. More...

Data Structures
struct	smf_hooks
	Collection of optional instrumentation hooks. More...
struct	smf_state
	General state that can be used in multiple state machines. More...
struct	smf_ctx
	Defines the current context of the state machine. More...

Macros
#define	SMF_CREATE_STATE(_entry, _run, _exit, _parent, _initial)
	Macro to create a hierarchical state with initial transitions.
#define	SMF_CTX(o)
	Macro to cast user defined object to state machine context.
#define	SMF_ERR_NULL_TRANSITION   1
	Error codes reported via the instrumentation error hook.
#define	SMF_ERR_TRANSITION_IN_EXIT   2
	smf_set_state called in exit action

Typedefs
typedef void(*	smf_transition_hook) (struct smf_ctx *ctx, const struct smf_state *source, const struct smf_state *dest)
	Called after the current state pointer is updated, before entry actions of the new state execute.
typedef void(*	smf_action_hook) (struct smf_ctx *ctx, const struct smf_state *state, enum smf_action_type action_type)
	Called before a state action (entry/run/exit) is invoked.
typedef void(*	smf_error_hook) (struct smf_ctx *ctx, int error_code)
	Called when an invalid operation is detected.
typedef void(*	state_method) (void *obj)
	Function pointer that implements a entry and exit actions of a state.
typedef enum smf_state_result(*	state_execution) (void *obj)
	Function pointer that implements a the run action of a state.

Enumerations
enum	smf_state_result { SMF_EVENT_HANDLED , SMF_EVENT_PROPAGATE }
	enum for the return value of a state_execution function More...
enum	smf_action_type { SMF_ACTION_ENTRY , SMF_ACTION_RUN , SMF_ACTION_EXIT }
	Enum identifying which action type is being executed. More...

Functions
void	smf_set_initial (struct smf_ctx *ctx, const struct smf_state *init_state)
	Initializes the state machine and sets its initial state.
void	smf_set_state (struct smf_ctx *ctx, const struct smf_state *new_state)
	Changes a state machines state.
void	smf_set_terminate (struct smf_ctx *ctx, int32_t val)
	Terminate a state machine.
int32_t	smf_run_state (struct smf_ctx *ctx)
	Runs one iteration of a state machine (including any parent states)
static const struct smf_state *	smf_get_current_leaf_state (const struct smf_ctx *const ctx)
	Get the current leaf state.
static const struct smf_state *	smf_get_current_executing_state (const struct smf_ctx *const ctx)
	Get the state that is currently executing.

Detailed Description

State Machine Framework API.

Version

0.2.0

Macro Definition Documentation

SMF_CREATE_STATE

#define SMF_CREATE_STATE	(		_entry,
			_run,
			_exit,
			_parent,
			_initial )

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Value:

{                                                                          \
        .entry   = _entry,                                                 \
        .run     = _run,                                                   \
        .exit    = _exit,                                                  \
        IF_ENABLED(CONFIG_SMF_ANCESTOR_SUPPORT, (.parent = _parent,))      \
        IF_ENABLED(CONFIG_SMF_INITIAL_TRANSITION, (.initial = _initial,))  \
}

Macro to create a hierarchical state with initial transitions.

Parameters

_entry	State entry function or NULL
_run	State run function or NULL
_exit	State exit function or NULL
_parent	State parent object or NULL
_initial	State initial transition object or NULL

SMF_CTX

#define SMF_CTX

(

o

)

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Value:

((struct smf_ctx *)o)

Macro to cast user defined object to state machine context.

Parameters

o	A pointer to the user defined object

SMF_ERR_NULL_TRANSITION

#define SMF_ERR_NULL_TRANSITION   1

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Error codes reported via the instrumentation error hook.

new_state is NULL in smf_set_state

SMF_ERR_TRANSITION_IN_EXIT

#define SMF_ERR_TRANSITION_IN_EXIT   2

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

smf_set_state called in exit action

Typedef Documentation

smf_action_hook

typedef void(* smf_action_hook) (struct smf_ctx *ctx, const struct smf_state *state, enum smf_action_type action_type)

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Called before a state action (entry/run/exit) is invoked.

Parameters

ctx	State machine context
state	The state whose action is about to execute
action_type	Which action (entry, run, or exit)

smf_error_hook

typedef void(* smf_error_hook) (struct smf_ctx *ctx, int error_code)

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Called when an invalid operation is detected.

Parameters

ctx	State machine context
error_code	One of SMF_ERR_* defines

smf_transition_hook

typedef void(* smf_transition_hook) (struct smf_ctx *ctx, const struct smf_state *source, const struct smf_state *dest)

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Called after the current state pointer is updated, before entry actions of the new state execute.

Parameters

ctx	State machine context
source	Previous state (before transition)
dest	New current state (after transition)

state_execution

typedef enum smf_state_result(* state_execution) (void *obj)

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Function pointer that implements a the run action of a state.

Parameters

obj	pointer user defined object

Returns

If the event should be propagated to parent states or not (Ignored when CONFIG_SMF_ANCESTOR_SUPPORT not defined)

state_method

typedef void(* state_method) (void *obj)

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Function pointer that implements a entry and exit actions of a state.

Parameters

obj	pointer user defined object

Enumeration Type Documentation

smf_action_type

enum smf_action_type

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Enum identifying which action type is being executed.

Note

This is used for instrumentation purposes.

Enumerator
SMF_ACTION_ENTRY	Entry action.
SMF_ACTION_RUN	Run action.
SMF_ACTION_EXIT	Exit action.

smf_state_result

enum smf_state_result

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

enum for the return value of a state_execution function

Enumerator
SMF_EVENT_HANDLED
SMF_EVENT_PROPAGATE

Function Documentation

smf_get_current_executing_state()

const struct smf_state * smf_get_current_executing_state ( const struct smf_ctx *const ctx )

inlinestatic

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Get the state that is currently executing.

This may be a parent state.

Parameters

ctx	State machine context

Returns

The state that is currently executing.

smf_get_current_leaf_state()

const struct smf_state * smf_get_current_leaf_state ( const struct smf_ctx *const ctx )

inlinestatic

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

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).

Parameters

ctx	State machine context

Returns

The current leaf state.

smf_run_state()

int32_t smf_run_state

(

struct smf_ctx *

ctx

)

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Runs one iteration of a state machine (including any parent states)

Parameters

ctx	State machine context

Returns

A non-zero value should terminate the state machine. This non-zero value could represent a terminal state being reached or the detection of an error that should result in the termination of the state machine.

smf_set_initial()

void smf_set_initial	(	struct smf_ctx *	ctx,
		const struct smf_state *	init_state )

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Initializes the state machine and sets its initial state.

Parameters

ctx	State machine context
init_state	Initial state the state machine starts in.

smf_set_state()

void smf_set_state	(	struct smf_ctx *	ctx,
		const struct smf_state *	new_state )

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Changes a state machines state.

This handles exiting the previous state and entering the target state. For HSMs the entry and exit actions of the Least Common Ancestor will not be run.

Parameters

ctx	State machine context
new_state	State to transition to (NULL is valid and exits all states)

smf_set_terminate()

void smf_set_terminate	(	struct smf_ctx *	ctx,
		int32_t	val )

#include </__w/bridle/bridle/workspace/zephyr/include/zephyr/smf.h>

Terminate a state machine.

Parameters

ctx	State machine context
val	Non-Zero termination value that's returned by the smf_run_state function.