Index: RTC.c =================================================================== diff -u -r13c32729e3186ebb5487e41a0cecd4cf15d357eb -r6c500be6ac0c5adffc0d91b666862e35ba27e2db --- RTC.c (.../RTC.c) (revision 13c32729e3186ebb5487e41a0cecd4cf15d357eb) +++ RTC.c (.../RTC.c) (revision 6c500be6ac0c5adffc0d91b666862e35ba27e2db) @@ -22,6 +22,11 @@ #include "SystemCommMessages.h" #include "OperationModes.h" +/** + * @addtogroup RTC + * @{ + */ + // ********** Definitions ********** #define RTC_REG_1_12_HOUR_MODE_MASK 0x0004 ///< 12-hour mode mask (0x0004) @@ -115,7 +120,7 @@ #define LOCAL_TO_GTM_TIME_CONVERSION 8U ///< Local time to GTM conversion for VectorCAST #endif -/// RTC self test state enums +/// RTC self test state enumeration. typedef enum RTC_Self_Test_States { RTC_SELF_TEST_STATE_START = 0, ///< Self test start @@ -127,7 +132,7 @@ NUM_OF_RTC_SELF_TEST_STATES ///< Total number of self test states } RTC_SELF_TEST_STATE_T; -/// Read date states enums +/// Read date states enumeration. typedef enum RTC_Read_Data { RTC_SEND_COMMAND = 0, ///< RTC send command @@ -136,7 +141,7 @@ NUM_OF_RTC_SERVICE_STATES ///< Total number of RTC read date states } RTC_GET_DATA_STATE_T; -/// RTC exec state enums +/// RTC exec state enumeration. typedef enum RTC_Exec_State { RTC_EXEC_STATE_WAIT_FOR_POST = 0, ///< Exec state wait for post @@ -150,7 +155,7 @@ } RTC_EXEC_STATE_T; #pragma pack(push,4) -/// Timestamp struct +/// Timestamp structure. typedef struct { U16 seconds; ///< Seconds @@ -222,12 +227,12 @@ // ********** Public functions ********** -/************************************************************************* - * @brief initRTC - * The initRTC initializes the RTC +/*********************************************************************//** + * @brief + * The initRTC initializes the RTC. * @details - * Inputs : none - * Outputs : The function is empty for now + * Inputs: RTCSelfTestState, RTCSelfTestState + * Outputs: RTCSelfTestState, RTCSelfTestState * @return none *************************************************************************/ void initRTC( void ) @@ -236,14 +241,20 @@ RTCServiceState = RTC_SEND_COMMAND; } -/************************************************************************* - * @brief setRTCTimestamp + /*********************************************************************//** + * @brief * The setRTCTimestamp gets the timestamp values, converts them into BCD - * and inserts them into the txBuffer to be written into the RTC + * and inserts them into the txBuffer to be written into the RTC. * @details - * Inputs : seconds, minutes, hours, days, months, years - * Outputs : txBuffer will be prepared with the timestamp - * @return none + * Inputs: RTCNewTimestampStruct, hasWriteToRTCRequested, isTimestampBufferReady + * Outputs: RTCNewTimestampStruct, hasWriteToRTCRequested, isTimestampBufferReady + * @param secs seconds + * @param mins minutes + * @param hours hours + * @param days days + * @param months months + * @param years years + * @return TRUE is the provided data is valid *************************************************************************/ BOOL setRTCTimestamp( U08 secs, U08 mins, U08 hours, U08 days, U08 months, U32 years ) { @@ -284,16 +295,17 @@ RTCNewTimestampStruct.months = months; RTCNewTimestampStruct.years = years; } + return isDataOk; } -/************************************************************************* - * @brief execRTCSelfTest - * The execRTCSelfTest runs the RTC POST during the self test +/*********************************************************************//** + * @brief + * The execRTCSelfTest runs the RTC POST during the self test. * @details - * Inputs : none - * Outputs : SELF_TEST_STATUS_T - * @return SELF_TEST_STATUS_T + * Inputs: RTCSelfTestState + * Outputs: RTCSelfTestState, alarm if invalid state was called + * @return RTCSelfTestResult the result of self test *************************************************************************/ SELF_TEST_STATUS_T execRTCSelfTest( void ) { @@ -344,12 +356,12 @@ return RTCSelfTestResult; } -/************************************************************************* - * @brief execRTC - * The execRTC runs the RTC during normal operations +/*********************************************************************//** + * @brief + * The execRTC runs the RTC during normal operations. * @details - * Inputs : none - * Outputs : none + * Inputs: RTCExecState + * Outputs: RTCExecState, alarm if invalid state was called * @return none *************************************************************************/ void execRTC( void ) @@ -403,29 +415,34 @@ } } -/************************************************************************* - * @brief getRTCTimestamp - * The getRTCTimestamp returns the current time in epoch +/*********************************************************************//** + * @brief + * The getRTCTimestamp returns the current time in epoch. * @details - * Inputs : none - * Outputs : current time in epoch - * @return lastEpochTime + * Inputs: lastEpochTime + * Outputs: none + * @return lastEpochTime the time in epoch as a U32 *************************************************************************/ U32 getRTCTimestamp( void ) { return lastEpochTime; } -/************************************************************************* - * @brief writeToRAM +/*********************************************************************//** + * @brief * The writeToRAM checks whether the RAM status is idle and if it is, it * will check input address and length to make sure they are within the * range. If everything is fine, it will prepare the txBuffer and set the - * RAM status to busy + * RAM status to busy. * @details - * Inputs : address, data, length - * Outputs : RTC_RAM_STATUS_T - * @return RTC_RAM_STATUS_T + * Inputs: RTCRAMStatus, RTCRAMState, hasWriteToRAMRequested, RAMBufferLength, + * prepRAMBuffer, txBuffer + * Outputs: RTCRAMStatus, RTCRAMState, hasWriteToRAMRequested, RAMBufferLength, + * prepRAMBuffer, txBuffer + * @param address address of the RTC RAM to write to + * @param data address of the data buffer to be written to RAM + * @param length length of the buffer + * @return status of the RTC RAM *************************************************************************/ RTC_RAM_STATUS_T writeToRAM( U32 address, U08* data, U32 length ) { @@ -460,19 +477,24 @@ } } } + return status; } -/************************************************************************* - * @brief readFromRAM +/*********************************************************************//** + * @brief * The readFromRAM checks whether the RAM status is idle and if it is, it * will check input address and length to make sure they are within the * range. If everything is fine, it will prepare the txBuffer and set the - * RAM status to busy + * RAM status to busy. * @details - * Inputs : address, length - * Outputs : RTC_RAM_STATUS_T - * @return RTC_RAM_STATUS_T + * Inputs: RTCRAMStatus, RTCRAMState, hasReadFromRAMRequested, RAMBufferLength, + * prepRAMBuffer, txBuffer + * Outputs: RTCRAMStatus, RTCRAMState, hasReadFromRAMRequested, RAMBufferLength, + * prepRAMBuffer, txBuffer + * @param address address of the RTC RAM to read data from + * @param length length of data to be read from RAM + * @return status of the RTC RAM *************************************************************************/ RTC_RAM_STATUS_T readFromRAM( U32 address, U32 length ) { @@ -510,27 +532,27 @@ return status; } -/************************************************************************* - * @brief getRTCRAMState - * The getRTCRAMState returns the RAM state +/*********************************************************************//** + * @brief + * The getRTCRAMState returns the RAM state. * @details - * Inputs : none - * Outputs : RTC_RAM_STATE_T - * @return RTC_RAM_STATE_T + * Inputs: RTCRAMState + * Outputs: none + * @return RTC RAM state *************************************************************************/ RTC_RAM_STATE_T getRTCRAMState( void ) { return RTCRAMState; } -/************************************************************************* - * @brief getRTCRAMStatus +/*********************************************************************//** + * @brief * The getRTCRAMStatus returns the RAM state. If the RAM status is complete - * it will set the RAM status to Idle and the RAM state to Ready + * it will set the RAM status to Idle and the RAM state to Ready. * @details - * Inputs : none - * Outputs : RTC_RAM_STATE_T - * @return RTC_RAM_STATE_T + * Inputs: RTCRAMStatus, RTCRAMState + * Outputs: RTCRAMStatus, RTCRAMState + * @return RTC RAM status *************************************************************************/ RTC_RAM_STATUS_T getRTCRAMStatus( void ) { @@ -543,13 +565,15 @@ return RTCRAMStatus; } -/************************************************************************* - * @brief getDataFromRAM +/*********************************************************************//** + * @brief * The getDataFromRAM populates the provided external buffer with the data - * in the specified address in the RAM + * in the specified address in the RAM. * @details - * Inputs : external buffer (pointer), length - * Outputs : none + * Inputs: RAMBuffer + * Outputs: none + * @param externalBuffer address of the external buffer to copy data into + * @param length length of data to be copied into buffer * @return none *************************************************************************/ void getDataFromRAM( U08* externalBuffer, U32 length ) @@ -563,6 +587,7 @@ // ********** Private functions ********* +//TODO fill up the functions /*void mibspiNotification(mibspiBASE_t *mibspi, uint32 flags) { @@ -573,20 +598,21 @@ } */ - -/************************************************************************* - * @brief serviceRTC +/*********************************************************************//** + * @brief * The serviceRTC is the interface to the RTC chip: * If it was called for the first time, it will send the command * If the provided buffer length is not the same as previous, it will * set the buffer length. Otherwise it will ignore it * If it was not called for the first time, it will wait to the buffer * to be transmitted and then it will populate the provided receive buffer - * If the transaction failed, it will try 3 time before it fails + * If the transaction failed, it will try 3 time before it fails. * @details - * Inputs : bufferTransmit, bufferReceive, bufferLength - * Outputs : result (bool) - * @return result (bool) + * Inputs : isRTCServiceOnEntry, RTCServiceState, numberOfFailedRTCTransfers, + * previousTransferLength + * Outputs: isRTCServiceOnEntry, RTCServiceState, numberOfFailedRTCTransfers, + * previousTransferLength + * @return TRUE if RTC operation was successful *************************************************************************/ static BOOL serviceRTC( U16* bufferTransmit, U16* bufferReceive, U16 bufferLength ) { @@ -661,15 +687,15 @@ return result; } -/************************************************************************* - * @brief isRTCFunctional +/*********************************************************************//** + * @brief * The isRTCFunctional checks whether the RTC is still functional by checking * the bits in the first 3 control registers. The function ignore the clear - * flags + * flags. * @details - * Inputs : none - * Outputs : hasTestPassed (bool) - * @return hasTestPassed (bool) + * Inputs: rxBuffer + * Outputs: alarm if any of the control registers are at fault + * @return TRUE if the control registers are normal *************************************************************************/ static BOOL isRTCFunctional( void ) { @@ -723,13 +749,14 @@ return hasTestPassed; } -/************************************************************************* - * @brief convertBCD2Decimal - * The convertBCD2Decimal converts the BCD values to decimal +/*********************************************************************//** + * @brief + * The convertBCD2Decimal converts the BCD values to decimal. * @details - * Inputs : bcd value - * Outputs : decimal value - * @return decimal value + * Inputs: none + * Outputs: none + * @param bcd the number in bcd + * @return number is decimal a U08 *************************************************************************/ static U08 convertBCD2Decimal( U08 bcd ) { @@ -748,16 +775,18 @@ { decimal = ( bcdHigh * TEN ) + bcdLow; } + return decimal; } -/************************************************************************* - * @brief convertDecimal2BCD - * The convertDecimal2BCD converts the decimal values to BCD +/*********************************************************************//** + * @brief + * The convertDecimal2BCD converts the decimal values to BCD. * @details - * Inputs : decimal value - * Outputs : bcd value - * @return bcd value + * Inputs: none + * Outputs: none + * @param decimal number if decimal + * @return number in bcd as a U08 *************************************************************************/ static U08 convertDecimal2BCD( U08 decimal ) { @@ -777,13 +806,13 @@ return bcd; } -/************************************************************************* - * @brief convertTime2Epoch - * The convertTime2Epoch converts the time into epoch (seconds from Jan 1 1970) +/*********************************************************************//** + * @brief + * The convertTime2Epoch converts the time into epoch (seconds from Jan 1 1970). * @details - * Inputs : none - * Outputs : epochTime value - * @return epochTime value + * Inputs: RTCTimestampStruct + * Outputs: none + * @return time in epoch as a U32 *************************************************************************/ static U32 convertTime2Epoch( void ) { @@ -815,13 +844,13 @@ return (U32)epochTime; } -/************************************************************************* - * @brief updateReadTimestampStruct - * The updateReadTimestampStruct function updates the time struct after every - * read +/*********************************************************************//** + * @brief + * The updateReadTimestampStruct function updates the time structure + * after every read. * @details - * Inputs : none - * Outputs : none + * Inputs: RTCTimestampStruct + * Outputs: RTCTimestampStruct * @return none *************************************************************************/ static void updateReadTimestampStruct( void ) @@ -835,14 +864,15 @@ RTCTimestampStruct.years = convertBCD2Decimal( rxBuffer[ RTC_YEARS_INDEX ] ); } -/************************************************************************* - * @brief setMibSPIBufferLength +/*********************************************************************//** + * @brief * The setMibSPIBufferLength sets the MibSPI buffer length prior to every - * RTC transaction + * RTC transaction. * @details - * Inputs : length - * Outputs : ransferStatus (bool) - * @return transferStatus (bool) + * Inputs: none + * Outputs: none + * @param length length of data transfer in bytes + * @return TRUE if the buffer length was set successfully *************************************************************************/ static BOOL setMibSPIBufferLength( U16 length ) { @@ -907,12 +937,13 @@ return transferStatus; } -/************************************************************************* - * @brief prepBufferForReadCommand - * The prepBufferForReadCommand sets the txBuffer for a read +/*********************************************************************//** + * @brief + * The prepBufferForReadCommand sets the txBuffer for a read. * @details - * Inputs : length - * Outputs : none + * Inputs: txBuffer + * Outputs: txBuffer + * @param length length of buffer to read * @return none *************************************************************************/ static void prepBufferForReadCommand( U08 length ) @@ -926,14 +957,14 @@ } } -/************************************************************************* - * @brief handleExecWaitForPostState +/*********************************************************************//** + * @brief * The handleExecWaitForPostState checks whether POST has completed and what - * was the result of the POST test. It will either go to Idle of Fault + * was the result of the POST test. It will either go to Idle of Fault. * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * Inputs: RTCSelfTestState + * Outputs: none + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecWaitForPostState( void ) { @@ -947,15 +978,16 @@ return result; } -/************************************************************************* - * @brief handleExecIdleState +/*********************************************************************//** + * @brief * The handleExecIdleState checks whether read or write to RTC or RAM has * been requested. If none of them have been requested, it will increment the - * timer + * timer. * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * Inputs: nohasWriteToRTCRequested, hasWriteToRAMRequested, + * hasReadFromRAMRequested, timeCounter + * Outputs: timeCounter + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecIdleState( void ) { @@ -986,13 +1018,15 @@ return result; } -/************************************************************************* - * @brief handleExecWriteState - * The handleExecWriteState writes timestamp to RTC +/*********************************************************************//** + * @brief + * The handleExecWriteState writes timestamp to RTC. * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * Inputs: isTimestampBufferReady, txBuffer, hasWriteToRTCRequested, + * timeCounter, RTCServiceState + * Outputs: isTimestampBufferReady, txBuffer, hasWriteToRTCRequested, + * timeCounter, alarm if any RTC RAM operations occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecWriteState( void ) { @@ -1032,13 +1066,14 @@ return result; } -/************************************************************************* - * @brief handleExecPrepRAMState - * The handleExecPrepRAMState prepares the RAM for read or write +/*********************************************************************//** + * @brief + * The handleExecPrepRAMState prepares the RAM for read or write. * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * Inputs: RTCServiceState, hasWriteToRAMRequested, hasReadFromRAMRequested, + * prepRAMBuffer, RAMBuffer + * Outputs: alarm if any RTC RAM operations error occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecPrepRAMState( void ) { @@ -1065,13 +1100,15 @@ return result; } -/************************************************************************* - * @brief handleExecWriteToRAMState - * The handleExecWriteToRAMState writes to RAM +/*********************************************************************//** + * @brief + * The handleExecWriteToRAMState writes to RAM. * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * Inputs: RTCServiceState, hasWriteToRAMRequested, RTCRAMStatus, txBuffer, + * RAMBuffer, RAMBufferLength + * Outputs: hasWriteToRAMRequested, RTCRAMStatus, alarm if any RTC RAM + * operations errors occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecWriteToRAMState( void ) { @@ -1095,13 +1132,15 @@ return result; } -/************************************************************************* - * @brief handleExecReadFromRAMState - * The handleExecReadFromRAMState read from RAM +/*********************************************************************//** + * @brief + * The handleExecReadFromRAMState read from RAM. * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * Inputs: RTCServiceState, hasReadFromRAMRequested, RTCRAMStatus, txBuffer, + * RAMBuffer, RAMBufferLength + * Outputs: hasReadFromRAMRequested, RTCRAMStatus, alarm if any RTC RAM + * operations errors occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecReadFromRAMState( void ) { @@ -1125,15 +1164,16 @@ return result; } -/************************************************************************* - * @brief handleExecReadState - * The handleExecReadState reads timestamp from RTC. The function calls - * other functions to update the time struct and convert the latest time - * to epoch +/*********************************************************************//** + * @brief + * The handleExecReadState reads timestamp from RTC. The function calls + * other functions to update the time structure and convert the latest time + * to epoch. * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * Inputs: RTCServiceState, lastEpochTime, timeCounter, txBuffer, rxBuffer + * Outputs: lastEpochTime, timeCounter, alarm if any RTC operations error + * occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecReadState( void ) { @@ -1161,14 +1201,14 @@ return result; } -/************************************************************************* - * @brief handleSelfTestStart +/*********************************************************************//** + * @brief * The handleSelfTestStart calls another function to prepare the txBuffer - * for a read and sets the state to control registers + * for a read and sets the state to control registers. * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * Inputs: RTCSelfTestResult + * Outputs: RTCSelfTestResult + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestStart( void ) { @@ -1180,16 +1220,17 @@ return result; } -/************************************************************************* - * @brief handleSelfTestCheckCtrlRegs +/*********************************************************************//** + * @brief * The handleSelfTestCheckCtrlRegs receives the control registers and calls * another function to check whether RTC is function or not. If the RTC is * functional, it will update the RTCPreviousSecond variable and sets the - * state machine to the next state + * state machine to the next state. * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * Inputs: RTCServiceState, txBuffer, rxBuffer, RTCPreviousSecond, + * RTCSelfTestResult + * Outputs: RTCPreviousSecond, RTCSelfTestResult + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestCheckCtrlRegs( void ) { @@ -1219,15 +1260,16 @@ return result; } -/************************************************************************* - * @brief handleSelfTestWaitForFirstSecond +/*********************************************************************//** + * @brief * The handleSelfTestWaitForFirstSecond continuously reads the RTC and compares * latest second from RTC to the previous second and if it has changed, it will - * start the timer and set the state machine to the next state + * start the timer and set the state machine to the next state. * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * Inputs: RTCServiceState, txBuffer, rxBuffer, RTCCurrentSecond, RTCSelfTestTimer, + * RTCPreviousSecond + * Outputs: RTCCurrentSecond, RTCSelfTestTimer, RTCPreviousSecond + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestWaitForFirstSecond( void ) { @@ -1263,15 +1305,15 @@ return result; } -/************************************************************************* - * @brief handleSelfTestWaitForSecondSecond +/*********************************************************************//** + * @brief * The handleSelfTestWaitForSecondSecond continuously reads the RTC and compares * latest second from RTC to the previous second and if it has changed, it will - * set the state machine to the next state + * set the state machine to the next state. * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * Inputs: RTCServiceState, txBuffer, rxBuffer, RTCCurrentSecond + * Outputs: RTCCurrentSecond + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestWaitForSecondSecond( void ) { @@ -1304,16 +1346,17 @@ return result; } -/************************************************************************* - * @brief handleSelfTestCheckAccuracy +/*********************************************************************//** + * @brief * The handleSelfTestCheckAccuracy checks whether the time has been elapsed * within the specified time tolerance. It will call another function to check * whether one second has elapsed. If the time has elapsed, how much time has - * passed since the last second that was read from RTC + * passed since the last second that was read from RTC. * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * Inputs: RTCSelfTestTimer, RTCSelfTestResult + * Outputs : RTCSelfTestTimer, RTCSelfTestResult, alarm if RTC time accuracy + * test failed + * @return Next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestCheckAccuracy( void ) { @@ -1338,3 +1381,5 @@ return result; } + +/**@}*/