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       ti/ipc/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  *  centralizes 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  *  @brief  The resource is still in use
  69  */
  70 #define MultiProc_S_BUSY                 (2)
  71
  72 /*!
  73  *  @brief  The module has been already setup
  74  */
  75 #define MultiProc_S_ALREADYSETUP         (1)
  76
  77 /*!
  78  *  @brief  Operation is successful.
  79  */
  80 #define MultiProc_S_SUCCESS              (0)
  81
  82 /*!
  83  *  @brief  Generic failure.
  84  */
  85 #define MultiProc_E_FAIL                (-1)
  86
  87 /*!
  88  *  @brief  Argument passed to function is invalid.
  89  */
  90 #define MultiProc_E_INVALIDARG          (-2)
  91
  92 /*!
  93  *  @brief  Operation resulted in memory failure.
  94  */
  95 #define MultiProc_E_MEMORY              (-3)
  96
  97 /*!
  98  *  @brief  The specified entity already exists.
  99  */
 100 #define MultiProc_E_ALREADYEXISTS       (-4)
 101
 102 /*!
 103  *  @brief  Unable to find the specified entity.
 104  */
 105 #define MultiProc_E_NOTFOUND            (-5)
 106
 107 /*!
 108  *  @brief  Operation timed out.
 109  */
 110 #define MultiProc_E_TIMEOUT             (-6)
 111
 112 /*!
 113  *  @brief  Module is not initialized.
 114  */
 115 #define MultiProc_E_INVALIDSTATE        (-7)
 116
 117 /*!
 118  *  @brief  A failure occurred in an OS-specific call
 119  */
 120 #define MultiProc_E_OSFAILURE           (-8)
 121
 122 /*!
 123  *  @brief  Specified resource is not available
 124  */
 125 #define MultiProc_E_RESOURCE            (-9)
 126
 127 /*!
 128  *  @brief  Operation was interrupted. Please restart the operation
 129  */
 130 #define MultiProc_E_RESTART             (-10)
 131
 132 /* =============================================================================
 133  *  Macros
 134  * =============================================================================
 135  */
 136
 137 /*!
 138  *  @brief  Invalid processor id.
 139  */
 140 #define MultiProc_INVALIDID             (0xFFFF)
 141
 142 /* =============================================================================
 143  *  MultiProc Module-wide Functions
 144  * =============================================================================
 145  */
 146
 147  /*!
 148  *  @brief      Gets the base MultiProc id of the cluster
 149  *
 150  *  Retrieves the base MultiProc id for the cluster of processors.
 151  *
 152  *  @return     MultiProc id for base of cluster
 153  *
 154  *  @sa         MultiProc_getClusterId
 155  */
 156 UInt16 MultiProc_getBaseIdOfCluster(Void);
 157
 158 /*!
 159  *  @brief      Gets the MultiProc id
 160  *
 161  *  Retrieves the MultiProc id for the processor with corresponding MultiProc
 162  *  name. #MultiProc_INVALIDID is returned if the name was not found.
 163  *
 164  *  @param      name  Name of the processor.
 165  *
 166  *  @return     MultiProc id
 167  *
 168  *  @sa         MultiProc_getName
 169  */
 170 UInt16 MultiProc_getId(String name);
 171
 172 /*!
 173  *  @brief      Gets the name of a processor
 174  *
 175  *  @param      id  MultiProc id.
 176  *
 177  *  @return     Name of the processor
 178  *
 179  *  The returned string should never be modified.
 180  *
 181  *  @sa         MultiProc_getId
 182  */
 183 String MultiProc_getName(UInt16 id);
 184
 185 /*!
 186  *  @brief      Gets the number of processors
 187  *
 188  *  @return     Number of processors configured with MultiProc
 189  */
 190 UInt16 MultiProc_getNumProcessors(Void);
 191
 192 /*!
 193  *  @brief      Gets the number of processors in the cluster
 194  *
 195  *  @return     Number of processors in cluster
 196  */
 197 UInt16 MultiProc_getNumProcsInCluster(Void);
 198
 199 /*!
 200  *  @brief      Gets executing processor's MultiProc id
 201  *
 202  *  @return     Executing processor's id
 203  *
 204  *  @sa         MultiProc_getId
 205  */
 206 UInt16 MultiProc_self(Void);
 207
 208 /*!
 209  *  @brief      Sets executing processor's MultiProc id
 210  *
 211  *  @param      id  MultiProc id
 212  *
 213  *  @return     MultiProc status:
 214  *              - #MultiProc_S_SUCCESS: MultiProc id successfully set
 215  *              - #MultiProc_E_FAIL:    MultiProc id cannot be set at this time
 216  */
 217 Int MultiProc_setLocalId(UInt16 id);
 218
 219 #if defined (__cplusplus)
 220 }
 221 #endif /* defined (__cplusplus) */
 222
 223 #endif /* ti_ipc_MultiProc__include */