//================================================================================================
/*! \file hs_lib.c
\brief Contains several functions that are used by task hs_hdl

Contains several functions that are used by task hs_hdl

*/

//================================================================================================
/*! \fn void init_tuni_table (unsigned int spectr_id)

This function is used to init SD_hdl and Spectroscopy_table for several OBS operations. Indeed several operations 
(e.g. tuning wbs, tuining hrs) have default values for parameters (e.g. number of coadded frames, integration time).
The input parameter spectr_id carries the code of the operation. 

*/

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

Resets (i.e. flush all data) the HW fifos. Resets (i.e. sets the static variables to the default values) the 
OBS part in cherge of handling the fifo output, that is hs0, hs1 and data_hdl tasks.

This function is called at the beginning of any measurement or hs activity for safety reasons.

*/

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

Prepare a new command execution by the ls_hdl task
this function is similar to HS_safe_status(), but addresses the simpler case
of the preparation of a ls_hdl activity, so no need to stop HK frame requests
and wait for pending frames to become zero; what we need is to stop any VM and
hs_hdl activities and bring back AID_spectroscopy to REQUIRING_HK; in case there
is a running hs_hdl activity, a rude 1100 ms sleep is for the moment adopted to
ensure that all frame transfers are finished

*/

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

Checks if the HS subsystem is in a safe status where a safe status
is the one where there are no frames pending.

It returns 1 if the HS system is safe and 0 if not.

If HS is not safe performs actions to bring it towards a safe status. These actions depend upon the HS current activity
as indicated by the global AID_spectroscopy.


If AID_spec = requiring_hk
	the system is requiring science data only for the purpose of prducing HK.
	in this case we stop hk reqs by changing the value of AID_spec and request a flush
	in order to bring the pending frames counters towards zero.

If AID_spec indicates that a VM activity is ongoing
	stops the VM, and wait a time sufficient for any pending frame to be processed 
	then reset the frame counters and returns 1.

If AID_spec indicates that a OBS activity involving HK is ongoing
	just change AID_spec to stopping_OBS
	
In all other cases we simply check whether there are pendig frames or not by checking the value of the 
frame counters (fifo_x_pending_frames).
*/

//================================================================================================
/*! \fn int bring_to_safe (HS_HDL_MSG *message)

This function is called at the starting of any hs activity. 
Checks if the HS subsystem is in a safe status and, if not takes appropriate ctions to bring
it towards a safe status: this is done by calling the function hs_safe_status.

If the system is safe it returns 1. In this case the calling function can start the activity.
If HS not safe it waits a certain time and returns 0. In this case the calling function 
cannot start any activity but has to call again this function and wait for the HS subsystem to became safe.
However the number of time that the starting of an activity is attempted is recorded in the relative
field of the hs_hdl queue message which is passed as the input parameter (exec_attemp). 
This counter is increased at every attempt and a maximum number 
of attempts exist, after which the function performs and hard reset of the HS subsystem: this is done to avoid to get stuck
in case of any problem.
*/

//================================================================================================
/*! \fn int start_abort (HS_HDL_MSG *message)

This is the first and only step of an abort command. This function is executed within the hs_hdl task
in response to a packet with operation_id = START_ABORT.

*/

//================================================================================================
/*! \fn int start_total_power (HS_HDL_MSG *message)

This is the first and only OBS step of a total power measurement (additional steps are carried out by the VM).
The function is executed within the hs_hdl task in response to a message with operation_id = START_TOTAL_POWER.
Like all other start functions it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.

It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.

The actions specifically taken by this functions in order to start the activity when the HS
susbsystem is safe are the following:
- several VM related static variables are initialised.
- several HS subsystem related static variables (used by tasks hs_lib and data_hdl) are initialised.
- the value of AID_spectroscopy is set according to the activity
- the TOTAL_POWER VM program is loaded and the VM is started (this is done by calling function start_VM)

*/

//================================================================================================
/*! \fn int start_freq_switch (HS_HDL_MSG *message)

This is the first and only OBS step of a freq switch measurement (additional steps are carried out by the VM).
The function is executed within the hs_hdl task in response to a message with operation_id = START_FREQ_SWITCH.
Like all other start functions it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.

It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.

The actions specifically taken by this functions in order to start the activity when the HS
susbsystem is safe are the following:
- several VM related static variables are initialised.
- several HS subsystem related static variables (used by tasks hs_lib and data_hdl) are initialised.
- the value of AID_spectroscopy is set according to the activity
- the freq switch VM program is loaded and the VM is started (this is done by calling function start_VM)
*/

