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/SharedRegion.h
34 *
35 * @brief Shared memory manager and address translator
36 *
37 * @note SharedRegion is currently only available for SYS/BIOS.
38 *
39 * The SharedRegion module is designed to be used in a multi-processor
40 * environment in which memory regions are shared and accessed
41 * across different processors. The module itself does not use any shared
42 * memory, because all module state is stored locally. SharedRegion
43 * APIs use the system gate for thread protection.
44 *
45 * This module creates and stores a local shared memory region table. The
46 * table contains the processor's view for every shared region in the system.
47 * The table must not contain any overlapping regions. Each processor's
48 * view of a particular shared memory region is determined by the region id.
49 * In cases where a processor cannot access a certain shared memory region,
50 * that shared memory region should be left invalid for that processor.
51 * Note: The number of entries must be the same on all processors.
52 *
53 * Each shared region contains the following:
54 * - @b base - The base address
55 * - @b len - The length
56 * - @b name - The name of the region
57 * - @b isValid - Whether the region is valid
58 * - @b ownerProcId - The id of the processor which owns the region
59 * - @b cacheEnable - Whether the region is cacheable
60 * - @b cacheLineSize - The cache line size
61 * - @b createHeap - Whether a heap is created for the region.
62 *
63 * A region is added using the SharedRegion_setEntry() API.
64 * The length of a region must be the same across all processors.
65 * The owner of the region can be specified. If specified, the owner
66 * manages the shared region. It creates a HeapMemMP instance which spans
67 * the full size of the region. The other processors open the same HeapMemMP
68 * instance.
69 *
70 * Note: Prior to calling Ipc_start(), If a SharedRegion's 'isValid'
71 * is true and 'createHeap' is true then the owner of the SharedRegion
72 * must be the same as the owner of SharedRegion 0.
73 *
74 * After a shared region is valid, SharedRegion APIs can be used to convert
75 * pointers between the local processor's address space and the SharedRegion-
76 * pointer (SRPtr) address space. These APIs include
77 * SharedRegion_getId(), SharedRegion_getSRPtr() and SharedRegion_getPtr().
78 * An example is shown below:
79 *
80 * @code
81 * SharedRegion_SRPtr srptr;
82 * Ptr addr;
83 * UInt16 id;
84 *
85 * // to get the id of the local address if id is not already known.
86 * id = SharedRegion_getId(addr);
87 *
88 * // to get the shared region pointer for the local address
89 * srptr = SharedRegion_getSRPtr(addr, id);
90 *
91 * // to get the local address from the shared region pointer
92 * addr = SharedRegion_getPtr(srptr);
93 * @endcode
94 *
95 * The SharedRegion header should be included in an application as follows:
96 * @code
97 * #include <ti/ipc/SharedRegion.h>
98 * @endcode
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 /*!< @brief The base address of the region */
206 SizeT len;
207 /*!< @brief The length of the region
208 *
209 * The length of a region must be the same across all
210 * processors in the system.
211 */
213 UInt16 ownerProcId;
214 /*!< @brief 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 /*!< @brief Whether the region is valid */
223 Bool cacheEnable;
224 /*!< @brief 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 /*!< @brief 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 /*!< @brief 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 /*!< @brief 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 @c regionid entry
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 Return the address of the shared region entry structure
322 *
323 * This function is to be used only for module startup configuration.
324 * The returned address gives you direct access to the in-memory entry
325 * structure. Use it to configure the entry just before the module
326 * startup phase begins. It is intended to support single-image loading.
327 *
328 * Do not use this function during normal run-time operations; use
329 * SharedRegion_getEntry() instead.
330 */
331 SharedRegion_Entry *SharedRegion_getEntryPtr(UInt16 regionId);
333 /*!
334 * @brief Gets the heap associated with the specified region id
335 *
336 * The heap handle returned is of type xdc.runtime.IHeap.
337 * This handle type can be used with xdc.runtime.Memory.
338 *
339 * The following code shows an example.
340 *
341 * @code
342 * #include <xdc/runtime/IHeap.h>
343 * #include <xdc/runtime/Memory.h>
344 * #include <ti/ipc/SharedRegion.h>
345 *
346 * IHeap_Handle heap;
347 * UInt16 regionId;
348 * SizeT size;
349 * SizeT align;
350 *
351 * heap = (IHeap_Handle)SharedRegion_getHeap(regionId); // get the heap
352 * Memory_alloc(heap, size, align, NULL); // alloc memory from heap
353 * @endcode
354 *
355 * @param regionId the region id
356 *
357 * @return Handle of the heap, NULL if the region has no heap
358 */
359 Ptr SharedRegion_getHeap(UInt16 regionId);
361 /*!
362 * @brief Gets the region id for the specified address
363 *
364 * @param addr address
365 *
366 * @return region id
367 */
368 UInt16 SharedRegion_getId(Ptr addr);
370 /*!
371 * @brief Gets the id of a region, given its name
372 *
373 * @param name name of the region
374 *
375 * @return region id
376 */
377 UInt16 SharedRegion_getIdByName(String name);
379 /*!
380 * @brief Gets the number of regions
381 *
382 * @return number of regions
383 */
384 UInt16 SharedRegion_getNumRegions(Void);
386 /*!
387 * @brief Calculate the local pointer from the shared region pointer
388 *
389 * @param srptr SharedRegion pointer
390 *
391 * @return local pointer or NULL if shared region pointer is invalid
392 *
393 * @sa SharedRegion_getSRPtr()
394 */
395 Ptr SharedRegion_getPtr(SharedRegion_SRPtr srptr);
397 /*!
398 * @brief Calculate the shared region pointer given local address and id
399 *
400 * @param addr the local address
401 * @param regionId region id
402 *
403 * @return SharedRegion pointer
404 *
405 * @sa SharedRegion_getPtr()
406 */
407 SharedRegion_SRPtr SharedRegion_getSRPtr(Ptr addr, UInt16 regionId);
409 /*!
410 * @brief whether cache enable was specified
411 *
412 * @param regionId region id
413 *
414 * @return 'TRUE' if cache enable specified, otherwise 'FALSE'
415 */
416 Bool SharedRegion_isCacheEnabled(UInt16 regionId);
418 /*!
419 * @brief Sets the entry at the specified region id
420 *
421 * SharedRegion_setEntry() is used to set up a shared region that is
422 * currently invalid. Configuration is performed using the values supplied
423 * in the 'entry' parameter. If the 'createHeap' flag is TRUE, then a
424 * region heap will be created (if the processor is the region owner)
425 * or opened.
426 *
427 * If 'createHeap' is TRUE, SharedRegion_setEntry() must always be called by
428 * a 'client' of the shared region only after the region owner has called
429 * SharedRegion_setEntry(). It is unsafe to poll using SharedRegion_setEntry()
430 * to wait for the corresponding heap to be created by the owner. An external
431 * synchronization mechanism (i.e. Notify, shared memory, etc) must be used
432 * to ensure the proper sequence of operations.
433 *
434 * NOTE: This function should never be called upon a region
435 * that is currently valid.
436 *
437 * @param regionId region id
438 * @param entry pointer to set region information.
439 *
440 * @return Status
441 * - #SharedRegion_S_SUCCESS: Operation was successful
442 * - #SharedRegion_E_FAIL: Region already exists or overlaps with
443 * with another region
444 * - #SharedRegion_E_MEMORY: Unable to create Heap
445 */
446 Int SharedRegion_setEntry(UInt16 regionId, SharedRegion_Entry *entry);
448 /*!
449 * @brief Whether address translation is enabled
450 *
451 * @return 'TRUE' if translate is enabled otherwise 'FALSE'
452 */
453 Bool SharedRegion_translateEnabled(Void);
455 /*!
456 * @brief Returns the SharedRegion_SRPtr value that maps to NULL
457 *
458 * @return Value in SRPtr-space that maps to NULL in Ptr-space
459 */
460 SharedRegion_SRPtr SharedRegion_invalidSRPtr(Void);
462 #if defined (__cplusplus)
463 }
464 #endif /* defined (__cplusplus) */
466 #endif /* ti_ipc_SharedRegion__include */