1 2 3 4 5 6 7 8 9 10 11
12 13 14
15 package xdc.cfg;
16
17 /*!
18 * ======== Program ========
19 * The Program object for the configuration object model.
20 *
21 * This module defines the "root" of the configuration object model; all
22 * "top-level" configuration settings for the executable are provided by
23 * this object. Program configuration scripts reference this module via the
24 * global variable `Program`; i.e., `Program` is implicitly initialized as
25 * follows:
26 * @p(code)
27 * var Program = xdc.useModule('xdc.cfg.Program');
28 * @p
29 *
30 * After a configuration script completes successfully, the following files
31 * are generated:
32 * @p(nlist)
33 * - package/cfg/<exe_name>.c
34 * - package/cfg/<exe_name>.xdl
35 * @p
36 * where `<exe_name>` is the name of the executable with the final '.'
37 * character replaced with an '_'.
38 *
39 * The generated C file contains code and data from each module used by the
40 * program and must be compiled and linked with the other sources to
41 * produce the final executable. The generated linker command file must also
42 * be added during this final link step.
43 *
44 * The linker command file is produced by expanding a template
45 * provided by the platform specifed during configuration and contains
46 * hardware and compiler specific directives required by the target modules
47 * that are part of the program's configuration. This template expands
48 * other templates specified by each imported package's
49 * `{@link xdc.IPackage#getSects getSects}` method, for example. This allows
50 * each package participating in the configuration executable to
51 * automatically contribute a portion of the executable's linker command
52 * file.
53 *
54 * You can modify or augment the contents of this file via
55 * `{@link xdc.cfg.Program#sectionsExclude sectionsExclude}` and
56 * `{@link xdc.cfg.Program#sectionsTemplate sectionsTemplate}`. It is even
57 * possible to completely replace the template used to generate this file via
58 * `{@link xdc.cfg.Program#linkTemplate linkTemplate}`. These configuration
59 * options provide the user complete control of the linker command file
60 */
61
62 @Template("./Program.xdt")
63
64 metaonly module Program {
65
66 /*!
67 * ======== GenerationOptions ========
68 * Options that control the files generated as part of program
69 * configuration.
70 *
71 * @field(debuggerFiles) If set to `true` in a configuration script,
72 * debugger project files will be generated as part of the
73 * configuration step. If set to `false`, these files will not
74 * be generated.
75 *
76 * If it is not set (or set to undefined) and the environment
77 * variable `environment["xdc.cfg.gen.debuggerFiles"]` is
78 * non-`null`, then the default value of this parameter is taken
79 * to be the value of the following expression:
80 * @p(code)
81 * environment["xdc.cfg.gen.debuggerFiles"] == "true"
82 * @p
83 * This makes it is possible to enable the generation of
84 * debugger project files from build scripts by passing
85 * the option `-Dxdc.cfg.gen.debuggerFiles=true` to the
86 * configuration tool (see
87 * `{@link xdc.bld.Executable#Attrs.xsopts}` or
88 * `{@link xdc.bld.PackageContents#Attrs.xsopts}`).
89 *
90 * Finally, if `debuggerFiles` is not set (or set to `undefined`)
91 * and the environment variable above is not defined,
92 * the generation of debugger project files occurs only if
93 * `{@link xdc.cfg.Program#build.profile}` contains
94 * the string `"debug"`. So, unless otherwise specified, debug
95 * profiles result in debugger project files being generated.
96 */
97 struct GenerationOptions {
98 Bool debuggerFiles; /*! if `true`, generate debugger "project" files */
99 };
100
101 /*!
102 * ======== SectionSpec ========
103 * Map that instructs the linker where to place output sections.
104 *
105 * This structure contains some fields that are specific to TI targets.
106 * On non-TI targets, such fields are ignored.
107 *
108 * @field(runSegment) Defines the memory segment where the section is
109 * to be run.
110 *
111 * @field(loadSegment) Defines the memory segment where the section is
112 * to be loaded. If 'runSegment' or 'loadSegment' is defined,
113 * but not both, the linker is instructed to use the defined
114 * field as the load and run allocation for the section.
115 *
116 * @field(runAddress) Defines the memory address where the section is
117 * to be run. It is an error if both 'runSegment' and 'runAddress'
118 * are specified.
119 *
120 * @field(loadAddress) Defines the memory address where the section is
121 * to be loaded. It is an error if both 'loadSegment' and
122 * 'loadAddress' are specified. If 'runAddress' or 'loadAddress'
123 * is defined, but not both, the linker is instructed to use the
124 * defined field as the load and run address for the section.
125 *
126 * @field(runAlign) If runSegment is specified, runAlign determines the
127 * alignment. It is an error if both 'runAlign' and 'runAddress'
128 * are specified.
129 *
130 * @field(loadAlign) If runSegment is specified, runAlign determins the
131 * alignment. It is an error if both 'loadAlign' and 'loadAddress'
132 * are specified.
133 *
134 * @field(type) Defines flags for special section types (COPY, DSECT,
135 * NOLOAD).
136 *
137 * @field(fill) Defines the value to initialize an uninitialized
138 * section.
139 */
140 struct SectionSpec {
141 String runSegment; /*! segment where section contents are run */
142 String loadSegment; /*! segment where section contents are loaded */
143 UInt runAddress; /*! start address of section when run */
144 UInt loadAddress; /*! start address of section when loaded */
145 UInt runAlign; /*! alignment of section within runSegment */
146 UInt loadAlign; /*! alignment of section within loadSegment */
147 String type; /*! target-specific flags */
148 UInt fill; /*! fill value */
149 };
150
151 /*!
152 * ======== gen ========
153 * Generation options for this executable
154 *
155 * This configuration parameter allows the program configuration script
156 * to control (to some extent) what files are generated as part of the
157 * configuration process.
158 */
159 config GenerationOptions gen;
160
161 /*!
162 * ======== globalSection ========
163 * UNDER CONSTRUCTION
164 * @_nodoc
165 *
166 * Section where `{@link #globals}` are placed.
167 *
168 * All globals specified in the application configuration file
169 * are placed into this section.
170 *
171 * The default is `null`, which means the `{@link #dataSection}` is used.
172 */
173 config String globalSection = null;
174
175 /*!
176 * ======== sysStack ========
177 * The size of the executable's initial system stack
178 *
179 * On architectures that maintain a separate "system stack" in addition
180 * to the normal `{@link #stack}`, this parameter sets its initial size
181 * (in units of chars). This parameter is ignored for those
182 * architectures for which there is just a single stack; in other
183 * words, almost all known architectures.
184 *
185 * This parameter is used on later generation TI/C55 16-bit DSPs where,
186 * in order to compatibly support 24-bit addresses, a separate
187 * system call/return stack that stores the upper address bits is
188 * employed.
189 */
190 config UInt sysStack = 0x1000;
191
192 /*!
193 * ======== stack ========
194 * The size of the executable's initial stack
195 *
196 * On platforms that enable control of the initial stack size (the
197 * stack that exists immediately after reset), this parameter specifies
198 * its initial size (in units of chars).
199 */
200 config UInt stack = 0x1000;
201
202 /*!
203 * ======== heap ========
204 * The size of the executable's initial heap
205 *
206 * On platforms that enable control of the size of the heap managed by
207 * the run-time support function malloc(), this parameter specifies
208 * its initial size (in units of chars).
209 */
210 config UInt heap = 0x1000;
211
212 /*!
213 * ======== argSize ========
214 * The size allocated for command line args to the executable
215 *
216 * On platforms that require static allocation of space to hold
217 * command line arguments, this parameter specifies its maximum size
218 * (in units of chars).
219 *
220 * Command line arguments are passed to C's `main` function when it's
221 * declared via the prototype: `int main(int argc, char *argv[])`. the
222 * `argv` array points to an array of strings allocated from the
223 * memory block whose size is controlled by `argSize`.
224 *
225 * Setting `argSize` to 0 means that no `argv` array will be allocated
226 * and the application `main()` function should be declared as
227 * `int main(void)`.
228 */
229 config UInt argSize = 0x200;
230
231 /*!
232 * ======== execCmd ========
233 * The command used to run this executable
234 *
235 * This string is used to create a command that runs the executable
236 * from the command line. If it is not set by the configuration script,
237 * it is set by the program's platform package (during program
238 * configuration).
239 *
240 * This command is run as follows:
241 * @p(code)
242 * execCmd <prog> <args>
243 * @p
244 * where, `<prog>` is the name of the executable and `<args>` are
245 * the arguments specified in the test (if any).
246 *
247 * @a(Note)
248 * This parameter is ignored if the exec command is specified as part
249 * of the test; see `{@link xdc.bld.Test#Attrs}`.
250 */
251 config String execCmd;
252
253 /*!
254 * ======== linkTemplate ========
255 * The template for the Program's linker command file
256 *
257 * A template is used to create the linker command file for each
258 * program. It can be optionally specified by setting this
259 * configuration parameter in the program's configuration script. If
260 * `linkTemplate` it is not set or set to `null`, the template is
261 * obtained from the platform associated with this program (i.e., the
262 * platform named by the `{@link #platform}` config in this module).
263 * See `{@link xdc.platform.IPlatform#getLinkTemplate IPlatform.getLinkTemplate}`.
264 *
265 * The `linkTemplate` string names a package path relative path; e.g.,
266 * if the linker template you want to specify is
267 * `"templates/big_n_hairy.xdt"` in the package `myCompany.myPackage`,
268 * `linkTemplate` should be set to:
269 * @p(code)
270 * "myCompany/myPackage/templates/big_n_hairy.xdt"
271 * @p
272 * If `linkTemplate` begins with the string `"./"`, the file is NOT
273 * searched for along the package path; instead the file name is taken
274 * to specify a file relative to the current working directory.
275 *
276 * In any case, if `linkTemplate` is non-`null`, the file must exist;
277 * otherwise, the configuration step will fail.
278 *
279 * @see #sectionsTemplate, #sectionsExclude, #memoryExclude
280 */
281 config String linkTemplate = null;
282
283 /*!
284 * ======== main ========
285 * The main entry point for the program
286 *
287 * This parameter is optionally set by the user's program
288 * configuration script. If it is not set, then a "legacy" `main()`
289 * function is assumed to be linked into the program; otherwise,
290 * the value of `main` is used as the "main" entry point to the
291 * program.
292 */
293 config Int (*main)(Int, Char*[]);
294
295 /*!
296 * ======== sectMap ========
297 * A section name to SectionSpec mapping
298 *
299 * This is a program specific mapping of output section names to
300 * {@link #SectionSpec} objects. The map supports mapping of section
301 * names to memory names; see {@link xdc.platform.IPlatform#sectMap}.
302 *
303 * This parameter enables program configurations to place named
304 * sections in platform specific memory regions. During generation of
305 * the linker command file, sections are mapped to named memories by
306 * first consulting this table; if the table does not contain a mapping,
307 * the target classifies each section as either "code", "data" or
308 * "stack" {@link xdc.bld.ITarget#sectMap} and the platform defines a
309 * memory region for each of these section types
310 * ({@link xdc.platform.IPlatform#codeMemory}/
311 * {@link xdc.platform.IPlatform#dataMemory}). If
312 * this does not produce a result, an error is generated.
313 * It is important to note that `sectMap` does not contain the complete
314 * section allocation for the program. It only contains the entries
315 * explicitly added to `sectMap`. To get the complete section
316 * allocation, a user should call {@link #getSectMap}.
317 *
318 * Suppose for example that the platform defines a memory segment
319 * named "DDR2". The following configuration statement places
320 * everything from the ".text" section into the "DDR2" segment.
321 *
322 * @p(code)
323 * Program.sectMap[".text"] = new Program.SectionSpec();
324 * Program.sectMap[".text"].loadSegment = "DDR2";
325 * @p
326 *
327 * @see #SectionSpec
328 * @see xdc.platform.IPlatform#sectMap
329 * @see xdc.bld.ITarget#sectMap
330 */
331 config Any sectMap[string];
332
333 /*!
334 * ======== sectionsExclude ========
335 * Sections to exclude from linker command file generation
336 *
337 * The `sectionsExclude` string is a JavaScript regular expression
338 * that is used to identify names of sections that should NOT be
339 * be handled by the normal linker command file generation process.
340 *
341 * Sections whose name matches `sectionsExclude` must be handled
342 * using a custom linker command file or by specifying a custom template
343 * (see `{@link #sectionsTemplate}` or `{@link #linkTemplate}`).
344 * @a(Examples)
345 * To completely override the placement of all output sections you can
346 * define `sectionsExclude` to match any string.
347 * @p(code)
348 * // Note: the '.' below represents _any_ character, not just "."
349 * Program.sectionsExclude = ".*";
350 * @p
351 * To override output sections that begin with '.' you must specify
352 * the literal character '.' and use the '^' character to match the
353 * beginning of the string.
354 * @p(code)
355 * // the sequence '^\.' matches just "." at the start of the name
356 * Program.sectionsExclude = "^\.";
357 * @p
358 * To override a specific sections you should be careful to supply a
359 * regular expression that matches the entire section name. You can
360 * use '$' to match the end of the name.
361 * @p(code)
362 * // match only ".const" or ".text"
363 * Program.sectionsExclude = "^\.const$|^\.text$";
364 * @p
365 *
366 * @see #sectionsTemplate, #linkTemplate
367 */
368 config String sectionsExclude = null;
369
370 /*!
371 * ======== memoryExclude ========
372 * Exclude memory definitions from linker command file generation
373 *
374 * This parameter accepts boolean values. If true, it disables default
375 * memory definitions from being added to the generated linker command
376 * file.
377 *
378 * This allows the user to define a custom memory map in a separate file
379 * and add it to the linker's command line.
380 *
381 * @see #sectionsTemplate, #sectionsExclude, #linkTemplate
382 */
383 config Bool memoryExclude = false;
384
385 /*!
386 * ======== sectionsTemplate ========
387 * Replace the sections portion of the generated linker command file
388 *
389 * The `sectionsTemplate` string names a template that is used to replace
390 * the "`SECTIONS`" content to the generated linker command file. This
391 * is useful especially when excluding specific sections via
392 * `{@link #sectionsExclude}` or when taking full control of the linker
393 * command file via `{@link #linkTemplate}` is unnecessary. The original
394 * "`SECTIONS`" content is computed and passed as an argument to this
395 * template, which makes it relatively simple to perform small changes to
396 * the "`SECTIONS`" content without having to explicitly handle every
397 * section required by the compiler toolchain.
398 *
399 * The `sectionsTemplate` string names a package path relative path; e.g.,
400 * if the linker template you want to specify is
401 * `"templates/mySections.xdt"` in the package `myCompany.myPackage`,
402 * `sectionsTemplate` should be set to:
403 * @p(code)
404 * "myCompany/myPackage/templates/mySections.xdt"
405 * @p
406 * If `sectionsTemplate` begins with the string `"./"`, the file is NOT
407 * searched for along the package path; instead the file name is taken
408 * to specify a file relative to the current working directory.
409 *
410 * In any case, if `sectionsTemplate` is non-`null`, the file must exist;
411 * otherwise, the configuration step will fail.
412 *
413 * During expansion of this template, there are three "parameters"
414 * that can be referenced to generate new content.
415 * @p(dlist)
416 * - `this`
417 * reference to the `{@link Program}` object
418 * - `$args[0]`
419 * is the complete section map derived from
420 * `{@link Program#sectMap}`; some special sections relevant to
421 * XDCtools are added to the map defined by `Program.sectMap`.
422 * - `$args[1]`
423 * is a string that contains the content that would have been
424 * placed in the `SECTIONS` portion of the generated linker
425 * command file. This allows templates to easily modify this
426 * content or simply add statements before or after it.
427 * @p
428 * @a(Example)
429 * The following template, specific to TI compiler tools, adds start
430 * and size symbols for the `.stack` section and ensures that the stack
431 * is the first section to be allocated in its designated memory segment.
432 * @p(code)
433 * %// first output allocation for the .stack section
434 * %var sectMap = $args[0];
435 * %var stack = sectMap[".stack"];
436 * .stack: >`stack.loadSegment` START(_stack_start) SIZE(_stack_size)
437 * %
438 * %// now append the normally generated content
439 * `$args[1]`
440 * @p
441 * Note: this example requires that the `.stack` section be excluded
442 * from the normal generation via `{@link sectionsExclude}`; otherwise
443 * this section will be specified twice by the template shown above.
444 * @p(code)
445 * Program.sectionsExclude = "^\.stack$";
446 * @p
447 *
448 * @see #sectionsExclude, #linkTemplate
449 */
450 config String sectionsTemplate = null;
451
452 /*!
453 * ======== system ========
454 * @_nodoc
455 * A facade for the {@link xdc.runtime.System#SupportProxy} parameter
456 *
457 * The program configuration script may select an implementation of
458 * the `xdc.runtime.ISystemSupport` interface and "bind" it by setting
459 * this parameter. If the module assigned to this parameter does not
460 * inherit from `xdc.runtime.ISystemSupport`, the configuration will fail.
461 *
462 * If this parameter is not set (or set to `undefined`), then a default
463 * implementation is used: `xdc.runtime.SysStd` or, if
464 * `Program.build.target.os` is `null`, `xdc.runtime.SysMin`. Recall that
465 * `Program.build.target.os` is specified in the Build Object Model;
466 * `Program.build.target` is the target specified when the executable was
467 * added to the package.
468 *
469 * If this parameter is set to `null`, then the `System` module is not
470 * linked into the application (unless 'Memory' is used); any references
471 * to `System`'s methods will result in a linker error. By setting this
472 * parameter to `null`, one is asserting that `System`'s methods will not
473 * be used.
474 */
475 config Any system;
476
477 /*!
478 * ======== name ========
479 * The name of the executable file
480 *
481 * This is the full file name (relative to the package's base) of the
482 * executable that results from this configuration.
483 *
484 * @a(readonly)
485 * This parameter is set by the generated program configuration script
486 * and must not be modified.
487 */
488 config String name;
489
490 /*!
491 * ======== cfgBase ========
492 * UNDER CONSTRUCTION
493 * @_nodoc
494 */
495 config String cfgBase;
496
497 /*!
498 * ======== buildPackage ========
499 * The name of the executable's package
500 *
501 * This is the full package name (relative to the package's repository)
502 * of the package that contains the executable being configured.
503 *
504 * @a(readonly)
505 * This parameter is set by the generated program configuration script
506 * and must not be modified.
507 */
508 config String buildPackage;
509
510 /*!
511 * ======== endian ========
512 * The endianess of the executable
513 *
514 * This parameter is an alias for `build.target.model.dataModel` and is
515 * set to one of the following values: `"big"`, `"little"`, or `null`.
516 *
517 * @a(readonly)
518 * This parameter is set by the generated program configuration script
519 * and must not be modified.
520 */
521 config String endian = null;
522
523 /*!
524 * ======== codeModel ========
525 * The memory model for code
526 *
527 * This parameter is an alias for `build.target.model.codeModel` and is
528 * set to one of the following target-specific values: `"near"`, `"far"`,
529 * `"large"`, or `null`.
530 *
531 * @a(readonly)
532 * This parameter is set by the generated program configuration script
533 * and must not be modified.
534 */
535 config String codeModel = null;
536
537 /*!
538 * ======== dataModel ========
539 * The memory model for data
540 *
541 * This parameter is an alias for `build.target.model.dataModel` and is
542 * set to one of the following target-specific values: `"near"`, `"far"`,
543 * `"large"`, or `null`.
544 *
545 * @a(readonly)
546 * This parameter is set by the generated program configuration script
547 * and must not be modified.
548 */
549 config String dataModel = null;
550
551 /*!
552 * ======== build ========
553 * This program's build attributes
554 *
555 * This parameter allows arbitrary build attributes to be carried
556 * forward from the Build Object Model (BOM) into the configuration
557 * model for program configuration scripts to read.
558 *
559 * Conceptually, this config parameter should be declared as follows:
560 * @p(code)
561 * struct BuildAttrs inherits xdc.bld.Executable.Attrs {
562 * config xdc.bld.ITarget.Module target;
563 * };
564 * @p
565 * All parameters of the target associated with the executable being
566 * configured are available through '`Program.build.target`'. Any config
567 * parameter set in the BOM's `{@link xdc.bld.Executable#attrs}` is also
568 * available through `{@link #build}`. For example, the name of the
569 * target is `Program.build.target.name` and the name of the
570 * executable's configuration script is `Program.build.cfgScript`.
571 *
572 * @a(readonly)
573 * This parameter is set by the generated program configuration script
574 * and must not be modified.
575 */
576 config Any build;
577
578 /*!
579 * ======== cpu ========
580 * The execution context "seen" by the executable.
581 *
582 * Since the execution context is largely determined by the CPU that
583 * runs the executable, this configuration parameter allows scripts with
584 * access to the program object to conditionally configure based on CPU
585 * characteristics (e.g., ISA or revision of a chip).
586 *
587 * @a(readonly)
588 * This parameter is set by the platform's implementation of
589 * `xdc.IPackage` (i.e., `package.xs`).
590 */
591 config xdc.platform.IExeContext.Instance cpu;
592
593 /*!
594 * ======== platformName ========
595 * The name of the executable's platform
596 *
597 * This field is the name of the platform instance used to create the
598 * executable; e.g., `"ti.platforms.sim55xx"`, or
599 * `"ti.platforms.sim6xxx:TMS320C6416"`.
600 *
601 * Platform instance names have the form:
602 * @p(code)
603 * <platform_pkg>:<instance_id>
604 * @p
605 * where `<platform_pkg>` is the name of the platform package
606 * responsible for creating the platform instance and the optional
607 * "`:<instance_id>`" is a suffix that uniquely identifies the creation
608 * parameters for this instance.
609 *
610 * The creation parameters are the values specified by the map
611 * `{@link xdc.bld.BuildEnvironment#platformTable}`;
612 * if this map does not contain the platform instance name, the
613 * instance is created with default values that are specific to the
614 * platform.
615 *
616 * @a(readonly)
617 * This parameter is set by the generated program configuration script
618 * and must not be modified.
619 */
620 config String platformName;
621
622 /*!
623 * ======== platform ========
624 * The executable's platform instance object
625 *
626 * The platform instance that provided an execution context for the
627 * executable being configured.
628 *
629 * @a(readonly)
630 * This parameter is set by the generated program configuration script
631 * and must not be modified.
632 */
633 config xdc.platform.IPlatform.Instance platform;
634
635 /*!
636 * ======== global ========
637 * Global variable declarations
638 *
639 * Assignments to this hash table become global symbols that can be
640 * used to directly reference objects. These objects are declared
641 * in a generated header that is indirectly included by the header
642 * `xdc/cfg/global.h`.
643 *
644 * Configuration scripts define symbols by adding new properties to
645 * `global`.
646 * @p(code)
647 * Program.global.myInstance = Mod.create();
648 * Program.global.myString = "hello world";
649 * @p
650 *
651 * Programs can reference the symbols defined in `global` by including
652 * the C/C++ header `xdc/cfg/global.h` as follows:
653 * @p(code)
654 * #include <pkg/Mod.h>
655 * #include <xdc/cfg/global.h>
656 * :
657 * Mod_fxn(myInstance, ...);
658 * printf("greetings: %s\n", myString);
659 * @p
660 *
661 * To compile sources that include `xdc/cfg/global.h`, one symbol must be
662 * defined before including this header:
663 * @p(dlist)
664 * - `xdc_cfg__header__`
665 * the package qualified name of the executable-specific C/C++
666 * header generated by the program configuration tool; e.g.,
667 * `local/examples/package/cfg/mycfg_x62.h`.
668 * @p
669 * For example, to compile sources that reference the values declared in
670 * `{@link #global}` for a TI C6x target with a generated
671 * configuration header named `package/cfg/mycfg_x62.h` in a package
672 * named `local.examples` the following command line is sufficient:
673 * @p(code)
674 * cl6x -Dxdc_cfg__header__=local/examples/package/cfg/mycfg_x62.h ...
675 * @p
676 *
677 * The `xdc_cfg__header__` symbol is automatically defined when you use
678 * the the XDC Build Engine (`{@link xdc.bld}`) to create executables; see
679 * `{@link xdc.bld.Executable#addObjects}`
680 *
681 * @see xdc.bld.Executable#addObjects
682 */
683 config Any global[string];
684
685 /*!
686 * ======== symbol ========
687 * Global symbol specifications
688 *
689 * UNDER CONSTRUCTION
690 * @_nodoc
691 *
692 * This map contains symbol definitions that are used to define aliases
693 * or constants. Symbol names are the C symbol names; i.e., compiler name
694 * mangling, such as the addition of a leading "_", is performed
695 * automatically.
696 *
697 * @a(Examples)
698 * To define a symbolic constant:
699 * @p(code)
700 * Program.symbol["ONE"] = 1;
701 * @p
702 * The line above causes the symbol "ONE" to be defined in the linker
703 * command file to be equal to 1. Note this in contrast to defining a
704 * variable whose value is 1; symbols do not occupy space, they are just
705 * symbolic constants defined in the symbol table of the executable.
706 *
707 * This is currently used by xdc.runtime.Startup to define symbols
708 * optionally referenced by boot files that support early startup
709 * "reset" functions.
710 */
711 config Any symbol[string];
712
713 /*!
714 * ======== exportModule ========
715 * Force all the symbols of a module to be part of a configuration
716 *
717 * Although a call xdc.useModule() will force some of a module's methods
718 * to be part of a configuration, the linker is still free to omit any
719 * symbols that are not referenced. Use of exportModule will force all
720 * methods of the specified module to be available.
721 */
722 Void exportModule(String modName);
723
724 /*!
725 * ======== getSectMap ========
726 * Return the complete mapping of section names to `{@link #SectionSpec}`
727 * entries
728 *
729 * The returned map is assembled from `{@link xdc.bld.ITarget#sectMap}`,
730 * `{@link xdc.platform.IPlatform#sectMap}`,
731 * `{@link xdc.platform.IPlatform#codeMemory}`,
732 * `{@link xdc.platform.IPlatform#dataMemory}`,
733 * `{@link xdc.platform.IPlatform#stackMemory}` and `{@link #sectMap}`.
734 * The function can be called at any time during configuration, but if
735 * it is called before all packages had a chance to change `sectMap`,
736 * the returned map may not correspond to the actual section
737 * allocation as configured in the linker command file.
738 *
739 * @a(returns)
740 * `getSectMap` returns a map with section names as keys and
741 * `{@link #SectionSpec}` entries as values.
742 */
743 function getSectMap();
744
745 /*!
746 * ======== importAssembly ========
747 * UNDER CONSTRUCTION
748 * @_nodoc
749 */
750 Void importAssembly(String asmName);
751
752 /*!
753 * ======== targetModules ========
754 * UNDER CONSTRUCTION
755 * @_nodoc
756 *
757 * This function returns a list of target modules. The list is completed
758 * only after all packages are closed, and runtime.finalized() is closed,
759 * so the only time when this function can be safely called is from
760 * within module$static$init and instance$static$init functions, package
761 * validate() functions, and templates.
762 *
763 * This function is currently used by xdc.runtime modules to retrieve a
764 * list of modules that use xdc.runtime services. The list therefore does
765 * not include modules that have the attribute `@NoRuntime`.
766 */
767 function targetModules();
768
769 /*!
770 * ======== freezeRomConfig ========
771 * UNDER CONSTRUCTION
772 * @_nodoc
773 */
774 Void freezeRomConfig(String modName, String cfgName);
775
776 /*!
777 * ======== freezeRomConfig2 ========
778 * UNDER CONSTRUCTION
779 * @_nodoc
780 */
781 function freezeRomConfig2(mod, cfgName);
782
783 /*!
784 * ======== freezeRomParams ========
785 * UNDER CONSTRUCTION
786 * @_nodoc
787 */
788 function freezeRomParams(mod);
789
790 /*!
791 * ======== frozenRomConfig ========
792 * UNDER CONSTRUCTION
793 * @_nodoc
794 */
795 Bool frozenRomConfig(String modName, String cfgName);
796
797 /*!
798 * ======== frozenRomConfig2 ========
799 * UNDER CONSTRUCTION
800 * @_nodoc
801 */
802 function frozenRomConfig2(mod, cfgName);
803 }
804 805 806
807