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

In this file task hs_hdl is implemented together with several of its ancillary functions. This task is in charge of executing several 
OBS commands and specifically all the commands requiring interaction with ther HS subsystems. When not running the task is in wait state 
on the HS_HDL_QUEUE. To start a command the cmd_seq task puts a the corresponding TC packets into the queue. A command is normally 
executed in several steps. Upon reception of the TC packet the task hs_hdl calls a function implementing the first step of the command.
Each step eventually reqenqueues a packet in the hs_hdl queue that triggers the sccessuive step.

The first step of every command is special since it performs no processing but a standard sequence of actions:
Specififcally it checks whether another command involving hs is running (as signaled by the fifo_x_pending frames). 
	- If yes the TC packet is reenqueued and no processing take place
	- If not the current command static data are initialised, including the AID_spectroscopy value
	and the pakcet requiring the first step is pushed into the hs_hdl queue.
	
Important globals are:

current_command_number: every command has a number and the currently running one has the number stored in this variable.
This counter is incremented by cmd_seq everytime that a new command is passed to hs_hdl. The command number is contained in 
every packet that is put into the hs_hdl queue. Task hs_hdl compares the pkt number with the running command number
and if the two do not match it knows that the packet is obsolete, since a newer command exist, and shall be aborted. 
In this case the packet is simply dropped, possibly freeing the pool block it was carrying, thereby stopping the obsolete command.

Fifo_x_pending_frames: everytime a frame is requested to one of the HW fifos this counter is incremented. Every time a frame has been
processed, up to the data_hdl task, this counter is decremented. Therefore, if this counter is greater than 0, a frame is being processed
and it is not a good idea to change any static variable that could affect the hs system. On the contrary when the counters are zero the 
hs system is not working (the tasks are waiting on some queue or event) and we can change the static variables.


*/

//================================================================================================
/*! \fn void hs_hdl( void );

This is the hs_hdl task. The task is in a wait state on the HS_HDL_QUEUE. Upon a packet reception
the packet command_number is checkd against the current_command_number and if the two does not match the 
command is obsolete and can be dropped. In this case we check if a block was linked to the message and, in 
case yes, free the block. If the message is relative to the current command the operation_id is switched
to decide what is the processing function in charge of the message handling.

*/


//================================================================================================
/*! \fn int wbs_att_set (int aid, int command_number)

This function implements step 1,2 or 3 of the wbs tuning procedure, depending on the parameter aid.
If aid == WBS_ATTSETT_ID then it is the first step and a zero_scan() is performed.
If aid == WBS_ATTSETT_ID2 then it is the second step and parameter setting is performed followed by a wbs integration.
If aid == WBS_ATTSETT_ID3 then it is the third step and a wbs integration is performed.

The science data frames received from the WBS are processed by the hs0, hs1, and data_hdl tasks, which know from the 
value of AID_spectroscopy what is the running procedure.

An RC_FAIL value is returned if it was impossible to write on the LS queue any of the commands to the subsystems.

The input parameter command_number is passed to the integration procedure whch will perform the integration only
if this is equal to the current_command_number.
*/

//================================================================================================
/*! \fn int zero_scan (int command_number)
Executes a wbs zero scan: sets the appropriate values of the WBS parameters and performs 
a wbs integration. An RC_FAIL is returned when it was impossible to write on the LS queue.

The input parameter command_number is passed to the integration procedure which will perform the integration only
if this is equal to the current_command_number.
*/

