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 "usb_osa_bm.h"
  83
  84 /*******************************************************************************
  85  * API
  86  ******************************************************************************/
  87
  88 #if defined(__cplusplus)
  89 extern "C" {
  90 #endif
  91
  92 /*!
  93  * @name USB OSA Memory Management
  94  * @{
  95  */
  96
  97 /*!
  98  * @brief Reserves the requested amount of memory in bytes.
  99  *
 100  * The function is used to reserve the requested amount of memory in bytes and initializes it to 0.
 101  *
 102  * @param length Amount of bytes to reserve.
 103  *
 104  * @return Pointer to the reserved memory. NULL if memory can't be allocated.
 105  */
 106 void *USB_OsaMemoryAllocate(uint32_t length);
 107
 108 /*!
 109  * @brief Frees the memory previously reserved.
 110  *
 111  * The function is used to free the memory block previously reserved.
 112  *
 113  * @param p Pointer to the start of the memory block previously reserved.
 114  *
 115  */
 116 extern void USB_OsaMemoryFree(void *p);
 117
 118 /* @} */
 119
 120 /*!
 121  * @name USB OSA Event
 122  * @{
 123  */
 124
 125 /*!
 126  * @brief Creates an event object with all flags cleared.
 127  *
 128  * This function creates an event object and sets its clear mode. If the clear mode
 129  * is kUSB_OsaEventAutoClear, when a task gets the event flags, these flags are
 130  * cleared automatically. If the clear mode is kUSB_OsaEventManualClear, the flags must
 131  * be cleared manually.
 132  *
 133  * @param handle    It is an out parameter, which is used to return the pointer of the event object.
 134  * @param flag      The event is auto-clear or manual-clear. See the enumeration #usb_osa_event_mode_t.
 135  *
 136  * @return A USB OSA error code or kStatus_OSA_Success.
 137  *
 138  * Example:
 139    @code
 140    usb_osa_event_handle eventHandle;
 141    usb_osa_status_t     usbOsaStatus;
 142    usbOsaStatus = USB_OsaEventCreate(&eventHandle, kUSB_OsaEventManualClear);
 143    @endcode
 144  *
 145  */
 146 extern usb_osa_status_t USB_OsaEventCreate(usb_osa_event_handle *handle, uint32_t flag);
 147
 148 /*!
 149  * @brief Destroys a created event object.
 150  *
 151  * @param handle    Pointer to the event object.
 152  *
 153  * @return A USB OSA error code or kStatus_OSA_Success.
 154  *
 155  * Example:
 156    @code
 157    usb_osa_status_t     usbOsaStatus;
 158    ...
 159    usbOsaStatus = USB_OsaEventDestroy(eventHandle);
 160    @endcode
 161  *
 162  */
 163 extern usb_osa_status_t USB_OsaEventDestroy(usb_osa_event_handle handle);
 164
 165 /*!
 166  * @brief Sets an event flag.
 167  *
 168  * Sets specified flags for an event object.
 169  *
 170  * @param handle    Pointer to the event object.
 171  * @param bitMask   Event flags to be set.
 172  *
 173  * @return A USB OSA error code or kStatus_OSA_Success.
 174  *
 175  * Example:
 176    @code
 177    usb_osa_status_t     usbOsaStatus;
 178    ...
 179    usbOsaStatus = USB_OsaEventSet(eventHandle, 0x01U);
 180    @endcode
 181  *
 182  */
 183 extern usb_osa_status_t USB_OsaEventSet(usb_osa_event_handle handle, uint32_t bitMask);
 184
 185 /*!
 186  * @brief Waits for an event flag.
 187  *
 188  * This function waits for a combination of flags to be set in an event object.
 189  * An applications can wait for any/all bits to be set. This function can
 190  * get the flags that wake up the waiting task.
 191  *
 192  * @param handle    Pointer to the event object.
 193  * @param bitMask   Event flags to wait.
 194  * @param flag      Wait all flags or any flag to be set. 0U - wait any flag, others, wait all flags.
 195  * @param timeout   The maximum number of milliseconds to wait for the event.
 196  *                  If the wait condition is not met, passing 0U
 197  *                  waits indefinitely when the environment is an RTOS and returns the kStatus_OSA_Timeout
 198  *                  immediately. Pass any value for the bare metal.
 199  * @param bitSet    Flags that wake up the waiting task are obtained by this parameter.
 200  *
 201  * @return An USB OSA error code or kStatus_OSA_Success.
 202  *
 203  * Example:
 204    @code
 205    usb_osa_status_t     usbOsaStatus;
 206    uint32_t             bitSet;
 207    ...
 208    usbOsaStatus = USB_OsaEventWait(eventHandle, 0x01U, 0U, 0U, &bitSet);
 209    @endcode
 210  *
 211  */
 212 extern usb_osa_status_t USB_OsaEventWait(
 213     usb_osa_event_handle handle, uint32_t bitMask, uint32_t flag, uint32_t timeout, uint32_t *bitSet);
 214
 215 /*!
 216  * @brief Checks an event flag.
 217  *
 218  * This function checks for a combination of flags to be set in an event object.
 219  *
 220  * @param handle   Pointer to the event object.
 221  * @param bitMask  Event flags to check.
 222  * @param bitSet   Flags have been set.
 223  *
 224  * @return An USB OSA error code or kStatus_OSA_Success.
 225  *
 226  * Example:
 227    @code
 228    usb_osa_status_t     usbOsaStatus;
 229    uint32_t             bitSet;
 230    ...
 231    usbOsaStatus = USB_OsaEventCheck(eventHandle, 0x01U, &bitSet);
 232    @endcode
 233  *
 234  */
 235 extern usb_osa_status_t USB_OsaEventCheck(usb_osa_event_handle handle, uint32_t bitMask, uint32_t *bitSet);
 236
 237 /*!
 238  * @brief Clears an event flag.
 239  *
 240  * This function clears flags of an event object.
 241  *
 242  * @param handle    Pointer to the event object
 243  * @param bitMask   Event flags to be cleared.
 244  *
 245  * @return An USB OSA error code or kStatus_OSA_Success.
 246  *
 247  * Example:
 248    @code
 249    usb_osa_status_t     usbOsaStatus;
 250    ...
 251    usbOsaStatus = USB_OsaEventClear(eventHandle, 0x01U);
 252    @endcode
 253  */
 254 extern usb_osa_status_t USB_OsaEventClear(usb_osa_event_handle handle, uint32_t bitMask);
 255 /* @} */
 256
 257 /*!
 258  * @name USB OSA Semaphore
 259  * @{
 260  */
 261
 262 /*!
 263  * @brief Creates a semaphore with a given value.
 264  *
 265  * This function creates a semaphore and sets the default count.
 266  *
 267  * @param handle    It is an out parameter, which is used to return pointer of the semaphore object.
 268  * @param count     Initializes a value of the semaphore.
 269  *
 270  * @return An USB OSA error code or kStatus_OSA_Success.
 271  *
 272  * Example:
 273    @code
 274    usb_osa_sem_handle   semHandle;
 275    usb_osa_status_t     usbOsaStatus;
 276    usbOsaStatus = USB_OsaSemCreate(&semHandle, 1U);
 277    @endcode
 278  *
 279  */
 280 extern usb_osa_status_t USB_OsaSemCreate(usb_osa_sem_handle *handle, uint32_t count);
 281
 282 /*!
 283  * @brief Destroys a semaphore object.
 284  *
 285  * This function destroys a semaphore object.
 286  *
 287  * @param handle    Pointer to the semaphore.
 288  *
 289  * @return An USB OSA error code or kStatus_OSA_Success.
 290  *
 291  * Example:
 292    @code
 293    usb_osa_sem_handle   semHandle;
 294    usb_osa_status_t     usbOsaStatus;
 295    ...
 296    usbOsaStatus = USB_OsaSemDestroy(semHandle);
 297    @endcode
 298  *
 299  */
 300 extern usb_osa_status_t USB_OsaSemDestroy(usb_osa_sem_handle handle);
 301
 302 /*!
 303  * @brief Posts a semaphore.
 304  *
 305  * This function wakes up a task waiting on the semaphore. If a task is not pending, increases the semaphore's
 306  value.
 307  *
 308  * @param handle    Pointer to the semaphore.
 309  *
 310  * @return A USB OSA error code or kStatus_OSA_Success.
 311  *
 312  * Example:
 313    @code
 314    usb_osa_sem_handle   semHandle;
 315    usb_osa_status_t     usbOsaStatus;
 316    ...
 317    usbOsaStatus = USB_OsaSemPost(semHandle);
 318    @endcode
 319  *
 320  */
 321 extern usb_osa_status_t USB_OsaSemPost(usb_osa_sem_handle handle);
 322
 323 /*!
 324  * @brief Waits on a semaphore.
 325  *
 326  * This function checks the semaphore's value. If it is positive, it decreases the semaphore's value and return
 327  kStatus_OSA_Success.
 328  *
 329  * @param handle    Pointer to the semaphore.
 330  * @param timeout   The maximum number of milliseconds to wait for the semaphore.
 331  *                  If the wait condition is not met, passing 0U
 332  *                  waits indefinitely when environment is RTOS. And return kStatus_OSA_Timeout
 333  *                  immediately for bare metal no matter what value has been passed.
 334  *
 335  * @return A USB OSA error code or kStatus_OSA_Success.
 336  *
 337  * Example:
 338    @code
 339    usb_osa_sem_handle   semHandle;
 340    usb_osa_status_t     usbOsaStatus;
 341    ...
 342    usbOsaStatus = USB_OsaSemWait(semHandle, 0U);
 343    @endcode
 344  *
 345  */
 346 extern usb_osa_status_t USB_OsaSemWait(usb_osa_sem_handle handle, uint32_t timeout);
 347 /* @} */
 348
 349 /*!
 350  * @name USB OSA Mutex
 351  * @{
 352  */
 353
 354 /*!
 355  * @brief Creates a mutex.
 356  *
 357  * This function creates a mutex and sets it to an unlocked status.
 358  *
 359  * @param handle    It is out parameter, which is used to return the pointer of the mutex object.
 360  *
 361  * @return A USB OSA error code or kStatus_OSA_Success.
 362  *
 363  * Example:
 364    @code
 365    usb_osa_mutex_handle mutexHandle;
 366    usb_osa_status_t     usbOsaStatus;
 367    usbOsaStatus = USB_OsaMutexCreate(&mutexHandle);
 368    @endcode
 369  *
 370  */
 371 extern usb_osa_status_t USB_OsaMutexCreate(usb_osa_mutex_handle *handle);
 372
 373 /*!
 374  * @brief Destroys a mutex.
 375  *
 376  * This function destroys a mutex and sets it to an unlocked status.
 377  *
 378  * @param handle    Pointer to the mutex.
 379  *
 380  * @return A USB OSA error code or kStatus_OSA_Success.
 381  *
 382  * Example:
 383    @code
 384    usb_osa_mutex_handle mutexHandle;
 385    usb_osa_status_t     usbOsaStatus;
 386    ...
 387    usbOsaStatus = USB_OsaMutexDestroy(mutexHandle);
 388    @endcode
 389  *
 390  */
 391 extern usb_osa_status_t USB_OsaMutexDestroy(usb_osa_mutex_handle handle);
 392
 393 /*!
 394  * @brief Waits for a mutex and locks it.
 395  *
 396  * This function checks the mutex status. If it is unlocked, it locks it and returns the
 397  * kStatus_OSA_Success. Otherwise, it waits forever to lock in RTOS and returns the
 398  * kStatus_OSA_Success immediately for bare metal.
 399  *
 400  * @param handle    Pointer to the mutex.
 401  *
 402  * @return A USB OSA error code or kStatus_OSA_Success.
 403  *
 404  * Example:
 405    @code
 406    usb_osa_mutex_handle mutexHandle;
 407    usb_osa_status_t     usbOsaStatus;
 408    ...
 409    usbOsaStatus = USB_OsaMutexLock(mutexHandle);
 410    @endcode
 411  *
 412  */
 413 extern usb_osa_status_t USB_OsaMutexLock(usb_osa_mutex_handle handle);
 414
 415 /*!
 416  * @brief Unlocks a mutex.
 417  *
 418  * This function unlocks a mutex.
 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_OsaMutexUnlock(mutexHandle);
 430    @endcode
 431  *
 432  */
 433 extern usb_osa_status_t USB_OsaMutexUnlock(usb_osa_mutex_handle handle);
 434 /* @} */
 435
 436 /*!
 437  * @name USB OSA Message Queue
 438  * @{
 439  */
 440
 441 /*!
 442  * @brief Creates a message queue.
 443  *
 444  * This function creates a message queue.
 445  *
 446  * @param handle    It is an out parameter, which is used to return a pointer of the message queue object.
 447  * @param count     The count of elements in the queue.
 448  * @param size      Size of every elements in words.
 449  *
 450  * @return A USB OSA error code or kStatus_OSA_Success.
 451  *
 452  * Example:
 453    @code
 454    usb_osa_msgq_handle  msgqHandle;
 455    usb_osa_status_t     usbOsaStatus;
 456    usbOsaStatus = USB_OsaMsgqCreate(msgqHandle, 8U, 4U);
 457    @endcode
 458  *
 459  */
 460 extern usb_osa_status_t USB_OsaMsgqCreate(usb_osa_msgq_handle *handle, uint32_t count, uint32_t size);
 461
 462 /*!
 463  * @brief Destroys a message queue.
 464  *
 465  * This function destroys a message queue.
 466  *
 467  * @param handle    Pointer to a message queue.
 468  *
 469  * @return A USB OSA error code or kStatus_OSA_Success.
 470  *
 471  * Example:
 472    @code
 473    usb_osa_msgq_handle  msgqHandle;
 474    usb_osa_status_t     usbOsaStatus;
 475    ...
 476    usbOsaStatus = USB_OsaMsgqDestroy(msgqHandle);
 477    @endcode
 478  *
 479  */
 480 extern usb_osa_status_t USB_OsaMsgqDestroy(usb_osa_msgq_handle handle);
 481
 482 /*!
 483  * @brief Sends a message.
 484  *
 485  * This function sends a message to the tail of the message queue.
 486  *
 487  * @param handle    Pointer to a message queue.
 488  * @param msg       The pointer to a message to be put into the queue.
 489  *
 490  * @return A USB OSA error code or kStatus_OSA_Success.
 491  *
 492  * Example:
 493    @code
 494    usb_osa_msgq_handle      msgqHandle;
 495    message_struct_t         message;
 496    usb_osa_status_t         usbOsaStatus;
 497    ...
 498    usbOsaStatus = USB_OsaMsgqSend(msgqHandle, &message);
 499    @endcode
 500  *
 501  */
 502 extern usb_osa_status_t USB_OsaMsgqSend(usb_osa_msgq_handle handle, void *msg);
 503
 504 /*!
 505  * @brief Receives a message.
 506  *
 507  * This function receives a message from the head of the message queue.
 508  *
 509  * @param handle    Pointer to a message queue.
 510  * @param msg       The pointer to save a received message.
 511  * @param timeout   The maximum number of milliseconds to wait for a message.
 512  *                  If the wait condition is not met, passing 0U
 513  *                  waits indefinitely when an environment is RTOS and returns the kStatus_OSA_Timeout
 514  *                  immediately for bare metal.
 515  *
 516  * @return A USB OSA error code or kStatus_OSA_Success.
 517  *
 518  * Example:
 519    @code
 520    usb_osa_msgq_handle      msgqHandle;
 521    message_struct_t         message;
 522    usb_osa_status_t         usbOsaStatus;
 523    ...
 524    usbOsaStatus = USB_OsaMsgqRecv(msgqHandle, &message, 0U);
 525    @endcode
 526  *
 527  */
 528 extern usb_osa_status_t USB_OsaMsgqRecv(usb_osa_msgq_handle handle, void *msg, uint32_t timeout);
 529
 530 /*!
 531  * @brief Checks a message queue and receives a message if the queue is not empty.
 532  *
 533  * This function checks a message queue and receives a message if the queue is not empty.
 534  *
 535  * @param handle    Pointer to a message queue.
 536  * @param msg       The pointer to save a received message.
 537  *
 538  * @return A USB OSA error code or kStatus_OSA_Success.
 539  *
 540  * Example:
 541    @code
 542    usb_osa_msgq_handle      msgqHandle;
 543    message_struct_t         message;
 544    usb_osa_status_t         usbOsaStatus;
 545    ...
 546    usbOsaStatus = USB_OsaMsgqCheck(msgqHandle, &message);
 547    @endcode
 548  *
 549  */
 550 extern usb_osa_status_t USB_OsaMsgqCheck(usb_osa_msgq_handle handle, void *msg);
 551
 552 /* @} */
 553
 554 #if defined(__cplusplus)
 555 }
 556 #endif
 557
 558 /* @} */
 559
 560 #endif /* __USB_OSA_H__ */