1    /*
     2     * Copyright (c) 2013, 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     *  ======== HeapCallback.xdc ========
    34     */
    35    
    36    package ti.sysbios.heaps;
    37    
    38    import xdc.rov.ViewInfo;
    39    import xdc.runtime.Memory;
    40    
    41    /*!
    42     *  ======== HeapCallback ========
    43     *  A heap that calls user supplied callback functions
    44     *
    45     *  The HeapCallback module enables users to provide a custom heap
    46     *  implementation by providing callback functions that will be invoked
    47     *  by HeapCallback for the various heap management functions.
    48     *
    49     *  The user-supplied HeapCallback.initInstFxn is called during boot time to
    50     *  initialize any HeapCallback objects that were created in the .cfg file.
    51     *  The user-supplied HeapCallback.createInstFxn is called during runtime
    52     *  for any calls to HeapCallback_create().  Both of these functions return
    53     *  a context value (typically a pointer to an object managed by the
    54     *  user-supplied heap code).  This context value is passed to subsequent
    55     *  user allocInstFxn, freeInstFxn, etc. functions.
    56     *
    57     *  HeapCallback_alloc(), HeapCallback_free() and HeapCallback_getStats()
    58     *  call the user-supplied allocInstFxn, freeInstFxn and getStatsInstFxn
    59     *  functions with the context value returned by initInstFxn or createInstFxn.
    60     *
    61     *  HeapCallback_delete() calls the user-supplied instDeleteFxn with the
    62     *  context returned by the createInstFxn.
    63     *
    64     *  @a(Examples)
    65     *  Configuration example: The following XDC configuration statements
    66     *  creates a HeapCallback instance and plugs in the user defined functions.
    67     *
    68     *  @p(code)
    69     *  var HeapCallback = xdc.useModule('ti.sysbios.heaps.HeapCallback');
    70     *
    71     *  var params = new HeapCallback.Params();
    72     *  params.arg = 1;
    73     *  HeapCallback.create(params);
    74     *
    75     *  HeapCallback.initInstFxn = '&userInitFxn';
    76     *  HeapCallback.createInstFxn = '&userCreateFxn';
    77     *  HeapCallback.deleteInstFxn = '&userDeleteFxn';
    78     *  HeapCallback.allocInstFxn = '&userAllocFxn';
    79     *  HeapCallback.freeInstFxn = '&userFreeFxn';
    80     *  HeapCallback.getStatsInstFxn = '&userGetStatsFxn';
    81     *  HeapCallback.isBlockingInstFxn = '&userIsBlockingFxn';
    82     *
    83     *  @p
    84     */
    85    @ModuleStartup
    86    @InstanceFinalize
    87    module HeapCallback inherits xdc.runtime.IHeap {
    88    
    89        /*!  @_nodoc */
    90        metaonly struct BasicView {
    91            UArg        arg;
    92            UArg        context;
    93        }
    94    
    95        /*!  @_nodoc */
    96        metaonly struct ModuleView {
    97            String initInstFxn;
    98            String createInstFxn;
    99            String deleteInstFxn;
   100            String allocInstFxn;
   101            String freeInstFxn;
   102            String getStatsInstFxn;
   103            String isBlockingInstFxn;
   104        }
   105    
   106        /*!
   107         *  ======== rovViewInfo ========
   108         *  @_nodoc
   109         */
   110        @Facet
   111        metaonly config xdc.rov.ViewInfo.Instance rovViewInfo =
   112            xdc.rov.ViewInfo.create({
   113                viewMap: [
   114                    ['Basic',
   115                        {
   116                            type: ViewInfo.INSTANCE,
   117                            viewInitFxn: 'viewInitBasic',
   118                            structName: 'BasicView'
   119                        }
   120                    ],
   121                    ['Module',
   122                        {
   123                            type: xdc.rov.ViewInfo.MODULE,
   124                            viewInitFxn: 'viewInitModule',
   125                            structName: 'ModuleView'
   126                        }
   127                    ]
   128                ]
   129            });
   130    
   131        /*!
   132         *  ======== AllocInstFxn ========
   133         *  Instance alloc callback function signature
   134         *
   135         *  This function takes the context return from createInstFxn(), the
   136         *  size to be allocated and the align value.  The return value from
   137         *  this function is a pointer to the allocated memory block.
   138         */
   139        typedef Ptr (*AllocInstFxn)(UArg, SizeT, SizeT);
   140    
   141        /*!
   142         *  ======== CreateInstFxn ========
   143         *  Instance create callback function signature
   144         *
   145         *  {@link HeapCallback#arg} is passed as an argument to this function.
   146         *  The return value from this function (context) will be passed as an
   147         *  argument to the other instance functions.
   148         */
   149        typedef UArg (*CreateInstFxn)(UArg);
   150    
   151        /*!
   152         *  ======== DeleteInstFxn ========
   153         *  Instance delete callback function signature
   154         *
   155         *  The context returned from createInstFxn() is passed as an argument to
   156         *  this function.
   157         */
   158        typedef Void (*DeleteInstFxn)(UArg);
   159    
   160        /*!
   161         *  ======== FreeInstFxn ========
   162         *  Instance free callback function signature
   163         *
   164         *  This function takes the context returned by createInstFxn() and a
   165         *  pointer to the buffer to be freed and the size to be freed.
   166         */
   167        typedef Void (*FreeInstFxn)(UArg, Ptr, SizeT);
   168    
   169        /*!
   170         *  ======== GetStatsInstFxn ========
   171         *  Instance getStats callback function signature
   172         *
   173         *  This function takes the context returned by createInstFxn() and a
   174         *  pointer to a memory stats object.
   175         */
   176        typedef Void (*GetStatsInstFxn)(UArg, Memory.Stats *);
   177    
   178        /*!
   179         *  ======== InitInstFxn ========
   180         *  Instance init callback function signature
   181         *
   182         *  `{@link HeapCallback#arg} is passed as an argument to this function.
   183         *  The return value from this function (context) will passed as an
   184         *  argument to the other instance functions.
   185         */
   186        typedef UArg (*InitInstFxn)(UArg);
   187    
   188        /*!
   189         *  ======== IsBlockingInstFxn ========
   190         *  Instance isblocking callback function signature
   191         *
   192         *  The context return from createInstFxn() is passed as an argument to
   193         *  this function. The return value is 'TRUE' or 'FALSE'.
   194         */
   195        typedef Bool (*IsBlockingInstFxn)(UArg);
   196    
   197        /*!
   198         *  ======== allocInstFxn ========
   199         *  User supplied instance alloc function
   200         *
   201         *  This function is called when the `{@link HeapCallback#alloc}` is
   202         *  called.
   203         *
   204         *  This parameter is configured with a default alloc function. The
   205         *  default alloc function returns NULL.
   206         */
   207        config AllocInstFxn allocInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultAlloc';
   208    
   209        /*!
   210         *  ======== createInstFxn ========
   211         *  User supplied instance create function
   212         *
   213         *  This function is called when the `{@link HeapCallback#create}` is
   214         *  called.
   215         *
   216         *  This parameter is configured with a default create function.
   217         *  The default create function returns 0.
   218         */
   219        config CreateInstFxn createInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultCreate';
   220    
   221        /*!
   222         *  ======== deleteInstFxn ========
   223         *  User supplied instance delete function
   224         *
   225         *  This function is called when the `{@link HeapCallback#delete}` is
   226         *  called.
   227         *
   228         *  This parameter is configured with a default delete function.
   229         */
   230        config DeleteInstFxn deleteInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultDelete';
   231    
   232        /*!
   233         *  ======== freeInstFxn ========
   234         *  User supplied instance free function
   235         *
   236         *  This function is called when the `{@link HeapCallback#free}` is
   237         *  called.
   238         *
   239         *  This parameter is configured with a default free function.
   240         */
   241        config FreeInstFxn freeInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultFree';
   242    
   243        /*!
   244         *  ======== getStatsInstFxn ========
   245         *  User supplied getStat function
   246         *
   247         *  This function is called when the `{@link HeapCallback#getStat}` is
   248         *  called.
   249         *
   250         *  This parameter is configured with a default getStats function.
   251         *  The default getStats function does not make any changes to stats
   252         *  structure.
   253         */
   254        config GetStatsInstFxn getStatsInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultGetStats';
   255    
   256        /*!
   257         *  ======== initInstFxn ========
   258         *  User supplied init function
   259         *
   260         *  This function is called in Module startup for statically created
   261         *  instances.  The user-supplied function must not do any memory
   262         *  allocations or call any module create functions (e.g.,
   263         *  Semaphore_create()).
   264         *
   265         *  This parameter is configured with a default init function.  The
   266         *  default init function returns NULL.
   267         */
   268        config InitInstFxn initInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultInit';
   269    
   270        /*!
   271         *  ======== isBlockingInstFxn ========
   272         *  User supplied isBlocking function
   273         *
   274         *  This function is called when the `{@link HeapCallback#isBlocking}` is
   275         *  called.
   276         *
   277         *  This parameter is configured with a default isBlocking function.  The
   278         *  default isBlocking returns FALSE.
   279         */
   280        config IsBlockingInstFxn isBlockingInstFxn = '&ti_sysbios_heaps_HeapCallback_defaultIsBlocking';
   281    
   282    instance:
   283    
   284        /*!
   285         *  ======== create ========
   286         *  Create a `HeapCallback` Heap instance
   287         */
   288        create();
   289    
   290        /*!
   291         *  ======== getContext ========
   292         *  Get the context returned from user supplied create function
   293         */
   294        UArg getContext();
   295    
   296        /*!
   297         *  ======== arg ========
   298         *  User supplied argument for the user supplied create function.
   299         *
   300         *  This user supplied argument will be passed back as an argument to the
   301         *  `createInstFxn` function. It can be used by the
   302         *  `{@link HeapCallback#createInstFxn}` function at runtime to
   303         *  differentiate between the multiple Heap instances configured in the
   304         *  user config script.
   305         *
   306         *  The user can skip configuring this argument. In such a case, the
   307         *  default value `0` will be passed back as an argument to the
   308         *  `createInstFxn` function.
   309         */
   310        config UArg arg = 0;
   311    
   312    internal:   /* not for client use */
   313    
   314        struct Instance_State {
   315            UArg context;       /* context returned from createInstFxn */
   316            UArg arg;           /* argument to createInstFxn */
   317        };
   318    }