Update abstraction rtos with improved documentation and utilities.

Author: dustin-crossman

targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/abstraction/rtos/include/COMPONENT_RTX/cyabs_rtos_impl.h

@@ -60,7 +60,7 @@ typedef enum
 } cy_thread_priority_t ;
 
 typedef osThreadId_t cy_thread_t;                      /** CMSIS definition of a thread handle */
-typedef uint32_t cy_thread_arg_t;                      /** Argument passed to the entry function of a thread */
+typedef void * cy_thread_arg_t;                        /** Argument passed to the entry function of a thread */
 typedef osMutexId_t cy_mutex_t;                        /** CMSIS definition of a mutex */
 typedef osSemaphoreId_t cy_semaphore_t;                /** CMSIS definition of a semaphore */
 typedef osEventFlagsId_t cy_event_t;                   /** CMSIS definition of an event */

targets/TARGET_Cypress/TARGET_PSOC6/psoc6csp/abstraction/rtos/include/cyabs_rtos.h

@@ -29,7 +29,7 @@
 #define INCLUDED_CY_RTOS_INTERFACE_H_
 
 #include "cyabs_rtos_impl.h"
-#include <cy_result.h>
+#include "cy_result.h"
 #include <stdint.h>
 #include <stdbool.h>
 
@@ -72,6 +72,8 @@ extern "C"
 #define CY_RTOS_GENERAL_ERROR               CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 2)
 /** A bad argument was passed into the APIs */
 #define CY_RTOS_BAD_PARAM                   CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 5)
+/** A memory alignment issue was detected. Ensure memory provided is aligned per CY_RTOS_ALIGNMENT */
+#define CY_RTOS_ALIGNMENT_ERROR             CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 6)
 
 /** \} group_abstraction_rtos_common */
 
@@ -146,7 +148,7 @@ typedef void (*cy_timer_callback_t)(cy_timer_callback_arg_t arg);
  * 
  * \ingroup group_abstraction_rtos_common
  */
-extern cy_rtos_error_t cy_rtos_last_error();
+cy_rtos_error_t cy_rtos_last_error();
 
 /*********************************************** Threads **********************************************/
 
