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