
/****************************************************************
 * USER DOCUMENTATION	*		SOCKET CONNEXION	*
 ****************************************************************
 * Date: 15/04/02	*	Author: SP  Pragmadev		*
 * Doc ver: 1.0		*	RTDS VER: 1.1			*
 ****************************************************************
 *			*					*
 *	SOURCE FILES	*		HEADER FILES		*
 ****************************************************************
 *	RTDS_MAIN	*	RTDS_POSIX_TYPES.H		*
 *	RTDS_OS		*	RTDS_TYPES.H			*
 *	RTDS_POSIX	*	RTDS_OS.H			*
 *			*	RTDS_OS_BASIC.H			*
 ****************************************************************/

/******************************************************************
 *		    External program connection
 *****************************************************************/



This feature allows sending SDL message, timer message or changing the system timer from an
external program. In order to do so a TCP Client could be started by C program (see compiler
option in the user manual). At the present time only data from server to client are allowed. 

The TCP client source code (RTDS_TCP_CLIENT.c /RTDS_TCP_CLIENT.h) are available for any
user optimization or adaptation (files are located in the code based directory).

When running a C program, the client is started in a dedicated thread and will wait for a command
to process. The TCP client understand three different commands: M to send SDL message, T
to force timer and C to change system clock.


Data transfers
--------------
All commands sent to the TCP client are started by a key letter (that define command) followed
by commands parameter and ended by a end of transmission character (EOT).
When command requires several parameters each parameter is delimited by a separator
 (OxOA:\n) that will indicate the end of each data block to read. When all data are transmitted the command
is ended by the delimiter: 'S\n' that will indicate the end of transmission (EOT).

* Server side:
-> send command
-> send all require information (commands parameter)
-> send the end of transmission delimiter 'S\n'

* Client side:
-> wait for a command
-> interpret and process all parameters
-> execute specific procedure or function

When receiving data, the client will first read the command (that will be the first value) and then
wait for other data (parameters). When command is received the client enter in a state machine
that will allow the client to knows exactly which type of data will be next received.
TCP clients socket port is defined at compilation time using macro declaration
RTDS_SOCKET_PORT (more information are available in the User manual).

Sending SDL Message
-------------------
This command allows to send SDL message from external program.

* Server side (external program)
The first data to send is the command:'M' followed by information related to the message
to send. For sending message all the following informations are required:
- data1 = Signal Number (long)
- data2 = Size of message data (long)
- data3 = Data (char *)
- data4 = Receiver QueueId (QueueId)
- data5 = Sender QueueId (QueueId)

* Client side (C program)
TCP client state machine:
-> wait for the 'M' command
-> receive all required message information
-> get the message unique IDallocate memory for message data to send
-> call RTDS_SimulatorMsgQueueSend (define in RTDS_OS.c)

* Exemple:
For sending message 'HELLO WORLD' from ProcessA(QueueId=0x02547) to ProcessB
(QueueId=0x02687), we will first assume that 'HELLO WORD' signal number is 1 (all
signal number are defined by RTDS code generator and available in the RTDS_Gen.h
file).
For sending this message server program will just write the following data on socket:
M\n 1\n     11\n 48454C4C4F20574F524C44\n 0x02687\n 0x02547\n  S\n
cmd Number Size     message data           receiver sender     EOT
With '48454C4C4F20574F524C44' the hexadecimal representation of the message data to send 
('HELLO WORLD').

Forcing timer to overruns
-------------------------
This command allows to send the timer's message from external program and require two parameters.
* Server side (external program)
The command to send is T\n followed by the following timers information:
- data1 = process Id that owns the timer (RTDS_processId)
- data2 = timer number (int):
- Client side (C program)
TCP client state machine:
- wait for 'T' command
- receive Process Id
- receive timer number
- send timer message using RTDS_forceTimer function (defined in RTDS_OS.c)

* Exemple:
Forcing timerA, owned by ProcessA (Process Id: 0x03547) to overruns. We first assume
that timer number is 1 (all timer number are defined by RTDS code generator and available
in the RTDS_Gen.h file). To do so the server program will write on socket the following
data:
T\n 0x01564\n   1\n         S\n
cmd Process ID Timer_number EOT

Changing system time
--------------------
This feature allow to change system time value: used for example when forcing timer to overruns.
* Server side (external program)
The command to send is C\n followed by the new clock value

Information required:
- data1 = New clock value (int):
- Client side (C program)

TCP client state machine
-> wait for 'C' command
-> receive time value
-> send timer message using RTDS_Profile_tickSet function (defined in
RTDS_POSIX.c)

* Exemple:
To set system clock to 1000 server program will just write on socket the following data:
 C\n   10000\n
 cmd Clock value
