Rename: git mv src packages to complete application of ipc-j patches to ipcdev.
[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       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  */
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  *  @def    MultiProc_S_BUSY
69  *  @brief  The resource is still in use
70  */
71 #define MultiProc_S_BUSY                 2
73 /*!
74  *  @def    MultiProc_S_ALREADYSETUP
75  *  @brief  The module has been already setup
76  */
77 #define MultiProc_S_ALREADYSETUP         1
79 /*!
80  *  @def    MultiProc_S_SUCCESS
81  *  @brief  Operation is successful.
82  */
83 #define MultiProc_S_SUCCESS              0
85 /*!
86  *  @def    MultiProc_E_FAIL
87  *  @brief  Generic failure.
88  */
89 #define MultiProc_E_FAIL                -1
91 /*!
92  *  @def    MultiProc_E_INVALIDARG
93  *  @brief  Argument passed to function is invalid.
94  */
95 #define MultiProc_E_INVALIDARG          -2
97 /*!
98  *  @def    MultiProc_E_MEMORY
99  *  @brief  Operation resulted in memory failure.
100  */
101 #define MultiProc_E_MEMORY              -3
103 /*!
104  *  @def    MultiProc_E_ALREADYEXISTS
105  *  @brief  The specified entity already exists.
106  */
107 #define MultiProc_E_ALREADYEXISTS       -4
109 /*!
110  *  @def    MultiProc_E_NOTFOUND
111  *  @brief  Unable to find the specified entity.
112  */
113 #define MultiProc_E_NOTFOUND            -5
115 /*!
116  *  @def    MultiProc_E_TIMEOUT
117  *  @brief  Operation timed out.
118  */
119 #define MultiProc_E_TIMEOUT             -6
121 /*!
122  *  @def    MultiProc_E_INVALIDSTATE
123  *  @brief  Module is not initialized.
124  */
125 #define MultiProc_E_INVALIDSTATE        -7
127 /*!
128  *  @def    MultiProc_E_OSFAILURE
129  *  @brief  A failure occurred in an OS-specific call
130  */
131 #define MultiProc_E_OSFAILURE           -8
133 /*!
134  *  @def    MultiProc_E_RESOURCE
135  *  @brief  Specified resource is not available
136  */
137 #define MultiProc_E_RESOURCE            -9
139 /*!
140  *  @def    MultiProc_E_RESTART
141  *  @brief  Operation was interrupted. Please restart the operation
142  */
143 #define MultiProc_E_RESTART             -10
145 /* =============================================================================
146  *  Macros
147  * =============================================================================
148  */
150 /*!
151  *  @def    MultiProc_INVALIDID
152  *  @brief  Invalid processor id.
153  */
154 #define MultiProc_INVALIDID             (0xFFFF)
156 /* =============================================================================
157  *  MultiProc Module-wide Functions
158  * =============================================================================
159  */
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);
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);
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);
199 /*!
200  *  @brief      Gets the number of processors
201  *
202  *  @return     Number of processors configured with MultiProc
203  */
204 UInt16 MultiProc_getNumProcessors(Void);
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);
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);
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);
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);
244 #if defined (__cplusplus)
246 #endif /* defined (__cplusplus) */
248 #endif /* ti_ipc_MultiProc__include */