//================================================================================================
/*! \fn int tune_mix_mag (unsigned int AID_sp, int command_number)

This function performs the generic step of the wbs or hrs mixer magnet tuning procedure. It sends several commands
to the instruments and requires several HK (which are stored in a static variable). Waits for the HK to be
produced (by waiting for event MEAS_EVENT, which is set after all the HK requests have been processed). Performs
a WBS or HS integration. It cooperates with a party function working within the data_hdl task that is in charge of 
processing the HS data produced by the integration and of triggering the next step. There exist several static data 
that are accessed by both procedures in every step:

mixer_mag_steps_performed: records the number of  steps performed. used to control the termination.
mixer_magnet_data: a vector containing the TC data (tuning parameters) and the HK produced during the 
					tuning procedure

The input parameter command_number is passed to the integration procedure whch will perform the integration only
if this is equal to the current_command_number.

An RC_FAIL value is returned if it was impossible to write on the LS queue any of the commands to the subsystems.

*/


//================================================================================================
/*! \fn int wbs_calibration_step1 (int command_number)

First step of wbs calibration.

The input parameter command_number is passed to the integration procedure whch will perform the integration only
if this is equal to the current_command_number.
*/

//================================================================================================
/*! \fn int wbs_calibration_step2 (int command_number)

Second step of wbs calibration.

The input parameter command_number is passed to the integration procedure whch will perform the integration only
if this is equal to the current_command_number.

*/

//================================================================================================
/*! \fn int spec_wbs_zero (int command_number)

Sends to the ls task the commands for spectroscopy wbs zero.

The input parameter command_number is passed to the integration procedure whch will perform the integration only
if this is equal to the current_command_number.
*/


//================================================================================================
/*! \fn void mkstep_dip_scan_if (int command_number)

Performs the operations of a single step of the dip scan with ifpower. It sends several commands
to the instruments and requires several HK (which are stored in a static variable). Waits for the HK to be
produced (by waiting for event MEAS_EVENT, which is set after all the HK requests have been processed). Performs
a WBS or HS integration. It cooperates with a party function working within the data_hdl task that is in charge of 
processing the HS data produced by the integration and of triggering the next step. There exist several static data 
that are accessed by both procedures in every step:

dip_scan_if_cur_step: records the number of  steps performed. used to control the termination.
dip_scan_if_data: a vector containing the data during the scan

The input parameter command_number is passed to the integration procedure whch will perform the integration only
if this is equal to the current_command_number.
*/


//================================================================================================
/*! \fn int wbs_integrate (unsigned int integ_time, int flush_at_end, int command_number)

Perform a variable duration wbs integration. The duration is specified by the first parameter.
If the second parameter is set to 1 the procedure will set the HS_FLUSH evenrt for the task hs_flush to extract 
the data from the fifo (this is needed only for the last transfer of a sequence).
The third parameter tells to what command the integration is relative. This parameter is checked against 
current_command_number and if the two do not match integration is not requested.

An RC_FAIL value is returned if any problema was encountered (if it was not
possible to pass the command to the ls task by writing on the ls command queues.
An RC_OK value is returne if all was ok.

Whenever an integration is requested the fifo_x_pending_frames counter is increased.

*/

//================================================================================================
/*! \fn int hrs_integrate (unsigned int integ_time, int flush_at_end, int command_number)

Perform a variable duration hrs integration. The duration is specified by the first parameter.
If the second parameter is set to 1 the procedure will set the HS_FLUSH evenrt for the task hs_flush to extract 
the data from the fifo (this is needed only for the last transfer of a sequence).
The third parameter tells to what command the integration is relative. This parameter is checked against 
current_command_number and if the two do not match integration is not requested.

An RC_FAIL value is returned if any problema was encountered (if it was not
possible to pass the command to the ls task by writing on the ls command queues.
An RC_OK value is returne if all was ok.

Whenever an integration is requested the fifo_x_pending_frames counter is increased.
*/

//================================================================================================
/*! \fn void task_hs_hdl_sleep (unsigned int sleep_time)

this function is a controlled sleep function. It sets a timer (hs_hdl_Timer) to the sleep time and put 
itself on a wait state on  the semaphore HS_HDL_WAIT_SEMA. When the timer reaches zero the semaphore is signalled 
and wait ends; however the sleep can be interrupted by any other task who signals the semaphore HS_HDL_WAIT_SEMA.

*/