//================================================================================================
/*! \fn int start_slow_chop (HS_HDL_MSG *message)

This is the first and only OBS step of a slow chop measurement (additional steps are carried out by the VM).
The function is executed within the hs_hdl task in response to a message with operation_id = START_SLOW_CHOP.
Like all other start functions it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.

It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.

The actions specifically taken by this functions in order to start the activity when the HS
susbsystem is safe are the following:
- several VM related static variables are initialised.
- several HS subsystem related static variables (used by tasks hs_lib and data_hdl) are initialised.
- the value of AID_spectroscopy is set according to the activity
- the slow chop VM program is loaded and the VM is started (this is done by calling function start_VM)
*/

//================================================================================================
/*! \fn int start_fast_chop (HS_HDL_MSG *message)

This is the first and only OBS step of a fast chop measurement (additional steps are carried out by the VM).
The function is executed within the hs_hdl task in response to a message with operation_id = START_FAST_CHOP.
Like all other start functions it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.

It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.

The actions specifically taken by this functions in order to start the activity when the HS
susbsystem is safe are the following:
- several VM related static variables are initialised.
- several HS subsystem related static variables (used by tasks hs_lib and data_hdl) are initialised.
- the value of AID_spectroscopy is set according to the activity
- the fast chop VM program is loaded and the VM is started (this is done by calling function start_VM)
*/


//================================================================================================
/*! \fn int upload_VM_code (HS_HDL_MSG *message)

This function writes in array Code[] the vm code coming with a TC packet whose
format is that of the old configure ss fid 5, but assuming that only 32-bit
parameters are present; the parts of array Code[] where writing is forbidden
are the following index ranges (extremes included): 0-2 (entry points of
preloaded programs), 8-2047 (preloaded programs), 8064-8191 (parameters area). 
*/

//================================================================================================
/*! \fn int start_VM_prog (HS_HDL_MSG *message)

This is the first and only OBS step of a generic VM procedure (additional steps are carried out by the VM).
The specific procedure to execute is carried by the TC data stored in the input message.
Like all other start functions it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.

It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.

the TC packet that triggers this function is assumed to be like the one for
total power but with the addition of a 16-bit parameter after the BBID: the
index (between 0 and 7) in the entry point area of Code[] where the offset for
the vm program to be executed is stored; note: during the vm program execution,
AID_spectroscopy is given the same value of a total power measurement
*/

//================================================================================================
/*! \fn int start_hrs_tune (HS_HDL_MSG *message)

This is the start step of a hrs tuning procedure.
The function is executed within the hs_hdl task in response to a message with operation_id = START_HRS_TUNE.
Like all other start functions it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.
Next it equeues the a message with operation_id = HRS_ATTSETT_ID that will trigger the next step of the procedure.
It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.
*/

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

Implements the first step of an hrs tuning procedure: it prepares the hrs and start an integration.

returns RC_OK.

The input parameter command_number (that is the code of the current command) is passed down to 
the integration procedure in order to be saved in the static variables that 
record for which command the current frame was asked.
*/

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

Implements the second step of an hrs tuning procedure: it prepares the hrs and start an integration.

returns RC_OK.

The input parameter command_number (that is the code of the current command) is passed down to 
the integration procedure in order to be saved in the static variables that 
record for which command the current frame was asked.
*/

//================================================================================================
/*! \fn void packetize_ATTHRS (unsigned int i)

Process the science data of the first step of an hrs tuning command.
Sends a tune report TM(21,3) to the HK_TM_QUEUE.
The input parameter i specifies whether the frame is from hrs V or H.
*/

//================================================================================================
/*! \fn void packetize_ATTHRS2 (unsigned int i)

Process the science data of the second step of an hrs tuning command.
Sends a tune report TM(21,3) to the HK_TM_QUEUE.
The input parameter i specifies whether the frame is from hrs V or H.
*/

//================================================================================================
/*! \fn int start_wbs_tune (HS_HDL_MSG *message)

This is the start step of a wbs tuning procedure.
The function is executed within the hs_hdl task in response to a message with operation_id = START_WBS_TUNE.
Like all other start functions it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.
Next it equeues the a message with operation_id = WBS_ATTSETT_ID that will trigger the next step of the procedure.
It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.
*/

