New MultiProc API to update processor mapping
[ipc/ipcdev.git] / packages / ti / ipc / MultiProc.h
1 /*
2  * Copyright (c) 2012-2015 Texas Instruments Incorporated - http://www.ti.com
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.
40  *
41  *  Each processor in the MultiProc module may be uniquely identified by
42  *  either a name string or an integer ranging from 0 to NUMPROCESSORS - 1.
43  *
44  *  At runtime, the MultiProc_getId() call returns the MultiProc id for any
45  *  processor given its name.
46  *
47  *  The MultiProc header should be included in an application as follows:
48  *  @code
49  *  #include <ti/ipc/MultiProc.h>
50  *  @endcode
51  *
52  *  Configuration
53  *  -------------
54  *  It is critical that every core contains a consistent MultiProc
55  *  configuration.  Failure to do so will lead to unknown behavior,
56  *  including failures to attach, messages being sent to the wrong
57  *  cores, etc.
58  *
59  *  With few exceptions (e.g. MultiProc_setLocalId()), the MultiProc
60  *  configuration is done outside of the runtime APIs, and the actual
61  *  setup is unique to each OS:
62  *     - SYS/BIOS - see the ti.sdo.ipc.MultiProc module config settings.
63  *     - Linux/Android - see LAD's MultiProcCfg_<device>.c file,
64  *                       which must also correctly map the remoteproc id
65  *                       in the kernel to a given MultiProc id/name.
66  *     - QNX - see the SystemCfg_<device>.c file.
67  */
69 #ifndef ti_ipc_MultiProc__include
70 #define ti_ipc_MultiProc__include
72 #if defined (__cplusplus)
73 extern "C" {
74 #endif
76 /* =============================================================================
77  *  All success and failure codes for the module
78  * =============================================================================
79  */
81 /*!
82  *  @brief  The resource is still in use
83  */
84 #define MultiProc_S_BUSY                 (2)
86 /*!
87  *  @brief  The module has been already setup
88  */
89 #define MultiProc_S_ALREADYSETUP         (1)
91 /*!
92  *  @brief  Operation is successful.
93  */
94 #define MultiProc_S_SUCCESS              (0)
96 /*!
97  *  @brief  Generic failure.
98  */
99 #define MultiProc_E_FAIL                (-1)
101 /*!
102  *  @brief  Argument passed to function is invalid.
103  */
104 #define MultiProc_E_INVALIDARG          (-2)
106 /*!
107  *  @brief  Operation resulted in memory failure.
108  */
109 #define MultiProc_E_MEMORY              (-3)
111 /*!
112  *  @brief  The specified entity already exists.
113  */
114 #define MultiProc_E_ALREADYEXISTS       (-4)
116 /*!
117  *  @brief  Unable to find the specified entity.
118  */
119 #define MultiProc_E_NOTFOUND            (-5)
121 /*!
122  *  @brief  Operation timed out.
123  */
124 #define MultiProc_E_TIMEOUT             (-6)
126 /*!
127  *  @brief  Module is not initialized.
128  */
129 #define MultiProc_E_INVALIDSTATE        (-7)
131 /*!
132  *  @brief  A failure occurred in an OS-specific call
133  */
134 #define MultiProc_E_OSFAILURE           (-8)
136 /*!
137  *  @brief  Specified resource is not available
138  */
139 #define MultiProc_E_RESOURCE            (-9)
141 /*!
142  *  @brief  Operation was interrupted. Please restart the operation
143  */
144 #define MultiProc_E_RESTART             (-10)
146 /* =============================================================================
147  *  Macros
148  * =============================================================================
149  */
151 /*!
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      Return the list of processors in the cluster
174  *
175  *  Returns a list which contains the procIds of every processor in
176  *  the cluster. This is useful for functions which require a list
177  *  of procIds.
178  *
179  *  @return     List of processors Ids
180  *
181  *  @sa         MultiProc_getNumProcsInCluster
182  */
183 UInt16 *MultiProc_getClusterProcList(Void);
185 /*!
186  *  @brief      Gets the MultiProc id
187  *
188  *  Retrieves the MultiProc id for the processor with corresponding MultiProc
189  *  name. #MultiProc_INVALIDID is returned if the name was not found.
190  *
191  *  @param      name  Name of the processor.
192  *
193  *  @return     MultiProc id
194  *
195  *  @sa         MultiProc_getName
196  */
197 UInt16 MultiProc_getId(String name);
199 /*!
200  *  @brief      Gets the name of a processor
201  *
202  *  @param      id  MultiProc id.
203  *
204  *  @return     Name of the processor
205  *
206  *  The returned string should never be modified.
207  *
208  *  @sa         MultiProc_getId
209  */
210 String MultiProc_getName(UInt16 id);
212 /*!
213  *  @brief      Gets the number of processors
214  *
215  *  @return     Number of processors configured with MultiProc
216  */
217 UInt16 MultiProc_getNumProcessors(Void);
219 /*!
220  *  @brief      Gets the number of processors in the cluster
221  *
222  *  @return     Number of processors in cluster
223  */
224 UInt16 MultiProc_getNumProcsInCluster(Void);
226 /*!
227  *  @brief      Gets executing processor's MultiProc id
228  *
229  *  @return     Executing processor's id
230  *
231  *  @sa         MultiProc_getId
232  */
233 UInt16 MultiProc_self(Void);
235 /*!
236  *  @brief      Sets executing processor's MultiProc id
237  *
238  *  @param      id  MultiProc id
239  *
240  *  @remarks    Many users don't require this function.  A typical use case
241  *              for this function is on a homogenous multicore device where
242  *              the exact same image is loaded onto all cores and the
243  *              'current' processor id is determined/set at runtime by reading
244  *              a GPIO pin or interesting register like C6000's DNUM.
245  *
246  *  @remarks    To succeed, the currently configured id must be
247  *              MultiProc_INVALIDID.
248  *
249  *  @return     MultiProc status:
250  *              - #MultiProc_S_SUCCESS: MultiProc id successfully set
251  *              - #MultiProc_E_FAIL:    MultiProc id cannot be set at this time
252  */
253 Int MultiProc_setLocalId(UInt16 id);
255 /*!
256  *  @brief      Sets executing processor's MultiProc cluster base id
257  *
258  *  @param      id  Cluster base id
259  *
260  *  @remarks    Many users don't require this function.  A typical use case
261  *              for this function is on a homogenous multicore device where
262  *              the exact same image is loaded onto all cores and the
263  *              'current' processor's cluster base id is determined/set at
264  *              runtime by reading a GPIO pin or manually assigned via
265  *              a special mechanism.
266  *
267  *  @remarks    Currently only supported in SYSBIOS.
268  *
269  *  @return     MultiProc status:
270  *              - #MultiProc_S_SUCCESS: MultiProc cluster id successfully set
271  *              - #MultiProc_E_FAIL:    MultiProc cluster id cannot be set
272  */
273 Int MultiProc_setBaseIdOfCluster(UInt16 id);
275 /*
276  *  ======== MultiProc_rprocSetId ========
277  *  Update processor ID mapping at run-time
278  *
279  *  Internal use only. This function is temporary and will be
280  *  removed in a future build.
281  *
282  *  When using remoteproc to load a DSP processor, the VirtIO channel
283  *  ID is non-deterministic. This function is part of a larger hack to
284  *  update the mapping from ProcID to VirtIO Channel ID each time a DSP
285  *  is loaded.
286  */
287 Int MultiProc_rprocSetId(UInt16 procId, UInt rprocId);
289 #if defined (__cplusplus)
291 #endif /* defined (__cplusplus) */
293 #endif /* ti_ipc_MultiProc__include */