From 5734bff3b01da2a7369da07f77ad617c3ac32096 Mon Sep 17 00:00:00 2001 From: Neels Hofmeyr Date: Thu, 21 Feb 2019 02:27:48 +0100 Subject: represent negative T-timers as Osmocom-specific X-timers fi->T values are int, i.e. can be negative. Do not log them as unsigned, but define a distinct timer class "Xnnnn" for negative T values: i.e. for T == -1, print "Timeout of X1" instead of "Timeout of T4294967295". The negative T timer number space is useful to distinguish freely invented timers from proper 3GPP defined T numbers. So far I was using numbers like T993210 or T9999 for invented T, but X1, X2 etc. is a better solution. This way we can make sure to not accidentally define an invented timer number that actually collides with a proper 3GPP specified timer number that the author was not aware of at the time of writing. Add OSMO_T_FMT and OSMO_T_FMT_ARGS() macros as standardized timer number print format. Use that in fsm.c, tdef_vty.c, and adjust vty tests accordingly. Mention the two timer classes in various API docs and VTY online-docs. Change-Id: I3a59457623da9309fbbda235fe18fadd1636bff6 --- include/osmocom/core/fsm.h | 3 +++ include/osmocom/core/tdef.h | 11 ++++++++--- include/osmocom/vty/tdef_vty.h | 4 +++- 3 files changed, 14 insertions(+), 4 deletions(-) (limited to 'include/osmocom') diff --git a/include/osmocom/core/fsm.h b/include/osmocom/core/fsm.h index ae1c8575..13bfb331 100644 --- a/include/osmocom/core/fsm.h +++ b/include/osmocom/core/fsm.h @@ -194,6 +194,9 @@ void osmo_fsm_log_timeouts(bool log_timeouts); 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); diff --git a/include/osmocom/core/tdef.h b/include/osmocom/core/tdef.h index 92b71597..c8d9053d 100644 --- a/include/osmocom/core/tdef.h +++ b/include/osmocom/core/tdef.h @@ -54,6 +54,7 @@ static inline const char *osmo_tdef_unit_name(enum osmo_tdef_unit val) * { .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" }, + * { .T=-23, .default_val=42, .desc="internal X23 timeout (contrived example)" }, * {} * }; * @@ -61,8 +62,10 @@ static inline const char *osmo_tdef_unit_name(enum osmo_tdef_unit val) * 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". */ + /*! T1234 or X1234 number, corresponding to struct osmo_fsm_inst::T. + * Positive values for T are considered to be 3GPP spec compliant and appear in logging and VTY as "T1234", + * while negative values are considered to be Osmocom specific timers, represented in logging and VTY as + * "X1234". Be aware that osmo_tdef_fsm_inst_state_chg() interprets T == 0 as "state without timeout". */ 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. */ @@ -98,7 +101,9 @@ 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(). */ + /*! Timer number to match struct osmo_tdef.T, and to pass to osmo_fsm_inst_state_chg(). Positive values for T + * are considered to be 3GPP spec compliant and appear in logging and VTY as "T1234", while negative values are + * considered to be Osmocom specific timers, represented in logging and VTY as "X1234". */ int T; /*! If true, call osmo_fsm_inst_state_chg_keep_timer(). * If T == 0, keep previous T number, otherwise also set fi->T. */ diff --git a/include/osmocom/vty/tdef_vty.h b/include/osmocom/vty/tdef_vty.h index f55239ad..16d94981 100644 --- a/include/osmocom/vty/tdef_vty.h +++ b/include/osmocom/vty/tdef_vty.h @@ -35,7 +35,9 @@ struct osmo_tdef; struct osmo_tdef_group; #define OSMO_TDEF_VTY_ARG_T "TNNNN" -#define OSMO_TDEF_VTY_DOC_T "T-number, optionally preceded by 't' or 'T'.\n" +#define OSMO_TDEF_VTY_DOC_T \ + "T- or X-timer-number -- 3GPP compliant timer number of the format '1234' or 'T1234' or 't1234';" \ + " Osmocom-specific timer number of the format: 'X1234' or 'x1234'.\n" #define OSMO_TDEF_VTY_ARG_T_OPTIONAL "[" OSMO_TDEF_VTY_ARG_T "]" #define OSMO_TDEF_VTY_ARG_VAL "(<0-2147483647>|default)" -- cgit v1.2.3