src/ti/ipc/GateMP.h

   1 /*
   2  * Copyright (c) 2012-2013, 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  *  @file       GateMP.h
  34  *
  35  *  @brief      Multiple processor gate that provides local and remote context
  36  *              protection.
  37  *
  38  *  A GateMP instance can be used to enforce both local and remote context
  39  *  context protection.  That is, entering a GateMP can prevent preemption by
  40  *  another thread running on the same processor and simultaneously prevent a
  41  *  remote processor from entering the same gate.  GateMP's are typically used
  42  *  to protect reads/writes to a shared resource, such as shared memory.
  43  *
  44  *  Creating a GateMP requires supplying the following configuration
  45  *      - Instance name (see #GateMP_Params::name)
  46  *      - Region id (see #GateMP_Params::regionId)
  47  *  In addition, the following parameters should be configured as necessary:
  48  *      - The level of local protection (interrupt, thread, tasklet, process
  49  *        or none) can be configured using the #GateMP_Params::localProtect
  50  *        config parameter.
  51  *      - The type of remote system gate that can be used.  Most devices will
  52  *        typically have a single type of system gate so this configuration
  53  *        should typically be left alone.  See #GateMP_Params::remoteProtect for
  54  *        more information.
  55
  56  *  Once created GateMP allows the gate to be opened on another processor
  57  *  using GateMP_open() and the name that was used in GateMP_create().
  58  *
  59  *  A GateMP can be entered and left using GateMP_enter() and GateMP_leave()
  60  *  like any other gate that implements the IGateProvider interface.
  61  *
  62  *  GateMP has the following proxies - RemoteSystemProxy, RemoteCustom1Proxy
  63  *  and RemoteCustom2Proxy which are automatically plugged with device-specific
  64  *  delegates that implement multiple processor mutexes using a variety of
  65  *  hardware mechanisms.
  66  *
  67  *  GateMP creates a default system gate whose handle may be obtained
  68  *  using GateMP_getDefaultRemote().  Most IPC modules typically use this gate
  69  *  by default if they require gates and no instance gate is configured by the
  70  *  user.
  71  *
  72  *  The GateMP header should be included in an application as follows:
  73  *  @code
  74  *  #include <ti/ipc/GateMP.h>
  75  *  @endcode
  76  *
  77  *
  78  *  @version        0.00.01
  79  *
  80  *  ============================================================================
  81  */
  82
  83 #ifndef ti_ipc_GateMP__include
  84 #define ti_ipc_GateMP__include
  85
  86 #if defined (__cplusplus)
  87 extern "C" {
  88 #endif
  89
  90 /* =============================================================================
  91  *  All success and failure codes for the module
  92  * =============================================================================
  93  */
  94
  95 /*!
  96  *  @brief  The resource is still in use
  97  */
  98 #define GateMP_S_BUSY               2
  99
 100 /*!
 101  *  @brief  The module has been already setup
 102  */
 103 #define GateMP_S_ALREADYSETUP       1
 104
 105 /*!
 106  *  @brief  Operation is successful.
 107  */
 108 #define GateMP_S_SUCCESS            0
 109
 110 /*!
 111  *  @brief  Generic failure.
 112  */
 113 #define GateMP_E_FAIL              -1
 114
 115 /*!
 116  *  @brief  Argument passed to function is invalid.
 117  */
 118 #define GateMP_E_INVALIDARG        -2
 119
 120 /*!
 121  *  @brief  Operation resulted in memory failure.
 122  */
 123 #define GateMP_E_MEMORY            -3
 124
 125 /*!
 126  *  @brief  The specified entity already exists.
 127  */
 128 #define GateMP_E_ALREADYEXISTS     -4
 129
 130 /*!
 131  *  @brief  Unable to find the specified entity.
 132  */
 133 #define GateMP_E_NOTFOUND          -5
 134
 135 /*!
 136  *  @brief  Operation timed out.
 137  */
 138 #define GateMP_E_TIMEOUT           -6
 139
 140 /*!
 141  *  @brief  Module is not initialized.
 142  */
 143 #define GateMP_E_INVALIDSTATE      -7
 144
 145 /*!
 146  *  @brief  A failure occurred in an OS-specific call  */
 147 #define GateMP_E_OSFAILURE         -8
 148
 149 /*!
 150  *  @brief  Specified resource is not available  */
 151 #define GateMP_E_RESOURCE          -9
 152
 153 /*!
 154  *  @brief  Operation was interrupted. Please restart the operation  */
 155 #define GateMP_E_RESTART           -10
 156
 157 /* =============================================================================
 158  *  Structures & Enums
 159  * =============================================================================
 160  */
 161
 162 /*!
 163  *  @brief  A set of local context protection levels
 164  *
 165  *  Each member corresponds to a specific local processor gates used for
 166  *  local protection.
 167  *
 168  *  In Linux user mode, the following are the mapping for the constants
 169  *      - INTERRUPT -> [N/A]
 170  *      - TASKLET   -> [N/A]
 171  *      - THREAD    -> GateMutex
 172  *      - PROCESS   -> GateMutex
 173  *
 174  *  In Linux kernel mode, the following are the mapping for the constants
 175  *      - INTERRUPT -> [Interrupts disabled]
 176  *      - TASKLET   -> GateMutex
 177  *      - THREAD    -> GateMutex
 178  *      - PROCESS   -> GateMutex
 179  *
 180  *  For SYS/BIOS users, the following are the mappings for the constants
 181  *      - INTERRUPT -> GateAll: disables interrupts, Swis and Tasks
 182  *      - TASKLET   -> GateSwi: disables Swis and Tasks
 183  *      - THREAD    -> GateMutexPri: based on Semaphores
 184  *      - PROCESS   -> GateMutexPri: based on Semaphores
 185  */
 186 typedef enum GateMP_LocalProtect {
 187     GateMP_LocalProtect_NONE      = 0,
 188     /*!< Use no local protection */
 189
 190     GateMP_LocalProtect_INTERRUPT = 1,
 191     /*!< Use the INTERRUPT local protection level */
 192
 193     GateMP_LocalProtect_TASKLET   = 2,
 194     /*!< Use the TASKLET local protection level */
 195
 196     GateMP_LocalProtect_THREAD    = 3,
 197     /*!< Use the THREAD local protection level */
 198
 199     GateMP_LocalProtect_PROCESS   = 4
 200     /*!< Use the PROCESS local protection level */
 201
 202 } GateMP_LocalProtect;
 203
 204
 205 /*!
 206  *  @brief  Type of remote Gate
 207  *
 208  *  Each member corresponds to a specific type of remote gate.
 209  *  Each enum value corresponds to the following remote protection levels:
 210  *      - NONE      -> No remote protection (the GateMP instance will
 211  *                     exclusively offer local protection configured in
 212  *                     #GateMP_Params::localProtect
 213  *      - SYSTEM    -> Use the SYSTEM remote protection level (default for
 214  *                     remote protection
 215  *      - CUSTOM1   -> Use the CUSTOM1 remote protection level
 216  *      - CUSTOM2   -> Use the CUSTOM2 remote protection level
 217  */
 218 typedef enum GateMP_RemoteProtect {
 219     GateMP_RemoteProtect_NONE     = 0,
 220     /*!< No remote protection (the GateMP instance will exclusively
 221      *  offer local protection configured in #GateMP_Params::localProtect)
 222      */
 223
 224     GateMP_RemoteProtect_SYSTEM   = 1,
 225     /*!< Use the SYSTEM remote protection level (default remote protection) */
 226
 227     GateMP_RemoteProtect_CUSTOM1  = 2,
 228     /*!< Use the CUSTOM1 remote protection level */
 229
 230     GateMP_RemoteProtect_CUSTOM2  = 3
 231     /*!< Use the CUSTOM2 remote protection level */
 232
 233 } GateMP_RemoteProtect;
 234
 235 /*!
 236  *  @brief  GateMP_Handle type
 237  */
 238 typedef struct GateMP_Object *GateMP_Handle;
 239
 240 /*!
 241  *  @brief  Structure defining parameters for the GateMP module.
 242  */
 243 typedef struct GateMP_Params {
 244     String name;
 245     /*!< Name of this instance.
 246      *
 247      *  The name (if not NULL) must be unique among all GateMP instances
 248      *  in the entire system.  The name does not have to be in persistent
 249      *  memory.  The supplied string is copied into persistent memory.
 250      *  If no name is supplied, the instance cannot be opened calling
 251      *  GateMP_open().  The max length of the name is defined by the
 252      *  maxNameLen of the NameServer instance.
 253      */
 254
 255     UInt16 regionId;
 256     /*!< Shared region ID
 257      *
 258      *  The index corresponding to the shared region from which shared memory
 259      *  is allocated for the instance.  If not specified, the default of '0'
 260      *  is used, otherwise the specified SharedRegion is used.  The amount
 261      *  of shared memory allocated can be determined by calling
 262      *  GateMP_sharedMemReq().
 263      */
 264
 265     /*! @cond */
 266     Ptr sharedAddr;
 267     /*!< Physical address of the shared memory
 268      *
 269      *  This value can be left as 'null' unless it is required to place the
 270      *  instance at a specific location in shared memory.  If specified,
 271      *  it must be from a valid SharedRegion and the regionId is ignored.
 272      *  If sharedAddr is null, then shared memory for a new instance is
 273      *  allocated from the heap belonging to the region identified by
 274      *  #GateMP_Params::regionId.  The amount of shared memory allocated
 275      *  can be determined by calling GateMP_sharedMemReq().
 276      */
 277     /*! @endcond */
 278
 279
 280     GateMP_LocalProtect localProtect;
 281     /*!< Local protection level
 282      *
 283      *   The default value is #GateMP_LocalProtect_THREAD
 284      */
 285
 286     GateMP_RemoteProtect remoteProtect;
 287     /*!< Remote protection level
 288      *
 289      *   The default value is #GateMP_RemoteProtect_SYSTEM
 290      */
 291 } GateMP_Params;
 292
 293 /* =============================================================================
 294  *  GateMP Module-wide Functions
 295  * =============================================================================
 296  */
 297
 298 /*!
 299  *  @brief      Close an opened gate
 300  *
 301  *  @param[in,out]  handlePtr   Pointer to handle to opened GateMP instance
 302  *
 303  *  @return     GateMP status
 304  */
 305 Int GateMP_close(GateMP_Handle *handlePtr);
 306
 307 /*!
 308  *  @brief      Create a GateMP instance
 309  *
 310  *  The params structure should be initialized using GateMP_Params_init().
 311  *
 312  *  @param[in]  params      GateMP parameters
 313  *
 314  *  @return     GateMP Handle
 315  */
 316 GateMP_Handle GateMP_create(const GateMP_Params *params);
 317
 318 /*!
 319  *  @brief      Delete a created GateMP instance
 320  *
 321  *  @param[in,out]  handlePtr       Pointer to GateMP handle
 322  *
 323  *  @return     GateMP Status
 324  */
 325 Int GateMP_delete(GateMP_Handle *handlePtr);
 326
 327 /*!
 328  *  @brief      Get the default remote gate
 329  *
 330  *  @return     GateMP handle
 331  */
 332 GateMP_Handle GateMP_getDefaultRemote(Void);
 333
 334 /*!
 335  *  @brief      Get the local protection level configured in a GateMP instance
 336  *
 337  *  @return     GateMP_LocalProtect corresponding to local protection level
 338  */
 339 GateMP_LocalProtect GateMP_getLocalProtect(GateMP_Handle handle);
 340
 341 /*!
 342  *  @brief      Get the remote protection level configured in a GateMP instance
 343  *
 344  *  @return     GateMP_RemoteProtect corresponding to remote protection level
 345  */
 346 GateMP_RemoteProtect GateMP_getRemoteProtect(GateMP_Handle handle);
 347
 348 /*!
 349  *  @brief      Open a created GateMP by name
 350  *
 351  *  @param[in]  name        Name of the GateMP instance
 352  *  @param[out] handlePtr   Pointer to GateMP handle to be opened
 353  *
 354  *  @return     GateMP status:
 355  *              - #GateMP_E_NOTFOUND: open failed (name not found on any
 356  *                processor)
 357  *              - #GateMP_E_FAIL: open failed (general failure occurred)
 358  *              - #GateMP_S_SUCCESS: open successful
 359  */
 360 Int GateMP_open(String name, GateMP_Handle *handlePtr);
 361
 362 /*! @cond */
 363 Int GateMP_openByAddr(Ptr sharedAddr, GateMP_Handle *handlePtr);
 364
 365 /*! @endcond */
 366
 367 /*!
 368  *  @brief      Initialize a GateMP parameters struct
 369  *
 370  *  @param[out] params      Pointer to GateMP parameters
 371  *
 372  */
 373 Void GateMP_Params_init(GateMP_Params *params);
 374
 375 /*! @cond */
 376 /*!
 377  *  @brief      Amount of shared memory required for creation of each instance
 378  *
 379  *  @param[in]  params      Pointer to the parameters that will be used in
 380  *                          the create.
 381  *
 382  *  @return     Number of MAUs needed to create the instance.
 383  */
 384 SizeT GateMP_sharedMemReq(const GateMP_Params *params);
 385
 386 /*! @endcond */
 387
 388 /* =============================================================================
 389  *  GateMP Per-instance Functions
 390  * =============================================================================
 391  */
 392
 393 /*!
 394  *  @brief      Enter the GateMP
 395  *
 396  *  @param[in]  handle      GateMP handle
 397  *
 398  *  @return     key that must be used to leave the gate
 399  */
 400 IArg GateMP_enter(GateMP_Handle handle);
 401
 402 /*!
 403  *  @brief      Leave the GateMP
 404  *
 405  *  @param[in]  handle      GateMP handle
 406  *  @param[in]  key         key returned from GateMP_enter
 407  */
 408 Void GateMP_leave(GateMP_Handle handle, IArg key);
 409
 410 #if defined (__cplusplus)
 411 }
 412 #endif /* defined (__cplusplus) */
 413 #endif /* ti_ipc_GateMP__include */