diff options
Diffstat (limited to 'include/osmocom/core/tdef.h')
| -rw-r--r-- | include/osmocom/core/tdef.h | 172 |
1 files changed, 172 insertions, 0 deletions
diff --git a/include/osmocom/core/tdef.h b/include/osmocom/core/tdef.h new file mode 100644 index 00000000..92b71597 --- /dev/null +++ b/include/osmocom/core/tdef.h @@ -0,0 +1,172 @@ +/*! \file tdef.h + * API to define Tnnn timers globally and use for FSM state changes. + */ +/* + * (C) 2018-2019 by sysmocom - s.f.m.c. GmbH <info@sysmocom.de> + * + * All Rights Reserved + * + * SPDX-License-Identifier: GPL-2.0+ + * + * Author: Neels Hofmeyr <neels@hofmeyr.de> + * + * This program is free software; you can redistribute it and/or modify + * it under the terms of the GNU Affero General Public License as published by + * the Free Software Foundation; either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU Affero General Public License for more details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see <http://www.gnu.org/licenses/>. + */ +#pragma once + +#include <stdint.h> +#include <osmocom/core/utils.h> + +struct osmo_fsm_inst; + +/*! \defgroup Tdef Tnnn timer configuration + * @{ + * \file tdef.h + */ + +enum osmo_tdef_unit { + OSMO_TDEF_S = 0, /*!< most T are in seconds, keep 0 as default. */ + OSMO_TDEF_MS, /*!< milliseconds */ + OSMO_TDEF_M, /*!< minutes */ + OSMO_TDEF_CUSTOM, /*!< unspecified unit, explained in osmo_tdef.desc. */ +}; + +extern const struct value_string osmo_tdef_unit_names[]; +/*! \return enum osmo_tdef_unit value as human readable unit letter, or "custom-unit". */ +static inline const char *osmo_tdef_unit_name(enum osmo_tdef_unit val) +{ return get_value_string(osmo_tdef_unit_names, val); } + +/*! Define a GSM timer of the form Tnnn, with unit, default value and doc string. + * Typically used as an array with the last entry being left zero-initialized, e.g.: + * + * struct osmo_tdef tdefs[] = { + * { .T=10, .default_val=6, .desc="RR Assignment" }, + * { .T=101, .default_val=10, .desc="inter-BSC Handover MT, HO Request to HO Accept" }, + * { .T=3101, .default_val=3, .desc="RR Immediate Assignment" }, + * {} + * }; + * + * Program initialization should call osmo_tdefs_reset() so that all timers return the default_val, until e.g. the VTY + * configuration sets user-defined values (see osmo_tdef_vty_init()). + */ +struct osmo_tdef { + /*! T1234 number; type corresponds to struct osmo_fsm_inst.T. Negative and zero T numbers are actually possible, + * but be aware that osmo_tdef_fsm_inst_state_chg() interprets T == 0 as "no timer". */ + const int T; + /*! Timeout duration (according to unit), default value; type corresponds to osmo_fsm_inst_state_chg()'s + * timeout_secs argument. Note that osmo_fsm_inst_state_chg() clamps the range. */ + const unsigned long default_val; + const enum osmo_tdef_unit unit; + /*! Human readable description. For unit == OSMO_TDEF_CUSTOM, this should include an explanation of the value's + * unit. Best keep this a short one-liner (e.g. for VTY output). */ + const char *desc; + /*! Currently active timeout value, e.g. set by user config. This is the only mutable member: a user may + * configure the timeout value, but neither unit nor any other field. */ + unsigned long val; +}; + +/*! Iterate an array of struct osmo_tdef, the last item should be fully zero, i.e. "{}". + * Example: + * + * struct osmo_tdef *t; + * osmo_tdef_for_each(t, tdefs) { + * printf("%lu %s %s\n", t->val, osmo_tdef_unit_name(t->unit), t->desc); + * } + * + * \param[inout] t A struct osmo_tdef *t used for iteration, will point at the current entry inside the loop scope. + * \param[in] tdefs Array of struct osmo_tdef to iterate, zero-terminated. + */ +#define osmo_tdef_for_each(t, tdefs) \ + for (t = tdefs; t && (t->T || t->default_val || t->desc); t++) + +void osmo_tdefs_reset(struct osmo_tdef *tdefs); +unsigned long osmo_tdef_get(const struct osmo_tdef *tdefs, int T, enum osmo_tdef_unit as_unit, + unsigned long val_if_not_present); +struct osmo_tdef *osmo_tdef_get_entry(struct osmo_tdef *tdefs, int T); + +/*! Using osmo_tdef for osmo_fsm_inst: array entry for a mapping of state numbers to timeout definitions. + * For a usage example, see osmo_tdef_get_state_timeout() and test_tdef_state_timeout() in tdef_test.c. */ +struct osmo_tdef_state_timeout { + /*! Timer number to match struct osmo_tdef.T, and to pass to osmo_fsm_inst_state_chg(). */ + int T; + /*! If true, call osmo_fsm_inst_state_chg_keep_timer(). + * If T == 0, keep previous T number, otherwise also set fi->T. */ + bool keep_timer; +}; + +const struct osmo_tdef_state_timeout *osmo_tdef_get_state_timeout(uint32_t state, + const struct osmo_tdef_state_timeout *timeouts_array); + +/*! Call osmo_fsm_inst_state_chg() or osmo_fsm_inst_state_chg_keep_timer(), depending on the timeouts_array, tdefs and + * default_timeout. + * + * A T timer configured in sub-second precision is rounded up to the next full second. A timer in unit = + * OSMO_TDEF_CUSTOM is applied as if the unit is in seconds (i.e. this macro does not make sense for custom units!). + * + * See osmo_tdef_get_state_timeout() and osmo_tdef_get(). + * + * If no T timer is defined for the given state (T == 0), invoke the state change without a timeout. + * + * Should a T number be defined in timeouts_array that is not defined in tdefs, use default_timeout (in seconds). If + * default_timeout is negative, a missing T definition in tdefs instead causes a program abort. + * + * This is best used by wrapping this function call in a macro suitable for a specific FSM implementation, which can + * become as short as: my_fsm_state_chg(fi, NEXT_STATE): + * + * #define my_fsm_state_chg(fi, NEXT_STATE) \ + * osmo_tdef_fsm_inst_state_chg(fi, NEXT_STATE, my_fsm_timeouts, global_T_defs, 5) + * + * my_fsm_state_chg(fi, MY_FSM_STATE_1); + * // -> No timeout configured, will enter state without timeout. + * + * my_fsm_state_chg(fi, MY_FSM_STATE_3); + * // T423 configured for this state, will look up T423 in tdefs, or use 5 seconds if unset. + * + * my_fsm_state_chg(fi, MY_FSM_STATE_8); + * // keep_timer == true for this state, will invoke osmo_fsm_inst_state_chg_keep_timer(). + * + * \param[inout] fi osmo_fsm_inst to transition to another state. + * \param[in] state State number to transition to. + * \param[in] timeouts_array Array of struct osmo_tdef_state_timeout[32] to look up state in. + * \param[in] tdefs Array of struct osmo_tdef (last entry zero initialized) to look up T in. + * \param[in] default_timeout If a T is set in timeouts_array, but no timeout value is configured for T, then use this + * default timeout value as fallback, or pass -1 to abort the program. + * \return Return value from osmo_fsm_inst_state_chg() or osmo_fsm_inst_state_chg_keep_timer(). + */ +#define osmo_tdef_fsm_inst_state_chg(fi, state, timeouts_array, tdefs, default_timeout) \ + _osmo_tdef_fsm_inst_state_chg(fi, state, timeouts_array, tdefs, default_timeout, \ + __FILE__, __LINE__) +int _osmo_tdef_fsm_inst_state_chg(struct osmo_fsm_inst *fi, uint32_t state, + const struct osmo_tdef_state_timeout *timeouts_array, + const struct osmo_tdef *tdefs, unsigned long default_timeout, + const char *file, int line); + +/*! Manage timer definitions in named groups. + * This should be defined as an array with the final element kept fully zero-initialized, + * to be compatible with osmo_tdef_vty* API. There must not be any tdefs == NULL entries except on the final + * zero-initialized entry. */ +struct osmo_tdef_group { + const char *name; + const char *desc; + struct osmo_tdef *tdefs; +}; + +/*! Iterate an array of struct osmo_tdef_group, the last item should be fully zero, i.e. "{}". + * \param[inout] g A struct osmo_tdef_group *g used for iteration, will point at the current entry inside the loop scope. + * \param[in] tdefs Array of struct osmo_tdef_group to iterate, zero-terminated. + */ +#define osmo_tdef_groups_for_each(g, tdef_groups) \ + for (g = tdef_groups; g && g->tdefs; g++) + +/*! @} */ |