libosmocore 0.9.6-23.20170220git32ee5af8.fc42
Osmocom core library
|
Finite State Machine abstraction. More...
#include <errno.h>
#include <stdbool.h>
#include <string.h>
#include <osmocom/core/fsm.h>
#include <osmocom/core/talloc.h>
#include <osmocom/core/logging.h>
#include <osmocom/core/utils.h>
Functions | |
LLIST_HEAD (osmo_g_fsms) | |
void | osmo_fsm_log_addr (bool log_addr) |
specify if FSM instance addresses should be logged or not | |
struct osmo_fsm * | osmo_fsm_find_by_name (const char *name) |
int | osmo_fsm_register (struct osmo_fsm *fsm) |
register a FSM with the core | |
void | osmo_fsm_unregister (struct osmo_fsm *fsm) |
unregister a FSM from the core | |
static void | fsm_tmr_cb (void *data) |
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 | |
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 | |
void | osmo_fsm_inst_free (struct osmo_fsm_inst *fi) |
delete a given instance of a FSM | |
const char * | osmo_fsm_event_name (struct osmo_fsm *fsm, uint32_t event) |
get human-readable name of FSM event | |
const char * | osmo_fsm_inst_name (struct osmo_fsm_inst *fi) |
get human-readable name of FSM instance | |
const char * | osmo_fsm_state_name (struct osmo_fsm *fsm, uint32_t state) |
get human-readable name of FSM instance | |
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 | |
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 | |
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. | |
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. | |
Variables | |
static bool | fsm_log_addr = true |
const struct value_string | osmo_fsm_term_cause_names [] |
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.