fsm.h

Go to the documentation of this file.

 
#pragma once
 
#include <stdint.h>
#include <stdbool.h>
 
#include <osmocom/core/linuxlist.h>
#include <osmocom/core/timer.h>
#include <osmocom/core/utils.h>
#include <osmocom/core/logging.h>
 
struct osmo_fsm_inst;
 
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,
};
 
extern const struct value_string osmo_fsm_term_cause_names[];
static inline const char *osmo_fsm_term_cause_name(enum osmo_fsm_term_cause cause)
{
        return get_value_string(osmo_fsm_term_cause_names, cause);
}
 
 
struct osmo_fsm_state {
        uint32_t in_event_mask;
        uint32_t out_state_mask;
        const char *name;
        void (*action)(struct osmo_fsm_inst *fi, uint32_t event, void *data);
        void (*onenter)(struct osmo_fsm_inst *fi, uint32_t prev_state);
        void (*onleave)(struct osmo_fsm_inst *fi, uint32_t next_state);
};
 
struct osmo_fsm {
        struct llist_head list;
        struct llist_head instances;
        const char *name;
        const struct osmo_fsm_state *states;
        unsigned int num_states;
        uint32_t allstate_event_mask;
        void (*allstate_action)(struct osmo_fsm_inst *fi, uint32_t event, void *data);
        void (*cleanup)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause);
        int (*timer_cb)(struct osmo_fsm_inst *fi);
        int log_subsys;
        const struct value_string *event_names;
        void (*pre_term)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause);
};
 
struct osmo_fsm_inst {
        struct llist_head list;
        struct osmo_fsm *fsm;
        const char *id;
        const char *name;
        void *priv;
        int log_level;
        uint32_t state;
 
        int T;
        struct osmo_timer_list timer;
 
        struct {
                struct osmo_fsm_inst *parent;
                uint32_t parent_term_event;
                struct llist_head children;
                struct llist_head child;
                bool terminating;
        } proc;
};
 
void osmo_fsm_log_addr(bool log_addr);
void osmo_fsm_log_timeouts(bool log_timeouts);
void osmo_fsm_term_safely(bool term_safely);
void osmo_fsm_set_dealloc_ctx(void *ctx);
 
