Index: NVDataMgmt.c =================================================================== diff -u -r13c32729e3186ebb5487e41a0cecd4cf15d357eb -r6c500be6ac0c5adffc0d91b666862e35ba27e2db --- NVDataMgmt.c (.../NVDataMgmt.c) (revision 13c32729e3186ebb5487e41a0cecd4cf15d357eb) +++ NVDataMgmt.c (.../NVDataMgmt.c) (revision 6c500be6ac0c5adffc0d91b666862e35ba27e2db) @@ -26,6 +26,11 @@ #include "Timers.h" #include "Utilities.h" +/** + * @addtogroup NVDataMgmt + * @{ + */ + // Private defines #define QUEUE_MAX_SIZE 20U ///< Max queue size @@ -76,7 +81,7 @@ #define COMMAND_TIME_OUT 500U // time in ms ///< Timeout for an EEPROM or RTC command in ms -/// NVDataMgmt self test states +/// NVDataMgmt self test states enumeration. typedef enum NVDataMgmt_Self_Test_States { NVDATAMGMT_SELF_TEST_STATE_START = 0, ///< Self test start @@ -94,7 +99,7 @@ NUM_OF_NVDATAMGMT_SELF_TEST_STATES ///< Total number of self test states } NVDATAMGMT_SELF_TEST_STATE_T; -/// NVDataMgmt Exec states +/// NVDataMgmt Exec states enumeration. typedef enum NVDataMgmt_Exec_State { NVDATAMGMT_EXEC_STATE_WAIT_FOR_POST = 0, ///< Exec state wait for POST @@ -107,7 +112,7 @@ NUM_OF_NVDATAMGMT_EXEC_STATES ///< Total number of exec states } NVDATAMGMT_EXEC_STATE_T; -/// NVDataMgmt memory operation modes +/// NVDataMgmt memory operation modes enumeration. typedef enum NVDataMgmt_Operation { NVDATAMGMT_NONE = 0, ///< Default mode to prevent any accidental ops @@ -117,7 +122,7 @@ NUM_OF_NVDATAMGMT_OPS_STATES ///< Total number of operation states } NVDATAMGMT_OPERATION_STATE_T; -/// NVDataMgmt memory locations +/// NVDataMgmt memory locations enumeration. typedef enum NVDataMgmt_Location { NVDATAMGMT_EEPROM = 0, ///< Location EEPROM @@ -126,7 +131,7 @@ } NVDATAMGMT_LOCATION_STATE_T; #pragma pack(push, 1) -/// Memory operations struct +/// Memory operations structure. typedef struct { NVDATAMGMT_OPERATION_STATE_T memoryOperation; ///< Memory operation @@ -137,7 +142,7 @@ U32 length; ///< Length of a buffer } MEMORY_OPS_T; -/// Log header struct +/// Log header structure. typedef struct { U16 recordCount; ///< Record count @@ -146,51 +151,51 @@ BOOL isHdrCorrupted; ///< Log header corruption flag } LOG_HEADER_T; -/// Log record struct +/// Log record structure. typedef struct { LOG_HEADER_T logHeader; ///< Log header struct U16 crc; ///< Log header CRC } LOG_RECORD_T; -/// Treatment time struct +/// Treatment time structure. typedef struct { U32 treatmentTime; ///< Treatment time U16 crc; ///< Treatment time CRC } TREATMENT_TIME_RECORD_T; -/// Water consumption struct +/// Water consumption structure. typedef struct { U32 waterConsumption; ///< Water consumption U16 crc; ///< Water consumption CRC } WATER_CONSUMPTION_RECORD_T; -/// Manufacturing data struct +/// Manufacturing data structure. typedef struct { MFG_DATA_T mfgData; ///< Manufacturing data struct U16 crc; ///< Manufacturing data CRC U08 Padding[ 0x30 - sizeof(MFG_DATA_T) - sizeof(U16) ]; ///< Padding for reserved mfg data space } MFG_RECORD_T; -/// Service record struct +/// Service record structure. typedef struct { SERVICE_DATA_T serviceData; ///< Service date struct U16 crc; ///< Service data CRC } SERVICE_RECORD_T; -/// Calibration record struct +/// Calibration record structure. typedef struct { CALIBRATION_DATA_T calData; ///< Calibration data struct U16 crc; ///< Calibration data CRC U08 Padding[ 0x50 - sizeof(CALIBRATION_DATA_T) - sizeof(U16) ]; ///< Padding for reserved cal data space } CALIBRATION_RECORD_T; -/// Last disinfection record struct +/// Last disinfection record structure. typedef struct { DISINFECTION_DATE_T date; ///< Disinfection date (char array) @@ -219,7 +224,7 @@ static BOOL hasCommandTimedout = FALSE; ///< Boolean flag for timeout of the commands static U32 currentTime = 0; ///< Current time static BOOL calRecordIsValid = FALSE; ///< Flag indicates whether stored calibration record was found to be valid -static volatile BOOL powerOffIsImminent = FALSE; ///< Power off warning has been signaled. Non-volatile memory operations should be completed ASAP and then ceased. +static volatile BOOL powerOffIsImminent = FALSE; ///< Power off warning has been signaled. Non-volatile memory operations should be completed ASAP and then ceased // Private functions @@ -262,12 +267,14 @@ static BOOL didCommandTimeout ( ALARM_ID_T alarm, U08* state ); static BOOL eraseDataLogSectors ( void ); -/************************************************************************* - * @brief initNVDataMgmt - * The initNVDataMgmt initializes EEPROM +/*********************************************************************//** + * @brief + * The initNVDataMgmt initializes the module. * @details - * Inputs : none - * Outputs : none + * Inputs: NVDataMgmtSelfTestState, NVDataMgmtExecState, NVDataMgmtSelfTestResult, + * queueRearIndex, queueFrontIndex, queueCount + * Outputs: NVDataMgmtSelfTestState, NVDataMgmtExecState, NVDataMgmtSelfTestResult, + * queueRearIndex, queueFrontIndex, queueCount * @return none *************************************************************************/ void initNVDataMgmt ( void ) @@ -282,31 +289,31 @@ Fapi_setActiveFlashBank( Fapi_FlashBank7 ); } -/************************************************************************* +/*********************************************************************//** * @brief - * The signalPowerOffWarning signals this module that system power off is \n - * imminent and any non-volatile data writes in progress should be wrapped up \n + * The signalPowerOffWarning signals this module that system power off is + * imminent and any non-volatile data writes in progress should be wrapped up * quickly and any pending non-volatile data writes should not be started. * @details - * Inputs : none - * Outputs : powerOffIsImminent + * Inputs: none + * Outputs: powerOffIsImminent * @return none *************************************************************************/ void signalPowerOffWarning( void ) { powerOffIsImminent = TRUE; } -/************************************************************************* - * @brief setMfgData - * The setMfgData updates the struct that holds the manufacturing data, +/*********************************************************************//** + * @brief + * The setMfgData updates the structure that holds the manufacturing data, * calls another function to calculate the CRC for the provided data and * calls another function to erase sector 0 and write the new manufacturing * data. * @details - * Inputs : MFG_DATA_T (data) - * Outputs : BOOL - * @return BOOL + * Inputs: mfgRecord + * Outputs: mfgRecord + * @return TRUE is the enqueue was successfully scheduled *************************************************************************/ BOOL setMfgData ( MFG_DATA_T data ) { @@ -316,14 +323,15 @@ return status; } -/************************************************************************* - * @brief getMfgData - * The getMfgData returns the data in the struct that holds manufacturing - * record to buffer that the caller has provided +/*********************************************************************//** + * @brief + * The getMfgData returns the data in the structure that holds manufacturing + * record to buffer that the caller has provided. * @details - * Inputs : MFG_DATA_T* (buffer) - * Outputs : BOOL (status) - * @return BOOL (status) + * Inputs: mfgRecord + * Outputs: none + * @param buffer address of manufacturing data buffer + * @return TRUE if the buffer pointer was not null and the copy was successful *************************************************************************/ BOOL getMfgData ( MFG_DATA_T* buffer ) { @@ -338,16 +346,17 @@ return status; } -/************************************************************************* - * @brief setCalibrationData - * The setCalibrationData updates the struct that holds the calibration data, +/*********************************************************************//** + * @brief + * The setCalibrationData updates the structure that holds the calibration data, * calls another function to calculate the CRC for the provided data and * calls another function to erase sector 0 and write the new manufacturing * data. * @details - * Inputs : MFG_DATA_T (data) - * Outputs : BOOL - * @return BOOL + * Inputs: calibrationRecord + * Outputs: calibrationRecord + * @param data calibration data structure + * @return TRUE if updating was successfully scheduled *************************************************************************/ BOOL setCalibrationData ( CALIBRATION_DATA_T data ) { @@ -361,14 +370,15 @@ return status; } -/************************************************************************* - * @brief getCalibrationData - * The getCalibrationData returns the data in the struct that hold calibration - * record to buffer that the caller has provided +/*********************************************************************//** + * @brief + * The getCalibrationData returns the data in the structure that hold + * calibration record to buffer that the caller has provided. * @details - * Inputs : CALIBRATION_DATA_T* (buffer) - * Outputs : BOOL (status) - * @return BOOL (status) + * Inputs: calibrationRecord + * Outputs: none + * @param buffer address of calibration data buffer + * @return TRUE if calibration record valid *************************************************************************/ BOOL getCalibrationData ( CALIBRATION_DATA_T* buffer ) { @@ -383,15 +393,16 @@ return status; } -/************************************************************************* - * @brief setServiceDate - * The setServiceDate updates the struct that holds the calibration data, +/*********************************************************************//** + * @brief + * The setServiceDate updates the structure that holds the calibration data, * calls another function to calculate the CRC for the provided data if - * there is enough queues available, it schedules a write to RTC RAM + * there is enough queues available, it schedules a write to RTC RAM. * @details - * Inputs : SERVICE_DATA_T (data) - * Outputs : BOOL - * @return BOOL + * Inputs: serviceRecord + * Outputs: serviceRecord + * @param data service data buffer + * @return TRUE if the queue had enough space to schedule the job *************************************************************************/ BOOL setServiceDate ( SERVICE_DATA_T data ) { @@ -409,14 +420,15 @@ return status; } -/************************************************************************* - * @brief getServiceDate - * The getServiceDate returns the data in the struct that holds service - * date to buffer that the caller has provided +/*********************************************************************//** + * @brief + * The getServiceDate returns the data in the structure that holds service + * date to buffer that the caller has provided. * @details - * Inputs : SERVICE_DATA_T* (buffer) - * Outputs : BOOL (status) - * @return BOOL (status) + * Inputs: serviceRecord + * Outputs: none + * @param buffer address of service data buffer + * @return TRUE if the buffer address was not null *************************************************************************/ BOOL getServiceDate ( SERVICE_DATA_T* buffer ) { @@ -431,14 +443,15 @@ return status; } -/************************************************************************* - * @brief writeLogData +/*********************************************************************//** + * @brief * The writeLogData checks if the queue is not full and if it is not, it calls - * enqueue to schedule a job for writing the log data + * enqueue to schedule a job for writing the log data. * @details - * Inputs : LOG_DATA_T* (data) - * Outputs : BOOL - * @return BOOL + * Inputs: logRecord + * Outputs: none + * @param data address of log data buffer + * @return TRUE if the queue is not full and if the log header is not corrupted *************************************************************************/ BOOL writeLogData ( LOG_DATA_T* data ) { @@ -454,14 +467,16 @@ return status; } -/************************************************************************* - * @brief readLogData +/*********************************************************************//** + * @brief * The readLogData checks if the queue is not full and if it is not, it calls - * enqueue to schedule a job for writing the log data + * enqueue to schedule a job for writing the log data. * @details - * Inputs : READ_DATA_T* (buffer), U32 (length) - * Outputs : BOOL - * @return BOOL + * Inputs: none + * Outputs: none + * @param buffer address of read data buffer + * @param length length of the data log + * @return TRUE if there are enough queues available for the job *************************************************************************/ BOOL readLogData ( READ_DATA_T* buffer, U32 length ) { @@ -477,14 +492,15 @@ return status; } -/************************************************************************* - * @brief setTreatmentTime +/*********************************************************************//** + * @brief * The setTreatmentTime sets a queue job to write the treatment time in - * the specified RAM address + * the specified RAM address. * @details - * Inputs : U32 (mins) - * Outputs : BOOL - * @return BOOL + * Inputs: treatmentTimeRecord + * Outputs: treatmentTimeRecord + * @param hours treatmet time in hours + * @return TRUE if the queue was not full so the job was scheduled successfully *************************************************************************/ BOOL setTreatmentTime ( U32 hours ) { @@ -502,28 +518,29 @@ return status; } -/************************************************************************* - * @brief getTreatmentTime +/*********************************************************************//** + * @brief * The getTreatmentTime returns the total number treatment hours of the - * HD device + * HD device. * @details - * Inputs : none - * Outputs : U32 - * @return U32 + * Inputs: none + * Output: none + * @return treatment time as U32 *************************************************************************/ U32 getTreatmentTime ( void ) { return treatmentTimeRecord.treatmentTime; } -/************************************************************************* - * @brief setWaterConsumption +/*********************************************************************//** + * @brief * The setWaterConsumption sets a queue job to write the amount of water - * that has been consumed in DG + * that has been consumed in DG. * @details - * Inputs : U32 (liters) - * Outputs : BOOL - * @return BOOL + * Inputs: waterConsumptionRecord + * Outputs: waterConsumptionRecord + * @param liters consumed water is liters + * @return TRUE if queue is not full *************************************************************************/ BOOL setWaterConsumption ( U32 liters ) { @@ -541,28 +558,29 @@ return status; } -/************************************************************************* - * @brief getWaterConsumption - * The getWaterConsumption returns the amount of consumed water +/*********************************************************************//** + * @brief + * The getWaterConsumption returns the amount of consumed water. * @details - * Inputs : none - * Outputs : U32 - * @return U32 + * Inputs: none + * Outputs: none + * @return water consumption as a U32 *************************************************************************/ U32 getWaterConsumption ( void ) { return waterConsumptionRecord.waterConsumption; } -/************************************************************************* - * @brief setDisinfectionDate +/*********************************************************************//** + * @brief * The setDisinfectionDate gets the last disinfection date, calculates the * CRC for it and if the queue is not full, it schedules a write to RTC RAM - * to store the last date + * to store the last date. * @details - * Inputs : DISINFECTION_DATE_T (date) - * Outputs : BOOL (status) - * @return BOOL (status) + * Inputs: lastDisinfectionRecord + * Outputs: lastDisinfectionRecord + * @param date disinfection date buffer + * @return TRUE if the queue was not full *************************************************************************/ BOOL setDisinfectionDate ( DISINFECTION_DATE_T date ) { @@ -580,14 +598,15 @@ return status; } -/************************************************************************* - * @brief getDisinfectionDate +/*********************************************************************//** + * @brief * The getDisinfectionDate populates the provided buffer with the last - * disinfection date + * disinfection date. * @details - * Inputs : DISINFECTION_DATE_T* (buffer) - * Outputs : BOOL (status) - * @return BOOL (status) + * Inputs: lastDisinfectionRecord + * Outputs: none + * @param buffer address of disinfection date buffer + * @return TRUE if the buffer address was not null *************************************************************************/ BOOL getDisinfectionDate ( DISINFECTION_DATE_T* buffer ) { @@ -602,13 +621,13 @@ return status; } -/************************************************************************* - * @brief execNVDataMgmtSelfTest - * The execNVDataMgmtSelfTest runs the NVDataMgmt POST during the self test +/*********************************************************************//** + * @brief + * The execNVDataMgmtSelfTest runs the NVDataMgmt POST during the self test. * @details - * Inputs : none - * Outputs : SELF_TEST_STATUS_T - * @return SELF_TEST_STATUS_T + * Inputs: NVDataMgmtSelfTestState + * Outputs: NVDataMgmtSelfTestState, alarm if there was a software fault + * @return NVDataMgmtSelfTestResult the result of self test *************************************************************************/ SELF_TEST_STATUS_T execNVDataMgmtSelfTest ( void ) { @@ -690,13 +709,14 @@ return NVDataMgmtSelfTestResult; } -/************************************************************************* - * @brief setBootloaderFlag - * The setBootloaderFlag sets the bootloader flag to RTC RAM +/*********************************************************************//** + * @brief + * The setBootloaderFlag sets the bootloader flag to RTC RAM. * @details - * Inputs : U32 (flag) - * Outputs : BOOL - * @return BOOL + * Inputs: none + * Outputs: none + * @param flag the bootloader flag + * @return TRUE if the queue was not full *************************************************************************/ BOOL setBootloaderFlag ( U32 flag ) { @@ -712,29 +732,30 @@ return status; } -/************************************************************************* - * @brief getBootloaderFlag - * The getBootloaderFlag gets the bootloader flag from RTC RAM +/*********************************************************************//** + * @brief + * The getBootloaderFlag gets the bootloader flag from RTC RAM. * @details - * Inputs : none - * Outputs : U32 (flag value) - * @return U32 (flag value) + * Inputs: none + * Outputs: none + * @return bootloader flag as a U32 *************************************************************************/ U32 getBootloaderFlag( void ) { return bootloaderFlag; } -/************************************************************************* - * @brief execNVDataMgmt - * The execNVDataMgmt runs the NVDataMgmt main tasks +/*********************************************************************//** + * @brief + * The execNVDataMgmt runs the NVDataMgmt main tasks. * @details - * Inputs : none - * Outputs : none + * Inputs: NVDataMgmtExecState + * Outputs: NVDataMgmtExecState, alarm if exec state was invalid * @return none *************************************************************************/ void execNVDataMgmt( void ) -{ // TODO - not sure where it should go Dara, but need to look at powerOffIsImminent flag and block queuing of any new jobs, maybe even block starting of any new jobs if flag is set +{ // TODO - not sure where it should go Dara, but need to look at powerOffIsImminent flag and block + // queuing of any new jobs, maybe even block starting of any new jobs if flag is set switch ( NVDataMgmtExecState ) { case NVDATAMGMT_EXEC_STATE_WAIT_FOR_POST: @@ -786,15 +807,13 @@ } } -// Private functions - -/************************************************************************* - * @brief handleSelfTestStart - * The handleSelfTestStart enables the EEPROM bank sectors +/*********************************************************************//** + * @brief + * The handleSelfTestStart enables the EEPROM bank sectors. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestStart ( void ) { @@ -808,14 +827,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestEnableEEPROM +/*********************************************************************//** + * @brief * The handleSelfTestEnableEEPROM waits for EEPROM to return with ready from - * enabling the EEPROM command + * enabling the EEPROM command. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestEnableEEPROM ( void ) { @@ -837,14 +856,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadBootloaderFlag +/*********************************************************************//** + * @brief * The handleSelfTestReadBootloaderFlag reads the bootloader flag - * from RTC RAM + * from RTC RAM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime, bootloaderFlag + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadBootloaderFlag ( void ) { @@ -877,14 +896,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadHDTreatmentTime +/*********************************************************************//** + * @brief * The handleSelfTestReadHDTreatmentTime reads the HD treatment time - * from RTC RAM + * from RTC RAM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime, treatmentTimeRecord + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadHDTreatmentTime ( void ) { @@ -907,14 +926,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadDGWaterConsumption +/*********************************************************************//** + * @brief * The handleSelfTestReadDGWaterConsumption reads the DG water consumption - * from RTC RAM + * from RTC RAM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime, waterConsumptionRecord + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadDGWaterConsumption ( void ) { @@ -936,13 +955,13 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadLogRecord - * The handleSelfTestReadLogRecord reads the log record from RTC RAM +/*********************************************************************//** + * @brief + * The handleSelfTestReadLogRecord reads the log record from RTC RAM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime, logRecord, mfgRecord + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadLogRecord ( void ) { @@ -966,14 +985,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadMfgRecords +/*********************************************************************//** + * @brief * The handleSelfTestReadMfgRecords reads the manufacturing record from - * EEPROM + * EEPROM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime, calibrationRecord + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadMfgRecord ( void ) { @@ -993,14 +1012,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadCalibrationRecord +/*********************************************************************//** + * @brief * The handleSelfTestReadCalibrationRecord reads the calibration record - * from EEPROM + * from EEPROM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadCalibrationRecord ( void ) { @@ -1022,14 +1041,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadServiceRecord +/*********************************************************************//** + * @brief * The handleSelfTestReadServiceRecord reads the service dates from RTC - * RAM + * RAM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: currentTime, serviceRecord + * Outputs: currentTime + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadServiceRecord ( void ) { @@ -1050,14 +1069,14 @@ return state; } -/************************************************************************* - * @brief handleSelfTestReadLastDisinfectionDate +/*********************************************************************//** + * @brief * The handleSelfTestReadLastDisinfectionDate reads the last disinfection date - * from RTC RAM + * from RTC RAM. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: lastDisinfectionRecord + * Outputs: none + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestReadLastDisinfectionDate ( void ) { @@ -1074,14 +1093,16 @@ } -/************************************************************************* - * @brief handleSelfTestCheckCRC +/*********************************************************************//** + * @brief * The handleSelfTestCheckCRC calculates the CRC of the records and compares - * them to the CRC that was read. If they don't match, it will fail POST + * them to the CRC that was read. If they don't match, it will fail POST. * @details - * Inputs : none - * Outputs : NVDATAMGMT_SELF_TEST_STATE_T - * @return NVDATAMGMT_SELF_TEST_STATE_T + * Inputs: treatmentTimeRecord, waterConsumptionRecord, lastDisinfectionRecord, + * logRecord, mfgRecord, calibrationRecord, calibrationRecord, serviceRecord, + * NVDataMgmtSelfTestResult + * Outputs: NVDataMgmtSelfTestResult, alarm if any of the CRC checks failed + * @return next state *************************************************************************/ static NVDATAMGMT_SELF_TEST_STATE_T handleSelfTestCheckCRC ( void ) { @@ -1176,13 +1197,13 @@ return state; } -/************************************************************************* - * @brief handleExecWaitForPostState - * The handleExecWaitForPostState waits for POST to be completed +/*********************************************************************//** + * @brief + * The handleExecWaitForPostState waits for POST to be completed. * @details - * Inputs : none - * Outputs : NVDATAMGMT_EXEC_STATE_T - * @return NVDATAMGMT_EXEC_STATE_T + * Inputs: NVDataMgmtSelfTestState + * Outputs: none + * @return next state *************************************************************************/ static NVDATAMGMT_EXEC_STATE_T handleExecWaitForPostState ( void ) { @@ -1196,14 +1217,14 @@ return state; } -/************************************************************************* - * @brief handleExecIdleState +/*********************************************************************//** + * @brief * The handleExecIdleState checks if the queue is empty and if it is not - * empty, it sets the state of the job + * empty, it sets the state of the job. * @details - * Inputs : none - * Outputs : NVDATAMGMT_EXEC_STATE_T - * @return NVDATAMGMT_EXEC_STATE_T + * Inputs: currentJob, currentTime + * Outputs: currentJob + * @return next state *************************************************************************/ static NVDATAMGMT_EXEC_STATE_T handleExecIdleState ( void ) { @@ -1264,14 +1285,14 @@ return state; } -/************************************************************************* - * @brief handleExecWriteToEEPROMState +/*********************************************************************//** + * @brief * The handleExecWriteToEEPROMState issues a write command to EEPROM on entry - * and if the write was successful, it sets the state to Idle + * and if the write was successful, it sets the state to Idle. * @details - * Inputs : none - * Outputs : NVDATAMGMT_EXEC_STATE_T - * @return NVDATAMGMT_EXEC_STATE_T + * Inputs: none + * Outputs: none + * @return next state *************************************************************************/ static NVDATAMGMT_EXEC_STATE_T handleExecWriteToEEPROMState ( void ) { @@ -1286,14 +1307,14 @@ return state; } -/************************************************************************* +/*********************************************************************//** * @brief handleExecReadFromEEPROMState * The handleExecReadFromEEPROMState issues a read command to EEPROM on entry - * and if the read was successful, it sets the state to Idle + * and if the read was successful, it sets the state to Idle. * @details - * Inputs : none - * Outputs : NVDATAMGMT_EXEC_STATE_T - * @return NVDATAMGMT_EXEC_STATE_T + * Inputs: currentJob + * Outputs: currentJob + * @return next state *************************************************************************/ static NVDATAMGMT_EXEC_STATE_T handleExecReadFromEEPROMState ( void ) { @@ -1309,14 +1330,14 @@ return state; } -/************************************************************************* - * @brief handleExecEraseState +/*********************************************************************//** + * @brief * The handleExecEraseState issues an erase command to EEPROM on entry - * and if the erase was successful, it sets the state to Idle + * and if the erase was successful, it sets the state to Idle. * @details - * Inputs : none - * Outputs : NVDATAMGMT_EXEC_STATE_T - * @return NVDATAMGMT_EXEC_STATE_T + * Inputs: none + * Outputs: none + * @return next state *************************************************************************/ static NVDATAMGMT_EXEC_STATE_T handleExecEraseState ( void ) { @@ -1331,15 +1352,15 @@ return state; } -/************************************************************************* - * @brief handleExecWriteToRAMState +/*********************************************************************//** + * @brief * The handleExecWriteToRAMState issues a write command to RTC RAM if the * RAM was ready, and if the RAM got back to Idle after the write command, - * it sets the state to Idle + * it sets the state to Idle. * @details - * Inputs : none - * Outputs : NVDATAMGMT_EXEC_STATE_T - * @return NVDATAMGMT_EXEC_STATE_T + * Inputs: none + * Outputs: none + * @return next state *************************************************************************/ static NVDATAMGMT_EXEC_STATE_T handleExecWriteToRAMState ( void ) { @@ -1354,16 +1375,16 @@ return state; } -/************************************************************************* - * @brief handleExecReadFromRAMState +/*********************************************************************//** + * @brief * The handleExecReadFromRAMState issues a read command to RTC RAM if the * RAM was ready, and if the RAM got back to Idle after the read command, * it calls another function to read the data back from RTC RAM and - * it sets the state to Idle + * it sets the state to Idle. * @details - * Inputs : none - * Outputs : NVDATAMGMT_EXEC_STATE_T - * @return NVDATAMGMT_EXEC_STATE_T + * Inputs: currentJob + * Outputs: currentJob + * @return next state *************************************************************************/ static NVDATAMGMT_EXEC_STATE_T handleExecReadFromRAMState ( void ) { @@ -1380,14 +1401,19 @@ return state; } -/************************************************************************* - * @brief setMemoryOpsStruct - * The setMemoryOpsStruct fills up the job struct +/*********************************************************************//** + * @brief + * The setMemoryOpsStruct fills up the job structure. * @details - * Inputs : NVDATAMGMT_OPERATION_STATE_T (ops), NVDATAMGMT_LOCATION_STATE_T - * (location), U32 (startAddress), U08* (data), READ_DATA_T* (extAddress) - * U32 (length) - * Outputs : none + * Inputs: jobQueue, queueCount, queueRearIndex + * Outputs: jobQueue, queueCount, queueRearIndex + * @param ops type of operation (i.e. write to EEPROM) + * @param location location of operation (i.e. RTC RAM) + * @param startAddress start address of operation + * @param data address to the data buffer + * @param extAddress address of the external buffer. Used for reading the log + * data by a client + * @param length length of data for operation * @return none *************************************************************************/ static void setMemoryOpsStruct ( NVDATAMGMT_OPERATION_STATE_T ops, NVDATAMGMT_LOCATION_STATE_T location, @@ -1416,16 +1442,17 @@ _enable_IRQ(); } -/************************************************************************* - * @brief prepareWriteLogJobAndGetStartAddress +/*********************************************************************//** + * @brief * The prepareWriteLogJobAndGetStartAddress checks whether the next write * is at edge of the any of the sectors and if yes, it will update the log * header accordingly. If the write is not at the edge, it will prepare a * normal write to EEPROM job. * @details - * Inputs : U08* (data) - * Outputs : U32 (opsStartAddress) - * @return U32 (opsStartAddress) + * Inputs: logRecord + * Outputs: logRecord + * @param data address of data buffer + * @return address of the next write as a U32 *************************************************************************/ static U32 prepareWriteLogJobAndGetStartAddress ( U08* data ) { @@ -1470,14 +1497,14 @@ return opsStartAddress; } -/************************************************************************* - * @brief prepareReadLogJobAndGetStartAddress +/*********************************************************************//** + * @brief * The prepareReadLogJobAndGetStartAddress prepares a read from the specified * address of the EEPROM. * @details - * Inputs : none - * Outputs : U32 (opsStartAddress) - * @return U32 (opsStartAddress) + * Inputs: logRecord + * Outputs: logRecord + * @return address of the next read as a U32 *************************************************************************/ static U32 prepareReadLogJobAndGetStartAddress ( void ) { @@ -1510,19 +1537,24 @@ return opsStartAddress; } -/************************************************************************* - * @brief enqueue +/*********************************************************************//** + * @brief * The enqueue prepares the jobs to be processed. It checks if the requested * job is read or write, or if it is RTC or EEPROM and sets the job struct. * It checks for the corner cases, for instance, if the next write log to EEPROM * is at the beginning of the next sector, it schedules and erase first and then * it schedules the write jobs. The function breaks the write to EEPROM jobs to - * 16 bytes at the time + * 16 bytes at the time. * @details - * Inputs : NVDATAMGMT_OPERATION_STATE_T (ops), NVDATAMGMT_LOCATION_STATE_T - * (location), U32 (startAddress), U08* (data), READ_DATA_T* (extAddress) - * U32 (length) - * Outputs : none + * Inputs: none + * Outputs: none + * @param ops type of operation (i.e. write to EEPROM) + * @param location location of operation (i.e. RTC RAM) + * @param startAddress start address of operation + * @param data address to the data buffer + * @param extAddress address of the external buffer. Used for reading the log + * data by a client + * @param length length of data for operation * @return none *************************************************************************/ static void enqueue ( NVDATAMGMT_OPERATION_STATE_T ops, NVDATAMGMT_LOCATION_STATE_T location, @@ -1538,6 +1570,9 @@ if ( ops == NVDATAMGMT_WRITE && location == NVDATAMGMT_EEPROM ) { maxBufferLength = MAX_EEPROM_WRITE_BUFFER_BYTES; + + // If the start address is 0, it means it is a data log and the start + // address must be found by referring to the log record header if ( startAddress == 0 ) { opsStartAddress = prepareWriteLogJobAndGetStartAddress ( data ); @@ -1546,6 +1581,8 @@ // Setup EEPROM read log event else if ( ops == NVDATAMGMT_READ && location == NVDATAMGMT_EEPROM ) { + // If the start address is 0, it means it is a data log and the start + // address must be found by referring to the log record header if ( startAddress == 0 ) { opsStartAddress = prepareReadLogJobAndGetStartAddress(); @@ -1577,13 +1614,13 @@ } } -/************************************************************************* - * @brief dequeue +/*********************************************************************//** + * @brief * The dequeue increments the front index counter and if it is equal to - * rear index, it sets it to -1, meaning that the queue is empty + * rear index, it sets it to -1, meaning that the queue is empty. * @details - * Inputs : none - * Outputs : none + * Inputs: queueFrontIndex, queueCount + * Outputs: queueFrontIndex, queueCount * @return none *************************************************************************/ static void dequeue ( void ) @@ -1604,14 +1641,14 @@ _enable_IRQ(); } -/************************************************************************* - * @brief isQueueEmpty +/*********************************************************************//** + * @brief * The isQueueEmpty checks whether the queue is empty and if it is empty, - * it will return a false + * it will return a false. * @details - * Inputs : none - * Outputs : isEmpty (BOOL) - * @return isEmpty (BOOL) + * Inputs: queueCount + * Outputs: none + * @return TRUE if queue is not empty *************************************************************************/ static BOOL isQueueEmpty ( void ) { @@ -1625,14 +1662,14 @@ return isEmpty; } -/************************************************************************* - * @brief isQueueFull +/*********************************************************************//** + * @brief * The isQueueFull checks whether the queue is full and if it is full, - * it will return a true + * it will return a true. * @details - * Inputs : none - * Outputs : isFull (BOOL) - * @return isFull (BOOL) + * Inputs: queueCount + * Outputs: none + * @return TRUE is queue is full *************************************************************************/ static BOOL isQueueFull ( void ) { @@ -1646,29 +1683,29 @@ return isFull; } -/************************************************************************* - * @brief getAvailableQueueCount - * The getAvailableQueueCount returns the number of available queues left +/*********************************************************************//** + * @brief + * The getAvailableQueueCount returns the number of available queues left. * @details - * Inputs : none - * Outputs : U32 - * @return U32 + * Inputs: queueCount + * Outputs: none + * @return available queue counts as a U32 *************************************************************************/ static U32 getAvailableQueueCount ( void ) { return QUEUE_MAX_SIZE - queueCount; } -/************************************************************************* - * @brief enqueueBank7Sector0Records +/*********************************************************************//** + * @brief * The enqueueBank7Sector0Records checks whether there are enough number of * queues for erasing and setting the records. If there are enough queues, * it schedules an erase job and then schdules jobs to write all the records - * back to Bank 7 Sector 0 + * back to Bank 7 Sector 0. * @details - * Inputs : none - * Outputs : BOOL - * @return BOOL + * Inputs: mfgRecord, calibrationRecord + * Outputs: none + * @return TRUE if there are enough queue jobs available *************************************************************************/ static BOOL enqueueBank7Sector0Records( void ) { @@ -1687,15 +1724,17 @@ return status; } -/************************************************************************* - * @brief didCommandTimedout +/*********************************************************************//** + * @brief * The didCommandTimedout checks whether the a command whether RTC RAM or * EEPROM has timedout. If it has timedout, it sets the alarm and turns - * flag to TRUE + * flag to TRUE. * @details - * Inputs : ALARM_ID_T (alarm), U08* state (pointer to the state) - * Outputs : BOOL - * @return BOOL + * Inputs: none + * Outputs: alarm if command timed out + * @param alarm alarm ID + * @param state the state that the command timed out + * @return TRUE if a command timed out *************************************************************************/ static BOOL didCommandTimeout ( ALARM_ID_T alarm, U08* state ) { @@ -1715,14 +1754,14 @@ return status; } -/************************************************************************* - * @brief eraseDataLogSectors +/*********************************************************************//** + * @brief * The eraseDataLogSectors checks whether there are enough queues available - * and if there are, it schedules 3 erases to erase sectors 1,2, and 3 + * and if there are, it schedules 3 erases to erase sectors 1,2, and 3. * @details - * Inputs : none - * Outputs : BOOL - * @return BOOL + * Inputs: none + * Outputs: non + * @return TRUE if there are enough queues available *************************************************************************/ static BOOL eraseDataLogSectors ( void ) { @@ -1739,3 +1778,5 @@ return status; } + +/**@}*/