host_linux: Temporarily disable local lock
[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)
519 #endif /* defined (__cplusplus) */
521 #endif /* SharedRegion__include */