tool/mbed/mbed-sdk/libraries/mbed/targets/hal/TARGET_Freescale/TARGET_KPSDK_MCUS/TARGET_KPSDK_CODE/utilities/fsl_os_abstraction.h

   1 /*
   2  * Copyright (c) 2013 - 2014, Freescale Semiconductor, Inc.
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without modification,
   6  * are permitted provided that the following conditions are met:
   7  *
   8  * o Redistributions of source code must retain the above copyright notice, this list
   9  *   of conditions and the following disclaimer.
  10  *
  11  * o Redistributions in binary form must reproduce the above copyright notice, this
  12  *   list of conditions and the following disclaimer in the documentation and/or
  13  *   other materials provided with the distribution.
  14  *
  15  * o Neither the name of Freescale Semiconductor, Inc. nor the names of its
  16  *   contributors may be used to endorse or promote products derived from this
  17  *   software without specific prior written permission.
  18  *
  19  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  20  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  21  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  22  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  23  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  24  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  26  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29  */
  30 #if !defined(__FSL_OS_ABSTRACTION_H__)
  31 #define __FSL_OS_ABSTRACTION_H__
  32
  33 #include <stdint.h>
  34 #include <stdbool.h>
  35 #include <stdlib.h>
  36
  37 #if defined __CC_ARM
  38 #define inline      __inline
  39 #endif
  40
  41 /*!
  42  * @addtogroup os_abstraction
  43  * @{
  44  */
  45
  46 /*! @brief Status values to be returned by functions. */
  47 typedef enum
  48 {
  49     kSuccess = 0,  /*!< Functions work correctly.                   */
  50     kError,        /*!< Functions work failed.                      */
  51     kTimeout,      /*!< Timeout occurs while waiting for an object. */
  52     kIdle          /*!< Can not get the object in non-blocking mode.*/
  53 }fsl_rtos_status;
  54
  55 /*! @brief The event flags are set or not.*/
  56 typedef enum
  57 {
  58     kFlagNotSet = 0, /*!< The flags checked are set.     */
  59     kFlagSet         /*!< The flags checked are not set. */
  60 }event_status;
  61
  62 /*! @brief The event flags are cleared automatically or manually.*/
  63 typedef enum
  64 {
  65     kEventAutoClr = 0, /*!< The flags of the event will be cleared automatically. */
  66     kEventManualClr    /*!< The flags of the event will be cleared manually.      */
  67 }event_clear_type;
  68
  69 // Temporary "fix", until the proper macros are integrated in the on-line build system
  70 #define FSL_RTOS_MBED
  71
  72 /* Include required header file based on RTOS selection */
  73 #if defined (FSL_RTOS_MQX)
  74     /*! @brief Macro to set message queue copy messages to internal memory or not. */
  75     #define __FSL_RTOS_MSGQ_COPY_MSG__  1
  76     #include "fsl_os_abstraction_mqx.h"
  77
  78 #elif defined (FSL_RTOS_FREE_RTOS)
  79     #define __FSL_RTOS_MSGQ_COPY_MSG__  1
  80     #include "fsl_os_abstraction_free_rtos.h"
  81
  82 #elif defined (FSL_RTOS_UCOSII)
  83     #define __FSL_RTOS_MSGQ_COPY_MSG__  1
  84     #include "fsl_os_abstraction_ucosii.h"
  85
  86 #elif defined (FSL_RTOS_UCOSIII)
  87     #define __FSL_RTOS_MSGQ_COPY_MSG__  1
  88     #include "fsl_os_abstraction_ucosiii.h"
  89
  90 #elif defined (FSL_RTOS_CMSIS)
  91     #define __FSL_RTOS_MSGQ_COPY_MSG__  0
  92     #include "fsl_os_abstraction_cmsis.h"
  93
  94 #elif defined (FSL_RTOS_MBED)
  95     #define __FSL_RTOS_MSGQ_COPY_MSG__  1
  96     #include "fsl_os_abstraction_mbed.h"
  97
  98 #else
  99     #define __FSL_RTOS_MSGQ_COPY_MSG__  1
 100     #include "fsl_os_abstraction_bm.h"
 101 #endif
 102
 103 /*******************************************************************************
 104  * API
 105  ******************************************************************************/
 106
 107 #if defined(__cplusplus)
 108 extern "C" {
 109 #endif
 110
 111 /*!
 112  * @name Synchronization
 113  * @{
 114  */
 115
 116 /*!
 117  * @brief Initialize a synchronization object to a given state.
 118  *
 119  * @param obj The sync object to initialize.
 120  * @param initValue The initial value the object will be set to.
 121  *
 122  * @retval kSuccess The object was successfully created.
 123  * @retval kError Invalid parameter or no more objects can be created.
 124  */
 125 fsl_rtos_status sync_create(sync_object_t *obj, uint8_t initValue);
 126
 127 /*!
 128  * @brief Wait for the synchronization object.
 129  *
 130  * This function checks the sync object's counting value, if it is
 131  * positive, decreases it and returns kSuccess, otherwise, timeout will be
 132  * used for wait.
 133  *
 134  * @param obj Pointer to the synchronization object.
 135  * @param timeout The maximum number of milliseconds to wait for the object to be signalled.
 136  *      Pass the #kSyncWaitForever constant to wait indefinitely for someone to signal the object.
 137  *      A value of 0 should not be passed to this function. Instead, use sync_poll for
 138  *      a non blocking check.
 139  *
 140  * @retval kSuccess The object was signalled.
 141  * @retval kTimeout A timeout occurred.
 142  * @retval kError An incorrect parameter was passed.
 143  * @retval kIdle The object has not been signalled.
 144  *
 145  * @note There could be only one process waiting for the object at the same time.
 146  */
 147 fsl_rtos_status sync_wait(sync_object_t *obj, uint32_t timeout);
 148
 149 /*!
 150  * @brief Checks a synchronization object's status.
 151  *
 152  * This function is used to poll a sync object's status.
 153  * If the sync object's counting value is positive, decrease it and return
 154  * kSuccess. If the object's counting value is 0, the function will
 155  * return kIdle immediately
 156  *
 157  * @param obj The synchronization object.
 158  *
 159  * @retval kSuccess The object was signalled.
 160  * @retval kIdle The object was not signalled.
 161  * @retval kError An incorrect parameter was passed.
 162  */
 163 fsl_rtos_status sync_poll(sync_object_t *obj);
 164
 165 /*!
 166  * @brief Signal for someone waiting on the synchronization object to wake up.
 167  *
 168  * This function should not be called from an ISR.
 169  *
 170  * @param obj The synchronization object to signal.
 171  *
 172  * @retval kSuccess The object was successfully signaled.
 173  * @retval kError The object can not be signaled or invalid parameter.
 174  */
 175 fsl_rtos_status sync_signal(sync_object_t *obj);
 176
 177 /*!
 178  * @brief Signal for someone waiting on the synchronization object to wake up.
 179  *
 180  * This function should only be called from an ISR.
 181  *
 182  * @param obj The synchronization object to signal.
 183  *
 184  * @retval kSuccess The object was successfully signaled.
 185  * @retval kError The object can not be signaled or invalid parameter.
 186  */
 187 fsl_rtos_status sync_signal_from_isr(sync_object_t *obj);
 188
 189 /*!
 190  * @brief Destroy a previously created synchronization object.
 191  *
 192  * @param obj The synchronization object to destroy.
 193  *
 194  * @retval kSuccess The object was successfully destroyed.
 195  * @retval kError Object destruction failed.
 196  */
 197 fsl_rtos_status sync_destroy(sync_object_t *obj);
 198
 199 /* @} */
 200
 201 /*!
 202  * @name Resource locking
 203  * @{
 204  */
 205
 206 /*!
 207  * @brief Initialize a locking object.
 208  *
 209  * @param obj The lock object to initialize.
 210  *
 211  * @retval kSuccess The lock is created successfully.
 212  * @retval kError Tke lock creation failed.
 213  */
 214 fsl_rtos_status lock_create(lock_object_t *obj);
 215
 216 /*!
 217  * @brief Wait for the object to be unlocked and lock it.
 218  *
 219  * This function will wait for some time or wait forever if could not get the lock.
 220  *
 221  * @param obj The locking object.
 222  * @param timeout The maximum number of milliseconds to wait for the mutex.
 223  *      Pass the #kSyncWaitForever constant to wait indefinitely for someone to unlock the object.
 224  *      A value of 0 should not be passed to this function. Instead, use lock_poll for a non
 225  *      blocking check.
 226  *
 227  * @retval kSuccess The lock was obtained.
 228  * @retval kTimeout A timeout occurred.
 229  * @retval kError An incorrect parameter was passed.
 230  */
 231 fsl_rtos_status lock_wait(lock_object_t *obj, uint32_t timeout);
 232
 233 /*!
 234  * @brief Checks if a locking object can be locked and locks it if possible.
 235  *
 236  * This function returns instantly if could not get the lock.
 237  *
 238  * @param obj The locking object.
 239  *
 240  * @retval kSuccess The lock was obtained.
 241  * @retval kIdle The lock could not be obtained.
 242  * @retval kError An incorrect parameter was passed.
 243  *
 244  * @note There could be only one process waiting for the object at the same time.
 245  * For RTOSes, wait for a lock recursively by one task is not supported.
 246  *
 247  */
 248 fsl_rtos_status lock_poll(lock_object_t *obj);
 249
 250 /*!
 251  * @brief Unlock a previously locked object.
 252  *
 253  * @param obj The locking object to unlock.
 254  *
 255  * @retval kSuccess The object was successfully unlocked.
 256  * @retval kError The object can not be unlocked or invalid parameter.
 257  */
 258 fsl_rtos_status lock_release(lock_object_t *obj);
 259
 260 /*!
 261  * @brief Destroy a previously created locking object.
 262  *
 263  * @param obj The locking object to destroy.
 264  *
 265  * @retval kSuccess The object was successfully destroyed.
 266  * @retval kError Object destruction failed.
 267  */
 268 fsl_rtos_status lock_destroy(lock_object_t *obj);
 269
 270 /* @} */
 271
 272 /*!
 273  * @name Event signaling
 274  * @{
 275  */
 276
 277 /*!
 278  * @brief Initializes the event object.
 279  *
 280  * When the object is created, the flags is 0.
 281  *
 282  * @param obj Pointer to the event object to initialize.
 283  * @param clearType The event is auto-clear or manual-clear.
 284  *
 285  * @retval kSuccess The object was successfully created.
 286  * @retval kError Incorrect parameter or no more objects can be created.
 287  */
 288 fsl_rtos_status event_create(event_object_t *obj, event_clear_type clearType);
 289
 290 /*!
 291  * @brief Wait for any event flags to be set.
 292  *
 293  * This function will wait for some time or wait forever if no flags are set. Any flags set
 294  * will wake up the function.
 295  *
 296  * @param obj The event object.
 297  * @param timeout The maximum number of milliseconds to wait for the event.
 298  *      Pass the #kSyncWaitForever constant to wait indefinitely. A value of 0 should not be passed
 299  *      to this function.
 300  * @param setFlags Pointer to receive the flags that were set.
 301  *
 302  * @retval kSuccess An event was set.
 303  * @retval kTimeout A timeout occurred.
 304  * @retval kError An incorrect parameter was passed.
 305  */
 306 fsl_rtos_status event_wait(event_object_t *obj, uint32_t timeout, event_group_t *setFlags);
 307
 308 /*!
 309  * @brief Set one or more event flags of an event object.
 310  *
 311  * This function should not be called from an ISR.
 312  *
 313  * @param obj The event object.
 314  * @param flags Event flags to be set.
 315  *
 316  * @retval kSuccess The flags were successfully set.
 317  * @retval kError An incorrect parameter was passed.
 318  *
 319  * @note There could be only one process waiting for the event.
 320  *
 321  */
 322 fsl_rtos_status event_set(event_object_t *obj, event_group_t flags);
 323
 324 /*!
 325  * @brief Set one or more event flags of an event object.
 326  *
 327  * This function should only be called from an ISR.
 328  *
 329  * @param obj The event object.
 330  * @param flags Event flags to be set.
 331  *
 332  * @retval kSuccess The flags were successfully set.
 333  * @retval kError An incorrect parameter was passed.
 334  */
 335 fsl_rtos_status event_set_from_isr(event_object_t *obj, event_group_t flags);
 336
 337 /*!
 338  * @brief Clear one or more events of an event object.
 339  *
 340  * This function should not be called from an ISR.
 341  *
 342  * @param obj The event object.
 343  * @param flags Event flags to be clear.
 344  *
 345  * @retval kSuccess The flags were successfully cleared.
 346  * @retval kError An incorrect parameter was passed.
 347  */
 348 fsl_rtos_status event_clear(event_object_t *obj, event_group_t flags);
 349
 350 /*!
 351  * @brief Check the flags are set or not.
 352  *
 353  * @param obj The event object.
 354  * @param flag The flag to check.
 355  *
 356  * @retval kFlagsSet The flags checked are set.
 357  * @retval kFlagsNotSet The flags checked are not set or got an error.
 358  */
 359 event_status event_check_flags(event_object_t *obj, event_group_t flag);
 360
 361 /*!
 362  * @brief Destroy a previously created event object.
 363  *
 364  * @param obj The event object to destroy.
 365  *
 366  * @retval kSuccess The object was successfully destroyed.
 367  * @retval kError Event destruction failed.
 368  */
 369 fsl_rtos_status event_destroy(event_object_t *obj);
 370 /* @} */
 371
 372 /*!
 373  * @name Thread management
 374  * @{
 375  */
 376
 377 /*!
 378  * @brief Create a task.
 379  *
 380  * This function is wrapped by the macro task_create. Generally, this function is for
 381  * internal use only, applications must use FSL_RTOS_TASK_DEFINE to define resources for
 382  * task statically then use task_create to create task. If applications have prepare
 383  * the resouces for task dynamically, they can use this function to create the task.
 384  *
 385  * @param task The task function.
 386  * @param name The name of this task.
 387  * @param stackSize The stack size in byte.
 388  * @param stackMem Pointer to the stack. For bare metal, MQX and FreeRTOS, this could be NULL.
 389  * @param priority Initial priority of the task.
 390  * @param param Pointer to be passed to the task when it is created.
 391  * @param usesFloat This task will use float register or not.
 392  * @param handler Pointer to the task handler.
 393  *
 394  * @retval kSuccess The task was successfully created.
 395  * @retval kError The task could not be created.
 396  *
 397  * @note Different tasks can not use the same task function.
 398  */
 399 fsl_rtos_status __task_create(task_t task, uint8_t *name, uint16_t stackSize,
 400                               task_stack_t *stackMem, uint16_t priority,
 401                               void *param, bool usesFloat, task_handler_t *handler);
 402
 403 /*!
 404  * @brief Destroy a previously created task.
 405  * @note Depending on the RTOS, task resources may or may not be automatically freed,
 406  *       and this function may not return if the current task is destroyed.
 407  *
 408  * @param handler The handler of the task to destroy. Returned by the task_create function.
 409  *
 410  * @retval kSuccess The task was successfully destroyed.
 411  * @retval kError Task destruction failed or invalid parameter.
 412  */
 413 fsl_rtos_status task_destroy(task_handler_t handler);
 414 /* @} */
 415
 416 /*!
 417  * @name Message queues
 418  * @{
 419  */
 420
 421 /*!
 422  * @brief Initialize the message queue.
 423  *
 424  * This function will initialize the message queue that declared previously.
 425  * Here is an example demonstrating how to use:
 426    @code
 427    msg_queue_handler_t handler;
 428    MSG_QUEUE_DECLARE(my_message, msg_num, msg_size);
 429    handler = msg_queue_create(&my_message, msg_num, msg_size);
 430    @endcode
 431  *
 432  * @param queue The queue declared through the MSG_QUEUE_DECLARE macro.
 433  * @param number The number of elements in the queue.
 434  * @param size Size of every elements in words.
 435  *
 436  * @retval Handler to access the queue for put and get operations. If message queue
 437  *         created failed, return 0.
 438  */
 439 msg_queue_handler_t msg_queue_create(msg_queue_t *queue, uint16_t number, uint16_t size);
 440
 441 /*!
 442  * @brief Introduce an element at the tail of the queue.
 443  *
 444  * @param handler Queue handler returned by the msg_queue_create function.
 445  * @param item Pointer to the element to be introduced in the queue.
 446  *
 447  * @retval kSuccess Element successfully introduced in the queue.
 448  * @retval kError The queue was full or an invalid parameter was passed.
 449  */
 450 fsl_rtos_status msg_queue_put(msg_queue_handler_t handler, msg_queue_item_t item);
 451
 452 /*!
 453  * @brief Read and remove an element at the head of the queue.
 454  *
 455  * @param handler Queue handler returned by the msg_queue_create function.
 456  * @param item Pointer to store a pointer to the element of the queue.
 457  * @param timeout In case the queue is empty, the number of milliseconds to
 458  *        wait for an element to be introduced into the queue. Use 0 to return
 459  *        immediately or #kSyncWaitForever to wait indefinitely.
 460  *
 461  * @retval kSuccess Element successfully obtained from the queue.
 462  * @retval kTimeout If a timeout was specified, the queue remained empty after timeout.
 463  * @retval kError The queue was empty or the handler was invalid.
 464  * @retval kIdle The queue was empty and the timeout has not expired.
 465  *
 466  * @note There should be only one process waiting on the queue.
 467  */
 468 fsl_rtos_status msg_queue_get(msg_queue_handler_t handler,
 469                               msg_queue_item_t   *item,
 470                               uint32_t            timeout);
 471
 472 /*!
 473  * @brief Discards all elements in the queue and leaves the queue empty.
 474  *
 475  * @param handler Queue handler returned by the msg_queue_create function.
 476  *
 477  * @retval kSuccess Queue successfully emptied.
 478  * @retval kError Emptying queue failed.
 479  */
 480 fsl_rtos_status msg_queue_flush(msg_queue_handler_t handler);
 481
 482 /*!
 483  * @brief Destroy a previously created queue.
 484  *
 485  * @param handler Queue handler returned by the msg_queue_create function.
 486  *
 487  * @retval kSuccess The queue was successfully destroyed.
 488  * @retval kError Message queue destruction failed.
 489  */
 490 fsl_rtos_status msg_queue_destroy(msg_queue_handler_t handler);
 491
 492 /* @} */
 493
 494 #ifndef FSL_RTOS_MBED
 495 /*!
 496  * @name Memory Management
 497  * @{
 498  */
 499
 500 /*!
 501  * @brief Reserves the requested amount of memory in bytes.
 502  *
 503  * @param size Amount of bytes to reserve.
 504  *
 505  * @retval Pointer to the reserved memory. NULL if memory could not be allocated.
 506  */
 507 void * mem_allocate(size_t size);
 508
 509 /*!
 510  * @brief Reserves the requested amount of memory in bytes and initializes it to 0.
 511  *
 512  * @param size Amount of bytes to reserve.
 513  *
 514  * @retval Pointer to the reserved memory. NULL if memory could not be allocated.
 515  */
 516 void * mem_allocate_zero(size_t size);
 517
 518 /*!
 519  * @brief Releases the memory previously reserved.
 520  *
 521  * @param ptr Pointer to the start of the memory block previously reserved.
 522  *
 523  * @retval kSuccess Memory correctly released.
 524  */
 525 fsl_rtos_status mem_free(void *ptr);
 526 #endif
 527
 528 /* @} */
 529
 530 /*!
 531  * @name Time management
 532  * @{
 533  */
 534
 535 /*!
 536  * @brief Delays execution for a number of milliseconds.
 537  *
 538  * @param delay The time in milliseconds to wait.
 539  */
 540 void time_delay(uint32_t delay);
 541
 542 /* @} */
 543
 544 /*!
 545  * @name Interrupt management
 546  * @{
 547  */
 548
 549 /*!
 550  * @brief Install interrupt handler.
 551  *
 552  * @param irqNumber IRQ number of the interrupt.
 553  * @param handler The interrupt handler to install.
 554  *
 555  * @retval kSuccess Handler is installed successfully.
 556  * @retval kSuccess Handler could not be installed.
 557  */
 558 fsl_rtos_status interrupt_handler_register(int32_t irqNumber, void (*handler)(void));
 559
 560 /* @} */
 561
 562 #if defined(__cplusplus)
 563 }
 564 #endif
 565
 566 /*! @}*/
 567
 568 #endif /* __FSL_OS_ABSTRACTION_H__ */
 569 /*******************************************************************************
 570  * EOF
 571  ******************************************************************************/
 572