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

This file contains the task hk_ask (see function hk_ask) and related functions. The task hk_ask is 
triggered by a Virtuoso Timer (by default set to 3 sec) and is responsible for: 

requesting periodic housekeepings using the low priority ls queue to interface with the ls task
receiving hk data from the subsystems 
performing some error and limit check on the received hk data
organizing the hk data into packets and sending them to the tm_tc task by using the hk queue.

The file hk_ask.c also contains some other functions (start_single_hk, single_hk, hk_switch_FCU_err_count_on, 
hk_switch_FCU_err_count_off, hk_switch_limit_check_off, hk_switch_limit_check_on) that are used by other tasks.
*/
 
//================================================================================================
/*! \fn void hk_ask( void )
A timer is created and started in order to have a periodic signaling of the semaphore HK_REQ_SEMA 
(every 3 seconds by default). The task then waits on that semaphore, and, when it is signaled (and 
if the HK are enabled), it begins the process of asking, collecting and sending HK data. The two 
functions hk_issue_ls_FCU_LCU and hk_issue_ls_spectrom are used to send housekeeping requests to 
the ls task (the second function is called only if no spectroscopy measurement is being performed). 
OBS housekeepings are added by calling the function hk_prepare_data; error and limit checks are
performed through the functions hk_error_count, hk_limit_check; hk data is sent to tm_tc using 
the function hk_send_data. Besides periodic housekeepings, the task hk_ask produces essential HK 
as well, using the functions hk_ess_prepare_data, hk_ess_send_data.
*/

//================================================================================================
/*! \fn void hk_issue_ls_spectrom( void )
For each active spectrometer, this function sends an appropriate HK request in 
the low priority ls queue by calling the write_cmd_lp_queue function.
*/

//================================================================================================
/*! \fn void hk_issue_ls_FCU_LCU( void )
For both LCU and FCU this function pushes into the low priority ls queue commands taken from the 
array HK_FCU_commands, together with information about where the retrieved HK data and error codes 
should be placed (notice: for LCU the error code management has to be modified).
*/

//================================================================================================
/*! \fn void hk_prepare_data(void)
This function sends a dummy command to the low priority ls queue and then waits for the event HK_EVENT 
before starting to write OBS housekeeping data into the hk_block variable using the function rc_write_obs_hk.
The HK_EVENT is signalled by the task ls after the processing of the dummy command: this way we are sure that 
all Housekeeping data from the subsystems have already been collected.   
*/

//================================================================================================
/*! \fn void hk_error_count(void)
So far, this function works only on errors coming from FCU. If FCU is on and the error count is on, 
it detects the number of  errors (of the three types called err8C, err8D, err8F) provided together 
with the hk data. If there are no errors associated with the present hk data, the corresponding 
static counters are reset, otherwise they are incremented. When a static counter exceeds the corresponding 
maximum value (stored in the variables HK_N_breach_8C, HK_N_breach_8D, HK_N_breach_8F) the function 
generate_event is called.   
*/

//================================================================================================
/*! \fn void hk_limit_check(void)
This function carries out limit checks on some of the retrieved hk parameters; in case of exceeding, 
the function generate_event is called.
*/

//================================================================================================
/*! \fn void hk_send_data(void)
This function prepares the packet to be sent to the HK_TM_QUEUE (if necessary it produces several 
packets); it writes the source data header. After sending the block, it gets a new one through the 
function hk_get_block.
*/

//================================================================================================
/*! \fn void hk_ess_prepare_data(void)
This function gets a pool block for essential hk and copies a subset of the hk data in it.
*/

//================================================================================================
/*! \fn void hk_ess_send_data( void );
This function prepares the packet of essential HK to be sent to the HK_TM_QUEUE (if necessary 
it produces several packets).
*/

//================================================================================================
/*! \fn void hk_get_block( void );
This function gets a pool block from the HK pool, and sets the pointers of the array pdata_hs.
*/

//================================================================================================
/*! \fn void hk_process_wbs(int fifo_id, int* pdata, unsigned int * scan_count);
This function is called by task hs1 to perform HK processing for WBS and upload the
data to module hk_ask.
*/      

//================================================================================================
/*! \fn void hk_process_hrs(int fifo_id, int* pdata);
This function is called by task hs1 to perform HK processing for HRS and upload the
data to module hk_ask.
*/      


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

This function is a service of the module hk_ask. It is called by cmd_seq to ask for a single, non periodic HK packet.
A request can be accepted only if there are no other requests pending (as controlled by 
the static variable pending_single_hk). If there is a collision the second request is ignored.
*/

//================================================================================================
/*! \fn void single_hk(void);
  To ask for the subsample of houskeeping data needed in case of single Hk request
  and to prepare the single HK packet for Telemetry.

*/

//================================================================================================
/*! \fn void hk_switch_FCU_err_count_on(int N_breach_8C, int N_breach_8D, int N_breach_8F)

int N_breach_8C : value to be given to HK_N_breach_8C, represents the max number of breach for 8C commands \n
int N_breach_8D : value to be given to HK_N_breach_8D, represents the max number of breach for 8D commands \n
int N_breach_8F : value to be given to HK_N_breach_8F, represents the max number of breach for 8F commands \n

This function sets to 1 the variable HK_error_count_FCU_on and initializes the variables HK_N_breach_8C,
HK_N_breach_8D, HK_N_breach_8F with the values received as arguments. 
*/

//================================================================================================
/*! \fn int start_single_HK_LCU(LS_HDL_MSG *msg)

This function is called by ls_hdl in order to start a single_HK_LCU command. It extracts some data from the TC packet
passed with the queue message, constructs and enqueues a sequence of prepare/requireHK commands towards the LCU by posting 
the corresponding messages into the ls high priority queue and close the sequence by requiring a feedback to ls(). The
ls commands also contain the address of where to write the LCU responses that is in the single_HK_LCU_data[] vector;

*/

//================================================================================================
/*! void send_single_HK_LCU_report(void)

This function is called by ls_hdl in order to perform the second and last step of a single_HK_LCU command. 
It is activated when ls_hdl receives the feedback from ls() meaning that all the HK reqs have been executed so that
the data in single_HK_LCU_data[] vector are valid. The function simply constructs a TM packet to send these data 
towards tmtc_if for relaying to ground.
*/