Finite State Machine abstraction

Finite State Machine abstraction. More...

Files
file	fsm.h
	Finite State Machine.
file	fsm.c
	Osmocom generic Finite State Machine implementation.

Data Structures
struct	osmo_fsm_state
	description of a rule in the FSM More...
struct	osmo_fsm
	a description of an osmocom finite state machine More...
struct	osmo_fsm_inst
	a single instanceof an osmocom finite state machine More...

Macros
#define	LOGPFSMSL(fi, subsys, level, fmt, args...)    LOGPFSMSLSRC(fi, subsys, level, __FILE__, __LINE__, fmt, ## args)
	Log using FSM instance's context, on explicit logging subsystem and level. More...
#define	LOGPFSMSLSRC(fi, subsys, level, caller_file, caller_line, fmt, args...)
	Log using FSM instance's context, on explicit logging subsystem and level, and passing explicit source file and line information. More...
#define	LOGPFSML(fi, level, fmt, args...)    LOGPFSMLSRC(fi, level, __FILE__, __LINE__, fmt, ## args)
	Log using FSM instance's context, on explicit logging level. More...
#define	LOGPFSMLSRC(fi, level, caller_file, caller_line, fmt, args...)
	Log using FSM instance's context, on explicit logging level, and with explicit source file and line info. More...
#define	LOGPFSM(fi, fmt, args...)    LOGPFSML(fi, (fi) ? (fi)->log_level : LOGL_ERROR, fmt, ## args)
	Log using FSM instance's context. More...
#define	LOGPFSMSRC(fi, caller_file, caller_line, fmt, args...)
	Log using FSM instance's context, with explicit source file and line info. More...
#define	OSMO_T_FMT   "%c%u"
#define	OSMO_T_FMT_ARGS(T)   ((T) >= 0 ? 'T' : 'X'), ((T) >= 0 ? (T) : -(T))
#define	osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T)
	perform a state change of the given FSM instance More...
#define	osmo_fsm_inst_state_chg_ms(fi, new_state, timeout_ms, T)
#define	osmo_fsm_inst_state_chg_keep_timer(fi, new_state)
	perform a state change while keeping the current timer running. More...
#define	osmo_fsm_inst_state_chg_keep_or_start_timer(fi, new_state, timeout_secs, T)
	perform a state change while keeping the current timer if running, or starting a timer otherwise. More...
#define	osmo_fsm_inst_state_chg_keep_or_start_timer_ms(fi, new_state, timeout_ms, T)
#define	osmo_fsm_inst_dispatch(fi, event, data)    _osmo_fsm_inst_dispatch(fi, event, data, __FILE__, __LINE__)
	dispatch an event to an osmocom finite state machine instance More...
#define	osmo_fsm_inst_term(fi, cause, data)    _osmo_fsm_inst_term(fi, cause, data, __FILE__, __LINE__)
	Terminate FSM instance with given cause. More...
#define	osmo_fsm_inst_term_children(fi, cause, data)    _osmo_fsm_inst_term_children(fi, cause, data, __FILE__, __LINE__)
	Terminate all child FSM instances of an FSM instance. More...
#define	osmo_fsm_inst_broadcast_children(fi, cause, data)    _osmo_fsm_inst_broadcast_children(fi, cause, data, __FILE__, __LINE__)
	dispatch an event to all children of an osmocom finite state machine instance More...

Enumerations
enum	osmo_fsm_term_cause {   OSMO_FSM_TERM_PARENT ,   OSMO_FSM_TERM_REQUEST ,   OSMO_FSM_TERM_REGULAR ,   OSMO_FSM_TERM_ERROR ,   OSMO_FSM_TERM_TIMEOUT }

Functions
static const char *	osmo_fsm_term_cause_name (enum osmo_fsm_term_cause cause)
void	osmo_fsm_log_addr (bool log_addr)
	specify if FSM instance addresses should be logged or not More...
void	osmo_fsm_log_timeouts (bool log_timeouts)
	Enable or disable logging of timeout values for FSM instance state changes. More...
void	osmo_fsm_term_safely (bool term_safely)
	Enable safer way to deallocate cascades of terminating FSM instances. More...
void	osmo_fsm_set_dealloc_ctx (void *ctx)
	Instead of deallocating FSM instances, move them to the given talloc context. More...
int	osmo_fsm_register (struct osmo_fsm *fsm)
	register a FSM with the core More...
void	osmo_fsm_unregister (struct osmo_fsm *fsm)
	unregister a FSM from the core More...
struct osmo_fsm *	osmo_fsm_find_by_name (const char *name)
struct osmo_fsm_inst *	osmo_fsm_inst_find_by_name (const struct osmo_fsm *fsm, const char *name)
struct osmo_fsm_inst *	osmo_fsm_inst_find_by_id (const struct osmo_fsm *fsm, const char *id)
struct osmo_fsm_inst *	osmo_fsm_inst_alloc (struct osmo_fsm *fsm, void *ctx, void *priv, int log_level, const char *id)
	allocate a new instance of a specified FSM More...
struct osmo_fsm_inst *	osmo_fsm_inst_alloc_child (struct osmo_fsm *fsm, struct osmo_fsm_inst *parent, uint32_t parent_term_event)
	allocate a new instance of a specified FSM as child of other FSM instance More...
void	osmo_fsm_inst_unlink_parent (struct osmo_fsm_inst *fi, void *ctx)
	unlink child FSM from its parent FSM. More...
void	osmo_fsm_inst_change_parent (struct osmo_fsm_inst *fi, struct osmo_fsm_inst *new_parent, uint32_t new_parent_term_event)
	change parent instance of an FSM. More...
void	osmo_fsm_inst_free (struct osmo_fsm_inst *fi)
	delete a given instance of a FSM More...
int	osmo_fsm_inst_update_id (struct osmo_fsm_inst *fi, const char *id)
	Change id of the FSM instance. More...
int	osmo_fsm_inst_update_id_f (struct osmo_fsm_inst *fi, const char *fmt,...)
	Change id of the FSM instance using a string format. More...
int	osmo_fsm_inst_update_id_f_sanitize (struct osmo_fsm_inst *fi, char replace_with, const char *fmt,...)
	Change id of the FSM instance using a string format, and ensuring a valid id. More...
const char *	osmo_fsm_event_name (const struct osmo_fsm *fsm, uint32_t event)
	get human-readable name of FSM event More...
