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

3 files changed, 14 insertions, 4 deletions

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)"