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     *  ======== Defaults.xdc ========
    15     */
    16    
    17    package xdc.runtime;
    18    
    19    /*!
    20     *  ======== Defaults ========
    21     *  Default attributes inherited by all target modules
    22     *
    23     *  This module defines default values for `common$` structure. If other 
    24     *  modules do not set `common$` properties explicitly, these values will be
    25     *  used.
    26     */
    27    @RomConsts
    28    
    29    module Defaults {
    30    
    31        /*!
    32         *  ======== common$ ========
    33         *  Defaults inherited by all target modules
    34         *
    35         *  This structure defines the default values for the configuration
    36         *  parameters shared by all modules in a system.  Unless otherwise
    37         *  noted, setting one of the fields defined below will set the
    38         *  corresponding value for all modules in the system which have not
    39         *  been explicitly set; i.e., it will establish a default value for
    40         *  the parameter.
    41         *
    42         *  However, the modules from this package (`xdc.runtime`) are an
    43         *  exception. The values from `Default.common$` are not copied to
    44         *  `logger` and `diags_` properties of `common$` in `xdc.runtime`
    45         *  modules. The property `diags_ASSERT` is an exception to that exception.
    46         *  Its value from `Default.common$` is copied to all modules for which
    47         *  `diags_ASSERT` has not been explicitly set.
    48         *
    49         *  @a(diags_ASSERT)
    50         *  Enables asserts at runtime. Default is `ALWAYS_ON`
    51         *
    52         *  @a(diags_ENTRY)
    53         *  Enables entry trace for all functions. Default is `ALWAYS_OFF`
    54         *
    55         *  @a(diags_EXIT)
    56         *  Enables exit trace for all functions. Default is `ALWAYS_OFF`
    57         *
    58         *  @a(diags_INTERNAL)
    59         *  Enables internal asserts. Default is `ALWAYS_OFF`. When set to
    60         *  `ALWAYS_ON`, requires `diags_ASSERT` to be `ALWAYS_ON`.
    61         *
    62         *  @a(diags_LIFECYCLE)
    63         *  Enables logging of lifecycle events. These events are logged during 
    64         *  creates and deletes. Default is `ALWAYS_OFF`. 
    65         *
    66         *  @a(diags_STATUS)
    67         *  Enables logging of status events, such as error and warning events. 
    68         *  Default is `ALWAYS_ON`. Note that this does not mean that logging will
    69         *  occur by default--a logger instance must also be configured for the 
    70         *  module in order for events to be logged.
    71         *
    72         *  @a(diags_INFO)
    73         *  Enables logging of generic informational events. Default is 
    74         *  `ALWAYS_OFF`.
    75         *
    76         *  @a(diags_ANALYSIS)
    77         *  Enables logging of analysis events, such as benchmarking events. 
    78         *  Default is `ALWAYS_OFF`.
    79         *
    80         *  @a(diags_USER)
    81         *  Each `diags_USER` field controls a separate user-defined
    82         *  logging level. Default is `ALWAYS_OFF` for all `diags_USER` fileds.
    83         *
    84         *  @a(gate)
    85         *  Default gate used by all modules which are declared as being `@Gated`.
    86         *  By default, this parameter points to an instance of `{@link GateNull}`,
    87         *  which means there is no protection.
    88         *
    89         *  @a(gateParams)
    90         *  The default parameters used to create gates at runtime. See
    91         *  `{@link Types#Common$.gateParams}`.  Default is `null`.
    92         *
    93         *  @a(instanceHeap)
    94         *  Specify heap to be used for module instances. Default is `null`.
    95         *  If `instanceHeap` is `null`, instances will be allocated from
    96         *  the heap specified by `{@link Memory#defaultHeapInstance}`.
    97         *
    98         *  @a(instanceSection)
    99         *  Specify section to be used to place module instances. Default is
   100         *  `null`.
   101         *
   102         *  @a(logger)
   103         *  Default logger used by modules to write logs. By default there is 
   104         *  no logger.
   105         *
   106         *  @a(memoryPolicy)
   107         *  Used to specify type of application. `Types.STATIC_POLICY` is used when
   108         *  all objects are created statically. `Types.CREATE_POLICY` is used when 
   109         *  the application creates objects at runtime. `Types.DELETE_POLICY` is
   110         *  used when the application creates and deletes objects at runtime. This
   111         *  helps eliminate unwanted create and delete code.
   112         *
   113         *  @a(namedInstance)
   114         *  This parameter should be set to `true` if space needs to be allocated in
   115         *  instance objects for instance names. Allocating space for a name
   116         *  allows object view tools to display the names. The runtime functions
   117         *  `Mod_Handle_name()` and `Mod_Handle_label()` defined for each module
   118         *  `Mod` can be used to retrieve the name at runtime.
   119         *
   120         *  @a(namedModule)
   121         *  This field allows the name of the module to be retained on the target.
   122         *  Setting this to `false` will save space but will also prevent
   123         *  the target from being able to display the module names appearing
   124         *  in `Log` events and `Error`s.
   125         *
   126         *  Setting `namedModule` to `false` causes all modules, except for
   127         *  `{@link Memory}` and `{@link Main}` to be unnamed by default.  To
   128         *  eliminate the string names for these modules you must explicitly
   129         *  set their `common$.namedModule` parameters to `false`; without these
   130         *  two names, target-side display of error messages is somewhat cryptic.
   131         *
   132         *  @a(romPatchTable)
   133         *  Specify whether modules that are allocated to ROM are patchable.
   134         */
   135        override metaonly config Types.Common$ common$ = {
   136            diags_ASSERT:       Diags.ALWAYS_ON,
   137            diags_ENTRY:        Diags.ALWAYS_OFF,
   138            diags_EXIT:         Diags.ALWAYS_OFF,
   139            diags_INTERNAL:     Diags.ALWAYS_OFF,
   140            diags_LIFECYCLE:    Diags.ALWAYS_OFF,
   141            diags_STATUS:       Diags.ALWAYS_ON,
   142            diags_USER1:        Diags.ALWAYS_OFF,
   143            diags_USER2:        Diags.ALWAYS_OFF,
   144            diags_USER3:        Diags.ALWAYS_OFF,
   145            diags_USER4:        Diags.ALWAYS_OFF,
   146            diags_USER5:        Diags.ALWAYS_OFF,
   147            diags_USER6:        Diags.ALWAYS_OFF,
   148            diags_USER7:        Diags.ALWAYS_OFF,
   149            diags_INFO:         Diags.ALWAYS_OFF,
   150            diags_USER8:        Diags.ALWAYS_OFF,
   151            diags_ANALYSIS:     Diags.ALWAYS_OFF,
   152            fxntab:             true,
   153            gate:               null,
   154            gateParams:         null,
   155            instanceHeap:       null,
   156            instanceSection:    null,
   157            logger:             null,
   158            outPolicy:          Types.COMMON_FILE,
   159            memoryPolicy:       Types.DELETE_POLICY,
   160            namedInstance:      false,
   161            namedModule:        true,
   162            romPatchTable:      false,
   163        };
   164    
   165        /*! 
   166         *  ======== noRuntimeCommon$ ========
   167         *  Defaults inherited by the target modules that do not need the runtime
   168         *  support.
   169         *
   170         *  Modules for which the attribute `@NoRuntime` is set cannot use any
   171         *  functionality controlled by the parameters in their `common$`
   172         *  structures. For such modules, these parameters are set to the
   173         *  following values, and cannot be changed.  This ensures that
   174         *  `@NoRuntime` modules not used in situations where the normal
   175         *  module runtime features are required.
   176         */
   177        metaonly readonly config Types.Common$ noRuntimeCommon$ = {
   178            diags_ASSERT:       Diags.ALWAYS_OFF,
   179            diags_ENTRY:        Diags.ALWAYS_OFF,
   180            diags_EXIT:         Diags.ALWAYS_OFF,
   181            diags_INTERNAL:     Diags.ALWAYS_OFF,
   182            diags_LIFECYCLE:    Diags.ALWAYS_OFF,
   183            diags_STATUS:       Diags.ALWAYS_OFF,
   184            diags_USER1:        Diags.ALWAYS_OFF,
   185            diags_USER2:        Diags.ALWAYS_OFF,
   186            diags_USER3:        Diags.ALWAYS_OFF,
   187            diags_USER4:        Diags.ALWAYS_OFF,
   188            diags_USER5:        Diags.ALWAYS_OFF,
   189            diags_USER6:        Diags.ALWAYS_OFF,
   190            diags_USER7:        Diags.ALWAYS_OFF,
   191            diags_INFO:         Diags.ALWAYS_OFF,
   192            diags_USER8:        Diags.ALWAYS_OFF,
   193            diags_ANALYSIS:     Diags.ALWAYS_OFF,
   194            fxntab:             false,
   195            gate:               null,
   196            gateParams:         null,
   197            instanceHeap:       null,
   198            instanceSection:    null,
   199            logger:             null,
   200            outPolicy:          Types.COMMON_FILE,
   201            memoryPolicy:       Types.STATIC_POLICY,
   202            namedInstance:      false,
   203            namedModule:        false,
   204            romPatchTable:      false,
   205        };
   206    
   207        /*!
   208         *  ======== getCommon ========
   209         *  Get a specified common parameter from a module
   210         *
   211         *  Get the value of a member of the structure `common$` based on
   212         *  defaults and the current value of the parameter. If the current value
   213         *  of `param` is `undefined`, the function returns the default value
   214         *  for that parameter from `Default.common$`.
   215         *
   216         *  @param(eb)  module whose parameter is queried
   217         *
   218         *  @param(param)   string naming the queried parameter
   219         *
   220         *  @a(returns)
   221         *  Returns the value of the parameter named `param` from the module
   222         *  `mod`.
   223         */
   224        metaonly Any getCommon(IModule.Module mod, String param);
   225    };
   226    /*
   227     *  @(#) xdc.runtime; 2, 1, 0,0; 7-26-2016 11:46:12; /db/ztree/library/trees/xdc/xdc-B21/src/packages/
   228     */
   229