#define LOGPFSMSL(fi, subsys, level, fmt, args...) \
                LOGPFSMSLSRC(fi, subsys, level, __FILE__, __LINE__, fmt, ## args)
 
#define LOGPFSMSLSRC(fi, subsys, level, caller_file, caller_line, fmt, args...) \
                LOGPSRC(subsys, level, \
                        caller_file, caller_line, \
                        "%s{%s}: " fmt, \
                        osmo_fsm_inst_name(fi), \
                        (fi) ? osmo_fsm_state_name((fi)->fsm, (fi)->state) : "fi=NULL", ## args)
 
 
#define LOGPFSML(fi, level, fmt, args...) \
                LOGPFSMLSRC(fi, level, __FILE__, __LINE__, fmt, ## args)
 
#define LOGPFSMLSRC(fi, level, caller_file, caller_line, fmt, args...) \
                LOGPFSMSLSRC(fi, (fi) ? (fi)->fsm->log_subsys : DLGLOBAL, level, \
                             caller_file, caller_line, fmt, ## args)
 
#define LOGPFSM(fi, fmt, args...) \
                LOGPFSML(fi, (fi) ? (fi)->log_level : LOGL_ERROR, fmt, ## args)
 
#define LOGPFSMSRC(fi, caller_file, caller_line, fmt, args...) \
                LOGPFSMLSRC(fi, (fi) ? (fi)->log_level : LOGL_ERROR, \
                            caller_file, caller_line, \
                            fmt, ## args)
 
#define OSMO_T_FMT "%c%u"
#define OSMO_T_FMT_ARGS(T) ((T) >= 0 ? 'T' : 'X'), ((T) >= 0 ? (T) : -(T))
 
int osmo_fsm_register(struct osmo_fsm *fsm);
void osmo_fsm_unregister(struct osmo_fsm *fsm);
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);
struct osmo_fsm_inst *osmo_fsm_inst_alloc_child(struct osmo_fsm *fsm,
                                                struct osmo_fsm_inst *parent,
                                                uint32_t parent_term_event);
void osmo_fsm_inst_unlink_parent(struct osmo_fsm_inst *fi, void *ctx);
void osmo_fsm_inst_change_parent(struct osmo_fsm_inst *fi,
                                 struct osmo_fsm_inst *new_parent,
                                 uint32_t new_parent_term_event);
void osmo_fsm_inst_free(struct osmo_fsm_inst *fi);
 
int osmo_fsm_inst_update_id(struct osmo_fsm_inst *fi, const char *id);
int osmo_fsm_inst_update_id_f(struct osmo_fsm_inst *fi, const char *fmt, ...);
int osmo_fsm_inst_update_id_f_sanitize(struct osmo_fsm_inst *fi, char replace_with, const char *fmt, ...);
 
const char *osmo_fsm_event_name(const struct osmo_fsm *fsm, uint32_t event);
const char *osmo_fsm_inst_name(const struct osmo_fsm_inst *fi);
const char *osmo_fsm_state_name(const struct osmo_fsm *fsm, uint32_t state);
 
static inline const char *osmo_fsm_inst_state_name(struct osmo_fsm_inst *fi)
{ return fi ? osmo_fsm_state_name(fi->fsm, fi->state) : "NULL"; }
 
#define osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T) \
        _osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T, \
                                 __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);
 
#define osmo_fsm_inst_state_chg_ms(fi, new_state, timeout_ms, T) \
        _osmo_fsm_inst_state_chg_ms(fi, new_state, timeout_ms, T, \
                                 __FILE__, __LINE__)
int _osmo_fsm_inst_state_chg_ms(struct osmo_fsm_inst *fi, uint32_t new_state,
                                unsigned long timeout_ms, int T,
                                const char *file, int line);
 
#define osmo_fsm_inst_state_chg_keep_timer(fi, new_state) \
        _osmo_fsm_inst_state_chg_keep_timer(fi, new_state, \
                                 __FILE__, __LINE__)
int _osmo_fsm_inst_state_chg_keep_timer(struct osmo_fsm_inst *fi, uint32_t new_state,
                                        const char *file, int line);
 
#define osmo_fsm_inst_state_chg_keep_or_start_timer(fi, new_state, timeout_secs, T) \
        _osmo_fsm_inst_state_chg_keep_or_start_timer(fi, new_state, timeout_secs, T, \
                                                     __FILE__, __LINE__)
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);
 
#define osmo_fsm_inst_state_chg_keep_or_start_timer_ms(fi, new_state, timeout_ms, T) \
        _osmo_fsm_inst_state_chg_keep_or_start_timer_ms(fi, new_state, timeout_ms, T, \
                                                     __FILE__, __LINE__)
int _osmo_fsm_inst_state_chg_keep_or_start_timer_ms(struct osmo_fsm_inst *fi, uint32_t new_state,
                                                   unsigned long timeout_ms, int T,
                                                   const char *file, int line);
 
 
#define osmo_fsm_inst_dispatch(fi, event, data) \
        _osmo_fsm_inst_dispatch(fi, event, data, __FILE__, __LINE__)
int _osmo_fsm_inst_dispatch(struct osmo_fsm_inst *fi, uint32_t event, void *data,
                            const char *file, int line);
 
#define osmo_fsm_inst_term(fi, cause, data) \
        _osmo_fsm_inst_term(fi, cause, data, __FILE__, __LINE__)
void _osmo_fsm_inst_term(struct osmo_fsm_inst *fi,
                         enum osmo_fsm_term_cause cause, void *data,
                         const char *file, int line);
 
#define osmo_fsm_inst_term_children(fi, cause, data) \
        _osmo_fsm_inst_term_children(fi, cause, data, __FILE__, __LINE__)
void _osmo_fsm_inst_term_children(struct osmo_fsm_inst *fi,
                                  enum osmo_fsm_term_cause cause,
                                  void *data,
                                  const char *file, int line);
 
#define osmo_fsm_inst_broadcast_children(fi, cause, data) \
        _osmo_fsm_inst_broadcast_children(fi, cause, data, __FILE__, __LINE__)
void _osmo_fsm_inst_broadcast_children(struct osmo_fsm_inst *fi, uint32_t event,
                                        void *data, const char *file, int line);