libosmocore  0.9.6.113-fa5d
Osmocom core library
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Modules Pages
Finite State Machine abstraction

Files

file  fsm.h
 Finite State Machine.
 
file  fsm.c
 Finite State Machine abstraction.
 

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 LOGPFSML(fi, level, fmt, args...)
 
#define LOGPFSM(fi, fmt, args...)   LOGPFSML(fi, (fi)->log_level, fmt, ## args)
 
#define LOGPFSMLSRC(fi, level, caller_file, caller_line, fmt, args...)
 
#define LOGPFSMSRC(fi, caller_file, caller_line, fmt, args...)
 
#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_dispatch(fi, event, data)   _osmo_fsm_inst_dispatch(fi, event, data, __BASE_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, __BASE_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, __BASE_FILE__, __LINE__)
 Terminate all child FSM instances of an FSM 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...
 
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_fsmosmo_fsm_find_by_name (const char *name)
 
struct osmo_fsm_instosmo_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_instosmo_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_free (struct osmo_fsm_inst *fi)
 delete a given instance of a FSM More...
 
const char * osmo_fsm_event_name (struct osmo_fsm *fsm, uint32_t event)
 get human-readable name of FSM event More...
 
const char * osmo_fsm_inst_name (struct osmo_fsm_inst *fi)
 get human-readable name of FSM instance More...
 
const char * osmo_fsm_state_name (struct osmo_fsm *fsm, uint32_t state)
 get human-readable name of FSM instance 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_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...
 
 LLIST_HEAD (osmo_g_fsms)
 
static void fsm_tmr_cb (void *data)
 

Variables

const struct value_string osmo_fsm_term_cause_names []
 
static bool fsm_log_addr = true
 
const struct value_string osmo_fsm_term_cause_names []
 

Detailed Description

Macro Definition Documentation

#define LOGPFSML (   fi,
  level,
  fmt,
  args... 
)
Value:
LOGP((fi)->fsm->log_subsys, level, "%s{%s}: " fmt, \
osmo_fsm_state_name((fi)->fsm, (fi)->state), ## args)
const char * osmo_fsm_inst_name(struct osmo_fsm_inst *fi)
get human-readable name of FSM instance
Definition: fsm.c:273
#define LOGP(ss, level, fmt, args...)
Log a new message through the Osmocom logging framework.
Definition: logging.h:48
const char * osmo_fsm_state_name(struct osmo_fsm *fsm, uint32_t state)
get human-readable name of FSM instance
Definition: fsm.c:289
#define LOGPFSMLSRC (   fi,
  level,
  caller_file,
  caller_line,
  fmt,
  args... 
)
Value:
LOGPSRC((fi)->fsm->log_subsys, level, \
caller_file, caller_line, \
"%s{%s}: " fmt, \
osmo_fsm_state_name((fi)->fsm, (fi)->state), \
## args)
const char * osmo_fsm_inst_name(struct osmo_fsm_inst *fi)
get human-readable name of FSM instance
Definition: fsm.c:273
const char * osmo_fsm_state_name(struct osmo_fsm *fsm, uint32_t state)
get human-readable name of FSM instance
Definition: fsm.c:289
#define LOGPSRC(ss, level, caller_file, caller_line, fmt, args...)
Log through the Osmocom logging framework with explicit source. If caller_file is passed as NULL...
Definition: logging.h:75
#define LOGPFSMSRC (   fi,
  caller_file,
  caller_line,
  fmt,
  args... 
)
Value:
LOGPFSMLSRC(fi, (fi)->log_level, \
caller_file, caller_line, \
fmt, ## args)
#define osmo_fsm_inst_dispatch (   fi,
  event,
  data 
)    _osmo_fsm_inst_dispatch(fi, event, data, __BASE_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.

Referenced by osmo_fsm_inst_alloc_child().

#define osmo_fsm_inst_state_chg (   fi,
  new_state,
  timeout_secs,
 
)
Value:
_osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T, \
__BASE_FILE__, __LINE__)
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
Definition: fsm.c:323

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.

#define osmo_fsm_inst_term (   fi,
  cause,
  data 
)    _osmo_fsm_inst_term(fi, cause, data, __BASE_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.

#define osmo_fsm_inst_term_children (   fi,
  cause,
  data 
)    _osmo_fsm_inst_term_children(fi, cause, data, __BASE_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.

Enumeration Type Documentation

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

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]fiFSM instance
[in]eventEvent to send to FSM instance
[in]dataData to pass along with the event
[in]fileCalling source file (from osmo_fsm_inst_dispatch macro)
[in]lineCalling 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, DLGLOBAL, osmo_fsm_inst::fsm, osmo_fsm_state::in_event_mask, LOGL_ERROR, LOGPSRC, osmo_fsm::num_states, OSMO_ASSERT, osmo_fsm_event_name(), osmo_log_backtrace(), osmo_fsm_inst::state, and osmo_fsm::states.

Referenced by _osmo_fsm_inst_term().

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 this function. It verifies that the existing state actually permits a transiiton to new_state.

timeout_secs and T are optional parameters, and only have any effect if timeout_secs is not 0. If the timeout function is used, then the new_state is entered, and the FSM instances timer is set to expire in timeout_secs functions. At that time, the FSM's timer_cb function will be called for handling of the timeout by the user.

