Documented real-time features in reference and API guides (bug 539514)

Change-Id: I96240a75de3ce0816b615e6b7e39cc11d77ebcbb
Signed-off-by: Botond Baranyi <botond.baranyi@ericsson.com>

usrguide/apiguide/2-test_ports.adoc

@@ -175,7 +175,7 @@ void MyMessagePort::outgoing_send(const CHARSTRING& send_par)
 } /* end of namespace */
 ----
 
-=== Procedure-based Example
+== Procedure-based Example
 
 The definition of `MyProcedurePort` in module `MyModule`:
 [source]
@@ -912,3 +912,55 @@ There is another function for denoting warnings (that is, events that are not so
 void TTCN_warning(const char *warning_msg, …);
 
 This function puts an entry in the executor’s log with severity `TTCN_WARNING`. In contrast to `TTCN_error`, after logging the given message `TTCN_warning` returns and your test port can continue running.
+
+== Setting timestamps
+
+In order to use the timestamp redirects (`-> timestamp`) described in chapter 5 of the TTCN-3 standard extension `TTCN-3 Performance and Real Time Testing` (ETSI ES 202 782 V1.3.1, <<7-references.adoc#_16, [16]>>) the test port writer needs to add extra code to set the timestamps for the incoming and outgoing port operations of each port with the `realtime` clause.
+
+=== Incoming operations
+
+The timestamps of incoming port operations (`receive`, `trigger`, `getcall`, `getreply`, `catch` and `check`) need to be set when the incoming message or procedure is added to the queue.
+
+The member functions `incoming_message`, `incoming_call`, `incoming_reply` and `incoming_exception` (which add the message/procedure to the queue) have an optional `float` parameter called `timestamp`, if the test port was declared with the `realtime` clause.
+
+The value given to this parameter will be the one stored in the variable referenced in the timestamp redirect, if the operation has a timestamp redirect (otherwise the value is ignored).
+
+It is recommended that this parameter be set to the current test system time, which can be querried with `TTCN_Runtime::now()`, or to a float variable that was set to the current test system time earier in the function.
+
+Examples:
+[source]
+----
+incoming_message(my_message, TTCN_Runtime::now());
+----
+
+[source]
+----
+FLOAT reply_time = TTCN_Runtime::now();
+
+...
+
+incoming_reply(my_reply, reply_time);
+----
+
+=== Outgoing operations
+
+The timestamps of outgoing port operations (`send`, `call`, `reply`, `raise`) need to be set in the member functions `outgoing_send`, `outgoing_call`, `outgoing_reply` and `outgoing_raise`.
+
+These functions have a `float` pointer parameter called `timestamp_redirect`, if the test port was declared with the `realtime` clause.
+
+The value pointed to by this parameter will be the one stored in the variable referenced in the timestamp redirect, if the operation has a timestamp redirect.
+
+If it does not have a timestamp redirect, then this pointer parameter will be `NULL`. Because of this, the parameter must always have a null pointer check before it is assigned a value.
+
+It is recommended that the value pointed to by the parameter be set to the current test system time, which can be querried with `TTCN_Runtime::now()`.
+
+Example:
+[source]
+----
+if (timestamp_redirect != NULL) {
+  *timestamp_redirect = TTCN_Runtime::now();
+}
+----
+
+Note: Because of this extra parameter, adding or removing the `realtime` clause from a port will cause already-written C++ code for the port to no longer compile. In these cases the new parameters must be manually added or removed from the mentioned functions, or the user-written code copied to newly-generated test port skeletons.
+

usrguide/apiguide/7-references.adoc

@@ -29,3 +29,5 @@
 14. link:http://tldp.org/HOWTO/Program-Library-HOWTO/index.html[David A. Wheeler, Program Library HOWTO]
 
 15. link:https://www.etsi.org/deliver/etsi_es/202700_202799/202781/01.04.01_60/es_202781v010401p.pdf[ETSI ES 202 781 V1.4.1. (2015-06 Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3; TTCN-3 Language Extensions: Configuration and Deployment Support)]
+[[_16]]
+16. link:https://www.etsi.org/deliver/etsi_es/202700_202799/202782/01.03.01_60/es_202782v010301p.pdf[ETSI ES 202 782 V1.3.1. (2015-06 Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3; TTCN-3 Language Extensions: TTCN-3 Performance and Real Time Testing)]

usrguide/referenceguide/13-references.adoc

@@ -74,3 +74,6 @@
 
 [[_25]]
 * [25] link:https://www.etsi.org/deliver/etsi_es/201800_201899/20187311/04.07.01_60/es_20187311v040701p.pdf[Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3. Part 11: Using JSON with TTCN–3 European Telecommunications Standards Institute. ES 201 873-11 Version 4.7.1, June 2017]
+
+[[_26]]
+* [26] link:https://www.etsi.org/deliver/etsi_es/202700_202799/202782/01.03.01_60/es_202782v010301p.pdf[ETSI ES 202 782 V1.3.1. (2015-06 Methods for Testing and Specification (MTS); The Testing and Test Control Notation version 3; TTCN-3 Language Extensions: TTCN-3 Performance and Real Time Testing)]

usrguide/referenceguide/4-ttcn3_language_extensions.adoc

@@ -8757,3 +8757,92 @@ The translation logic of receiving is analogous to the translation logic of send
 The testing of some protocols requires the necessity to be able to send and receive during the execution of a translation function. This can be achieved using the `port.send()` and `port.receive()` statements in a translation function. This is only possible if the translation function has a port clause. The statements will be executed on the port instance which the execution of the translation function belongs to. The send and receive statements in a translation function should be used with caution as they can easily create an infinite loop.
 
 For example when a `port.send()` statement is executed in a translation function, the same translation function could be called automatically because the same translation procedure will be executed on the parameter of the send statement. The handling of these situations can be resolved using module parameters or port parameters.
+
+
+== Real-time testing features
+
+TITAN supports the real-time testing features described in chapter 5 of the TTCN-3 standard extension `TTCN-3 Performance and Real Time Testing` (ETSI ES 202 782 V1.3.1, <<13-references.adoc#_26, [26]>>) with the differences and limitations described in this section.
+
+* The real-time testing features are disabled by default. They can be activated with the compiler command line option `-I`.
+* The `stepsize` setting is not supported. The symbol `now` always returns the current test system time with microsecond precision (i.e. 6 decimal precision).
+* While the compiler allows timestamp redirects (`-> timestamp`) to be used in all situations indicated by the standard, they only store a valid timestamp if one was stored in the user-defined port's C++ code (as specified in the API guide, <<13-references.adoc#_16, [16]>>). Timestamp redirects on connected (internal) ports don't do anything, and the referenced variable remains unchanged (see example below).
+* Timestamp redirects also work on ports in translation mode, as long as both the translation port type and the provider port type have the `realtime` clause. Timestamp redirects can also be used inside translation functions (i.e. the `port.send` and `port.receive` statements can also have timestamp redirects).
+* The `wait` statement is not supported.
+
+Example:
+[source]
+----
+type port PT message realtime {
+  inout integer
+}
+
+type port PT_Internal message realtime {
+  inout integer
+}
+with {
+  extension "internal"
+}
+
+type component CT {
+  port PT pt;
+  port PT_Internal pt_int;
+}
+
+// timestamp redirects on a mapped user-defined port
+testcase tc() runs on CT {
+  map(self:pt, system:pt);
+  
+  var float time_start := now, time_send, time_receive;
+  
+  pt.send(1) -> timestamp time_send;
+  // time_send is set in the user-defined code of port type PT
+  if (time_send - time_start > 1.0) {
+    setverdict(fail);
+  }
+  
+  alt {
+    [] pt.receive(integer: ?) -> timestamp time_receive {
+      // time_receive is set in the user-defined code of port type PT
+      if (time_receive - time_send > 10.0) {
+        setverdict(fail);
+      }
+    }
+  }
+}
+
+// timestamp redirects on a connected internal port
+testcase tc2() runs on CT {
+  connect(self:pt, self:pt);
+  
+  var float time_start := now, time_send, time_receive;
+  
+  pt_int.send(1) -> timestamp time_send;
+  // time_send is unbound
+  
+  alt {
+    [] pt.receive(integer: ?) -> timestamp time_receive {
+      // time_receive is unbound
+    }
+  }
+}
+----
+
+In order for the timestamp redirects to work on port type `PT`, the following need to be set in the port type's C++ code:
+
+* The value pointed to by parameter `timestamp_redirect` in function `PT::outgoing_send` needs to be set to the current test system time (this sets the timestamps for `send` operations on the port).
+* The optional `timestamp` parameter of function `PT_BASE::incoming_message` needs to be set to the current test system time, when it is called (this sets the timestamps for `receive`, `trigger` and `check` operations on the port).
+
+For example:
+[source]
+----
+void PT::outgoing_send(const INTEGER& send_par, FLOAT* timestamp_redirect)
+{
+  if (timestamp_redirect != NULL) {
+    *timestamp_redirect = TTCN_Runtime::now();
+  }
+  
+  // the message is redirected to the port's input
+  incoming_message(send_par, TTCN_Runtime::now());
+}
+----
+