Index: Utilities.c =================================================================== diff -u -r8b18c3e875bd5d265399b603b8ea0a4c3ce8fcbe -r5fb988facecb08dceb2bba1c462d3097b53617f0 --- Utilities.c (.../Utilities.c) (revision 8b18c3e875bd5d265399b603b8ea0a4c3ce8fcbe) +++ Utilities.c (.../Utilities.c) (revision 5fb988facecb08dceb2bba1c462d3097b53617f0) @@ -17,7 +17,6 @@ #include // For memcpy -#include "Common.h" #include "FPGA.h" #include "Timers.h" #include "Utilities.h" @@ -140,24 +139,26 @@ }; // variables for time windowed counts (counts # of instances in a specific window of time) -static BOOL timeWindowedCountsInitialized[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Initialized flags for time windowed counts -static U32 timeWindowedCountsMaxCount[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Max. counts for time windowed counts -static U32 timeWindowedCountsWindowMs[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Time windows (in ms) for time windowed counts -static U32 timeWindowedCounts[ NUM_OF_TIME_WINDOWED_COUNTS ][ MAX_TIME_WINDOWED_COUNT ]; ///< Time stamps for instances for time windowed counts -static U32 timeWindowedCountIndexes[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< List indexes for time windowed counts -static U32 timeWindowedCountCounts[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Current counts for time windowed counts -static SEMAPHORE_STATUS_T sempahoreStatus[ NUM_OF_SEMAPHORES ]; +static BOOL timeWindowedCountsInitialized[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Initialized flags for time windowed counts. +static U32 timeWindowedCountsMaxCount[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Max. counts for time windowed counts. +static U32 timeWindowedCountsWindowMs[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Time windows (in ms) for time windowed counts. +static U32 timeWindowedCounts[ NUM_OF_TIME_WINDOWED_COUNTS ][ MAX_TIME_WINDOWED_COUNT ]; ///< Time stamps for instances for time windowed counts. +static U32 timeWindowedCountIndexes[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< List indexes for time windowed counts. +static U32 timeWindowedCountCounts[ NUM_OF_TIME_WINDOWED_COUNTS ]; ///< Current counts for time windowed counts. +// variables for semaphores +static SEMAPHORE_STATUS_T sempahoreStatus[ NUM_OF_SEMAPHORES ]; ///< Status of each defined semaphore. + /*********************************************************************//** * @brief * The crc32 function calculates a 32-bit CRC for a given range of bytes * in memory. Poly = 0x1EDC6F41. Not reflected. Initial value = 0x00000000. - * @details Inputs: CRC32_TABLE[] - * @details Outputs: none + * @details \b Inputs: CRC32_TABLE[] + * @details \b Outputs: none * @param initialValue initial CRC seed value * @param address pointer to start address of memory range to calculate CRC for * @param len number of bytes in the memory range to calculate CRC for - * @return CRC as a U32 + * @return 32-bit CRC *************************************************************************/ U32 crc32( U32 const initialValue, const U08 *address, U32 len ) { @@ -176,11 +177,11 @@ * @brief * The crc16 function calculates a 16-bit CRC for a given range of bytes * in memory. Poly = 0x1021. Not reflected. Initial value = 0xFFFF. - * @details Inputs: CRC16_TABLE[] - * @details Outputs: none + * @details \b Inputs: CRC16_TABLE[] + * @details \b Outputs: none * @param address pointer to start address of memory range to calculate CRC for * @param len number of bytes in the memory range to calculate CRC for - * @return CRC as a U16 + * @return 16-bit CRC *************************************************************************/ U16 crc16( const U08 *address, U32 len ) { @@ -199,11 +200,11 @@ * @brief * The crc8 function calculates a 8-bit CRC for a given range of bytes * in memory. - * @details Inputs: CRC8_TABLE[] - * @details Outputs: none + * @details \b Inputs: CRC8_TABLE[] + * @details \b Outputs: none * @param address pointer to start address of memory range to calculate CRC for * @param len number of bytes in the memory range to calculate CRC for - * @return CRC as a U08 + * @return 8-bit CRC *************************************************************************/ U08 crc8( const U08 *address, U32 len ) { @@ -222,11 +223,11 @@ * @brief * The crc4 function calculates a 4-bit CRC for a given range of bytes * in memory. - * @details Inputs: none - * @details Outputs: none + * @details \b Inputs: none + * @details \b Outputs: none * @param buffer pointer to start address of memory range to calculate CRC for * @param byteCount number of bytes in the memory range to calculate CRC for - * @return CRC as a U08 + * @return 4-bit CRC (4 lsb of byte) *************************************************************************/ U08 crc4( U16* buffer, U32 byteCount ) { @@ -269,11 +270,11 @@ * unsigned 32-bit numbers. If the second (ending) number is less than the * first (starting) number, then the difference is calculated with a wrap past * 32-bit full scale to zero. - * @details Inputs: none - * @details Outputs: none + * @details \b Inputs: none + * @details \b Outputs: none * @param start first number to compute difference for * @param end second number to compute difference for - * @return the difference between the two given numbers + * @return the unsigned difference between the two given 32-bit values *************************************************************************/ U32 u32DiffWithWrap( U32 start, U32 end ) { @@ -287,11 +288,11 @@ * The u16BiDiffWithWrap function calculates the difference between two given * unsigned 16-bit numbers. This version of function returns a signed value * to allow for a negative difference. - * @details Inputs: none - * @details Outputs: none + * @details \b Inputs: none + * @details \b Outputs: none * @param start first number to compute difference for * @param end second number to compute difference for - * @return the difference between the two given numbers + * @return the signed difference between the two given values *************************************************************************/ S32 u32BiDiffWithWrap( U32 start, U32 end ) { @@ -318,11 +319,11 @@ * unsigned 16-bit numbers. If the second (ending) number is less than the * first (starting) number, then the difference is calculated with a wrap past * 16-bit full scale to zero. - * @details Inputs: none - * @details Outputs: none + * @details \b Inputs: none + * @details \b Outputs: none * @param start first number to compute difference for * @param end second number to compute difference for - * @return the difference between the two given numbers + * @return the unsigned difference between the two given values *************************************************************************/ U16 u16DiffWithWrap( U16 start, U16 end ) { @@ -336,11 +337,11 @@ * The u16BiDiffWithWrap function calculates the difference between two given * unsigned 16-bit numbers. This version of function returns a signed value * to allow for a negative difference. - * @details Inputs: none - * @details Outputs: none + * @details \b Inputs: none + * @details \b Outputs: none * @param start first number to compute difference for * @param end second number to compute difference for - * @return the difference between the two given numbers + * @return the signed difference between the two given values *************************************************************************/ S16 u16BiDiffWithWrap( U16 start, U16 end ) { @@ -364,9 +365,10 @@ /*********************************************************************//** * @brief * The initTimeWindowedCount function initializes a given time windowed count. - * @details Inputs: timeWindowedCountsMaxCount, timeWindowedCountsInitialized - * @details Outputs: timeWindowedCountsMaxCount, timeWindowedCountsInitialized, alarm if - * software fault occurred + * @details \b Alarm: ALARM_ID_XX_SOFTWARE_FAULT triggered if given count or + * maximum count is invalid. + * @details \b Inputs: timeWindowedCountsMaxCount, timeWindowedCountsInitialized + * @details \b Outputs: timeWindowedCountsMaxCount, timeWindowedCountsInitialized * @param cnt ID of the time windowed count to initialize * @param maxCnt maximum number of instances in the time window for this count * @param winMs number of ms in the time window for this count @@ -418,11 +420,11 @@ * The incTimeWindowedCount function adds a new instance to a given time * windowed count. Must call initTimeWindowedCount() prior to calling this * function for a given time windowed count. - * *Note - thread protection not provided - assumed function will be called - * by one task for a given time windowed count. - * @details Inputs: timeWindowedCounts, timeWindowedCountIndexes, timeWindowedCountCounts - * @details Outputs: timeWindowedCounts, timeWindowedCountIndexes, timeWindowedCountCounts, - * alarm if a software fault occurred + * @warning Thread protection not provided - assumed function will be called + * by one task only for a given time windowed count. + * @details \b Alarm: ALARM_ID_XX_SOFTWARE_FAULT if invalid count given + * @details \b Inputs: timeWindowedCounts, timeWindowedCountIndexes, timeWindowedCountCounts + * @details \b Outputs: timeWindowedCounts, timeWindowedCountIndexes, timeWindowedCountCounts, * @param cnt ID of the time windowed count to add an instance to * @return TRUE if this instances brings the count to the maximum within * this counts time window, otherwise FALSE @@ -465,8 +467,10 @@ * The getCriticalData function gets the value for a given critical data * record. The integrity of the critical data is checked first. If the * critical data record fails the integrity check, a fault is triggered. - * @details Inputs: none - * @details Outputs: alarm if HD critical error occurred + * @details \b Alarm: ALARM_ID_XX_CRITICAL_DATA_ERROR if integrity check + * fails for the given critical data. + * @details \b Inputs: none + * @details \b Outputs: none * @param data Ptr to a critical data record * @return The data from a critical data record *************************************************************************/ @@ -501,8 +505,8 @@ * @brief * The isCriticalDataInRange function determines whether a critical data * value is within the range set for that critical data. - * @details Inputs: none - * @details Outputs: none + * @details \b Inputs: none + * @details \b Outputs: none * @param data Ptr to a critical data record * @return TRUE if given data is in range, FALSE if not *************************************************************************/ @@ -539,8 +543,10 @@ * @brief * The setCriticalData function sets the value for a given critical data * record. - * @details Inputs: none - * @details Outputs: alarm if HD critical error occurred + * @details \b Alarm: ALARM_ID_XX_CRITICAL_DATA_ERROR if given critical + * data's type is invalid. + * @details \b Inputs: none + * @details \b Outputs: none * @param data Ptr to a critical data record * @param value a value to set * @return TRUE if set was successful, FALSE if not (out of range) @@ -579,9 +585,10 @@ /*********************************************************************//** * @brief - * The resetCriticalData function resets a critical data record. - * @details Inputs: none - * @details Outputs: Given critical data record is reset to unset w/ default value. + * The resetCriticalData function resets a given critical data record to + * unset with its default value. + * @details \b Inputs: none + * @details \b Outputs: none * @param data Ptr to a critical data record * @return none *************************************************************************/ @@ -595,9 +602,9 @@ /*********************************************************************//** * @brief - * The hexStrToDec function convert hex string to decimal value. - * @details Inputs: none - * @details Outputs: none + * The hexStrToDec function converts a given hex string to a decimal value. + * @details \b Inputs: none + * @details \b Outputs: convValuePtr (ref param) is set to converted decimal value. * @param valuePtr pointer to hex string to convert * @param convValuePtr pointer to the provided buffer to write the converted * values back @@ -670,9 +677,9 @@ /*********************************************************************//** * @brief - * The initSemaphores function initializes the semaphores - * @details Inputs: none - * @details Outputs: sempahoreStatus + * The initSemaphores function initializes the defined semaphores. + * @details \b Inputs: none + * @details \b Outputs: sempahoreStatus[] * @return none *************************************************************************/ void initSemaphores( void ) @@ -687,30 +694,31 @@ /*********************************************************************//** * @brief - * The getSemaphore function gets a semaphore for the requested semaphore. - * @details Inputs: none - * @details Outputs: sempahoreStatus - * @param s which is the semaphore to be taken - * @return TRUE if semaphore is available and now it is taken otherwise, FALSE + * The acquireSemaphore function attempts to acquire the given semaphore. + * @details \b Alarm: ALARM_ID_XX_SOFTWARE_FAULT if given semaphore is invalid. + * @details \b Inputs: none + * @details \b Outputs: sempahoreStatus + * @param sem ID of semaphore to be acquired + * @return TRUE if semaphore is available and now acquired, otherwise FALSE *************************************************************************/ -BOOL getSemaphore( SEMAPHORE_T s ) +BOOL acquireSemaphore( SEMAPHORE_T sem ) { BOOL result = FALSE; _disable_IRQ(); - if ( FALSE == sempahoreStatus[ s ].isSemaphoreTaken ) + if ( FALSE == sempahoreStatus[ sem ].isSemaphoreTaken ) { - sempahoreStatus[ s ].semaphoreStartTimeMS = getMSTimerCount(); - sempahoreStatus[ s ].isSemaphoreTaken = TRUE; - result = TRUE; + sempahoreStatus[ sem ].semaphoreStartTimeMS = getMSTimerCount(); + sempahoreStatus[ sem ].isSemaphoreTaken = TRUE; + result = TRUE; } - else if ( TRUE == didTimeout( sempahoreStatus[ s ].semaphoreStartTimeMS, SEMAPHORE_IN_USE_TIMEOUT_MS ) ) + else if ( TRUE == didTimeout( sempahoreStatus[ sem ].semaphoreStartTimeMS, SEMAPHORE_IN_USE_TIMEOUT_MS ) ) { #ifdef _TD_ - SET_ALARM_WITH_2_U32_DATA( ALARM_ID_TD_SOFTWARE_FAULT, SW_FAULT_ID_SEMAPHORE_IN_USE_TIMEOUT, (U32)s ) + SET_ALARM_WITH_2_U32_DATA( ALARM_ID_TD_SOFTWARE_FAULT, SW_FAULT_ID_SEMAPHORE_IN_USE_TIMEOUT, (U32)sem ) #endif #ifdef _DD_ - SET_ALARM_WITH_2_U32_DATA( ALARM_ID_DD_SOFTWARE_FAULT, SW_FAULT_ID_SEMAPHORE_IN_USE_TIMEOUT, (U32)s ) + SET_ALARM_WITH_2_U32_DATA( ALARM_ID_DD_SOFTWARE_FAULT, SW_FAULT_ID_SEMAPHORE_IN_USE_TIMEOUT, (U32)sem ) #endif } _enable_IRQ(); @@ -720,30 +728,31 @@ /*********************************************************************//** * @brief - * The releaseSemaphore function releases a semaphore that was previously taken - * for a job. - * @details Inputs: none - * @details Outputs: sempahoreStatus - * @param s which is the semaphore to be released + * The releaseSemaphore function releases a semaphore that was previously + * acquired. + * @details \b Inputs: none + * @details \b Outputs: sempahoreStatus[] + * @param sem which is the semaphore to be released * @return none *************************************************************************/ -void releaseSemaphore( SEMAPHORE_T s ) +void releaseSemaphore( SEMAPHORE_T sem ) { - if ( TRUE == sempahoreStatus[ s ].isSemaphoreTaken ) + if ( TRUE == sempahoreStatus[ sem ].isSemaphoreTaken ) { - sempahoreStatus[ s ].isSemaphoreTaken = FALSE; + sempahoreStatus[ sem ].isSemaphoreTaken = FALSE; } } /*********************************************************************//** * @brief - * The isSemaphoreReleased function returns the status of a taken semaphore - * @details Inputs: none - * @details Outputs: sempahoreStatus + * The isSemaphoreAvailable function returns whether a given semaphore + * is available. + * @details \b Inputs: sempahoreStatus[] + * @details \b Outputs: none * @param s which is the semaphore to check - * @return status of the semaphore + * @return TRUE if semaphore is available, FALSE if already acquired *************************************************************************/ -BOOL isSemaphoreReleased( SEMAPHORE_T s ) +BOOL isSemaphoreAvailable( SEMAPHORE_T s ) { return ( TRUE == sempahoreStatus[ s ].isSemaphoreTaken ? FALSE : TRUE ); }