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

This file contains the functions used to implement the memory services of HIFI. Most of these functions are mainly interfaces 
between the OBS and the functions of the Memory Managment library (MM_lib) which implement the actual processing.

Memory services commands are excuted within the hs_hdl task, therefore they are organised in the same way as commands affecting 
the HS subsystems: this means that the execution is divided into one or more step: the first step will stop
the HS subsystem, set the value of the static variables affecting the command execution and launch the first step (if any) 
or directly execute the command if it is a single step command.

A common feature of the memory_lib functions is that they accept in input a structure of type memory_header that is 
used to specify the part of memory affected by the command and to return results. Therefore all the interfaces need 
essentially to create a memory header, pass it to the proper MM_lib function and the inspect the returned value
to generate an execution report.

The following commands are executed by the functions contained in this file:

memory_check: check the contents of a specified part of memory, i.e. computes the crc

memory_load:

memory_dump:

check_PM:

copy_OBS:

Other functions contained in this file are not executed within the hs_hdl task but, instead, are used to initialise
the memory library itself and are therefore executed within task entry_point at the program start.

*/

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

This function is called at program startup in order to initialize the memory managment library static data.
Essentially it sets to proper values the memory IDs matrix of the library by deleting all the stored segments 
(which, by default are those of PACS) and then registering the IDs needed by HIFI, specifying their address.

*/

//================================================================================================
/*! \fn int map_HIFI_id_to_LIB_id(unsigned int *id)

This function converts the HIFI memory ID (received with the TC) into a MM lib memory ID. 
The HIFI IDs does not explicitely specify the type of memory (PM or DM) were the ID is contained, while the library infer
this information from the first bit of the ID (first bit = 1 means DM while first bit = 0 means PM. Therefore this function 
simply change the first bit of the HIFI ID to the proper value thereby making it a MM_lib ID.

Input/Output parameter:
int *id: pointer to the the HIFI id. Its value is turned to the MM_lib id

Returned value:
1 if all rigth 
0 if the ID was not recognised

*/

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

Implements the first (and only) step of a memory check command. Executed within the hs_hdl task.
Specifically it stops any HS activity (not strictly required but it is safer), produce a memory header containing
the information about what is the part of memory to check by extractin the information from the TC packet,
 calls the function memory_check (of MM_lib) that computes and returns the crc, and check the rerurned value producing a report.

Input parameter:
HS_HDL_MSG *message: a pointer to the message received by hs_hdk in its queue: it contains a block where the whole TC is stored

Returned value:
RC_OK if all right
RC_FAIL if a problem occurred

*/

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

Implements the first (and only) step of a memory load command. Executed within the hs_hdl task.
Specifically it stops any HS activity (not strictly required but it is safer), produce a memory header containing
the information about what is the part of memory to load by extracting the information from the TC packet,
calls the function memory_load (of MM_lib) passing to this function the header and a pointer to the TC packet where the 
data to load are stored and checks the returned value producing a report.

Input parameter:
HS_HDL_MSG *message: a pointer to the messagfe received by hs_hdk in its queue: it contains a block where the whole TC is stored

Returned value:
RC_OK if all right
RC_FAIL if a problem occurred

*/

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

Implements the first step of a memory dump command.Executed within the hs_hdl task. 
Specifically it stops any HS activity (not strictly required but it is safer), produce a memory header containing
the information about what is the part of memory to load by extracting the information from the TC packet,
post a message into the hs_hdl qyeye in order to triffer the following step of the memory_dump command.

Input parameter:
HS_HDL_MSG *message: a pointer to the messagfe received by hs_hdk in its queue: it contains a block where the whole TC is stored

Returned value:
RC_OK if all right
RC_FAIL if a problem occurred

*/

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

Implements a step of a memory dump command. I.e. check if an there is still some data dumped, and if yes 
gets the contents of the relative memory, put them into a HK packet
and pass the packet to TMTC. The memory is accessed by means of the memory_dump function of the MM_lib which 
knows what is the actual part of memory to read from the memory header; it also updates the memory header for the next step; it 
returns the contents of the memory in variable data_store. As a flood control measure at the begining it checks the HK pool 
occupation level and, if full, the step is skipped, some time is waited and the step is reenqueued. 
As a final step it enqueues a packet into the hs_hdl queue in order to trigger the next step.

Input parameter:
int command_number  this is the command_number of the current memory_dump command and is needed to write it into the hs_hdl queue packet

Returned value:
RC_OK if all right
RC_FAIL if a problem occurred
*/


//================================================================================================
/*! \fn int generate_dump_report (int RAM_type, int mem_id, int start_add, int *data, unsigned int check_sum)

Writes the report for a memory_dump command into a HK packet then enqueues it towards tmtc_if task in order to be sent to ground.

Input parameter: 
int RAM_type: 	1 if DM 0 if PM, used to compute the lenght of the data in byte
int mem_id: memory ID of the TC
int start_add: start address of the TC
int *data: memory contents to be sent to ground. data[0] is the number of SAU to transfer
unsigned int check_sum: check sum of the dumped data


Returned value:
RC_OK if all right
RC_FAIL if a problem occurred
*/

//================================================================================================
/*! \fn int check_memory_header(memory_header header, int check_TC)

Decodes the value returned by the function crate_memory_header. If an error was detected the relative
message is enqueued towards ground with data taken from the header to specify the error. 

Input parameter: 
memory_header header: the memory header to be checked
int check_TC: the reurn of the function create_memory_header

Returned value:
RC_OK if all right
RC_FAIL if a problem occurred
*/

//================================================================================================
/*! \fn int generate_check_report (TC_packet * p_tc, unsigned int crc)

Writes the report packet of a memory_check command and enqueues it towards tmtc_if task in order to be sent to ground.

Input parameter: 
TC_packet * p_tc: a copy of the TC, to be added to the report
unsigned int crc: the computed crc on the memory area to check

Returned value:
RC_OK if all right
RC_FAIL if a problem occurred
*/


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

Executed within the hs_hdl task. Implements the start step of the simulated science command. The HS system is stopped and a message is posted into
hs_hdl queue to trigger the first step of simulated science 
...............
*/

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

Executed within the hs_hdl task. Implements the generic step of the simulated science command and triggers the next step 
.................
*/


//================================================================================================
/*! void generate_sim_science_data (void)

produces simulated science data and sends it towards data_hdl
......................
*/