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