kernel: add emphasis to nano_sem_take/k_sem_take return code difference

The reversal of the meaning of a value of 0 from k_sem_take vs
nano_sem_take has caused some issue when porting code from the legacy
API to the new API, so put some emphasis on this difference.

- Add a note in the API description.
- Put the call to k_sem_take and the reversal of the return value inside
  of nano_sem_take on one line so that grepping on it shows the
  reversal.

Change-Id: I2f4ba58dc087176d68b55371fa6e367b72559e70
Signed-off-by: Benjamin Walsh <[email protected]>

Author: benwrs

include/kernel.h

@@ -1694,6 +1694,12 @@ extern void k_sem_init(struct k_sem *sem, unsigned int initial_count,
  * @param timeout Waiting period to take the semaphore (in milliseconds),
  *                or one of the special values K_NO_WAIT and K_FOREVER.
  *
+ * @note When porting code from the nanokernel legacy API to the new API, be
+ * careful with the return value of this function. The return value is the
+ * reverse of the one of nano_sem_take family of APIs: 0 means success, and
+ * non-zero means failure, while the nano_sem_take family returns 1 for success
+ * and 0 for failure.
+ *
  * @retval 0 Semaphore taken.
  * @retval -EBUSY Returned without waiting.
  * @retval -EAGAIN Waiting period timed out.

include/legacy.h

@@ -1060,8 +1060,9 @@ static inline __deprecated void nano_sem_give(struct nano_sem *sem)
 static inline __deprecated int nano_sem_take(struct nano_sem *sem,
 					     int32_t timeout_in_ticks)
 {
-	return k_sem_take((struct k_sem *)sem, _ticks_to_ms(timeout_in_ticks))
-		== 0 ? 1 : 0;
+	int32_t ms = _ticks_to_ms(timeout_in_ticks);
+
+	return k_sem_take((struct k_sem *)sem, ms) == 0 ? 1 : 0;
 }
 
 /**