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 SharedRegion.h
34 *
35 * @brief Shared memory manager and address translator.
36 *
37 * The SharedRegion module is designed to be used in a multi-processor
38 * environment in which memory regions are shared and accessed
39 * across different processors. The module itself does not use any shared
40 * memory, because all module state is stored locally. SharedRegion
41 * APIs use the system gate for thread protection.
42 *
43 * This module creates and stores a local shared memory region table. The
44 * table contains the processor's view for every shared region in the system.
45 * The table must not contain any overlapping regions. Each processor's
46 * view of a particular shared memory region is determined by the region id.
47 * In cases where a processor cannot access a certain shared memory region,
48 * that shared memory region should be left invalid for that processor.
49 * Note: The number of entries must be the same on all processors.
50 *
51 * Each shared region contains the following:
52 * @li @b base - The base address
53 * @li @b len - The length
54 * @li @b name - The name of the region
55 * @li @b isValid - Whether the region is valid
56 * @li @b ownerProcId - The id of the processor which owns the region
57 * @li @b cacheEnable - Whether the region is cacheable
58 * @li @b cacheLineSize - The cache line size
59 * @li @b createHeap - Whether a heap is created for the region.
60 *
61 * A region is added using the SharedRegion_setEntry() API.
62 * The length of a region must be the same across all processors.
63 * The owner of the region can be specified. If specified, the owner
64 * manages the shared region. It creates a HeapMemMP instance which spans
65 * the full size of the region. The other processors open the same HeapMemMP
66 * instance.
67 *
68 * Note: Prior to calling Ipc_start(), If a SharedRegion's 'isValid'
69 * is true and 'createHeap' is true then the owner of the SharedRegion
70 * must be the same as the owner of SharedRegion 0.
71 *
72 * After a shared region is valid, SharedRegion APIs can be used to convert
73 * pointers between the local processor's address space and the SharedRegion-
74 * pointer (SRPtr) address space. These APIs include
75 * SharedRegion_getId(), SharedRegion_getSRPtr() and SharedRegion_getPtr().
76 * An example is shown below:
77 *
78 * @code
79 * SharedRegion_SRPtr srptr;
80 * Ptr addr;
81 * UInt16 id;
82 *
83 * // to get the id of the local address if id is not already known.
84 * id = SharedRegion_getId(addr);
85 *
86 * // to get the shared region pointer for the local address
87 * srptr = SharedRegion_getSRPtr(addr, id);
88 *
89 * // to get the local address from the shared region pointer
90 * addr = SharedRegion_getPtr(srptr);
91 * @endcode
92 *
93 * The SharedRegion header should be included in an application as follows:
94 * @code
95 * #include <ti/ipc/SharedRegion.h>
96 * @endcode
97 *
98 * ============================================================================
99 */
101 #ifndef ti_ipc_SharedRegion__include
102 #define ti_ipc_SharedRegion__include
105 #if defined (__cplusplus)
106 extern "C" {
107 #endif
109 /* ============================================================================
110 * All success and failure codes for the module
111 * =============================================================================
112 */
114 /*!
115 * @brief The resource is still in use
116 */
117 #define SharedRegion_S_BUSY 2
119 /*!
120 * @brief The module has been already setup
121 */
122 #define SharedRegion_S_ALREADYSETUP 1
124 /*!
125 * @brief Operation is successful.
126 */
127 #define SharedRegion_S_SUCCESS 0
129 /*!
130 * @brief Generic failure.
131 */
132 #define SharedRegion_E_FAIL -1
134 /*!
135 * @brief Argument passed to function is invalid.
136 */
137 #define SharedRegion_E_INVALIDARG -2
139 /*!
140 * @brief Operation resulted in memory failure.
141 */
142 #define SharedRegion_E_MEMORY -3
144 /*!
145 * @brief The specified entity already exists.
146 */
147 #define SharedRegion_E_ALREADYEXISTS -4
149 /*!
150 * @brief Unable to find the specified entity.
151 */
152 #define SharedRegion_E_NOTFOUND -5
154 /*!
155 * @brief Operation timed out.
156 */
157 #define SharedRegion_E_TIMEOUT -6
159 /*!
160 * @brief Module is not initialized.
161 */
162 #define SharedRegion_E_INVALIDSTATE -7
164 /*!
165 * @brief A failure occurred in an OS-specific call
166 */
167 #define SharedRegion_E_OSFAILURE -8
169 /*!
170 * @brief Specified resource is not available
171 */
172 #define SharedRegion_E_RESOURCE -9
174 /*!
175 * @brief Operation was interrupted. Please restart the operation
176 */
177 #define SharedRegion_E_RESTART -10
179 /* =============================================================================
180 * Macros
181 * =============================================================================
182 */
184 /*!
185 * @brief Invalid region id
186 */
187 #define SharedRegion_INVALIDREGIONID (0xFFFF)
189 /* =============================================================================
190 * Structures & Enums
191 * =============================================================================
192 */
194 /*!
195 * @brief SharedRegion pointer type
196 */
197 typedef Bits32 SharedRegion_SRPtr;
199 /*!
200 * @brief Structure defining a region
201 */
202 typedef struct SharedRegion_Entry {
203 Ptr base;
204 /*!< The base address of the region */
206 SizeT len;
207 /*!< The length of the region
208 *
209 * Ths length of a region must be the same across all
210 * processors in the system.
211 */
213 UInt16 ownerProcId;
214 /*!< The MultiProc id of the owner of the region
215 *
216 * The owner id for a shared region must be the same across
217 * all processors in the system.
218 */
220 Bool isValid;
221 /*!< Whether the region is valid */
223 Bool cacheEnable;
224 /*!< Whether to perform cache operations for the region
225 *
226 * If 'TRUE', a cache invalidate is performed before any read
227 * and a cache write back invalidate is performed after any
228 * write for the shared region. The cache operations are done
229 * for all caches. If 'FALSE', no cache operations are performed.
230 */
232 SizeT cacheLineSize;
233 /*!< The cache line size of the region
234 *
235 * The cache line size for a region must be the same across
236 * all processors in the system. It is used for structure
237 * alignment and padding.
238 */
240 Bool createHeap;
241 /*!< Whether a heap is created for the region
242 *
243 * If 'TRUE', a HeapMemMP instance is created with the size
244 * spanning the length of the shared region minus any memory
245 * that is reserved in the region. If 'FALSE', no heap
246 * is created in the shared region.
247 */
249 String name;
250 /*!< The name of the region.
251 *
252 * The name must be in persistent memory. It is used for
253 * displaying in ROV.
254 */
255 } SharedRegion_Entry;
258 /* =============================================================================
259 * SharedRegion Module-wide Functions
260 * =============================================================================
261 */
263 /*!
264 * @brief Clears the entry at the specified region id
265 *
266 * SharedRegion_clearEntry() is used to render invalid a shared region that is
267 * currently valid. If the region has a heap, it will either be closed or
268 * deleted as necessary. All attributes of region are reset to defaults.
269 *
270 * Calling SharedRegion_clearEntry() upon a region that is already invalid
271 * simply resets the region attributes to their defaults.
272 *
273 * NOTE: Region #0 is special and can neither be cleared nor set.
274 *
275 * @param regionId the region id
276 *
277 * @return Status
278 * - #SharedRegion_S_SUCCESS: Operation was successful
279 * - #SharedRegion_E_FAIL: Delete or close of heap created
280 * in region failed.
281 *
282 * @sa SharedRegion_setEntry()
283 */
284 Int SharedRegion_clearEntry(UInt16 regionId);
286 /*!
287 * @brief Initializes the entry fields
288 *
289 * @param entry pointer to a SharedRegion entry
290 *
291 * @sa SharedRegion_setEntry()
292 */
293 Void SharedRegion_entryInit(SharedRegion_Entry *entry);
295 /*!
296 * @brief Gets the cache line size for the specified region id
297 *
298 * @param regionId the region id
299 *
300 * @return Cache line size
301 *
302 * @sa SharedRegion_isCacheEnabled()
303 */
304 SizeT SharedRegion_getCacheLineSize(UInt16 regionId);
306 /*!
307 * @brief Gets the entry information for the specified region id
308 *
309 * @param regionId the region id
310 * @param entry pointer to return region information
311 *
312 * @return Status
313 * - #SharedRegion_S_SUCCESS: Operation was successful
314 * - #SharedRegion_E_FAIL: Operation failed
315 *
316 * @sa SharedRegion_setEntry()
317 */
318 Int SharedRegion_getEntry(UInt16 regionId, SharedRegion_Entry *entry);
320 /*!
321 * @brief Gets the heap associated with the specified region id
322 *
323 * If running on BIOS, the heap handle returned is of type xdc.runtime.IHeap.
324 * This handle type can be used with xdc.runtime.Memory. However, if running
325 * on Linux, the heap handle is of type ti.syslink.utils.IHeap. This handle
326 * type cannot be used with xdc.runtime.Memory, but can be used with
327 * ti.syslink.utils.Memory. The handle type is determined at compile time
328 * and cannot be deferred until runtime. The correct header file must be
329 * included to get the right type.
330 *
331 * The following code shows an example.
332 *
333 * @code
334 * #if defined(ti_sdo_ipc)
335 * #include <xdc/runtime/IHeap.h>
336 * #include <xdc/runtime/Memory.h>
337 * #elif defined(ti_syslink)
338 * #include <ti/syslink/utils/IHeap.h>
339 * #include <ti/syslink/utils/Memory.h>
340 * #endif
341 * #include <ti/ipc/SharedRegion.h>
342 *
343 * IHeap_Handle heap;
344 * UInt16 regionId;
345 * SizeT size;
346 * SizeT align;
347 *
348 * heap = (IHeap_Handle)SharedRegion_getHeap(regionId); // get the heap
349 * Memory_alloc(heap, size, align, NULL); // alloc memory from heap
350 * @endcode
351 *
352 * @param regionId the region id
353 *
354 * @return Handle of the heap, NULL if the region has no heap
355 */
356 Ptr SharedRegion_getHeap(UInt16 regionId);
358 /*!
359 * @brief Gets the region id for the specified address
360 *
361 * @param addr address
362 *
363 * @return region id
364 */
365 UInt16 SharedRegion_getId(Ptr addr);
367 /*!
368 * @brief Gets the id of a region, given its name
369 *
370 * @param name name of the region
371 *
372 * @return region id
373 */
374 UInt16 SharedRegion_getIdByName(String name);
376 /*!
377 * @brief Gets the number of regions
378 *
379 * @return number of regions
380 */
381 UInt16 SharedRegion_getNumRegions(Void);
383 /*!
384 * @brief Calculate the local pointer from the shared region pointer
385 *
386 * @param srptr SharedRegion pointer
387 *
388 * @return local pointer or NULL if shared region pointer is invalid
389 *
390 * @sa SharedRegion_getSRPtr()
391 */
392 Ptr SharedRegion_getPtr(SharedRegion_SRPtr srptr);
394 /*!
395 * @brief Calculate the shared region pointer given local address and id
396 *
397 * @param addr the local address
398 * @param regionId region id
399 *
400 * @return SharedRegion pointer
401 *
402 * @sa SharedRegion_getPtr()
403 */
404 SharedRegion_SRPtr SharedRegion_getSRPtr(Ptr addr, UInt16 regionId);
406 /*!
407 * @brief whether cache enable was specified
408 *
409 * @param regionId region id
410 *
411 * @return 'TRUE' if cache enable specified, otherwise 'FALSE'
412 */
413 Bool SharedRegion_isCacheEnabled(UInt16 regionId);
415 /*!
416 * @brief Sets the entry at the specified region id
417 *
418 * SharedRegion_setEntry() is used to set up a shared region that is
419 * currently invalid. Configuration is performed using the values supplied
420 * in the 'entry' parameter. If the 'createHeap' flag is TRUE, then a
421 * region heap will be created (if the processor is the region owner)
422 * or opened.
423 *
424 * If 'createHeap' is TRUE, SharedRegion_setEntry() must always be called by
425 * a 'client' of the shared region only after the region owner has called
426 * SharedRegion_setEntry(). It is unsafe to poll using SharedRegion_setEntry()
427 * to wait for the corresponding heap to be created by the owner. An external
428 * synchronization mechanism (i.e. Notify, shared memory, etc) must be used
429 * to ensure the proper sequence of operations.
430 *
431 * NOTE: This function should never be called upon a region
432 * that is currently valid.
433 *
434 * @param regionId region id
435 * @param entry pointer to set region information.
436 *
437 * @return Status
438 * - #SharedRegion_S_SUCCESS: Operation was successful
439 * - #SharedRegion_E_FAIL: Region already exists or overlaps with
440 * with another region
441 * - #SharedRegion_E_MEMORY: Unable to create Heap
442 */
443 Int SharedRegion_setEntry(UInt16 regionId, SharedRegion_Entry *entry);
445 /*!
446 * @brief Whether address translation is enabled
447 *
448 * @return 'TRUE' if translate is enabled otherwise 'FALSE'
449 */
450 Bool SharedRegion_translateEnabled(Void);
452 /*!
453 * @brief Returns the SharedRegion_SRPtr value that maps to NULL
454 *
455 * @return Value in SRPtr-space that maps to NULL in Ptr-space
456 */
457 SharedRegion_SRPtr SharedRegion_invalidSRPtr(Void);
459 #if defined (__cplusplus)
460 }
461 #endif /* defined (__cplusplus) */
463 #endif /* ti_ipc_SharedRegion__include */