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 outPolicy: Types.COMMON_FILE,
157 memoryPolicy: Types.DELETE_POLICY,
158 namedInstance: false,
159 namedModule: true,
160 romPatchTable: false,
161 };
162
163 /*!
164 * ======== noRuntimeCommon$ ========
165 * Defaults inherited by the target modules that do not need the runtime
166 * support.
167 *
168 * Modules for which the attribute `@NoRuntime` is set cannot use any
169 * functionality controlled by the parameters in their `common$`
170 * structures. For such modules, these parameters are set to the
171 * following values, and cannot be changed. This ensures that
172 * `@NoRuntime` modules not used in situations where the normal
173 * module runtime features are required.
174 */
175 metaonly readonly config Types.Common$ noRuntimeCommon$ = {
176 diags_ASSERT: Diags.ALWAYS_OFF,
177 diags_ENTRY: Diags.ALWAYS_OFF,
178 diags_EXIT: Diags.ALWAYS_OFF,
179 diags_INTERNAL: Diags.ALWAYS_OFF,
180 diags_LIFECYCLE: Diags.ALWAYS_OFF,
181 diags_STATUS: Diags.ALWAYS_OFF,
182 diags_USER1: Diags.ALWAYS_OFF,
183 diags_USER2: Diags.ALWAYS_OFF,
184 diags_USER3: Diags.ALWAYS_OFF,
185 diags_USER4: Diags.ALWAYS_OFF,
186 diags_USER5: Diags.ALWAYS_OFF,
187 diags_USER6: Diags.ALWAYS_OFF,
188 diags_USER7: Diags.ALWAYS_OFF,
189 diags_INFO: Diags.ALWAYS_OFF,
190 diags_USER8: Diags.ALWAYS_OFF,
191 diags_ANALYSIS: Diags.ALWAYS_OFF,
192 fxntab: false,
193 gate: null,
194 gateParams: null,
195 instanceHeap: null,
196 instanceSection: null,
197 logger: null,
198 outPolicy: Types.COMMON_FILE,
199 memoryPolicy: Types.STATIC_POLICY,
200 namedInstance: false,
201 namedModule: false,
202 romPatchTable: false,
203 };
204
205 /*!
206 * ======== getCommon ========
207 * Get a specified common parameter from a module
208 *
209 * Get the value of a member of the structure `common$` based on
210 * defaults and the current value of the parameter. If the current value
211 * of `param` is `undefined`, the function returns the default value
212 * for that parameter from `Default.common$`.
213 *
214 * @param(eb) module whose parameter is queried
215 *
216 * @param(param) string naming the queried parameter
217 *
218 * @a(returns)
219 * Returns the value of the parameter named `param` from the module
220 * `mod`.
221 */
222 metaonly Any getCommon(IModule.Module mod, String param);
223 };
224 225 226
227