src/common/usb_osa.h

   1 /*
   2  * The Clear BSD License
   3  * Copyright (c) 2015 - 2016, Freescale Semiconductor, Inc.
   4  * Copyright 2016 NXP
   5  * All rights reserved.
   6  *
   7  * Redistribution and use in source and binary forms, with or without modification,
   8  * are permitted (subject to the limitations in the disclaimer below) provided
   9  * that the following conditions are met:
  10  *
  11  * o Redistributions of source code must retain the above copyright notice, this list
  12  *   of conditions and the following disclaimer.
  13  *
  14  * o Redistributions in binary form must reproduce the above copyright notice, this
  15  *   list of conditions and the following disclaimer in the documentation and/or
  16  *   other materials provided with the distribution.
  17  *
  18  * o Neither the name of the copyright holder nor the names of its
  19  *   contributors may be used to endorse or promote products derived from this
  20  *   software without specific prior written permission.
  21  *
  22  * NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY THIS LICENSE.
  23  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
  24  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  25  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  26  * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
  27  * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  28  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  29  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
  30  * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  32  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  33  */
  34
  35 #ifndef __USB_OSA_H__
  36 #define __USB_OSA_H__
  37
  38 /*!
  39  * @addtogroup usb_os_abstraction
  40  * @{
  41  */
  42
  43 /*******************************************************************************
  44  * Definitions
  45  ******************************************************************************/
  46
  47 /*! @brief Define big endian */
  48 #define USB_BIG_ENDIAN (0U)
  49 /*! @brief Define little endian */
  50 #define USB_LITTLE_ENDIAN (1U)
  51
  52 /*! @brief Define current endian */
  53 #define ENDIANNESS USB_LITTLE_ENDIAN
  54
  55 /*! @brief Define USB OSA event handle */
  56 typedef void *usb_osa_event_handle;
  57
  58 /*! @brief Define USB OSA semaphore handle */
  59 typedef void *usb_osa_sem_handle;
  60
  61 /*! @brief Define USB OSA mutex handle */
  62 typedef void *usb_osa_mutex_handle;
  63
  64 /*! @brief Define USB OSA message queue handle */
  65 typedef void *usb_osa_msgq_handle;
  66
  67 /*! @brief USB OSA error code */
  68 typedef enum _usb_osa_status
  69 {
  70     kStatus_USB_OSA_Success = 0x00U, /*!< Success */
  71     kStatus_USB_OSA_Error,           /*!< Failed */
  72     kStatus_USB_OSA_TimeOut,         /*!< Timeout occurs while waiting */
  73 } usb_osa_status_t;
  74
  75 /*! @brief The event flags are cleared automatically or manually.*/
  76 typedef enum _usb_osa_event_mode
  77 {
  78     kUSB_OsaEventManualClear = 0U, /*!< The flags of the event is cleared manually. */
  79     kUSB_OsaEventAutoClear = 1U,   /*!< The flags of the event is cleared automatically. */
  80 } usb_osa_event_mode_t;
  81
  82 /* Include required header file based on RTOS selection */
  83 #if defined(USB_STACK_BM)
  84
  85 #include "usb_osa_bm.h"
  86
  87 #elif defined(USB_STACK_FREERTOS)
  88
  89 #include "usb_osa_freertos.h"
  90
  91 #elif defined(USB_STACK_UCOSII)
  92
  93 #include "usb_osa_ucosii.h"
  94
  95 #elif defined(USB_STACK_UCOSIII)
  96
  97 #include "usb_osa_ucosiii.h"
  98
  99 #else
 100 #if defined(SDK_OS_BAREMETAL)
 101
 102 #define USB_STACK_BM
 103 #include "usb_osa_bm.h"
 104
 105 #elif defined(SDK_OS_FREE_RTOS)
 106
 107 #define USB_STACK_FREERTOS
 108 #include "usb_osa_freertos.h"
 109
 110 #elif defined(SDK_OS_UCOSII)
 111
 112 #define USB_STACK_UCOSII
 113 #include "usb_osa_ucosii.h"
 114
 115 #elif defined(SDK_OS_UCOSIII)
 116
 117 #define USB_STACK_UCOSIII
 118 #include "usb_osa_ucosiii.h"
 119
 120 #else
 121
 122 #error Not define RTOS in file "usb_osa.h".
 123 #endif
 124 #endif
 125
 126 /*******************************************************************************
 127  * API
 128  ******************************************************************************/
 129
 130 #if defined(__cplusplus)
 131 extern "C" {
 132 #endif
 133
 134 /*!
 135  * @name USB OSA Memory Management
 136  * @{
 137  */
 138
 139 /*!
 140  * @brief Reserves the requested amount of memory in bytes.
 141  *
 142  * The function is used to reserve the requested amount of memory in bytes and initializes it to 0.
 143  *
 144  * @param length Amount of bytes to reserve.
 145  *
 146  * @return Pointer to the reserved memory. NULL if memory can't be allocated.
 147  */
 148 void *USB_OsaMemoryAllocate(uint32_t length);
 149
 150 /*!
 151  * @brief Frees the memory previously reserved.
 152  *
 153  * The function is used to free the memory block previously reserved.
 154  *
 155  * @param p Pointer to the start of the memory block previously reserved.
 156  *
 157  */
 158 extern void USB_OsaMemoryFree(void *p);
 159
 160 /* @} */
 161
 162 /*!
 163  * @name USB OSA Event
 164  * @{
 165  */
 166
 167 /*!
 168  * @brief Creates an event object with all flags cleared.
 169  *
 170  * This function creates an event object and sets its clear mode. If the clear mode
 171  * is kUSB_OsaEventAutoClear, when a task gets the event flags, these flags are
 172  * cleared automatically. If the clear mode is kUSB_OsaEventManualClear, the flags must
 173  * be cleared manually.
 174  *
 175  * @param handle    It is an out parameter, which is used to return the pointer of the event object.
 176  * @param flag      The event is auto-clear or manual-clear. See the enumeration #usb_osa_event_mode_t.
 177  *
 178  * @return A USB OSA error code or kStatus_OSA_Success.
 179  *
 180  * Example:
 181    @code
 182    usb_osa_event_handle eventHandle;
 183    usb_osa_status_t     usbOsaStatus;
 184    usbOsaStatus = USB_OsaEventCreate(&eventHandle, kUSB_OsaEventManualClear);
 185    @endcode
 186  *
 187  */
 188 extern usb_osa_status_t USB_OsaEventCreate(usb_osa_event_handle *handle, uint32_t flag);
 189
 190 /*!
 191  * @brief Destroys a created event object.
 192  *
 193  * @param handle    Pointer to the event object.
 194  *
 195  * @return A USB OSA error code or kStatus_OSA_Success.
 196  *
 197  * Example:
 198    @code
 199    usb_osa_status_t     usbOsaStatus;
 200    ...
 201    usbOsaStatus = USB_OsaEventDestroy(eventHandle);
 202    @endcode
 203  *
 204  */
 205 extern usb_osa_status_t USB_OsaEventDestroy(usb_osa_event_handle handle);
 206
 207 /*!
 208  * @brief Sets an event flag.
 209  *
 210  * Sets specified flags for an event object.
 211  *
 212  * @param handle    Pointer to the event object.
 213  * @param bitMask   Event flags to be set.
 214  *
 215  * @return A USB OSA error code or kStatus_OSA_Success.
 216  *
 217  * Example:
 218    @code
 219    usb_osa_status_t     usbOsaStatus;
 220    ...
 221    usbOsaStatus = USB_OsaEventSet(eventHandle, 0x01U);
 222    @endcode
 223  *
 224  */
 225 extern usb_osa_status_t USB_OsaEventSet(usb_osa_event_handle handle, uint32_t bitMask);
 226
 227 /*!
 228  * @brief Waits for an event flag.
 229  *
 230  * This function waits for a combination of flags to be set in an event object.
 231  * An applications can wait for any/all bits to be set. This function can
 232  * get the flags that wake up the waiting task.
 233  *
 234  * @param handle    Pointer to the event object.
 235  * @param bitMask   Event flags to wait.
 236  * @param flag      Wait all flags or any flag to be set. 0U - wait any flag, others, wait all flags.
 237  * @param timeout   The maximum number of milliseconds to wait for the event.
 238  *                  If the wait condition is not met, passing 0U
 239  *                  waits indefinitely when the environment is an RTOS and returns the kStatus_OSA_Timeout
 240  *                  immediately. Pass any value for the bare metal.
 241  * @param bitSet    Flags that wake up the waiting task are obtained by this parameter.
 242  *
 243  * @return An USB OSA error code or kStatus_OSA_Success.
 244  *
 245  * Example:
 246    @code
 247    usb_osa_status_t     usbOsaStatus;
 248    uint32_t             bitSet;
 249    ...
 250    usbOsaStatus = USB_OsaEventWait(eventHandle, 0x01U, 0U, 0U, &bitSet);
 251    @endcode
 252  *
 253  */
 254 extern usb_osa_status_t USB_OsaEventWait(
 255     usb_osa_event_handle handle, uint32_t bitMask, uint32_t flag, uint32_t timeout, uint32_t *bitSet);
 256
 257 /*!
 258  * @brief Checks an event flag.
 259  *
 260  * This function checks for a combination of flags to be set in an event object.
 261  *
 262  * @param handle   Pointer to the event object.
 263  * @param bitMask  Event flags to check.
 264  * @param bitSet   Flags have been set.
 265  *
 266  * @return An USB OSA error code or kStatus_OSA_Success.
 267  *
 268  * Example:
 269    @code
 270    usb_osa_status_t     usbOsaStatus;
 271    uint32_t             bitSet;
 272    ...
 273    usbOsaStatus = USB_OsaEventCheck(eventHandle, 0x01U, &bitSet);
 274    @endcode
 275  *
 276  */
 277 extern usb_osa_status_t USB_OsaEventCheck(usb_osa_event_handle handle, uint32_t bitMask, uint32_t *bitSet);
 278
 279 /*!
 280  * @brief Clears an event flag.
 281  *
 282  * This function clears flags of an event object.
 283  *
 284  * @param handle    Pointer to the event object
 285  * @param bitMask   Event flags to be cleared.
 286  *
 287  * @return An USB OSA error code or kStatus_OSA_Success.
 288  *
 289  * Example:
 290    @code
 291    usb_osa_status_t     usbOsaStatus;
 292    ...
 293    usbOsaStatus = USB_OsaEventClear(eventHandle, 0x01U);
 294    @endcode
 295  */
 296 extern usb_osa_status_t USB_OsaEventClear(usb_osa_event_handle handle, uint32_t bitMask);
 297 /* @} */
 298
 299 /*!
 300  * @name USB OSA Semaphore
 301  * @{
 302  */
 303
 304 /*!
 305  * @brief Creates a semaphore with a given value.
 306  *
 307  * This function creates a semaphore and sets the default count.
 308  *
 309  * @param handle    It is an out parameter, which is used to return pointer of the semaphore object.
 310  * @param count     Initializes a value of the semaphore.
 311  *
 312  * @return An USB OSA error code or kStatus_OSA_Success.
 313  *
 314  * Example:
 315    @code
 316    usb_osa_sem_handle   semHandle;
 317    usb_osa_status_t     usbOsaStatus;
 318    usbOsaStatus = USB_OsaSemCreate(&semHandle, 1U);
 319    @endcode
 320  *
 321  */
 322 extern usb_osa_status_t USB_OsaSemCreate(usb_osa_sem_handle *handle, uint32_t count);
 323
 324 /*!
 325  * @brief Destroys a semaphore object.
 326  *
 327  * This function destroys a semaphore object.
 328  *
 329  * @param handle    Pointer to the semaphore.
 330  *
 331  * @return An USB OSA error code or kStatus_OSA_Success.
 332  *
 333  * Example:
 334    @code
 335    usb_osa_sem_handle   semHandle;
 336    usb_osa_status_t     usbOsaStatus;
 337    ...
 338    usbOsaStatus = USB_OsaSemDestroy(semHandle);
 339    @endcode
 340  *
 341  */
 342 extern usb_osa_status_t USB_OsaSemDestroy(usb_osa_sem_handle handle);
 343
 344 /*!
 345  * @brief Posts a semaphore.
 346  *
 347  * This function wakes up a task waiting on the semaphore. If a task is not pending, increases the semaphore's
 348  value.
 349  *
 350  * @param handle    Pointer to the semaphore.
 351  *
 352  * @return A USB OSA error code or kStatus_OSA_Success.
 353  *
 354  * Example:
 355    @code
 356    usb_osa_sem_handle   semHandle;
 357    usb_osa_status_t     usbOsaStatus;
 358    ...
 359    usbOsaStatus = USB_OsaSemPost(semHandle);
 360    @endcode
 361  *
 362  */
 363 extern usb_osa_status_t USB_OsaSemPost(usb_osa_sem_handle handle);
 364
 365 /*!
 366  * @brief Waits on a semaphore.
 367  *
 368  * This function checks the semaphore's value. If it is positive, it decreases the semaphore's value and return
 369  kStatus_OSA_Success.
 370  *
 371  * @param handle    Pointer to the semaphore.
 372  * @param timeout   The maximum number of milliseconds to wait for the semaphore.
 373  *                  If the wait condition is not met, passing 0U
 374  *                  waits indefinitely when environment is RTOS. And return kStatus_OSA_Timeout
 375  *                  immediately for bare metal no matter what value has been passed.
 376  *
 377  * @return A USB OSA error code or kStatus_OSA_Success.
 378  *
 379  * Example:
 380    @code
 381    usb_osa_sem_handle   semHandle;
 382    usb_osa_status_t     usbOsaStatus;
 383    ...
 384    usbOsaStatus = USB_OsaSemWait(semHandle, 0U);
 385    @endcode
 386  *
 387  */
 388 extern usb_osa_status_t USB_OsaSemWait(usb_osa_sem_handle handle, uint32_t timeout);
 389 /* @} */
 390
 391 /*!
 392  * @name USB OSA Mutex
 393  * @{
 394  */
 395
 396 /*!
 397  * @brief Creates a mutex.
 398  *
 399  * This function creates a mutex and sets it to an unlocked status.
 400  *
 401  * @param handle    It is out parameter, which is used to return the pointer of the mutex object.
 402  *
 403  * @return A USB OSA error code or kStatus_OSA_Success.
 404  *
 405  * Example:
 406    @code
 407    usb_osa_mutex_handle mutexHandle;
 408    usb_osa_status_t     usbOsaStatus;
 409    usbOsaStatus = USB_OsaMutexCreate(&mutexHandle);
 410    @endcode
 411  *
 412  */
 413 extern usb_osa_status_t USB_OsaMutexCreate(usb_osa_mutex_handle *handle);
 414
 415 /*!
 416  * @brief Destroys a mutex.
 417  *
 418  * This function destroys a mutex and sets it to an unlocked status.
 419  *
 420  * @param handle    Pointer to the mutex.
 421  *
 422  * @return A USB OSA error code or kStatus_OSA_Success.
 423  *
 424  * Example:
 425    @code
 426    usb_osa_mutex_handle mutexHandle;
 427    usb_osa_status_t     usbOsaStatus;
 428    ...
 429    usbOsaStatus = USB_OsaMutexDestroy(mutexHandle);
 430    @endcode
 431  *
 432  */
 433 extern usb_osa_status_t USB_OsaMutexDestroy(usb_osa_mutex_handle handle);
 434
 435 /*!
 436  * @brief Waits for a mutex and locks it.
 437  *
 438  * This function checks the mutex status. If it is unlocked, it locks it and returns the
 439  * kStatus_OSA_Success. Otherwise, it waits forever to lock in RTOS and returns the
 440  * kStatus_OSA_Success immediately for bare metal.
 441  *
 442  * @param handle    Pointer to the mutex.
 443  *
 444  * @return A USB OSA error code or kStatus_OSA_Success.
 445  *
 446  * Example:
 447    @code
 448    usb_osa_mutex_handle mutexHandle;
 449    usb_osa_status_t     usbOsaStatus;
 450    ...
 451    usbOsaStatus = USB_OsaMutexLock(mutexHandle);
 452    @endcode
 453  *
 454  */
 455 extern usb_osa_status_t USB_OsaMutexLock(usb_osa_mutex_handle handle);
 456
 457 /*!
 458  * @brief Unlocks a mutex.
 459  *
 460  * This function unlocks a mutex.
 461  *
 462  * @param handle    Pointer to the mutex.
 463  *
 464  * @return A USB OSA error code or kStatus_OSA_Success.
 465  *
 466  * Example:
 467    @code
 468    usb_osa_mutex_handle mutexHandle;
 469    usb_osa_status_t     usbOsaStatus;
 470    ...
 471    usbOsaStatus = USB_OsaMutexUnlock(mutexHandle);
 472    @endcode
 473  *
 474  */
 475 extern usb_osa_status_t USB_OsaMutexUnlock(usb_osa_mutex_handle handle);
 476 /* @} */
 477
 478 /*!
 479  * @name USB OSA Message Queue
 480  * @{
 481  */
 482
 483 /*!
 484  * @brief Creates a message queue.
 485  *
 486  * This function creates a message queue.
 487  *
 488  * @param handle    It is an out parameter, which is used to return a pointer of the message queue object.
 489  * @param count     The count of elements in the queue.
 490  * @param size      Size of every elements in words.
 491  *
 492  * @return A USB OSA error code or kStatus_OSA_Success.
 493  *
 494  * Example:
 495    @code
 496    usb_osa_msgq_handle  msgqHandle;
 497    usb_osa_status_t     usbOsaStatus;
 498    usbOsaStatus = USB_OsaMsgqCreate(msgqHandle, 8U, 4U);
 499    @endcode
 500  *
 501  */
 502 extern usb_osa_status_t USB_OsaMsgqCreate(usb_osa_msgq_handle *handle, uint32_t count, uint32_t size);
 503
 504 /*!
 505  * @brief Destroys a message queue.
 506  *
 507  * This function destroys a message queue.
 508  *
 509  * @param handle    Pointer to a message queue.
 510  *
 511  * @return A USB OSA error code or kStatus_OSA_Success.
 512  *
 513  * Example:
 514    @code
 515    usb_osa_msgq_handle  msgqHandle;
 516    usb_osa_status_t     usbOsaStatus;
 517    ...
 518    usbOsaStatus = USB_OsaMsgqDestroy(msgqHandle);
 519    @endcode
 520  *
 521  */
 522 extern usb_osa_status_t USB_OsaMsgqDestroy(usb_osa_msgq_handle handle);
 523
 524 /*!
 525  * @brief Sends a message.
 526  *
 527  * This function sends a message to the tail of the message queue.
 528  *
 529  * @param handle    Pointer to a message queue.
 530  * @param msg       The pointer to a message to be put into the queue.
 531  *
 532  * @return A USB OSA error code or kStatus_OSA_Success.
 533  *
 534  * Example:
 535    @code
 536    usb_osa_msgq_handle      msgqHandle;
 537    message_struct_t         message;
 538    usb_osa_status_t         usbOsaStatus;
 539    ...
 540    usbOsaStatus = USB_OsaMsgqSend(msgqHandle, &message);
 541    @endcode
 542  *
 543  */
 544 extern usb_osa_status_t USB_OsaMsgqSend(usb_osa_msgq_handle handle, void *msg);
 545
 546 /*!
 547  * @brief Receives a message.
 548  *
 549  * This function receives a message from the head of the message queue.
 550  *
 551  * @param handle    Pointer to a message queue.
 552  * @param msg       The pointer to save a received message.
 553  * @param timeout   The maximum number of milliseconds to wait for a message.
 554  *                  If the wait condition is not met, passing 0U
 555  *                  waits indefinitely when an environment is RTOS and returns the kStatus_OSA_Timeout
 556  *                  immediately for bare metal.
 557  *
 558  * @return A USB OSA error code or kStatus_OSA_Success.
 559  *
 560  * Example:
 561    @code
 562    usb_osa_msgq_handle      msgqHandle;
 563    message_struct_t         message;
 564    usb_osa_status_t         usbOsaStatus;
 565    ...
 566    usbOsaStatus = USB_OsaMsgqRecv(msgqHandle, &message, 0U);
 567    @endcode
 568  *
 569  */
 570 extern usb_osa_status_t USB_OsaMsgqRecv(usb_osa_msgq_handle handle, void *msg, uint32_t timeout);
 571
 572 /*!
 573  * @brief Checks a message queue and receives a message if the queue is not empty.
 574  *
 575  * This function checks a message queue and receives a message if the queue is not empty.
 576  *
 577  * @param handle    Pointer to a message queue.
 578  * @param msg       The pointer to save a received message.
 579  *
 580  * @return A USB OSA error code or kStatus_OSA_Success.
 581  *
 582  * Example:
 583    @code
 584    usb_osa_msgq_handle      msgqHandle;
 585    message_struct_t         message;
 586    usb_osa_status_t         usbOsaStatus;
 587    ...
 588    usbOsaStatus = USB_OsaMsgqCheck(msgqHandle, &message);
 589    @endcode
 590  *
 591  */
 592 extern usb_osa_status_t USB_OsaMsgqCheck(usb_osa_msgq_handle handle, void *msg);
 593
 594 /* @} */
 595
 596 #if defined(__cplusplus)
 597 }
 598 #endif
 599
 600 /* @} */
 601
 602 #endif /* __USB_OSA_H__ */