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

This file contains the task data_hdl and related functions. The task is in charge of handling the science data
produced by the HIFI spectrometers that are passed to data_hdl by task hs1(). It also cooperates with task
hs_hdl() in the implementation of several HIFI commands.

*/
 
//================================================================================================
/*! \fn void data_hdl (void)

This function implements task data_hdl(). This task has an input queue, SD_PKT_QUEUE, and is noemally in a wait status
on this input queue. The queue is filled by task hs1() with the incoming science data frames. 

As soon as a message is received the task is activated. There are two types of messages: those really containing science data
and those simply informing this task that a science data frame has been received by hs1(). These latter messages are 

FRAME_HRS_V_ID
FRAME_HRS_H_ID
FRAME_WBS_V_ID
FRAME_WBS_H_ID

when one of these messages the only processing required is an update of the pending frames counters. On the contrary when 
a message containing science datas the processing varies depending on the specific command being executed. The typical processing 
is the construction of a TM packet and the enqueuement of this packet towards tmtc_if task for relaying to ground. After the processing 
has been executed data_hdl() may give feedback to the hs_hdl() task to trigger the next step of a command. data_hdl() also checks the 
termination of some commands and when the end is detected it resets the HW subsystem abn restarts the periodic HK requests
by setting the value of AID_spectroscopy to REQUIRING_HK.
*/

//================================================================================================
/*! \fn void check_if_measure_is_over (int fifo_id)

The input parameter tells that a sd packet has been received for the fifo_id specified.
The function check if a measurement is over by updating the number of missing frames (which is set at the beginning of a command)
and checking if it is zero; in this case the bit corresponding to the fifo is set in the end_of_measure_flag variable. 
This variable is then compared to the active fifo mask to decide whether the meas is over or not.

When the end of measurement is detected a completion message is enqueued, the spectroscopy table resetted and 
periodik HK requests are restarted by settin AID_spectroscopy to REQUIRING_HK.

*/


//================================================================================================
/*! \fn void check_termination_fast_chop (int fifo_id)

Similar to check_if_measure_is_over, but specific for fast_chop, which uses a smarter setting of the number of 
frames to produce in a given run of the command. This smarter setting avoids the use of the global end_of_measure_flag variable.
This function is informed by the input parameter that a science data frame was received 
for a given instruments and decrease the corresponding number of missing frames (holded by Sd_hdl[].duration).
When the number of missing frames is zero for all the instruments the fast_chop is over.

When the end of a fast chop measurement is detected a completion message is enqueued, the spectroscopy table resetted and 
periodik HK requests are restarted by settin AID_spectroscopy to REQUIRING_HK.
*/

//================================================================================================
/*! \fn void close_and_reinit (void)

This function is called when some command termination is detected  in order to perform a sequence of actions needed upon command
termination: specifically it calls enqueue_exec_compl() for the generation of the execution completion acknowledgement, 
then calls init_spec_table() to re-initialize part of the array Conf_Spectroscopy_table[], then sets AID_spectroscopy to the
normal "idle" value REQUIRING_HK.
*/

//================================================================================================
/*! \fn void reset_data_hdl (void)

This function resets to initial values several static variable used by the module data_hdl. It is normally called at the start
of an activity involving this module, and is part of the reset of the high speed subsystem.
*/

//================================================================================================
/*! \fn  void packetize_HRS (unsigned int subsysid, unsigned int phase, unsigned int transfer_cnt)

This function is used to format and pass a HRS Science Data frame to task tmtm_if for relaying to ground as a sequence of TM packets.
In particular it is used by any measurement involving HRS (slow chop, fast chop, frequency switch) and by the tune HRS command.

Input argument subsysid tell if the frame is from HRS H or V, phase represents the integration buffer (0 for buffer 1, 1 for buffer 2)
and transfer counter is simply a counter that records how many frames have been extracted from the instruments since the last setting
of the observation id.

The function formats the science data the packet based on data stored in globals Spectroscopy_table and Sd_hdl, 
operating directly on the SD pool block received from task hs1. Next the function constructs a science start frame packet 
(by calling write_hrs_start_frame) and passes it to task tmtc by posting a message into the SD_TM_QUEUE. Finally it passes 
to task tmtc the data by posting a sequence of messages into the SD_TM_QUEUE where each message carries a reference to a different 
part of the SD pool block where the data are actually hosted. Task tmtc is in charge of freeing the SD pool block when the last 
message has been received.
*/