const char *	osmo_fsm_inst_name (const struct osmo_fsm_inst *fi)
	get human-readable name of FSM instance More...
const char *	osmo_fsm_state_name (const struct osmo_fsm *fsm, uint32_t state)
	get human-readable name of FSM state More...
static const char *	osmo_fsm_inst_state_name (struct osmo_fsm_inst *fi)
	return the name of the state the FSM instance is currently in. More...
int	_osmo_fsm_inst_state_chg (struct osmo_fsm_inst *fi, uint32_t new_state, unsigned long timeout_secs, int T, const char *file, int line)
	perform a state change of the given FSM instance More...
int	_osmo_fsm_inst_state_chg_ms (struct osmo_fsm_inst *fi, uint32_t new_state, unsigned long timeout_ms, int T, const char *file, int line)
int	_osmo_fsm_inst_state_chg_keep_timer (struct osmo_fsm_inst *fi, uint32_t new_state, const char *file, int line)
	perform a state change while keeping the current timer running. More...
int	_osmo_fsm_inst_state_chg_keep_or_start_timer (struct osmo_fsm_inst *fi, uint32_t new_state, unsigned long timeout_secs, int T, const char *file, int line)
	perform a state change while keeping the current timer if running, or starting a timer otherwise. More...
int	_osmo_fsm_inst_state_chg_keep_or_start_timer_ms (struct osmo_fsm_inst *fi, uint32_t new_state, unsigned long timeout_ms, int T, const char *file, int line)
int	_osmo_fsm_inst_dispatch (struct osmo_fsm_inst *fi, uint32_t event, void *data, const char *file, int line)
	dispatch an event to an osmocom finite state machine instance More...
void	_osmo_fsm_inst_term (struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause, void *data, const char *file, int line)
	Terminate FSM instance with given cause. More...
void	_osmo_fsm_inst_term_children (struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause, void *data, const char *file, int line)
	Terminate all child FSM instances of an FSM instance. More...
void	_osmo_fsm_inst_broadcast_children (struct osmo_fsm_inst *fi, uint32_t event, void *data, const char *file, int line)
	Broadcast an event to all the FSMs children. More...
	LLIST_HEAD (osmo_g_fsms)
static void	fsm_free_or_steal (void *talloc_object)
	Internal call to free an FSM instance, which redirects to the context set by osmo_fsm_set_dealloc_ctx() if any. More...
static void	osmo_fsm_defer_free (void *talloc_object)
	talloc_free() the given object immediately, or once ongoing FSM terminations are done. More...
static void	fsm_tmr_cb (void *data)
static void	update_name (struct osmo_fsm_inst *fi)
static int	state_chg (struct osmo_fsm_inst *fi, uint32_t new_state, bool keep_timer, unsigned long timeout_ms, int T, const char *file, int line)

Variables
const struct value_string	osmo_fsm_term_cause_names []
static bool	fsm_log_addr = true
static bool	fsm_log_timeouts = false
static bool	fsm_term_safely_enabled = false
	See osmo_fsm_term_safely(). More...
struct {
struct osmo_fsm_inst *   root_fi
	The first FSM instance that invoked osmo_fsm_inst_term() in the current cascade. More...
unsigned int   depth
	2 if a secondary FSM terminates, 3 if a secondary FSM causes a tertiary FSM to terminate, and so on. More...
void *   collect_ctx
	Talloc context to collect all deferred deallocations (FSM instances, and talloc objects if any). More...
void *   fsm_dealloc_ctx
	See osmo_fsm_set_dealloc_ctx() More...
}	fsm_term_safely
	Internal state for FSM instance termination cascades. More...
const struct value_string	osmo_fsm_term_cause_names []

Detailed Description

Finite State Machine abstraction.

This is a generic C-language abstraction for implementing finite state machines within the Osmocom framework. It is intended to replace existing hand-coded or even only implicitly existing FSMs all over the existing code base.

An libosmocore FSM is described by its osmo_fsm description, which in turn refers to an array of osmo_fsm_state descriptor, each describing a single state in the FSM.

