2017-06-20 02:35:06 +00:00
|
|
|
/*! \file fsm.h
|
|
|
|
* Finite State Machine
|
|
|
|
*/
|
|
|
|
|
2016-05-29 01:53:17 +00:00
|
|
|
#pragma once
|
|
|
|
|
|
|
|
#include <stdint.h>
|
|
|
|
#include <stdbool.h>
|
|
|
|
|
|
|
|
#include <osmocom/core/linuxlist.h>
|
|
|
|
#include <osmocom/core/timer.h>
|
|
|
|
#include <osmocom/core/utils.h>
|
2019-11-09 05:41:10 +00:00
|
|
|
#include <osmocom/core/logging.h>
|
2016-05-29 01:53:17 +00:00
|
|
|
|
|
|
|
/*! \defgroup fsm Finite State Machine abstraction
|
|
|
|
* @{
|
2017-06-20 02:35:06 +00:00
|
|
|
* \file fsm.h */
|
2016-05-29 01:53:17 +00:00
|
|
|
|
|
|
|
struct osmo_fsm_inst;
|
|
|
|
|
|
|
|
enum osmo_fsm_term_cause {
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! terminate because parent terminated */
|
2016-05-29 01:53:17 +00:00
|
|
|
OSMO_FSM_TERM_PARENT,
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! terminate on explicit user request */
|
2016-05-29 01:53:17 +00:00
|
|
|
OSMO_FSM_TERM_REQUEST,
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! regular termination of process */
|
2016-05-29 01:53:17 +00:00
|
|
|
OSMO_FSM_TERM_REGULAR,
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! erroneous termination of process */
|
2016-05-29 01:53:17 +00:00
|
|
|
OSMO_FSM_TERM_ERROR,
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! termination due to time-out */
|
2016-06-18 08:36:25 +00:00
|
|
|
OSMO_FSM_TERM_TIMEOUT,
|
2016-05-29 01:53:17 +00:00
|
|
|
};
|
|
|
|
|
2016-12-14 17:35:47 +00:00
|
|
|
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);
|
|
|
|
}
|
|
|
|
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! description of a rule in the FSM */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct osmo_fsm_state {
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! bit-mask of permitted input events for this state */
|
2016-05-29 01:53:17 +00:00
|
|
|
uint32_t in_event_mask;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! bit-mask to which other states this state may transiton */
|
2016-05-29 01:53:17 +00:00
|
|
|
uint32_t out_state_mask;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! human-readable name of this state */
|
2016-05-29 01:53:17 +00:00
|
|
|
const char *name;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! function to be called for events arriving in this state */
|
2016-05-29 01:53:17 +00:00
|
|
|
void (*action)(struct osmo_fsm_inst *fi, uint32_t event, void *data);
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! function to be called just after entering the state */
|
2016-05-29 01:53:17 +00:00
|
|
|
void (*onenter)(struct osmo_fsm_inst *fi, uint32_t prev_state);
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! function to be called just before leaving the state */
|
2016-05-29 01:53:17 +00:00
|
|
|
void (*onleave)(struct osmo_fsm_inst *fi, uint32_t next_state);
|
|
|
|
};
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! a description of an osmocom finite state machine */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct osmo_fsm {
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! global list */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct llist_head list;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! list of instances of this FSM */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct llist_head instances;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! human readable name */
|
2016-05-29 01:53:17 +00:00
|
|
|
const char *name;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! table of state transition rules */
|
2016-05-29 01:53:17 +00:00
|
|
|
const struct osmo_fsm_state *states;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! number of entries in \ref states */
|
2016-05-29 01:53:17 +00:00
|
|
|
unsigned int num_states;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! bit-mask of events permitted in all states */
|
2016-05-29 01:53:17 +00:00
|
|
|
uint32_t allstate_event_mask;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! function pointer to be called for allstate events */
|
2016-05-29 01:53:17 +00:00
|
|
|
void (*allstate_action)(struct osmo_fsm_inst *fi, uint32_t event, void *data);
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! clean-up function, called during termination */
|
2016-05-29 01:53:17 +00:00
|
|
|
void (*cleanup)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause);
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! timer call-back for states with time-out.
|
2016-12-09 15:10:34 +00:00
|
|
|
* \returns 1 to request termination, 0 to keep running. */
|
2016-06-18 08:36:25 +00:00
|
|
|
int (*timer_cb)(struct osmo_fsm_inst *fi);
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! logging sub-system for this FSM */
|
2016-05-29 01:53:17 +00:00
|
|
|
int log_subsys;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! human-readable names of events */
|
2016-05-29 01:53:17 +00:00
|
|
|
const struct value_string *event_names;
|
2018-02-14 17:20:07 +00:00
|
|
|
/*! graceful exit function, called at the beginning of termination */
|
|
|
|
void (*pre_term)(struct osmo_fsm_inst *fi, enum osmo_fsm_term_cause cause);
|
2016-05-29 01:53:17 +00:00
|
|
|
};
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! a single instanceof an osmocom finite state machine */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct osmo_fsm_inst {
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! member in the fsm->instances list */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct llist_head list;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! back-pointer to the FSM of which we are an instance */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct osmo_fsm *fsm;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! human readable identifier */
|
2016-05-29 01:53:17 +00:00
|
|
|
const char *id;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! human readable fully-qualified name */
|
2016-05-29 01:53:17 +00:00
|
|
|
const char *name;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! some private data of this instance */
|
2016-05-29 01:53:17 +00:00
|
|
|
void *priv;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! logging level for this FSM */
|
2016-05-29 01:53:17 +00:00
|
|
|
int log_level;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! current state of the FSM */
|
2016-05-29 01:53:17 +00:00
|
|
|
uint32_t state;
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! timer number for states with time-out */
|
2016-05-29 01:53:17 +00:00
|
|
|
int T;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! timer back-end for states with time-out */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct osmo_timer_list timer;
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! support for fsm-based procedures */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct {
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! the parent FSM that has created us */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct osmo_fsm_inst *parent;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! the event we should send upon termination */
|
2016-05-29 01:53:17 +00:00
|
|
|
uint32_t parent_term_event;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! a list of children processes */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct llist_head children;
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! \ref llist_head linked to parent->proc.children */
|
2016-05-29 01:53:17 +00:00
|
|
|
struct llist_head child;
|
2019-04-07 22:33:53 +00:00
|
|
|
/*! Indicator whether osmo_fsm_inst_term() was already invoked on this instance. */
|
|
|
|
bool terminating;
|
2016-05-29 01:53:17 +00:00
|
|
|
} proc;
|
|
|
|
};
|
|
|
|
|
|
|
|
void osmo_fsm_log_addr(bool log_addr);
|
2018-05-31 13:30:15 +00:00
|
|
|
void osmo_fsm_log_timeouts(bool log_timeouts);
|
fsm: support graceful osmo_fsm_inst_term() cascades
Add global flag osmo_fsm_term_safely() -- if set to true, enable the following
behavior:
Detect osmo_fsm_inst_term() occuring within osmo_fsm_inst_term():
- collect deallocations until the outermost osmo_fsm_inst_term() is done.
- call osmo_fsm_inst_free() *after* dispatching the parent event.
If a struct osmo_fsm_inst enters osmo_fsm_inst_term() while another is already
within osmo_fsm_inst_term(), do not directly deallocate it, but talloc-reparent
it to a separate talloc context, to be deallocated with the outermost FSM inst.
The effect is that all osmo_fsm_inst freed within an osmo_fsm_inst_term()
cascade will stay allocated until all osmo_fsm_inst_term() are complete and all
of them will be deallocated at the same time.
Mark the deferred deallocation state as __thread in an attempt to make cascaded
deallocation handling threadsafe. Keep the enable/disable flag separate, so
that it is global and not per-thread.
The feature is showcased by fsm_dealloc_test.c: with this feature, all of those
wild deallocation scenarios succeed.
Make fsm_dealloc_test a normal regression test in testsuite.at.
Rationale:
It is difficult to gracefully handle deallocations of groups of FSM instances
that reference each other. As soon as one child dispatching a cleanup event
causes its parent to deallocate before fsm.c was ready for it, deallocation
will hit a use-after-free. Before this patch, by using parent_term events and
distinct "terminating" FSM states, parent/child FSMs can be taught to wait for
all children to deallocate before deallocating the parent. But as soon as a
non-child / non-parent FSM instance is involved, or actually any other
cleanup() action that triggers parent FSMs or parent talloc contexts to become
unused, it is near impossible to think of all possible deallocation events
ricocheting, and to avoid running into freeing FSM instances that were still in
the middle of osmo_fsm_inst_term(), or FSM instances to enter
osmo_fsm_inst_term() more than once. This patch makes deallocation of "all
possible" setups of complex cross referencing FSM instances easy to handle
correctly, without running into use-after-free or double free situations, and,
notably, without changing calling code.
Change-Id: I8eda67540a1cd444491beb7856b9fcd0a3143b18
2019-03-24 04:56:21 +00:00
|
|
|
void osmo_fsm_term_safely(bool term_safely);
|
add osmo_fsm_set_dealloc_ctx(), to help with use-after-free
This is a simpler and more general solution to the problem so far solved by
osmo_fsm_term_safely(true). This extends use-after-free fixes to arbitrary
functions, not only FSM instances during termination.
The aim is to defer talloc_free() until back in the main loop.
Rationale: I discovered an osmo-msc use-after-free crash from an invalid
message, caused by this pattern:
void event_action()
{
osmo_fsm_inst_dispatch(foo, FOO_EVENT, NULL);
osmo_fsm_inst_dispatch(bar, BAR_EVENT, NULL);
}
Usually, FOO_EVENT takes successful action, and afterwards we also notify bar.
However, in this particular case, FOO_EVENT caused failure, and the immediate
error handling directly terminated and deallocated bar. In such a case,
dispatching BAR_EVENT causes a use-after-free; this constituted a DoS vector
just from sending messages that cause *any* failure during the first event
dispatch.
Instead, when this is enabled, we do not deallocate 'foo' until event_action()
has returned back to the main loop.
Test: duplicate fsm_dealloc_test.c using this, and print the number of items
deallocated in each test loop, to ensure the feature works. We also verify that
the deallocation safety works simply by fsm_dealloc_test.c not crashing.
We should probably follow up by refusing event dispatch and state transitions
for FSM instances that are terminating or already terminated:
see I0adc13a1a998e953b6c850efa2761350dd07e03a.
Change-Id: Ief4dba9ea587c9b4aea69993e965fbb20fb80e78
2019-10-04 18:37:17 +00:00
|
|
|
void osmo_fsm_set_dealloc_ctx(void *ctx);
|
2016-05-29 01:53:17 +00:00
|
|
|
|
add LOGPFSMSL(), LOGPFSMSLSRC()
Using an FSM instace's logging context is very useful. Sometimes it makes sense
to log something on a different logging category than the FSM definition's
default category.
For example, an MSC conn has aspects concerning MM, CC, RR, MGCP, ..., and
currently all of those log on DMM.
This came up in I358cfbaf0f44f25148e8b9bafcb9257b1952b35a, where I want to log
an MGCP event using a ran_conn context, and used the conn->fi->id. That of
course omits context like the current conn FSM state...
I remember at least one other place where I recently added logging using some
fi->id as context, so it might turn out useful in various places.
Change-Id: I11b182a03f5ecb6df7cd8f260757d3626c8e945d
2018-12-19 22:34:25 +00:00
|
|
|
/*! Log using FSM instance's context, on explicit logging subsystem and level.
|
|
|
|
* \param fi An osmo_fsm_inst.
|
|
|
|
* \param subsys A logging subsystem, e.g. DLGLOBAL.
|
|
|
|
* \param level A logging level, e.g. LOGL_INFO.
|
|
|
|
* \param fmt printf-like format string.
|
|
|
|
* \param args Format string arguments.
|
|
|
|
*/
|
|
|
|
#define LOGPFSMSL(fi, subsys, level, fmt, args...) \
|
|
|
|
LOGPFSMSLSRC(fi, subsys, level, __FILE__, __LINE__, fmt, ## args)
|
|
|
|
|
|
|
|
/*! Log using FSM instance's context, on explicit logging subsystem and level,
|
|
|
|
* and passing explicit source file and line information.
|
|
|
|
* \param fi An osmo_fsm_inst.
|
|
|
|
* \param subsys A logging subsystem, e.g. DLGLOBAL.
|
|
|
|
* \param level A logging level, e.g. LOGL_INFO.
|
|
|
|
* \param caller_file A string constant containing a source file path, like __FILE__.
|
|
|
|
* \param caller_line A number constant containing a source file line, like __LINE__.
|
|
|
|
* \param fmt printf-like format string.
|
|
|
|
* \param args Format string arguments.
|
|
|
|
*/
|
|
|
|
#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)
|
|
|
|
|
|
|
|
|
2018-12-19 23:19:29 +00:00
|
|
|
/*! Log using FSM instance's context, on explicit logging level.
|
|
|
|
* \param fi An osmo_fsm_inst.
|
|
|
|
* \param level A logging level, e.g. LOGL_INFO.
|
|
|
|
* \param fmt printf-like format string.
|
|
|
|
* \param args Format string arguments.
|
|
|
|
*/
|
2016-12-14 16:37:34 +00:00
|
|
|
#define LOGPFSML(fi, level, fmt, args...) \
|
2018-12-19 23:00:11 +00:00
|
|
|
LOGPFSMLSRC(fi, level, __FILE__, __LINE__, fmt, ## args)
|
2016-12-14 16:37:34 +00:00
|
|
|
|
2018-12-19 23:19:29 +00:00
|
|
|
/*! Log using FSM instance's context, on explicit logging level, and with explicit source file and line info.
|
|
|
|
* The log subsystem to log on is obtained from the underlying FSM definition.
|
|
|
|
* \param fi An osmo_fsm_inst.
|
|
|
|
* \param level A logging level, e.g. LOGL_INFO.
|
|
|
|
* \param caller_file A string constant containing a source file path, like __FILE__.
|
|
|
|
* \param caller_line A number constant containing a source file line, like __LINE__.
|
|
|
|
* \param fmt printf-like format string.
|
|
|
|
* \param args Format string arguments.
|
|
|
|
*/
|
2016-12-23 00:00:13 +00:00
|
|
|
#define LOGPFSMLSRC(fi, level, caller_file, caller_line, fmt, args...) \
|
add LOGPFSMSL(), LOGPFSMSLSRC()
Using an FSM instace's logging context is very useful. Sometimes it makes sense
to log something on a different logging category than the FSM definition's
default category.
For example, an MSC conn has aspects concerning MM, CC, RR, MGCP, ..., and
currently all of those log on DMM.
This came up in I358cfbaf0f44f25148e8b9bafcb9257b1952b35a, where I want to log
an MGCP event using a ran_conn context, and used the conn->fi->id. That of
course omits context like the current conn FSM state...
I remember at least one other place where I recently added logging using some
fi->id as context, so it might turn out useful in various places.
Change-Id: I11b182a03f5ecb6df7cd8f260757d3626c8e945d
2018-12-19 22:34:25 +00:00
|
|
|
LOGPFSMSLSRC(fi, (fi) ? (fi)->fsm->log_subsys : DLGLOBAL, level, \
|
|
|
|
caller_file, caller_line, fmt, ## args)
|
2016-12-23 00:00:13 +00:00
|
|
|
|
2018-12-19 23:19:29 +00:00
|
|
|
/*! Log using FSM instance's context.
|
|
|
|
* The log level to log on is obtained from the FSM instance.
|
|
|
|
* The log subsystem to log on is obtained from the underlying FSM definition.
|
|
|
|
* \param fi An osmo_fsm_inst.
|
|
|
|
* \param fmt printf-like format string.
|
|
|
|
* \param args Format string arguments.
|
|
|
|
*/
|
2018-12-19 23:00:11 +00:00
|
|
|
#define LOGPFSM(fi, fmt, args...) \
|
2018-12-19 23:03:59 +00:00
|
|
|
LOGPFSML(fi, (fi) ? (fi)->log_level : LOGL_ERROR, fmt, ## args)
|
2018-12-19 23:00:11 +00:00
|
|
|
|
2018-12-19 23:19:29 +00:00
|
|
|
/*! Log using FSM instance's context, with explicit source file and line info.
|
|
|
|
* The log level to log on is obtained from the FSM instance.
|
|
|
|
* The log subsystem to log on is obtained from the underlying FSM definition.
|
|
|
|
* \param fi An osmo_fsm_inst.
|
|
|
|
* \param caller_file A string constant containing a source file path, like __FILE__.
|
|
|
|
* \param caller_line A number constant containing a source file line, like __LINE__.
|
|
|
|
* \param fmt printf-like format string.
|
|
|
|
* \param args Format string arguments.
|
|
|
|
*/
|
2016-12-23 00:00:13 +00:00
|
|
|
#define LOGPFSMSRC(fi, caller_file, caller_line, fmt, args...) \
|
2018-12-19 23:03:59 +00:00
|
|
|
LOGPFSMLSRC(fi, (fi) ? (fi)->log_level : LOGL_ERROR, \
|
2016-12-23 00:00:13 +00:00
|
|
|
caller_file, caller_line, \
|
|
|
|
fmt, ## args)
|
|
|
|
|
2019-02-21 01:27:48 +00:00
|
|
|
#define OSMO_T_FMT "%c%u"
|
|
|
|
#define OSMO_T_FMT_ARGS(T) ((T) >= 0 ? 'T' : 'X'), ((T) >= 0 ? T : -T)
|
|
|
|
|
2016-05-29 01:53:17 +00:00
|
|
|
int osmo_fsm_register(struct osmo_fsm *fsm);
|
2016-11-01 10:02:17 +00:00
|
|
|
void osmo_fsm_unregister(struct osmo_fsm *fsm);
|
2017-01-07 10:11:03 +00:00
|
|
|
struct osmo_fsm *osmo_fsm_find_by_name(const char *name);
|
2017-04-16 15:23:56 +00:00
|
|
|
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);
|
2016-05-29 01:53:17 +00:00
|
|
|
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);
|
2018-01-16 17:45:56 +00:00
|
|
|
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);
|
2016-05-29 01:53:17 +00:00
|
|
|
void osmo_fsm_inst_free(struct osmo_fsm_inst *fi);
|
|
|
|
|
2018-02-08 17:00:37 +00:00
|
|
|
int osmo_fsm_inst_update_id(struct osmo_fsm_inst *fi, const char *id);
|
2018-03-31 14:34:49 +00:00
|
|
|
int osmo_fsm_inst_update_id_f(struct osmo_fsm_inst *fi, const char *fmt, ...);
|
2019-04-11 04:58:44 +00:00
|
|
|
int osmo_fsm_inst_update_id_f_sanitize(struct osmo_fsm_inst *fi, char replace_with, const char *fmt, ...);
|
2018-02-08 17:00:37 +00:00
|
|
|
|
2016-05-29 01:53:17 +00:00
|
|
|
const char *osmo_fsm_event_name(struct osmo_fsm *fsm, uint32_t event);
|
|
|
|
const char *osmo_fsm_inst_name(struct osmo_fsm_inst *fi);
|
|
|
|
const char *osmo_fsm_state_name(struct osmo_fsm *fsm, uint32_t state);
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! return the name of the state the FSM instance is currently in. */
|
2017-02-28 02:38:38 +00:00
|
|
|
static inline const char *osmo_fsm_inst_state_name(struct osmo_fsm_inst *fi)
|
2019-01-21 23:22:17 +00:00
|
|
|
{ return fi ? osmo_fsm_state_name(fi->fsm, fi->state) : "NULL"; }
|
2017-02-28 02:38:38 +00:00
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! perform a state change of the given FSM instance
|
fsm: log caller's source for events and state changes, not fsm.c lines
When looking at log output, it is not interesting to see that a state
transition's petty details are implemented in fsm.c. Rather log the *caller's*
source file and line that caused an event, state change and cascading events.
To that end, introduce LOGPSRC() absorbing the guts of LOGP(), to be able to
explicitly pass the source file and line information.
Prepend an underscore to the function names of osmo_fsm_inst_state_chg(),
osmo_fsm_inst_dispatch() and osmo_fsm_inst_term(), and add file and line
arguments to them. Provide the previous names as macros that insert the
caller's __BASE_FILE__ and __LINE__ constants for the new arguments. Hence no
calling code needs to be changed.
In fsm.c, add LOGPFSMSRC to call LOGPSRC, and add LOGPFSMLSRC, and use them in
above _osmo_fsm_inst_* functions.
In addition, in _osmo_fsm_inst_term(), pass the caller's source file and line
on to nested event dispatches, so showing where a cascade originated from.
Change-Id: Iae72aba7bbf99e19dd584ccabea5867210650dcd
2016-12-14 16:24:54 +00:00
|
|
|
*
|
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
#define osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T) \
|
|
|
|
_osmo_fsm_inst_state_chg(fi, new_state, timeout_secs, T, \
|
2018-08-20 10:33:22 +00:00
|
|
|
__FILE__, __LINE__)
|
fsm: log caller's source for events and state changes, not fsm.c lines
When looking at log output, it is not interesting to see that a state
transition's petty details are implemented in fsm.c. Rather log the *caller's*
source file and line that caused an event, state change and cascading events.
To that end, introduce LOGPSRC() absorbing the guts of LOGP(), to be able to
explicitly pass the source file and line information.
Prepend an underscore to the function names of osmo_fsm_inst_state_chg(),
osmo_fsm_inst_dispatch() and osmo_fsm_inst_term(), and add file and line
arguments to them. Provide the previous names as macros that insert the
caller's __BASE_FILE__ and __LINE__ constants for the new arguments. Hence no
calling code needs to be changed.
In fsm.c, add LOGPFSMSRC to call LOGPSRC, and add LOGPFSMLSRC, and use them in
above _osmo_fsm_inst_* functions.
In addition, in _osmo_fsm_inst_term(), pass the caller's source file and line
on to nested event dispatches, so showing where a cascade originated from.
Change-Id: Iae72aba7bbf99e19dd584ccabea5867210650dcd
2016-12-14 16:24:54 +00:00
|
|
|
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);
|
|
|
|
|
2019-05-18 19:03:55 +00:00
|
|
|
#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);
|
|
|
|
|
2018-05-25 16:20:06 +00:00
|
|
|
/*! 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.
|
|
|
|
*/
|
|
|
|
#define osmo_fsm_inst_state_chg_keep_timer(fi, new_state) \
|
|
|
|
_osmo_fsm_inst_state_chg_keep_timer(fi, new_state, \
|
2018-08-20 10:33:22 +00:00
|
|
|
__FILE__, __LINE__)
|
2018-05-25 16:20:06 +00:00
|
|
|
int _osmo_fsm_inst_state_chg_keep_timer(struct osmo_fsm_inst *fi, uint32_t new_state,
|
|
|
|
const char *file, int line);
|
|
|
|
|
fsm: add osmo_fsm_inst_state_chg_keep_or_start_timer()
During FSM design for osmo-msc, I noticed that the current behavior that
keep_timer=true doesn't guarantee a running timer can make FSM design a bit
complex, especially when using osmo_tdef for timeout definitions.
A desirable keep_timer=true behavior is one that keeps the previous timer
running, but starts a timer if no timer is running yet.
The simplest example is: a given state repeatedly transitions back to itself,
but wants to set a timeout only on first entering, avoiding to restart the
timeout on re-entering.
Another example is a repeated transition between two or more states, where the
first time we enter this group a timeout should start, but it should not
restart from scratch on every transition.
When using osmo_tdef timeout definitions for this, so far separate meaningless
states have to be introduced that merely set a fixed timeout.
To simplify, add osmo_fsm_inst_state_chg_keep_or_start_timer(), and use this in
osmo_tdef_fsm_inst_state_chg() when both keep_timer == true *and* T != 0.
In tdef_test.ok, the changes show that on first entering state L, the previous
T=1 is now kept with a large remaining timeout. When entering state L from O,
where no timer was running, this time L's T123 is started.
Change-Id: Id647511a4b18e0c4de0e66fb1f35dc9adb9177db
2019-03-06 04:43:23 +00:00
|
|
|
/*! perform a state change while keeping the current timer if running, or starting a timer otherwise.
|
|
|
|
*
|
|
|
|
* This is useful to keep a timeout across several states, but to make sure that some timeout is actually running.
|
|
|
|
*
|
|
|
|
* This is a macro that calls _osmo_fsm_inst_state_chg_keep_or_start_timer() with the given
|
|
|
|
* parameters as well as the caller's source file and line number for logging
|
|
|
|
* purposes. See there for documentation.
|
|
|
|
*/
|
|
|
|
#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);
|
|
|
|
|
2019-05-18 19:03:55 +00:00
|
|
|
#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);
|
|
|
|
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! dispatch an event to an osmocom finite state machine instance
|
fsm: log caller's source for events and state changes, not fsm.c lines
When looking at log output, it is not interesting to see that a state
transition's petty details are implemented in fsm.c. Rather log the *caller's*
source file and line that caused an event, state change and cascading events.
To that end, introduce LOGPSRC() absorbing the guts of LOGP(), to be able to
explicitly pass the source file and line information.
Prepend an underscore to the function names of osmo_fsm_inst_state_chg(),
osmo_fsm_inst_dispatch() and osmo_fsm_inst_term(), and add file and line
arguments to them. Provide the previous names as macros that insert the
caller's __BASE_FILE__ and __LINE__ constants for the new arguments. Hence no
calling code needs to be changed.
In fsm.c, add LOGPFSMSRC to call LOGPSRC, and add LOGPFSMLSRC, and use them in
above _osmo_fsm_inst_* functions.
In addition, in _osmo_fsm_inst_term(), pass the caller's source file and line
on to nested event dispatches, so showing where a cascade originated from.
Change-Id: Iae72aba7bbf99e19dd584ccabea5867210650dcd
2016-12-14 16:24:54 +00:00
|
|
|
*
|
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
#define osmo_fsm_inst_dispatch(fi, event, data) \
|
2018-08-20 10:33:22 +00:00
|
|
|
_osmo_fsm_inst_dispatch(fi, event, data, __FILE__, __LINE__)
|
fsm: log caller's source for events and state changes, not fsm.c lines
When looking at log output, it is not interesting to see that a state
transition's petty details are implemented in fsm.c. Rather log the *caller's*
source file and line that caused an event, state change and cascading events.
To that end, introduce LOGPSRC() absorbing the guts of LOGP(), to be able to
explicitly pass the source file and line information.
Prepend an underscore to the function names of osmo_fsm_inst_state_chg(),
osmo_fsm_inst_dispatch() and osmo_fsm_inst_term(), and add file and line
arguments to them. Provide the previous names as macros that insert the
caller's __BASE_FILE__ and __LINE__ constants for the new arguments. Hence no
calling code needs to be changed.
In fsm.c, add LOGPFSMSRC to call LOGPSRC, and add LOGPFSMLSRC, and use them in
above _osmo_fsm_inst_* functions.
In addition, in _osmo_fsm_inst_term(), pass the caller's source file and line
on to nested event dispatches, so showing where a cascade originated from.
Change-Id: Iae72aba7bbf99e19dd584ccabea5867210650dcd
2016-12-14 16:24:54 +00:00
|
|
|
int _osmo_fsm_inst_dispatch(struct osmo_fsm_inst *fi, uint32_t event, void *data,
|
|
|
|
const char *file, int line);
|
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! Terminate FSM instance with given cause
|
fsm: log caller's source for events and state changes, not fsm.c lines
When looking at log output, it is not interesting to see that a state
transition's petty details are implemented in fsm.c. Rather log the *caller's*
source file and line that caused an event, state change and cascading events.
To that end, introduce LOGPSRC() absorbing the guts of LOGP(), to be able to
explicitly pass the source file and line information.
Prepend an underscore to the function names of osmo_fsm_inst_state_chg(),
osmo_fsm_inst_dispatch() and osmo_fsm_inst_term(), and add file and line
arguments to them. Provide the previous names as macros that insert the
caller's __BASE_FILE__ and __LINE__ constants for the new arguments. Hence no
calling code needs to be changed.
In fsm.c, add LOGPFSMSRC to call LOGPSRC, and add LOGPFSMLSRC, and use them in
above _osmo_fsm_inst_* functions.
In addition, in _osmo_fsm_inst_term(), pass the caller's source file and line
on to nested event dispatches, so showing where a cascade originated from.
Change-Id: Iae72aba7bbf99e19dd584ccabea5867210650dcd
2016-12-14 16:24:54 +00:00
|
|
|
*
|
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
#define osmo_fsm_inst_term(fi, cause, data) \
|
2018-08-20 10:33:22 +00:00
|
|
|
_osmo_fsm_inst_term(fi, cause, data, __FILE__, __LINE__)
|
fsm: log caller's source for events and state changes, not fsm.c lines
When looking at log output, it is not interesting to see that a state
transition's petty details are implemented in fsm.c. Rather log the *caller's*
source file and line that caused an event, state change and cascading events.
To that end, introduce LOGPSRC() absorbing the guts of LOGP(), to be able to
explicitly pass the source file and line information.
Prepend an underscore to the function names of osmo_fsm_inst_state_chg(),
osmo_fsm_inst_dispatch() and osmo_fsm_inst_term(), and add file and line
arguments to them. Provide the previous names as macros that insert the
caller's __BASE_FILE__ and __LINE__ constants for the new arguments. Hence no
calling code needs to be changed.
In fsm.c, add LOGPFSMSRC to call LOGPSRC, and add LOGPFSMLSRC, and use them in
above _osmo_fsm_inst_* functions.
In addition, in _osmo_fsm_inst_term(), pass the caller's source file and line
on to nested event dispatches, so showing where a cascade originated from.
Change-Id: Iae72aba7bbf99e19dd584ccabea5867210650dcd
2016-12-14 16:24:54 +00:00
|
|
|
void _osmo_fsm_inst_term(struct osmo_fsm_inst *fi,
|
|
|
|
enum osmo_fsm_term_cause cause, void *data,
|
|
|
|
const char *file, int line);
|
2016-05-29 01:53:17 +00:00
|
|
|
|
2017-06-19 22:17:59 +00:00
|
|
|
/*! Terminate all child FSM instances of an FSM instance.
|
fsm: factor out osmo_fsm_inst_term_children() from osmo_fsm_inst_term()
osmo_fsm_inst_term() has code for safe child removal, publish that part as
osmo_fsm_inst_term_children(); also use from osmo_fsm_inst_term().
As with osmo_fsm_inst_term(), add osmo_fsm_inst_term_children() macro to pass
the caller's source file and line to new _osmo_fsm_inst_term_children().
Rationale: in openbsc's VLR, I want to discard child FSMs when certain events
are handled. I could keep a pointer to each one, or simply iterate all
children, making the code a lot simpler in some places.
(Unfortunately, the patch may be displayed subobtimally. This really only moves
the children-loop to a new function, replaces it with a call to
_osmo_fsm_inst_term_children(fi, OSMO_FSM_TERM_PARENT, NULL, file, line) and
drops two local iterator variables. No other code changes are made, even though
the diff may show large removal + addition chunks)
Change-Id: I8dac1206259cbd251660f793ad023aaa1dc705a2
2016-12-23 03:26:39 +00:00
|
|
|
*
|
|
|
|
* 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.
|
|
|
|
*/
|
|
|
|
#define osmo_fsm_inst_term_children(fi, cause, data) \
|
2018-08-20 10:33:22 +00:00
|
|
|
_osmo_fsm_inst_term_children(fi, cause, data, __FILE__, __LINE__)
|
fsm: factor out osmo_fsm_inst_term_children() from osmo_fsm_inst_term()
osmo_fsm_inst_term() has code for safe child removal, publish that part as
osmo_fsm_inst_term_children(); also use from osmo_fsm_inst_term().
As with osmo_fsm_inst_term(), add osmo_fsm_inst_term_children() macro to pass
the caller's source file and line to new _osmo_fsm_inst_term_children().
Rationale: in openbsc's VLR, I want to discard child FSMs when certain events
are handled. I could keep a pointer to each one, or simply iterate all
children, making the code a lot simpler in some places.
(Unfortunately, the patch may be displayed subobtimally. This really only moves
the children-loop to a new function, replaces it with a call to
_osmo_fsm_inst_term_children(fi, OSMO_FSM_TERM_PARENT, NULL, file, line) and
drops two local iterator variables. No other code changes are made, even though
the diff may show large removal + addition chunks)
Change-Id: I8dac1206259cbd251660f793ad023aaa1dc705a2
2016-12-23 03:26:39 +00:00
|
|
|
void _osmo_fsm_inst_term_children(struct osmo_fsm_inst *fi,
|
|
|
|
enum osmo_fsm_term_cause cause,
|
|
|
|
void *data,
|
|
|
|
const char *file, int line);
|
|
|
|
|
2016-05-29 01:53:17 +00:00
|
|
|
/*! @} */
|