//================================================================================================
/*! \file ls.c

This file contains the task ls and related functions. The task ls is responsible
for taking entries out of the two LS_HP_QUEUE, LS_LP_QUEUE fifos, processing them
and sending corresponding commands and hk requests to the instruments via the tx 
register of the low speed serial port. Task ls also gets from the rx register of
the low speed serial port the answers to hk requests (thus coming from LCU or FCU).\n
This file ls.c also contains four functions (write_cmd_hp_queue, write_cmd_lp_queue, 
push_hp_queue, push_lp_queue) that are used by other tasks (especially by task hk_ask) 
to put entries into the fifos LS_HP_QUEUE, LS_LP_QUEUE.

*/

//================================================================================================
/*! \fn int send ( unsigned int * datum )
unsigned int * datum : pointer to the location of memory that holds the command that
must be sent on the low speed interface.\n 

This function checks Irq3_flag to see whether the low speed serial port is reserved 
by the virtual machine: in that case the function returns RC_TIME. Otherwise the 
function SendLss is called.
*/

//================================================================================================
/*! \fn int SendLss( unsigned int *datum )
unsigned int * datum : pointer to the location of memory that holds the command that
must be sent on the low speed interface.\n 

This function writes the data (pointed by the argument unsigned int *datum) into 
the transmission register of the low speed serial port. Before doing that, the 
function checks the least significant bit of the status register of the serial port. 
If the value of this bit is 1 (thus theoretically indicating that the tx register is busy), 
then the bit is changed to zero, the data is written into the transmission register, 
and the value returned by the function is ERR_BUSY_BIT_ASSERTED. Otherwise (the lsb is 0) 
the function returns the value RC_OK after writing the data.  
(note: though required when we use AVM1, the check of the status register could be 
omitted when using AVM2)
*/

//================================================================================================
/*! \fn int GetLss ( unsigned int * datum )
unsigned int * datum : pointer to the location of memory where the data coming from
the low speed interface has to be copied.\n

This function checks a bit in the status register of the serial port in order to 
see if the data is ready to be read. If the data is not ready, the function returns 
RC_FAIL; if the data is ready, the function puts it into the memory location pointed
by the argument datum, and then returns RC_OK.
*/

//================================================================================================
/*! \fn void ls_init(void)
This function resets the semaphore LS_SEMA and purges the two fifos LS_HP_QUEUE,
LS_LP_QUEUE.
*/

//================================================================================================
/*! \fn void ls ( void )
This function waits for the semaphore LS_SEMA to be signalled by a task adding 
entries to one of the fifos LS_HP_QUEUE, LS_LP_QUEUE. When this happens, the function
tries to read a data element from the high priority queue; if this queue is empty, 
then the function turns to the low priority queue to get an entry (if both the fifos 
are empty, an error has occurred, and the generate_event function is called). The 
structure of type LS_CMD_MSG retrieved from one of the fifos is then analysed. 
If the event_number field of that structure matches one of the following types HK_EVENT, 
NP_HK_COMPLETED, then the function goes to the next iteration of the while loop, 
after signalling a corresponding event or sending an appropriate message (this mechanism is used in the function 
hk_prepare_data (see file hk_ask.c) to signal an end-of-transaction).  
If the cmd_add field of the structure doesn't point to a correct command 
(first bit not equal to 1) then the function goes to the next iteration of the 
while loop, after calling the generate_event function. 
The send function is called (as a critical section) in order to have the command 
sent on the low speed bus. As long as this function returns RC_TIME, the ls task
is suspended. In case the critical section has returned ERR_BUSY_BIT_ASSERTED, some 
static variables (N_LS_event, and the array event_par) are conveniently altered, and 
generate_event is called. If the command sent was a housekeeping request, after a
3 msec wait, the hk data are read and put into the right memory location by 
calling the function GetLss (if this function returns RC_FAIL, the err_code field
of the structure is set to 1); if the command wasn't a hk request, nothing is done
but waiting for a specified amount of time. Then the control returns to the test of 
the semaphore LS_SEMA.
*/

//================================================================================================
/*! \fn int write_cmd_hp_queue(unsigned int * cmd, unsigned int ev_num)
unsigned int * cmd : pointer to the location of memory that holds a command: this pointer
must be put (as part of a structure) into the LS_HP_QUEUE.\n 
unsigned int ev_num : value that will be given to the field event_number of the structure to
be put into the LS_HP_QUEUE.\n
This function puts the pointer to a data structure of type LS_CMD_MSG into the 
LS_HP_QUEUE by using the function push_hp_queue. The data structure has the cmd_add 
field given by the argument cmd and the event_number field given by the argument ev_num;
fields ans_add and err_code are dummy.
*/

//================================================================================================
/*! \fn int write_cmd_lp_queue(unsigned int * cmd, unsigned int ev_num)
unsigned int * cmd : pointer to the location of memory that holds a command: this pointer
must be put (as part of a structure) into the LS_LP_QUEUE.\n 
unsigned int ev_num : value that will be given to the field event_number of the structure to
be put into the LS_LP_QUEUE.\n
This function puts the pointer to a data structure of type LS_CMD_MSG into the 
LS_LP_QUEUE by using the function push_lp_queue. The data structure has the cmd_add 
field given by the argument cmd and the event_number field given by the argument ev_num;
fields ans_add and err_code are dummy. Function write_cmd_lp_queue is used by two functions
in hk_ask.c file: hk_prepare_data and hk_issue_ls_spectrom.
*/

//================================================================================================
/*! \fn int push_lp_queue(void * datin)
void * datin : pointer to the data element (structure of type LS_CMD_MSG) that must 
be put into the virtuoso fifo LS_LP_QUEUE.\n
This function puts an entry in the low speed low priority queue LS_LP_QUEUE
by calling the function push_queue; if push_queue returns RC_OK, the semaphore LS_SEMA
is signalled.
*/

//================================================================================================
/*! \fn int push_hp_queue(void * datin)
void * datin :  pointer to the data element (structure of type LS_CMD_MSG) that must 
be put into the virtuoso fifo LS_HP_QUEUE.\n
This function puts an entry in the low speed high priority queue LS_LP_QUEUE
by calling the function push_queue; if push_queue returns RC_OK, the semaphore LS_SEMA
is signalled.
*/