doc and api improvements

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;

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:

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);

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;