diff --git a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/ADCDevice.h b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/ADCDevice.h index 5c74e4b..f0331a7 100644 --- a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/ADCDevice.h +++ b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/ADCDevice.h @@ -23,7 +23,7 @@ /** * ADCDevice implementation - * \defgroup ADCDevice Package ADCDevice + * \defgroup ADCDevice ADCDevice * \ingroup HAL * @{ */ @@ -41,6 +41,7 @@ struct ADCDevice; + typedef uint32_t (*ADCReadFunction)(const struct ADCDevice* self); /** @@ -59,41 +60,36 @@ struct ADCDevice // Function declarations // ----------------------------------------------------------------------------- - /** ADCDevice_construct - * \brief Constructor for a new ADC device - * + * \brief Constructor for a new ADC device * * This is a detailed description of the function * + * Created by: mmi * \memberof ADCDevice * * \param self ADC object * \param[in] read Pointer to read function * \param[in] resolutionsInBits The resolution of this ADC device in * number of bits - * * \return ErrorStatus SUCCESS if construction was successful * ERROR otherwise * * \todo - * */ extern ErrorStatus ADCDevice_construct(struct ADCDevice* self, ADCReadFunction read, unsigned int resolutionInBits); /** ADCDevice_destruct * \brief Destructor for ADC device - * * This is a detailed description of the function * + *Created by: mmi * \memberof ADCDevice * * \param self ADC object - * * \return void * * \todo - * */ extern void ADCDevice_destruct(struct ADCDevice* self); @@ -101,14 +97,13 @@ extern void ADCDevice_destruct(struct ADCDevice* self); * \brief Reads a value from the ADC device input * This is a detailed description of the function * + * Created by: mmi * \memberof ADCDevice * * \param self ADC object - * * \return uint32_t The current value read from the ADC * * \todo - * */ extern uint32_t ADCDevice_read(const struct ADCDevice* self); diff --git a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/Buzzer.h b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/Buzzer.h index cc6e049..00624c1 100644 --- a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/Buzzer.h +++ b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/Buzzer.h @@ -1,6 +1,6 @@ // ----------------------------------------------------------------------------- -/// @file Buzzer.h -/// @brief File description +/// \file Buzzer.h +/// \brief File description // ----------------------------------------------------------------------------- // Micro-Key bv // Industrieweg 28, 9804 TG Noordhorn @@ -17,16 +17,15 @@ // (c) 2015 Micro-Key bv // ----------------------------------------------------------------------------- -/** - * Buzzer implementation - * \defgroup Buzzer Package Buzzer - * \ingroup HAL - * @{ - */ - #ifndef INC_BUZZER_H_ #define INC_BUZZER_H_ +/** + * Buzzer implementation + * \defgroup Buzzer Buzzer + * \ingroup HAL + * @{ + */ // ----------------------------------------------------------------------------- // Include files @@ -62,102 +61,110 @@ // Type definitions. // ----------------------------------------------------------------------------- +/** + * \ingroup Buzzer + * \class Buzzer + * The Buzzer struct that can be used as an object + */ struct Buzzer { // General - bool initialized; - struct Gpio* gpio; + bool initialized; //!< Flag indicating initialisation status + struct Gpio* gpio; //!< The GPIO to use for the buzzer // Functionary properties - unsigned int pulseWidth; + unsigned int pulseWidth; //!< Pulsewidth of the buzzer tone // Task properties - bool runTask; - bool runPeriodically; - SemaphoreHandle_t semaphore; - xTaskHandle taskHandle; - int taskPriority; - uint16_t stackSize; + bool runTask; //!< keep-alive flag for buzzer task + bool runPeriodically; //!< Indicates single or periodical run + SemaphoreHandle_t semaphore; //!< Task semaphore for synchronisation + xTaskHandle taskHandle; //!< FreeRTOS task handle + int taskPriority; //!< FreeRTOS task priority + uint16_t stackSize; //!< FreeRTOS task stacksize }; // ----------------------------------------------------------------------------- // Function declarations // ----------------------------------------------------------------------------- -/** ---------------------------------------------------------------------------- - * Buzzer_construct - * Constructor for a new buzzer instance +/** Buzzer_construct + * \brief Constructor for a new buzzer instance * - * @param self The buzzer object that gets created - * @param gpio The GPIO to use - * @param taskPriority FreeRTOS task priority - * @param stackSize FreeRTOS stack size + * This function creates a new buzzer object * - * @return ErrorStatus SUCCESS if constructor was successful, + * Created by: mmi + * \memberof Buzzer + * + * \param self The buzzer object that gets created + * \param[in] gpio The GPIO to use + * \param[in] taskPriority FreeRTOS task priority + * \param[in] stackSize FreeRTOS stack size + * \return ErrorStatus SUCCESS if constructor was successful, * including generation/start of task * ERROR otherwise * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ extern ErrorStatus Buzzer_construct(struct Buzzer* self, struct Gpio* gpio, int taskPriority, uint16_t stackSize); -/** ---------------------------------------------------------------------------- - * Buzzer_destruct +/** Buzzer_destruct * Destructor for buzzer instance. Also removes the buzzer task * - * @param self The buzzer instance to destruct + * Created by: mmi + * \memberof Buzzer * - * @return void + * \param self The buzzer instance to destruct + * \return void * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ extern void Buzzer_destruct(struct Buzzer* self); -/** ---------------------------------------------------------------------------- - * Buzzer_start - * Starts the buzzer with a repeating tone. +/** Buzzer_start + * \brief Starts the buzzer with a repeating tone. * Tone length is given with argument pulseWidth * - * @param self The buzzer instance to use - * @param pulseWidth The length of the tone in ms. Also defines + * Created by: mmi + * \memberof Buzzer + * + * \param self The buzzer instance to use + * \param[in] pulseWidth The length of the tone in ms. Also defines * the length of the pause between two * tones * - * @return void + * \return void * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ extern void Buzzer_start(struct Buzzer* self, unsigned int pulseWidth); -/** ---------------------------------------------------------------------------- - * Buzzer_stop - * Stops the repeating buzzer tone +/** Buzzer_stop + * \brief Stops the repeating buzzer tone * - * @param self THe buzzer instance to stop + * Created by: mmi + * \memberof Buzzer * - * @return void + * \param self The buzzer instance to stop * + * \return void * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ extern void Buzzer_stop(struct Buzzer* self); -/** ---------------------------------------------------------------------------- - * Buzzer_singleTone +/** Buzzer_singleTone * Creates a single tone with the length given in pulseWidth * - * @param self The buzzer instance to use - * @param pulseWidth The length of the tone in ms + * Created by: mmi + * \memberof Buzzer * - * @return void + * \param self The buzzer instance to use + * \param[in] pulseWidth The length of the tone in ms + * \return void * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ extern void Buzzer_singleTone(struct Buzzer* self, unsigned int pulseWidth); diff --git a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CachedStorage.h b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CachedStorage.h index b74a348..66bbbdc 100644 --- a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CachedStorage.h +++ b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CachedStorage.h @@ -1,6 +1,6 @@ // ----------------------------------------------------------------------------- -/// @file CachedStorage.h -/// @brief Generic memory cache +/// \file CachedStorage.h +/// \brief Generic memory cache // ----------------------------------------------------------------------------- // Micro-Key bv // Industrieweg 28, 9804 TG Noordhorn @@ -17,16 +17,16 @@ // (c) 2017 Micro-Key bv // ----------------------------------------------------------------------------- +#ifndef _CACHEDEEPROM_H_ +#define _CACHEDEEPROM_H_ + /** * CachedStorage implementation - * \defgroup CachedStorage Package CachedStorage + * \defgroup CachedStorage CachedStorage * \ingroup HAL * @{ */ -#ifndef _CACHEDEEPROM_H_ -#define _CACHEDEEPROM_H_ - // ----------------------------------------------------------------------------- // Include files // ----------------------------------------------------------------------------- @@ -49,16 +49,28 @@ // Type definitions. // ----------------------------------------------------------------------------- - +/** + * \ingroup CachedStorage + * \class CachedStorage + * The CachedStorage struct that can be used as an object + */ struct CachedStorage { - bool initialized; - unsigned int pageNumber; - size_t cacheSize; - bool dirty; - struct MemoryDevice* memoryDevice; - uint32_t* storage; - uint32_t* tempBuffer; + bool initialized; //!< Flag indicating initialisation status + unsigned int pageNumber; //!< The pageNumber of the memory section on + //!< which the cache is located. + //!< This is usually for FLASH or EEPROM + //!< devices and required for PAGE-ERASE + //!< functionality. Can be set to any random + //!< value if PAGE-ERASE is not necessary + size_t cacheSize; //!< The size of the cache in bytes + bool dirty; //!< Marker that cache has been updated + struct MemoryDevice* memoryDevice; //!< The memory device on which this cache + //!< is located + uint32_t* storage; //!< Pointer to the cache that is written to + //!< read from + uint32_t* tempBuffer; //!< Pointer to a temporary buffer for + //!< comparison }; // ----------------------------------------------------------------------------- @@ -66,134 +78,139 @@ struct CachedStorage // ----------------------------------------------------------------------------- -/** ---------------------------------------------------------------------------- - * CachedStorage_construct - * Constructor for a new cached storage instance +/** CachedStorage_construct + * \briefConstructor for a new cached storage instance * Function makes use of MALLOC * - * @param self The cache instance - * @param memoryDevice The memory device to use on which the + * Created by: mmi + * \memberof CachedStorage + * + * \param self The cache instance + * \param[in] memoryDevice The memory device to use on which the * cache is located - * @param pageNumber The pageNumber of the memory section on + * \param[in] pageNumber The pageNumber of the memory section on * which the cache is located. * This is usually for FLASH or EEPROM * devices and required for PAGE-ERASE * functionality. Can be set to any random * value if PAGE-ERASE is not necessary - * @param cacheSize The size of the cache. + * \param[in] cacheSize The size of the cache. * This value is 32bit oriented and * NOT BYTE-WISE. * The memory allocation will internally * re-calculate to bytes - * - * @return ErrorStatus SUCCESS if constructor was successful + * \return ErrorStatus SUCCESS if constructor was successful * ERROR otherwise * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ ErrorStatus CachedStorage_construct(struct CachedStorage* self, struct MemoryDevice* memoryDevice, unsigned int pageNumber, size_t cacheSize); -/** ---------------------------------------------------------------------------- - * CachedStorage_destruct - * Destructor for a cached storage instance +/** CachedStorage_destruct + * \brief Destructor for a cached storage instance * Function makes use of FREE * - * @param self The cache instance to destruct + * Created by: mmi + * \memberof CachedStorage * - * @return void + * \param self The cache instance to destruct + * \return void * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ void CachedStorage_destruct(struct CachedStorage* self); -/** ---------------------------------------------------------------------------- - * CachedStorage_writeWord - * Function to write a word (32bit) to cache +/** CachedStorage_writeWord + * \brief Function to write a word (32bit) to cache * - * @param self The cache instance - * @param offset Offset within the cache to put the data - * @param value The value/data to write + * Created by: mmi + * \memberof CachedStorage * - * @return void + * \param self The cache instance + * \param[in] offset Offset within the cache to put the data + * \param[in] value The value/data to write + * \return void * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ void CachedStorage_writeWord(struct CachedStorage* self, int offset, uint32_t value); -/** ---------------------------------------------------------------------------- - * CachedStorage_writeBlob +/** CachedStorage_writeBlob + * \brief Function to write a blob. + * * Function to write a blob (any given format/amount of data) to cache; hence - * the void pointer. - * The function verifies cache boundaries using the offset and blob size - * blobsize is 32bit oriented, NOT BYTE + * the void pointer. The function verifies cache boundaries using the offset and + * blob size blobsize is 32bit oriented, NOT BYTE * - * @param self The cache instance - * @param offset Offset within the cache to put the data - * @param blob Void pointer to the data to be written - * @param blobSize sizeof the blob structure. Give in 32bit, + * Created by: mmi + * \memberof CachedStorage + * + * \param self The cache instance + * \param offset Offset within the cache to put the data + * \param blob Void pointer to the data to be written + * \param blobSize sizeof the blob structure. Give in 32bit, * NOT IN BYTES + * \return void * - * @return void - * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ void CachedStorage_writeBlob(struct CachedStorage* self, int offset, const void* blob, size_t blobSize); -/** ---------------------------------------------------------------------------- - * CachedStorage_readWord - * Function to read a word (32bit) from cache +/** CachedStorage_readWord + * \brief Function to read a word (32bit) from cache * - * @param self The cache instance - * @param offset Offset within the cache to put the data + * Created by: mmi + * \memberof CachedStorage * - * @return uint32_t The read data + * \param self The cache instance + * \param[in] offset Offset within the cache to put the data * - * @todo - * ----------------------------------------------------------------------------- + * \return uint32_t The read data + * + * \todo */ uint32_t CachedStorage_readWord(struct CachedStorage* self, int offset); -/** ---------------------------------------------------------------------------- - * CachedStorage_readBlob +/** CachedStorage_readBlob + * \brief Function to read a blob + * * Function to read a blob (any given format/amount of data) from cache; hence * the void pointer. * The function verifies cache boundaries using the offset * - * @param self The cache instance - * @param offset Offset within the cache to put the data + * Created by: mmi + * \memberof CachedStorage * - * @return void* Void pointer to the blob structure + * \param self The cache instance + * \param[in] offset Offset within the cache to put the data * + * \return void* Void pointer to the blob structure * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ const void* CachedStorage_readBlob(struct CachedStorage* self, int offset); -/** ---------------------------------------------------------------------------- - * CachedStorage_commit - * Function that puts the data from cache to the memory device. +/** CachedStorage_commit + * \brief Function that puts the data from cache to the memory device. + * * This function will verify that the content of the cache is actually different * from the conent of the memory location. If data is equal, not write action * will be performed * In case of memory that needs PAGE-ERASE prior to write, the erase function * will be called automatically. * - * @param self The cache instance + * Created by: mmi + * \memberof CachedStorage * - * @return void + * \param self The cache instance + * \return void * - * @todo - * ----------------------------------------------------------------------------- + * \todo */ void CachedStorage_commit(struct CachedStorage* self); diff --git a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CoverSolenoid.h b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CoverSolenoid.h index 7cbbdde..b4225ab 100644 --- a/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CoverSolenoid.h +++ b/S - Software/0 - HSB MRTS Kathode-MCP/3 - Implementation/0 - Code/HAL/inc/CoverSolenoid.h @@ -17,16 +17,15 @@ // (c) 2015 Micro-Key bv // ----------------------------------------------------------------------------- -/** - * CoverSolenoid implementation - * \defgroup CoverSolenoid Package CoverSolenoid - * \ingroup HAL - * @{ - */ - #ifndef SOLENOID_H_ #define SOLENOID_H_ +/** + * CoverSolenoid implementation + * \defgroup CoverSolenoid CoverSolenoid + * \ingroup HAL + * @{ + */ // ----------------------------------------------------------------------------- // Include files