The general idea is that all actions performed within one state are located at one position in the code (the state's action function), as opposed to the 'message-centric' view of e.g. the existing state machines of the LAPD(m) core, where there is one message for each possible event (primitive), and the function then needs to concern itself on how to handle that event over all possible states.

For each state, there is a bit-mask of permitted input events for this state, as well as a bit-mask of permitted new output states to which the state can change. Furthermore, there is a function pointer implementing the actual handling of the input events occurring whilst in that state.

Furthermore, each state offers a function pointer that can be executed just before leaving a state, and another one just after entering a state.

When transitioning into a new state, an optional timer number and time-out can be passed along. The timer is started just after entering the new state, and will call the osmo_fsm timer_cb function once it expires. This is intended to be used in telecom state machines where a given timer (identified by a certain number) is started to terminate the fsm or terminate the fsm once expected events are not happening before timeout expiration.

As there can often be many concurrent FSMs of one given class, we introduce the concept of osmo_fsm_inst, i.e. an FSM instance. The instance keeps the actual state, while the osmo_fsm descriptor contains the static/const descriptor of the FSM's states and possible transitions.

osmo_fsm are integrated with the libosmocore logging system. The logging sub-system is determined by the FSM descriptor, as we assume one FSM (let's say one related to a location update procedure) is inevitably always tied to a sub-system. The logging level however is configurable for each FSM instance, to ensure that e.g. DEBUG logging can be used for the LU procedure of one subscriber, while NOTICE level is used for all other subscribers.

In order to attach private state to the osmo_fsm_inst, it offers an opaque private pointer.

Macro Definition Documentation

LOGPFSM

#define LOGPFSM	(		fi,
			fmt,
			args...
	)		LOGPFSML(fi, (fi) ? (fi)->log_level : LOGL_ERROR, fmt, ## args)

Log using FSM instance's context.

The log level to log on is obtained from the FSM instance. The log subsystem to log on is obtained from the underlying FSM definition.

Parameters

fi	An osmo_fsm_inst.
fmt	printf-like format string.
args	Format string arguments.

LOGPFSML

#define LOGPFSML	(		fi,
			level,
			fmt,
			args...
	)		LOGPFSMLSRC(fi, level, __FILE__, __LINE__, fmt, ## args)

Log using FSM instance's context, on explicit logging level.

Parameters

fi	An osmo_fsm_inst.
level	A logging level, e.g. LOGL_INFO.
fmt	printf-like format string.
args	Format string arguments.

LOGPFSMLSRC

#define LOGPFSMLSRC	(		fi,
			level,
			caller_file,
			caller_line,
			fmt,
			args...
	)

Value:

                LOGPFSMSLSRC(fi, (fi) ? (fi)->fsm->log_subsys : DLGLOBAL, level, \
                             caller_file, caller_line, fmt, ## args)

Log using FSM instance's context, on explicit logging level, and with explicit source file and line info.

The log subsystem to log on is obtained from the underlying FSM definition.

Parameters

fi	An osmo_fsm_inst.
level	A logging level, e.g. LOGL_INFO.
caller_file	A string constant containing a source file path, like FILE.
caller_line	A number constant containing a source file line, like LINE.
fmt	printf-like format string.
args	Format string arguments.

LOGPFSMSL

#define LOGPFSMSL	(		fi,
			subsys,
			level,
			fmt,
			args...
	)		LOGPFSMSLSRC(fi, subsys, level, __FILE__, __LINE__, fmt, ## args)

Log using FSM instance's context, on explicit logging subsystem and level.

Parameters

fi	An osmo_fsm_inst.
subsys	A logging subsystem, e.g. DLGLOBAL.
level	A logging level, e.g. LOGL_INFO.
fmt	printf-like format string.
args	Format string arguments.

LOGPFSMSLSRC

#define LOGPFSMSLSRC	(		fi,
			subsys,
			level,
			caller_file,
			caller_line,
			fmt,
			args...
	)

Value:

                LOGPSRC(subsys, level, \
                        caller_file, caller_line, \
                        "%s{%s}: " fmt, \
                        osmo_fsm_inst_name(fi), \
                        (fi) ? osmo_fsm_state_name((fi)->fsm, (fi)->state) : "fi=NULL", ## args)

Log using FSM instance's context, on explicit logging subsystem and level, and passing explicit source file and line information.

Parameters

fi	An osmo_fsm_inst.
subsys	A logging subsystem, e.g. DLGLOBAL.
level	A logging level, e.g. LOGL_INFO.
caller_file	A string constant containing a source file path, like FILE.
caller_line	A number constant containing a source file line, like LINE.
fmt	printf-like format string.
args	Format string arguments.

LOGPFSMSRC

#define LOGPFSMSRC	(		fi,
			caller_file,
			caller_line,
			fmt,
			args...
	)

Value:

                LOGPFSMLSRC(fi, (fi) ? (fi)->log_level : LOGL_ERROR, \
                            caller_file, caller_line, \
                            fmt, ## args)

Log using FSM instance's context, with explicit source file and line info.

The log level to log on is obtained from the FSM instance. The log subsystem to log on is obtained from the underlying FSM definition.

Parameters

fi	An osmo_fsm_inst.
caller_file	A string constant containing a source file path, like FILE.
caller_line	A number constant containing a source file line, like LINE.
fmt	printf-like format string.
args	Format string arguments.

osmo_fsm_inst_broadcast_children

#define osmo_fsm_inst_broadcast_children	(		fi,
			cause,
			data
	)		_osmo_fsm_inst_broadcast_children(fi, cause, data, __FILE__, __LINE__)

dispatch an event to all children of an osmocom finite state machine instance

This is a macro that calls _osmo_fsm_inst_broadcast_children() with the given parameters as well as the caller's source file and line number for logging purposes. See there for documentation.

osmo_fsm_inst_dispatch

#define osmo_fsm_inst_dispatch	(		fi,
			event,
			data
	)		_osmo_fsm_inst_dispatch(fi, event, data, __FILE__, __LINE__)

dispatch an event to an osmocom finite state machine instance

This is a macro that calls _osmo_fsm_inst_dispatch() with the given parameters as well as the caller's source file and line number for logging purposes. See there for documentation.

osmo_fsm_inst_state_chg

#define osmo_fsm_inst_state_chg	(		fi,
			new_state,
			timeout_secs,
			T
	)

Value:

        _osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T, \
                                 __FILE__, __LINE__)

perform a state change of the given FSM instance

This is a macro that calls _osmo_fsm_inst_state_chg() with the given parameters as well as the caller's source file and line number for logging purposes. See there for documentation.

osmo_fsm_inst_state_chg_keep_or_start_timer

#define osmo_fsm_inst_state_chg_keep_or_start_timer	(		fi,
			new_state,
			timeout_secs,
			T
	)

Value:

        _osmo_fsm_inst_state_chg_keep_or_start_timer(fi, new_state, timeout_secs, T, \
                                                     __FILE__, __LINE__)

perform a state change while keeping the current timer if running, or starting a timer otherwise.

This is useful to keep a timeout across several states, but to make sure that some timeout is actually running.

This is a macro that calls _osmo_fsm_inst_state_chg_keep_or_start_timer() with the given parameters as well as the caller's source file and line number for logging purposes. See there for documentation.

osmo_fsm_inst_state_chg_keep_or_start_timer_ms

#define osmo_fsm_inst_state_chg_keep_or_start_timer_ms	(		fi,
			new_state,
			timeout_ms,
			T
	)

Value:

        _osmo_fsm_inst_state_chg_keep_or_start_timer_ms(fi, new_state, timeout_ms, T, \
                                                     __FILE__, __LINE__)

osmo_fsm_inst_state_chg_keep_timer

#define osmo_fsm_inst_state_chg_keep_timer	(		fi,
			new_state
	)

Value:

        _osmo_fsm_inst_state_chg_keep_timer(fi, new_state, \
                                 __FILE__, __LINE__)

perform a state change while keeping the current timer running.

This is useful to keep a timeout across several states (without having to round the remaining time to seconds).

This is a macro that calls _osmo_fsm_inst_state_chg_keep_timer() with the given parameters as well as the caller's source file and line number for logging purposes. See there for documentation.

osmo_fsm_inst_state_chg_ms

#define osmo_fsm_inst_state_chg_ms	(		fi,
			new_state,
			timeout_ms,
			T
	)

Value:

        _osmo_fsm_inst_state_chg_ms(fi, new_state, timeout_ms, T, \
                                 __FILE__, __LINE__)

osmo_fsm_inst_term

