1    /* --COPYRIGHT--,TI
     2     * Copyright (c) $(CPYYEAR)
     3     * Texas Instruments
     4     *
     5     *  All rights reserved.  Property of Texas Instruments
     6     *  Restricted rights to use, duplicate or disclose this code are
     7     *  granted through contract.
     8     * 
     9     * --/COPYRIGHT--*/
    10    /*
    11     *  ======== HeapMemMP.xdc ========
    12     *
    13     *! Revision History
    14     *! ================
    15     *! 23-Mar-2010 skp     cdoc cleanup
    16     *! 12-Feb-2010 skp     SDOCM00066723 (Remove 'version' field from Attrs)
    17     *! 09-Sep-2009 skp     09/09/09 code review changes
    18     *! 27-Aug-2009 skp     08/26/09 code review changes
    19     *! 23-Aug-2009 skp     Added static support/ROV views
    20     *! 12-Aug-2009 skp     Created from ti.sysbios.heaps.HeapMem
    21     */
    22    
    23    package ti.sdo.ipc.heaps;
    24    
    25    import ti.sdo.ipc.SharedRegion;
    26    import ti.sdo.ipc.Ipc;
    27    import ti.sdo.ipc.GateMP;
    28    import ti.sdo.utils.NameServer;
    29    
    30    import xdc.rov.ViewInfo;    /* Display local/shared state + FreeBlockView */
    31    
    32    import xdc.runtime.Error;
    33    import xdc.runtime.Assert;
    34    import xdc.runtime.Memory;
    35    import xdc.runtime.Startup;
    36    
    37    /*!
    38     *  ======== HeapMemMP ========
    39     *  Multi-processor variable size buffer heap implementation.
    40     *
    41     *  This module has a common header that can be found in the {@link ti.ipc}
    42     *  package.  Application code should include the common header file (not the 
    43     *  RTSC-generated one):
    44     *
    45     *  <PRE>#include &lt;ti/ipc/HeapMemMP.h></PRE>
    46     *   
    47     *  The RTSC module must be used in the application's RTSC configuration file 
    48     *  (.cfg) if runtime APIs will be used in the application:
    49     *  
    50     *  <PRE>HeapMemMP = xdc.useModule('ti.sdo.ipc.heaps.HeapMemMP');</PRE>
    51     *
    52     *  Documentation for all runtime APIs, instance configuration parameters, 
    53     *  error codes macros and type definitions available to the application 
    54     *  integrator can be found in the 
    55     *  <A HREF="../../../../doxygen/html/files.html">Doxygen documenation</A>
    56     *  for the IPC product.  However, the documentation presented on this page 
    57     *  should be referred to for information specific to the RTSC module, such as
    58     *  module configuration, Errors, and Asserts.
    59     *  @p
    60     */
    61    @InstanceInitError   /* For NameServer_addUInt32                            */
    62    @InstanceFinalize    /* For finalizing shared memory and removing NS entry  */
    63    
    64    module HeapMemMP inherits xdc.runtime.IHeap {
    65        
    66        /*! @_nodoc */
    67        metaonly struct BasicView {
    68            String          name;
    69            Ptr             buf;
    70            Memory.Size     totalSize;
    71            String          objType;
    72            Ptr             gate;
    73        }
    74        
    75        /*! @_nodoc */
    76        metaonly struct DetailedView {
    77            String          name;
    78            Ptr             buf;
    79            Memory.Size     totalSize;
    80            String          objType;
    81            Ptr             gate;  
    82            Ptr             attrs;
    83            Bool            cacheEnabled;
    84            Memory.Size     totalFreeSize;
    85            Memory.Size     largestFreeSize;
    86        }
    87        
    88        /*! @_nodoc */
    89        metaonly struct FreeBlockView {
    90            String          address;
    91            String          label;
    92            String          size;
    93        }
    94    
    95        /*! @_nodoc */
    96        @Facet
    97        metaonly config ViewInfo.Instance rovViewInfo = 
    98            ViewInfo.create({
    99                viewMap: [
   100                [
   101                    'Basic',
   102                    {
   103                        type: ViewInfo.INSTANCE,
   104                        viewInitFxn: 'viewInitBasic',
   105                        structName: 'BasicView'
   106                    }
   107                ],
   108                [
   109                    'Detailed',
   110                    {
   111                        type: ViewInfo.INSTANCE,
   112                        viewInitFxn: 'viewInitDetailed',
   113                        structName: 'DetailedView'
   114                    }
   115                ],
   116                [
   117                    'FreeList',
   118                    {
   119                        type: ViewInfo.INSTANCE_DATA,
   120                        viewInitFxn: 'viewInitData',
   121                        structName: 'FreeBlockView'
   122                    }
   123                ]
   124                ]
   125            });
   126    
   127        /*!
   128         *  ======== ExtendedStats ========
   129         *  Stats structure for the getExtendedStats API.  
   130         *
   131         *  @field(buf)           Local address of the shared buffer
   132         *                        This may be different from the original buf 
   133         *                        parameter due to alignment requirements.
   134         *  @field(size)          Size of the shared buffer. 
   135         *                        This may be different from the original size 
   136         *                        parameter due to alignment requirements.
   137         */
   138        struct ExtendedStats {
   139            Ptr   buf;
   140            SizeT size;
   141        }
   142      
   143        /*!
   144         *  Assert raised when a block of size 0 is requested.
   145         */
   146        config Assert.Id A_zeroBlock = 
   147            {msg: "A_zeroBlock: Cannot allocate size 0"};
   148        
   149        /*!
   150         *  Assert raised when the requested heap size is too small.
   151         */
   152        config Assert.Id A_heapSize = 
   153            {msg: "A_heapSize: Requested heap size is too small"};     
   154        
   155        /*!
   156         *  Assert raised when the requested alignment is not a power of 2.
   157         */
   158        config Assert.Id A_align = 
   159            {msg: "A_align: Requested align is not a power of 2"};     
   160            
   161        /*!
   162         *  Assert raised when the free detects that an invalid addr or size. 
   163         *
   164         *  This could arise when multiple frees are done on the same buffer or
   165         *  if corruption occurred.
   166         *
   167         *  This also could occur when an alloc is made with size N and the 
   168         *  free for this buffer specifies size M where M > N. Note: not every 
   169         *  case is detectable.
   170         *
   171         *  This assert can also be caused when passing an invalid addr to free
   172         *  or if the size is causing the end of the buffer to be
   173         *  out of the expected range.
   174         */
   175        config Assert.Id A_invalidFree = 
   176            {msg: "A_invalidFree: Invalid free"};
   177        
   178        /*! 
   179         *  Maximum runtime entries 
   180         *
   181         *  Maximum number of HeapMemMP's that can be dynamically created and
   182         *  added to the NameServer.
   183         *
   184         *  To minimize the amount of runtime allocation, this parameter allows
   185         *  the pre-allocation of memory for the HeapMemMP's NameServer table.
   186         *  The default is to allow growth (i.e. memory allocation when 
   187         *  creating a new instance).
   188         */
   189        metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
   190        
   191        /*! 
   192         *  Maximum length for heap names
   193         */
   194        config UInt maxNameLen = 32;
   195        
   196        /*! 
   197         *  Section name is used to place the names table
   198         *
   199         *  The default value of NULL implies that no explicit placement is 
   200         *  performed.
   201         */
   202        metaonly config String tableSection = null;
   203    
   204    instance:
   205    
   206        /*! 
   207         *  GateMP used for critical region management of the shared memory 
   208         *
   209         *  Using the default value of NULL will result in use of the GateMP
   210         *  system gate for context protection.
   211         */
   212        config GateMP.Handle gate = null; 
   213        
   214        /*! @_nodoc
   215         *  Set to TRUE by the open() call. No one else should touch this!
   216         */
   217        config Bool openFlag = false;
   218    
   219        /*! 
   220         *  Name of this instance.
   221         *
   222         *  The name (if not NULL) must be unique among all HeapMemMP
   223         *  instances in the entire system.  When creating a new
   224         *  heap, it is necessary to supply an instance name.
   225         */
   226        config String name = null;
   227        
   228        /*! 
   229         *  Shared region ID
   230         *
   231         *  The index corresponding to the shared region from which shared memory
   232         *  will be allocated.
   233         */
   234        config UInt32 regionId = 0;
   235    
   236        /*! @_nodoc
   237         *  Physical address of the shared memory
   238         *
   239         *  This value can be left as 'null' unless it is required to place the
   240         *  heap at a specific location in shared memory.  If sharedAddr is null,
   241         *  then shared memory for a new instance will be allocated from the 
   242         *  heap belonging to the region identified by {@link #regionId}.
   243         */
   244        config Ptr sharedAddr = null;
   245        
   246        /*!
   247         *  Size of {@link #sharedBuf}
   248         *
   249         *  This is the size of the buffer to be used in the HeapMemMP instance.  
   250         *  The actual buffer size in the created instance might actually be less
   251         *  than the value supplied in 'sharedBufSize' because of alignment 
   252         *  constraints. 
   253         *
   254         *  It is important to note that the total amount of shared memory required
   255         *  for a HeapMemMP instance will be greater than the size supplied here.
   256         *  Additional space will be consumed by shared instance attributes and
   257         *  alignment-related padding.  Use the {@link #sharedMemReq} or the
   258         *  {@link #sharedMemReqMeta} call to determine the exact amount of shared
   259         *  memory required for an instance for a given sharedBufSize and cache
   260         *  settings.
   261         */
   262        config SizeT sharedBufSize = 0; 
   263    
   264        /*! 
   265         *  ======== getStats ========
   266         *  @a(HeapMemMP)
   267         *  getStats() will lock the heap using the HeapMemMP Gate while it retrieves
   268         *  the HeapMemMP's statistics.
   269         *
   270         *  The returned totalSize reflects the usable size of the buffer, not
   271         *  necessarily the size specified during create.
   272         */
   273        override Void getStats(xdc.runtime.Memory.Stats *stats);
   274    
   275    internal:
   276    
   277        /*! Used in the attrs->status field */
   278        const UInt32 CREATED    = 0x07041776;
   279    
   280        /*! 
   281         *  This Params object is used for temporary storage of the
   282         *  module wide parameters that are for setting the NameServer instance.
   283         */
   284        metaonly config NameServer.Params nameSrvPrms;
   285    
   286        /*! Initialize shared memory, adjust alignment, allocate memory for buf */
   287        Void postInit(Object *obj, Error.Block *eb);
   288        
   289        /*! 
   290         * Header maintained at the lower address of every free block. The size of 
   291         * this struct must be a power of 2 
   292         */
   293        struct Header {
   294            SharedRegion.SRPtr  next;  /* SRPtr to next header (Header *)    */
   295            Bits32              size;  /* Size of this segment (Memory.size) */
   296        };
   297        
   298        /*! Structure of attributes in shared memory */    
   299        struct Attrs {
   300            Bits32                  status;     /* Version number                */
   301            SharedRegion.SRPtr      bufPtr;     /* SRPtr to buf                  */
   302            Header                  head;       /* First free block pointer.     */
   303                                                /* The size field will be used   */
   304                                                /* to store original heap size.  */
   305            SharedRegion.SRPtr      gateMPAddr; /* GateMP SRPtr                  */
   306        }
   307    
   308        struct Instance_State {
   309            Attrs               *attrs;         /* Local pointer to attrs        */
   310            GateMP.Handle       gate;           /* Gate for critical regions     */
   311            Ipc.ObjType         objType;        /* Static/Dynamic? open/creator? */
   312            Ptr                 nsKey;          /* Used to remove NS entry       */    
   313            Bool                cacheEnabled;   /* Whether to do cache calls     */
   314            UInt32              regionId;       /* SharedRegion index            */
   315            SizeT               allocSize;      /* Shared memory allocated       */
   316            Char                *buf;           /* Local pointer to buf          */
   317            SizeT               minAlign;       /* Minimum alignment required    */
   318            SizeT               bufSize;        /* Size of usable buffer         */
   319        };
   320        
   321        struct Module_State {
   322            NameServer.Handle       nameServer;
   323        };
   324    }
   325