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

1 files changed, 38 insertions, 17 deletions

diff --git a/tests/tdef/tdef_vty_test_config_subnode.vty b/tests/tdef/tdef_vty_test_config_subnode.vty
index 50e5f590..2605f71d 100644
--- a/tests/tdef/tdef_vty_test_config_subnode.vty
+++ b/tests/tdef/tdef_vty_test_config_subnode.vty
@@ -4,7 +4,7 @@ tdef_vty_test> list
 ... !timer
 
 tdef_vty_test> show timer ?
-  [TNNNN]  T-number, optionally preceded by 't' or 'T'.
+  [TNNNN]  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'.
 
 tdef_vty_test> show timer
 T1 = 100 s	Testing a hundred seconds (default: 100 s)
@@ -12,7 +12,7 @@ T2 = 100 ms	Testing a hundred milliseconds (default: 100 ms)
 T3 = 100 m	Testing a hundred minutes (default: 100 m)
 T4 = 100	Testing a hundred potatoes (default: 100)
 T2147483647 = 4294967295 m	Very large (default: 4294967295 m)
-T-23 = 239471 s	Negative T number (default: 239471 s)
+X23 = 239471 s	Negative T number (default: 239471 s)
 
 tdef_vty_test> enable
 tdef_vty_test# show timer
@@ -21,7 +21,7 @@ T2 = 100 ms	Testing a hundred milliseconds (default: 100 ms)
 T3 = 100 m	Testing a hundred minutes (default: 100 m)
 T4 = 100	Testing a hundred potatoes (default: 100)
 T2147483647 = 4294967295 m	Very large (default: 4294967295 m)
-T-23 = 239471 s	Negative T number (default: 239471 s)
+X23 = 239471 s	Negative T number (default: 239471 s)
 
 tdef_vty_test# configure terminal
 tdef_vty_test(config)# show running-config
@@ -35,7 +35,7 @@ T2 = 100 ms	Testing a hundred milliseconds (default: 100 ms)
 T3 = 100 m	Testing a hundred minutes (default: 100 m)
 T4 = 100	Testing a hundred potatoes (default: 100)
 T2147483647 = 4294967295 m	Very large (default: 4294967295 m)
-T-23 = 239471 s	Negative T number (default: 239471 s)
+X23 = 239471 s	Negative T number (default: 239471 s)
 
 tdef_vty_test(config-net)# do show timer T3
 T3 = 100 m	Testing a hundred minutes (default: 100 m)
@@ -73,17 +73,13 @@ tdef_vty_test(config-net)# timer 666
 tdef_vty_test(config-net)# timer T666 5
 % No such timer: T666
 
-tdef_vty_test(config-net)# timer T-23 42
-tdef_vty_test(config-net)# timer T-23
-T-23 = 42 s	Negative T number (default: 239471 s)
-
-tdef_vty_test(config-net)# timer t-23 43
-tdef_vty_test(config-net)# timer T-23
-T-23 = 43 s	Negative T number (default: 239471 s)
+tdef_vty_test(config-net)# timer X23 42
+tdef_vty_test(config-net)# timer X23
+X23 = 42 s	Negative T number (default: 239471 s)
 
-tdef_vty_test(config-net)# timer -23 44
-tdef_vty_test(config-net)# timer T-23
-T-23 = 44 s	Negative T number (default: 239471 s)
+tdef_vty_test(config-net)# timer x23 43
+tdef_vty_test(config-net)# timer x23
+X23 = 43 s	Negative T number (default: 239471 s)
 
 tdef_vty_test(config-net)# do show timer
 T1 = 9012345 s	Testing a hundred seconds (default: 100 s)
@@ -91,17 +87,42 @@ T2 = 100 ms	Testing a hundred milliseconds (default: 100 ms)
 T3 = 100 m	Testing a hundred minutes (default: 100 m)
 T4 = 100	Testing a hundred potatoes (default: 100)
 T2147483647 = 4294967295 m	Very large (default: 4294967295 m)
-T-23 = 44 s	Negative T number (default: 239471 s)
+X23 = 43 s	Negative T number (default: 239471 s)
+
+tdef_vty_test(config-net)# timer T-23 42
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 'T-23'
+tdef_vty_test(config-net)# timer T-23
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 'T-23'
+
+tdef_vty_test(config-net)# timer t-23 42
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 't-23'
+tdef_vty_test(config-net)# timer t-23
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 't-23'
+
+tdef_vty_test(config-net)# timer X-23 42
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 'X-23'
+tdef_vty_test(config-net)# timer X-23
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 'X-23'
+
+tdef_vty_test(config-net)# timer x-23 42
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 'x-23'
+tdef_vty_test(config-net)# timer x-23
+% Invalid T timer argument (should be 'T1234' or 'X1234'): 'x-23'
+
+tdef_vty_test(config-net)# timer -23 42
+% Invalid T timer argument (should be 'T1234' or 'X1234'): '-23'
+tdef_vty_test(config-net)# timer -23
+% Invalid T timer argument (should be 'T1234' or 'X1234'): '-23'
 
 tdef_vty_test(config-net)# show running-config
 ... !timer
 net
  timer T1 9012345
- timer T-23 44
+ timer X23 43
 ... !timer
 
 tdef_vty_test(config-net)# timer T1 default
-tdef_vty_test(config-net)# timer T-23 default
+tdef_vty_test(config-net)# timer X23 default
 
 tdef_vty_test(config-net)# show running-config
 ... !timer