Index: RTC.c =================================================================== diff -u -rcf2afaec02799525f80e803b55a0f55948c75cad -r0f1d0c443daee3e30ae823711e85f3410bbf49fe --- RTC.c (.../RTC.c) (revision cf2afaec02799525f80e803b55a0f55948c75cad) +++ RTC.c (.../RTC.c) (revision 0f1d0c443daee3e30ae823711e85f3410bbf49fe) @@ -1,14 +1,14 @@ /************************************************************************** * -* Copyright (c) 2019-2020 Diality Inc. - All Rights Reserved. +* Copyright (c) 2019-2021 Diality Inc. - All Rights Reserved. * * THIS CODE MAY NOT BE COPIED OR REPRODUCED IN ANY FORM, IN PART OR IN * WHOLE, WITHOUT THE EXPLICIT PERMISSION OF THE COPYRIGHT OWNER. * * @file RTC.c * * @author (last) Sean Nash -* @date (last) 21-Jul-2020 +* @date (last) 01-Oct-2020 * * @author (original) Dara Navaei * @date (original) 11-Jan-2020 @@ -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,19 +120,19 @@ #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 RTC_SELF_TEST_STATE_CHECK_CTRL_REGS, ///< Self test check control registers RTC_SELF_TEST_STATE_WAIT_FOR_FIRST_SECOND, ///< Self test wait for first second RTC_SELF_TEST_STATE_WAIT_FOR_SECOND_SECOND, ///< Self test wait for second second - RTC_SELF_TEST_STATE_CHECK_ACCURACY, ///< Self test check time accuracy + RTC_SELF_TEST_STATE_CHECK_ACCURACY, ///< Self test check time accuracy (compare 1st to 2nd second vs. timer counter) RTC_SELF_TEST_STATE_COMPLETE, ///< Self test complete - NUM_OF_RTC_SELF_TEST_STATES ///< Total number of self test states + 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 @@ -165,35 +170,35 @@ // ********** private data ********** -static RTC_SELF_TEST_STATE_T RTCSelfTestState = RTC_SELF_TEST_STATE_START; ///< Self test variable -static RTC_GET_DATA_STATE_T RTCServiceState = RTC_SEND_COMMAND; ///< RTC get data variable -static RTC_EXEC_STATE_T RTCExecState = RTC_EXEC_STATE_WAIT_FOR_POST; ///< RTC exec state variable -static SELF_TEST_STATUS_T RTCSelfTestResult = SELF_TEST_STATUS_IN_PROGRESS; ///< RTC self test status variable -static RTC_RAM_STATUS_T RTCRAMStatus = RTC_RAM_STATUS_IDLE; ///< RTC RAM status variable -static RTC_RAM_STATE_T RTCRAMState = RTC_RAM_STATE_READY; ///< RTC RAM state -static RTC_TIMESTAMP_T RTCTimestampStruct; ///< Timestamp struct -static RTC_TIMESTAMP_T RTCNewTimestampStruct; ///< New timestamp struct +static RTC_SELF_TEST_STATE_T RTCSelfTestState = RTC_SELF_TEST_STATE_START; ///< Self test variable. +static RTC_GET_DATA_STATE_T RTCServiceState = RTC_SEND_COMMAND; ///< RTC get data variable. +static RTC_EXEC_STATE_T RTCExecState = RTC_EXEC_STATE_WAIT_FOR_POST; ///< RTC exec state variable. +static SELF_TEST_STATUS_T RTCSelfTestResult = SELF_TEST_STATUS_IN_PROGRESS; ///< RTC self-test status variable. +static RTC_RAM_STATUS_T RTCRAMStatus = RTC_RAM_STATUS_IDLE; ///< RTC RAM status variable. +static RTC_RAM_STATE_T RTCRAMState = RTC_RAM_STATE_READY; ///< RTC RAM state. +static RTC_TIMESTAMP_T RTCTimestampStruct; ///< Timestamp record - last read from RTC. +static RTC_TIMESTAMP_T RTCNewTimestampStruct; ///< New timestamp record that will hold the new time to be written to RTC. -static U32 RTCSelfTestTimer = 0; ///< Self test timer -static U32 RTCPreviousSecond = 0; ///< Previous second -static U32 RAMBufferLength = 0; ///< RAM buffer length -static U32 lastEpochTime = 0; ///< last epoch time -static U32 previousTransferLength = 0; ///< Previous transfer length +static U32 RTCSelfTestTimer = 0; ///< Self test timer. +static U32 RTCPreviousSecond = 0; ///< Previous second for self-test comparison. +static U32 RAMBufferLength = 0; ///< RAM buffer length for RAM operations. +static U32 lastEpochTime = 0; ///< last epoch time. +static U32 previousTransferLength = 0; ///< Previous transfer length. -static U32 timeCounter = 1; ///< Initial time counter (1) -static U32 numberOfFailedRTCTransfers = 1; ///< Initial number of failed RTC transactions (1) +static U32 timeCounter = 1; ///< Initial time counter (1). +static U32 numberOfFailedRTCTransfers = 1; ///< Initial number of failed RTC transactions (1). -static BOOL hasWriteToRTCRequested = FALSE; ///< Flag to request RTC write -static BOOL hasWriteToRAMRequested = FALSE; ///< Flag to write to RTC RAM -static BOOL hasReadFromRAMRequested = FALSE; ///< Flag to read from RTC RAM -static BOOL isRTCServiceOnEntry = FALSE; ///< Flag to check if service is on entry -static BOOL isTimestampBufferReady = FALSE; ///< Flag to check if the timestamp buffer is ready +static BOOL hasWriteToRTCRequested = FALSE; ///< Flag to request RTC write. +static BOOL hasWriteToRAMRequested = FALSE; ///< Flag to write to RTC RAM. +static BOOL hasReadFromRAMRequested = FALSE; ///< Flag to read from RTC RAM. +static BOOL isRTCServiceOnEntry = FALSE; ///< Flag to check if service is on entry. +static BOOL isTimestampBufferReady = FALSE; ///< Flag to check if the timestamp buffer is ready. -static U16 rxBuffer[ MIBSPI_MAX_BUFFER_LENGTH + 1 ]; ///< Buffer to receive data from RTC -static U16 txBuffer[ MIBSPI_MAX_BUFFER_LENGTH + 1 ]; ///< Buffer to transmit data to RTC +static U16 rxBuffer[ MIBSPI_MAX_BUFFER_LENGTH + 1 ]; ///< Buffer to receive data from RTC. +static U16 txBuffer[ MIBSPI_MAX_BUFFER_LENGTH + 1 ]; ///< Buffer to transmit data to RTC. -static U16 prepRAMBuffer[ RTC_RAM_PREP_BUFFER_LENGTH ]; ///< Buffer to send prep commands to RTC RAM -static U16 RAMBuffer[ MIBSPI_MAX_BUFFER_LENGTH ]; ///< Buffer to read RTC RAM data +static U16 prepRAMBuffer[ RTC_RAM_PREP_BUFFER_LENGTH ]; ///< Buffer to send prep read/write commands to RTC RAM. +static U16 RAMBuffer[ MIBSPI_MAX_BUFFER_LENGTH ]; ///< Buffer to read RTC RAM data. // ********** Private function prototypes ********* @@ -222,12 +227,11 @@ // ********** Public functions ********** -/************************************************************************* - * @brief initRTC - * The initRTC initializes the RTC - * @details - * Inputs : none - * Outputs : The function is empty for now +/*********************************************************************//** + * @brief + * The initRTC initializes the RTC module. + * @details Inputs: RTCSelfTestState, RTCSelfTestState + * @details Outputs: RTCSelfTestState, RTCSelfTestState * @return none *************************************************************************/ void initRTC( void ) @@ -236,18 +240,24 @@ RTCServiceState = RTC_SEND_COMMAND; } -/************************************************************************* - * @brief setRTCTimestamp - * The setRTCTimestamp gets the timestamp values, converts them into BCD - * 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 + /*********************************************************************//** + * @brief + * The setRTCTimestamp gets the timestamp values from caller, converts them + * into BCD format and inserts them into the txBuffer to be written into the RTC. + * @details Inputs: RTCNewTimestampStruct, hasWriteToRTCRequested, isTimestampBufferReady + * @details 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 ) { BOOL isDataOk = TRUE; + if ( secs > MAX_ALLOWED_SECONDS ) { isDataOk = FALSE; @@ -284,16 +294,16 @@ RTCNewTimestampStruct.months = months; RTCNewTimestampStruct.years = years; } + return isDataOk; } -/************************************************************************* - * @brief execRTCSelfTest - * The execRTCSelfTest runs the RTC POST during the self test - * @details - * Inputs : none - * Outputs : SELF_TEST_STATUS_T - * @return SELF_TEST_STATUS_T +/*********************************************************************//** + * @brief + * The execRTCSelfTest runs the RTC POST during the self-test. + * @details Inputs: RTCSelfTestState + * @details Outputs: RTCSelfTestState, alarm if invalid state was called + * @return RTCSelfTestResult the result of self-test *************************************************************************/ SELF_TEST_STATUS_T execRTCSelfTest( void ) { @@ -344,12 +354,11 @@ return RTCSelfTestResult; } -/************************************************************************* - * @brief execRTC - * The execRTC runs the RTC during normal operations - * @details - * Inputs : none - * Outputs : none +/*********************************************************************//** + * @brief + * The execRTC function executes a signle pass of the RTC monitor state machine. + * @details Inputs: RTCExecState + * @details Outputs: RTCExecState, alarm if invalid state was called * @return none *************************************************************************/ void execRTC( void ) @@ -403,34 +412,38 @@ } } -/************************************************************************* - * @brief getRTCTimestamp - * The getRTCTimestamp returns the current time in epoch - * @details - * Inputs : none - * Outputs : current time in epoch - * @return lastEpochTime +/*********************************************************************//** + * @brief + * The getRTCTimestamp returns the current time in epoch format. + * @details Inputs: lastEpochTime + * @details 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 - * @details - * Inputs : address, data, length - * Outputs : RTC_RAM_STATUS_T - * @return RTC_RAM_STATUS_T + * RAM status to busy. + * @details Inputs: RTCRAMStatus, RTCRAMState, hasWriteToRAMRequested, RAMBufferLength, + * prepRAMBuffer, txBuffer + * @details 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 ) { RTC_RAM_STATUS_T status = RTCRAMStatus; U16 castedAddress = (U16)( address & MASK_OFF_MSW ); + if ( status == RTC_RAM_STATUS_IDLE ) { if ( castedAddress > MAX_ALLOWED_RTC_RAM_ADDRESS ) @@ -444,6 +457,7 @@ else { U08 i; + RTCRAMStatus = status = RTC_RAM_STATUS_IN_PROGRESS; RTCRAMState = RTC_RAM_STATE_BUSY; hasWriteToRAMRequested = TRUE; @@ -460,24 +474,29 @@ } } } + 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 - * @details - * Inputs : address, length - * Outputs : RTC_RAM_STATUS_T - * @return RTC_RAM_STATUS_T + * RAM status to busy. + * @details Inputs: RTCRAMStatus, RTCRAMState, hasReadFromRAMRequested, RAMBufferLength, + * prepRAMBuffer, txBuffer + * @details 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 ) { RTC_RAM_STATUS_T status = RTCRAMStatus; U16 castedAddress = (U16)( address & MASK_OFF_MSW ); + if ( status == RTC_RAM_STATUS_IDLE ) { if ( castedAddress > MAX_ALLOWED_RTC_RAM_ADDRESS ) @@ -491,6 +510,7 @@ else { U08 i; + status = RTCRAMStatus = RTC_RAM_STATUS_IN_PROGRESS; RTCRAMState = RTC_RAM_STATE_BUSY; hasReadFromRAMRequested = TRUE; @@ -510,27 +530,25 @@ return status; } -/************************************************************************* - * @brief getRTCRAMState - * The getRTCRAMState returns the RAM state - * @details - * Inputs : none - * Outputs : RTC_RAM_STATE_T - * @return RTC_RAM_STATE_T +/*********************************************************************//** + * @brief + * The getRTCRAMState returns the RAM state. + * @details Inputs: RTCRAMState + * @details Outputs: none + * @return RTC RAM state *************************************************************************/ RTC_RAM_STATE_T getRTCRAMState( void ) { return RTCRAMState; } -/************************************************************************* - * @brief getRTCRAMStatus - * 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 - * @details - * Inputs : none - * Outputs : RTC_RAM_STATE_T - * @return RTC_RAM_STATE_T +/*********************************************************************//** + * @brief + * The getRTCRAMStatus returns the RAM status. If the RAM status is complete + * it will set the RAM status to Idle and the RAM state to Ready. + * @details Inputs: RTCRAMStatus, RTCRAMState + * @details Outputs: RTCRAMStatus, RTCRAMState + * @return RTC RAM status *************************************************************************/ RTC_RAM_STATUS_T getRTCRAMStatus( void ) { @@ -543,13 +561,14 @@ return RTCRAMStatus; } -/************************************************************************* - * @brief getDataFromRAM +/*********************************************************************//** + * @brief * The getDataFromRAM populates the provided external buffer with the data - * in the specified address in the RAM - * @details - * Inputs : external buffer (pointer), length - * Outputs : none + * in the specified address in the RTC RAM. + * @details Inputs: RAMBuffer + * @details 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 ) @@ -561,8 +580,7 @@ } } -// ********** Private functions ********* - +//TODO fill up the functions /*void mibspiNotification(mibspiBASE_t *mibspi, uint32 flags) { @@ -573,20 +591,20 @@ } */ - -/************************************************************************* - * @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 - * @details - * Inputs : bufferTransmit, bufferReceive, bufferLength - * Outputs : result (bool) - * @return result (bool) + * If the transaction failed, it will try 3 time before it fails. + * @details Inputs: isRTCServiceOnEntry, RTCServiceState, numberOfFailedRTCTransfers, + * previousTransferLength + * @details Outputs: isRTCServiceOnEntry, RTCServiceState, numberOfFailedRTCTransfers, + * previousTransferLength + * @return TRUE if RTC operation was successful *************************************************************************/ static BOOL serviceRTC( U16* bufferTransmit, U16* bufferReceive, U16 bufferLength ) { @@ -661,15 +679,14 @@ 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 - * @details - * Inputs : none - * Outputs : hasTestPassed (bool) - * @return hasTestPassed (bool) + * flags. + * @details Inputs: rxBuffer + * @details 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 +740,13 @@ return hasTestPassed; } -/************************************************************************* - * @brief convertBCD2Decimal - * The convertBCD2Decimal converts the BCD values to decimal - * @details - * Inputs : bcd value - * Outputs : decimal value - * @return decimal value +/*********************************************************************//** + * @brief + * The convertBCD2Decimal converts the BCD values to decimal. + * @details Inputs: none + * @details Outputs: none + * @param bcd the number in bcd + * @return number is decimal a U08 *************************************************************************/ static U08 convertBCD2Decimal( U08 bcd ) { @@ -748,16 +765,17 @@ { decimal = ( bcdHigh * TEN ) + bcdLow; } + return decimal; } -/************************************************************************* - * @brief convertDecimal2BCD - * The convertDecimal2BCD converts the decimal values to BCD - * @details - * Inputs : decimal value - * Outputs : bcd value - * @return bcd value +/*********************************************************************//** + * @brief + * The convertDecimal2BCD converts the decimal values to BCD. + * @details Inputs: none + * @details Outputs: none + * @param decimal number if decimal + * @return number in bcd as a U08 *************************************************************************/ static U08 convertDecimal2BCD( U08 decimal ) { @@ -777,13 +795,12 @@ return bcd; } -/************************************************************************* - * @brief convertTime2Epoch - * The convertTime2Epoch converts the time into epoch (seconds from Jan 1 1970) - * @details - * Inputs : none - * Outputs : epochTime value - * @return epochTime value +/*********************************************************************//** + * @brief + * The convertTime2Epoch converts the time into epoch (seconds from Jan 1 1970). + * @details Inputs: RTCTimestampStruct + * @details Outputs: none + * @return time in epoch as a U32 *************************************************************************/ static U32 convertTime2Epoch( void ) { @@ -815,13 +832,12 @@ return (U32)epochTime; } -/************************************************************************* - * @brief updateReadTimestampStruct - * The updateReadTimestampStruct function updates the time struct after every - * read - * @details - * Inputs : none - * Outputs : none +/*********************************************************************//** + * @brief + * The updateReadTimestampStruct function updates the time structure + * after every read. + * @details Inputs: RTCTimestampStruct + * @details Outputs: RTCTimestampStruct * @return none *************************************************************************/ static void updateReadTimestampStruct( void ) @@ -835,14 +851,14 @@ RTCTimestampStruct.years = convertBCD2Decimal( rxBuffer[ RTC_YEARS_INDEX ] ); } -/************************************************************************* - * @brief setMibSPIBufferLength +/*********************************************************************//** + * @brief * The setMibSPIBufferLength sets the MibSPI buffer length prior to every - * RTC transaction - * @details - * Inputs : length - * Outputs : ransferStatus (bool) - * @return transferStatus (bool) + * RTC transaction. + * @details Inputs: none + * @details 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 +923,12 @@ return transferStatus; } -/************************************************************************* - * @brief prepBufferForReadCommand - * The prepBufferForReadCommand sets the txBuffer for a read - * @details - * Inputs : length - * Outputs : none +/*********************************************************************//** + * @brief + * The prepBufferForReadCommand sets the txBuffer for a read. + * @details Inputs: txBuffer + * @details Outputs: txBuffer + * @param length length of buffer to read * @return none *************************************************************************/ static void prepBufferForReadCommand( U08 length ) @@ -926,14 +942,13 @@ } } -/************************************************************************* - * @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 - * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * was the result of the POST test. It will either go to Idle of Fault. + * @details Inputs: RTCSelfTestState + * @details Outputs: none + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecWaitForPostState( void ) { @@ -947,15 +962,15 @@ 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 - * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) + * timer. + * @details Inputs: nohasWriteToRTCRequested, hasWriteToRAMRequested, + * hasReadFromRAMRequested, timeCounter + * @details Outputs: timeCounter + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecIdleState( void ) { @@ -986,13 +1001,14 @@ return result; } -/************************************************************************* - * @brief handleExecWriteState - * The handleExecWriteState writes timestamp to RTC - * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) +/*********************************************************************//** + * @brief + * The handleExecWriteState writes timestamp to RTC. + * @details Inputs: isTimestampBufferReady, txBuffer, hasWriteToRTCRequested, + * timeCounter, RTCServiceState + * @details Outputs: isTimestampBufferReady, txBuffer, hasWriteToRTCRequested, + * timeCounter, alarm if any RTC RAM operations occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecWriteState( void ) { @@ -1032,13 +1048,13 @@ return result; } -/************************************************************************* - * @brief handleExecPrepRAMState - * The handleExecPrepRAMState prepares the RAM for read or write - * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) +/*********************************************************************//** + * @brief + * The handleExecPrepRAMState prepares the RAM for read or write. + * @details Inputs: RTCServiceState, hasWriteToRAMRequested, hasReadFromRAMRequested, + * prepRAMBuffer, RAMBuffer + * @details Outputs: alarm if any RTC RAM operations error occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecPrepRAMState( void ) { @@ -1065,13 +1081,14 @@ return result; } -/************************************************************************* - * @brief handleExecWriteToRAMState - * The handleExecWriteToRAMState writes to RAM - * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) +/*********************************************************************//** + * @brief + * The handleExecWriteToRAMState writes to RAM. + * @details Inputs: RTCServiceState, hasWriteToRAMRequested, RTCRAMStatus, txBuffer, + * RAMBuffer, RAMBufferLength + * @details Outputs: hasWriteToRAMRequested, RTCRAMStatus, alarm if any RTC RAM + * operations errors occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecWriteToRAMState( void ) { @@ -1095,13 +1112,14 @@ return result; } -/************************************************************************* - * @brief handleExecReadFromRAMState - * The handleExecReadFromRAMState read from RAM - * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) +/*********************************************************************//** + * @brief + * The handleExecReadFromRAMState read from RAM. + * @details Inputs: RTCServiceState, hasReadFromRAMRequested, RTCRAMStatus, txBuffer, + * RAMBuffer, RAMBufferLength + * @details Outputs: hasReadFromRAMRequested, RTCRAMStatus, alarm if any RTC RAM + * operations errors occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecReadFromRAMState( void ) { @@ -1125,15 +1143,15 @@ 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 - * @details - * Inputs : none - * Outputs : result (RTC_EXEC_STATE_T) - * @return result (RTC_EXEC_STATE_T) +/*********************************************************************//** + * @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: RTCServiceState, lastEpochTime, timeCounter, txBuffer, rxBuffer + * @details Outputs: lastEpochTime, timeCounter, alarm if any RTC operations error + * occurred + * @return next state *************************************************************************/ static RTC_EXEC_STATE_T handleExecReadState( void ) { @@ -1161,14 +1179,13 @@ return result; } -/************************************************************************* - * @brief handleSelfTestStart +/*********************************************************************//** + * @brief * The handleSelfTestStart calls another function to prepare the txBuffer - * 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) + * for a read and sets the state to control registers. + * @details Inputs: RTCSelfTestResult + * @details Outputs: RTCSelfTestResult + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestStart( void ) { @@ -1180,16 +1197,16 @@ 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 - * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * state machine to the next state. + * @details Inputs: RTCServiceState, txBuffer, rxBuffer, RTCPreviousSecond, + * RTCSelfTestResult + * @details Outputs: RTCPreviousSecond, RTCSelfTestResult + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestCheckCtrlRegs( void ) { @@ -1219,15 +1236,15 @@ 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 - * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * start the timer and set the state machine to the next state. + * @details Inputs: RTCServiceState, txBuffer, rxBuffer, RTCCurrentSecond, RTCSelfTestTimer, + * RTCPreviousSecond + * @details Outputs: RTCCurrentSecond, RTCSelfTestTimer, RTCPreviousSecond + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestWaitForFirstSecond( void ) { @@ -1263,15 +1280,14 @@ 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 - * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * set the state machine to the next state. + * @details Inputs: RTCServiceState, txBuffer, rxBuffer, RTCCurrentSecond + * @details Outputs: RTCCurrentSecond + * @return next state *************************************************************************/ static RTC_SELF_TEST_STATE_T handleSelfTestWaitForSecondSecond( void ) { @@ -1304,16 +1320,16 @@ 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 - * @details - * Inputs : none - * Outputs : result (RTC_SELF_TEST_STATE_T) - * @return result (RTC_SELF_TEST_STATE_T) + * passed since the last second that was read from RTC. + * @details 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 +1354,5 @@ return result; } + +/**@}*/