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