//================================================================================================
/*! \fn void packetize_ATTWBS2 (unsigned int wbs_id, int scan_count)

Process the science data of the first and second step of an wbs tuning command.
Sends a tune report TM(21,3) to the HK_TM_QUEUE.
the input parameter wbs_id specifies the wbs (H or V)
the second parameter carries the scan count.
*/

//================================================================================================
/*! \fn void zscan_WBS (unsigned int i, int scan_count)

Process the science data of the zero_scan step of an wbs tuning command.
Executed within data_hdl
the input parameter wbs_id specifies the wbs (H or V)
the second parameter carries the scan count.
*/

//================================================================================================
/*! \fn int start_dip_scan_ifp (HS_HDL_MSG * message)

This is the start step of a diplexer scan with IF power procedure.
The function is executed within the hs_hdl task in response to a message with operation_id = START_DIPSCAN_IFP.
Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.
Next it equeues the a message with operation_id = DIP_SCAN_IF_ID that will trigger the next step of the procedure.
It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.
*/


//================================================================================================
/*! \fn void dipscan_compute_ifpower (unsigned int fifo_id, unsigned int step)

Process the science data of a diplexer scan with IF power. Executed within data_hdl
For a single step of a diplexer scan with if power, this function, given a hrs 
block (accessible through the global variable sd_msg), computes the eight powers 
relating to chip 2 (whereas those relating to chip 1 are simply ignored); the
powers are stored into appropriate locations of the array dip_scan_if_data[].
*/

//================================================================================================
/*! \fn int start_wbs_calibrate (HS_HDL_MSG * message)

This is the start step of both a spectroscopy wbs comb and a spectroscopy wbs zero,
depending on the operation code contained into the structure pointed by message
 
Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.
Next it equeues the a message with an operation_id that will trigger the next step of the procedure.
It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.
*/


//================================================================================================
/*! \fn int start_tune_mixer_magnet_hrs (HS_HDL_MSG *message)

This is the start step of a hrs mixer magnet tuning 
 
The function is executed within the hs_hdl task in response to a message with operation_id = START_HRS_MIXMAG.
Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.
Next it equeues the a message with operation_id = TUNE_HMIXMAG_ID that will trigger the next step of the procedure.
It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.
*/

//================================================================================================
/*! \fn int start_tune_mixer_magnet_wbs (HS_HDL_MSG *message)

This is the start step of a wbs mixer magnet tuning 
 
The function is executed within the hs_hdl task in response to a message with operation_id = START_WBS_MIXMAG.
Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it initializes the HS system and static variables involved in command executions.
Next it equeues the a message with operation_id = TUNE_WMIXMAG_ID that will trigger the next step of the procedure.
It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.
*/

//================================================================================================
/*! \fn void tune_hmixmag (unsigned int fifo_id, unsigned int * nl)

This function process the science data of the generic mixer magnet hrs tuning procedure step.
It is executed within data_hdl.

Specifically it function computes the average 
power from the frame received and, if necessary, updates the variables used for
the minimum average power search.
arguments: fifo_id = subsysID (specify if hrs H or V); nl = nloop array*/

//================================================================================================
/*! \fn void tune_wmixmag (unsigned int fifo_id, unsigned int * nl, unsigned int scan_count)

This function process the science data of the generic mixer magnet wbs tuning procedure step.
It is executed within data_hdl.

It computes the average 
power from the frame received and, if necessary, updates the variables used for
the minimum average power search.
arguments: fifo_id = subsysID (it should be 0 for wbsh, 1 for wbsv); nl = nloop array
*/

//================================================================================================
/*! \fn void send_mixmag_rep (unsigned int tuni_id)

executed within data_hdl:
it prepares and sends to tmtc the report at the end of a mixer magnet tuning;
this function receives a tuni_id to distinguish between wbs and hrs.
*/

//================================================================================================
/*! \fn void set_magnet_opt_current (unsigned int tuni_id)

executed within data_hdl:
this function is called at the end of a mixer magnet tuning (hrs or wbs) in order to set
the magnet currents to the optimum values.
The input tuni_id tells whether the wbs or hrs is to be set.
*/


