\doxysection{include/osmocom/core/fsm.h File Reference}
\label{fsm_8h}\index{include/osmocom/core/fsm.h@{include/osmocom/core/fsm.h}}


Finite State Machine.  


{\ttfamily \#include $<$stdint.\+h$>$}\newline
{\ttfamily \#include $<$stdbool.\+h$>$}\newline
{\ttfamily \#include $<$osmocom/core/linuxlist.\+h$>$}\newline
{\ttfamily \#include $<$osmocom/core/timer.\+h$>$}\newline
{\ttfamily \#include $<$osmocom/core/utils.\+h$>$}\newline
{\ttfamily \#include $<$osmocom/core/logging.\+h$>$}\newline
\doxysubsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+state}
\begin{DoxyCompactList}\small\item\em description of a rule in the FSM \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm}
\begin{DoxyCompactList}\small\item\em a description of an osmocom finite state machine \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst}
\begin{DoxyCompactList}\small\item\em a single instanceof an osmocom finite state machine \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Macros}
\begin{DoxyCompactItemize}
\item 
\#define \textbf{ LOGPFSMSL}(fi,  \textbf{ subsys},  \textbf{ level},  fmt,  args...)~  \textbf{ LOGPFSMSLSRC}(fi, \textbf{ subsys}, \textbf{ level}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+, fmt, \#\# args)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging subsystem and level. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSMSLSRC}(fi,  \textbf{ subsys},  \textbf{ level},  caller\+\_\+file,  caller\+\_\+line,  fmt,  args...)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging subsystem and level, and passing explicit source file and line information. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSML}(fi,  \textbf{ level},  fmt,  args...)~  \textbf{ LOGPFSMLSRC}(fi, \textbf{ level}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+, fmt, \#\# args)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging level. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSMLSRC}(fi,  \textbf{ level},  caller\+\_\+file,  caller\+\_\+line,  fmt,  args...)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, on explicit logging level, and with explicit source file and line info. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSM}(fi,  fmt,  args...)~  \textbf{ LOGPFSML}(fi, (fi) ? (fi)-\/$>$log\+\_\+level \+: \textbf{ LOGL\+\_\+\+ERROR}, fmt, \#\# args)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context. \end{DoxyCompactList}\item 
\#define \textbf{ LOGPFSMSRC}(fi,  caller\+\_\+file,  caller\+\_\+line,  fmt,  args...)
\begin{DoxyCompactList}\small\item\em Log using FSM instance\textquotesingle{}s context, with explicit source file and line info. \end{DoxyCompactList}\item 
\#define \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT}~\char`\"{}\%c\%\textbf{ u}\char`\"{}
\item 
\#define \textbf{ OSMO\+\_\+\+T\+\_\+\+FMT\+\_\+\+ARGS}(T)~((T) $>$= 0 ? \textquotesingle{}T\textquotesingle{} \+: \textquotesingle{}X\textquotesingle{}), ((T) $>$= 0 ? (T) \+: -\/(T))
\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg}(fi,  new\+\_\+state,  timeout\+\_\+secs,  T)
\begin{DoxyCompactList}\small\item\em perform a state change of the given FSM instance \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+ms}(fi,  new\+\_\+state,  timeout\+\_\+ms,  T)
\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer}(fi,  new\+\_\+state)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer running. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer}(fi,  new\+\_\+state,  timeout\+\_\+secs,  T)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer if running, or starting a timer otherwise. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer\+\_\+ms}(fi,  new\+\_\+state,  timeout\+\_\+ms,  T)
\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch}(fi,  \textbf{ event},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch}(fi, \textbf{ event}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em dispatch an event to an osmocom finite state machine instance \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+term}(fi,  \textbf{ cause},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em Terminate FSM instance with given cause. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children}(fi,  \textbf{ cause},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em Terminate all child FSM instances of an FSM instance. \end{DoxyCompactList}\item 
\#define \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children}(fi,  \textbf{ cause},  \textbf{ data})~ \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children}(fi, \textbf{ cause}, \textbf{ data}, \+\_\+\+\_\+\+FILE\+\_\+\+\_\+, \+\_\+\+\_\+\+LINE\+\_\+\+\_\+)
\begin{DoxyCompactList}\small\item\em dispatch an event to all children of an osmocom finite state machine instance \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Enumerations}
\begin{DoxyCompactItemize}
\item 
enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \{ \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+PARENT}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+REQUEST}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+REGULAR}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+ERROR}
, \newline
\textbf{ OSMO\+\_\+\+FSM\+\_\+\+TERM\+\_\+\+TIMEOUT}
 \}
