1    /* 
     2     * Copyright (c) 2010, Texas Instruments Incorporated
     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     *  ======== HeapMultiBufMP.xdc ========
    34     *
    35     * 
    36     */
    37    
    38    package ti.sdo.ipc.heaps;
    39    
    40    import ti.sdo.ipc.SharedRegion;
    41    import ti.sdo.ipc.Ipc;
    42    import ti.sdo.ipc.GateMP;
    43    import ti.sdo.utils.NameServer;
    44    
    45    import xdc.rov.ViewInfo;    /* Display local/shared state + FreeBlockView */
    46    
    47    import xdc.runtime.Error;
    48    import xdc.runtime.Assert;
    49    import xdc.runtime.Memory;
    50    import xdc.runtime.Startup;
    51    
    52    /*!
    53     *  ======== HeapMultiBufMP ========
    54     *  Multi-processor fixed-size buffer heap implementation
    55     *
    56     *  @p(html)
    57     *  This module has a common header that can be found in the {@link ti.ipc}
    58     *  package.  Application code should include the common header file (not the 
    59     *  RTSC-generated one):
    60     *
    61     *  <PRE>#include &lt;ti/ipc/HeapMultiBufMP.h></PRE>
    62     *   
    63     *  The RTSC module must be used in the application's RTSC configuration file 
    64     *  (.cfg) if runtime APIs will be used in the application:
    65     *  
    66     *  <PRE>HeapMultiBufMP = xdc.useModule('ti.sdo.ipc.heaps.HeapMultiBufMP');
    67     *  </PRE>
    68     *
    69     *  Documentation for all runtime APIs, instance configuration parameters, 
    70     *  error codes macros and type definitions available to the application 
    71     *  integrator can be found in the 
    72     *  <A HREF="../../../../../doxygen/html/files.html">Doxygen documenation</A>
    73     *  for the IPC product.  However, the documentation presented on this page 
    74     *  should be referred to for information specific to the RTSC module, such as
    75     *  module configuration, Errors, and Asserts.
    76     *  @p
    77     *
    78     *  It is important to note that max allocation tracking is disabled by default 
    79     *  in {@link #trackMaxAllocs}.  Disabling allocation tracking improves alloc/
    80     *  free performance especially when cache calls are required in shared memory.
    81     */
    82    @InstanceInitError
    83    @InstanceFinalize
    84    
    85    module HeapMultiBufMP inherits xdc.runtime.IHeap 
    86    {
    87        /*! @_nodoc */
    88        metaonly struct BasicView {
    89            String          name;
    90            Ptr             buf;
    91            Memory.Size     totalSize;
    92            String          objType;
    93            Ptr             gate;
    94            Bool            exact;
    95        }
    96        
    97        /*! @_nodoc */
    98        metaonly struct BucketsView {
    99            Ptr             baseAddr;
   100            UInt            blockSize;
   101            UInt            align;
   102            UInt            numBlocks;
   103            UInt            numFreeBlocks;
   104            UInt            minFreeBlocks;
   105        }
   106    
   107        /*! @_nodoc */
   108        @Facet
   109        metaonly config ViewInfo.Instance rovViewInfo =
   110            ViewInfo.create({
   111                viewMap: [
   112                [   
   113                    'Basic',
   114                    {
   115                        type: ViewInfo.INSTANCE,
   116                        viewInitFxn: 'viewInitBasic',
   117                        structName: 'BasicView'
   118                    }
   119                ],
   120                [   
   121                    'Buffer Information',
   122                    {
   123                        type: ViewInfo.INSTANCE_DATA,
   124                        viewInitFxn: 'viewInitData',
   125                        structName: 'BucketsView'
   126                    }
   127                ],
   128                ]
   129            });
   130            
   131        /*! 
   132         *  Structure for bucket configuration
   133         *
   134         *  An array of buckets is a required parameter to create any 
   135         *  HeapMultiBufMP instance.  The fields of each bucket correspond
   136         *  to the attributes of each buffer in the HeapMultiBufMP.  The actual
   137         *  block sizes and alignments may be adjusted per the process described
   138         *  at {@link #bucketEntries}.
   139         *
   140         *  @field(blockSize)       Size of each block (in MADUs)
   141         *  @field(numBlocks)       Number of blocks
   142         *  @field(align)           Alignment of each block (in MADUs)
   143         */    
   144        struct Bucket {
   145            SizeT       blockSize;
   146            UInt        numBlocks;
   147            SizeT       align;
   148        }
   149    
   150        /*!
   151         *  ======== ExtendedStats ========
   152         *  Stats structure for the getExtendedStats API.  
   153         *
   154         *  @field(numBuckets)         Number of buckets
   155         *  @field(numBlocks)          Number of blocks in each buffer
   156         *  @field(blockSize)          Block size of each buffer     
   157         *  @field(align)              Alignment of each buffer
   158         *  @field(maxAllocatedBlocks) The maximum number of blocks allocated from
   159         *                             this heap at any single point in time during
   160         *                             the lifetime of this HeapMultiBufMP instance
   161         *
   162         *  @field(numAllocatedBlocks) The total number of blocks currently
   163         *                             allocated in this HeapMultiBufMP instance
   164         */
   165        struct ExtendedStats {
   166            UInt numBuckets;
   167            UInt numBlocks          [8];
   168            UInt blockSize          [8];
   169            UInt align              [8];
   170            UInt maxAllocatedBlocks [8];
   171            UInt numAllocatedBlocks [8];
   172        }
   173            
   174        /*!
   175         *  Assert raised when the align parameter is not a power of 2.
   176         */
   177        config Assert.Id A_invalidAlign = 
   178            {msg: "align parameter must be a power of 2"};
   179    
   180        /*! 
   181         *  Assert raised when an invalid buffer size was passed to free() 
   182         */
   183        config Assert.Id A_sizeNotFound = 
   184            {msg: "an invalid buffer size was passed to free"};
   185            
   186        /*! 
   187         *  Assert raised when an invalid block address was passed to free() 
   188         */
   189        config Assert.Id A_addrNotFound = 
   190            {msg: "an invalid buffer address was passed to free"};
   191            
   192        /*!
   193         *  Error raised when exact matching failed
   194         */
   195        config Error.Id E_exactFail =
   196            {msg: "E_exactFail: Exact allocation failed (requested size = 0x%x and buffer size = 0x%x)"};        
   197      
   198        /*! 
   199         *  Maximum runtime entries 
   200         *
   201         *  Maximum number of HeapMultiBufMP's that can be dynamically created and
   202         *  added to the NameServer.
   203         *
   204         *  To minimize the amount of runtime allocation, this parameter allows
   205         *  the pre-allocation of memory for the HeapMultiBufMP's NameServer table.
   206         *  The default is to allow growth (i.e. memory allocation when 
   207         *  creating a new instance).
   208         */
   209        metaonly config UInt maxRuntimeEntries = NameServer.ALLOWGROWTH;
   210            
   211        /*! 
   212         *  Maximum length for heap names
   213         */
   214        config UInt maxNameLen = 32;
   215        
   216        /*! 
   217         *  Section name is used to place the names table
   218         *
   219         *  The default value of NULL implies that no explicit placement is 
   220         *  performed.
   221         */
   222        metaonly config String tableSection = null;
   223        
   224        /*!
   225         *  Track the maximum number of allocated blocks
   226         * 
   227         *  This will enable/disable the tracking of the maximum number of
   228         *  allocations for a HeapMultiBufMP instance.  This maximum refers to the
   229         *  "all time" maximum number of allocations for the history of a 
   230         *  HeapMultiBufMP instance, not the current number of allocations.
   231         * 
   232         *  Tracking the maximum might adversely affect performance when allocating
   233         *  and/or freeing. If this feature is not needed, setting this to false
   234         *  avoids the performance penalty.
   235         */
   236        config Bool trackMaxAllocs = false;
   237         
   238    instance:
   239    
   240        /*! 
   241         *  GateMP used for critical region management of the shared memory 
   242         *
   243         *  Using the default value of NULL will result in use of the GateMP
   244         *  system gate for context protection.
   245         */
   246        config GateMP.Handle gate = null; 
   247    
   248        /*! @_nodoc
   249         *   by the open() call. No one else should touch this!
   250         */
   251        config Bool openFlag = false;
   252        
   253        /*!
   254         *  Use exact matching
   255         *
   256         *  Setting this flag will allow allocation only if the requested size
   257         *  is equal to (rather than less than or equal to) a buffer's block size.
   258         */
   259        config Bool exact = false;
   260        
   261        /*! 
   262         *  Name of this instance.
   263         *
   264         *  The name (if not NULL) must be unique among all HeapMultiBufMP
   265         *  instances in the entire system.  When creating a new
   266         *  heap, it is necessary to supply an instance name.
   267         */
   268        config String name = null;
   269    
   270        /*!
   271         *  Number of buckets in {@link #bucketEntries}
   272         *
   273         *  This parameter is required to create any instance.
   274         */
   275        config Int numBuckets = 0;
   276        
   277        /*!
   278         *  Bucket Entries
   279         * 
   280         *  The bucket entries are an array of {@link #Bucket}s whose values  
   281         *  correspond to the desired alignment, block size and length for each 
   282         *  buffer.  It is important to note that the alignments and sizes for each 
   283         *  buffer may be adjusted due to cache and alignment related constraints.  
   284         *  Buffer sizes are rounded up by their corresponding alignments.  Buffer 
   285         *  alignments themselves will assume the value of region cache alignment 
   286         *  size when the cache size is greater than the requested buffer alignment. 
   287         * 
   288         *  For example, specifying a bucket with {blockSize: 192, align: 256} will
   289         *  result in a buffer of blockSize = 256 and alignment = 256.  If cache 
   290         *  alignment is required, then a bucket of {blockSize: 96, align: 64} will 
   291         *  result in a buffer of blockSize = 128 and alignment = 128 (assuming 
   292         *  cacheSize = 128).
   293         */
   294        config Bucket bucketEntries[];
   295        
   296        /*! 
   297         *  Shared region ID
   298         *
   299         *  The index corresponding to the shared region from which shared memory
   300         *  will be allocated.
   301         */
   302        config UInt16 regionId = 0;
   303    
   304        /*! @_nodoc
   305         *  Physical address of the shared memory
   306         *
   307         *  This value can be left as 'null' unless it is required to place the
   308         *  heap at a specific location in shared memory.  If sharedAddr is null,
   309         *  then shared memory for a new instance will be allocated from the 
   310         *  heap belonging to the region identified by {@link #regionId}.
   311         */
   312        config Ptr sharedAddr = null;
   313    
   314    internal:
   315        
   316        /*! Used in the attrs->status field */
   317        const UInt32 CREATED = 0x05101920;
   318        
   319        /*! 
   320         *  This Params object is used for temporary storage of the
   321         *  module wide parameters that are for setting the NameServer instance.
   322         */
   323        metaonly config NameServer.Params nameSrvPrms;
   324    
   325        /*! slice and dice the buffer */
   326        Void postInit(Object *obj, Error.Block *eb);
   327        
   328        /*! 
   329         * Takes in modifiable array of bucket entries, performs an in-place sort
   330         * of the bucket entries, combines the entries as necessary, and returns
   331         * the new number of buckets in the combined entries
   332         */
   333        UInt processBuckets(Bucket *bucketEntries, Params *params, 
   334                            UInt16 regionId);
   335    
   336        /*! 
   337         * Add the block to the tail; index specifies the buffer number
   338         *
   339         * Precondition: inv obj->attrs->bucket[index]
   340         * Postcondition: wb obj->attrs->bucket[index] and wb the block
   341         */
   342        Void putTail(Object *obj, Int index, Elem *block);
   343        
   344        /*! 
   345         * Removes a block from the head and returns it; index specifies 
   346         * the buffer number. The block is invalidated before returned
   347         *
   348         * Precondition: inv obj->attrs->bucket[index]
   349         * Postcondition: wb obj->attrs->bucket[index]
   350         */
   351        Elem *getHead(Object *obj, Int index);
   352        
   353        /*! Needed for freelist */    
   354        @Opaque struct Elem {
   355            /* must be volatile for whole_program */
   356            volatile SharedRegion.SRPtr next;   
   357        };
   358        
   359        /*! Shared memory state for a single buffer. */
   360        struct BucketAttrs {
   361            SharedRegion.SRPtr  head;
   362            SharedRegion.SRPtr  tail;
   363            SharedRegion.SRPtr  baseAddr;
   364            Bits32              numFreeBlocks;
   365            Bits32              minFreeBlocks;
   366            Bits32              blockSize;
   367            Bits32              align;
   368            Bits32              numBlocks;
   369        }
   370        
   371        /*! Shared memory state for a HeapMultiBufMP instance */    
   372        struct Attrs {
   373            Bits32              status;         /* Created stamp                 */
   374            SharedRegion.SRPtr  gateMPAddr;     /* GateMP SRPtr                  */
   375            Bits32              numBuckets;     /* Number of buffers             */
   376            BucketAttrs         buckets[8]; /* Buffer attributes        */
   377            Bits16              exact;          /* 1 = exact matching, 0 = no    */     
   378        }
   379        
   380        struct Instance_State {
   381            Attrs               *attrs;         /* Shared state                  */
   382            GateMP.Handle       gate;           /* Gate for critical regions     */
   383            Ipc.ObjType         objType;        /* See enum ObjType              */
   384            Ptr                 nsKey;          /* Used to remove NS entry       */
   385            Bool                cacheEnabled;   /* Whether to do cache calls     */
   386            UInt16              regionId;       /* SharedRegion index            */
   387            SizeT               allocSize;      /* Shared memory allocated       */
   388            Char                *buf;           /* Local pointer to buf          */
   389            Bucket              bucketEntries[];/* Optimized bucketEntries       */
   390                                                /* NULL for dynamic instance     */
   391            UInt                numBuckets;     /* # of optimized entries        */
   392            Bool                exact;          /* Exact match flag              */
   393        };
   394        
   395        struct Module_State {
   396            NameServer.Handle   nameServer;
   397        };
   398    }
   399    /*
   400     *  @(#) ti.sdo.ipc.heaps; 1, 0, 0, 0,186; 8-10-2010 17:49:24; /db/vtree/library/trees/ipc/ipc-e23x/src/
   401     */
   402