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

This file contains a series of functions for the generation of TM packets related to
events, telecommand verification, and reports. More specifically:
- event reports: function generate_event()
- telecommand verification: functions enqueue_ok(), enqueue_nok(), enqueue_exec_fail(),
enqueue_exec_compl(), completion_update()
- reports of other kinds: generate_report()

In addition the header file contains most of the OBS error code mnemonics
*/


//==============================================================================
/*! \fn void init_event_counters( unsigned int counter_51, unsigned int counter_54)

This function is called at startup (see main) in order to init event counters. At call time the parameters 
are set equal to the number of TM packets already produced by the boot software so that the count does not restart from zero.
*/

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

This function is to be called before posting a message into the event queue. If the return value is 0
the queue is full and the calling function should NOT post the event. If the return value is 1 the event can be posted.

The function checks if at least 2 slots are free in the queue. If only one is free, it is used 
by the function itself to post a warning message saying that errors were disabled. And 0 is returned.
Otherwise 1 is returned.
*/ 

//==============================================================================
/*! \fn int generate_event (int ev_subtype, int ev_id, int sid, int N_param, int * rep_param)

This function is called when the generation of a TM packet of type 5 (event)
is required; this function can handle different subtypes (tipically: 1, 2, 4),
evids and sids, that are passed as arguments; additional parameters can be included
in the TM packet through arguments N_param, rep_param; the memory block for the
event packet is taken from the EV_POOL and is passed to task tmtc by sending a
message in the fifo EVENT_TM_QUEUE. */


//==============================================================================
/*! \fn int enqueue_ok (TC_packet * packet, unsigned int subtype)

Function that produces a telecommand verification TM packet (type 1);
according to the second argument received, subtype may be 1 (acceptance success), 
or 7 (execution completed). Ack bits in the TC packet are checked to know whether
the TC verification is required. The packet produced is built in a memory block of
the EV_POOL and is queued towards task tmtc using the fifo EVENT_TM_QUEUE. Note:
this function is always used for TC acceptance success reports, and it is also
used for execution completion reports of "short" telecommands (i.e. those that are
executed immediately in task cmd_seq, and that consequently do not update the
variable completion_info). */


//==============================================================================
/*! \fn int enqueue_nok (TC_packet * packet, unsigned int subtype, unsigned int err_code, int N_param, unsigned int * param_ptr)

Function that produces a telecommand verification TM packet (type 1);
according to the second argument received, subtype may be 2 (acceptance failure), 
or 8 (execution failure). The packet produced is built in a memory block of
the EV_POOL and is queued towards task tmtc using the fifo EVENT_TM_QUEUE. Note:
this function is always used for TC acceptance failure reports, and it is also
used for execution failure reports of "short" telecommands (i.e. those that are
executed immediately in task cmd_seq, and that consequently do not update the
variable completion_info). */



//==============================================================================
/*! \fn int enqueue_exec_fail (unsigned int err_code, int N_param, unsigned int * param_ptr)

This function is to be called every time that a telecommand execution failure
is detected, in order to produce an execution failure TM(1,8) packet; the variable
completion_info is read to get information about the TC packet whose execution
failed; the variable is then reset. Function's arguments are: an error code, the
number of error describing parameters to be included in the TM packet, the pointer
to the list of these paramters. The TM(1,8) packet is built in a memory block of
the EV_POOL, and is sent towards tmtc_if task using the EVENT_TM_QUEUE. Note: this
function always returns RC_FAIL because the caller needs to propagate it to the
higher level */


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

This function produces, if requested, a packet TM(1,7): execution completed;
the variable completion_info is read to get information about the TC packet whose
execution is succesfully completed; the TM(1,7) packet eventually produced is
built in a memory block of the EV_POOL, and is sent towards tmtc_if task using
the EVENT_TM_QUEUE; in any case the variable completion_info is reset, because
the TC execution has been brought to completion. */

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

This function updates the variable for completion management (named completion_info),
and it is then to be called when the execution of a "long" telecommand is started; 
before updating the completion_info variable, it checks if the previous TC execution
is completed, otherwise an execution failure must be produced (signalling that the
previous TC has been aborted); note: if the argument received is a NULL pointer,
then the variable completion_info is simply reset. */

//==============================================================================
/*! \fn int generate_report (unsigned int rep_apid, int rep_type, int rep_subtype, int N_param, unsigned int * rep_param)

This function produces a TM packet (with apid = rep_apid, type = rep_type,
subtype = rep_subtype) containing N_param parameters, each 16-bit long, pointed
by rep_param; the packet is built using a memory block taken from the HK_POOL and
is passed to task tmtc by sending a message in the HK_TM_QUEUE fifo; this function
is used in many of the cases where a report of some kind must be produced. */