From 08ffe89682e72c70876d3dbfd0555161e16608e9 Mon Sep 17 00:00:00 2001 From: "Robin.Mueller" Date: Wed, 27 May 2020 23:41:59 +0200 Subject: [PATCH] doc and api improvements --- osal/FreeRTOS/BinarySemaphore.cpp | 4 +-- osal/FreeRTOS/BinarySemaphore.h | 27 ++++++++++--------- osal/FreeRTOS/CountingSemaphUsingTask.h | 36 ++++++++++++++++++++----- osal/FreeRTOS/CountingSemaphore.h | 4 +++ 4 files changed, 51 insertions(+), 20 deletions(-) diff --git a/osal/FreeRTOS/BinarySemaphore.cpp b/osal/FreeRTOS/BinarySemaphore.cpp index 8891b755..7d882aff 100644 --- a/osal/FreeRTOS/BinarySemaphore.cpp +++ b/osal/FreeRTOS/BinarySemaphore.cpp @@ -84,7 +84,7 @@ SemaphoreHandle_t BinarySemaphore::getSemaphore() { return handle; } -ReturnValue_t BinarySemaphore::giveBinarySemaphore(SemaphoreHandle_t semaphore) { +ReturnValue_t BinarySemaphore::release(SemaphoreHandle_t semaphore) { if (semaphore == nullptr) { return SemaphoreIF::SEMAPHORE_NULLPOINTER; } @@ -97,7 +97,7 @@ ReturnValue_t BinarySemaphore::giveBinarySemaphore(SemaphoreHandle_t semaphore) } // Be careful with the stack size here. This is called from an ISR! -ReturnValue_t BinarySemaphore::giveBinarySemaphoreFromISR( +ReturnValue_t BinarySemaphore::releaseFromISR( SemaphoreHandle_t semaphore, BaseType_t * higherPriorityTaskWoken) { if (semaphore == nullptr) { return SemaphoreIF::SEMAPHORE_NULLPOINTER; diff --git a/osal/FreeRTOS/BinarySemaphore.h b/osal/FreeRTOS/BinarySemaphore.h index b883f801..f3839151 100644 --- a/osal/FreeRTOS/BinarySemaphore.h +++ b/osal/FreeRTOS/BinarySemaphore.h @@ -52,7 +52,7 @@ public: * for example by an ISR or another task. * @param timeoutMs * @return -@c RETURN_OK on success - * -@c RETURN_FAILED on failure + * -@c SemaphoreIF::SEMAPHORE_TIMEOUT on timeout */ ReturnValue_t acquire(uint32_t timeoutMs = SemaphoreIF::NO_TIMEOUT) override; @@ -60,16 +60,17 @@ public: /** * Same as lockBinarySemaphore() with timeout in FreeRTOS ticks. * @param timeoutTicks - * @return - @c RETURN_OK on success - * - @c RETURN_FAILED on failure + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_TIMEOUT on timeout */ ReturnValue_t acquireWithTickTimeout(TickType_t timeoutTicks = BinarySemaphore::NO_TIMEOUT); /** - * Give back the binary semaphore - * @return - @c RETURN_OK on success - * - @c RETURN_FAILED on failure + * Release the binary semaphore. + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_NOT_OWNED if the semaphores is + * already available. */ ReturnValue_t release() override; @@ -82,20 +83,22 @@ public: /** * Wrapper function to give back semaphore from handle * @param semaphore - * @return - @c RETURN_OK on success - * - @c RETURN_FAILED on failure + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_NOT_OWNED if the semaphores is + * already available. */ - static ReturnValue_t giveBinarySemaphore(SemaphoreHandle_t semaphore); + static ReturnValue_t release(SemaphoreHandle_t semaphore); /** * Wrapper function to give back semaphore from handle when called from an ISR * @param semaphore * @param higherPriorityTaskWoken This will be set to pdPASS if a task with a higher priority * was unblocked - * @return - @c RETURN_OK on success - * - @c RETURN_FAILED on failure + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_NOT_OWNED if the semaphores is + * already available. */ - static ReturnValue_t giveBinarySemaphoreFromISR(SemaphoreHandle_t semaphore, + static ReturnValue_t releaseFromISR(SemaphoreHandle_t semaphore, BaseType_t * higherPriorityTaskWoken); protected: diff --git a/osal/FreeRTOS/CountingSemaphUsingTask.h b/osal/FreeRTOS/CountingSemaphUsingTask.h index 2c54b31b..73d3f987 100644 --- a/osal/FreeRTOS/CountingSemaphUsingTask.h +++ b/osal/FreeRTOS/CountingSemaphUsingTask.h @@ -12,7 +12,7 @@ extern "C" { /** * @brief Couting Semaphore implementation which uses the notification value * of the task. The notification value should therefore not be used - * for other purposes + * for other purposes. * @details * Additional information: https://www.freertos.org/RTOS-task-notifications.html * and general semaphore documentation. @@ -22,17 +22,37 @@ public: CountingSemaphoreUsingTask(const uint8_t maxCount, uint8_t initCount); virtual ~CountingSemaphoreUsingTask(); + /** + * Acquire the counting semaphore. + * If no semaphores are available, the task will be blocked + * for a maximum of #timeoutMs or until one is given back, + * for example by an ISR or another task. + * @param timeoutMs + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_TIMEOUT on timeout + */ ReturnValue_t acquire(uint32_t timeoutMs = SemaphoreIF::NO_TIMEOUT) override; + + /** + * Release a semaphore, increasing the number of available counting + * semaphores up to the #maxCount value. + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_NOT_OWNED if #maxCount semaphores are + * already available. + */ ReturnValue_t release() override; + uint8_t getSemaphoreCounter() const override; static uint8_t getSemaphoreCounterFromISR(TaskHandle_t task); + /** - * Acquire, using a timeout value in ticks + * Acquire with a timeout value in ticks * @param timeoutTicks - * @return + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_TIMEOUT on timeout */ ReturnValue_t acquireWithTickTimeout( - TickType_t timeoutTicks= SemaphoreIF::NO_TIMEOUT); + TickType_t timeoutTicks = SemaphoreIF::NO_TIMEOUT); /** * Get handle to the task related to the semaphore. @@ -43,13 +63,17 @@ public: /** * Release semaphore of task by supplying task handle * @param taskToNotify - * @return + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_NOT_OWNED if #maxCount semaphores are + * already available. */ static ReturnValue_t release(TaskHandle_t taskToNotify); /** * Release seamphore of a task from an ISR. * @param taskToNotify - * @return + * @return -@c RETURN_OK on success + * -@c SemaphoreIF::SEMAPHORE_NOT_OWNED if #maxCount semaphores are + * already available. */ static ReturnValue_t releaseFromISR(TaskHandle_t taskToNotify, BaseType_t* higherPriorityTaskWoken); diff --git a/osal/FreeRTOS/CountingSemaphore.h b/osal/FreeRTOS/CountingSemaphore.h index 77050f90..bed3c726 100644 --- a/osal/FreeRTOS/CountingSemaphore.h +++ b/osal/FreeRTOS/CountingSemaphore.h @@ -21,6 +21,10 @@ public: CountingSemaphore (CountingSemaphore &&); //! @brief Move assignment CountingSemaphore & operator=(CountingSemaphore &&); + + /* Same API as binary semaphore otherwise. acquire() can be called + * until there are not semaphores left and release() can be called + * until maxCount is reached. */ private: const uint8_t maxCount; uint8_t initCount = 0;