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     *  ======== Types.xdc ========
    15     */
    16    
    17    package xdc.runtime;
    18    
    19    /*!
    20     *  ======== Types ========
    21     *  Basic constants and types
    22     *
    23     *  This module defines basic constants and types used throughout the
    24     *  `xdc.runtime` package and, in some cases, in every module.
    25     *
    26     *  The `{@link #Common$ Common$}` structure defined by the `Types` module
    27     *  is available for (or common to) all modules. Every field of the
    28     *  `Common$` structure is a configuration parameter that may be set within
    29     *  a configuration script for any module (not just the
    30     *  `xdc.runtime` modules). The fields of this structure are typically read
    31     *  by the modules in the `xdc.runtime` package at configuration time to
    32     *  control the generation of data structures that are embedded in the
    33     *  application and referenced by these modules at runtime.
    34     *
    35     *  Every module has a configuration parameter named
    36     *  `{@link #common$ common$}` that is of type `Common$`. This allows the user
    37     *  of any module to control the module's diagnostics, where its instances
    38     *  are allocated, how they are allocated, and (for gated modules) what
    39     *  gate it should use to protect critical sections.
    40     *
    41     *  @a(Examples)
    42     *  Configuration example: The following configuration script specifies
    43     *  that the instance objects managed by the `Memory` module in the
    44     *  `xdc.runtime` package should be placed in the ".fast" memory section
    45     *  and that `ENTRY` diagnostics should be available at runtime.
    46     *
    47     *  @p(code)
    48     *      var Memory = xdc.useModule('xdc.runtime.Memory");
    49     *      Memory.common$.instanceSection = ".fast";
    50     *      Memory.common$.diags_ENTRY = Diags.RUNTIME_OFF
    51     *  @p
    52     *
    53     *  Note that by setting `Memory.common$.diags_ENTRY` to `Diags.RUNTIME_OFF`
    54     *  we are both enabling `ENTRY` events and specifying that they are initially
    55     *  disabled; they must be explicitly enabled at runtime. See the
    56     *  `{@link Diags}` modules for additional information.
    57     */
    58    
    59    @CustomHeader
    60    @RomConsts
    61    
    62    
    63    module Types {
    64    
    65        /*!
    66         *  ======== ModuleId ========
    67         *  Unique module identifier
    68         *
    69         *  Module IDs are assigned at configuration time based in the set
    70         *  of modules that are "used" in the application.  So, although each
    71         *  module has a unique 16-bit ID at runtime this ID may vary between
    72         *  configurations of the application.
    73         *
    74         *  To save precious data space, module names are managed by the
    75         *  `{@link Text}` module and it is this table that is used to assign
    76         *  module IDs.  If the table is maintained on the target, the module ID
    77         *  is an "index" into this table; otherwise, the module ID is simply
    78         *  a unique integer less than the total number of modules in the
    79         *  application.
    80         *
    81         *  Although module IDs are not independent of an application's
    82         *  configuration, a module's ID may be compared to a runtime value
    83         *  symbolically.  Every module has a (generated) method that returns
    84         *  the module's ID; e.g., a module named `Task` has a method named
    85         *  `Task_Module_id()` which returns `Task`'s module ID.
    86         *
    87         *  @p(code)
    88         *      #include <xdc/runtime/Types.h>
    89         *      #include <ti/sysbios/knl/Task.h>
    90         *         :
    91         *      void checkId(Types_ModuleId modId) {
    92         *          if (Task_Module_id() == modId) {
    93         *              System_printf("Task module");
    94         *          }
    95         *      }
    96         *  @p
    97         */
    98        typedef Bits16 ModuleId;
    99    
   100        typedef Bits16 DiagsMask;
   101    
   102        /*!
   103         *  ======== Event ========
   104         *  `{@link ILogger}` event encoding
   105         *
   106         *  Whereas a `{@link Log#Event}` encodes an event ID and a mask, a
   107         *  `Types_Event` encodes the same event ID and the module ID of the
   108         *  module containing the call site that generated the `Types_Event`.
   109         */
   110        typedef Bits32 Event;
   111    
   112        /*!
   113         *  ======== getEventId ========
   114         *  Get event ID of the specified event
   115         *
   116         *  This method is used to get an ID that can be compared to other
   117         *  "known" IDs.  For example, after a `{@link #Event Types_Event}` is
   118         *  generated, the following code determines if the event
   119         *  corresponds to a `{@link Log#L_create}` event:
   120         *  @p(code)
   121         *      Bool isCreateEvent(Types_Event evt) {
   122         *          return (Log_getEventId(Log_L_create) == Types_getEventId(evt));
   123         *      }
   124         *  @p
   125         *
   126         *  @param(evt) an event created via `{@link #makeEvent}`
   127         *
   128         *  @a(returns) This function returns the event ID of a specified event.
   129         */
   130        @Macro RopeId getEventId(Event evt);
   131    
   132        /*!
   133         *  ======== getModuleId ========
   134         *  Get the module ID for the specified event
   135         *
   136         *  @param(evt) an event created via `{@link #makeEvent}`
   137         *
   138         *  @a(returns) This function returns the module ID of a specified event.
   139         */
   140        @Macro ModuleId getModuleId(Event evt);
   141    
   142        /*!
   143         *  ======== makeEvent ========
   144         *  Make an Event from an Event ID and a module ID
   145         *
   146         *  @param(id)          ID of the event itself
   147         *  @param(callSite)    the module from which this event originated
   148         *
   149         *  @a(returns) This function returns an event.
   150         */
   151        @Macro Event makeEvent(RopeId id, ModuleId callSite);
   152    
   153        /*!
   154         *  ======== EventId ========
   155         *  @_nodoc
   156         *
   157         *  Deprecated name for `Types.Event`; ids are often encoded as a field
   158         *  in the event itself.
   159         */
   160        typedef Event EventId;
   161    
   162        /*! @_nodoc */
   163        struct CordAddr__;
   164    
   165        /*! @_nodoc */
   166        typedef CordAddr__ *CordAddr;
   167    
   168        /*! @_nodoc */
   169        struct GateRef__;
   170    
   171        /*! @_nodoc */
   172        typedef GateRef__ *GateRef;
   173    
   174        /*! @_nodoc */
   175        typedef Bits16 RopeId;
   176    
   177        /*!
   178         *  ======== CreatePolicy ========
   179         *  Instance creation policy
   180         */
   181        enum CreatePolicy {
   182            STATIC_POLICY,  /*! static creation only; no runtime create/delete */
   183            CREATE_POLICY,  /*! dynamic creation, but no deletion */
   184            DELETE_POLICY   /*! dynamic creation and deletion */
   185        };
   186    
   187        /*!
   188         *  ======== OutputPolicy ========
   189         *  Destination file for module's functions
   190         */
   191        enum OutputPolicy {
   192            COMMON_FILE,    /*! functions are in the common C file */
   193            SEPARATE_FILE,  /*! module has its own separate file */
   194            NO_FILE         /*! functions are not generated */
   195        };
   196    
   197        /*!
   198         *  ======== Label ========
   199         *  Instance label struct
   200         *
   201         *  Label structures are used to provide human readable names for
   202         *  instance handles.
   203         *
   204         *  It is possible to initialize a `Label` from any instance handle.  All
   205         *  modules that support instances provide a method named
   206         *  `Mod_Handle_label()` which, given an instance handle and a pointer to
   207         *  a `Label` structure, initializes the structure with all available
   208         *  information.  For example, the following code fragment initializes a
   209         *  `Label` from an instance of the `HeapMin` module.
   210         *  @p(code)
   211         *      HeapMin_Handle heap;
   212         *      Types_Label label;
   213         *      HeapMin_Handle_label(heap, &label);
   214         *  @p
   215         *
   216         *  Unless you explicitly disable it, `{@link System#printf System_printf}`
   217         *  can be used to convert a pointer to a `Label` into an human readable
   218         *  "instance name".  Continuing with the example above, the following
   219         *  line can be used to print an instance's label.
   220         *  @p(code)
   221         *      System_printf("heap instance name: %$L\n", &label);
   222         *  @p
   223         *
   224         *  @see System#printf, System#extendedFormats
   225         *  @see Text#putLabel
   226         */
   227        struct Label {
   228            Ptr handle;         /*! instance object address */
   229            ModuleId modId;     /*! corresponding module id */
   230            String iname;       /*! name supplied during instance creation */
   231            Bool named;         /*! true, if `iname` is available */
   232        };
   233    
   234        /*!
   235         *  ======== Site ========
   236         *  Error site description struct
   237         *
   238         *  This structure describes the location of the line that raised
   239         *  an error.
   240         *
   241         *  @field(mod) the module id of the module containing the call site
   242         *  @field(file) the name of the file containing the call site or `NULL`;
   243         *               some call sites omit the file name to save data space.
   244         *  @field(line) the line number within the file named
   245         */
   246        struct Site {
   247            ModuleId mod;   /*! module id of this site */
   248            CString file;   /*! filename of this site */
   249            Int line;       /*! line number of this site */
   250        };
   251    
   252        /*!
   253         *  ======== Timestamp64 ========
   254         *  64-bit timestamp struct
   255         *
   256         *  Some platforms only support 32-bit timestamps.  In this case,
   257         *  the most significant 32-bits are always set to 0.
   258         */
   259        struct Timestamp64 {
   260            Bits32 hi;      /*! most significant 32-bits of timestamp */
   261            Bits32 lo;      /*! least significant 32-bits of timestamp */
   262        };
   263    
   264        /*! 
   265         *  ======== FreqHz ========
   266         *  Frequency-in-hertz struct
   267         */
   268        struct FreqHz {
   269            Bits32 hi;      /*! most significant 32-bits of frequency */
   270            Bits32 lo;      /*! least significant 32-bits of frequency */
   271        };
   272    
   273        /*!
   274         *  ======== RegDesc ========
   275         *  Registry module descriptor
   276         */
   277        struct RegDesc {
   278            RegDesc         *next;
   279            CString         modName;
   280            Types.ModuleId  id;
   281            DiagsMask       mask;
   282        };
   283    
   284        /*!
   285         *  ======== Common$ ========
   286         *  Common module config struct
   287         *
   288         *  Every module contains this structure during the configuration
   289         *  phase. The fields of this structure are set in configuration scripts
   290         *  and referenced by the modules in the `xdc.runtime` package. For default
   291         *  values of these fields, see `{@link Defaults}`.
   292         *
   293         *  @field(diags_ASSERT) The `{@link Diags#ASSERT}` bit of a module's
   294         *  diagnostics mask.
   295         *
   296         *  @field(diags_ENTRY) The `{@link Diags#ENTRY}` category of a module's
   297         *  diagnostics mask.
   298         *
   299         *  @field(diags_EXIT) The `{@link Diags#EXIT}` category of a module's
   300         *  diagnostics mask.
   301         *
   302         *  @field(diags_INTERNAL) The `{@link Diags#INTERNAL}` bit of a module's
   303         *  diagnostics mask.
   304         *
   305         *  @field(diags_LIFECYCLE) The `{@link Diags#LIFECYCLE}` category of a
   306         *  module's diagnostics mask.
   307         *
   308         *  @field(diags_STATUS) The `{@link Diags#STATUS}` category of a module's
   309         *  diagnostics mask.
   310         *
   311         *  @field(diags_USER1) The `{@link Diags#USER1}` category of a module's
   312         *  diagnostics mask.
   313         *
   314         *  @field(diags_USER2) The `{@link Diags#USER2}` category of a module's
   315         *  diagnostics mask.
   316         *
   317         *  @field(diags_USER3) The `{@link Diags#USER3}` category of a module's
   318         *  diagnostics mask.
   319         *
   320         *  @field(diags_USER4) The `{@link Diags#USER4}` category of a module's
   321         *  diagnostics mask.
   322         *
   323         *  @field(diags_USER5) The `{@link Diags#USER5}` category of a module's
   324         *  diagnostics mask.
   325         *
   326         *  @field(diags_USER6) The `{@link Diags#USER6}` category of a module's
   327         *  diagnostics mask.
   328         *
   329         *  @field(diags_USER7) The `{@link Diags#USER7}` category of a module's
   330         *  diagnostics mask. The bit for this category has been repurposed for the
   331         *  `{@link Diags#INFO}` category, so the use of USER7 has been deprecated.
   332         *
   333         *  @field(diags_INFO) The `{@link Diags#INFO}` category of a module's
   334         *  diagnostics mask.
   335         *
   336         *  @field(diags_USER8) The `{@link Diags#USER8}` category of a module's
   337         *  diagnostics mask. The bit for this category has been repurposed for the
   338         *  `{@link Diags#ANALYSIS}` category, so the use of USER8 has been
   339         *  deprecated.
   340         *
   341         *  @field(diags_ANALYSIS) The `{@link Diags#ANALYSIS}` category of a
   342         *  module's diagnostics mask.
   343         *
   344         *  @field(fxntab)
   345         *  This configuration parameter is only applicable to modules that
   346         *  inherit an interface and have instance objects.  Setting `fxntab`
   347         *  to `false` can save some data space but also prevents the
   348         *  application from using instance objects through abstract interfaces.
   349         *
   350         *  Function tables are used whenever it's necessary to call a module's
   351         *  methods via an abstract interface; e.g., the `{@link Memory}` module
   352         *  calls methods defined by the `{@link IHeap}` interface but there may
   353         *  be several distinct modules that implement this interface.  In order
   354         *  for this type of call to be possible, instance objects contain a
   355         *  reference to a function table containing the instance module's
   356         *  functions; the caller gets the module's function from the instance
   357         *  object and calls through a function pointer.  Every module that
   358         *  inherits an interface has such a table and modules that do not
   359         *  inherit an interface do not have a function table.
   360         *
   361         *  If this configuration parameter is set to `false`, the module's
   362         *  instance objects will NOT be initialized with a reference to their
   363         *  module's function table and, since the function table will not
   364         *  be referenced by the application, the resulting executable will be
   365         *  smaller.  However, if this parameter is `false` you must never
   366         *  attempt to use this module's instance objects via reference this
   367         *  module through an abstract interface.  Since this is often hard to
   368         *  determine, especially as an application evolves over time, you should
   369         *  only set this parameter to `false` when you are absolutely sure that
   370         *  the module's functions are always only being directly called and you
   371         *  need to absolutely minimize the data footprint of your application.
   372         *
   373         *  The default for this parameter is `true`.
   374         *
   375         *  @field(gate) A handle to the module-level `{@link IGateProvider}`
   376         *  instance to be used when this module calls functions from
   377         *  `{@link Gate}`
   378         *
   379         *  @field(gateParams) `Gate` parameters used by this module to create
   380         *  the gates used when this module calls 
   381         *  `{@link Gate#allocInstance() Gate_allocInstance}`
   382         *
   383         *  @field(instanceHeap) Identifies the heap from which this module
   384         *  should allocate memory.
   385         *
   386         *  @field(instanceSection) Identifies the section in which instances
   387         *  created by this module should be placed.
   388         *
   389         *  @field(logger) The handle of the logger instance used by the module.
   390         *  All log events generated by the module are routed to this logger
   391         *  instance. See `{@link ILogger}` for details on the logger interface.
   392         *  See `{@link LoggerBuf}` and `{@link LoggerSys}` for two examples of 
   393         *  logger modules provided by the `{@link xdc.runtime}` package.
   394         *
   395         *  @field(memoryPolicy) Specifies whether this module should allow
   396         *  static object creation only (`{@link #CreatePolicy STATIC_POLICY}`),
   397         *  dynamic object creation but not deletion
   398         *  (`{@link #CreatePolicy CREATE_POLICY}`), or both dynamic object
   399         *  creation and deletion (`{@link #CreatePolicy DELETE_POLICY}`).
   400         *
   401         *  @field(namedInstance) If set to `true`, each instance object is
   402         *  given an additional field to hold a string name that is used
   403         *  when displaying information about an instance. Setting this to
   404         *  `true` increases the size of the module's instance objects by a
   405         *  single word but improves the usability of tools that display
   406         *  instance objects.  If set to `false`, assignments of instance
   407         *  names are silently ignored.  This allows one to remove instance
   408         *  name support to save space without having to change any source code.
   409         *  See `{@link xdc.runtime.IInstance#name IInstance.name}` for details.
   410         *
   411         *  @field(namedModule) If set to `true`, this module's string name
   412         *  is retained on the target so that it can be displayed as part
   413         *  of `{@link Log}` and `{@link Error}` events. Setting this to `false`
   414         *  saves data space in the application at the expense of readability
   415         *  of log and error messages associated with this module.
   416         *
   417         *  Note: setting this to `false` also prevents one from controlling the
   418         *  module's diagnostics at runtime via `{@link Diags#setMask()}`.
   419         *  This method uses the module's name to lookup the module's
   420         *  diagnostics mask.  It is still possible to control the module's
   421         *  diagnostics at design-time from a configuration script.
   422         *
   423         *  @see Diags, Defaults
   424         */
   425        metaonly struct Common$ {
   426            Diags.Mode diags_ASSERT;    /*! module's Diags assert mode */
   427            Diags.Mode diags_ENTRY;     /*! module's function entry Diags mode */
   428            Diags.Mode diags_EXIT;      /*! module's function exit Diags mode */
   429            Diags.Mode diags_INTERNAL;  /*! module's internal assert mode */
   430            Diags.Mode diags_LIFECYCLE; /*! module's instance lifecycle mode */
   431            Diags.Mode diags_STATUS;    /*! module's errors and warnings */
   432            Diags.Mode diags_USER1;     /*! module's user1 Diags mode */
   433            Diags.Mode diags_USER2;     /*! module's user2 Diags mode */
   434            Diags.Mode diags_USER3;     /*! module's user3 Diags mode */
   435            Diags.Mode diags_USER4;     /*! module's user4 Diags mode */
   436            Diags.Mode diags_USER5;     /*! module's user5 Diags mode */
   437            Diags.Mode diags_USER6;     /*! module's user6 Diags mode */
   438            Diags.Mode diags_USER7;     /*! module's user7 Diags mode */
   439            Diags.Mode diags_INFO;      /*! module's informational event mode */
   440            Diags.Mode diags_USER8;     /*! module's user8 Diags mode */
   441            Diags.Mode diags_ANALYSIS;  /*! module's Diags analysis mode */
   442            Bool fxntab;                /*! @_nodoc enable function tables */
   443            IGateProvider.Handle gate;  /*! module's gate */
   444            Ptr gateParams;             /*! gate params for module created gates */
   445            IHeap.Handle instanceHeap;  /*! module's instance heap */
   446            String instanceSection;     /*! memory section for module's instances*/
   447            ILogger.Handle logger;      /*! module's logger */
   448            OutputPolicy outPolicy;     /*! destination file for module's code */
   449            CreatePolicy memoryPolicy;  /*! module's memory policy */
   450            Bool namedInstance;         /*! true => instances have string names */
   451            Bool namedModule;           /*! true => module's name is on target */
   452            Bool romPatchTable;         /*! @_nodoc */
   453        }
   454    
   455        /*!
   456         *  ======== RtaDecoderData ========
   457         *  @_nodoc
   458         *
   459         *  loggers
   460         *    name - Used to identify the logger in GUI
   461         *    bufferSym - For stop-mode; symbol at which the logger's entry
   462         *                buffer can be found
   463         *    bufferLen - For stop-mode; length of the logger's entry buffer in
   464         *                MAUs
   465         */
   466        @XmlDtd metaonly struct RtaDecoderData {
   467            String targetName;
   468            String binaryParser;
   469            String endian;
   470            Int bitsPerChar;
   471            Int argSize;
   472            Int eventSize;
   473            String dataTransportClassName;
   474            String controlTransportClassName;
   475            struct {
   476                String name;
   477                String type;
   478                Any metaArgs;
   479            } loggers[ ];
   480            struct {
   481                Int id;
   482                String logger;
   483                String diagsMask;
   484            } modMap[string];
   485            struct {
   486                Int id;
   487                String msg;
   488            } evtMap[string];
   489        };
   490    
   491        /*!
   492         *  ======== ViewInfo ========
   493         *  @_nodoc
   494         *  XGconf view descriptor.
   495         */
   496        metaonly struct ViewInfo {
   497            String viewType;
   498            String viewFxn;
   499            String fields[];
   500        }
   501    
   502    internal:
   503    
   504        typedef Bits32 LogEvent;
   505    
   506        typedef Void (*LoggerFxn0)(Ptr, LogEvent, ModuleId);
   507        typedef Void (*LoggerFxn1)(Ptr, LogEvent, ModuleId, IArg);
   508        typedef Void (*LoggerFxn2)(Ptr, LogEvent, ModuleId, IArg, IArg);
   509        typedef Void (*LoggerFxn4)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg);
   510        typedef Void (*LoggerFxn8)(Ptr, LogEvent, ModuleId, IArg, IArg, IArg, IArg,
   511                                   IArg, IArg, IArg, IArg);
   512    
   513        struct Vec {
   514            Int len;
   515            Ptr arr;
   516        };
   517    
   518        /*
   519         *  ======== Link ========
   520         *  Link used to maintain atomic linked lists
   521         */
   522        struct Link {
   523            Link *next;
   524            Link *prev;
   525        };
   526    
   527        /*
   528         *  ======== InstHdr ========
   529         *  Header for all runtime created instance objects
   530         */
   531        struct InstHdr {
   532            Link link;
   533        }
   534    
   535        /*
   536         *  ======== PrmsHdr ========
   537         *  Header for all _Params structures
   538         */
   539        struct PrmsHdr {
   540            SizeT size;     /* size of the entire parameter structure */
   541            Ptr self;       /* pointer to self; used to check params are init'd */
   542            Ptr modFxns;
   543            Ptr instPrms;
   544        }
   545    
   546        /*
   547         *  ======== Base ========
   548         *  Header for all module vtables
   549         */
   550        struct Base {
   551            //490928 const Base *base;     /* points to inherited interface base */
   552            Base *base;     /* points to inherited interface base */
   553        }
   554    
   555        /*
   556         *  ======== SysFxns ========
   557         *  Deprecated.  Use SysFxns2 instead
   558         */
   559        struct SysFxns {
   560            Ptr (*__create)(Ptr, SizeT, Ptr, const Ptr, SizeT, Error.Block*);
   561            Void (*__delete)(Ptr);
   562            Label *(*__label)(Ptr, Label *);
   563            ModuleId __mid;
   564        }
   565    
   566        /*
   567         *  ======== SysFxns2 ========
   568         *  System data embedded in module's vtable
   569         */
   570        struct SysFxns2 {
   571    
   572            /*
   573             *  ======== __create ========
   574             *  Signature of configuration generated module instance constructor
   575             *
   576             *  This function calls Core_createObject().
   577             *
   578             *  Params:
   579             *      Ptr           - pointer to inststance object
   580             *      SizeT         - size of instance object
   581             *      CPtr          - pointer to struct of required create args
   582             *      const UChar * - pointer to struct of default create parameters
   583             *      SizeT         - size of default params structure
   584             *      Error_Block * - caller's error block pointer
   585             */
   586            Ptr (*__create)(Ptr, SizeT, Ptr, const UChar *, SizeT, Error.Block *);
   587            // 490928 Ptr (*__create)(Ptr, SizeT, CPtr, const UChar *, SizeT, Error.Block *);
   588    
   589            Void (*__delete)(Ptr);
   590            Label *(*__label)(Ptr, Label *);
   591            ModuleId __mid;
   592        }
   593    }
   594    /*
   595     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:23; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   596     */
   597