The api documentation of osmo_fsm_state_name() refers to an FSM
instance, but it really means the state of an FSM.
Change-Id: I88ddd6048426d380c49170e66f57b3843398c046
The FSM allows to set individual action callback functions for each
state but it does not allow to leave the action callback pointer
unpopulated. However, there are cornercases where having no callback
function is desirable.
- Check if action callback is popolated before executing it.
Change-Id: I36d221c973d3890721ef1d376fb9be82c4311378
In the osmo-msc, I would like to set the subscr conn FSM identifier by a string
format, to include the type of Complete Layer 3 that is taking place. I could
each time talloc a string and free it again. This API is more convenient.
From osmo_fsm_inst_update_id(), call osmo_fsm_inst_update_id_f() with "%s" (or
pass NULL).
Put the name updating into separate static update_name() function to clarify.
Adjust the error message for erratic ID: don't say "allocate", it might be from
an update. Adjust test expectation.
Change-Id: I76743a7642f2449fd33350691ac8ebbf4400371d
On erratic id in osmo_fsm_inst_update_id(), don't say "Attempting to allocate
FSM instance".
Escape the invalid id using osmo_quote_str().
Change-Id: I770fc460de21faa42b403f694e853e8da01c4bef
Since alloc relies on osmo_fsm_inst_update_id() to set the name, never skip
that.
In osmo_fsm_inst_alloc(), we allow passing a NULL id, and in
osmo_fsm_inst_update_id(), we set the name without id if id is NULL.
Change-Id: I6d6b09a811b82770818f19b189a57d9fc4a8133b
strcmp() *must not* be passed NULL pointers, or we hit:
../../../src/libosmocore/src/fsm.c:123:8: runtime error: null pointer passed as argument 2, which is declared to never be null
ASAN:DEADLYSIGNAL
(Or, alternatively, a segfault.)
If any of the search string or an FSM instance's name string should be NULL,
simply never match.
Technically, an FSM should never have a NULL name, but a current bug actually
allows this (pass NULL id to alloc), which will be addressed by an upcoming
patch. To test for it, we need to first make sure this here doesn't segfault.
Change-Id: I2e5f82c06d1a4727bd93e955366e3b62b2df1b32
If the name stays the same the log messages will still log with the old
id. Since we can now change the id we need to update the name as well.
NULL as id was allowed before so we should allow that as well.
Change-Id: I6b01eb10b8a05fee3e4a5cdefdcf3ce9f79545b4
Event names are displayed in VTY commands so all FSM should have them.
Print an error message if an FSM is registered without event names.
We could also return an error code, however at present no caller checks
the return value of osmo_fsm_register() so this would be pointless.
Add event names to the test FSM and update expected output accordingly.
Change-Id: I08b100d62b5c50bf025ef87d31ea39072539cf37
Related: OS#3008
The function _osmo_fsm_inst_term() terminates all child FSMs befor
it calls fi->fsm_cleanup(). This prevents the cleanup callback to
perform last actions on the child FSMs (e.g.
osmo_fsm_inst_unlink_parent()).
- Since moving the cleanup callack to the beginning of the function
would alter the termination behavior and possibly cause malfunction
in already existing implementation that use OSMO fsm, a new
optional callback that is called immediately at the beginning of
the terminatopn process is added.
Change-Id: I0fdda9fe994753f975a658c0f3fb3615949cc8bb
Closes: OS#2915
Sometimes we want to create an FSM instance before we know its name. In
that case we should be able to update the id later.
Change-Id: Ic216e5b11d4440f8e106a297714f4f06c1152945
This reverts commit 5ec91980ac.
More or less like I expected, it creates fall-out. osmo-msc master builds are failing, as are the open build service builds. The patch has therefor *not* been sufficiently tested.
Change-Id: I8d961d7bbd91b6a8d7691f24cb67720c3d001c7e
The function _osmo_fsm_inst_term() terminates all child FSMs befor
it calls fi->fsm_cleanup(). This prevnts the cleanup callback to
perform last actions on the child FSMs (e.g.
osmo_fsm_inst_unlink_parent()).
move the function call to _osmo_fsm_inst_term_children() below the
call to fi->fsm->cleanup().
Change-Id: Ie89d435417306c6bf897274eabc3ed0a46485c26
At the moment it is not possible to unlink a child from from
its parent, nor is it possible to assign a new parent to a
child FSM.
- osmo_fsm_inst_unlink_parent():
Make it possible to unlink childs from a parent.
- osmo_fsm_inst_change_parent():
Make it possible to change the parent of a child.
Change-Id: I6d18cbd4ada903cf3720b3ad2a89fc643085beef
llist_del(&fi->proc.child) is executed always, regardless whether
a parent is configured or not. This may lead into a double llist_del
when the child has been previously unlinked.
- check if fi->proc.parent is set, and only then execute
llist_del(&fi->proc.child);
Change-Id: I4b33d508c8a11b72fbf30125088a882894d9e6ac
When calling the timer_cb, that may have effected an fi termination and
deallocation, e.g. from dispatching events and/or complex choices made.
Current timer_cb implementations expect T to reflect the fired timer number, so
we can't actually set T=0 before calling the timer_cb.
Instead, never reset T to zero, let it always reflect the timer that last
fired. When a new timer starts, T will be set to its new value.
Adding a T arg to the timer_cb() would have been the cleanest solution, so that
fi->T can be set to zero before dispatching the timer_cb. But since we've
already rolled out this FSM API, we should stay backwards compatible.
In the case where the timer returned 1 to request termination, we can assume
that the fi still exists, but to be consistent, don't set T = 0 in that code
path either.
Change-Id: I18626b55a1491098b3ed602df1b331f08d25625a
Let's fix some erroneous/accidential references to wrong license,
update copyright information where applicable and introduce a
SPDX-License-Identifier to all files.
Change-Id: I39af26c6aaaf5c926966391f6565fc5936be21af
Let's enforce that the names of FSMs and their instances are valid
osmocom identifiers. This is important as the FSMs are automatically
exported via those names on the CTRL inteface, and we have to make sure
CTRL syntax actually permits them.
Change-Id: I9ef59432f43a3cdb94e4cbb0c44ac3f9b2aac0f2
Considering the various styles and implications found in the sources, edit
scores of files to follow the same API doc guidelines around the doxygen
grouping and the \file tag.
Many files now show a short description in the generated API doc that was so
far only available as C comment.
The guidelines and reasoning behind it is documented at
https://osmocom.org/projects/cellular-infrastructure/wiki/Guidelines_for_API_documentation
In some instances, remove file comments and add to the corresponding group
instead, to be shared among several files (e.g. bitvec).
Change-Id: Ifa70e77e90462b5eb2b0457c70fd25275910c72b
Especially for short descriptions, it is annoying to have to type \brief for
every single API doc.
Drop all \brief and enable the AUTOBRIEF feature of doxygen, which always takes
the first sentence of an API doc as the brief description.
Change-Id: I11a8a821b065a128108641a2a63fb5a2b1916e87
It's a pity that even with this patch we still are fare away from having
the whole API documented. However, at least we have a more solid
foundation. Updates not only extend the documentation, but also make
sure it is rendered properly in the doxygen HTML.
Change-Id: I1344bd1a6869fb00de7c1899a8db93bba9bafce3
Add a new function timer function to set up the timer, similar to what
we have in the Linux kernel. This patch also converts existing opencoded
timer setup in the libosmocore tree as initial client of this new
function.
This patch implicitly removes function callback passed by reference that
defeat compile time type validation.
Compile-tested only, but I ran make check that reports success when
testing timer infrastructure.
Change-Id: I2fa49972ecaab3748b25168b26d92034e9145666
If the user starts the FSM timer with a given timer number during
fsm_inst_state_chg() with a timeout, we should remove that "T" number
after timer expiration. Otherwise it might be confusing if e.g. the VTY
interface shows FSM instances with a certain timer number assigned, but
that timer is not actually running anymore.
Change-Id: I71167ec1000dc4c6954d851d3b92f6bf12984925
Introduce two lookup helper functions to resolve a fsm_instance based on
the FSM and name or ID. Also, add related test cases.
Change-Id: I707f3ed2795c28a924e64adc612d378c21baa815
This addresses a FIXME in the fsm.c code: osmo_fsm_register() should
fail in case a FSM with the given name already exists.
Change-Id: I5fd882939859c79581eba70c14cbafd64560b583
During FSM instance termination, fetch the parent pointer every time just
before using it, in case the child termination or cleanup callback wish to
change anything about the parent, e.g. to prevent event dispatch.
This patch was created to try and fix a problem that was in the end solved
differently. There is no actual need or use case for this at the moment, but it
generally makes sense to get the parent pointer as late as possible.
Change-Id: I999d7f29ba10281d4005c5163130bb2d80148362
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
LOGPFSM and LOGPFSML are in the header file, put the *SRC variants also there
so users of the osmo_fsm_inst API may conveniently create own functions that
log the caller's source file and line.
Very useful if many action functions call the same event dispatching function,
like foo_fsm_done(), and one needs to know which of the callers to debug.
Change-Id: I39447b1d15237b28f88d8c5f08d82c764679dc80
Logging 'Release' is a bit ambiguous. At first I tought a subscriber
connection was being released, IMHO 'Freeing instance' better describes that
we are freeing an osmo_fsm_inst.
Change-Id: I5cf99707d2ba5620b2988f777fa39cc806ec0212
OSMO_STRINGIFY particularly allows putting port numbers from a #define into VTY
doc strings, like:
#define FOO_PORT 2342
DEFUN(...,
"Foo UDP port (default: " OSMO_STRINGIFY(FOO_PORT) ")\n")
OSMO_VALUE_STRING creates value_string items with the string being exactly the
enum value's name. Replaces a similar macro def in fsm.c
Change-Id: I857af45ae602bb9a647ba26cf8b0d1b23403b54c
When terminating child FSMs, restart iteration after every child, to make
sure that we don't terminate a child twice. Terminating one child may emit
events that in turn terminates other children.
I created this patch because at first it looked like the cause of a bug,
which turned out not to be the case. So I have no actual use case of this
situation, but it does generally make sense to me, so submitting this.
Change-Id: I00990b47e42eeb43707a9a42abcd9df52fe5f483
Since removing an FSM from its parent twice causes a segfault, it is very
interesting to see when that is attempted.
Removing could be made more robust, but logging is interesting for
investigating why an FSM is being removed twice in the first place (currently
the case in openbsc's vlr_lu_fsm).
Change-Id: Idec6b7aa5344f1e903c9d2aa2a3640cab0d70fb0
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
Provide one central LOGPFSML to print FSM information, take the FSM logging
subsystem from the FSM instance but use an explicitly provided log level
instead of the FSM's default level.
Use to replace some, essentially, duplications of the LOGPFSM macro.
In effect, the fsm_test's expected error changes, since the previous code dup
for logging events used round braces to indicate the fi's state, while the
central macro uses curly braces.
Change-Id: If295fdabb3f31a0fd9490d1e0df57794c75ae547
osmo_fsm_inst_alloc() logs allocation but osmo_fsm_inst_free() is
silent. Fix this by adding log message for deallocation to make FSM
lifecycle tracking easier. Also make sure it's covered by test suite.
Change-Id: I7e5b55a1fff8e36cf61c7fb61d3e79c1f00e29d2
In osmo_fsm_inst_state_chg(), we need to stop any not-yet-expired timer
of the old state before transitioning into the new state.
Change-Id: I2558f9a7027a877ea8263785ed3c8d70d2513996
The 'id' is used to generate the human-readable name of the FSM.
However, when the FSM creates slave FSMs later, the caller-passed "ID"
mgiht long be gone again (e.g. it was on stack memory). So let's copy
the 'id' string to a chunk of dynamically-allocated memory at time of
FSM start to ensure we have it later when creating child FSMs.
Change-Id: Ib88a2c02c5c91f17b4ec1e9db57a06d6d66465fb
If a FSM doesn't specify any timer_cb, simply terminate the FSM by
default on time-out. This is a reasonable default for most cases, and
avoids copy+pasting a one-line timer_cb function in every FSM.
Also, even if there is a timer_cb, let it have a return value to decide
if the core should terminate after return from timer_cb or not.
Change-Id: I0461a9593bfb729c82b7d1d1cf9f30b1079d0212
This code is supposed to formalize some of the state machine handling in
Osmocom code.
Change-Id: I0b0965a912598c1f6b84042a99fea9d522642466
Reviewed-on: https://gerrit.osmocom.org/163
Tested-by: Jenkins Builder
Reviewed-by: Harald Welte <laforge@gnumonks.org>
Philipp Maier
Neels Hofmeyr
Daniel Willmann
Harald Welte
Neels Hofmeyr
Pau Espin