[processor-sdk/big-data-ipc-examples.git] / host_linux / simple_buffer_example / host / SharedRegion / SharedRegion.h
1 /*
2 * Copyright (c) 2017 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 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 SharedRegion__include
102 #define SharedRegion__include
104 #if defined (__cplusplus)
105 extern "C" {
106 #endif
108 /* ============================================================================
109 * All success and failure codes for the module
110 * =============================================================================
111 */
113 /*!
114 * @brief The resource is still in use
115 */
116 #define SharedRegion_S_BUSY 2
118 /*!
119 * @brief The module has been already setup
120 */
121 #define SharedRegion_S_ALREADYSETUP 1
123 /*!
124 * @brief Operation is successful.
125 */
126 #define SharedRegion_S_SUCCESS 0
128 /*!
129 * @brief Generic failure.
130 */
131 #define SharedRegion_E_FAIL -1
133 /*!
134 * @brief Argument passed to function is invalid.
135 */
136 #define SharedRegion_E_INVALIDARG -2
138 /*!
139 * @brief Operation resulted in memory failure.
140 */
141 #define SharedRegion_E_MEMORY -3
143 /*!
144 * @brief The specified entity already exists.
145 */
146 #define SharedRegion_E_ALREADYEXISTS -4
148 /*!
149 * @brief Unable to find the specified entity.
150 */
151 #define SharedRegion_E_NOTFOUND -5
153 /*!
154 * @brief Operation timed out.
155 */
156 #define SharedRegion_E_TIMEOUT -6
158 /*!
159 * @brief Module is not initialized.
160 */
161 #define SharedRegion_E_INVALIDSTATE -7
163 /*!
164 * @brief A failure occurred in an OS-specific call
165 */
166 #define SharedRegion_E_OSFAILURE -8
168 /*!
169 * @brief Specified resource is not available
170 */
171 #define SharedRegion_E_RESOURCE -9
173 /*!
174 * @brief Operation was interrupted. Please restart the operation
175 */
176 #define SharedRegion_E_RESTART -10
178 /* =============================================================================
179 * Macros
180 * =============================================================================
181 */
183 /*!
184 * @brief Invalid region id
185 */
186 #define SharedRegion_INVALIDREGIONID (0xFFFF)
188 /* =============================================================================
189 * Structures & Enums
190 * =============================================================================
191 */
192 /*!
193 * @brief Module configuration structure.
194 */
195 typedef struct SharedRegion_Config {
196 SizeT cacheLineSize;
197 /*!<
198 * Worst-case cache line size
199 *
200 * This is the default system cache line size for all modules.
201 * When a module puts structures in shared memory, this value is
202 * used to make sure items are aligned on a cache line boundary.
203 * If no cacheLineSize is specified for a region, it will use this
204 * value.
205 */
207 UInt16 numEntries;
208 /*!<
209 * The number of shared region table entries.
210 *
211 * This value is used for calculating the number of bits for the offset.
212 * Note: This value must be the same across all processors in the system.
213 * Increasing this parameter will increase the footprint and
214 * the time for translating a pointer to a SRPtr.
215 */
217 Bool translate;
218 /*!< This configuration parameter should be set to 'true'
219 * if and only if all shared memory regions are the same
220 * for all processors. If 'true', it results in a fast
221 * getPtr and getSRPtr.
222 */
223 } SharedRegion_Config;
225 /*!
226 * @brief SharedRegion pointer type
227 */
228 typedef Bits32 SharedRegion_SRPtr;
230 /*!
231 * @brief Structure defining a region
232 */
233 typedef struct SharedRegion_Entry {
234 Ptr base;
235 /*!< @brief The base address of the region */
237 SizeT len;
238 /*!< @brief The length of the region
239 *
240 * The length of a region must be the same across all
241 * processors in the system.
242 */
244 UInt16 ownerProcId;
245 /*!< @brief The MultiProc id of the owner of the region
246 *
247 * The owner id for a shared region must be the same across
248 * all processors in the system.
249 */
251 Bool isValid;
252 /*!< @brief Whether the region is valid */
254 Bool cacheEnable;
255 /*!< @brief Whether to perform cache operations for the region
256 *
257 * If 'TRUE', a cache invalidate is performed before any read
258 * and a cache write back invalidate is performed after any
259 * write for the shared region. The cache operations are done
260 * for all caches. If 'FALSE', no cache operations are performed.
261 */
263 SizeT cacheLineSize;
264 /*!< @brief The cache line size of the region
265 *
266 * The cache line size for a region must be the same across
267 * all processors in the system. It is used for structure
268 * alignment and padding.
269 */
271 Bool createHeap;
272 /*!< @brief Whether a heap is created for the region
273 *
274 * If 'TRUE', a HeapMemMP instance is created with the size
275 * spanning the length of the shared region minus any memory
276 * that is reserved in the region. If 'FALSE', no heap
277 * is created in the shared region.
278 */
280 String name;
281 /*!< @brief The name of the region.
282 *
283 * The name must be in persistent memory. It is used for
284 * displaying in ROV.
285 */
286 } SharedRegion_Entry;
289 /* =============================================================================
290 * SharedRegion Module-wide Functions
291 * =============================================================================
292 */
294 /*!
295 * @brief Clears the @c regionid entry
296 *
297 * SharedRegion_clearEntry() is used to render invalid a shared region that is
298 * currently valid. If the region has a heap, it will either be closed or
299 * deleted as necessary. All attributes of region are reset to defaults.
300 *
301 * Calling SharedRegion_clearEntry() upon a region that is already invalid
302 * simply resets the region attributes to their defaults.
303 *
304 * @note Region #0 is special and can neither be cleared nor set.
305 *
306 * @param regionId the region id
307 *
308 * @return Status
309 * - #SharedRegion_S_SUCCESS: Operation was successful
310 * - #SharedRegion_E_FAIL: Delete or close of heap created
311 * in region failed.
312 *
313 * @sa SharedRegion_setEntry()
314 */
315 Int SharedRegion_clearEntry(UInt16 regionId);
317 /*!
318 * @brief Initializes the entry fields
319 *
320 * @param entry pointer to a SharedRegion entry
321 *
322 * @sa SharedRegion_setEntry()
323 */
324 Void SharedRegion_entryInit(SharedRegion_Entry *entry);
326 /*!
327 * @brief Gets the cache line size for the specified region id
328 *
329 * @param regionId the region id
330 *
331 * @return Cache line size
332 *
333 * @sa SharedRegion_isCacheEnabled()
334 */
335 SizeT SharedRegion_getCacheLineSize(UInt16 regionId);
337 /*!
338 * @brief Gets the entry information for the specified region id
339 *
340 * @param regionId the region id
341 * @param entry pointer to return region information
342 *
343 * @return Status
344 * - #SharedRegion_S_SUCCESS: Operation was successful
345 * - #SharedRegion_E_FAIL: Operation failed
346 *
347 * @sa SharedRegion_setEntry()
348 */
349 Int SharedRegion_getEntry(UInt16 regionId, SharedRegion_Entry *entry);
351 /*!
352 * @brief Return the address of the shared region entry structure
353 *
354 * This function is to be used only for module startup configuration.
355 * The returned address gives you direct access to the in-memory entry
356 * structure. Use it to configure the entry just before the module
357 * startup phase begins. It is intended to support single-image loading.
358 *
359 * Do not use this function during normal run-time operations; use
360 * SharedRegion_getEntry() instead.
361 */
362 SharedRegion_Entry *SharedRegion_getEntryPtr(UInt16 regionId);
364 /*!
365 * @brief Gets the heap associated with the specified region id
366 *
367 * The heap handle returned is of type xdc.runtime.IHeap.
368 * This handle type can be used with xdc.runtime.Memory.
369 *
370 * The following code shows an example.
371 *
372 * @code
373 * #include <xdc/runtime/IHeap.h>
374 * #include <xdc/runtime/Memory.h>
375 * #include <ti/ipc/SharedRegion.h>
376 *
377 * IHeap_Handle heap;
378 * UInt16 regionId;
379 * SizeT size;
380 * SizeT align;
381 *
382 * heap = (IHeap_Handle)SharedRegion_getHeap(regionId); // get the heap
383 * Memory_alloc(heap, size, align, NULL); // alloc memory from heap
384 * @endcode
385 *
386 * @param regionId the region id
387 *
388 * @return Handle of the heap, NULL if the region has no heap
389 */
390 Ptr SharedRegion_getHeap(UInt16 regionId);
392 /*!
393 * @brief Gets the region id for the specified address
394 *
395 * @param addr address
396 *
397 * @return region id
398 */
399 UInt16 SharedRegion_getId(Ptr addr);
401 /*!
402 * @brief Gets the id of a region, given its name
403 *
404 * @param name name of the region
405 *
406 * @return region id
407 */
408 UInt16 SharedRegion_getIdByName(String name);
410 /*!
411 * @brief Gets the number of regions
412 *
413 * @return number of regions
414 */
415 UInt16 SharedRegion_getNumRegions(Void);
417 /*!
418 * @brief Calculate the local pointer from the shared region pointer
419 *
420 * @param srptr SharedRegion pointer
421 *
422 * @return local pointer or NULL if shared region pointer is invalid
423 *
424 * @sa SharedRegion_getSRPtr()
425 */
426 Ptr SharedRegion_getPtr(SharedRegion_SRPtr srptr);
428 /*!
429 * @brief Calculate the shared region pointer given local address and id
430 *
431 * @param addr the local address
432 * @param regionId region id
433 *
434 * @return SharedRegion pointer
435 *
436 * @sa SharedRegion_getPtr()
437 */
438 SharedRegion_SRPtr SharedRegion_getSRPtr(Ptr addr, UInt16 regionId);
440 /*!
441 * @brief whether cache enable was specified
442 *
443 * @param regionId region id
444 *
445 * @return 'TRUE' if cache enable specified, otherwise 'FALSE'
446 */
447 Bool SharedRegion_isCacheEnabled(UInt16 regionId);
449 /*!
450 * @brief Sets the entry at the specified region id
451 *
452 * SharedRegion_setEntry() is used to set up a shared region that is
453 * currently invalid. Configuration is performed using the values supplied
454 * in the 'entry' parameter. If the 'createHeap' flag is TRUE, then a
455 * region heap will be created (if the processor is the region owner)
456 * or opened.
457 *
458 * If 'createHeap' is TRUE, SharedRegion_setEntry() must always be called by
459 * a 'client' of the shared region only after the region owner has called
460 * SharedRegion_setEntry(). It is unsafe to poll using SharedRegion_setEntry()
461 * to wait for the corresponding heap to be created by the owner. An external
462 * synchronization mechanism (i.e. Notify, shared memory, etc) must be used
463 * to ensure the proper sequence of operations.
464 *
465 * NOTE: This function should never be called upon a region
466 * that is currently valid.
467 *
468 * @param regionId region id
469 * @param entry pointer to set region information.
470 *
471 * @return Status
472 * - #SharedRegion_S_SUCCESS: Operation was successful
473 * - #SharedRegion_E_FAIL: Region already exists or overlaps with
474 * with another region
475 * - #SharedRegion_E_MEMORY: Unable to create Heap
476 */
477 Int SharedRegion_setEntry(UInt16 regionId, SharedRegion_Entry *entry);
479 /*!
480 * @brief Whether address translation is enabled
481 *
482 * @return 'TRUE' if translate is enabled otherwise 'FALSE'
483 */
484 Bool SharedRegion_translateEnabled(Void);
486 /*!
487 * @brief Returns the SharedRegion_SRPtr value that maps to NULL
488 *
489 * @return Value in SRPtr-space that maps to NULL in Ptr-space
490 */
491 SharedRegion_SRPtr SharedRegion_invalidSRPtr(Void);
493 /*!
494 * @brief Function to setup the SharedRegion module.
495 *
496 * @param cfgParams Configuration values.
497 */
498 Void SharedRegion_getConfig (SharedRegion_Config * config);
500 /*!
501 * @brief Function to setup the SharedRegion module.
502 *
503 * Here if user passes both numEntries and indexBits, than
504 * numEntries takes precedence over indexBits.
505 *
506 * @param cfg Configuration values.
507 *
508 * @sa SharedRegion_destroy
509 */
510 Int SharedRegion_setup (SharedRegion_Config * config);
512 /* =============================================================================
513 * APIs
514 * =============================================================================
515 */
517 #if defined (__cplusplus)
518 }
519 #endif /* defined (__cplusplus) */
521 #endif /* SharedRegion__include */