fsm.h File Reference

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

Include dependency graph for fsm.h:

Go to the source code of this file.

Data Structures
struct	ecu_fsm_state
	Single state in fsm, initialized via ECU_FSM_STATE_CTOR(). Pointers are const-qualified to only allow states to be created at compile-time. More...
struct	ecu_fsm
	Finite state machine. Users create their own FSMs by containing this as an intrusive member. More...

Macros
#define	ECU_FSM_GET_CONTEXT(ecu_fsm_ptr_, type_, member_)    ECU_CONTAINER_OF(ecu_fsm_ptr_, type_, member_)
	Converts intrusive ecu_fsm member into the user's fsm type. This should be used inside each state's definition. More...
#define	ECU_FSM_STATE_ENTRY_UNUSED    ((void (*)(struct ecu_fsm *))0)
	Helper macro supplied to ECU_FSM_STATE_CTOR() if state's entry handler is unused.
#define	ECU_FSM_STATE_EXIT_UNUSED    ((void (*)(struct ecu_fsm *))0)
	Helper macro supplied to ECU_FSM_STATE_CTOR() if state's exit handler is unused.
#define	ECU_FSM_STATE_CTOR(entry_, exit_, handler_)
	Creates an ecu_fsm_state at compile-time. Example usage: More...

Functions
Constructors
void	ecu_fsm_ctor (struct ecu_fsm *me, const struct ecu_fsm_state *state)
	Fsm constructor. More...
Member Functions
void	ecu_fsm_change_state (struct ecu_fsm *me, const struct ecu_fsm_state *state)
	Transitions fsm into a new state. More...
void	ecu_fsm_dispatch (struct ecu_fsm *me, const void *event)
	Relays event to fsm where it is processed by the current state's handler function. Manages all state transition logic if any state changes were signalled via ecu_fsm_change_state(). More...
void	ecu_fsm_start (struct ecu_fsm *me)
	Runs the initial state's entry handler and manages all state transition logic if any state changes were signalled via ecu_fsm_change_state(). This function does nothing if the initial state's entry handler is unused. More...

Detailed Description

See fsm.h section in Sphinx documentation.

Author

Ian Ress

Version

0.1

Date

2024-03-14

Copyright

Copyright (c) 2025

Macro Definition Documentation

ECU_FSM_GET_CONTEXT

#define ECU_FSM_GET_CONTEXT	(		ecu_fsm_ptr_,
			type_,
			member_
	)		ECU_CONTAINER_OF(ecu_fsm_ptr_, type_, member_)

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

Parameters

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

ECU_FSM_STATE_CTOR

#define ECU_FSM_STATE_CTOR	(		entry_,
			exit_,
			handler_
	)

Value:

    {                                               \
        .entry = (entry_),                          \
        .exit = (exit_),                            \
        .handler = (handler_)                       \
    }

Creates an ecu_fsm_state at compile-time. Example usage:

static const struct ecu_fsm_state STATE1 = ECU_FSM_STATE_CTOR(
     &entry_handler, ECU_FSM_STATE_EXIT_UNUSED, &state_handler
);

Parameters

entry_	Optional function that executes when state is first entered. This must be of type (void (*)(struct ecu_fsm *)). Supply ECU_FSM_STATE_ENTRY_UNUSED if unused.
exit_	Optional function that executes when state exits. This must be of type (void (*)(struct ecu_fsm *)). Supply ECU_FSM_STATE_EXIT_UNUSED if unused.
handler_	Mandatory function that processes events dispatched to this state. This must be of type (void (*)(struct ecu_fsm *, const void *)).

Function Documentation

ecu_fsm_change_state()

void ecu_fsm_change_state	(	struct ecu_fsm *	me,
		const struct ecu_fsm_state *	state
	)

Transitions fsm into a new state.

Precondition

state constructed via ECU_FSM_STATE_CTOR().

Warning

This must only be called within ecu_fsm_state::handler and ecu_fsm_state::entry.

Parameters

me	Fsm to transition.
state	State to transition into. If fsm's current state == state then a self-transition will occur. I.e. state::exit then state::entry.

ecu_fsm_ctor()

void ecu_fsm_ctor	(	struct ecu_fsm *	me,
		const struct ecu_fsm_state *	state
	)

Fsm constructor.

Precondition

Memory already allocated for me.

state constructed via ECU_FSM_STATE_CTOR().

Warning

Supplied fsm cannot be active, otherwise behavior is undefined.

Parameters

me	Fsm to construct.
state	Fsm's initial state.

ecu_fsm_dispatch()

void ecu_fsm_dispatch	(	struct ecu_fsm *	me,
		const void *	event
	)

Relays event to fsm where it is processed by the current state's handler function. Manages all state transition logic if any state changes were signalled via ecu_fsm_change_state().

Precondition

me constructed via ecu_fsm_ctor().

Warning

This function must run to completion.

Parameters

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

ecu_fsm_start()

void ecu_fsm_start

(

struct ecu_fsm *

me

)

Runs the initial state's entry handler and manages all state transition logic if any state changes were signalled via ecu_fsm_change_state(). This function does nothing if the initial state's entry handler is unused.

Precondition

me constructed via ecu_fsm_ctor().

Warning

This function should only be called once on startup and must run to completion.

Parameters

me	Fsm to start. This should not be an already running fsm.