#define osmo_fsm_inst_term	(		fi,
			cause,
			data
	)		_osmo_fsm_inst_term(fi, cause, data, __FILE__, __LINE__)

Terminate FSM instance with given cause.

This is a macro that calls _osmo_fsm_inst_term() with the given parameters as well as the caller's source file and line number for logging purposes. See there for documentation.

osmo_fsm_inst_term_children

#define osmo_fsm_inst_term_children	(		fi,
			cause,
			data
	)		_osmo_fsm_inst_term_children(fi, cause, data, __FILE__, __LINE__)

Terminate all child FSM instances of an FSM instance.

This is a macro that calls _osmo_fsm_inst_term_children() with the given parameters as well as the caller's source file and line number for logging purposes. See there for documentation.

OSMO_T_FMT

#define OSMO_T_FMT   "%c%u"

OSMO_T_FMT_ARGS

#define OSMO_T_FMT_ARGS

(

T

)

((T) >= 0 ? 'T' : 'X'), ((T) >= 0 ? (T) : -(T))

Enumeration Type Documentation

osmo_fsm_term_cause

enum osmo_fsm_term_cause

Enumerator
OSMO_FSM_TERM_PARENT	terminate because parent terminated
OSMO_FSM_TERM_REQUEST	terminate on explicit user request
OSMO_FSM_TERM_REGULAR	regular termination of process
OSMO_FSM_TERM_ERROR	erroneous termination of process
OSMO_FSM_TERM_TIMEOUT	termination due to time-out

Function Documentation

_osmo_fsm_inst_broadcast_children()

void _osmo_fsm_inst_broadcast_children	(	struct osmo_fsm_inst *	fi,
		uint32_t	event,
		void *	data,
		const char *	file,
		int	line
	)

Broadcast an event to all the FSMs children.

Iterate over all children and send them the specified event.

Parameters

[in]	fi	FSM instance of the parent
[in]	event	Event to send to children of FSM instance
[in]	data	Data to pass along with the event
[in]	file	Calling source file (from osmo_fsm_inst_dispatch macro)
[in]	line	Calling source line (from osmo_fsm_inst_dispatch macro)

References _osmo_fsm_inst_dispatch(), osmo_fsm_inst::child, osmo_fsm_inst::children, data, file(), llist_for_each_entry_safe, and osmo_fsm_inst::proc.

_osmo_fsm_inst_dispatch()

int _osmo_fsm_inst_dispatch	(	struct osmo_fsm_inst *	fi,
		uint32_t	event,
		void *	data,
		const char *	file,
		int	line
	)

dispatch an event to an osmocom finite state machine instance

Best invoke via the osmo_fsm_inst_dispatch() macro which logs the source file where the event was effected. Alternatively, you may pass file as NULL to use the normal file/line indication instead.

Any incoming events to osmo_fsm instances must be dispatched to them via this function. It verifies, whether the event is permitted based on the current state of the FSM. If not, -1 is returned.

Parameters

[in]	fi	FSM instance
[in]	event	Event to send to FSM instance
[in]	data	Data to pass along with the event
[in]	file	Calling source file (from osmo_fsm_inst_dispatch macro)
[in]	line	Calling source line (from osmo_fsm_inst_dispatch macro)

Returns

0 in case of success; negative on error

References osmo_fsm_state::action, osmo_fsm::allstate_action, osmo_fsm::allstate_event_mask, data, DLGLOBAL, file(), osmo_fsm_inst::fsm, osmo_fsm_state::in_event_mask, LOGL_ERROR, LOGPFSMLSRC, LOGPFSMSRC, LOGPSRC, osmo_fsm::num_states, OSMO_ASSERT, osmo_fsm_event_name(), osmo_log_backtrace(), osmo_fsm_inst::proc, osmo_fsm_inst::state, osmo_fsm::states, and osmo_fsm_inst::terminating.

Referenced by _osmo_fsm_inst_broadcast_children(), and _osmo_fsm_inst_term().

_osmo_fsm_inst_state_chg()

int _osmo_fsm_inst_state_chg	(	struct osmo_fsm_inst *	fi,
		uint32_t	new_state,
		unsigned long	timeout_secs,
		int	T,
		const char *	file,
		int	line
	)

perform a state change of the given FSM instance

Best invoke via the osmo_fsm_inst_state_chg() macro which logs the source file where the state change was effected. Alternatively, you may pass file as NULL to use the normal file/line indication instead.

All changes to the FSM instance state must be made via an osmo_fsm_inst_state_chg_* function. It verifies that the existing state actually permits a transition to new_state.

