Neels Hofmeyr | 17518fe | 2017-06-20 04:35:06 +0200 | [diff] [blame] | 1 | /*! \file fsm.c |
| 2 | * Osmocom generic Finite State Machine implementation. */ |
| 3 | /* |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 4 | * (C) 2016 by Harald Welte <laforge@gnumonks.org> |
| 5 | * |
Harald Welte | e08da97 | 2017-11-13 01:00:26 +0900 | [diff] [blame] | 6 | * SPDX-License-Identifier: GPL-2.0+ |
| 7 | * |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 8 | * This program is free software; you can redistribute it and/or modify |
| 9 | * it under the terms of the GNU General Public License as published by |
| 10 | * the Free Software Foundation; either version 2 of the License, or |
| 11 | * (at your option) any later version. |
| 12 | * |
| 13 | * This program is distributed in the hope that it will be useful, |
| 14 | * but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 15 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 16 | * GNU General Public License for more details. |
| 17 | * |
| 18 | * You should have received a copy of the GNU General Public License |
| 19 | * along with this program; if not, write to the Free Software |
| 20 | * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, |
| 21 | * MA 02110-1301, USA. |
| 22 | */ |
| 23 | |
| 24 | #include <errno.h> |
| 25 | #include <stdbool.h> |
Harald Welte | 8808bb4 | 2017-01-07 11:11:03 +0100 | [diff] [blame] | 26 | #include <string.h> |
Pau Espin Pedrol | 4f8857e | 2017-06-18 12:23:00 +0200 | [diff] [blame] | 27 | #include <inttypes.h> |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 28 | |
| 29 | #include <osmocom/core/fsm.h> |
| 30 | #include <osmocom/core/talloc.h> |
| 31 | #include <osmocom/core/logging.h> |
| 32 | #include <osmocom/core/utils.h> |
| 33 | |
| 34 | /*! \addtogroup fsm |
| 35 | * @{ |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 36 | * Finite State Machine abstraction |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 37 | * |
| 38 | * This is a generic C-language abstraction for implementing finite |
| 39 | * state machines within the Osmocom framework. It is intended to |
| 40 | * replace existing hand-coded or even only implicitly existing FSMs |
| 41 | * all over the existing code base. |
| 42 | * |
| 43 | * An libosmocore FSM is described by its \ref osmo_fsm description, |
| 44 | * which in turn refers to an array of \ref osmo_fsm_state descriptor, |
| 45 | * each describing a single state in the FSM. |
| 46 | * |
| 47 | * The general idea is that all actions performed within one state are |
| 48 | * located at one position in the code (the state's action function), |
| 49 | * as opposed to the 'message-centric' view of e.g. the existing |
| 50 | * state machines of the LAPD(m) coe, where there is one message for |
| 51 | * eahc possible event (primitive), and the function then needs to |
| 52 | * concern itself on how to handle that event over all possible states. |
| 53 | * |
| 54 | * For each state, there is a bit-mask of permitted input events for |
| 55 | * this state, as well as a bit-mask of permitted new output states to |
| 56 | * which the state can change. Furthermore, there is a function |
| 57 | * pointer implementing the actual handling of the input events |
| 58 | * occurring whilst in thta state. |
| 59 | * |
| 60 | * Furthermore, each state offers a function pointer that can be |
| 61 | * executed just before leaving a state, and another one just after |
| 62 | * entering a state. |
| 63 | * |
| 64 | * When transitioning into a new state, an optional timer number and |
| 65 | * time-out can be passed along. The timer is started just after |
| 66 | * entering the new state, and will call the \ref osmo_fsm timer_cb |
| 67 | * function once it expires. This is intended to be used in telecom |
| 68 | * state machines where a given timer (identified by a certain number) |
| 69 | * is started to terminate the fsm or terminate the fsm once expected |
| 70 | * events are not happening before timeout expiration. |
| 71 | * |
| 72 | * As there can often be many concurrent FSMs of one given class, we |
| 73 | * introduce the concept of \ref osmo_fsm_inst, i.e. an FSM instance. |
| 74 | * The instance keeps the actual state, while the \ref osmo_fsm |
| 75 | * descriptor contains the static/const descriptor of the FSM's states |
| 76 | * and possible transitions. |
| 77 | * |
| 78 | * osmo_fsm are integrated with the libosmocore logging system. The |
| 79 | * logging sub-system is determined by the FSM descriptor, as we assume |
| 80 | * one FSM (let's say one related to a location update procedure) is |
| 81 | * inevitably always tied to a sub-system. The logging level however |
| 82 | * is configurable for each FSM instance, to ensure that e.g. DEBUG |
| 83 | * logging can be used for the LU procedure of one subscriber, while |
| 84 | * NOTICE level is used for all other subscribers. |
| 85 | * |
| 86 | * In order to attach private state to the \ref osmo_fsm_inst, it |
| 87 | * offers an opaque priv pointer. |
Neels Hofmeyr | 17518fe | 2017-06-20 04:35:06 +0200 | [diff] [blame] | 88 | * |
| 89 | * \file fsm.c */ |
Harald Welte | 96e2a00 | 2017-06-12 21:44:18 +0200 | [diff] [blame] | 90 | |
Harald Welte | 3419391 | 2017-01-07 11:49:55 +0100 | [diff] [blame] | 91 | LLIST_HEAD(osmo_g_fsms); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 92 | static bool fsm_log_addr = true; |
| 93 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 94 | /*! specify if FSM instance addresses should be logged or not |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 95 | * |
| 96 | * By default, the FSM name includes the pointer address of the \ref |
Neels Hofmeyr | a3953e0 | 2016-12-14 18:34:30 +0100 | [diff] [blame] | 97 | * osmo_fsm_inst. This behavior can be disabled (and re-enabled) |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 98 | * using this function. |
| 99 | * |
| 100 | * \param[in] log_addr Indicate if FSM instance address shall be logged |
| 101 | */ |
| 102 | void osmo_fsm_log_addr(bool log_addr) |
| 103 | { |
Max | 61281f4 | 2016-11-01 10:49:31 +0100 | [diff] [blame] | 104 | fsm_log_addr = log_addr; |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 105 | } |
| 106 | |
Harald Welte | 8808bb4 | 2017-01-07 11:11:03 +0100 | [diff] [blame] | 107 | struct osmo_fsm *osmo_fsm_find_by_name(const char *name) |
| 108 | { |
| 109 | struct osmo_fsm *fsm; |
Harald Welte | 3419391 | 2017-01-07 11:49:55 +0100 | [diff] [blame] | 110 | llist_for_each_entry(fsm, &osmo_g_fsms, list) { |
Harald Welte | 8808bb4 | 2017-01-07 11:11:03 +0100 | [diff] [blame] | 111 | if (!strcmp(name, fsm->name)) |
| 112 | return fsm; |
| 113 | } |
| 114 | return NULL; |
| 115 | } |
| 116 | |
Harald Welte | 4585e67 | 2017-04-16 17:23:56 +0200 | [diff] [blame] | 117 | struct osmo_fsm_inst *osmo_fsm_inst_find_by_name(const struct osmo_fsm *fsm, |
| 118 | const char *name) |
| 119 | { |
| 120 | struct osmo_fsm_inst *fi; |
| 121 | |
| 122 | llist_for_each_entry(fi, &fsm->instances, list) { |
| 123 | if (!strcmp(name, fi->name)) |
| 124 | return fi; |
| 125 | } |
| 126 | return NULL; |
| 127 | } |
| 128 | |
| 129 | struct osmo_fsm_inst *osmo_fsm_inst_find_by_id(const struct osmo_fsm *fsm, |
| 130 | const char *id) |
| 131 | { |
| 132 | struct osmo_fsm_inst *fi; |
| 133 | |
| 134 | llist_for_each_entry(fi, &fsm->instances, list) { |
| 135 | if (!strcmp(id, fi->id)) |
| 136 | return fi; |
| 137 | } |
| 138 | return NULL; |
| 139 | } |
| 140 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 141 | /*! register a FSM with the core |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 142 | * |
| 143 | * A FSM descriptor needs to be registered with the core before any |
| 144 | * instances can be created for it. |
| 145 | * |
| 146 | * \param[in] fsm Descriptor of Finite State Machine to be registered |
| 147 | * \returns 0 on success; negative on error |
| 148 | */ |
| 149 | int osmo_fsm_register(struct osmo_fsm *fsm) |
| 150 | { |
Harald Welte | 8c4f545 | 2017-10-03 17:44:03 +0800 | [diff] [blame] | 151 | if (!osmo_identifier_valid(fsm->name)) { |
| 152 | LOGP(DLGLOBAL, LOGL_ERROR, "Attempting to register FSM with illegal identifier '%s'\n", fsm->name); |
| 153 | return -EINVAL; |
| 154 | } |
Harald Welte | 8808bb4 | 2017-01-07 11:11:03 +0100 | [diff] [blame] | 155 | if (osmo_fsm_find_by_name(fsm->name)) |
| 156 | return -EEXIST; |
Harald Welte | 3419391 | 2017-01-07 11:49:55 +0100 | [diff] [blame] | 157 | llist_add_tail(&fsm->list, &osmo_g_fsms); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 158 | INIT_LLIST_HEAD(&fsm->instances); |
| 159 | |
| 160 | return 0; |
| 161 | } |
| 162 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 163 | /*! unregister a FSM from the core |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 164 | * |
| 165 | * Once the FSM descriptor is unregistered, active instances can still |
| 166 | * use it, but no new instances may be created for it. |
| 167 | * |
| 168 | * \param[in] fsm Descriptor of Finite State Machine to be removed |
| 169 | */ |
| 170 | void osmo_fsm_unregister(struct osmo_fsm *fsm) |
| 171 | { |
| 172 | llist_del(&fsm->list); |
| 173 | } |
| 174 | |
| 175 | /* small wrapper function around timer expiration (for logging) */ |
| 176 | static void fsm_tmr_cb(void *data) |
| 177 | { |
| 178 | struct osmo_fsm_inst *fi = data; |
| 179 | struct osmo_fsm *fsm = fi->fsm; |
Harald Welte | f627c0f | 2016-06-18 10:36:25 +0200 | [diff] [blame] | 180 | uint32_t T = fi->T; |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 181 | |
| 182 | LOGPFSM(fi, "Timeout of T%u\n", fi->T); |
| 183 | |
Harald Welte | f627c0f | 2016-06-18 10:36:25 +0200 | [diff] [blame] | 184 | if (fsm->timer_cb) { |
| 185 | int rc = fsm->timer_cb(fi); |
Neels Hofmeyr | 19ec7b9 | 2017-11-18 23:10:24 +0100 | [diff] [blame] | 186 | if (rc != 1) |
| 187 | /* We don't actually know whether fi exists anymore. |
| 188 | * Make sure to not access it and return right away. */ |
Harald Welte | f627c0f | 2016-06-18 10:36:25 +0200 | [diff] [blame] | 189 | return; |
Neels Hofmeyr | 19ec7b9 | 2017-11-18 23:10:24 +0100 | [diff] [blame] | 190 | /* The timer_cb told us to terminate, so we can safely assume |
| 191 | * that fi still exists. */ |
Harald Welte | f627c0f | 2016-06-18 10:36:25 +0200 | [diff] [blame] | 192 | LOGPFSM(fi, "timer_cb requested termination\n"); |
| 193 | } else |
| 194 | LOGPFSM(fi, "No timer_cb, automatic termination\n"); |
| 195 | |
| 196 | /* if timer_cb returns 1 or there is no timer_cb */ |
| 197 | osmo_fsm_inst_term(fi, OSMO_FSM_TERM_TIMEOUT, &T); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 198 | } |
| 199 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 200 | /*! allocate a new instance of a specified FSM |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 201 | * \param[in] fsm Descriptor of the FSM |
| 202 | * \param[in] ctx talloc context from which to allocate memory |
| 203 | * \param[in] priv private data reference store in fsm instance |
| 204 | * \param[in] log_level The log level for events of this FSM |
| 205 | * \returns newly-allocated, initialized and registered FSM instance |
| 206 | */ |
| 207 | struct osmo_fsm_inst *osmo_fsm_inst_alloc(struct osmo_fsm *fsm, void *ctx, void *priv, |
| 208 | int log_level, const char *id) |
| 209 | { |
| 210 | struct osmo_fsm_inst *fi = talloc_zero(ctx, struct osmo_fsm_inst); |
| 211 | |
| 212 | fi->fsm = fsm; |
| 213 | fi->priv = priv; |
| 214 | fi->log_level = log_level; |
Pablo Neira Ayuso | 44f423f | 2017-05-08 18:00:28 +0200 | [diff] [blame] | 215 | osmo_timer_setup(&fi->timer, fsm_tmr_cb, fi); |
Harald Welte | 8c4f545 | 2017-10-03 17:44:03 +0800 | [diff] [blame] | 216 | if (id) { |
| 217 | if (!osmo_identifier_valid(id)) { |
| 218 | LOGP(DLGLOBAL, LOGL_ERROR, "Attempting to allocate FSM instance of type '%s'" |
| 219 | " with illegal identifier '%s'\n", fsm->name, id); |
| 220 | talloc_free(fi); |
| 221 | return NULL; |
| 222 | } |
Harald Welte | f323911 | 2016-07-10 15:11:45 +0200 | [diff] [blame] | 223 | fi->id = talloc_strdup(fi, id); |
Harald Welte | 8c4f545 | 2017-10-03 17:44:03 +0800 | [diff] [blame] | 224 | } |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 225 | |
| 226 | if (!fsm_log_addr) { |
| 227 | if (id) |
| 228 | fi->name = talloc_asprintf(fi, "%s(%s)", fsm->name, id); |
| 229 | else |
| 230 | fi->name = talloc_asprintf(fi, "%s", fsm->name); |
| 231 | } else { |
| 232 | if (id) |
| 233 | fi->name = talloc_asprintf(fi, "%s(%s)[%p]", fsm->name, |
| 234 | id, fi); |
| 235 | else |
| 236 | fi->name = talloc_asprintf(fi, "%s[%p]", fsm->name, fi); |
| 237 | } |
| 238 | |
| 239 | INIT_LLIST_HEAD(&fi->proc.children); |
| 240 | INIT_LLIST_HEAD(&fi->proc.child); |
| 241 | llist_add(&fi->list, &fsm->instances); |
| 242 | |
| 243 | LOGPFSM(fi, "Allocated\n"); |
| 244 | |
| 245 | return fi; |
| 246 | } |
| 247 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 248 | /*! allocate a new instance of a specified FSM as child of |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 249 | * other FSM instance |
| 250 | * |
| 251 | * This is like \ref osmo_fsm_inst_alloc but using the parent FSM as |
| 252 | * talloc context, and inheriting the log level of the parent. |
| 253 | * |
| 254 | * \param[in] fsm Descriptor of the to-be-allocated FSM |
| 255 | * \param[in] parent Parent FSM instance |
| 256 | * \param[in] parent_term_event Event to be sent to parent when terminating |
| 257 | * \returns newly-allocated, initialized and registered FSM instance |
| 258 | */ |
| 259 | struct osmo_fsm_inst *osmo_fsm_inst_alloc_child(struct osmo_fsm *fsm, |
| 260 | struct osmo_fsm_inst *parent, |
| 261 | uint32_t parent_term_event) |
| 262 | { |
| 263 | struct osmo_fsm_inst *fi; |
| 264 | |
| 265 | fi = osmo_fsm_inst_alloc(fsm, parent, NULL, parent->log_level, |
| 266 | parent->id); |
| 267 | if (!fi) { |
| 268 | /* indicate immediate termination to caller */ |
| 269 | osmo_fsm_inst_dispatch(parent, parent_term_event, NULL); |
| 270 | return NULL; |
| 271 | } |
| 272 | |
| 273 | LOGPFSM(fi, "is child of %s\n", osmo_fsm_inst_name(parent)); |
| 274 | |
| 275 | fi->proc.parent = parent; |
| 276 | fi->proc.parent_term_event = parent_term_event; |
| 277 | llist_add(&fi->proc.child, &parent->proc.children); |
| 278 | |
| 279 | return fi; |
| 280 | } |
| 281 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 282 | /*! delete a given instance of a FSM |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 283 | * \param[in] fsm The FSM to be un-registered and deleted |
| 284 | */ |
| 285 | void osmo_fsm_inst_free(struct osmo_fsm_inst *fi) |
| 286 | { |
Max | 3de97e1 | 2016-11-02 10:37:58 +0100 | [diff] [blame] | 287 | LOGPFSM(fi, "Deallocated\n"); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 288 | osmo_timer_del(&fi->timer); |
| 289 | llist_del(&fi->list); |
| 290 | talloc_free(fi); |
| 291 | } |
| 292 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 293 | /*! get human-readable name of FSM event |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 294 | * \param[in] fsm FSM descriptor of event |
| 295 | * \param[in] event Event integer value |
| 296 | * \returns string rendering of the event |
| 297 | */ |
| 298 | const char *osmo_fsm_event_name(struct osmo_fsm *fsm, uint32_t event) |
| 299 | { |
| 300 | static char buf[32]; |
| 301 | if (!fsm->event_names) { |
Pau Espin Pedrol | 4f8857e | 2017-06-18 12:23:00 +0200 | [diff] [blame] | 302 | snprintf(buf, sizeof(buf), "%"PRIu32, event); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 303 | return buf; |
| 304 | } else |
| 305 | return get_value_string(fsm->event_names, event); |
| 306 | } |
| 307 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 308 | /*! get human-readable name of FSM instance |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 309 | * \param[in] fi FSM instance |
| 310 | * \returns string rendering of the FSM identity |
| 311 | */ |
| 312 | const char *osmo_fsm_inst_name(struct osmo_fsm_inst *fi) |
| 313 | { |
| 314 | if (!fi) |
| 315 | return "NULL"; |
| 316 | |
| 317 | if (fi->name) |
| 318 | return fi->name; |
| 319 | else |
| 320 | return fi->fsm->name; |
| 321 | } |
| 322 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 323 | /*! get human-readable name of FSM instance |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 324 | * \param[in] fsm FSM descriptor |
| 325 | * \param[in] state FSM state number |
| 326 | * \returns string rendering of the FSM state |
| 327 | */ |
| 328 | const char *osmo_fsm_state_name(struct osmo_fsm *fsm, uint32_t state) |
| 329 | { |
| 330 | static char buf[32]; |
| 331 | if (state >= fsm->num_states) { |
Pau Espin Pedrol | 4f8857e | 2017-06-18 12:23:00 +0200 | [diff] [blame] | 332 | snprintf(buf, sizeof(buf), "unknown %"PRIu32, state); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 333 | return buf; |
| 334 | } else |
| 335 | return fsm->states[state].name; |
| 336 | } |
| 337 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 338 | /*! perform a state change of the given FSM instance |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 339 | * |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 340 | * Best invoke via the osmo_fsm_inst_state_chg() macro which logs the source |
| 341 | * file where the state change was effected. Alternatively, you may pass \a |
| 342 | * file as NULL to use the normal file/line indication instead. |
| 343 | * |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 344 | * All changes to the FSM instance state must be made via this |
| 345 | * function. It verifies that the existing state actually permits a |
| 346 | * transiiton to new_state. |
| 347 | * |
| 348 | * timeout_secs and T are optional parameters, and only have any effect |
| 349 | * if timeout_secs is not 0. If the timeout function is used, then the |
| 350 | * new_state is entered, and the FSM instances timer is set to expire |
| 351 | * in timeout_secs functions. At that time, the FSM's timer_cb |
| 352 | * function will be called for handling of the timeout by the user. |
| 353 | * |
| 354 | * \param[in] fi FSM instance whose state is to change |
| 355 | * \param[in] new_state The new state into which we should change |
| 356 | * \param[in] timeout_secs Timeout in seconds (if !=0) |
| 357 | * \param[in] T Timer number (if \ref timeout_secs != 0) |
Neels Hofmeyr | b805cc1 | 2016-12-23 04:23:18 +0100 | [diff] [blame] | 358 | * \param[in] file Calling source file (from osmo_fsm_inst_state_chg macro) |
| 359 | * \param[in] line Calling source line (from osmo_fsm_inst_state_chg macro) |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 360 | * \returns 0 on success; negative on error |
| 361 | */ |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 362 | int _osmo_fsm_inst_state_chg(struct osmo_fsm_inst *fi, uint32_t new_state, |
| 363 | unsigned long timeout_secs, int T, |
| 364 | const char *file, int line) |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 365 | { |
| 366 | struct osmo_fsm *fsm = fi->fsm; |
| 367 | uint32_t old_state = fi->state; |
| 368 | const struct osmo_fsm_state *st = &fsm->states[fi->state]; |
| 369 | |
| 370 | /* validate if new_state is a valid state */ |
| 371 | if (!(st->out_state_mask & (1 << new_state))) { |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 372 | LOGPFSMLSRC(fi, LOGL_ERROR, file, line, |
| 373 | "transition to state %s not permitted!\n", |
| 374 | osmo_fsm_state_name(fsm, new_state)); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 375 | return -EPERM; |
| 376 | } |
| 377 | |
Harald Welte | 02a6672 | 2016-07-10 15:13:51 +0200 | [diff] [blame] | 378 | /* delete the old timer */ |
| 379 | osmo_timer_del(&fi->timer); |
| 380 | |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 381 | if (st->onleave) |
| 382 | st->onleave(fi, new_state); |
| 383 | |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 384 | LOGPFSMSRC(fi, file, line, "state_chg to %s\n", |
| 385 | osmo_fsm_state_name(fsm, new_state)); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 386 | fi->state = new_state; |
Harald Welte | 460f9ef | 2016-08-01 00:38:36 +0200 | [diff] [blame] | 387 | st = &fsm->states[new_state]; |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 388 | |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 389 | if (timeout_secs) { |
Harald Welte | f627c0f | 2016-06-18 10:36:25 +0200 | [diff] [blame] | 390 | fi->T = T; |
| 391 | osmo_timer_schedule(&fi->timer, timeout_secs, 0); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 392 | } |
| 393 | |
Harald Welte | 673018f | 2016-07-10 15:09:43 +0200 | [diff] [blame] | 394 | /* Call 'onenter' last, user might terminate FSM from there */ |
| 395 | if (st->onenter) |
| 396 | st->onenter(fi, old_state); |
| 397 | |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 398 | return 0; |
| 399 | } |
| 400 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 401 | /*! dispatch an event to an osmocom finite state machine instance |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 402 | * |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 403 | * Best invoke via the osmo_fsm_inst_dispatch() macro which logs the source |
| 404 | * file where the event was effected. Alternatively, you may pass \a file as |
| 405 | * NULL to use the normal file/line indication instead. |
| 406 | * |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 407 | * Any incoming events to \ref osmo_fsm instances must be dispatched to |
| 408 | * them via this function. It verifies, whether the event is permitted |
| 409 | * based on the current state of the FSM. If not, -1 is returned. |
| 410 | * |
| 411 | * \param[in] fi FSM instance |
| 412 | * \param[in] event Event to send to FSM instance |
| 413 | * \param[in] data Data to pass along with the event |
Neels Hofmeyr | b805cc1 | 2016-12-23 04:23:18 +0100 | [diff] [blame] | 414 | * \param[in] file Calling source file (from osmo_fsm_inst_dispatch macro) |
| 415 | * \param[in] line Calling source line (from osmo_fsm_inst_dispatch macro) |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 416 | * \returns 0 in case of success; negative on error |
| 417 | */ |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 418 | int _osmo_fsm_inst_dispatch(struct osmo_fsm_inst *fi, uint32_t event, void *data, |
| 419 | const char *file, int line) |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 420 | { |
| 421 | struct osmo_fsm *fsm; |
| 422 | const struct osmo_fsm_state *fs; |
| 423 | |
| 424 | if (!fi) { |
Neels Hofmeyr | c7155df | 2016-12-23 04:24:51 +0100 | [diff] [blame] | 425 | LOGPSRC(DLGLOBAL, LOGL_ERROR, file, line, |
Pau Espin Pedrol | 4f8857e | 2017-06-18 12:23:00 +0200 | [diff] [blame] | 426 | "Trying to dispatch event %"PRIu32" to non-existent" |
Neels Hofmeyr | c7155df | 2016-12-23 04:24:51 +0100 | [diff] [blame] | 427 | " FSM instance!\n", event); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 428 | osmo_log_backtrace(DLGLOBAL, LOGL_ERROR); |
| 429 | return -ENODEV; |
| 430 | } |
| 431 | |
| 432 | fsm = fi->fsm; |
| 433 | OSMO_ASSERT(fi->state < fsm->num_states); |
| 434 | fs = &fi->fsm->states[fi->state]; |
| 435 | |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 436 | LOGPFSMSRC(fi, file, line, |
| 437 | "Received Event %s\n", osmo_fsm_event_name(fsm, event)); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 438 | |
| 439 | if (((1 << event) & fsm->allstate_event_mask) && fsm->allstate_action) { |
| 440 | fsm->allstate_action(fi, event, data); |
| 441 | return 0; |
| 442 | } |
| 443 | |
| 444 | if (!((1 << event) & fs->in_event_mask)) { |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 445 | LOGPFSMLSRC(fi, LOGL_ERROR, file, line, |
| 446 | "Event %s not permitted\n", |
| 447 | osmo_fsm_event_name(fsm, event)); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 448 | return -1; |
| 449 | } |
| 450 | fs->action(fi, event, data); |
| 451 | |
| 452 | return 0; |
| 453 | } |
| 454 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 455 | /*! Terminate FSM instance with given cause |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 456 | * |
| 457 | * This safely terminates the given FSM instance by first iterating |
| 458 | * over all children and sending them a termination event. Next, it |
| 459 | * calls the FSM descriptors cleanup function (if any), followed by |
| 460 | * releasing any memory associated with the FSM instance. |
| 461 | * |
| 462 | * Finally, the parent FSM instance (if any) is notified using the |
| 463 | * parent termination event configured at time of FSM instance start. |
| 464 | * |
| 465 | * \param[in] fi FSM instance to be terminated |
| 466 | * \param[in] cause Cause / reason for termination |
Neels Hofmeyr | b805cc1 | 2016-12-23 04:23:18 +0100 | [diff] [blame] | 467 | * \param[in] data Opaque event data to be passed with the parent term event |
| 468 | * \param[in] file Calling source file (from osmo_fsm_inst_term macro) |
| 469 | * \param[in] line Calling source line (from osmo_fsm_inst_term macro) |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 470 | */ |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 471 | void _osmo_fsm_inst_term(struct osmo_fsm_inst *fi, |
| 472 | enum osmo_fsm_term_cause cause, void *data, |
| 473 | const char *file, int line) |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 474 | { |
Neels Hofmeyr | 3faa014 | 2016-12-18 23:41:41 +0100 | [diff] [blame] | 475 | struct osmo_fsm_inst *parent; |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 476 | uint32_t parent_term_event = fi->proc.parent_term_event; |
| 477 | |
Neels Hofmeyr | 5c5c78a | 2016-12-14 18:35:47 +0100 | [diff] [blame] | 478 | LOGPFSMSRC(fi, file, line, "Terminating (cause = %s)\n", |
| 479 | osmo_fsm_term_cause_name(cause)); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 480 | |
Neels Hofmeyr | c014f60 | 2016-12-23 04:26:39 +0100 | [diff] [blame] | 481 | _osmo_fsm_inst_term_children(fi, OSMO_FSM_TERM_PARENT, NULL, |
| 482 | file, line); |
| 483 | |
| 484 | /* delete ourselves from the parent */ |
Neels Hofmeyr | 3faa014 | 2016-12-18 23:41:41 +0100 | [diff] [blame] | 485 | parent = fi->proc.parent; |
Philipp Maier | 23d3161 | 2018-01-16 18:50:23 +0100 | [diff] [blame] | 486 | if (parent) { |
Neels Hofmeyr | c014f60 | 2016-12-23 04:26:39 +0100 | [diff] [blame] | 487 | LOGPFSMSRC(fi, file, line, "Removing from parent %s\n", |
| 488 | osmo_fsm_inst_name(parent)); |
Philipp Maier | 23d3161 | 2018-01-16 18:50:23 +0100 | [diff] [blame] | 489 | llist_del(&fi->proc.child); |
| 490 | } |
Neels Hofmeyr | c014f60 | 2016-12-23 04:26:39 +0100 | [diff] [blame] | 491 | |
| 492 | /* call destructor / clean-up function */ |
| 493 | if (fi->fsm->cleanup) |
| 494 | fi->fsm->cleanup(fi, cause); |
| 495 | |
| 496 | LOGPFSMSRC(fi, file, line, "Freeing instance\n"); |
Neels Hofmeyr | 3faa014 | 2016-12-18 23:41:41 +0100 | [diff] [blame] | 497 | /* Fetch parent again in case it has changed. */ |
| 498 | parent = fi->proc.parent; |
Neels Hofmeyr | c014f60 | 2016-12-23 04:26:39 +0100 | [diff] [blame] | 499 | osmo_fsm_inst_free(fi); |
| 500 | |
| 501 | /* indicate our termination to the parent */ |
| 502 | if (parent && cause != OSMO_FSM_TERM_PARENT) |
| 503 | _osmo_fsm_inst_dispatch(parent, parent_term_event, data, |
| 504 | file, line); |
| 505 | } |
| 506 | |
Neels Hofmeyr | 87e4550 | 2017-06-20 00:17:59 +0200 | [diff] [blame] | 507 | /*! Terminate all child FSM instances of an FSM instance. |
Neels Hofmeyr | c014f60 | 2016-12-23 04:26:39 +0100 | [diff] [blame] | 508 | * |
| 509 | * Iterate over all children and send them a termination event, with the given |
| 510 | * cause. Pass OSMO_FSM_TERM_PARENT to avoid dispatching events from the |
| 511 | * terminated child FSMs. |
| 512 | * |
| 513 | * \param[in] fi FSM instance that should be cleared of child FSMs |
| 514 | * \param[in] cause Cause / reason for termination (OSMO_FSM_TERM_PARENT) |
| 515 | * \param[in] data Opaque event data to be passed with the parent term events |
| 516 | * \param[in] file Calling source file (from osmo_fsm_inst_term_children macro) |
| 517 | * \param[in] line Calling source line (from osmo_fsm_inst_term_children macro) |
| 518 | */ |
| 519 | void _osmo_fsm_inst_term_children(struct osmo_fsm_inst *fi, |
| 520 | enum osmo_fsm_term_cause cause, |
| 521 | void *data, |
| 522 | const char *file, int line) |
| 523 | { |
| 524 | struct osmo_fsm_inst *first_child, *last_seen_first_child; |
| 525 | |
Neels Hofmeyr | 06ac9b4 | 2016-12-20 12:05:19 +0100 | [diff] [blame] | 526 | /* iterate over all children, starting from the beginning every time: |
| 527 | * terminating an FSM may emit events that cause other FSMs to also |
| 528 | * terminate and remove themselves from this list. */ |
| 529 | last_seen_first_child = NULL; |
| 530 | while (!llist_empty(&fi->proc.children)) { |
| 531 | first_child = llist_entry(fi->proc.children.next, |
| 532 | typeof(*first_child), |
| 533 | proc.child); |
| 534 | |
| 535 | /* paranoia: do not loop forever */ |
| 536 | if (first_child == last_seen_first_child) { |
| 537 | LOGPFSMLSRC(fi, LOGL_ERROR, file, line, |
| 538 | "Internal error while terminating child" |
| 539 | " FSMs: a child FSM is stuck\n"); |
| 540 | break; |
| 541 | } |
| 542 | last_seen_first_child = first_child; |
| 543 | |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 544 | /* terminate child */ |
Neels Hofmeyr | c014f60 | 2016-12-23 04:26:39 +0100 | [diff] [blame] | 545 | _osmo_fsm_inst_term(first_child, cause, data, |
Neels Hofmeyr | 725698a | 2016-12-14 17:24:54 +0100 | [diff] [blame] | 546 | file, line); |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 547 | } |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 548 | } |
| 549 | |
Neels Hofmeyr | 5c5c78a | 2016-12-14 18:35:47 +0100 | [diff] [blame] | 550 | const struct value_string osmo_fsm_term_cause_names[] = { |
Neels Hofmeyr | 1808096 | 2016-12-16 13:43:54 +0100 | [diff] [blame] | 551 | OSMO_VALUE_STRING(OSMO_FSM_TERM_PARENT), |
| 552 | OSMO_VALUE_STRING(OSMO_FSM_TERM_REQUEST), |
| 553 | OSMO_VALUE_STRING(OSMO_FSM_TERM_REGULAR), |
| 554 | OSMO_VALUE_STRING(OSMO_FSM_TERM_ERROR), |
| 555 | OSMO_VALUE_STRING(OSMO_FSM_TERM_TIMEOUT), |
Neels Hofmeyr | 5c5c78a | 2016-12-14 18:35:47 +0100 | [diff] [blame] | 556 | { 0, NULL } |
| 557 | }; |
| 558 | |
Harald Welte | 136e737 | 2016-05-29 10:53:17 +0900 | [diff] [blame] | 559 | /*! @} */ |