packages/ti/ipc/MultiProc.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       MultiProc.h
  34  *
  35  *  @brief      Processor ID Manager
  36  *
  37  *  Many IPC modules require the ability to uniquely specify and identify
  38  *  processors in a multi-processor environment. The MultiProc module
  39  *  centeralizes processor id management into one module.  Since this
  40  *  configuration is almost always universally required, most IPC applications
  41  *  require supplying configuration of this module.
  42  *
  43  *  Each processor in the MultiProc module may be uniquely identified by
  44  *  either a name string or an integer ranging from 0 to NUMPROCESSORS - 1.
  45  *
  46  *  At runtime, the #MultiProc_getId call returns the MultiProc id for any
  47  *  processor given its name.
  48  *
  49  *  The MultiProc header should be included in an application as follows:
  50  *  @code
  51  *  #include <ti/ipc/MultiProc.h>
  52  *  @endcode
  53  */
  54
  55 #ifndef ti_ipc_MultiProc__include
  56 #define ti_ipc_MultiProc__include
  57
  58 #if defined (__cplusplus)
  59 extern "C" {
  60 #endif
  61
  62 /* =============================================================================
  63  *  All success and failure codes for the module
  64  * =============================================================================
  65  */
  66
  67 /*!
  68  *  @def    MultiProc_S_BUSY
  69  *  @brief  The resource is still in use
  70  */
  71 #define MultiProc_S_BUSY                 2
  72
  73 /*!
  74  *  @def    MultiProc_S_ALREADYSETUP
  75  *  @brief  The module has been already setup
  76  */
  77 #define MultiProc_S_ALREADYSETUP         1
  78
  79 /*!
  80  *  @def    MultiProc_S_SUCCESS
  81  *  @brief  Operation is successful.
  82  */
  83 #define MultiProc_S_SUCCESS              0
  84
  85 /*!
  86  *  @def    MultiProc_E_FAIL
  87  *  @brief  Generic failure.
  88  */
  89 #define MultiProc_E_FAIL                -1
  90
  91 /*!
  92  *  @def    MultiProc_E_INVALIDARG
  93  *  @brief  Argument passed to function is invalid.
  94  */
  95 #define MultiProc_E_INVALIDARG          -2
  96
  97 /*!
  98  *  @def    MultiProc_E_MEMORY
  99  *  @brief  Operation resulted in memory failure.
 100  */
 101 #define MultiProc_E_MEMORY              -3
 102
 103 /*!
 104  *  @def    MultiProc_E_ALREADYEXISTS
 105  *  @brief  The specified entity already exists.
 106  */
 107 #define MultiProc_E_ALREADYEXISTS       -4
 108
 109 /*!
 110  *  @def    MultiProc_E_NOTFOUND
 111  *  @brief  Unable to find the specified entity.
 112  */
 113 #define MultiProc_E_NOTFOUND            -5
 114
 115 /*!
 116  *  @def    MultiProc_E_TIMEOUT
 117  *  @brief  Operation timed out.
 118  */
 119 #define MultiProc_E_TIMEOUT             -6
 120
 121 /*!
 122  *  @def    MultiProc_E_INVALIDSTATE
 123  *  @brief  Module is not initialized.
 124  */
 125 #define MultiProc_E_INVALIDSTATE        -7
 126
 127 /*!
 128  *  @def    MultiProc_E_OSFAILURE
 129  *  @brief  A failure occurred in an OS-specific call
 130  */
 131 #define MultiProc_E_OSFAILURE           -8
 132
 133 /*!
 134  *  @def    MultiProc_E_RESOURCE
 135  *  @brief  Specified resource is not available
 136  */
 137 #define MultiProc_E_RESOURCE            -9
 138
 139 /*!
 140  *  @def    MultiProc_E_RESTART
 141  *  @brief  Operation was interrupted. Please restart the operation
 142  */
 143 #define MultiProc_E_RESTART             -10
 144
 145 /* =============================================================================
 146  *  Macros
 147  * =============================================================================
 148  */
 149
 150 /*!
 151  *  @def    MultiProc_INVALIDID
 152  *  @brief  Invalid processor id.
 153  */
 154 #define MultiProc_INVALIDID             (0xFFFF)
 155
 156 /* =============================================================================
 157  *  MultiProc Module-wide Functions
 158  * =============================================================================
 159  */
 160
 161  /*!
 162  *  @brief      Gets the base MultiProc id of the cluster
 163  *
 164  *  Retrieves the base MultiProc id for the cluster of processors.
 165  *
 166  *  @return     MultiProc id for base of cluster
 167  *
 168  *  @sa         MultiProc_getClusterId
 169  */
 170 UInt16 MultiProc_getBaseIdOfCluster(Void);
 171
 172 /*!
 173  *  @brief      Gets the MultiProc id
 174  *
 175  *  Retrieves the MultiProc id for the processor with corresponding MultiProc
 176  *  name. #MultiProc_INVALIDID is returned if the name was not found.
 177  *
 178  *  @param      name  Name of the processor.
 179  *
 180  *  @return     MultiProc id
 181  *
 182  *  @sa         MultiProc_getName
 183  */
 184 UInt16 MultiProc_getId(String name);
 185
 186 /*!
 187  *  @brief      Gets the name of a processor
 188  *
 189  *  @param      id  MultiProc id.
 190  *
 191  *  @return     Name of the processor
 192  *
 193  *  The returned string should never be modified.
 194  *
 195  *  @sa         MultiProc_getId
 196  */
 197 String MultiProc_getName(UInt16 id);
 198
 199 /*!
 200  *  @brief      Gets the number of processors
 201  *
 202  *  @return     Number of processors configured with MultiProc
 203  */
 204 UInt16 MultiProc_getNumProcessors(Void);
 205
 206 /*!
 207  *  @brief      Gets the number of processors in the cluster
 208  *
 209  *  @return     Number of processors in cluster
 210  */
 211 UInt16 MultiProc_getNumProcsInCluster(Void);
 212
 213 /*!
 214  *  @brief      Gets executing processor's MultiProc id
 215  *
 216  *  @return     Executing processor's id
 217  *
 218  *  @sa         MultiProc_getId
 219  */
 220 UInt16 MultiProc_self(Void);
 221
 222 /*!
 223  *  @brief      Sets executing processor's base id of the cluster
 224  *
 225  *  @param      baseId  The MultiProc base id of the cluster
 226  *
 227  *  @return     MultiProc status:
 228  *              - #MultiProc_S_SUCCESS: sucessfully set base id of cluster
 229  *              - #MultiProc_E_FAIL:    failed to set base id of cluster
 230  */
 231 Int MultiProc_setBaseIdOfCluster(UInt16 baseId);
 232
 233 /*!
 234  *  @brief      Sets executing processor's MultiProc id
 235  *
 236  *  @param      id  MultiProc id
 237  *
 238  *  @return     MultiProc status:
 239  *              - #MultiProc_S_SUCCESS: MultiProc id successfully set
 240  *              - #MultiProc_E_FAIL:    MultiProc id cannot be set at this time
 241  */
 242 Int MultiProc_setLocalId(UInt16 id);
 243
 244 #if defined (__cplusplus)
 245 }
 246 #endif /* defined (__cplusplus) */
 247
 248 #endif /* ti_ipc_MultiProc__include */