If timeout_secs is 0, stay in the new state indefinitely, without a timeout (stop the FSM instance's timer if it was runnning).

If timeout_secs > 0, start or reset the FSM instance's timer with this timeout. On expiry, invoke the FSM instance's timer_cb – if no timer_cb is set, an expired timer immediately terminates the FSM instance with OSMO_FSM_TERM_TIMEOUT.

The value of T is stored in fi->T and is then available for query in timer_cb. If passing timeout_secs == 0, it is recommended to also pass T == 0, so that fi->T is reset to 0 when no timeout is invoked.

Positive values for T are considered to be 3GPP spec compliant and appear in logging and VTY as "T1234", while negative values are considered to be Osmocom specific timers, represented in logging and VTY as "X1234".

See also osmo_tdef_fsm_inst_state_chg() from the osmo_tdef API, which provides a unified way to configure and apply GSM style Tnnnn timers to FSM state transitions.

Parameters

[in]	fi	FSM instance whose state is to change
[in]	new_state	The new state into which we should change
[in]	timeout_secs	Timeout in seconds (if !=0), maximum-clamped to 2147483647 seconds.
[in]	T	Timer number, where positive numbers are considered to be 3GPP spec compliant timer numbers and are logged as "T1234", while negative numbers are considered Osmocom specific timer numbers logged as "X1234".
[in]	file	Calling source file (from osmo_fsm_inst_state_chg macro)
[in]	line	Calling source line (from osmo_fsm_inst_state_chg macro)

Returns

0 on success; negative on error

References file(), and state_chg().

Referenced by _osmo_tdef_fsm_inst_state_chg().

_osmo_fsm_inst_state_chg_keep_or_start_timer()

int _osmo_fsm_inst_state_chg_keep_or_start_timer	(	struct osmo_fsm_inst *	fi,
		uint32_t	new_state,
		unsigned long	timeout_secs,
		int	T,
		const char *	file,
		int	line
	)

perform a state change while keeping the current timer if running, or starting a timer otherwise.

This is useful to keep a timeout across several states, but to make sure that some timeout is actually running.

Best invoke via the osmo_fsm_inst_state_chg_keep_or_start_timer() macro which logs the source file where the state change was effected. Alternatively, you may pass file as NULL to use the normal file/line indication instead.

All changes to the FSM instance state must be made via an osmo_fsm_inst_state_chg_* function. It verifies that the existing state actually permits a transition to new_state.

Parameters

[in]	fi	FSM instance whose state is to change
[in]	new_state	The new state into which we should change
[in]	timeout_secs	If no timer is running yet, set this timeout in seconds (if !=0), maximum-clamped to 2147483647 seconds.
[in]	T	Timer number, where positive numbers are considered to be 3GPP spec compliant timer numbers and are logged as "T1234", while negative numbers are considered Osmocom specific timer numbers logged as "X1234".
[in]	file	Calling source file (from osmo_fsm_inst_state_chg macro)
[in]	line	Calling source line (from osmo_fsm_inst_state_chg macro)

Returns

0 on success; negative on error

References file(), and state_chg().

_osmo_fsm_inst_state_chg_keep_or_start_timer_ms()

int _osmo_fsm_inst_state_chg_keep_or_start_timer_ms	(	struct osmo_fsm_inst *	fi,
		uint32_t	new_state,
		unsigned long	timeout_ms,
		int	T,
		const char *	file,
		int	line
	)

References file(), and state_chg().

Referenced by _osmo_tdef_fsm_inst_state_chg().

_osmo_fsm_inst_state_chg_keep_timer()

int _osmo_fsm_inst_state_chg_keep_timer	(	struct osmo_fsm_inst *	fi,
		uint32_t	new_state,
		const char *	file,
		int	line
	)

perform a state change while keeping the current timer running.

This is useful to keep a timeout across several states (without having to round the remaining time to seconds).

Best invoke via the osmo_fsm_inst_state_chg_keep_timer() macro which logs the source file where the state change was effected. Alternatively, you may pass file as NULL to use the normal file/line indication instead.

All changes to the FSM instance state must be made via an osmo_fsm_inst_state_chg_* function. It verifies that the existing state actually permits a transition to new_state.

Parameters

[in]	fi	FSM instance whose state is to change
[in]	new_state	The new state into which we should change
[in]	file	Calling source file (from osmo_fsm_inst_state_chg macro)
[in]	line	Calling source line (from osmo_fsm_inst_state_chg macro)

Returns

0 on success; negative on error

References file(), and state_chg().

Referenced by _osmo_tdef_fsm_inst_state_chg().

_osmo_fsm_inst_state_chg_ms()

int _osmo_fsm_inst_state_chg_ms	(	struct osmo_fsm_inst *	fi,
		uint32_t	new_state,
		unsigned long	timeout_ms,
		int	T,
		const char *	file,
		int	line
	)

References file(), and state_chg().

Referenced by _osmo_tdef_fsm_inst_state_chg().

_osmo_fsm_inst_term()

void _osmo_fsm_inst_term	(	struct osmo_fsm_inst *	fi,
		enum osmo_fsm_term_cause	cause,
		void *	data,
		const char *	file,
		int	line
	)

Terminate FSM instance with given cause.

This safely terminates the given FSM instance by first iterating over all children and sending them a termination event. Next, it calls the FSM descriptors cleanup function (if any), followed by releasing any memory associated with the FSM instance.

Finally, the parent FSM instance (if any) is notified using the parent termination event configured at time of FSM instance start.

Parameters

[in]	fi	FSM instance to be terminated
[in]	cause	Cause / reason for termination
[in]	data	Opaque event data to be passed with the parent term event
[in]	file	Calling source file (from osmo_fsm_inst_term macro)
[in]	line	Calling source line (from osmo_fsm_inst_term macro)

References _osmo_fsm_inst_dispatch(), _osmo_fsm_inst_term_children(), cause, osmo_fsm_inst::child, osmo_fsm::cleanup, data, file(), osmo_fsm_inst::fsm, fsm_term_safely, fsm_term_safely_enabled, llist_del(), LOGPFSMSRC, osmo_fsm_inst_free(), osmo_fsm_inst_name(), osmo_fsm_term_cause_name(), OSMO_FSM_TERM_PARENT, osmo_fsm_inst::parent, osmo_fsm_inst::parent_term_event, osmo_fsm::pre_term, osmo_fsm_inst::proc, and osmo_fsm_inst::terminating.

Referenced by _osmo_fsm_inst_term_children().

_osmo_fsm_inst_term_children()

void _osmo_fsm_inst_term_children	(	struct osmo_fsm_inst *	fi,
		enum osmo_fsm_term_cause	cause,
		void *	data,
		const char *	file,
		int	line
	)

Terminate all child FSM instances of an FSM instance.

Iterate over all children and send them a termination event, with the given cause. Pass OSMO_FSM_TERM_PARENT to avoid dispatching events from the terminated child FSMs.

Parameters

[in]	fi	FSM instance that should be cleared of child FSMs
[in]	cause	Cause / reason for termination (OSMO_FSM_TERM_PARENT)
[in]	data	Opaque event data to be passed with the parent term events
[in]	file	Calling source file (from osmo_fsm_inst_term_children macro)
[in]	line	Calling source line (from osmo_fsm_inst_term_children macro)

References _osmo_fsm_inst_term(), cause, osmo_fsm_inst::children, data, file(), llist_empty(), llist_entry, LOGL_ERROR, LOGPFSMLSRC, llist_head::next, and osmo_fsm_inst::proc.

Referenced by _osmo_fsm_inst_term().

fsm_free_or_steal()

static void fsm_free_or_steal ( void *  talloc_object )

static

Internal call to free an FSM instance, which redirects to the context set by osmo_fsm_set_dealloc_ctx() if any.

References fsm_term_safely.

Referenced by osmo_fsm_defer_free(), osmo_fsm_inst_alloc(), and osmo_fsm_inst_free().

fsm_tmr_cb()

static void fsm_tmr_cb ( void *  data )

static

References data, osmo_fsm_inst::fsm, LOGPFSM, osmo_fsm_inst_term, OSMO_FSM_TERM_TIMEOUT, OSMO_T_FMT, OSMO_T_FMT_ARGS, osmo_fsm_inst::T, and osmo_fsm::timer_cb.

Referenced by osmo_fsm_inst_alloc().

LLIST_HEAD()

LLIST_HEAD

(

osmo_g_fsms

)

osmo_fsm_defer_free()

static void osmo_fsm_defer_free ( void *  talloc_object )

static

talloc_free() the given object immediately, or once ongoing FSM terminations are done.

If an FSM deallocation cascade is ongoing, talloc_steal() the given talloc_object into the talloc context that is freed once the cascade is done. If no FSM deallocation cascade is ongoing, or if osmo_fsm_term_safely() is disabled, immediately talloc_free the object.

This can be useful if some higher order talloc object, which is the talloc parent for FSM instances or their priv objects, is not itself tied to an FSM instance. This function allows safely freeing it without affecting ongoing FSM termination cascades.

Once passed to this function, the talloc_object should be considered as already freed. Only FSM instance pre_term() and cleanup() functions as well as event handling caused by these may safely assume that it is still valid memory.

The talloc_object should not have multiple parents.

(This function may some day move to public API, which might be redundant if we introduce a select-loop volatile context mechanism to defer deallocation instead.)

Parameters

[in]

talloc_object

Object pointer to free.

References fsm_free_or_steal(), fsm_term_safely, and OSMO_ASSERT.

Referenced by osmo_fsm_inst_free().

osmo_fsm_event_name()

const char * osmo_fsm_event_name	(	const struct osmo_fsm *	fsm,
		uint32_t	event
	)

get human-readable name of FSM event

Parameters

[in]	fsm	FSM descriptor of event
[in]	event	Event integer value

Returns

string rendering of the event

References osmo_fsm::event_names, osmo_fsm_inst::fsm, and get_value_string().

Referenced by _osmo_fsm_inst_dispatch().

osmo_fsm_find_by_name()

struct osmo_fsm * osmo_fsm_find_by_name

(

const char *

name

)

References list, llist_for_each_entry, name, osmo_fsm::name, and osmo_g_fsms.

Referenced by osmo_fsm_register().

osmo_fsm_inst_alloc()

struct osmo_fsm_inst * osmo_fsm_inst_alloc	(	struct osmo_fsm *	fsm,
		void *	ctx,
		void *	priv,
		int	log_level,
		const char *	id
	)

allocate a new instance of a specified FSM

Parameters

[in]	fsm	Descriptor of the FSM
[in]	ctx	talloc context from which to allocate memory
[in]	priv	private data reference store in fsm instance
[in]	log_level	The log level for events of this FSM
[in]	id	The name/ID of the FSM instance

Returns

newly-allocated, initialized and registered FSM instance

References osmo_fsm_inst::child, osmo_fsm_inst::children, osmo_fsm_inst::fsm, fsm_free_or_steal(), fsm_tmr_cb(), INIT_LLIST_HEAD, osmo_fsm::instances, osmo_fsm_inst::list, llist_add(), osmo_fsm_inst::log_level, LOGPFSM, osmo_fsm_inst_update_id(), osmo_timer_setup(), osmo_fsm_inst::priv, osmo_fsm_inst::proc, and osmo_fsm_inst::timer.

Referenced by osmo_fsm_inst_alloc_child().

osmo_fsm_inst_alloc_child()

struct osmo_fsm_inst * osmo_fsm_inst_alloc_child	(	struct osmo_fsm *	fsm,
		struct osmo_fsm_inst *	parent,
		uint32_t	parent_term_event
	)

allocate a new instance of a specified FSM as child of other FSM instance

This is like osmo_fsm_inst_alloc but using the parent FSM as talloc context, and inheriting the log level of the parent.

Parameters

[in]	fsm	Descriptor of the to-be-allocated FSM
[in]	parent	Parent FSM instance
[in]	parent_term_event	Event to be sent to parent when terminating

Returns

newly-allocated, initialized and registered FSM instance

References osmo_fsm_inst::fsm, osmo_fsm_inst::id, osmo_fsm_inst::log_level, LOGPFSM, osmo_fsm_inst_alloc(), osmo_fsm_inst_change_parent(), osmo_fsm_inst_dispatch, osmo_fsm_inst_name(), osmo_fsm_inst::parent, and osmo_fsm_inst::parent_term_event.

osmo_fsm_inst_change_parent()

void osmo_fsm_inst_change_parent	(	struct osmo_fsm_inst *	fi,
		struct osmo_fsm_inst *	new_parent,
		uint32_t	new_parent_term_event
	)

change parent instance of an FSM.

Parameters

[in]	fi	Descriptor of the to-be-allocated FSM.
[in]	new_parent	New parent FSM instance.
[in]	new_parent_term_event	Event to be sent to parent when terminating.

Never call this function from the cleanup callback! (see also osmo_fsm_inst_unlink_parent()).

References osmo_fsm_inst::child, osmo_fsm_inst::children, llist_add(), osmo_fsm_inst_unlink_parent(), osmo_fsm_inst::parent, osmo_fsm_inst::parent_term_event, and osmo_fsm_inst::proc.

Referenced by osmo_fsm_inst_alloc_child().

osmo_fsm_inst_find_by_id()

struct osmo_fsm_inst * osmo_fsm_inst_find_by_id	(	const struct osmo_fsm *	fsm,
		const char *	id
	)

References osmo_fsm_inst::fsm, osmo_fsm_inst::id, osmo_fsm::instances, list, and llist_for_each_entry.

osmo_fsm_inst_find_by_name()

struct osmo_fsm_inst * osmo_fsm_inst_find_by_name	(	const struct osmo_fsm *	fsm,
		const char *	name
	)

References osmo_fsm_inst::fsm, osmo_fsm::instances, list, llist_for_each_entry, name, and osmo_fsm_inst::name.

osmo_fsm_inst_free()

void osmo_fsm_inst_free

(

struct osmo_fsm_inst *

fi

)

delete a given instance of a FSM

Parameters

[in]

fi

FSM instance to be un-registered and deleted

References fsm_free_or_steal(), fsm_term_safely, osmo_fsm_inst::list, llist_del(), LOGPFSM, osmo_fsm_defer_free(), osmo_timer_del(), and osmo_fsm_inst::timer.

Referenced by _osmo_fsm_inst_term().

osmo_fsm_inst_name()

const char * osmo_fsm_inst_name

(

const struct osmo_fsm_inst *

fi

)

get human-readable name of FSM instance

Parameters

[in]

fi

FSM instance

Returns

string rendering of the FSM identity

References osmo_fsm_inst::fsm, osmo_fsm::name, and osmo_fsm_inst::name.

Referenced by _osmo_fsm_inst_term(), and osmo_fsm_inst_alloc_child().

osmo_fsm_inst_state_name()

static const char * osmo_fsm_inst_state_name ( struct osmo_fsm_inst *  fi )

inlinestatic

return the name of the state the FSM instance is currently in.

References osmo_fsm_inst::fsm, osmo_fsm_state_name(), and osmo_fsm_inst::state.

osmo_fsm_inst_unlink_parent()

void osmo_fsm_inst_unlink_parent	(	struct osmo_fsm_inst *	fi,
		void *	ctx
	)

unlink child FSM from its parent FSM.

Parameters

[in]	fi	Descriptor of the child FSM to unlink.
[in]	ctx	New talloc context

Never call this function from the cleanup callback, because at that time the child FSMs will already be terminated. If unlinking should be performed on FSM termination, use the grace callback instead.

References osmo_fsm_inst::child, llist_del(), osmo_fsm_inst::parent, osmo_fsm_inst::parent_term_event, and osmo_fsm_inst::proc.

Referenced by osmo_fsm_inst_change_parent().

osmo_fsm_inst_update_id()

int osmo_fsm_inst_update_id	(	struct osmo_fsm_inst *	fi,
		const char *	id
	)

Change id of the FSM instance.

Parameters

[in]	fi	FSM instance
[in]	id	new ID

Returns

0 if the ID was updated, otherwise -EINVAL

References osmo_fsm_inst_update_id_f().

Referenced by osmo_fsm_inst_alloc(), and osmo_fsm_inst_update_id_f_sanitize().

osmo_fsm_inst_update_id_f()

int osmo_fsm_inst_update_id_f	(	struct osmo_fsm_inst *	fi,
		const char *	fmt,
			...
	)

Change id of the FSM instance using a string format.

Parameters

[in]	fi	FSM instance.
[in]	fmt	format string to compose new ID.
[in]	...	variable argument list for format string.

Returns

0 if the ID was updated, otherwise -EINVAL.

References DLGLOBAL, osmo_fsm_inst::fsm, osmo_fsm_inst::id, LOGL_ERROR, LOGP, osmo_fsm::name, osmo_identifier_valid(), osmo_quote_str(), and update_name().

Referenced by osmo_fsm_inst_update_id().

osmo_fsm_inst_update_id_f_sanitize()

int osmo_fsm_inst_update_id_f_sanitize	(	struct osmo_fsm_inst *	fi,
		char	replace_with,
		const char *	fmt,
			...
	)

Change id of the FSM instance using a string format, and ensuring a valid id.

Replace any characters that are not permitted as FSM identifier with replace_with.

Parameters

[in]	fi	FSM instance.
[in]	replace_with	Character to use instead of non-permitted FSM id characters. Make sure to choose a legal character, e.g. '-'.
[in]	fmt	format string to compose new ID.
[in]	...	variable argument list for format string.

Returns

0 if the ID was updated, otherwise -EINVAL.

References osmo_fsm_inst_update_id(), and osmo_identifier_sanitize_buf().

osmo_fsm_log_addr()

void osmo_fsm_log_addr

(

bool

log_addr

)

specify if FSM instance addresses should be logged or not

By default, the FSM name includes the pointer address of the osmo_fsm_inst. This behavior can be disabled (and re-enabled) using this function.

Parameters

[in]

log_addr

Indicate if FSM instance address shall be logged

References fsm_log_addr.

osmo_fsm_log_timeouts()

void osmo_fsm_log_timeouts

(

bool

log_timeouts

)

Enable or disable logging of timeout values for FSM instance state changes.

By default, state changes are logged by state name only, omitting the timeout. When passing true, each state change will also log the T number (or Osmocom-specific X number) and the chosen timeout in seconds. osmo_fsm_inst_state_chg_keep_timer() will log remaining timeout in millisecond precision.

The default for this is false to reflect legacy behavior. Since various C tests that verify logging output already existed prior to this option, keeping timeout logging off makes sure that they continue to pass. Particularly, osmo_fsm_inst_state_chg_keep_timer() may cause non-deterministic logging of remaining timeout values.

For any program that does not explicitly require deterministic logging output, i.e. anything besides regression tests involving FSM instances, it is recommended to call osmo_fsm_log_timeouts(true).

Parameters

[in]

log_timeouts

Pass true to log timeouts on state transitions, false to omit timeouts.

References fsm_log_timeouts.

osmo_fsm_register()

int osmo_fsm_register

(

struct osmo_fsm *

fsm

)

register a FSM with the core

A FSM descriptor needs to be registered with the core before any instances can be created for it.

Parameters

[in]

fsm

Descriptor of Finite State Machine to be registered

Returns

0 on success; negative on error

References DLGLOBAL, osmo_fsm::event_names, osmo_fsm_inst::fsm, INIT_LLIST_HEAD, osmo_fsm::instances, osmo_fsm::list, llist_add_tail(), LOGL_ERROR, LOGP, osmo_fsm::name, osmo_fsm_find_by_name(), osmo_g_fsms, and osmo_identifier_valid().

osmo_fsm_set_dealloc_ctx()

void osmo_fsm_set_dealloc_ctx

(

void *

ctx

)

Instead of deallocating FSM instances, move them to the given talloc context.

It is the caller's responsibility to clear this context to actually free the memory of terminated FSM instances. Make sure to not talloc_free(ctx) itself before setting a different osmo_fsm_set_dealloc_ctx(). To clear a ctx without the need to call osmo_fsm_set_dealloc_ctx() again, rather use talloc_free_children(ctx).

For example, to defer deallocation to the next osmo_select_main_ctx() iteration, set this to OTC_SELECT.

Deferring deallocation is the simplest solution to avoid most use-after-free problems from FSM instance deallocation. This is a simpler and more general solution than osmo_fsm_term_safely().

To disable the feature again, pass NULL as ctx.

Both osmo_fsm_term_safely() and osmo_fsm_set_dealloc_ctx() can be enabled at the same time, which will result in first collecting deallocated FSM instances in fsm_term_safely.collect_ctx, and finally reparenting that to the ctx passed here. However, in practice, it does not really make sense to enable both at the same time.

Parameters

ctx[in]

Instead of talloc_free()int, talloc_steal() all future deallocated osmo_fsm_inst instances to this ctx. If NULL, go back to talloc_free() as usual.

References fsm_term_safely.

osmo_fsm_state_name()

const char * osmo_fsm_state_name	(	const struct osmo_fsm *	fsm,
		uint32_t	state
	)

get human-readable name of FSM state

Parameters

[in]	fsm	FSM descriptor
[in]	state	FSM state number

Returns

string rendering of the FSM state

References osmo_fsm_inst::fsm, osmo_fsm_state::name, osmo_fsm::num_states, osmo_fsm_inst::state, and osmo_fsm::states.

Referenced by osmo_fsm_inst_state_name(), and state_chg().

osmo_fsm_term_cause_name()

static const char * osmo_fsm_term_cause_name ( enum osmo_fsm_term_cause  cause )

inlinestatic

References cause, get_value_string(), and osmo_fsm_term_cause_names.

Referenced by _osmo_fsm_inst_term().

osmo_fsm_term_safely()

void osmo_fsm_term_safely

(

bool

term_safely

)

Enable safer way to deallocate cascades of terminating FSM instances.

Note, using osmo_fsm_set_dealloc_ctx() is a more general solution to this same problem. Particularly, in a program using osmo_select_main_ctx(), the simplest solution to avoid most use-after-free problems from FSM instance deallocation is using osmo_fsm_set_dealloc_ctx(OTC_SELECT).

When enabled, an FSM instance termination detects whether another FSM instance is already terminating, and instead of deallocating immediately, collects all terminating FSM instances in a talloc context, to be bulk deallocated once all event handling and termination cascades are done.

For example, if an FSM's cleanup() sends an event to some "other" FSM, which in turn causes the FSM's parent to deallocate, then the parent would talloc_free() the child's memory, causing a use-after-free. There are infinite constellations like this, which all are trivially solved with this feature enabled.

For illustration, see fsm_dealloc_test.c.

When enabled, this feature changes the order of logging, which may break legacy unit test expectations, and changes the order of deallocation to after the parent term event is dispatched.

Parameters

[in]

term_safely

Pass true to switch to safer FSM instance termination behavior.

References fsm_term_safely_enabled.

osmo_fsm_unregister()

void osmo_fsm_unregister

(

struct osmo_fsm *

fsm

)

unregister a FSM from the core

Once the FSM descriptor is unregistered, active instances can still use it, but no new instances may be created for it.

Parameters

[in]

fsm

Descriptor of Finite State Machine to be removed

References osmo_fsm_inst::fsm, osmo_fsm::list, and llist_del().

state_chg()

static int state_chg ( struct osmo_fsm_inst *  fi, uint32_t  new_state, bool  keep_timer, unsigned long  timeout_ms, int  T, const char *  file, int  line  )

static

References osmo_timer_list::active, file(), osmo_fsm_inst::fsm, fsm_log_timeouts, LOGL_ERROR, LOGPFSMLSRC, LOGPFSMSRC, osmo_fsm_state::onenter, osmo_fsm_state::onleave, osmo_fsm_state_name(), OSMO_T_FMT, OSMO_T_FMT_ARGS, osmo_timer_del(), osmo_timer_pending(), osmo_timer_remaining(), osmo_timer_schedule(), osmo_fsm_state::out_state_mask, osmo_fsm_inst::proc, osmo_fsm_inst::state, osmo_fsm::states, osmo_fsm_inst::T, osmo_fsm_inst::terminating, and osmo_fsm_inst::timer.

Referenced by _osmo_fsm_inst_state_chg(), _osmo_fsm_inst_state_chg_keep_or_start_timer(), _osmo_fsm_inst_state_chg_keep_or_start_timer_ms(), _osmo_fsm_inst_state_chg_keep_timer(), and _osmo_fsm_inst_state_chg_ms().

update_name()

static void update_name ( struct osmo_fsm_inst *  fi )

static

References osmo_fsm_inst::fsm, fsm_log_addr, osmo_fsm_inst::id, osmo_fsm::name, and osmo_fsm_inst::name.

Referenced by osmo_fsm_inst_update_id_f().

Variable Documentation

void* { ... } ::collect_ctx

Talloc context to collect all deferred deallocations (FSM instances, and talloc objects if any).

unsigned int { ... } ::depth

2 if a secondary FSM terminates, 3 if a secondary FSM causes a tertiary FSM to terminate, and so on.

void* { ... } ::fsm_dealloc_ctx

See osmo_fsm_set_dealloc_ctx()

fsm_log_addr

bool fsm_log_addr = true

static

Referenced by osmo_fsm_log_addr(), and update_name().

fsm_log_timeouts

bool fsm_log_timeouts = false

static

Referenced by osmo_fsm_log_timeouts(), and state_chg().

__thread struct { ... } fsm_term_safely

Internal state for FSM instance termination cascades.

Referenced by _osmo_fsm_inst_term(), fsm_free_or_steal(), osmo_fsm_defer_free(), osmo_fsm_inst_free(), and osmo_fsm_set_dealloc_ctx().

fsm_term_safely_enabled

bool fsm_term_safely_enabled = false

static

See osmo_fsm_term_safely().

Referenced by _osmo_fsm_inst_term(), and osmo_fsm_term_safely().

osmo_fsm_term_cause_names [1/2]

const struct value_string osmo_fsm_term_cause_names[]

extern

Referenced by osmo_fsm_term_cause_name().

osmo_fsm_term_cause_names [2/2]

const struct value_string osmo_fsm_term_cause_names[]

Initial value:

= {
        OSMO_VALUE_STRING(OSMO_FSM_TERM_PARENT),
        OSMO_VALUE_STRING(OSMO_FSM_TERM_REQUEST),
        OSMO_VALUE_STRING(OSMO_FSM_TERM_REGULAR),
        OSMO_VALUE_STRING(OSMO_FSM_TERM_ERROR),
        OSMO_VALUE_STRING(OSMO_FSM_TERM_TIMEOUT),
        { 0, NULL }
}

Referenced by osmo_fsm_term_cause_name().

struct osmo_fsm_inst* { ... } ::root_fi

The first FSM instance that invoked osmo_fsm_inst_term() in the current cascade.