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     *  ======== HeapBufMP.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     *! 28-Oct-2009 skp     10/26/09 code review
    18     *! 15-Sep-2009 skp     Support for GateMP and new SharedRegion
    19     *! 23-Aug-2009 skp     Added static support/ROV views
    20     *! 05-Aug-2009 skp     Added 'exact' field to attrs
    21     *! 03-Aug-2008 toddm   Stolen from avala-i18
    22     */
    23    
    24    package ti.sdo.ipc.heaps;
    25    
    26    import ti.sdo.ipc.ListMP;
    27    import ti.sdo.ipc.SharedRegion;
    28    import ti.sdo.ipc.Ipc;
    29    import ti.sdo.ipc.GateMP;
    30    import ti.sdo.utils.NameServer;
    31    
    32    import xdc.rov.ViewInfo;
    33    
    34    import xdc.runtime.Error;
    35    import xdc.runtime.Assert;
    36    
    37    /*!
    38     *  ======== HeapBufMP ========
    39     *  Multi-processor fixed-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/HeapBufMP.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>HeapBufMP = xdc.useModule('ti.sdo.ipc.heaps.HeapBufMP');</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     *  It is important to note that allocation tracking is disabled by default in
    62     *  {@link #trackAllocs}.  Disabling allocation tracking improves alloc/free
    63     *  performance especially when cache calls are required in shared memory.
    64     */
    65    
    66    @InstanceInitError
    67    @InstanceFinalize
    68    
    69    module HeapBufMP inherits xdc.runtime.IHeap 
    70    {
    71        /*! @_nodoc */
    72        metaonly struct BasicView {
    73            String      name;
    74            Ptr         buf;
    75            String      objType;
    76            Ptr         gate;
    77            Bool        exact;
    78            SizeT       align;
    79            SizeT       blockSize;
    80            UInt        numBlocks;
    81            UInt        curAllocated;
    82            UInt        maxAllocated;
    83            Ptr         freeList;
    84        }
    85    
    86        /*! @_nodoc */
    87        @Facet
    88        metaonly config ViewInfo.Instance rovViewInfo =
    89            ViewInfo.create({
    90                viewMap: [
    91                    [
    92                        'Basic',    
    93                        {
    94                            type: ViewInfo.INSTANCE, 
    95                            viewInitFxn: 'viewInitBasic', 
    96                            structName: 'BasicView'
    97                        }
    98                    ]
    99                ]
   100            });
   101            
   102        /*!
   103         *  Assert raised when freeing a block that is not in the buffer's range
   104         */
   105        config Assert.Id A_invBlockFreed =
   106            {msg: "A_invBlockFreed: Invalid block being freed"};
   107            
   108        /*!
   109         *  Error raised when a requested alloc size is too large
   110         */
   111        config Error.Id E_sizeTooLarge =
   112            {msg: "E_sizeTooLarge: Requested alloc size of 0x%x is greater than 0x%x"};
   113            
   114        /*!
   115         *  Error raised when a requested alignment is too large
   116         */
   117        config Error.Id E_alignTooLarge =
   118            {msg: "E_alignTooLarge: Requested alignment size of %d is greater than %d"};
   119            
   120        /*!
   121         *  Error raised when exact matching failed
   122         */
   123        config Error.Id E_exactFail =
   124            {msg: "E_exactFail: Exact allocation failed (requested size = 0x%x and buffer size = 0x%x)"};
   125        
   126        /*! 
   127         *  Maximum runtime entries 
   128         *
   129         *  Maximum number of HeapBufMP's that can be dynamically created and
   130         *  added to the NameServer.
   131         *
   132         *  To minimize the amount of runtime allocation, this parameter allows
   133         *  the pre-allocation of memory for the HeapBufMP's NameServer table.
   134         *  The default is to allow growth (i.e. memory allocation when 
   135         *  creating a new instance).
   136         */
   137        metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
   138        
   139        /*! 
   140         *  Maximum length for heap names
   141         */
   142        config UInt maxNameLen = 32;
   143        
   144        /*! 
   145         *  Section name is used to place the names table
   146         *
   147         *  The default value of NULL implies that no explicit placement is 
   148         *  performed.
   149         */
   150        metaonly config String tableSection = null;
   151        
   152        /*!
   153         *  Track the number of allocated blocks
   154         * 
   155         *  This will enable/disable the tracking of the current and maximum number
   156         *  of allocations for a HeapBufMP instance.  This maximum refers to the 
   157         *  "all time" maximum number of allocations for the history of a HeapBufMP
   158         *  instance.
   159         * 
   160         *  Tracking allocations might adversely affect performance when allocating
   161         *  and/or freeing.  This is especially true if cache is enabled for the
   162         *  shared region.  If this feature is not needed, setting this to false
   163         *  avoids the performance penalty.
   164         */
   165        config Bool trackAllocs = false;
   166        
   167    instance:
   168    
   169        /*! 
   170         *  GateMP used for critical region management of the shared memory 
   171         *
   172         *  Using the default value of NULL will result in use of the GateMP
   173         *  system gate for context protection.
   174         */
   175        config GateMP.Handle gate = null;
   176    
   177        /*! @_nodoc
   178         *  Set to TRUE by the open() call. No one else should touch this!
   179         */
   180        config Bool openFlag = false;
   181        
   182        /*!
   183         *  Use exact matching
   184         *
   185         *  Setting this flag will allow allocation only if the requested size
   186         *  is equal to (rather than less than or equal to) the buffer's block 
   187         *  size.
   188         */
   189        config Bool exact = false;
   190        
   191        /*! 
   192         *  Name of this instance.
   193         *
   194         *  The name (if not NULL) must be unique among all HeapBufMP
   195         *  instances in the entire system.  When creating a new
   196         *  heap, it is necessary to supply an instance name.
   197         */
   198        config String name = null;
   199    
   200        /*! 
   201         *  Alignment (in MAUs) of each block.
   202         *
   203         *  The alignment must be a power of 2. If the value 0 is specified,
   204         *  the value will be changed to meet the minimum structure alignment 
   205         *  requirements (refer to 
   206         *  {@link xdc.runtime.Memory#getMaxDefaultTypeAlign} and
   207         *  {@link xdc.runtime.Memory#getMaxDefaultTypeAlignMeta} and
   208         *  the cache alignment size of the region in which the heap will
   209         *  be placed.  Therefore, the actual alignment may be larger.
   210         *
   211         *  The default alignment is 0.
   212         */
   213        config SizeT align = 0;
   214    
   215        /*! 
   216         *  Number of fixed-size blocks.
   217         *
   218         *  This is a required parameter for all new HeapBufMP instances.
   219         */
   220        config UInt numBlocks = 0;
   221        
   222        /*!
   223         *  Size (in MAUs) of each block.
   224         *
   225         *  HeapBufMP will round the blockSize up to the nearest multiple of the
   226         *  alignment, so the actual blockSize may be larger. When creating a
   227         *  HeapBufMP dynamically, this needs to be taken into account to determine
   228         *  the proper buffer size to pass in.
   229         *
   230         *  Required parameter.
   231         *
   232         *  The default size of the blocks is 0 MAUs.
   233         */
   234        config SizeT blockSize = 0;
   235        
   236        /*! 
   237         *  Shared region ID
   238         *
   239         *  The index corresponding to the shared region from which shared memory
   240         *  will be allocated.
   241         */
   242        config UInt32 regionId = 0;
   243        
   244        /*! @_nodoc
   245         *  Physical address of the shared memory
   246         *
   247         *  This value can be left as 'null' unless it is required to place the
   248         *  heap at a specific location in shared memory.  If sharedAddr is null,
   249         *  then shared memory for a new instance will be allocated from the 
   250         *  heap belonging to the region identified by {@link #regionId}.
   251         */
   252        config Ptr sharedAddr = null;
   253            
   254    internal:
   255        
   256        /*! Used in the attrs->status field */
   257        const UInt32 CREATED = 0x05251995;
   258        
   259        /*! 
   260         *  This Params object is used for temporary storage of the
   261         *  module wide parameters that are for setting the NameServer instance.
   262         */
   263        metaonly config NameServer.Params nameSrvPrms;
   264    
   265        /*! slice and dice the buffer */
   266        Void postInit(Object *obj, Error.Block *eb);
   267        
   268        /*! Structure of attributes in shared memory */    
   269        struct Attrs {
   270            Bits32              status;
   271            SharedRegion.SRPtr  gateMPAddr;     /* GateMP SRPtr (shm safe)       */
   272            SharedRegion.SRPtr  bufPtr;         /* Memory managed by instance    */
   273            Bits32              numFreeBlocks;  /* Number of free blocks         */
   274            Bits32              minFreeBlocks;  /* Min number of free blocks     */
   275            Bits32              blockSize;      /* True size of each block       */
   276            Bits32              align;          /* Alignment of each block       */
   277            Bits32              numBlocks;      /* Number of individual blocks.  */      
   278            Bits16              exact;          /* For 'exact' allocation        */  
   279        }
   280    
   281        struct Instance_State {
   282            Attrs               *attrs;
   283            GateMP.Handle       gate;           /* Gate for critical regions     */
   284            Ipc.ObjType         objType;        /* See enum ObjType              */
   285            Ptr                 nsKey;          /* Used to remove NS entry       */
   286            Bool                cacheEnabled;   /* Whether to do cache calls     */
   287            UInt32              regionId;       /* SharedRegion index            */
   288            SizeT               allocSize;      /* Shared memory allocated       */
   289            Char                *buf;           /* Local pointer to buf          */
   290            ListMP.Handle       freeList;       /* List of free buffers          */
   291            SizeT               blockSize;      /* Adjusted blockSize            */
   292            SizeT               align;          /* Adjusted alignment            */
   293            UInt                numBlocks;      /* Number of blocks in buffer    */
   294            Bool                exact;          /* Exact match flag              */
   295        };
   296        
   297        struct Module_State {
   298            NameServer.Handle   nameServer;     /* NameServer for this module    */
   299        };
   300    }