\end{DoxyCompactItemize}
\doxysubsection*{Functions}
\begin{DoxyCompactItemize}
\item 
static const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+name} (enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \textbf{ cause})
\item 
void \textbf{ osmo\+\_\+fsm\+\_\+log\+\_\+addr} (bool log\+\_\+addr)
\begin{DoxyCompactList}\small\item\em specify if FSM instance addresses should be logged or not \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+log\+\_\+timeouts} (bool log\+\_\+timeouts)
\begin{DoxyCompactList}\small\item\em Enable or disable logging of timeout values for FSM instance state changes. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+safely} (bool term\+\_\+safely)
\begin{DoxyCompactList}\small\item\em Enable safer way to deallocate cascades of terminating FSM instances. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+set\+\_\+dealloc\+\_\+ctx} (void $\ast$ctx)
\begin{DoxyCompactList}\small\item\em Instead of deallocating FSM instances, move them to the given talloc context. \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+register} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm)
\begin{DoxyCompactList}\small\item\em register a FSM with the core \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+unregister} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm)
\begin{DoxyCompactList}\small\item\em unregister a FSM from the core \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+find\+\_\+by\+\_\+name} (const char $\ast$\textbf{ name})
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+find\+\_\+by\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, const char $\ast$\textbf{ name})
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+find\+\_\+by\+\_\+id} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, const char $\ast$id)
\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, void $\ast$ctx, void $\ast$priv, int log\+\_\+level, const char $\ast$id)
\begin{DoxyCompactList}\small\item\em allocate a new instance of a specified FSM \end{DoxyCompactList}\item 
struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+alloc\+\_\+child} (struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$parent, uint32\+\_\+t parent\+\_\+term\+\_\+event)
\begin{DoxyCompactList}\small\item\em allocate a new instance of a specified FSM as child of other FSM instance \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+unlink\+\_\+parent} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, void $\ast$ctx)
\begin{DoxyCompactList}\small\item\em unlink child FSM from its parent FSM. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+change\+\_\+parent} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$new\+\_\+parent, uint32\+\_\+t new\+\_\+parent\+\_\+term\+\_\+event)
\begin{DoxyCompactList}\small\item\em change parent instance of an FSM. \end{DoxyCompactList}\item 
void \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+free} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi)
\begin{DoxyCompactList}\small\item\em delete a given instance of a FSM \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, const char $\ast$id)
\begin{DoxyCompactList}\small\item\em Change id of the FSM instance. \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, const char $\ast$fmt,...)
\begin{DoxyCompactList}\small\item\em Change id of the FSM instance using a string format. \end{DoxyCompactList}\item 
int \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+update\+\_\+id\+\_\+f\+\_\+sanitize} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, char replace\+\_\+with, const char $\ast$fmt,...)
\begin{DoxyCompactList}\small\item\em Change id of the FSM instance using a string format, and ensuring a valid id. \end{DoxyCompactList}\item 
const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+event\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, uint32\+\_\+t \textbf{ event})
\begin{DoxyCompactList}\small\item\em get human-\/readable name of FSM event \end{DoxyCompactList}\item 
const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi)
\begin{DoxyCompactList}\small\item\em get human-\/readable name of FSM instance \end{DoxyCompactList}\item 
const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+state\+\_\+name} (const struct \textbf{ osmo\+\_\+fsm} $\ast$fsm, uint32\+\_\+t state)
\begin{DoxyCompactList}\small\item\em get human-\/readable name of FSM state \end{DoxyCompactList}\item 
static const char $\ast$ \textbf{ osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+name} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi)
\begin{DoxyCompactList}\small\item\em return the name of the state the FSM instance is currently in. \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+secs, int T, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em perform a state change of the given FSM instance \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+ms} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+ms, int T, const char $\ast$\textbf{ file}, int line)
\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+timer} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer running. \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+secs, int T, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em perform a state change while keeping the current timer if running, or starting a timer otherwise. \end{DoxyCompactList}\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+state\+\_\+chg\+\_\+keep\+\_\+or\+\_\+start\+\_\+timer\+\_\+ms} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t new\+\_\+state, unsigned long timeout\+\_\+ms, int T, const char $\ast$\textbf{ file}, int line)
\item 
int \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+dispatch} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t \textbf{ event}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em dispatch an event to an osmocom finite state machine instance \end{DoxyCompactList}\item 
void \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \textbf{ cause}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Terminate FSM instance with given cause. \end{DoxyCompactList}\item 
void \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+term\+\_\+children} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, enum \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause} \textbf{ cause}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Terminate all child FSM instances of an FSM instance. \end{DoxyCompactList}\item 
void \textbf{ \+\_\+osmo\+\_\+fsm\+\_\+inst\+\_\+broadcast\+\_\+children} (struct \textbf{ osmo\+\_\+fsm\+\_\+inst} $\ast$fi, uint32\+\_\+t \textbf{ event}, void $\ast$\textbf{ data}, const char $\ast$\textbf{ file}, int line)
\begin{DoxyCompactList}\small\item\em Broadcast an event to all the FSMs children. \end{DoxyCompactList}\end{DoxyCompactItemize}
\doxysubsection*{Variables}
\begin{DoxyCompactItemize}
\item 
const struct \textbf{ value\+\_\+string} \textbf{ osmo\+\_\+fsm\+\_\+term\+\_\+cause\+\_\+names} [$\,$]
\end{DoxyCompactItemize}


\doxysubsection{Detailed Description}
Finite State Machine. 

