packages/ti/osal/MutexP.h

   1 /*
   2  * Copyright (c) 2021, Texas Instruments Incorporated
   3  * All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  *
   9  * *  Redistributions of source code must retain the above copyright
  10  *    notice, this list of conditions and the following disclaimer.
  11  *
  12  * *  Redistributions in binary form must reproduce the above copyright
  13  *    notice, this list of conditions and the following disclaimer in the
  14  *    documentation and/or other materials provided with the distribution.
  15  *
  16  * *  Neither the name of Texas Instruments Incorporated nor the names of
  17  *    its contributors may be used to endorse or promote products derived
  18  *    from this software without specific prior written permission.
  19  *
  20  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
  21  * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
  22  * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  23  * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
  24  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  25  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  26  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
  27  * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
  28  * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
  29  * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
  30  * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31  */
  32 /**
  33  *  \ingroup DRV_OSAL_MODULE
  34  *  \defgroup DRV_OSAL_MutexP MutexP
  35  *            MutexP interface
  36  *
  37  *  @{
  38  */
  39 /** ============================================================================
  40  *  @file       MutexP.h
  41  *
  42  *  @brief      Mailbox module for the RTOS Porting Interface.
  43   *
  44  *  ============================================================================
  45  */
  46
  47 #ifndef ti_osal_MutexP__include
  48 #define ti_osal_MutexP__include
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 #include <stdint.h>
  55 #include <stdbool.h>
  56 #include <stddef.h>
  57
  58 /**
  59  * \anchor MutexP_Status
  60  * \name MutexP Status codes
  61  *
  62  * @{
  63  */
  64 /*!
  65  *  @brief  This enumerator defines the Status codes for MutexP APIs
  66  */
  67 typedef int32_t MutexP_Status;
  68 /*! API completed successfully */
  69 #define MutexP_OK             0
  70 /*! API failed */
  71 #define MutexP_FAILURE        (-(int32_t)1)
  72 /*! API failed  because of a timeout */
  73 #define MutexP_TIMEOUT        (-(int32_t)2)
  74 /* @} */
  75
  76 /*!
  77  *  @brief    Wait forever define
  78  */
  79 #define MutexP_WAIT_FOREVER (~((uint32_t)0U))
  80
  81 /*!
  82  *  @brief    No wait define
  83  */
  84 #define MutexP_NO_WAIT       ((uint32_t)0U)
  85
  86
  87 /*!
  88  *  @brief    Opaque client reference to an instance of a MutexP
  89  *
  90  *  A MutexP_Handle returned from the ::MutexP_create represents that
  91  *  instance and  is used in the other instance based functions
  92  */
  93 typedef  void *MutexP_Handle;
  94
  95 /*!
  96  *  @brief    MutexP Mutex Object
  97  *
  98  *  Structure that contains the MutexP Mutex Object to be used with the
  99  *  MutexP_constructMutex function
 100  */
 101 typedef struct MutexP_Object_s {
 102     void * object;      /*!< Pointer to OS specifc mutex object */
 103     uintptr_t key;      /*!< The key returned during mutex lock */
 104 } MutexP_Object;
 105
 106
 107 /*!
 108  *  @brief  Function to create a mutex.
 109  *
 110  *  @param  mutexObj  Pointer to the mutex object
 111  *
 112  *  @return  A MutexP_Handle on success or a NULL on an error
 113  */
 114 extern MutexP_Handle MutexP_create(MutexP_Object *mutexObj);
 115
 116 /*!
 117  *  @brief  Function to delete a mutex.
 118  *
 119  *  @param  handle  A MutexP_Handle returned from MutexP_create
 120  *
 121  *  @return Status of the functions
 122  *    - MutexP_OK: Deleted the mutex instance
 123  *    - MutexP_FAILURE: Failed to delete the mutex instance
 124  */
 125 extern MutexP_Status MutexP_delete(MutexP_Handle handle);
 126
 127 /*!
 128  *  @brief  Function to unlock the mutex.
 129  *
 130  *  @param  handle  A MutexP_Handle returned from MutexP_create
 131  *
 132  *  @return Status of the functions
 133  *    - MutexP_OK: Unlocked the mutex
 134  *    - MutexP_FAILURE: Failed to unlock the mutex
 135  */
 136 extern MutexP_Status MutexP_unlock(MutexP_Handle handle);
 137
 138 /*!
 139  *  @brief  Function to lock the mutex.
 140  *
 141  *  @param  handle  A MutexP_Handle returned from MutexP_create
 142  *
 143  *  @param  timeout Timeout (in milliseconds) to wait for lock
 144  *                  the mutex.
 145  *
 146  *  @return Status of the functions
 147  *    - MutexP_OK: Locked the mutex
 148  *    - MutexP_TIMEOUT: Timed out waiting for a mutex unlock
 149  *    - MutexP_FAILURE: Failed to lock the mutex
 150  */
 151 extern MutexP_Status MutexP_lock(MutexP_Handle handle,
 152                                  uint32_t timeout);
 153
 154 #ifdef __cplusplus
 155 }
 156 #endif
 157
 158 #endif /* ti_osal_MutexP__include */
 159 /* @} */