1    /* 
     2     *  Copyright (c) 2008-2020 Texas Instruments Incorporated
     3     *  This program and the accompanying materials are made available under the
     4     *  terms of the Eclipse Public License v1.0 and Eclipse Distribution License
     5     *  v. 1.0 which accompanies this distribution. The Eclipse Public License is
     6     *  available at http://www.eclipse.org/legal/epl-v10.html and the Eclipse
     7     *  Distribution License is available at
     8     *  http://www.eclipse.org/org/documents/edl-v10.php.
     9     *
    10     *  Contributors:
    11     *      Texas Instruments - initial implementation
    12     * */
    13    /*
    14     *  ======== IModule.xdc ========
    15     */
    16    
    17    /*!
    18     *  ======== IModule ========
    19     *  Base interface for all modules
    20     *
    21     *  All modules share a common set of configuration parameters and methods.
    22     *
    23     *  @a(internal)
    24     *  This section provides a terse summary of the methods provided by every
    25     *  module for use within the module's implementation.  Each method's
    26     *  prototype is shown along with a brief summary of its behavior.
    27     *  These methods are declared in the module's internal header which should
    28     *  always be included in any file referencing these functions.  For a
    29     *  module named `Mod` the following statement includes this header.
    30     *  @p(code)
    31     *      #include "package/internal/Mod.xdc.h"
    32     *  @p
    33     *
    34     *  In the prototypes below, `Mod` refers to the module being implemented,
    35     *  `embeddedObj` is the name of field in the module's state structure that
    36     *  is either an embedded object field or an array of such objects, and
    37     *  `fld` is the name of a field declared in the module's state structure.
    38     *
    39     *  @p(code)
    40     *  // enter the module's gate
    41     *  IArg Mod_Module_enter(Gate_Handle gate);
    42     *
    43     *  // leave the module's gate
    44     *  Mod_Module_leave(Gate_Handle, IArg);
    45     *
    46     *  // return a pointer to the embeddedObj field
    47     *  Ptr Mod_Module_State_embeddedObj();
    48     *
    49     *  // the value of the fld field of the module's state structure
    50     *  Mod_module->fld;    // fld is declared in module's .xdc file
    51     *  @p
    52     *
    53     *  @a(external)
    54     *  This section provides a terse summary of the methods provided by every
    55     *  module for use by an application or other modules.  Each method's
    56     *  prototype is shown along with a brief summary of its behavior.
    57     *  These methods are declared in the module's header which should always
    58     *  be included in any file referencing these functions.  For a module named
    59     *  `Mod` in the package named `a.b.c`, the following statement includes this
    60     *  header.
    61     *  @p(code)
    62     *      #include <a/b/c/Mod.h>
    63     *  @p
    64     *
    65     *  In the prototypes below, `IMod` referes to some interface, `Mod` refers to
    66     *  a module that (optionally) inherits from `IMod`, and `pkgName` is the
    67     *  name of the package containing the interface `IMod`.
    68     *  @p(code)
    69     *
    70     *  // methods to operate on modules
    71     *
    72     *      // return heap associated with this module
    73     *      IHeap_Handle Mod_Module_heap();
    74     *
    75     *      // get Mod's module ID
    76     *      Types_ModuleId Mod_Module_id();
    77     *
    78     *      // return TRUE if Mod's startup is complete
    79     *      Bool Mod_Module_startupDone();
    80     *
    81     *      // type-safe conversion from an interface to an inheriting module
    82     *      // Returns NULL if the conversion is not valid
    83     *      Mod_Handle Mod_Handle_downCast(IMod_Handle handle);
    84     *
    85     *      // type-safe conversion from a module to an interface it inherits from
    86     *      // Returns NULL if the conversion is not valid
    87     *      IMod_Handle Mod_Handle_upCast(Mod_Module_Handle handle);
    88     *
    89     *  // methods that create and destruct runtime Mod instances
    90     *
    91     *      // create a heap-based runtime instance
    92     *      // The number and type of other parameters is module-specific
    93     *      Mod_Handle Mod_create( ..., Mod_Params *prms, Error_Block *eb)
    94     *
    95     *      // destroy a heap-based runtime instance
    96     *      // Can be safely called only for instances created by Mod_create()
    97     *      Void Mod_delete(Mod_Handle *hPtr)
    98     *
    99     *      // create a stack-based or a static runtime instance
   100     *      // The number and type of other parameters is module-specific
   101     *      Void Mod_construct(Mod_Struct *obj, ..., Mod_Params *prms, Error_Block *eb)
   102     *
   103     *      // destroy a stack-based or a static runtime instance
   104     *      // Can be safely called only for instances created by Mod_construct()
   105     *      Void Mod_destruct(Mod_Struct *obj)
   106     *
   107     *  // methods to access the instances managed by Mod
   108     *
   109     *      // return heap used to create instances
   110     *      IHeap_Handle Mod_Object_heap();
   111     *
   112     *      // return count of static instances
   113     *      Int Mod_Object_count();
   114     *
   115     *      // get the i'th instance object of an array of instance objects
   116     *      //
   117     *      // If the array reference is NULL, get the i'th statically created
   118     *      // instance object.
   119     *      Mod_Object *Mod_Object_get(Mod_Object *array, Int i);
   120     *
   121     *      // get the first "live" runtime instance
   122     *      Mod_Object *Mod_Object_first();
   123     *
   124     *      // get the next "live" runtime instance
   125     *      Mod_Object *Mod_Object_next(Mod_Object *obj);
   126     *
   127     *  // methods that operate on instance handles
   128     *
   129     *      // fill in buf structure with instance's label info, returns buf
   130     *      Types_Label *Mod_Handle_label(Mod_Handle inst, Types_Label *buf);
   131     *
   132     *      // returns name of the instance inst, if it has one (otherwise NULL)
   133     *      String Mod_Handle_name(Mod_Handle inst);
   134     *
   135     *      // type-safe conversion of module handle to interface handle
   136     *      // Returns NULL if the conversion is not valid
   137     *      IMod_Handle Mod_Handle_to_pkgName_IMod(Mod_Handle inst);
   138     *
   139     *      // type-safe conversion of interface handle to module handle
   140     *      // Returns NULL if the conversion is not valid
   141     *      Mod_Handle Mod_Handle_from_pkgName_IMod(IMod_Handle inst);
   142     *
   143     *      // get the module that created the handle
   144     *      Mod_Module Mod_Handle_to_Module(Mod_Handle inst);
   145     *  @p
   146     */
   147    interface IModule {
   148    
   149        /*!
   150         *  ======== common$ ========
   151         *  Common module configuration parameters
   152         *
   153         *  All modules have this configuration parameter. Its name contains the '$'
   154         *  character to ensure it does not conflict with configuration parameters
   155         *  declared by the module. This allows new configuration parameters to be
   156         *  added in the future without any chance of breaking existing modules.
   157         */
   158        metaonly config Types.Common$ common$;
   159    
   160        /*!
   161         *  ======== viewNameMap$ ========
   162         *  Specifies the ROV views for the module.
   163         *  @_nodoc
   164         *
   165         *  Maps the view name to the RovView descriptor.
   166         */
   167        metaonly config Types.ViewInfo viewNameMap$[string];
   168    
   169        /*!
   170         *  ======== rovShowRawTab$ ========
   171         *  @_nodoc
   172         */
   173        metaonly config Bool rovShowRawTab$ = true;
   174    
   175        /*!
   176         *  ======== configNameMap$ ========
   177         *  @_nodoc
   178         */
   179        metaonly readonly config Types.ViewInfo configNameMap$[string] = [
   180            ["xdc.runtime/Memory", {viewType: "module", fields: [
   181                "common$.instanceHeap", "common$.instanceSection",
   182                "common$.memoryPolicy",
   183                "common$.namedModule", "common$.namedInstance",
   184                "common$.fxntab", "common$.romPatchTable"
   185            ]}],
   186            ["xdc.runtime/Diagnostics", {viewType: "module", fields: [
   187                "common$.logger",
   188                "common$.diags_ASSERT", "common$.diags_ENTRY",
   189                "common$.diags_EXIT", "common$.diags_INTERNAL",
   190                "common$.diags_LIFECYCLE", 
   191                "common$.diags_STATUS",
   192                "common$.diags_USER1",
   193                "common$.diags_USER2", "common$.diags_USER3",
   194                "common$.diags_USER4", "common$.diags_USER5",
   195                "common$.diags_USER6", "common$.diags_INFO",
   196                "common$.diags_ANALYSIS"
   197            ]}],
   198            ["xdc.runtime/Concurrency", {viewType: "module", fields: [
   199                "common$.gate", "common$.gateParams"
   200            ]}],
   201            ["xdc.runtime/Log Events", {viewType: "module", fields: [
   202                "Log.Event"]}],
   203            ["xdc.runtime/Log Events", {viewType: "instance", fields: [
   204                "Log.Event"]}],
   205            ["xdc.runtime/Asserts", {viewType: "module", fields: [
   206                "Assert.Id"]}],
   207            ["xdc.runtime/Asserts", {viewType: "instance", fields: [
   208                "Assert.Id"]}],
   209            ["xdc.runtime/Errors", {viewType: "module", fields: [
   210                "Error.Id"]}],
   211            ["xdc.runtime/Errors", {viewType: "instance", fields: [
   212                "Error.Id"]}],
   213        ];
   214    
   215        /*! @_nodoc */
   216        @System config Bits32 Module__diagsEnabled = 0;
   217        /*! @_nodoc */
   218        @System config Bits32 Module__diagsIncluded = 0;
   219        /*! @_nodoc */
   220        @System config Bits16* Module__diagsMask = null;
   221    
   222        /*! @_nodoc */
   223        @System config Ptr Module__gateObj = null;
   224        /*! @_nodoc */
   225        @System config Ptr Module__gatePrms = null;
   226    
   227        /*! @_nodoc */
   228        @System config Types.ModuleId Module__id = 0;
   229    
   230        /*! @_nodoc */
   231        @System config Bool Module__loggerDefined = false;
   232        /*! @_nodoc */
   233        @System config Ptr Module__loggerObj = null;
   234        /*! @_nodoc */
   235        @System config Types.LoggerFxn0 Module__loggerFxn0 = null;
   236        /*! @_nodoc */
   237        @System config Types.LoggerFxn1 Module__loggerFxn1 = null;
   238        /*! @_nodoc */
   239        @System config Types.LoggerFxn2 Module__loggerFxn2 = null;
   240        /*! @_nodoc */
   241        @System config Types.LoggerFxn4 Module__loggerFxn4 = null;
   242        /*! @_nodoc */
   243        @System config Types.LoggerFxn8 Module__loggerFxn8 = null;
   244    
   245        /*! @_nodoc */
   246        @System config Int Object__count = 0;
   247        /*! @_nodoc */
   248        @System config IHeap.Handle Object__heap = null;
   249        /*! @_nodoc */
   250        @System config SizeT Object__sizeof = 0;
   251        /*! @_nodoc */
   252        @System config Ptr Object__table = null;
   253    
   254        /*!
   255         *  ======== Handle__label ========
   256         *  Initialize a `Types.Label` from an instance handle
   257         *  @_nodoc
   258         *
   259         *  @param(obj) input instance handle
   260         *  @param(lab) pointer to `Label` struct to initialize from `obj`
   261         */
   262        @System Types.Label *Handle__label(Ptr obj, Types.Label *lab);
   263    
   264        /*! @_nodoc */
   265        @System Bool Module__startupDone();
   266    
   267        /*! @_nodoc
   268         *      aa  - address of "required" create args structure
   269         *      pa  - address of instance parameter structure
   270         *      psz - sizeof of parameter structure
   271         *      eb  - error block pointer
   272         *
   273         *  Currently, we keep Object__create and Object__delete because these are
   274         *  the functions used in virtual tables. All Object__create functions have
   275         *  the same signature so we can use SysFxns2 to define a type for virtual
   276         *  tables instead of using a different type for each module. we could
   277         *  delete these two functions.
   278         */
   279        @System Ptr Object__create(CPtr aa, const UChar *pa, SizeT psz,
   280                                   Error.Block *eb);
   281    
   282        /*! @_nodoc */
   283        @System Void Object__delete(Ptr instp);
   284    
   285        /*! @_nodoc */
   286        @System Ptr Object__get(Ptr oarr, Int i);
   287    
   288        /*!
   289         *  ======== Object__first ========
   290         *  Return the first member of a list of dynamically created instances
   291         *  @_nodoc
   292         *
   293         *  @a(warning) The methods `first()` and `next()` are not thread-safe.
   294         *              The caller must ensure that no instances are removed or
   295         *              added while the list is being traversed.
   296         *
   297         *  @a(returns)
   298         *  Returns a handle to a first instance or `NULL` if there are no
   299         *  instances in the list.
   300         */
   301        @System Ptr Object__first();
   302    
   303        /*!
   304         *  ======== Object__next ========
   305         *  Return the next instance from the list of dynamically created instances
   306         *  @_nodoc
   307         *
   308         *  @param(obj) handle to a dynamically created instance
   309         *
   310         *  @a(returns)
   311         *  Returns a handle to a first instance or `NULL` if there are no
   312         *  instances in the list
   313         */
   314        @System Ptr Object__next(Ptr obj);
   315    
   316        /*! @_nodoc */
   317        @System Void Params__init(Ptr dst, const void *src, SizeT psz, SizeT isz);
   318    
   319        /*! @_nodoc */
   320        @System Bool Proxy__abstract();
   321    
   322        /*! @_nodoc */
   323        @System CPtr Proxy__delegate();
   324    }
   325    /*
   326     *  @(#) xdc.runtime; 2, 1, 0,0; 10-3-2020 15:24:56; /db/ztree/library/trees/xdc/xdc-K04/src/packages/
   327     */
   328