1 /***********************************************************************************************//** 2 * \file cyabs_rtos.h 3 * 4 * \brief 5 * Defines the Cypress RTOS Interface. Provides prototypes for functions that 6 * allow Cypress libraries to use RTOS resources such as threads, mutexes & 7 * timing functions in an abstract way. The APIs are implemented in the Port 8 * Layer RTOS interface which is specific to the RTOS in use. 9 * 10 *************************************************************************************************** 11 * \copyright 12 * Copyright 2018-2022 Cypress Semiconductor Corporation (an Infineon company) or 13 * an affiliate of Cypress Semiconductor Corporation 14 * 15 * SPDX-License-Identifier: Apache-2.0 16 * 17 * Licensed under the Apache License, Version 2.0 (the "License"); 18 * you may not use this file except in compliance with the License. 19 * You may obtain a copy of the License at 20 * 21 * http://www.apache.org/licenses/LICENSE-2.0 22 * 23 * Unless required by applicable law or agreed to in writing, software 24 * distributed under the License is distributed on an "AS IS" BASIS, 25 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 26 * See the License for the specific language governing permissions and 27 * limitations under the License. 28 **************************************************************************************************/ 29 30 #pragma once 31 32 #include "cyabs_rtos_impl.h" 33 #include "cy_result.h" 34 #include <stdint.h> 35 #include <stdbool.h> 36 #include <stddef.h> 37 38 /** 39 * \defgroup group_abstraction_rtos_common Common 40 * General types and defines for working with the RTOS abstraction layer. 41 * \defgroup group_abstraction_rtos_event Events 42 * APIs for acquiring and working with Events. 43 * \defgroup group_abstraction_rtos_mutex Mutex 44 * APIs for acquiring and working with Mutexes. 45 * \defgroup group_abstraction_rtos_queue Queue 46 * APIs for creating and working with Queues. 47 * \defgroup group_abstraction_rtos_semaphore Semaphore 48 * APIs for acquiring and working with Semaphores. 49 * \defgroup group_abstraction_rtos_threads Threads 50 * APIs for creating and working with Threads. 51 * \defgroup group_abstraction_rtos_scheduler Scheduler 52 * APIs for working with Scheduler. 53 * \defgroup group_abstraction_rtos_time Time 54 * APIs for getting the current time and waiting. 55 * \defgroup group_abstraction_rtos_timer Timer 56 * APIs for creating and working with Timers. 57 */ 58 59 #ifdef __cplusplus 60 extern "C" 61 { 62 #endif 63 64 /******************************************** CONSTANTS *******************************************/ 65 66 /** 67 * \ingroup group_abstraction_rtos_common 68 * \{ 69 */ 70 71 #if defined(DOXYGEN) 72 /** Return value indicating success */ 73 #define CY_RSLT_SUCCESS ((cy_rslt_t)0x00000000U) 74 #endif 75 76 /** Used with RTOS calls that require a timeout. This implies the call will never timeout. */ 77 #define CY_RTOS_NEVER_TIMEOUT ( (uint32_t)0xffffffffUL ) 78 79 // 80 // Note on error strategy. If the error is a normal part of operation (timeouts, full queues, empty 81 // queues), the these errors are listed here and the abstraction layer implementation must map from 82 // the underlying errors to these. If the errors are special cases, the the error \ref 83 // CY_RTOS_GENERAL_ERROR will be returned and \ref cy_rtos_last_error() can be used to retrieve the 84 // RTOS specific error message. 85 // 86 /** Requested operation did not complete in the specified time */ 87 #define CY_RTOS_TIMEOUT \ 88 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 0) 89 /** The RTOS could not allocate memory for the specified operation */ 90 #define CY_RTOS_NO_MEMORY \ 91 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 1) 92 /** An error occured in the RTOS */ 93 #define CY_RTOS_GENERAL_ERROR \ 94 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 2) 95 /** A bad argument was passed into the APIs */ 96 #define CY_RTOS_BAD_PARAM \ 97 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 5) 98 /** A memory alignment issue was detected. Ensure memory provided is aligned per \ref 99 CY_RTOS_ALIGNMENT_MASK */ 100 #define CY_RTOS_ALIGNMENT_ERROR \ 101 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 6) 102 /** Requested operation not supported with this RTOS */ 103 #define CY_RTOS_UNSUPPORTED \ 104 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 7) 105 106 /** \} group_abstraction_rtos_common */ 107 108 /** 109 * \ingroup group_abstraction_rtos_queue 110 * \{ 111 */ 112 113 /** The Queue is already full and can't accept any more items at this time */ 114 #define CY_RTOS_QUEUE_FULL \ 115 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 3) 116 /** The Queue is empty and has nothing to remove */ 117 #define CY_RTOS_QUEUE_EMPTY \ 118 CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_ABSTRACTION_OS, 4) 119 120 /** \} group_abstraction_rtos_queue */ 121 122 /********************************************* TYPES **********************************************/ 123 124 /** 125 * The state a thread can be in 126 * 127 * \ingroup group_abstraction_rtos_threads 128 */ 129 typedef enum cy_thread_state 130 { 131 CY_THREAD_STATE_INACTIVE, /**< thread has not started or was terminated but not yet joined */ 132 CY_THREAD_STATE_READY, /**< thread can run, but is not currently */ 133 CY_THREAD_STATE_RUNNING, /**< thread is currently running */ 134 CY_THREAD_STATE_BLOCKED, /**< thread is blocked waiting for something */ 135 CY_THREAD_STATE_TERMINATED, /**< thread has terminated but not freed */ 136 CY_THREAD_STATE_UNKNOWN /**< thread is in an unknown state */ 137 } cy_thread_state_t; 138 139 /** 140 * The type of timer 141 * 142 * \ingroup group_abstraction_rtos_timer 143 */ 144 typedef enum cy_timer_trigger_type 145 { 146 CY_TIMER_TYPE_PERIODIC, /**< called periodically until stopped */ 147 CY_TIMER_TYPE_ONCE /**< called once only */ 148 } cy_timer_trigger_type_t; 149 150 #define cy_timer_type_periodic (CY_TIMER_TYPE_PERIODIC) /**< \deprecated replaced by \ref 151 CY_TIMER_TYPE_PERIODIC */ 152 #define cy_timer_type_once (CY_TIMER_TYPE_ONCE) /**< \deprecated replaced by \ref 153 CY_TIMER_TYPE_ONCE */ 154 155 /** 156 * The type of a function that is the entry point for a thread 157 * 158 * @param[in] arg the argument passed from the thread create call to the entry function 159 * 160 * \ingroup group_abstraction_rtos_threads 161 */ 162 typedef void (* cy_thread_entry_fn_t)(cy_thread_arg_t arg); 163 164 /** 165 * The callback function to be called by a timer 166 * 167 * \ingroup group_abstraction_rtos_timer 168 */ 169 typedef void (* cy_timer_callback_t)(cy_timer_callback_arg_t arg); 170 171 /** 172 * Return the last error from the RTOS. 173 * 174 * The functions in the RTOS abstraction layer adhere to the Infineon return 175 * results calling convention. The underlying RTOS implementations will not but rather 176 * will have their own error code conventions. This function is provided as a service 177 * to the developer, mostly for debugging, and returns the underlying RTOS error code 178 * from the last RTOS abstraction layer that returned \ref CY_RTOS_GENERAL_ERROR. 179 * 180 * @return RTOS specific error code. 181 * 182 * \ingroup group_abstraction_rtos_common 183 */ 184 cy_rtos_error_t cy_rtos_last_error(void); 185 186 187 /********************************************* Threads ********************************************/ 188 189 /** 190 * \ingroup group_abstraction_rtos_threads 191 * \{ 192 */ 193 194 /** Create a thread with specific thread argument. 195 * 196 * This function is called to startup a new thread. If the thread can exit, it must call 197 * \ref cy_rtos_thread_exit() just before doing so. All created threads that can terminate, either 198 * by themselves or forcefully by another thread MUST have \ref cy_rtos_thread_join() called on them 199 * by another thread in order to cleanup any resources that might have been allocated for them. 200 * 201 * @param[out] thread Pointer to a variable which will receive the new thread handle 202 * @param[in] entry_function Function pointer which points to the main function for the new thread 203 * @param[in] name String thread name used for a debugger 204 * @param[in] stack The buffer to use for the thread stack. This must be aligned to 205 * \ref CY_RTOS_ALIGNMENT_MASK with a size of at least \ref 206 * CY_RTOS_MIN_STACK_SIZE. 207 * If stack is null, cy_rtos_create_thread will allocate a stack from 208 * the heap. 209 * @param[in] stack_size The size of the thread stack in bytes 210 * @param[in] priority The priority of the thread. Values are operating system specific, 211 * but some common priority levels are defined: 212 * CY_THREAD_PRIORITY_LOW 213 * CY_THREAD_PRIORITY_NORMAL 214 * CY_THREAD_PRIORITY_HIGH 215 * @param[in] arg The argument to pass to the new thread 216 * 217 * @return The status of thread create request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 218 * CY_RTOS_GENERAL_ERROR] 219 */ 220 cy_rslt_t cy_rtos_thread_create(cy_thread_t* thread, cy_thread_entry_fn_t entry_function, 221 const char* name, void* stack, uint32_t stack_size, 222 cy_thread_priority_t priority, cy_thread_arg_t arg); 223 224 /** Exit the current thread. 225 * 226 * This function is called just before a thread exits. In some cases it is sufficient 227 * for a thread to just return to exit, but in other cases, the RTOS must be explicitly 228 * signaled. In cases where a return is sufficient, this should be a null funcition. 229 * where the RTOS must be signaled, this function should perform that In cases operation. 230 * In code using RTOS services, this function should be placed at any at any location 231 * where the main thread function will return, exiting the thread. Threads that can 232 * exit must still be joined (\ref cy_rtos_thread_join) to ensure their resources are 233 * fully cleaned up. 234 * 235 * @return The status of thread exit request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 236 */ 237 cy_rslt_t cy_rtos_thread_exit(void); 238 239 /** Terminates another thread. 240 * 241 * This function is called to terminate another thread and reap the resources claimed 242 * by the thread. This should be called both when forcibly terminating another thread 243 * as well as any time a thread can exit on its own. For some RTOS implementations 244 * this is not required as the thread resources are claimed as soon as it exits. In 245 * other cases, this must be called to reclaim resources. Threads that are terminated 246 * must still be joined (\ref cy_rtos_thread_join) to ensure their resources are fully 247 * cleaned up. 248 * 249 * @param[in] thread Handle of the thread to terminate 250 * 251 * @returns The status of the thread terminate. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 252 */ 253 cy_rslt_t cy_rtos_thread_terminate(cy_thread_t* thread); 254 255 /** Waits for a thread to complete. 256 * 257 * This must be called on any thread that can complete to ensure that any resources that 258 * were allocated for it are cleaned up. 259 * 260 * @param[in] thread Handle of the thread to wait for 261 * 262 * @returns The status of thread join request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 263 */ 264 cy_rslt_t cy_rtos_thread_join(cy_thread_t* thread); 265 266 /** Checks if the thread is running 267 * 268 * This function is called to determine if a thread is actively running or not. For information on 269 * the thread state, use the \ref cy_rtos_thread_get_state() function. 270 * 271 * @param[in] thread Handle of the terminated thread to delete 272 * @param[out] running Returns true if the thread is running, otherwise false 273 * 274 * @returns The status of the thread running check. [\ref CY_RSLT_SUCCESS, \ref 275 * CY_RTOS_GENERAL_ERROR] 276 */ 277 cy_rslt_t cy_rtos_thread_is_running(cy_thread_t* thread, bool* running); 278 279 /** Gets the state the thread is currently in 280 * 281 * This function is called to determine if a thread is running/blocked/inactive/ready etc. 282 * 283 * @param[in] thread Handle of the terminated thread to delete 284 * @param[out] state Returns the state the thread is currently in 285 * 286 * @returns The status of the thread state check. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 287 */ 288 cy_rslt_t cy_rtos_thread_get_state(cy_thread_t* thread, cy_thread_state_t* state); 289 290 /** Get current thread handle 291 * 292 * Returns the unique thread handle of the current running thread. 293 * 294 * @param[out] thread Handle of the current running thread 295 * 296 * @returns The status of thread join request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 297 */ 298 cy_rslt_t cy_rtos_thread_get_handle(cy_thread_t* thread); 299 300 301 /** Suspend current thread until notification is received 302 * 303 * This function suspends the execution of current thread until it is notified 304 * by \ref cy_rtos_thread_set_notification from another thread or ISR, or timed out with 305 * specify timeout value 306 * 307 * @param[in] timeout_ms Maximum number of milliseconds to wait 308 * Use the \ref CY_RTOS_NEVER_TIMEOUT constant to wait forever. 309 * 310 * @returns The status of thread wait. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_TIMEOUT, \ref 311 * CY_RTOS_GENERAL_ERROR] 312 */ 313 cy_rslt_t cy_rtos_thread_wait_notification(cy_time_t timeout_ms); 314 315 316 /** Set the thread notification for a thread 317 * 318 * This function sets the thread notification for the target thread. 319 * The target thread waiting for the notification to be set will resume from suspended state. 320 * 321 * @param[in] thread Handle of the target thread 322 * 323 * @returns The status of thread wait. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR, 324 * \ref CY_RTOS_BAD_PARAM] 325 */ 326 cy_rslt_t cy_rtos_thread_set_notification(cy_thread_t* thread); 327 328 329 /** Get the name of a thread 330 * 331 * This function returns the name of the target thread 332 * 333 * @param[in] thread Handle of the target thread 334 * 335 * @param[out] thread_name Will be updated to point to the thread name. Can return 336 * NULL in the case of no thread name. 337 * 338 * @returns The status of getting the thread name. [\ref CY_RSLT_SUCCESS, \ref 339 * CY_RTOS_GENERAL_ERROR] 340 * 341 */ 342 cy_rslt_t cy_rtos_thread_get_name(cy_thread_t* thread, const char** thread_name); 343 344 345 /** \} group_abstraction_rtos_threads */ 346 347 348 /********************************************* 349 * Scheduler 350 ********************************************/ 351 352 /** 353 * \ingroup group_abstraction_rtos_scheduler 354 * \{ 355 */ 356 357 /** Suspend the scheduler 358 * 359 * This function suspends the scheduler and makes sure that the code executed after the call does 360 * not get interrupted by a task switch. 361 * Multiple suspend calls can be done making nesting possible granted 362 * that the same number of resume calls are made. 363 * 364 * @note API functions that have the potential to cause a context switch 365 * must not be called while the scheduler is suspended. 366 * 367 * @return The status of scheduler suspend request. [\ref CY_RSLT_SUCCESS] 368 */ 369 cy_rslt_t cy_rtos_scheduler_suspend(void); 370 371 /** Resume the scheduler 372 * 373 * This function resumes the scheduler after it was suspended. 374 * If incorrectly called (called more times than \ref cy_rtos_scheduler_suspend) it fails returning 375 * \ref CY_RTOS_BAD_PARAM 376 * 377 * @return The status of scheduler resume request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_BAD_PARAM] 378 */ 379 cy_rslt_t cy_rtos_scheduler_resume(void); 380 381 /** \} group_abstraction_rtos_scheduler */ 382 383 384 385 /********************************************* Mutexes ********************************************/ 386 387 /** 388 * \ingroup group_abstraction_rtos_mutex 389 * \{ 390 */ 391 392 /** Create a mutex which can support recursion or not. 393 * 394 * Creates a binary mutex which can be used for mutual exclusion to prevent simulatenous 395 * access of shared resources. Created mutexes can support priority inheritance if recursive. 396 * 397 * \note Not all RTOS implementations support non-recursive mutexes. In this case a recursive 398 * mutex will be created. 399 * 400 * @param[out] mutex Pointer to the mutex handle to be initialized 401 * @param[in] recursive Should the created mutex support recursion or not 402 * 403 * @return The status of mutex creation request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 404 * CY_RTOS_GENERAL_ERROR] 405 */ 406 cy_rslt_t cy_rtos_mutex_init(cy_mutex_t* mutex, bool recursive); 407 408 /** Get a mutex. 409 * 410 * If the mutex is available, it is acquired and this function returned. 411 * If the mutex is not available, the thread waits until the mutex is available 412 * or until the timeout occurs. 413 * 414 * @note This function must not be called from an interrupt context as it may block. 415 * 416 * @param[in] mutex Pointer to the mutex handle 417 * @param[in] timeout_ms Maximum number of milliseconds to wait while attempting to get 418 * the mutex. Use the \ref CY_RTOS_NEVER_TIMEOUT constant to wait forever. 419 * 420 * @return The status of the get mutex. Returns timeout if mutex was not acquired 421 * before timeout_ms period. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_TIMEOUT, \ref 422 * CY_RTOS_GENERAL_ERROR] 423 */ 424 cy_rslt_t cy_rtos_mutex_get(cy_mutex_t* mutex, cy_time_t timeout_ms); 425 426 /** Set a mutex. 427 * 428 * The mutex is released allowing any other threads waiting on the mutex to 429 * obtain the semaphore. 430 * 431 * @param[in] mutex Pointer to the mutex handle 432 * 433 * @return The status of the set mutex request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 434 * 435 */ 436 cy_rslt_t cy_rtos_mutex_set(cy_mutex_t* mutex); 437 438 /** Deletes a mutex. 439 * 440 * This function frees the resources associated with a sempahore. 441 * 442 * @param[in] mutex Pointer to the mutex handle 443 * 444 * @return The status to the delete request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 445 */ 446 cy_rslt_t cy_rtos_mutex_deinit(cy_mutex_t* mutex); 447 448 /** \} group_abstraction_rtos_mutex */ 449 450 /******************************************** Semaphores ******************************************/ 451 452 /** 453 * \ingroup group_abstraction_rtos_semaphore 454 * \{ 455 */ 456 457 /** 458 * Create a semaphore 459 * 460 * This is basically a counting semaphore. It can be used for synchronization between tasks and 461 * tasks and interrupts. 462 * 463 * @param[in,out] semaphore Pointer to the semaphore handle to be initialized 464 * @param[in] maxcount The maximum count for this semaphore 465 * @param[in] initcount The initial count for this semaphore 466 * 467 * @return The status of the semaphore creation. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 468 * CY_RTOS_GENERAL_ERROR] 469 */ 470 cy_rslt_t cy_rtos_semaphore_init(cy_semaphore_t* semaphore, uint32_t maxcount, uint32_t initcount); 471 472 /** 473 * Get/Acquire a semaphore 474 * 475 * If the semaphore count is zero, waits until the semaphore count is greater than zero. 476 * Once the semaphore count is greater than zero, this function decrements 477 * the count and return. It may also return if the timeout is exceeded. 478 * 479 * @param[in] semaphore Pointer to the semaphore handle 480 * @param[in] timeout_ms Maximum number of milliseconds to wait while attempting to get 481 * the semaphore. Use the \ref CY_RTOS_NEVER_TIMEOUT constant to wait 482 * forever. Must be zero if in_isr is true. 483 * @return The status of get semaphore operation [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_TIMEOUT, \ref 484 * CY_RTOS_NO_MEMORY, \ref CY_RTOS_GENERAL_ERROR] 485 */ 486 cy_rslt_t cy_rtos_semaphore_get(cy_semaphore_t* semaphore, cy_time_t timeout_ms); 487 488 /** 489 * Set/Release a semaphore 490 * 491 * Increments the semaphore count, up to the maximum count for this semaphore. 492 * 493 * @param[in] semaphore Pointer to the semaphore handle 494 * Value of false indicates calling from normal thread context 495 * @return The status of set semaphore operation [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 496 * CY_RTOS_GENERAL_ERROR] 497 */ 498 cy_rslt_t cy_rtos_semaphore_set(cy_semaphore_t* semaphore); 499 500 /** 501 * Get the count of a semaphore. 502 * 503 * Gets the number of available tokens on the semaphore. 504 * 505 * @param[in] semaphore Pointer to the semaphore handle 506 * @param[out] count Pointer to the return count 507 * @return The status of get semaphore count operation [\ref CY_RSLT_SUCCESS, \ref 508 * CY_RTOS_GENERAL_ERROR] 509 */ 510 cy_rslt_t cy_rtos_semaphore_get_count(cy_semaphore_t* semaphore, size_t* count); 511 512 /** 513 * Deletes a semaphore 514 * 515 * This function frees the resources associated with a semaphore. 516 * 517 * @param[in] semaphore Pointer to the semaphore handle 518 * 519 * @return The status of semaphore deletion [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 520 * CY_RTOS_GENERAL_ERROR] 521 */ 522 cy_rslt_t cy_rtos_semaphore_deinit(cy_semaphore_t* semaphore); 523 524 /** \} group_abstraction_rtos_semaphore */ 525 526 /********************************************* Events ********************************************/ 527 528 /** 529 * \ingroup group_abstraction_rtos_event 530 * \{ 531 */ 532 533 /** Create an event. 534 * 535 * This is an event which can be used to signal a set of threads 536 * with a 32 bit data element. 537 * 538 * @param[in,out] event Pointer to the event handle to be initialized 539 * 540 * @return The status of the event initialization request. 541 * [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref CY_RTOS_GENERAL_ERROR] 542 */ 543 cy_rslt_t cy_rtos_event_init(cy_event_t* event); 544 545 /** Set the event flag bits. 546 * 547 * This is an event which can be used to signal a set of threads 548 * with a 32 bit data element. Any threads waiting on this event are released 549 * 550 * @param[in] event Pointer to the event handle 551 * @param[in] bits The value of the 32 bit flags 552 * 553 * @return The status of the set request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 554 * CY_RTOS_GENERAL_ERROR] 555 */ 556 cy_rslt_t cy_rtos_event_setbits(cy_event_t* event, uint32_t bits); 557 558 /** 559 * Clear the event flag bits 560 * 561 * This function clears bits in the event. 562 * 563 * @param[in] event Pointer to the event handle 564 * @param[in] bits Any bits set in this value, will be cleared in the event. 565 * 566 * @return The status of the clear flags request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, 567 * \ref CY_RTOS_GENERAL_ERROR] 568 */ 569 cy_rslt_t cy_rtos_event_clearbits(cy_event_t* event, uint32_t bits); 570 571 /** Get the event bits. 572 * 573 * Returns the current bits for the event. 574 * 575 * @param[in] event Pointer to the event handle 576 * @param[out] bits pointer to receive the value of the event flags 577 * 578 * @return The status of the get request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 579 * CY_RTOS_GENERAL_ERROR] 580 */ 581 cy_rslt_t cy_rtos_event_getbits(cy_event_t* event, uint32_t* bits); 582 583 /** Wait for the event and return bits. 584 * 585 * Waits for the event to be set and then returns the bits associated 586 * with the event, or waits for the given timeout period. 587 * @note This function returns if any bit in the set is set. 588 * 589 * @param[in] event Pointer to the event handle 590 * @param[in,out] bits pointer to receive the value of the event flags 591 * @param[in] clear if true, clear any bits set that cause the wait to return 592 * if false, do not clear bits 593 * @param[in] all if true, all bits in the initial bits value must be set to return 594 * if false, any one bit in the initial bits value must be set to return 595 * @param[in] timeout_ms The amount of time to wait in milliseconds 596 * 597 * @return The status of the wait for event request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, 598 * \ref CY_RTOS_GENERAL_ERROR] 599 */ 600 cy_rslt_t cy_rtos_event_waitbits(cy_event_t* event, uint32_t* bits, bool clear, bool all, 601 cy_time_t timeout_ms); 602 603 /** Deinitialize a event. 604 * 605 * This function frees the resources associated with an event. 606 * 607 * @param[in] event Pointer to the event handle 608 * 609 * @return The status of the deletion request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 610 */ 611 cy_rslt_t cy_rtos_event_deinit(cy_event_t* event); 612 613 /** \} group_abstraction_rtos_event */ 614 615 /********************************************* Queues *********************************************/ 616 617 /** 618 * \ingroup group_abstraction_rtos_queue 619 * \{ 620 */ 621 622 /** Create a queue. 623 * 624 * This is a queue of data where entries are placed on the back of the queue 625 * and removed from the front of the queue. 626 * 627 * @param[out] queue Pointer to the queue handle 628 * @param[in] length The maximum length of the queue in items 629 * @param[in] itemsize The size of each item in the queue. 630 * 631 * @return The status of the init request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 632 * CY_RTOS_GENERAL_ERROR] 633 */ 634 cy_rslt_t cy_rtos_queue_init(cy_queue_t* queue, size_t length, size_t itemsize); 635 636 /** Put an item in a queue. 637 * 638 * This function puts an item in the queue. The item is copied 639 * into the queue using a memory copy and the data pointed to by item_ptr 640 * is no longer referenced once the call returns. 641 * 642 * @note If in_isr is true, timeout_ms must be zero. 643 * 644 * @param[in] queue Pointer to the queue handle 645 * @param[in] item_ptr Pointer to the item to place in the queue 646 * @param[in] timeout_ms The time to wait to place the item in the queue 647 * 648 * @return The status of the put request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 649 * CY_RTOS_GENERAL_ERROR, \ref CY_RTOS_QUEUE_FULL] 650 */ 651 cy_rslt_t cy_rtos_queue_put(cy_queue_t* queue, const void* item_ptr, cy_time_t timeout_ms); 652 653 /** Gets an item in a queue. 654 * 655 * This function gets an item from the queue. The item is copied 656 * out of the queue into the memory provide by item_ptr. This space must be 657 * large enough to hold a queue entry as defined when the queue was initialized. 658 * 659 * @note If in_isr is true, timeout_ms must be zero. 660 * 661 * @param[in] queue Pointer to the queue handle 662 * @param[in] item_ptr Pointer to the memory for the item from the queue 663 * @param[in] timeout_ms The time to wait to get an item from the queue 664 * 665 * @return The status of the get request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 666 * CY_RTOS_GENERAL_ERROR, \ref CY_RTOS_QUEUE_EMPTY] 667 */ 668 cy_rslt_t cy_rtos_queue_get(cy_queue_t* queue, void* item_ptr, cy_time_t timeout_ms); 669 670 /** Return the number of items in the queue. 671 * 672 * This function returns the number of items currently in the queue. 673 * 674 * @param[in] queue Pointer to the queue handle 675 * @param[out] num_waiting Pointer to the return count 676 * 677 * @return The status of the count request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 678 */ 679 cy_rslt_t cy_rtos_queue_count(cy_queue_t* queue, size_t* num_waiting); 680 681 /** Return the amount of empty space in the queue. 682 * 683 * This function returns the amount of empty space in the 684 * queue. For instance, if the queue was created with 10 entries max and there 685 * are currently 2 entries in the queue, this will return 8. 686 * 687 * @param[in] queue Pointer to the queue handle 688 * @param[out] num_spaces Pointer to the return count. 689 * 690 * @return The status of the space request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 691 */ 692 cy_rslt_t cy_rtos_queue_space(cy_queue_t* queue, size_t* num_spaces); 693 694 /** Reset the queue. 695 * 696 * This function sets the queue to empty. 697 * 698 * @param[in] queue pointer to the queue handle 699 * 700 * @return The status of the reset request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 701 */ 702 cy_rslt_t cy_rtos_queue_reset(cy_queue_t* queue); 703 704 /** Deinitialize the queue handle. 705 * 706 * This function de-initializes the queue and returns all 707 * resources used by the queue. 708 * 709 * @param[in] queue Pointer to the queue handle 710 * 711 * @return The status of the deinit request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 712 */ 713 cy_rslt_t cy_rtos_queue_deinit(cy_queue_t* queue); 714 715 /** \} group_abstraction_rtos_queue */ 716 717 /********************************************* Timers *********************************************/ 718 719 /** 720 * \ingroup group_abstraction_rtos_timer 721 * \{ 722 */ 723 724 /** Create a new timer. 725 * 726 * This function initializes a timer object. 727 * @note The timer is not active until start is called. 728 * @note The callback may be (likely will be) called from a different thread. 729 * 730 * @param[out] timer Pointer to the timer handle to initialize 731 * @param[in] type Type of timer (periodic or once) 732 * @param[in] fun The function 733 * @param[in] arg Argument to pass along to the callback function 734 * 735 * @return The status of the init request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 736 */ 737 cy_rslt_t cy_rtos_timer_init(cy_timer_t* timer, cy_timer_trigger_type_t type, 738 cy_timer_callback_t fun, cy_timer_callback_arg_t arg); 739 740 /** Sends a request to start the timer. Depending on the priorities of threads in the system, 741 * it may be necessary for high priority items to wait before the timer actually starts running. 742 * 743 * @param[in] timer Pointer to the timer handle 744 * @param[in] num_ms The number of milliseconds to wait before the timer fires 745 * 746 * @return The status of the start request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 747 */ 748 cy_rslt_t cy_rtos_timer_start(cy_timer_t* timer, cy_time_t num_ms); 749 750 /** Sends a request to stop the timer. Depending on the priorities of threads in the system, 751 * it may be necessary for high priority items to wait before the timer is actually stopped. 752 * 753 * @param[in] timer Pointer to the timer handle 754 * 755 * @return The status of the stop request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 756 */ 757 cy_rslt_t cy_rtos_timer_stop(cy_timer_t* timer); 758 759 /** Returns state of a timer. 760 * 761 * @param[in] timer Pointer to the timer handle 762 * @param[out] state Return value for state, true if running, false otherwise 763 * 764 * @return The status of the is_running request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 765 */ 766 cy_rslt_t cy_rtos_timer_is_running(cy_timer_t* timer, bool* state); 767 768 /** Deinit the timer. 769 * 770 * This function deinitializes the timer and frees all consumed resources. 771 * 772 * @param[in] timer Pointer to the timer handle 773 * 774 * @return The status of the deinit request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 775 */ 776 cy_rslt_t cy_rtos_timer_deinit(cy_timer_t* timer); 777 778 /** \} group_abstraction_rtos_timer */ 779 780 /********************************************** Time **********************************************/ 781 782 /** 783 * \ingroup group_abstraction_rtos_time 784 * \{ 785 */ 786 787 /** Gets time in milliseconds since RTOS start. 788 * 789 * @note Since this is only 32 bits, it will roll over every 49 days, 17 hours, 2 mins, 47.296 790 * seconds 791 * 792 * @param[out] tval Pointer to the struct to populate with the RTOS time 793 * 794 * @returns Time in milliseconds since the RTOS started. 795 */ 796 cy_rslt_t cy_rtos_time_get(cy_time_t* tval); 797 798 /** Delay for a number of milliseconds. 799 * 800 * Processing of this function depends on the minimum sleep 801 * time resolution of the RTOS. The current thread should sleep for 802 * the longest period possible which is less than the delay required, 803 * then makes up the difference with a tight loop. 804 * 805 * @param[in] num_ms The number of milliseconds to delay for 806 * 807 * @return The status of the delay request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 808 */ 809 cy_rslt_t cy_rtos_delay_milliseconds(cy_time_t num_ms); 810 811 /** \} group_abstraction_rtos_time */ 812 813 /********************************************** Deprecated ***************************************/ 814 815 //================================================================================================== 816 // Threads 817 //================================================================================================== 818 /** 819 * \ingroup group_abstraction_rtos_threads 820 * \{ 821 */ 822 823 /** Create a thread with specific thread argument. 824 * 825 * This function is called to startup a new thread. If the thread can exit, it must call 826 * \ref cy_rtos_exit_thread() just before doing so. All created threads that can terminate, either 827 * by themselves or forcefully by another thread MUST have \ref cy_rtos_join_thread() called on them 828 * by another thread in order to cleanup any resources that might have been allocated for them. 829 * 830 * @param[out] thread Pointer to a variable which will receive the new thread handle 831 * @param[in] entry_function Function pointer which points to the main function for the new thread 832 * @param[in] name String thread name used for a debugger 833 * @param[in] stack The buffer to use for the thread stack. This must be aligned to 834 * \ref CY_RTOS_ALIGNMENT_MASK with a size of at least \ref 835 * CY_RTOS_MIN_STACK_SIZE. 836 * If stack is null, cy_rtos_create_thread will allocate a stack from 837 * the heap. 838 * @param[in] stack_size The size of the thread stack in bytes 839 * @param[in] priority The priority of the thread. Values are operating system specific, 840 * but some common priority levels are defined: 841 * CY_THREAD_PRIORITY_LOW 842 * CY_THREAD_PRIORITY_NORMAL 843 * CY_THREAD_PRIORITY_HIGH 844 * @param[in] arg The argument to pass to the new thread 845 * 846 * @return The status of thread create request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 847 * CY_RTOS_GENERAL_ERROR] 848 */ 849 #define cy_rtos_create_thread(thread, entry_function, name, stack, stack_size, priority, arg) \ 850 cy_rtos_thread_create(thread, entry_function, name, stack, stack_size, priority, arg) 851 852 /** Checks if the thread is running 853 * 854 * This function is called to determine if a thread is actively running or not. For information on 855 * the thread state, use the \ref cy_rtos_get_thread_state() function. 856 * 857 * @param[in] thread Handle of the terminated thread to delete 858 * @param[out] running Returns true if the thread is running, otherwise false 859 * 860 * @returns The status of the thread running check. [\ref CY_RSLT_SUCCESS, \ref 861 * CY_RTOS_GENERAL_ERROR] 862 */ 863 #define cy_rtos_is_thread_running(thread, running) \ 864 cy_rtos_thread_is_running(thread, running) 865 866 /** Set the thread notification for a thread 867 * 868 * This function sets the thread notification for the target thread. 869 * The target thread waiting for the notification to be set will resume from suspended state. 870 * 871 * @param[in] thread Handle of the target thread 872 * @param[in] in_isr If true this is being called from within an ISR 873 * 874 * @returns The status of thread wait. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR, 875 * \ref CY_RTOS_BAD_PARAM] 876 */ 877 #define cy_rtos_set_thread_notification(thread, in_isr) \ 878 cy_rtos_thread_set_notification(thread) 879 880 /** Suspend current thread until notification is received 881 * 882 * This function suspends the execution of current thread until it is notified 883 * by \ref cy_rtos_set_thread_notification from another thread or ISR, or timed out with 884 * specify timeout value 885 * 886 * @param[in] timeout_ms Maximum number of milliseconds to wait 887 * Use the \ref CY_RTOS_NEVER_TIMEOUT constant to wait forever. 888 * 889 * @returns The status of thread wait. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_TIMEOUT, \ref 890 * CY_RTOS_GENERAL_ERROR] 891 */ 892 #define cy_rtos_wait_thread_notification(timeout_ms) cy_rtos_thread_wait_notification(timeout_ms) 893 894 /** Gets the state the thread is currently in 895 * 896 * This function is called to determine if a thread is running/blocked/inactive/ready etc. 897 * 898 * @param[in] thread Handle of the terminated thread to delete 899 * @param[out] state Returns the state the thread is currently in 900 * 901 * @returns The status of the thread state check. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 902 */ 903 #define cy_rtos_get_thread_state(thread, state) cy_rtos_thread_get_state(thread, state) 904 905 /** Waits for a thread to complete. 906 * 907 * This must be called on any thread that can complete to ensure that any resources that 908 * were allocated for it are cleaned up. 909 * 910 * @param[in] thread Handle of the thread to wait for 911 * 912 * @returns The status of thread join request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 913 */ 914 #define cy_rtos_join_thread(thread) cy_rtos_thread_join(thread) 915 916 /** Get current thread handle 917 * 918 * Returns the unique thread handle of the current running thread. 919 * 920 * @param[out] thread Handle of the current running thread 921 * 922 * @returns The status of thread join request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 923 */ 924 #define cy_rtos_get_thread_handle(thread) cy_rtos_thread_get_handle(thread) 925 926 /** Terminates another thread. 927 * 928 * This function is called to terminate another thread and reap the resources claimed 929 * by the thread. This should be called both when forcibly terminating another thread 930 * as well as any time a thread can exit on its own. For some RTOS implementations 931 * this is not required as the thread resources are claimed as soon as it exits. In 932 * other cases, this must be called to reclaim resources. Threads that are terminated 933 * must still be joined (\ref cy_rtos_join_thread) to ensure their resources are fully 934 * cleaned up. 935 * 936 * @param[in] thread Handle of the thread to terminate 937 * 938 * @returns The status of the thread terminate. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 939 */ 940 #define cy_rtos_terminate_thread(thread) cy_rtos_thread_terminate(thread) 941 942 /** Exit the current thread. 943 * 944 * This function is called just before a thread exits. In some cases it is sufficient 945 * for a thread to just return to exit, but in other cases, the RTOS must be explicitly 946 * signaled. In cases where a return is sufficient, this should be a null funcition. 947 * where the RTOS must be signaled, this function should perform that In cases operation. 948 * In code using RTOS services, this function should be placed at any at any location 949 * where the main thread function will return, exiting the thread. Threads that can 950 * exit must still be joined (\ref cy_rtos_join_thread) to ensure their resources are 951 * fully cleaned up. 952 * 953 * @return The status of thread exit request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 954 */ 955 #define cy_rtos_exit_thread cy_rtos_thread_exit 956 /** \} group_abstraction_rtos_threads */ 957 958 //================================================================================================== 959 // Mutexes 960 //================================================================================================== 961 /** 962 * \ingroup group_abstraction_rtos_mutex 963 * \{ 964 */ 965 966 /** Create a mutex which can support recursion or not. 967 * 968 * Creates a binary mutex which can be used for mutual exclusion to prevent simulatenous 969 * access of shared resources. Created mutexes can support priority inheritance if recursive. 970 * 971 * \note Not all RTOS implementations support non-recursive mutexes. In this case a recursive 972 * mutex will be created. 973 * 974 * @param[out] mutex Pointer to the mutex handle to be initialized 975 * @param[in] recursive Should the created mutex support recursion or not 976 * 977 * @return The status of mutex creation request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 978 * CY_RTOS_GENERAL_ERROR] 979 */ 980 #define cy_rtos_init_mutex2(mutex, recursive) \ 981 cy_rtos_mutex_init(mutex, recursive) 982 983 /** Create a mutex which can support recursion. 984 * 985 * Creates a binary mutex which can be used for mutual exclusion to prevent simulatenous 986 * access of shared resources. Created mutexes can support priority inheritance if recursive. 987 * 988 * \note Not all RTOS implementations support non-recursive mutexes. In this case a recursive 989 * mutex will be created. 990 * 991 * @param[out] mutex Pointer to the mutex handle to be initialized 992 * 993 * @return The status of mutex creation request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 994 * CY_RTOS_GENERAL_ERROR] 995 */ 996 #define cy_rtos_init_mutex(mutex) \ 997 cy_rtos_mutex_init(mutex, true) 998 999 /** Get a mutex. 1000 * 1001 * If the mutex is available, it is acquired and this function returned. 1002 * If the mutex is not available, the thread waits until the mutex is available 1003 * or until the timeout occurs. 1004 * 1005 * @note This function must not be called from an interrupt context as it may block. 1006 * 1007 * @param[in] mutex Pointer to the mutex handle 1008 * @param[in] timeout_ms Maximum number of milliseconds to wait while attempting to get 1009 * the mutex. Use the \ref CY_RTOS_NEVER_TIMEOUT constant to wait forever. 1010 * 1011 * @return The status of the get mutex. Returns timeout if mutex was not acquired 1012 * before timeout_ms period. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_TIMEOUT, \ref 1013 * CY_RTOS_GENERAL_ERROR] 1014 */ 1015 #define cy_rtos_get_mutex(mutex, timeout_ms) \ 1016 cy_rtos_mutex_get(mutex, timeout_ms) 1017 1018 /** Set a mutex. 1019 * 1020 * The mutex is released allowing any other threads waiting on the mutex to 1021 * obtain the semaphore. 1022 * 1023 * @param[in] mutex Pointer to the mutex handle 1024 * 1025 * @return The status of the set mutex request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1026 * 1027 */ 1028 #define cy_rtos_set_mutex(mutex) cy_rtos_mutex_set(mutex) 1029 1030 /** Deletes a mutex. 1031 * 1032 * This function frees the resources associated with a sempahore. 1033 * 1034 * @param[in] mutex Pointer to the mutex handle 1035 * 1036 * @return The status to the delete request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1037 */ 1038 #define cy_rtos_deinit_mutex(mutex) cy_rtos_mutex_deinit(mutex) 1039 1040 /** \} group_abstraction_rtos_mutex */ 1041 1042 //================================================================================================== 1043 // Semaphores 1044 //================================================================================================== 1045 /** 1046 * \ingroup group_abstraction_rtos_semaphore 1047 * \{ 1048 */ 1049 1050 /** 1051 * Create a semaphore 1052 * 1053 * This is basically a counting semaphore. It can be used for synchronization between tasks and 1054 * tasks and interrupts. 1055 * 1056 * @param[in,out] semaphore Pointer to the semaphore handle to be initialized 1057 * @param[in] maxcount The maximum count for this semaphore 1058 * @param[in] initcount The initial count for this semaphore 1059 * 1060 * @return The status of the semaphore creation. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1061 * CY_RTOS_GENERAL_ERROR] 1062 */ 1063 #define cy_rtos_init_semaphore(semaphore, maxcount, initcount) \ 1064 cy_rtos_semaphore_init(semaphore, maxcount, initcount) 1065 1066 /** 1067 * Get/Acquire a semaphore 1068 * 1069 * If the semaphore count is zero, waits until the semaphore count is greater than zero. 1070 * Once the semaphore count is greater than zero, this function decrements 1071 * the count and return. It may also return if the timeout is exceeded. 1072 * 1073 * @param[in] semaphore Pointer to the semaphore handle 1074 * @param[in] timeout_ms Maximum number of milliseconds to wait while attempting to get 1075 * the semaphore. Use the \ref CY_RTOS_NEVER_TIMEOUT constant to wait 1076 * forever. Must be zero if in_isr is true. 1077 * @param[in] in_isr true if we are trying to get the semaphore from with an ISR 1078 * @return The status of get semaphore operation [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_TIMEOUT, \ref 1079 * CY_RTOS_NO_MEMORY, \ref CY_RTOS_GENERAL_ERROR] 1080 */ 1081 #define cy_rtos_get_semaphore(semaphore, timeout_ms, \ 1082 in_isr) cy_rtos_semaphore_get(semaphore, timeout_ms) 1083 1084 /** 1085 * Set/Release a semaphore 1086 * 1087 * Increments the semaphore count, up to the maximum count for this semaphore. 1088 * 1089 * @param[in] semaphore Pointer to the semaphore handle 1090 * @param[in] in_isr Value of true indicates calling from interrupt context 1091 * Value of false indicates calling from normal thread context 1092 * @return The status of set semaphore operation [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1093 * CY_RTOS_GENERAL_ERROR] 1094 */ 1095 #define cy_rtos_set_semaphore(semaphore, in_isr) cy_rtos_semaphore_set(semaphore) 1096 1097 /** 1098 * Get the count of a semaphore. 1099 * 1100 * Gets the number of available tokens on the semaphore. 1101 * 1102 * @param[in] semaphore Pointer to the semaphore handle 1103 * @param[out] count Pointer to the return count 1104 * @return The status of get semaphore count operation [\ref CY_RSLT_SUCCESS, \ref 1105 * CY_RTOS_GENERAL_ERROR] 1106 */ 1107 #define cy_rtos_get_count_semaphore(semaphore, count) cy_rtos_semaphore_get_count(semaphore, count) 1108 1109 /** 1110 * Deletes a semaphore 1111 * 1112 * This function frees the resources associated with a semaphore. 1113 * 1114 * @param[in] semaphore Pointer to the semaphore handle 1115 * 1116 * @return The status of semaphore deletion [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1117 * CY_RTOS_GENERAL_ERROR] 1118 */ 1119 #define cy_rtos_deinit_semaphore(semaphore) cy_rtos_semaphore_deinit(semaphore) 1120 1121 /** \} group_abstraction_rtos_semaphore */ 1122 1123 //================================================================================================== 1124 // Events 1125 //================================================================================================== 1126 1127 /** 1128 * \ingroup group_abstraction_rtos_event 1129 * \{ 1130 */ 1131 1132 /** Create an event. 1133 * 1134 * This is an event which can be used to signal a set of threads 1135 * with a 32 bit data element. 1136 * 1137 * @param[in,out] event Pointer to the event handle to be initialized 1138 * 1139 * @return The status of the event initialization request. 1140 * [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref CY_RTOS_GENERAL_ERROR] 1141 */ 1142 #define cy_rtos_init_event(event) cy_rtos_event_init(event) 1143 1144 /** Set the event flag bits. 1145 * 1146 * This is an event which can be used to signal a set of threads 1147 * with a 32 bit data element. Any threads waiting on this event are released 1148 * 1149 * @param[in] event Pointer to the event handle 1150 * @param[in] bits The value of the 32 bit flags 1151 * @param[in] in_isr If true, this is called from an ISR, otherwise from a thread 1152 * 1153 * @return The status of the set request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1154 * CY_RTOS_GENERAL_ERROR] 1155 */ 1156 #define cy_rtos_setbits_event(event, bits, in_isr) cy_rtos_event_setbits(event, bits) 1157 1158 /** 1159 * Clear the event flag bits 1160 * 1161 * This function clears bits in the event. 1162 * 1163 * @param[in] event Pointer to the event handle 1164 * @param[in] bits Any bits set in this value, will be cleared in the event. 1165 * @param[in] in_isr if true, this is called from an ISR, otherwise from a thread 1166 * 1167 * @return The status of the clear flags request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, 1168 * \ref CY_RTOS_GENERAL_ERROR] 1169 */ 1170 #define cy_rtos_clearbits_event(event, bits, in_isr) cy_rtos_event_clearbits(event, bits) 1171 1172 /** Get the event bits. 1173 * 1174 * Returns the current bits for the event. 1175 * 1176 * @param[in] event Pointer to the event handle 1177 * @param[out] bits pointer to receive the value of the event flags 1178 * 1179 * @return The status of the get request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1180 * CY_RTOS_GENERAL_ERROR] 1181 */ 1182 #define cy_rtos_getbits_event(event, bits) cy_rtos_event_getbits(event, bits) 1183 1184 /** Wait for the event and return bits. 1185 * 1186 * Waits for the event to be set and then returns the bits associated 1187 * with the event, or waits for the given timeout period. 1188 * @note This function returns if any bit in the set is set. 1189 * 1190 * @param[in] event Pointer to the event handle 1191 * @param[in,out] bits pointer to receive the value of the event flags 1192 * @param[in] clear if true, clear any bits set that cause the wait to return 1193 * if false, do not clear bits 1194 * @param[in] all if true, all bits in the initial bits value must be set to return 1195 * if false, any one bit in the initial bits value must be set to return 1196 * @param[in] timeout_ms The amount of time to wait in milliseconds 1197 * 1198 * @return The status of the wait for event request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, 1199 * \ref CY_RTOS_GENERAL_ERROR] 1200 */ 1201 #define cy_rtos_waitbits_event(event, bits, clear, all, \ 1202 timeout_ms) \ 1203 cy_rtos_event_waitbits(event, bits, clear, all, timeout_ms) 1204 1205 /** Deinitialize a event. 1206 * 1207 * This function frees the resources associated with an event. 1208 * 1209 * @param[in] event Pointer to the event handle 1210 * 1211 * @return The status of the deletion request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1212 */ 1213 #define cy_rtos_deinit_event(event) cy_rtos_event_deinit(event) 1214 1215 /** \} group_abstraction_rtos_event */ 1216 1217 //================================================================================================== 1218 // Queues 1219 //================================================================================================== 1220 1221 /** 1222 * \ingroup group_abstraction_rtos_queue 1223 * \{ 1224 */ 1225 1226 /** Create a queue. 1227 * 1228 * This is a queue of data where entries are placed on the back of the queue 1229 * and removed from the front of the queue. 1230 * 1231 * @param[out] queue Pointer to the queue handle 1232 * @param[in] length The maximum length of the queue in items 1233 * @param[in] itemsize The size of each item in the queue. 1234 * 1235 * @return The status of the init request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1236 * CY_RTOS_GENERAL_ERROR] 1237 */ 1238 #define cy_rtos_init_queue(queue, length, itemsize) \ 1239 cy_rtos_queue_init(queue, length, itemsize) 1240 1241 /** Put an item in a queue. 1242 * 1243 * This function puts an item in the queue. The item is copied 1244 * into the queue using a memory copy and the data pointed to by item_ptr 1245 * is no longer referenced once the call returns. 1246 * 1247 * @note If in_isr is true, timeout_ms must be zero. 1248 * 1249 * @param[in] queue Pointer to the queue handle 1250 * @param[in] item_ptr Pointer to the item to place in the queue 1251 * @param[in] timeout_ms The time to wait to place the item in the queue 1252 * @param[in] in_isr If true this is being called from within and ISR 1253 * 1254 * @return The status of the put request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1255 * CY_RTOS_GENERAL_ERROR, \ref CY_RTOS_QUEUE_FULL] 1256 */ 1257 #define cy_rtos_put_queue(queue, item_ptr, timeout_ms, in_isr) \ 1258 cy_rtos_queue_put(queue, item_ptr, timeout_ms) 1259 1260 /** Gets an item in a queue. 1261 * 1262 * This function gets an item from the queue. The item is copied 1263 * out of the queue into the memory provide by item_ptr. This space must be 1264 * large enough to hold a queue entry as defined when the queue was initialized. 1265 * 1266 * @note If in_isr is true, timeout_ms must be zero. 1267 * @note A value of CY_RTOS_NEVER_TIMEOUT assigned to timeout_ms will cause the task to block 1268 * indefinitely (without a timeout). 1269 * 1270 * @param[in] queue Pointer to the queue handle 1271 * @param[in] item_ptr Pointer to the memory for the item from the queue 1272 * @param[in] timeout_ms The time to wait to get an item from the queue 1273 * @param[in] in_isr If true this is being called from within an ISR 1274 * 1275 * @return The status of the get request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_NO_MEMORY, \ref 1276 * CY_RTOS_GENERAL_ERROR, \ref CY_RTOS_QUEUE_EMPTY] 1277 */ 1278 #define cy_rtos_get_queue(queue, item_ptr, timeout_ms, in_isr) \ 1279 cy_rtos_queue_get(queue, item_ptr, timeout_ms) 1280 1281 /** Return the number of items in the queue. 1282 * 1283 * This function returns the number of items currently in the queue. 1284 * 1285 * @param[in] queue Pointer to the queue handle 1286 * @param[out] num_waiting Pointer to the return count 1287 * 1288 * @return The status of the count request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1289 */ 1290 #define cy_rtos_count_queue(queue, num_waiting) \ 1291 cy_rtos_queue_count(queue, num_waiting) 1292 1293 /** Return the amount of empty space in the queue. 1294 * 1295 * This function returns the amount of empty space in the 1296 * queue. For instance, if the queue was created with 10 entries max and there 1297 * are currently 2 entries in the queue, this will return 8. 1298 * 1299 * @param[in] queue Pointer to the queue handle 1300 * @param[out] num_spaces Pointer to the return count. 1301 * 1302 * @return The status of the space request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1303 */ 1304 #define cy_rtos_space_queue(queue, num_spaces) \ 1305 cy_rtos_queue_space(queue, num_spaces) 1306 1307 /** Reset the queue. 1308 * 1309 * This function sets the queue to empty. 1310 * 1311 * @param[in] queue pointer to the queue handle 1312 * 1313 * @return The status of the reset request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1314 */ 1315 #define cy_rtos_reset_queue(queue) \ 1316 cy_rtos_queue_reset(queue) 1317 1318 /** Deinitialize the queue handle. 1319 * 1320 * This function de-initializes the queue and returns all 1321 * resources used by the queue. 1322 * 1323 * @param[in] queue Pointer to the queue handle 1324 * 1325 * @return The status of the deinit request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1326 */ 1327 #define cy_rtos_deinit_queue(queue) \ 1328 cy_rtos_queue_deinit(queue) 1329 1330 /** \} group_abstraction_rtos_queue */ 1331 1332 //================================================================================================== 1333 // Timers 1334 //================================================================================================== 1335 1336 /** 1337 * \ingroup group_abstraction_rtos_timer 1338 * \{ 1339 */ 1340 1341 /** Create a new timer. 1342 * 1343 * This function initializes a timer object. 1344 * @note The timer is not active until start is called. 1345 * @note The callback may be (likely will be) called from a different thread. 1346 * 1347 * @param[out] timer Pointer to the timer handle to initialize 1348 * @param[in] type Type of timer (periodic or once) 1349 * @param[in] fun The function 1350 * @param[in] arg Argument to pass along to the callback function 1351 * 1352 * @return The status of the init request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1353 */ 1354 #define cy_rtos_init_timer(timer, type, fun, arg) \ 1355 cy_rtos_timer_init(timer, type, fun, arg) 1356 1357 /** Sends a request to start the timer. Depending on the priorities of threads in the system, 1358 * it may be necessary for high priority items to wait before the timer actually starts running. 1359 * 1360 * @param[in] timer Pointer to the timer handle 1361 * @param[in] num_ms The number of milliseconds to wait before the timer fires 1362 * 1363 * @return The status of the start request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1364 */ 1365 #define cy_rtos_start_timer(timer, num_ms) \ 1366 cy_rtos_timer_start(timer, num_ms) 1367 1368 /** Sends a request to stop the timer. Depending on the priorities of threads in the system, 1369 * it may be necessary for high priority items to wait before the timer is actually stopped. 1370 * 1371 * @param[in] timer Pointer to the timer handle 1372 * 1373 * @return The status of the stop request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1374 */ 1375 #define cy_rtos_stop_timer(timer) cy_rtos_timer_stop(timer) 1376 1377 /** Returns state of a timer. 1378 * 1379 * @param[in] timer Pointer to the timer handle 1380 * @param[out] state Return value for state, true if running, false otherwise 1381 * 1382 * @return The status of the is_running request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1383 */ 1384 #define cy_rtos_is_running_timer(timer, state) \ 1385 cy_rtos_timer_is_running(timer, state) 1386 1387 /** Deinit the timer. 1388 * 1389 * This function deinitializes the timer and frees all consumed resources. 1390 * 1391 * @param[in] timer Pointer to the timer handle 1392 * 1393 * @return The status of the deinit request. [\ref CY_RSLT_SUCCESS, \ref CY_RTOS_GENERAL_ERROR] 1394 */ 1395 #define cy_rtos_deinit_timer(timer) cy_rtos_timer_deinit(timer) 1396 1397 /** \} group_abstraction_rtos_timer */ 1398 1399 //================================================================================================== 1400 // Time 1401 //================================================================================================== 1402 1403 /** 1404 * \ingroup group_abstraction_rtos_time 1405 * \{ 1406 */ 1407 1408 /** Gets time in milliseconds since RTOS start. 1409 * 1410 * @note Since this is only 32 bits, it will roll over every 49 days, 17 hours, 2 mins, 47.296 1411 * seconds 1412 * 1413 * @param[out] tval Pointer to the struct to populate with the RTOS time 1414 * 1415 * @returns Time in milliseconds since the RTOS started. 1416 */ 1417 #define cy_rtos_get_time(tval) cy_rtos_time_get(tval) 1418 1419 /** \} group_abstraction_rtos_time */ 1420 1421 #ifdef __cplusplus 1422 } // extern "C" 1423 #endif 1424
