1    /* 
     2     *  Copyright (c) 2008 Texas Instruments. All rights reserved.
     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 to access the instances managed by Mod
    90     *
    91     *      // return heap used to create instances
    92     *      IHeap_Handle Mod_Object_heap();
    93     *
    94     *      // return count of static instances
    95     *      Int Mod_Object_count();
    96     *
    97     *      // get the i'th instance object of an array of instance objects
    98     *      //
    99     *      // If the array reference is NULL, get the i'th statically created
   100     *      // instance object.
   101     *      Mod_Object *Mod_Object_get(Mod_Object *array, Int i);
   102     *
   103     *      // get the first "live" runtime instance
   104     *      Mod_Object *Mod_Object_first();
   105     *
   106     *      // get the next "live" runtime instance
   107     *      Mod_Object *Mod_Object_next(Mod_Object *obj);
   108     *
   109     *  // methods that operate on instance handles
   110     *
   111     *      // fill in buf structure with instance's label info, returns buf
   112     *      Types_Label *Mod_Handle_label(Mod_Handle inst, Types_Label *buf);
   113     *
   114     *      // returns name of the instance inst, if it has one (otherwise NULL)
   115     *      String Mod_Handle_name(Mod_Handle inst);
   116     *
   117     *      // type-safe conversion of module handle to interface handle
   118     *      // Returns NULL if the conversion is not valid
   119     *      IMod_Handle Mod_Handle_to_pkgName_IMod(Mod_Handle inst);
   120     *
   121     *      // type-safe conversion of interface handle to module handle
   122     *      // Returns NULL if the conversion is not valid
   123     *      Mod_Handle Mod_Handle_from_pkgName_IMod(IMod_Handle inst);
   124     *
   125     *      // get the module that created the handle
   126     *      Mod_Module Mod_Handle_to_Module(Mod_Handle inst);
   127     *  @p
   128     */
   129    interface IModule {
   130    
   131        /*!
   132         *  ======== common$ ========
   133         *  Common module configuration parameters
   134         *
   135         *  All modules have this configuration parameter.  Its name
   136         *  contains the '$' character to ensure it does not conflict with
   137         *  configuration parameters declared by the module.  This allows
   138         *  new configuration parameters to be added in the future without
   139         *  any chance of breaking existing modules.
   140         */
   141        metaonly config Types.Common$ common$;
   142    
   143        /*!
   144         *  ======== viewNameMap$ ========
   145         *  Specifies the ROV views for the module.
   146         *  @_nodoc
   147         *
   148         *  Maps the view name to the RovView descriptor.
   149         */
   150        metaonly config Types.ViewInfo viewNameMap$[string];
   151    
   152        /*!
   153         *  ======== rovShowRawTab$ ========
   154         *  @_nodoc
   155         */
   156        metaonly config Bool rovShowRawTab$ = true;
   157    
   158        /*!
   159         *  ======== configNameMap$ ========
   160         *  @_nodoc
   161         */
   162        metaonly readonly config Types.ViewInfo configNameMap$[string] = [
   163            ["xdc.runtime/Memory", {viewType: "module", fields: [
   164                "common$.instanceHeap", "common$.instanceSection",
   165                "common$.memoryPolicy",
   166                "common$.namedModule", "common$.namedInstance",
   167                "common$.fxntab", "common$.romPatchTable"
   168            ]}],
   169            ["xdc.runtime/Diagnostics", {viewType: "module", fields: [
   170                "common$.logger",
   171                "common$.diags_ASSERT", "common$.diags_ENTRY",
   172                "common$.diags_EXIT", "common$.diags_INTERNAL",
   173                "common$.diags_LIFECYCLE", 
   174                "common$.diags_STATUS",
   175                "common$.diags_USER1",
   176                "common$.diags_USER2", "common$.diags_USER3",
   177                "common$.diags_USER4", "common$.diags_USER5",
   178                "common$.diags_USER6", "common$.diags_INFO",
   179                "common$.diags_ANALYSIS"
   180            ]}],
   181            ["xdc.runtime/Concurrency", {viewType: "module", fields: [
   182                "common$.gate", "common$.gateParams"
   183            ]}],
   184            ["xdc.runtime/Log Events", {viewType: "module", fields: [
   185                "Log.Event"]}],
   186            ["xdc.runtime/Log Events", {viewType: "instance", fields: [
   187                "Log.Event"]}],
   188            ["xdc.runtime/Asserts", {viewType: "module", fields: [
   189                "Assert.Id"]}],
   190            ["xdc.runtime/Asserts", {viewType: "instance", fields: [
   191                "Assert.Id"]}],
   192            ["xdc.runtime/Errors", {viewType: "module", fields: [
   193                "Error.Id"]}],
   194            ["xdc.runtime/Errors", {viewType: "instance", fields: [
   195                "Error.Id"]}],
   196        ];
   197    
   198        /*! @_nodoc */
   199        @System config Bits32 Module__diagsEnabled = 0;
   200        /*! @_nodoc */
   201        @System config Bits32 Module__diagsIncluded = 0;
   202        /*! @_nodoc */
   203        @System config Bits16* Module__diagsMask = null;
   204    
   205        /*! @_nodoc */
   206        @System config Ptr Module__gateObj = null;
   207        /*! @_nodoc */
   208        @System config Ptr Module__gatePrms = null;
   209    
   210        /*! @_nodoc */
   211        @System config Types.ModuleId Module__id = 0;
   212    
   213        /*! @_nodoc */
   214        @System config Bool Module__loggerDefined = false;
   215        /*! @_nodoc */
   216        @System config Ptr Module__loggerObj = null;
   217        /*! @_nodoc */
   218        @System config Types.LoggerFxn0 Module__loggerFxn0 = null;
   219        /*! @_nodoc */
   220        @System config Types.LoggerFxn1 Module__loggerFxn1 = null;
   221        /*! @_nodoc */
   222        @System config Types.LoggerFxn2 Module__loggerFxn2 = null;
   223        /*! @_nodoc */
   224        @System config Types.LoggerFxn4 Module__loggerFxn4 = null;
   225        /*! @_nodoc */
   226        @System config Types.LoggerFxn8 Module__loggerFxn8 = null;
   227    
   228        /*! @_nodoc */
   229        @System config Int Object__count = 0;
   230        /*! @_nodoc */
   231        @System config IHeap.Handle Object__heap = null;
   232        /*! @_nodoc */
   233        @System config SizeT Object__sizeof = 0;
   234        /*! @_nodoc */
   235        @System config Ptr Object__table = null;
   236    
   237        /*!
   238         *  ======== Handle__label ========
   239         *  Initialize a `Types.Label` from an instance handle
   240         *  @_nodoc
   241         *
   242         *  @param(obj) input instance handle
   243         *  @param(lab) pointer to `Label` struct to initialize from `obj`
   244         */
   245        @System Types.Label *Handle__label(Ptr obj, Types.Label *lab);
   246    
   247        /*! @_nodoc */
   248        @System Bool Module__startupDone();
   249    
   250        /*! @_nodoc
   251         *      __aa  - address of "required" create args structure
   252         *      __pa  - address of instance parameter structure
   253         *      __psz - sizeof of parameter structure
   254         *      __eb  - error block pointer
   255         *
   256         *  Currently, we keep Object__create and Object__delete because these are
   257         *  the functions used in virtual tables. All Object__create functions have
   258         *  the same signature so we can use SysFxns2 to define a type for virtual
   259         *  tables instead of using a different type for each module. we could
   260         *  delete these two functions.
   261         */
   262        //490928 @System Ptr Object__create(CPtr __aa,
   263        @System Ptr Object__create(CPtr __aa, const UChar *__pa, SizeT __psz,
   264                                   Error.Block *__eb);
   265    
   266        /*! @_nodoc */
   267        @System Void Object__delete(Ptr instp);
   268    
   269        /*! @_nodoc */
   270        @System Ptr Object__get(Ptr oarr, Int i);
   271    
   272        /*!
   273         *  ======== Object__first ========
   274         *  Return the first member of a list of dynamically created instances
   275         *  @_nodoc
   276         *
   277         *  @a(warning) The methods `first()` and `next()` are not thread-safe.
   278         *              The caller must ensure that no instances are removed or
   279         *              added while the list is being traversed.
   280         *
   281         *  @a(returns)
   282         *  Returns a handle to a first instance or `NULL` if there are no
   283         *  instances in the list.
   284         */
   285        @System Ptr Object__first();
   286    
   287        /*!
   288         *  ======== Object__next ========
   289         *  Return the next instance from the list of dynamically created instances
   290         *  @_nodoc
   291         *
   292         *  @param(obj) handle to a dynamically created instance
   293         *
   294         *  @a(returns)
   295         *  Returns a handle to a first instance or `NULL` if there are no
   296         *  instances in the list
   297         */
   298        @System Ptr Object__next(Ptr obj);
   299    
   300        /*! @_nodoc */
   301        @System Void Params__init(Ptr dst, const void *src, SizeT psz, SizeT isz);
   302    
   303        /*! @_nodoc */
   304        @System Bool Proxy__abstract();
   305    
   306        /*! @_nodoc */
   307        //490928 @System CPtr Proxy__delegate();
   308        @System CPtr Proxy__delegate();
   309    }
   310    /*
   311     *  @(#) xdc.runtime; 2, 1, 0,0; 2-8-2017 14:15:55; /db/ztree/library/trees/xdc/xdc-D05/src/packages/
   312     */
   313