module xdc.runtime.Startup |
|
|
|
The xdc.runtime startup bootstrap
Every module can optionally define a startup function which is called
before
main(). Modules declare that they want to participate in this
startup sequence via the
@ModuleStartup attribute in the module's spec
file. Modules that use this attribute must also implement the following
startup function:
[
more ... ]
#include <xdc/runtime/Startup.h>
module-wide constants & types
module-wide config parameters
module-wide functions
module-wide built-ins
XDCscript usage |
meta-domain |
var Startup = xdc.useModule('xdc.runtime.Startup');
module-wide constants & types
module-wide config parameters
module Startup {
module-wide constants & types
module-wide config parameters
module-wide functions
}
DETAILS
Every module can optionally define a startup function which is called
before main(). Modules declare that they want to participate in this
startup sequence via the @ModuleStartup attribute in the module's spec
file. Modules that use this attribute must also implement the following
startup function:
Int Mod_Module_startup(Int state);
where "Mod" is the name of the module requesting startup support.
The parameter to the startup function serves as "state variable" whose
initial value will be
Startup_NOTDONE. If
startup() returns a value
other than
Startup_DONE, it will be called in a subsequent pass with this
return value passed in as
state. To ensure this process terminates,
no startup function is ever called more than
maxPasses
times.
For situations in which the startup of one module depends upon another
having completed its startup processing, the following function is
automatically defined for all modules and proxies:
Bool Mod_Module_startupDone();
where "Mod" is the name of some module or proxy. These predicates can
be used as guards inside of a startup function to probe whether a
particular module has completed its own startup processing. As a
convenience, the function Startup_rtsDone() probes the necessary set of
xdc.runtime modules required to support instance create() functions, and
should be called before any startup-time instance creation and/or
memory allocation is performed.
Int Mod_Module_startup(Int state)
{
if (!Startup_rtsDone()) {
return (Startup_NOTDONE);
}
.
.
.
return (Startup_DONE);
}
STARTUP SEQUENCE
The following list defines when in the startup sequence the user provided
startup functions are being invoked:
- CPU is initialized and C stack setup is performed.
- Function specified by Startup.resetFxn is called.
Startup.resetFxn is called only on platforms where reset is performed
before running a program. For example, boot code for all TI targets
invokes Startup.resetFxn, while that function is not invoked on
Microsoft targets.
- C runtime initialization is performed.
- Functions from the array Startup.firstFxns are called.
- All Mod_Module_startup functions are called in a loop until all such
functions return Startup_DONE or maxPasses threshold is reached.
- Functions from the array Startup.lastFxns are called.
- The function main is called.
The steps 4 - 6 occur during C++ static object initialization. Since
the ANSI C++ Language Standard does not provide a means to control
the order of C++ constructors, if a C++ constructor uses an XDC module,
there is no guarantee that the module's startup function already ran.
Therefore, any C++ constructor that needs XDC modules' services should
call Startup_exec first to force all startup related functions from
steps 4 - 6 to run, before the constructor uses any XDC module.
Also, if a target does not support C++, the steps 4 - 6 will not run
automatically. It is then up to a user's code to invoke Startup_exec,
possibly as the first step in main.
const Startup.DONE |
|
Returned from module startup functions no further calls are required
XDCscript usage |
meta-domain |
#define Startup_DONE (Int)-1
const Startup.NOTDONE |
|
Initial value of state argument passed to module startup functions
XDCscript usage |
meta-domain |
const Startup.NOTDONE = 0;
#define Startup_NOTDONE (Int)0
typedef Startup.InitFxn |
|
Type of function assignable to firstFxns, lastFxns, or resetFxn
typedef Void (*Startup_InitFxn)();
config Startup.firstFxns // module-wide |
|
List of functions called before module startup
XDCscript usage |
meta-domain |
config Startup.lastFxns // module-wide |
|
List of functions called after module startup
XDCscript usage |
meta-domain |
config Startup.maxPasses // module-wide |
|
Max number of iterations over the set of startup functions
XDCscript usage |
meta-domain |
Startup.maxPasses = Int 32;
extern const Int Startup_maxPasses;
metaonly config Startup.common$ // module-wide |
|
Common module configuration parameters
XDCscript usage |
meta-domain |
DETAILS
All modules have this configuration parameter. Its name
contains the '$' character to ensure it does not conflict with
configuration parameters declared by the module. This allows
new configuration parameters to be added in the future without
any chance of breaking existing modules.
metaonly config Startup.resetFxn // module-wide |
|
Function to be called by during initialization
XDCscript usage |
meta-domain |
Startup.resetFxn = Void(*)() null;
DETAILS
This function is called only on platforms where reset is performed
before running the program. The purpose of this function is to set up
the hardware registers (cache, external memory interface, etc.) before
any other code executes.
Startup.exec( ) // module-wide |
|
Execute the startup functions of all resident modules
DETAILS
Note that this function is idempotent, and can be called at any point
in the platform/target startup sequence in which "ordinary" C functions
can execute. By default, this function is called as part of the
standard C++ static initialization sequence.
If your target compiler does not support C++, this function must be
called at least once prior to using any xdc.runtime modules.
Simply call this function at the very beginning of main().
Startup.rtsDone( ) // module-wide |
|
Query the state of the xdc.runtime package
DETAILS
This function is used by module startup functions to determine
when it is possible to use the xdc.runtime modules; e.g. to
allocate memory, create instances managed by some module (even
those outside the xdc.runtime package), call a Log function,
etc.
RETURNS
Returns TRUE when all xdc.runtime modules have completed
initialization.
module-wide built-ins |
|
// Get this module's unique id
Bool Startup_Module_startupDone( );
// Test if this module has completed startup
// The heap from which this module allocates memory
Bool Startup_Module_hasMask( );
// Test whether this module has a diagnostics mask
Bits16 Startup_Module_getMask( );
// Returns the diagnostics mask for this module
Void Startup_Module_setMask( Bits16 mask );
// Set the diagnostics mask for this module
generated on Wed, 06 Jan 2010 18:40:43 GMT