@@ -179,7 +181,7 @@ extern cy_rtos_error_t cy_rtos_last_error();
  *
  * @return The status of thread create request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_create_thread(cy_thread_t *thread, cy_thread_entry_fn_t entry_function,
+cy_rslt_t cy_rtos_create_thread(cy_thread_t *thread, cy_thread_entry_fn_t entry_function,
             const char *name, void *stack, uint32_t stack_size, cy_thread_priority_t priority, cy_thread_arg_t arg);
 
 
@@ -196,7 +198,7 @@ extern cy_rslt_t cy_rtos_create_thread(cy_thread_t *thread, cy_thread_entry_fn_t
  *
  * @return The status of thread exit request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_exit_thread();
+cy_rslt_t cy_rtos_exit_thread();
 
 /** Terminates another thread.
  *
@@ -212,40 +214,51 @@ extern cy_rslt_t cy_rtos_exit_thread();
  *
  * @returns The status of the thread terminate. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_terminate_thread(cy_thread_t *thread);
+cy_rslt_t cy_rtos_terminate_thread(cy_thread_t *thread);
+
+/** Waits for a thread to complete.
+ *
+ * This must be called on any thread that can complete to ensure that any resources that
+ * were allocated for it are cleaned up.
+ *
+ * @param[in] thread Handle of the thread to wait for
+ *
+ * @returns The status of thread join request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
+ */
+cy_rslt_t cy_rtos_join_thread(cy_thread_t *thread);
 
 /** Checks if the thread is running
  *
- * This function is called to determine if a thread is running or not.
+ * This function is called to determine if a thread is running or not. For information on
+ * the thread state, use the cy_rtos_get_thread_state() function.
  *
- * @param[in] thread     handle of the terminated thread to delete
- * @param[out] running   returns true if the thread is running, otherwise false
+ * @param[in] thread     Handle of the terminated thread to delete
+ * @param[out] running   Returns true if the thread is running, otherwise false
  *
  * @returns The status of the thread running check. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_is_thread_running(cy_thread_t *thread, bool *running);
+cy_rslt_t cy_rtos_is_thread_running(cy_thread_t *thread, bool *running);
 
 /** Gets the state the thread is currently in
  *
- * This function is called to determine if a thread is running or not.
+ * This function is called to determine if a thread is running/blocked/inactive/ready etc.
  *
- * @param[in] thread     handle of the terminated thread to delete
- * @param[out] state     returns the state the thread is currently in
+ * @param[in] thread     Handle of the terminated thread to delete
+ * @param[out] state     Returns the state the thread is currently in
  *
  * @returns The status of the thread state check. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_get_thread_state(cy_thread_t *thread, cy_thread_state_t *state);
+cy_rslt_t cy_rtos_get_thread_state(cy_thread_t *thread, cy_thread_state_t *state);
 
-/** Waits for a thread to complete.
+/** Get current thread handle
  *
- * This must be called on any thread that can complete to ensure that any resources that
- * were allocated for it are cleaned up.
+ * Returns the unique thread handle of the current running thread.
  *
- * @param[in] thread Handle of the thread to wait for
+ * @param[out] thread Handle of the current running thread
  *
  * @returns The status of thread join request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_join_thread(cy_thread_t *thread);
+cy_rslt_t cy_rtos_get_thread_handle(cy_thread_t *thread);
 
 /** \} group_abstraction_rtos_threads */
 
@@ -265,7 +278,7 @@ extern cy_rslt_t cy_rtos_join_thread(cy_thread_t *thread);
  *
  * @return The status of mutex creation request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_init_mutex(cy_mutex_t *mutex);
+cy_rslt_t cy_rtos_init_mutex(cy_mutex_t *mutex);
 
 /** Get a mutex.
  *
@@ -283,7 +296,7 @@ extern cy_rslt_t cy_rtos_init_mutex(cy_mutex_t *mutex);
  * @return The status of the get mutex. Returns timeout if mutex was not acquired
  *                    before timeout_ms period. [CY_RSLT_SUCCESS, CY_RTOS_TIMEOUT]
  */
-extern cy_rslt_t cy_rtos_get_mutex(cy_mutex_t *mutex, cy_time_t timeout_ms);
+cy_rslt_t cy_rtos_get_mutex(cy_mutex_t *mutex, cy_time_t timeout_ms);
 
 /** Set a mutex.
  *
@@ -295,7 +308,7 @@ extern cy_rslt_t cy_rtos_get_mutex(cy_mutex_t *mutex, cy_time_t timeout_ms);
  * @return The status of the set mutex request. [CY_RSLT_SUCCESS, CY_RTOS_TIMEOUT]
  *
  */
-extern cy_rslt_t cy_rtos_set_mutex(cy_mutex_t *mutex);
+cy_rslt_t cy_rtos_set_mutex(cy_mutex_t *mutex);
 
 /** Deletes a mutex.
  *
@@ -305,7 +318,7 @@ extern cy_rslt_t cy_rtos_set_mutex(cy_mutex_t *mutex);
  *
  * @return The status to the delete request. [CY_RSLT_SUCCESS, CY_RTOS_TIMEOUT]
  */
-extern cy_rslt_t cy_rtos_deinit_mutex(cy_mutex_t *mutex);
+cy_rslt_t cy_rtos_deinit_mutex(cy_mutex_t *mutex);
 
 /** \} group_abstraction_rtos_mutex */
 
@@ -327,7 +340,7 @@ extern cy_rslt_t cy_rtos_deinit_mutex(cy_mutex_t *mutex);
  *
  * @return The status of the sempahore creation. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_init_semaphore(cy_semaphore_t *semaphore, uint32_t maxcount, uint32_t initcount);
+cy_rslt_t cy_rtos_init_semaphore(cy_semaphore_t *semaphore, uint32_t maxcount, uint32_t initcount);
 
 /**
  * Get/Acquire a semaphore
@@ -343,7 +356,7 @@ extern cy_rslt_t cy_rtos_init_semaphore(cy_semaphore_t *semaphore, uint32_t maxc
  * @param[in] in_isr      true if we are trying to get the semaphore from with an ISR
  * @return The status of get semaphore operation [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_get_semaphore(cy_semaphore_t *semaphore, cy_time_t timeout_ms, bool in_isr);
+cy_rslt_t cy_rtos_get_semaphore(cy_semaphore_t *semaphore, cy_time_t timeout_ms, bool in_isr);
 
 /**
  * Set/Release a semaphore
@@ -355,7 +368,7 @@ extern cy_rslt_t cy_rtos_get_semaphore(cy_semaphore_t *semaphore, cy_time_t time
  *                        Value of false indicates calling from normal thread context
  * @return The status of set semaphore operation [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_set_semaphore(cy_semaphore_t *semaphore, bool in_isr);
+cy_rslt_t cy_rtos_set_semaphore(cy_semaphore_t *semaphore, bool in_isr);
 
 /**
  * Deletes a sempahore
@@ -366,7 +379,7 @@ extern cy_rslt_t cy_rtos_set_semaphore(cy_semaphore_t *semaphore, bool in_isr);
  *
  * @return The status of semaphore deletion [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_deinit_semaphore(cy_semaphore_t *semaphore);
+cy_rslt_t cy_rtos_deinit_semaphore(cy_semaphore_t *semaphore);
 
 /** \} group_abstraction_rtos_semaphore */
 
@@ -387,7 +400,7 @@ extern cy_rslt_t cy_rtos_deinit_semaphore(cy_semaphore_t *semaphore);
  * @return The status of the event initialization request.
  *         [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_init_event(cy_event_t *event);
+cy_rslt_t cy_rtos_init_event(cy_event_t *event);
 
 /** Set the event flag bits.
  *
@@ -400,7 +413,7 @@ extern cy_rslt_t cy_rtos_init_event(cy_event_t *event);
  *
  * @return The status of the set request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_setbits_event(cy_event_t *event, uint32_t bits, bool in_isr) ;
+cy_rslt_t cy_rtos_setbits_event(cy_event_t *event, uint32_t bits, bool in_isr) ;
 
 /**
  * Clear the event flag bits
@@ -413,7 +426,7 @@ extern cy_rslt_t cy_rtos_setbits_event(cy_event_t *event, uint32_t bits, bool in
  *
  * @return The status of the clear flags request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_clearbits_event(cy_event_t *event, uint32_t bits, bool in_isr) ;
+cy_rslt_t cy_rtos_clearbits_event(cy_event_t *event, uint32_t bits, bool in_isr) ;
 
 /** Get the event bits.
  *
@@ -424,7 +437,7 @@ extern cy_rslt_t cy_rtos_clearbits_event(cy_event_t *event, uint32_t bits, bool
  *
  * @return The status of the get request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_getbits_event(cy_event_t *event, uint32_t *bits);
+cy_rslt_t cy_rtos_getbits_event(cy_event_t *event, uint32_t *bits);
 
 /** Wait for the event and return bits.
  *
@@ -442,7 +455,7 @@ extern cy_rslt_t cy_rtos_getbits_event(cy_event_t *event, uint32_t *bits);
  *
  * @return The status of the wait for event request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_waitbits_event(cy_event_t *event, uint32_t *bits, bool clear, bool all, cy_time_t timeout);
+cy_rslt_t cy_rtos_waitbits_event(cy_event_t *event, uint32_t *bits, bool clear, bool all, cy_time_t timeout);
 
 /** Deinitialize a event.
  *
@@ -452,7 +465,7 @@ extern cy_rslt_t cy_rtos_waitbits_event(cy_event_t *event, uint32_t *bits, bool
  *
  * @return The status of the deletion request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_deinit_event(cy_event_t *event);
+cy_rslt_t cy_rtos_deinit_event(cy_event_t *event);
 
 /** \} group_abstraction_rtos_event */
 
@@ -474,7 +487,7 @@ extern cy_rslt_t cy_rtos_deinit_event(cy_event_t *event);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_init_queue(cy_queue_t *queue, size_t length, size_t itemsize);
+cy_rslt_t cy_rtos_init_queue(cy_queue_t *queue, size_t length, size_t itemsize);
 
 /** Put an item in a queue.
  *
@@ -491,7 +504,7 @@ extern cy_rslt_t cy_rtos_init_queue(cy_queue_t *queue, size_t length, size_t ite
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR, CY_RTOS_QUEUE_FULL]
  */
-extern cy_rslt_t cy_rtos_put_queue(cy_queue_t *queue, const void *item_ptr, cy_time_t timeout_ms, bool in_isr);
+cy_rslt_t cy_rtos_put_queue(cy_queue_t *queue, const void *item_ptr, cy_time_t timeout_ms, bool in_isr);
 
 /** Gets an item in a queue.
  *
@@ -508,7 +521,7 @@ extern cy_rslt_t cy_rtos_put_queue(cy_queue_t *queue, const void *item_ptr, cy_t
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_NO_MEMORY, CY_RTOS_GENERAL_ERROR, CY_RTOS_QUEUE_EMPTY]
  */
-extern cy_rslt_t cy_rtos_get_queue(cy_queue_t *queue, void *item_ptr, cy_time_t timeout_ms, bool in_isr);
+cy_rslt_t cy_rtos_get_queue(cy_queue_t *queue, void *item_ptr, cy_time_t timeout_ms, bool in_isr);
 
 /** Return the number of items in the queue.
  *
@@ -519,7 +532,7 @@ extern cy_rslt_t cy_rtos_get_queue(cy_queue_t *queue, void *item_ptr, cy_time_t
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_count_queue(cy_queue_t *queue, size_t *num_waiting);
+cy_rslt_t cy_rtos_count_queue(cy_queue_t *queue, size_t *num_waiting);
 
 /** Return the amount of empty space in the queue.
  *
@@ -532,7 +545,7 @@ extern cy_rslt_t cy_rtos_count_queue(cy_queue_t *queue, size_t *num_waiting);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_space_queue(cy_queue_t *queue, size_t *num_spaces);
+cy_rslt_t cy_rtos_space_queue(cy_queue_t *queue, size_t *num_spaces);
 
 /** Reset the queue.
  *
@@ -542,7 +555,7 @@ extern cy_rslt_t cy_rtos_space_queue(cy_queue_t *queue, size_t *num_spaces);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_reset_queue(cy_queue_t *queue);
+cy_rslt_t cy_rtos_reset_queue(cy_queue_t *queue);
 
 /** Deinitialize the queue handle.
  *
@@ -553,7 +566,7 @@ extern cy_rslt_t cy_rtos_reset_queue(cy_queue_t *queue);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_deinit_queue(cy_queue_t *queue);
+cy_rslt_t cy_rtos_deinit_queue(cy_queue_t *queue);
 
 /** \} group_abstraction_rtos_queue */
 
@@ -576,7 +589,7 @@ extern cy_rslt_t cy_rtos_deinit_queue(cy_queue_t *queue);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_init_timer(cy_timer_t *timer, cy_timer_trigger_type_t type,
+cy_rslt_t cy_rtos_init_timer(cy_timer_t *timer, cy_timer_trigger_type_t type,
         cy_timer_callback_t fun, cy_timer_callback_arg_t arg);
 
 /** Start a timer.
@@ -588,15 +601,15 @@ extern cy_rslt_t cy_rtos_init_timer(cy_timer_t *timer, cy_timer_trigger_type_t t
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_start_timer(cy_timer_t *timer, cy_time_t num_ms);
+cy_rslt_t cy_rtos_start_timer(cy_timer_t *timer, cy_time_t num_ms);
 
 /** Stop a timer.
  *
  * @param[in] timer Pointer to the timer handle
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_stop_timer(cy_timer_t *timer);
+cy_rslt_t cy_rtos_stop_timer(cy_timer_t *timer);
 
 /** Returns state of a timer.
  *
@@ -605,7 +618,7 @@ extern cy_rslt_t cy_rtos_stop_timer(cy_timer_t *timer);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_is_running_timer(cy_timer_t *timer, bool *state);
+cy_rslt_t cy_rtos_is_running_timer(cy_timer_t *timer, bool *state);
 
 /** Deinit the timer.
  *
@@ -616,7 +629,7 @@ extern cy_rslt_t cy_rtos_is_running_timer(cy_timer_t *timer, bool *state);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_deinit_timer(cy_timer_t *timer);
+cy_rslt_t cy_rtos_deinit_timer(cy_timer_t *timer);
 
 /** \} group_abstraction_rtos_timer */
 
@@ -635,7 +648,7 @@ extern cy_rslt_t cy_rtos_deinit_timer(cy_timer_t *timer);
  *
  * @returns Time in milliseconds since the RTOS started.
  */
-extern cy_rslt_t cy_rtos_get_time(cy_time_t *tval);
+cy_rslt_t cy_rtos_get_time(cy_time_t *tval);
 
 /** Delay for a number of milliseconds.
  *
@@ -648,7 +661,7 @@ extern cy_rslt_t cy_rtos_get_time(cy_time_t *tval);
  *
  * @return The status of the creation request. [CY_RSLT_SUCCESS, CY_RTOS_GENERAL_ERROR]
  */
-extern cy_rslt_t cy_rtos_delay_milliseconds(cy_time_t num_ms);
+cy_rslt_t cy_rtos_delay_milliseconds(cy_time_t num_ms);
 
 /** \} group_abstraction_rtos_timer */