Finite State Machine abstraction

## Files

file | fsm.h
file | fsm.c

## 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_state_chg_keep_timer(fi, new_state)
| perform a state change while keeping the current timer running. 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_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...
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...
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_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_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)
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_secs, int T, const char *file, int line)

## 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

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) coe, where there is one message for eahc 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 thta 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 priv pointer.

## Macro Definition Documentation

## LOGPFSM

#define LOGPFSM | ( |  | fi,
|  |  | fmt,
|  |  | args...
| ) |  | LOGPFSML(fi, (fi)->log_level, fmt, ## args)

## LOGPFSML

#define LOGPFSML | ( |  | fi,
|  |  | level,
|  |  | fmt,
|  |  | args...
| ) |  |

Value:
LOGP((fi)->fsm->log_subsys, OSMO_MAX(level, (fi)->log_level), \
"%s{%s}: " fmt, \
osmo_fsm_inst_name(fi), \
osmo_fsm_state_name((fi)->fsm, (fi)->state), ## args)

## LOGPFSMLSRC

#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_inst_name(fi), \
osmo_fsm_state_name((fi)->fsm, (fi)->state), \
## args)

## LOGPFSMSRC

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

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

## osmo_fsm_inst_dispatch

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

## 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, \
__BASE_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_timer

#define osmo_fsm_inst_state_chg_keep_timer | ( |  | fi,
|  |  | new_state
| ) |  |

Value:
_osmo_fsm_inst_state_chg_keep_timer(fi, new_state, \
__BASE_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_term

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

## osmo_fsm_inst_term_children

#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

## 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_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, DLGLOBAL, 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::state, and osmo_fsm::states.

Referenced by _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.

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] | 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)
  [in] | T | Timer number (if timeout_secs != 0)
  [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 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 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(), osmo_fsm_inst::child, osmo_fsm::cleanup, osmo_fsm_inst::fsm, 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, and osmo_fsm_inst::proc.

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(), osmo_fsm_inst::children, llist_empty(), llist_entry, LOGL_ERROR, LOGPFSMLSRC, llist_head::next, and osmo_fsm_inst::proc.

Referenced by _osmo_fsm_inst_term().

## fsm_tmr_cb()

static void fsm_tmr_cb | ( | void * | data | ) |

static

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

Referenced by osmo_fsm_inst_alloc().

## LLIST_HEAD()

LLIST_HEAD | ( | osmo_g_fsms |  | ) |

## osmo_fsm_event_name()

const char * osmo_fsm_event_name | ( | 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 osmo_fsm::list, llist_for_each_entry, name, and osmo_fsm::name.

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_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, osmo_fsm_inst::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, osmo_fsm_inst::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] | fsm | The FSM to be un-registered and deleted

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

Referenced by _osmo_fsm_inst_term().

## osmo_fsm_inst_name()

const char * osmo_fsm_inst_name | ( | 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 | ) |

inline static

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

## 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_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_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(), and osmo_identifier_valid().

## osmo_fsm_state_name()

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

get human-readable name of FSM instance

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

inline static

References get_value_string(), and osmo_fsm_term_cause_names.

Referenced by _osmo_fsm_inst_term().

## 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_secs,
|  | int | T,
|  | const char * | file,
|  | int | line
| ) |  |

static

References osmo_fsm_inst::fsm, LOGL_ERROR, LOGPFSMLSRC, LOGPFSMSRC, 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.

Referenced by _osmo_fsm_inst_state_chg(), and _osmo_fsm_inst_state_chg_keep_timer().

## 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

## fsm_log_addr

bool fsm_log_addr = true

static

Referenced by osmo_fsm_log_addr(), and update_name().

## osmo_fsm_term_cause_names [1/2]

const struct value_string osmo_fsm_term_cause_names[]

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

OSMO_FSM_TERM_ERROR
@ OSMO_FSM_TERM_ERROR
erroneous termination of process
Definition: fsm.h:28
OSMO_FSM_TERM_REGULAR
@ OSMO_FSM_TERM_REGULAR
regular termination of process
Definition: fsm.h:26
_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
Definition: fsm.c:497
level
uint8_t level
logging level
Definition: gsmtap.h:8
_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.
Definition: fsm.c:523
OSMO_FSM_TERM_PARENT
@ OSMO_FSM_TERM_PARENT
terminate because parent terminated
Definition: fsm.h:22
LOGPFSMLSRC
#define LOGPFSMLSRC(fi, level, caller_file, caller_line, fmt, args...)
Definition: fsm.h:131
OSMO_FSM_TERM_REQUEST
@ OSMO_FSM_TERM_REQUEST
terminate on explicit user request
Definition: fsm.h:24
OSMO_VALUE_STRING
#define OSMO_VALUE_STRING(x)
Make a value_string entry from an enum value name.
Definition: utils.h:26
OSMO_FSM_TERM_TIMEOUT
@ OSMO_FSM_TERM_TIMEOUT
termination due to time-out
Definition: fsm.h:30
osmo_fsm_inst_name
const char * osmo_fsm_inst_name(struct osmo_fsm_inst *fi)
get human-readable name of FSM instance
Definition: fsm.c:406
LOGPSRC
#define LOGPSRC(ss, level, caller_file, caller_line, fmt, args...)
Log through the Osmocom logging framework with explicit source.
Definition: logging.h:73
osmo_fsm_state_name
const char * osmo_fsm_state_name(struct osmo_fsm *fsm, uint32_t state)
get human-readable name of FSM instance
Definition: fsm.c:422
LOGP
#define LOGP(ss, level, fmt, args...)
Log a new message through the Osmocom logging framework.
Definition: logging.h:46
OSMO_MAX
#define OSMO_MAX(a, b)
Return the maximum of two specified values.
Definition: utils.h:16