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 @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 228
229