libosmocore  1.0.1.85-9f28
Osmocom core library
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
fsm.h
Go to the documentation of this file.
1 
5 #pragma once
6 
7 #include <stdint.h>
8 #include <stdbool.h>
9 
10 #include <osmocom/core/linuxlist.h>
11 #include <osmocom/core/timer.h>
12 #include <osmocom/core/utils.h>
13 
18 struct osmo_fsm_inst;
19 
31 };
32 
33 extern const struct value_string osmo_fsm_term_cause_names[];
34 static inline const char *osmo_fsm_term_cause_name(enum osmo_fsm_term_cause cause)
35 {
37 }
38 
39 
43  uint32_t in_event_mask;
45  uint32_t out_state_mask;
47  const char *name;
49  void (*action)(struct osmo_fsm_inst *fi, uint32_t event, void *data);
51  void (*onenter)(struct osmo_fsm_inst *fi, uint32_t prev_state);
53  void (*onleave)(struct osmo_fsm_inst *fi, uint32_t next_state);
54 };
55 
57 struct osmo_fsm {
59  struct llist_head list;
63  const char *name;
65  const struct osmo_fsm_state *states;
67  unsigned int num_states;
71  void (*allstate_action)(struct osmo_fsm_inst *fi, uint32_t event, void *data);
73  void (*cleanup)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause);
76  int (*timer_cb)(struct osmo_fsm_inst *fi);
80  const struct value_string *event_names;
82  void (*pre_term)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause);
83 };
84 
86 struct osmo_fsm_inst {
88  struct llist_head list;
90  struct osmo_fsm *fsm;
92  const char *id;
94  const char *name;
96  void *priv;
98  int log_level;
100  uint32_t state;
101 
103  int T;
106 
108  struct {
117  } proc;
118 };
119 
120 void osmo_fsm_log_addr(bool log_addr);
121 void osmo_fsm_log_timeouts(bool log_timeouts);
122 
130 #define LOGPFSMSL(fi, subsys, level, fmt, args...) \
131  LOGPFSMSLSRC(fi, subsys, level, __FILE__, __LINE__, fmt, ## args)
132 
143 #define LOGPFSMSLSRC(fi, subsys, level, caller_file, caller_line, fmt, args...) \
144  LOGPSRC(subsys, level, \
145  caller_file, caller_line, \
146  "%s{%s}: " fmt, \
147  osmo_fsm_inst_name(fi), \
148  (fi) ? osmo_fsm_state_name((fi)->fsm, (fi)->state) : "fi=NULL", ## args)
149 
150 
157 #define LOGPFSML(fi, level, fmt, args...) \
158  LOGPFSMLSRC(fi, level, __FILE__, __LINE__, fmt, ## args)
159 
169 #define LOGPFSMLSRC(fi, level, caller_file, caller_line, fmt, args...) \
170  LOGPFSMSLSRC(fi, (fi) ? (fi)->fsm->log_subsys : DLGLOBAL, level, \
171  caller_file, caller_line, fmt, ## args)
172 
180 #define LOGPFSM(fi, fmt, args...) \
181  LOGPFSML(fi, (fi) ? (fi)->log_level : LOGL_ERROR, fmt, ## args)
182 
192 #define LOGPFSMSRC(fi, caller_file, caller_line, fmt, args...) \
193  LOGPFSMLSRC(fi, (fi) ? (fi)->log_level : LOGL_ERROR, \
194  caller_file, caller_line, \
195  fmt, ## args)
196 
197 #define OSMO_T_FMT "%c%u"
198 #define OSMO_T_FMT_ARGS(T) ((T) >= 0 ? 'T' : 'X'), ((T) >= 0 ? T : -T)
199 
200 int osmo_fsm_register(struct osmo_fsm *fsm);
201 void osmo_fsm_unregister(struct osmo_fsm *fsm);
202 struct osmo_fsm *osmo_fsm_find_by_name(const char *name);
204  const char *name);
205 struct osmo_fsm_inst *osmo_fsm_inst_find_by_id(const struct osmo_fsm *fsm,
206  const char *id);
207 struct osmo_fsm_inst *osmo_fsm_inst_alloc(struct osmo_fsm *fsm, void *ctx, void *priv,
208  int log_level, const char *id);
210  struct osmo_fsm_inst *parent,
211  uint32_t parent_term_event);
212 void osmo_fsm_inst_unlink_parent(struct osmo_fsm_inst *fi, void *ctx);
214  struct osmo_fsm_inst *new_parent,
215  uint32_t new_parent_term_event);
216 void osmo_fsm_inst_free(struct osmo_fsm_inst *fi);
217 
218 int osmo_fsm_inst_update_id(struct osmo_fsm_inst *fi, const char *id);
219 int osmo_fsm_inst_update_id_f(struct osmo_fsm_inst *fi, const char *fmt, ...);
220 
221 const char *osmo_fsm_event_name(struct osmo_fsm *fsm, uint32_t event);
222 const char *osmo_fsm_inst_name(struct osmo_fsm_inst *fi);
223 const char *osmo_fsm_state_name(struct osmo_fsm *fsm, uint32_t state);
224 
226 static inline const char *osmo_fsm_inst_state_name(struct osmo_fsm_inst *fi)
227 { return fi ? osmo_fsm_state_name(fi->fsm, fi->state) : "NULL"; }
228 
235 #define osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T) \
236  _osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T, \
237  __FILE__, __LINE__)
238 int _osmo_fsm_inst_state_chg(struct osmo_fsm_inst *fi, uint32_t new_state,
239  unsigned long timeout_secs, int T,
240  const char *file, int line);
241 
251 #define osmo_fsm_inst_state_chg_keep_timer(fi, new_state) \
252  _osmo_fsm_inst_state_chg_keep_timer(fi, new_state, \
253  __FILE__, __LINE__)
254 int _osmo_fsm_inst_state_chg_keep_timer(struct osmo_fsm_inst *fi, uint32_t new_state,
255  const char *file, int line);
256 
265 #define osmo_fsm_inst_state_chg_keep_or_start_timer(fi, new_state, timeout_secs, T) \
266  _osmo_fsm_inst_state_chg_keep_or_start_timer(fi, new_state, timeout_secs, T, \
267  __FILE__, __LINE__)
268 int _osmo_fsm_inst_state_chg_keep_or_start_timer(struct osmo_fsm_inst *fi, uint32_t new_state,
269  unsigned long timeout_secs, int T,
270  const char *file, int line);
271 
278 #define osmo_fsm_inst_dispatch(fi, event, data) \
279  _osmo_fsm_inst_dispatch(fi, event, data, __FILE__, __LINE__)
280 int _osmo_fsm_inst_dispatch(struct osmo_fsm_inst *fi, uint32_t event, void *data,
281  const char *file, int line);
282 
289 #define osmo_fsm_inst_term(fi, cause, data) \
290  _osmo_fsm_inst_term(fi, cause, data, __FILE__, __LINE__)
291 void _osmo_fsm_inst_term(struct osmo_fsm_inst *fi,
292  enum osmo_fsm_term_cause cause, void *data,
293  const char *file, int line);
294 
301 #define osmo_fsm_inst_term_children(fi, cause, data) \
302  _osmo_fsm_inst_term_children(fi, cause, data, __FILE__, __LINE__)
304  enum osmo_fsm_term_cause cause,
305  void *data,
306  const char *file, int line);
307 
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...
Definition: fsm.c:627
uint32_t state
current state of the FSM
Definition: fsm.h:100
struct osmo_fsm_inst * parent
the parent FSM that has created us
Definition: fsm.h:110
int log_subsys
logging sub-system for this FSM
Definition: fsm.h:78
uint32_t out_state_mask
bit-mask to which other states this state may transiton
Definition: fsm.h:45
const char * name
human-readable name of this state
Definition: fsm.h:47
void(* action)(struct osmo_fsm_inst *fi, uint32_t event, void *data)
function to be called for events arriving in this state
Definition: fsm.h:49
struct osmo_fsm_inst * osmo_fsm_inst_find_by_name(const struct osmo_fsm *fsm, const char *name)
Definition: fsm.c:138
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
Definition: fsm.c:651
const char * name
human readable fully-qualified name
Definition: fsm.h:94
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:573
uint32_t allstate_event_mask
bit-mask of events permitted in all states
Definition: fsm.h:69
const char * get_value_string(const struct value_string *vs, uint32_t val)
get human-readable string for given value
Definition: utils.c:55
void osmo_fsm_inst_free(struct osmo_fsm_inst *fi)
delete a given instance of a FSM
Definition: fsm.c:400
void osmo_fsm_log_addr(bool log_addr)
specify if FSM instance addresses should be logged or not
Definition: fsm.c:103
osmo_fsm_term_cause
Definition: fsm.h:20
const struct value_string osmo_fsm_term_cause_names[]
Definition: fsm.c:789
int T
timer number for states with time-out
Definition: fsm.h:103
void osmo_fsm_unregister(struct osmo_fsm *fsm)
unregister a FSM from the core
Definition: fsm.c:198
struct osmo_fsm * fsm
back-pointer to the FSM of which we are an instance
Definition: fsm.h:90
struct osmo_fsm_inst * osmo_fsm_inst_find_by_id(const struct osmo_fsm *fsm, const char *id)
Definition: fsm.c:155
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:599
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.
Definition: fsm.h:226
void(* onleave)(struct osmo_fsm_inst *fi, uint32_t next_state)
function to be called just before leaving the state
Definition: fsm.h:53
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.
Definition: fsm.c:706
struct osmo_fsm * osmo_fsm_find_by_name(const char *name)
Definition: fsm.c:128
const char * osmo_fsm_event_name(struct osmo_fsm *fsm, uint32_t event)
get human-readable name of FSM event
Definition: fsm.c:413
struct llist_head list
global list
Definition: fsm.h:59
const char * id
human readable identifier
Definition: fsm.h:92
A mapping between human-readable string and numeric value.
Definition: utils.h:37
uint32_t parent_term_event
the event we should send upon termination
Definition: fsm.h:112
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.
Definition: fsm.c:758
erroneous termination of process
Definition: fsm.h:28
uint8_t cause
unsigned int num_states
number of entries in states
Definition: fsm.h:67
struct llist_head instances
list of instances of this FSM
Definition: fsm.h:61
int(* timer_cb)(struct osmo_fsm_inst *fi)
timer call-back for states with time-out.
Definition: fsm.h:76
write Write running configuration to or terminal n Write configuration to the file(same as write file)\n") ALIAS(config_write_file
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
Definition: fsm.c:301
char name[32]
source file name
Definition: gsmtap.h:124
Osmocom timer handling routines.
const char * name
human readable name
Definition: fsm.h:63
void(* cleanup)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause)
clean-up function, called during termination
Definition: fsm.h:73
static const char * osmo_fsm_term_cause_name(enum osmo_fsm_term_cause cause)
Definition: fsm.h:34
struct osmo_timer_list timer
timer back-end for states with time-out
Definition: fsm.h:105
uint8_t data[0]
void * priv
some private data of this instance
Definition: fsm.h:96
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.
Definition: fsm.c:381
a single instanceof an osmocom finite state machine
Definition: fsm.h:86
int log_level
logging level for this FSM
Definition: fsm.h:98
Simple doubly linked list implementation.
struct llist_head list
member in the fsm->instances list
Definition: fsm.h:88
struct osmo_fsm_inst::@0 proc
support for fsm-based procedures
void osmo_fsm_log_timeouts(bool log_timeouts)
Enable or disable logging of timeout values for FSM instance state changes.
Definition: fsm.c:123
(double) linked list header structure
Definition: linuxlist.h:46
const char * osmo_fsm_inst_name(struct osmo_fsm_inst *fi)
get human-readable name of FSM instance
Definition: fsm.c:427
a description of an osmocom finite state machine
Definition: fsm.h:57
void(* pre_term)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause)
graceful exit function, called at the beginning of termination
Definition: fsm.h:82
struct llist_head children
a list of children processes
Definition: fsm.h:114
description of a rule in the FSM
Definition: fsm.h:41
const struct osmo_fsm_state * states
table of state transition rules
Definition: fsm.h:65
const struct value_string * event_names
human-readable names of events
Definition: fsm.h:80
void(* allstate_action)(struct osmo_fsm_inst *fi, uint32_t event, void *data)
function pointer to be called for allstate events
Definition: fsm.h:71
event
struct llist_head child
llist_head linked to parent->proc.children
Definition: fsm.h:116
void osmo_fsm_inst_unlink_parent(struct osmo_fsm_inst *fi, void *ctx)
unlink child FSM from its parent FSM.
Definition: fsm.c:364
terminate because parent terminated
Definition: fsm.h:22
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.
Definition: fsm.c:265
const char * osmo_fsm_state_name(struct osmo_fsm *fsm, uint32_t state)
get human-readable name of FSM state
Definition: fsm.c:443
A structure representing a single instance of a timer.
Definition: timer.h:56
int osmo_fsm_register(struct osmo_fsm *fsm)
register a FSM with the core
Definition: fsm.c:175
int osmo_fsm_inst_update_id(struct osmo_fsm_inst *fi, const char *id)
Change id of the FSM instance.
Definition: fsm.c:233
uint32_t in_event_mask
bit-mask of permitted input events for this state
Definition: fsm.h:43
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
Definition: fsm.c:336
regular termination of process
Definition: fsm.h:26
termination due to time-out
Definition: fsm.h:30
void(* onenter)(struct osmo_fsm_inst *fi, uint32_t prev_state)
function to be called just after entering the state
Definition: fsm.h:51
terminate on explicit user request
Definition: fsm.h:24