//================================================================================================
/*! \fn int configure_peakup_function (HS_HDL_MSG * message)

Start (and only) of a configure peak up - performs the peakup configuration 

The function is executed within the hs_hdl task in response to a message with operation_id = CONFIGURE_PEAKUP.
Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it performs the peakup
configuration  by writing some variables; it also sets to zero all the flags
in peakup_acquired_flags[], thus indicating that previously acquired powers are
no more valid
It returns RC_OK in case of normal termination and RC_FAIL if any problem is encountered.
*/

//================================================================================================
/*! \fn int start_peakup_acquire_hrs (HS_HDL_MSG * message)

First step of a hrs peakup acquisition  

The function is executed within the hs_hdl task in response to a message with operation_id = ACQUIRE_PEAKUP_HRS 

Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it performs the data transfer request to the appropriate HRS subsystem (h or v depending on the
value of a parameter contained into the TC); if the peak up type is 1, then the
data transfer request must be preceded by the transmission of the ls command needed
to set the chopper position; note that a number of checks on telecommand parameters
are performed before actually starting the main operations.
*/

//================================================================================================
/*! \fn int start_peakup_acquire_wbs (HS_HDL_MSG * message)

First and only step of a wbs peakup acquisition  

The function is executed within the hs_hdl task in response to a message with operation_id = ACQUIRE_PEAKUP_WBS

Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it performs the
data transfer request to the appropriate WBS subsystem (h or v depending on the
value of a parameter contained into the TC); if the peak up type is 1, then the
data transfer request must be preceded by the transmission of the ls command needed
to set the chopper position; note that a number of checks on telecommand parameters
are performed before actually starting the main operations.
*/

//================================================================================================
/*! \fn void peakup_hrs_compute_ifpower (unsigned int fifo_id)

Process the science data received within a hrs peakup.
Pxecuted within the data_hdl task.

Given a hrs block (accessible through the global variable sd_msg),
computes the average of the eight powers relating to chip 2: this average value
is stored into array peakup_acquired_ifpowers[], at index (peakup_meas_seq_number - 1);
the corresponding flag in peakup_acquired_flags[] is set.
*/

//================================================================================================
/*! \fn void void peakup_wbs_compute_ifpower (unsigned int fifo_id, unsigned int scan_count)

Process the science data received within a wbs peakup.
Pxecuted within the data_hdl task.

Given a wbs block (accessible through the global variable sd_msg),
computes the average of the four powers obtained with default offsets and npixels:
this average value is stored into array peakup_acquired_ifpowers[], at index 
(peakup_meas_seq_number - 1); the corresponding flag in peakup_acquired_flags[] is set.
*/

//================================================================================================
/*! \fn int peakup_tune_chopper (HS_HDL_MSG * message)

First and only step of a correction chopper procedure

The function is executed within the hs_hdl task in response to a message with operation_id = PEAKUP_CHOPPER_CORR

Like all other start functions after a few inits it checks if the HS system is safe. 
If it is not safe the message (which is received by this function as input parameter) is reenqueued (by the bring_to_safe function) 
and no actions are taken. 
If the system is safe it 1) performs some checks before starting; 2) computes the peak position for the chopper,
based on the 9 powers previously acquired; 3) sends an ls command to set the
chopper position to the optimum calculated; 4) prepares and sends a final report
*/

//================================================================================================
/*! \fn int peakup_aocs_correction (HS_HDL_MSG * message)

First and only step of a Correction AOCS Telecommand

The function is executed within the cmd_seq task in response to a Correction AOCS TC:

1) performs some checks before starting; 2) using the 9 powers previously acquired, computes
the peak position on the "j axis" and, if peakup type is 2, also on the "i axis"
3) prepares and sends a report packet and an event packet.
*/

//================================================================================================
/*! \fn void shift_right (int *p_data, int length, int shift)

Purpose: To perform the division required by the coadding mechanism.
Description: This function right shifts the words of the frame just processed.
Input: Pointer and length of the data buffer and amount of shift.
*/

//================================================================================================
/*! \fn void siftdown (int array[], int lower, int upper)
Tool for the heapsort routine
*/

//================================================================================================
/*! \fn void heapsort (int array[], int len)

Heap sort, used to find the median element in mediand_idx.
*/

//================================================================================================
/*! \fn unsigned int median_idx (int * invec, int inlen)

finds andf returns the position of the median element of input vettore
*/