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