//================================================================================================
/*! \fn  void packetize_WBS (unsigned int subsysid, unsigned int phase, int scan_count, unsigned int transfer_cnt)

This function is used to format and pass a WBS Science Data frame to task tmtm_if for relaying to ground as a sequence of TM packets.
In particular it is used by any measurement involving WBS (slow chop, fast chop, frequency switch) and by the tune WBS command.

Input argument subsysid tell if the frame is from HRS H or V, phase represents the integration buffer (0 for buffer 1, 1 for buffer 2),
scan_count carries the scan count as extracted from the instrument and transfer counter is simply a counter that records how many 
frames have been extracted from the instruments since the last setting of the observation id.

The function formats the science data the packet based on data stored in globals Spectroscopy_table and Sd_hdl, 
operating directly on the SD pool block received from task hs1. Next the function constructs a science start frame packet 
(by calling write_wbs_start_frame) and passes it to task tmtc by posting a message into the SD_TM_QUEUE. Finally it passes 
to task tmtc the data by posting a sequence of messages into the SD_TM_QUEUE where each message carries a reference to a different 
part of the SD pool block where the data are actually hosted. Task tmtc is in charge of freeing the SD pool block when the last 
message has been received.
*/

//================================================================================================
/*! \fn  void write_science_headers (unsigned int subsysid, unsigned int phase, int numpack)

this function writes the TM packet header at the beginning of the memory block
referenced by variable sd_msg.block (the block is in the SD_POOL); note: argument
phase represents the integration buffer (0 for buffer 1, 1 for buffer 2)
*/


//================================================================================================
/*! \fn  void write_hrs_start_frame (unsigned int subsysid, unsigned int phase, unsigned int transfer_cnt, int numpack, int *p_ppp)

this function prepares and sends a start frame packet for hrs: TM(21,1) with 
sid 1,..4;  notice: argument phase represents the integration buffer (0 for 
buffer 1, 1 for buffer 2).
*/

//================================================================================================
/*! \fn  void write_wbs_start_frame (unsigned int subsysid, unsigned int phase, unsigned int transfer_cnt, int int_scan_count, int numpack, int *p_ppp)

this function prepares and sends a start frame packet for wbs: TM(21,1) with 
sid 5,..8;  notice: argument phase represents the integration buffer (0 for 
buffer 1, 1 for buffer 2).
*/

//================================================================================================
/*! \fn  void hrs_right_shift (void)

Used in formatting of hrs data

*/


//================================================================================================
/*! \fn  void packetize_IFHRS (unsigned int subsysid, unsigned int phase)

this function computes the IF power for a hrs frame and relays it to tmtc by 
posting a packet TM(3,25) (IF housekeeping) with sid 25,..,28  
into the HK_TM_QUEUE; notice: argument phase represents the integration 
buffer (0 for buffer 1, 1 for buffer 2).
*/

//================================================================================================
/*! \fn  void packetize_IFWBS (unsigned int subsysid, int scan_count, unsigned int phase)

this function computes the IF power for a wbs frame and relays it to tmtc by 
posting a packet TM(3,25) (IF housekeeping) with sid 25,..,28  
into the HK_TM_QUEUE; notice: argument phase represents the integration 
buffer (0 for buffer 1, 1 for buffer 2).
*/

//================================================================================================
/*! \fn  void init_sdh (void)

inits of SD buffer handlers
*/


//================================================================================================
/*! \fn  int get_hrs_frames_per_wbs (void)
Returns the number of hrs starts per wbs start
*/

//================================================================================================
/*! \fn  int init_science_data (void)

Inizializes hs variables in order to allow a new total power spectroscopy measurement.
I.E. copies Spectroscopy_table into sd_hdl and inits other stuff (Meas_spectr, the sd_hdl blocks...)
*/

//================================================================================================
/*! \fn  int pkt_complete (int fifo_id, int coadded)

Checks the number of coadditions against those to be done. Returns 1 if the two match.
*/

//================================================================================================
/*! \fn  void init_spec_table (void)

this function copies the 29 elements of the initialization table 
Spectroscopy_table_init[] into the first 29 elements of Spectroscopy_table[].

*/

//================================================================================================
/*! \fn  void init_conf_spec_table (void)

this function copies the 29 elements of the initialization table 
Spectroscopy_table_init[] into the first 29 elements of Conf_Spectroscopy_table[].
*/

//================================================================================================
/*! \fn  void store_wbs_att_sett (int fifo_id, int* pdata)

at the end of the first step of wbs calibration we save the wbs attenuator setting 
into the array variable wbs_att_setting. This function is called by task hs1 during 
wbs frame processing.

*/

//================================================================================================
/*! \fn  void trigger_next_step (unsigned int next_AID_spectr, unsigned int subsys_id)

this function prepares a message and sends it to task hs_hdl via fifo HS_HDL_QUEUE;
the message triggers the next step of the current activity (tuning, scan, calibration);
global variable AID_spectroscopy is set to the value pertaining the next step;
*/