Parameters
[in]fiFSM instance whose state is to change
[in]new_stateThe new state into which we should change
[in]timeout_secsTimeout in seconds (if !=0)
[in]TTimer number (if timeout_secs != 0)
[in]fileCalling source file (from osmo_fsm_inst_state_chg macro)
[in]lineCalling source line (from osmo_fsm_inst_state_chg macro)
Returns
0 on success; negative on error

References osmo_fsm_inst::fsm, LOGL_ERROR, osmo_fsm_state::onenter, osmo_fsm_state::onleave, osmo_fsm_state_name(), osmo_timer_del(), osmo_timer_schedule(), osmo_fsm_state::out_state_mask, osmo_fsm_inst::state, osmo_fsm::states, osmo_fsm_inst::T, and osmo_fsm_inst::timer.

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]fiFSM instance to be terminated
[in]causeCause / reason for termination
[in]dataOpaque event data to be passed with the parent term event
[in]fileCalling source file (from osmo_fsm_inst_term macro)
[in]lineCalling source line (from osmo_fsm_inst_term macro)

References _osmo_fsm_inst_dispatch(), _osmo_fsm_inst_term_children(), osmo_fsm_inst::child, osmo_fsm::cleanup, osmo_fsm_inst::fsm, llist_del(), osmo_fsm_inst_free(), osmo_fsm_inst_name(), OSMO_FSM_TERM_PARENT, osmo_fsm_inst::parent, osmo_fsm_inst::parent_term_event, and osmo_fsm_inst::proc.

Referenced by _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]fiFSM instance that should be cleared of child FSMs
[in]causeCause / reason for termination (OSMO_FSM_TERM_PARENT)
[in]dataOpaque event data to be passed with the parent term events
[in]fileCalling source file (from osmo_fsm_inst_term_children macro)
[in]lineCalling source line (from osmo_fsm_inst_term_children macro)

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

Referenced by _osmo_fsm_inst_term().

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

get human-readable name of FSM event

Parameters
[in]fsmFSM descriptor of event
[in]eventEvent integer value
Returns
string rendering of the event

References osmo_fsm::event_names, and get_value_string().

Referenced by _osmo_fsm_inst_dispatch().

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]fsmDescriptor of the FSM
[in]ctxtalloc context from which to allocate memory
[in]privprivate data reference store in fsm instance
[in]log_levelThe log level for events of this FSM
Returns
newly-allocated, initialized and registered FSM instance

References osmo_timer_list::cb, osmo_fsm_inst::child, osmo_fsm_inst::children, osmo_timer_list::data, osmo_fsm_inst::fsm, osmo_fsm_inst::id, INIT_LLIST_HEAD, osmo_fsm::instances, osmo_fsm_inst::list, llist_add(), osmo_fsm_inst::log_level, osmo_fsm::name, osmo_fsm_inst::name, osmo_fsm_inst::priv, osmo_fsm_inst::proc, and osmo_fsm_inst::timer.

Referenced by 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]fsmDescriptor of the to-be-allocated FSM
[in]parentParent FSM instance
[in]parent_term_eventEvent to be sent to parent when terminating
Returns
newly-allocated, initialized and registered FSM instance

References osmo_fsm_inst::child, osmo_fsm_inst::children, osmo_fsm_inst::id, llist_add(), osmo_fsm_inst::log_level, osmo_fsm_inst_alloc(), osmo_fsm_inst_dispatch, osmo_fsm_inst_name(), osmo_fsm_inst::parent, osmo_fsm_inst::parent_term_event, and osmo_fsm_inst::proc.

void osmo_fsm_inst_free ( struct osmo_fsm_inst fi)

delete a given instance of a FSM

Parameters
[in]fsmThe FSM to be un-registered and deleted

References osmo_fsm_inst::list, llist_del(), osmo_timer_del(), and osmo_fsm_inst::timer.

Referenced by _osmo_fsm_inst_term().

const char * osmo_fsm_inst_name ( struct osmo_fsm_inst fi)

get human-readable name of FSM instance

Parameters
[in]fiFSM 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().

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_addrIndicate if FSM instance address shall be logged
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]fsmDescriptor of Finite State Machine to be registered
Returns
0 on success; negative on error

References INIT_LLIST_HEAD, osmo_fsm::instances, osmo_fsm::list, llist_add_tail(), and osmo_fsm::name.

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

get human-readable name of FSM instance

Parameters
[in]fsmFSM descriptor
[in]stateFSM state number
Returns
string rendering of the FSM state

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

Referenced by _osmo_fsm_inst_state_chg().

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]fsmDescriptor of Finite State Machine to be removed

References osmo_fsm::list, and llist_del().

Variable Documentation

const struct value_string osmo_fsm_term_cause_names[]
Initial value:
= {
{ 0, NULL }
}
erroneous termination of process
Definition: fsm.h:28
#define OSMO_VALUE_STRING(x)
Make a value_string entry from an enum value name.
Definition: utils.h:21
terminate because parent terminated
Definition: fsm.h:22
regular termination of process
Definition: fsm.h:26
termination due to time-out
Definition: fsm.h:30
terminate on explicit user request
Definition: fsm.h:24