cda9a74182234c7d971f775304f78a52b6aed134
[ipc/ipcdev.git] / 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  */
55 #ifndef ti_ipc_MultiProc__include
56 #define ti_ipc_MultiProc__include
58 #if defined (__cplusplus)
59 extern "C" {
60 #endif
62 /* =============================================================================
63  *  All success and failure codes for the module
64  * =============================================================================
65  */
67 /*!
68  *  @brief  The resource is still in use
69  */
70 #define MultiProc_S_BUSY                 2
72 /*!
73  *  @brief  The module has been already setup
74  */
75 #define MultiProc_S_ALREADYSETUP         1
77 /*!
78  *  @brief  Operation is successful.
79  */
80 #define MultiProc_S_SUCCESS              0
82 /*!
83  *  @brief  Generic failure.
84  */
85 #define MultiProc_E_FAIL                -1
87 /*!
88  *  @brief  Argument passed to function is invalid.
89  */
90 #define MultiProc_E_INVALIDARG          -2
92 /*!
93  *  @brief  Operation resulted in memory failure.
94  */
95 #define MultiProc_E_MEMORY              -3
97 /*!
98  *  @brief  The specified entity already exists.
99  */
100 #define MultiProc_E_ALREADYEXISTS       -4
102 /*!
103  *  @brief  Unable to find the specified entity.
104  */
105 #define MultiProc_E_NOTFOUND            -5
107 /*!
108  *  @brief  Operation timed out.
109  */
110 #define MultiProc_E_TIMEOUT             -6
112 /*!
113  *  @brief  Module is not initialized.
114  */
115 #define MultiProc_E_INVALIDSTATE        -7
117 /*!
118  *  @brief  A failure occurred in an OS-specific call
119  */
120 #define MultiProc_E_OSFAILURE           -8
122 /*!
123  *  @brief  Specified resource is not available
124  */
125 #define MultiProc_E_RESOURCE            -9
127 /*!
128  *  @brief  Operation was interrupted. Please restart the operation
129  */
130 #define MultiProc_E_RESTART             -10
132 /* =============================================================================
133  *  Macros
134  * =============================================================================
135  */
137 /*!
138  *  @brief  Invalid processor id.
139  */
140 #define MultiProc_INVALIDID             (0xFFFF)
142 /* =============================================================================
143  *  MultiProc Module-wide Functions
144  * =============================================================================
145  */
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);
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);
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);
185 /*!
186  *  @brief      Gets the number of processors
187  *
188  *  @return     Number of processors configured with MultiProc
189  */
190 UInt16 MultiProc_getNumProcessors(Void);
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);
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);
208 /*!
209  *  @brief      Sets executing processor's base id of the cluster
210  *
211  *  @param      baseId  The MultiProc base id of the cluster
212  *
213  *  @return     MultiProc status:
214  *              - #MultiProc_S_SUCCESS: successfully set base id of cluster
215  *              - #MultiProc_E_FAIL:    failed to set base id of cluster
216  */
217 Int MultiProc_setBaseIdOfCluster(UInt16 baseId);
219 /*!
220  *  @brief      Sets executing processor's MultiProc id
221  *
222  *  @param      id  MultiProc id
223  *
224  *  @return     MultiProc status:
225  *              - #MultiProc_S_SUCCESS: MultiProc id successfully set
226  *              - #MultiProc_E_FAIL:    MultiProc id cannot be set at this time
227  */
228 Int MultiProc_setLocalId(UInt16 id);
230 #if defined (__cplusplus)
232 #endif /* defined (__cplusplus) */
234 #endif /* ti_ipc_MultiProc__include */