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

This file contains a set of functions that are called by vaious tasks to perform various activities.
It is essentially a library. Most of the functions are used by task cmd_seq.
*/

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

Sends a start abort command to task hs_hdl that will stop any pending activity
and put the hs chain in a well defined state and AID_spectroscopy to REQUIRING_HK; 
the global variable abort_is_running is checked to see if an abort is already running: 
if yes, the new abort request is dropped. 
*/

//==============================================================================
/*! \fn void obs_ident (TC_packet * packet)

Writes ObsID & BBID coming with the TC packet into the corresponding global variables, 
and resets the transfer counters
*/

//==============================================================================
/*! \fn void instrument_status (TC_packet * packet)

This function is called by cmd_seq and executes the "instrument status" notification TC (notify PDU status);
global variables SubsysStatus, Active_spectr are updated according to the SS status
word coming with the TC; for each spectrometer that was off and has been switched
on: 1) resets the corresponding hw fifo; 2) sets to zero the corresponding variable
fifo_x_pending_frames; finally, through the IRQ mask register, enables only the
interrupts corresponding to SS that are on.
*/

//==============================================================================
/*! \fn int configure_ss (TC_packet * packet)

Called by task cmd_seq to execute a configure subsystem TC(8,4,12). After producing a TM(8,6) report packet 
which contains an echo of the received TC it sends into the ls queue the sequence of commands that were 
received with the TC and that will configure the subsystem 
*/


//==============================================================================
/*! \fn int configure_spectroscopy (TC_packet * packet)

Called by task cmd_seq to execute a configure spectroscopy command. 
The TC contains 29 16-bit parameters that must be copied into the two arrays
Spectroscopy_table[] and Conf_Spectroscopy_table[]. In addition an echo of the 
written parameters is generated and sent as a TM packet
*/


//==============================================================================
/*! \fn int send_single_command (TC_packet * packet) 

Called by task cmd_seq in order to execute the send_single_command TC:
it enqueues towards task LS the single command coming with the TC packet, 
and produces an echo tm packet.
*/

//==============================================================================
/*! \fn void forward_command_to_ls_hdl (TC_packet * packet, int oper_id)

Called by task cmd_seq in order to pass a command to task ls_hdl.
- It increase the global current_command_number in order to assign a number to the command just received
and to stop any previously running command. 
- It signals the semaphore Sema_Wait_Group in order to get task ls_hdl out of any wait state.
- It calls the completion_update() function to store the parameters of the running command.
- It flushes the hs_hdl task input fifo since if any message is there it is now obsolete (since
a new command has just been received).
- Updates the value of the building_block global variable.
- It sets the fields of a message to be passed to the ls_hdl input queue and in particular the copies the operation_id 
received from cmd_seq into the message: this filed tells the task ls_hdl what is the required action.
- Finally it posts the message into the ls_hdl_queue
*/

//==============================================================================
/*! \fn void forward_TCpacket_to_ls_hdl (TC_packet * packet, int oper_id)

Called by task cmd_seq in order to pass a command to task ls_hdl.
- It increase the global current_command_number in order to assign a number to the command just received
and to stop any previously running command. 
- It signals the semaphore Sema_Wait_Group in order to get task ls_hdl out of any wait state.
- It calls the completion_update() function to store the parameters of the running command.
- Gets a block from the TC_POOL and copies the TC packet received by cmd_seq over it
- It flushes the hs_hdl task input fifo since if any message is there it is now obsolete (since
a new command has just been received).
- Updates the value of the building_block global variable.
- It sets the fields of a message to be passed to the ls_hdl input queue and in particular copies the operation_id 
received from cmd_seq into the message: this filed tells the task ls_hdl what is the required action. Also a reference to the
block where the TC paket was copied is passed.
- Finally it posts the message into the ls_hdl_queue
*/

//==============================================================================
/*! \fn void forward_TCpacket_to_hs_hdl (TC_packet * packet, int command_aid)

Called by task cmd_seq in order to pass a command to task hs_hdl.
- It increase the global current_command_number in order to assign a number to the command just received
and to stop any previously running command. 
- It signals the semaphore Sema_Wait_Group in order to get task hs_hdl out of any wait state.
- It calls the completion_update() function to store the parameters of the running command.
- Gets a block from the TC_POOL and copies the TC packet received by cmd_seq over it
- It flushes the hs_hdl task input fifo since if any message is there it is now obsolete (since
a new command has just been received).
- Updates the value of the building_block global variable.
- It sets the fields of a message to be passed to the ls_hdl input queue and in particular copies the operation_id 
received from cmd_seq into the message: this filed tells the task ls_hdl what is the required action. Also a reference to the
block where the TC paket was copied is passed.
- Finally it posts the message into the hs_hdl_queue
*/

//==============================================================================
/*! \fn int enable_time_verification (TC_packet * packet)
Called by task cmd_seq to implement the enable time verification TC
Prepares a TM packet whith the current time stamp, then enqueues it towards tmtc_if task.
*/

//==============================================================================
/*! \fn int perform_connection_test (TC_packet * packet)           
Called by task cmd_seq to implement the perform connection test TC
Prepares a TM packet whith no data, then enqueues it towards tmtc_if task.
*/

//==============================================================================
/*! \fn void NYI_TC (TC_packet * packet)
Service function used by cmd_seq when a TC is received that not yet implemented.
Produces a TC acceptance failure: TM(1,2).
*/

//==============================================================================
/*! \fn void reset_function (unsigned int act_id)
Perform a software reset. Disables all interrupts and restart the OBS
*/

//==============================================================================
/*! \fn void pkt_enable (TC_packet * packet, int flag)

Called by cmd_seq in response to a packet transmission enable/disable TC. 
It enables/disables (depending on the value of the argument flag: 1 enables, 0 disables)
packets specified by (type, subtype, packet_id); if packet_id is zero, 
all TM packets with (type, subtype) are enabled/disabled.
*/

//==============================================================================
/*! \fn int pkt_enable_report (TC_packet * packet)

Called by cmd_seq in response to a packet transmission report TC. 
It produces a TM packet containing the list of (type, subtype, packet_id) combinations
whose transmission is enabled; the packet is sent to the EVENT_TM_QUEUE. 
*/