From RTSC-Pedia

—— LANDSCAPE orientation

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC

Creating Configurable Content

How to leverage the configuration process

Contents 1 Introduction 2 Configuration Process 2.1 Package Functions 2.2 Module Functions 2.3 Order of Evaluation

Introduction

During the configuration process, the RTSC configuration framework invokes specific package functions in response to commands in the user's script and the commands in loaded packages. As a result, it's important to understand which meta-domain package and module functions are invoked by the RTSC configuration framework, when these functions are called, and the context that exists when they are called. The sections below provide the details necessary for the content producer to fully leverage the RTSC configuration framework.

Configuration Process

The configuration process proceeds in a sequence of "phases":

1. object model initialization
2. user's configuration script runs
3. all loaded packages are closed
4. module state initialization is run for all "used" modules
5. instance state initialization is run for all created instances
6. config model validation is run for all loaded packages
7. C code generation is run for all "used" modules

In each phase, meta-only XDCscript code defined by the user or the loaded packages is invoked. This script code manipulates a "configuration object model" which is ultimately used to generate a C source file and a linker command file that are integrated into an application's final build.

Package Functions

The following package functions are called during the configuration process and are optionally defined in the package's package.xs file:

• init() — package initialization occurs when a package is loaded, before a user or any other package can read or write package's configuration parameters
• close() — after the user's script is run, each package can act upon the current state of the configuration and make changes in the configuration
• validate() — after all packages and module methods finish modifying the model, the model is "sealed" (made unmodifiable) and then each package can validate the configuration and possibly abort it, but nothing in the model can be changed at this point
• getLibs() — if validation completes without any errors, getLibs() is called to get the libraries necessary to use this package
• getSects() — if all of the libraries specified by getLibs() exist, getSects() is called to get package-specific linker section data which is placed in the generated linker command file along with the list of libraries specified by getLibs()

If you don't define one of these functions, a default implementation will be used instead. For detailed documentation of these functions see xdc.IPackage.

Module Functions

The following functions are optionally defined in each module's .xs file:

• module$meta$init() — called right before the package's init() function, so its purpose is similar, but module specific initialization should be here.
• module$use() — called after user's script, as a consequence of an xdc.useModule() call on the module. In most cases, the function module$use does not execute immediately within the xdc.useModule() call. The execution of module$use is delayed until the module's package is closing. However, an exception is made for modules whose packages are already closed at the time xdc.useModule() is called on them. In such cases, module$use executes immediately and it executes after the module's package close function is called. Changes in configuration parameters are allowed in module$use.
• module$static$init() — target object for the module is initialized; no changes in configuration parameters are allowed here and is only called for target modules.
• module$validate() — called for all modules in a package, before the package's validate() function; can be used to verify the consistency of values assigned to configuration parameters, but no changes in parameters are allowed.
• instance$meta$init() — invoked whenever create() is called, configuration can be changed.
• instance$static$init() — invoked after closing to initialize instance object, no changes in configuration parameters are allowed; called only for instances of target modules.

For detailed documentation of these functions see the XDCscript Language Reference.

Order of Evaluation

The table below summarizes the order of evaluation of the methods optionally supplied by a package. Within a package, these methods are guaranteed to be evaluated in top to bottom order. When two methods appear in the same row, no order is guaranteed.

Id	Phase	Package	Module	Instance
2	user's script		module$meta$init [2-3]
		init [2-3]
				instance$meta$init [2-5]
3	package close	close [3]	module$use [3]	instance$meta$init [2-5]
4	module init		module$static$init [4]	instance$meta$init [2-5]
5	instance init			instance$static$init [5]
6	validation		module$validate [6]
		validate [6]
7	generation		module templates [7]

Order of evaluation between packages is also indicated by this table. Each method name is followed by the id(s) of the phases in which it can be run. A method whose largest phase id is less than the minimum phase id of another method is guaranteed to run first. For example, all package validate() methods run after all instance$meta$init() calls.

Ordering of phases also determines which xdc methods can and cannot be called within a particular phase. Any calls that would require going backwards to an already completed phase are not allowed. For example, module$static$init functions invoked in the phase 4 cannot call xdc.loadPackage() on any new packages because the package's init() function, which can be called only in phases 2 and 3, would have to be called for those packages. Here is a summary of such limitations:

• After the phase 3, all configuration parameters are sealed and cannot be changed
• xdc.loadPackage() and xdc.useModule() can be called only in the first 3 phases
• xdc.module() can always be called for modules in previously loaded packages, but only in the first 3 phases for modules from packages not being already loaded
• Mod.create() can be called only in the first 5 phases

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC