hsm.h File Reference

#include <stdbool.h>
#include <stddef.h>
#include <stdint.h>
#include "ecu/utils.h"

Include dependency graph for hsm.h:

Go to the source code of this file.

Data Structures
struct	ecu_hsm_state
	Single state in hsm, initialized via ECU_HSM_STATE_CTOR(). Pointers are const-qualified to only allow states to be created at compile-time. More...
struct	ecu_hsm
	Hierarchical state machine. Users create their own HSMs by containing this as an intrusive member. More...

Macros
#define	ECU_HSM_GET_CONTEXT(ecu_hsm_ptr_, type_, member_)    ECU_CONTAINER_OF(ecu_hsm_ptr_, type_, member_)
	Converts intrusive ecu_hsm member into the user's hsm type. This should be used inside each state's definition. More...
#define	ECU_HSM_STATE_ENTRY_UNUSED    ((void (*)(struct ecu_hsm *))0)
	Helper macro supplied to ECU_HSM_STATE_CTOR() if state's entry handler is unused.
#define	ECU_HSM_STATE_EXIT_UNUSED    ((void (*)(struct ecu_hsm *))0)
	Helper macro supplied to ECU_HSM_STATE_CTOR() if state's exit handler is unused.
#define	ECU_HSM_STATE_INITIAL_UNUSED    ((void (*)(struct ecu_hsm *))0)
	Helper macro supplied to ECU_HSM_STATE_CTOR() if state's initial handler is unused. More...
#define	ECU_HSM_STATE_CTOR(entry_, exit_, initial_, handler_, parent_)
	Creates an ecu_hsm_state at compile-time. Example usage: More...

Functions
Constructors
void	ecu_hsm_ctor (struct ecu_hsm *me, const struct ecu_hsm_state *state, uint8_t height)
	Hsm constructor. More...
Member Functions
void	ecu_hsm_change_state (struct ecu_hsm *me, const struct ecu_hsm_state *state)
	Transitions hsm into a new state. More...
void	ecu_hsm_dispatch (struct ecu_hsm *me, const void *event)
	Relays event to hsm where it is processed by the current state's handler function. The event is propagated up the state hierarchy until it is handled. All state transitions signalled via ecu_hsm_change_state() are also managed in this function. More...
void	ecu_hsm_start (struct ecu_hsm *me)
	Starts the hsm by entering from ECU_HSM_TOP_STATE to the target state supplied in ecu_hsm_ctor(). If the target is a composite state, initial handlers are ran to fully transition down the state hierarchy. More...

Variables
const struct ecu_hsm_state	ECU_HSM_TOP_STATE
	The default top state. Serves as the root of every hsm.

Detailed Description

See hsm.h section in Sphinx documentation.

Author

Ian Ress

Version

0.1

Date

2025-05-01

Copyright

Copyright (c) 2025

Macro Definition Documentation

ECU_HSM_GET_CONTEXT

#define ECU_HSM_GET_CONTEXT	(		ecu_hsm_ptr_,
			type_,
			member_
	)		ECU_CONTAINER_OF(ecu_hsm_ptr_, type_, member_)

Converts intrusive ecu_hsm member into the user's hsm type. This should be used inside each state's definition.

Parameters

ecu_hsm_ptr_	Pointer to intrusive ecu_hsm. This must be pointer to non-const. I.e. (struct ecu_hsm *).
type_	User's hsm type containing the intrusive ecu_hsm member. Do not use const specifier. I.e. (struct my_type), never (const struct my_type).
member_	Name of ecu_hsm member within user's type.

ECU_HSM_STATE_CTOR

#define ECU_HSM_STATE_CTOR	(		entry_,
			exit_,
			initial_,
			handler_,
			parent_
	)

Value:

    {                                                                  \
        .entry = (entry_),                                             \
        .exit = (exit_),                                               \
        .initial = (initial_),                                         \
        .handler = (handler_),                                         \
        .parent = (parent_)                                            \
    }

Creates an ecu_hsm_state at compile-time. Example usage:

static const struct ecu_hsm_state STATE1 = ECU_HSM_STATE_CTOR(
     &entry_handler, ECU_HSM_STATE_EXIT_UNUSED, &state_handler, &initial_handler, &PARENT_STATE
);

Parameters

entry_	Optional function that executes when state is first entered. This must be of type (void (*)(struct ecu_hsm *)). Supply ECU_FSM_STATE_ENTRY_UNUSED if unused.
exit_	Optional function that executes when state exits. This must be of type (void (*)(struct ecu_hsm *)). Supply ECU_FSM_STATE_EXIT_UNUSED if unused.
initial_	Function that transitions to starting (child) state when a transition targets a composite state. Mandatory for composite states. Otherwise supply ECU_HSM_STATE_INITIAL_UNUSED for leaf states. This must be of type (void (*)(struct ecu_hsm *)).
handler_	Mandatory function that processes events dispatched to this state. This must be of type (void (*)(struct ecu_hsm *, const void *)).
parent_	This state's parent. Supply pointer to ECU_HSM_TOP_STATE if this state's parent is the default top state.

ECU_HSM_STATE_INITIAL_UNUSED

#define ECU_HSM_STATE_INITIAL_UNUSED    ((void (*)(struct ecu_hsm *))0)

Helper macro supplied to ECU_HSM_STATE_CTOR() if state's initial handler is unused.

Warning

This can only be used for leaf states.

Function Documentation

ecu_hsm_change_state()

void ecu_hsm_change_state	(	struct ecu_hsm *	me,
		const struct ecu_hsm_state *	state
	)

Transitions hsm into a new state.

Precondition

state constructed via ECU_HSM_STATE_CTOR().

Warning

This can only be called within ecu_hsm_state::handler and ecu_hsm_state::initial. If a transition is signalled in ecu_hsm_state::handler, it must handle the event by returning true. The HSM must be in a leaf state after all transitions are completed.

Parameters

me	Hsm to transition.
state	State to transition into. This cannot be ECU_HSM_TOP_STATE.

ecu_hsm_ctor()

void ecu_hsm_ctor	(	struct ecu_hsm *	me,
		const struct ecu_hsm_state *	state,
		uint8_t	height
	)

Hsm constructor.

Precondition

Memory already allocated for me.

state constructed via ECU_HSM_STATE_CTOR().

Parameters

me	Hsm to construct.
state	Hsm's initial state. This cannot be ECU_HSM_TOP_STATE.
height	Number of levels in the hsm, starting at 1. For example if the hsm only consists of a single state, this would be 1 (user's state and ECU_HSM_TOP_STATE).

ecu_hsm_dispatch()

void ecu_hsm_dispatch	(	struct ecu_hsm *	me,
		const void *	event
	)

Relays event to hsm where it is processed by the current state's handler function. The event is propagated up the state hierarchy until it is handled. All state transitions signalled via ecu_hsm_change_state() are also managed in this function.

Precondition

me constructed via ecu_hsm_ctor() and started via ecu_hsm_start().

Warning

This function must run to completion. The HSM must be in a leaf state after this function completes.

Parameters

me	Hsm to run.
event	Event to dispatch. This cannot be NULL.

ecu_hsm_start()

void ecu_hsm_start

(

struct ecu_hsm *

me

)

Starts the hsm by entering from ECU_HSM_TOP_STATE to the target state supplied in ecu_hsm_ctor(). If the target is a composite state, initial handlers are ran to fully transition down the state hierarchy.

Precondition

me constructed via ecu_hsm_ctor().

Warning

This function should only be called once on startup and must run to completion. The HSM must be in a leaf state after this function completes.

Parameters

me	Hsm to start. This should not be an already running hsm.