module xdc.runtime.Startup |
|
|
|
The xdc.runtime startup bootstrap
This module manages the very early startup initialization that occurs
before C's
main() function is invoked. This initialization typically
consists of setting hardware specific registers that control watchdog
timers, access to memory, cache settings, clock speeds, etc.
[
more ... ]
#include <xdc/runtime/Startup.h>
Functions |
Void | |
Bool | |
Functions common to all target modules |
|
|
Defines |
#define | |
#define | |
Typedefs |
typedef Void | |
Constants |
| |
| |
extern const Int | |
DETAILS
This module manages the very early startup initialization that occurs
before C's main() function is invoked. This initialization typically
consists of setting hardware specific registers that control watchdog
timers, access to memory, cache settings, clock speeds, etc.
In addition to configuration parameters that allow the user to add custom
startup functions, this module also provides services that allow modules
to automatically add initialiazation functions to the startup sequence.
STARTUP SEQUENCE
The following list defines the startup sequence and, in particular, when
user provided startup functions are invoked:
- CPU is initialized and initial C stack setup is performed.
- The 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, but this 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 (see Module Initialization below)
are called in a loop until all such functions return
Startup_DONE or the 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.
MODULE INITIALIZATION
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);
}
EXAMPLES
The following code shows how to add custom startup functions to this module.
var Startup = xdc.useModule('xdc.runtime.Startup');
Startup.resetFxn = "&myResetFxn";
Startup.firstFxns[Startup.firstFxns.length++] = "&myFirst";
Startup.lastFxns[Startup.lastFxns.length++] = "&myLast";
const Startup_DONE |
|
Returned from module startup functions no further calls are required
#define Startup_DONE (Int)-1
const Startup_NOTDONE |
|
Initial value of state argument passed to module startup functions
#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
SEE
config Startup_lastFxns // module-wide |
|
List of functions called after module startup
SEE
config Startup_maxPasses // module-wide |
|
Max number of iterations over the set of startup functions
extern const Int Startup_maxPasses;
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
var Startup = xdc.useModule('xdc.runtime.Startup');
module-wide constants & types
module-wide config parameters
generated on Mon, 02 Jun 2014 21:19:16 GMT