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 ... ]
C synopsis target-domain sourced in xdc/runtime/Startup.xdc
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:
  1. CPU is initialized and initial C stack setup is performed.
  2. 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.
  3. C runtime initialization is performed.
  4. Functions from the array Startup.firstFxns are called.
  5. 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.
  6. Functions from the array Startup.lastFxns are called.
  7. 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

C synopsis target-domain
#define Startup_DONE (Int)-1
 
 
const Startup_NOTDONE

Initial value of state argument passed to module startup functions

C synopsis target-domain
#define Startup_NOTDONE (Int)0
 
 
typedef Startup_InitFxn

Type of function assignable to firstFxns, lastFxns, or resetFxn

C synopsis target-domain
typedef Void (*Startup_InitFxn)();
 
 
config Startup_firstFxns  // module-wide

List of functions called before module startup

C synopsis target-domain
extern const Startup_InitFxn Startup_firstFxns[length];
 
SEE
 
config Startup_lastFxns  // module-wide

List of functions called after module startup

C synopsis target-domain
extern const Startup_InitFxn Startup_lastFxns[length];
 
SEE
 
config Startup_maxPasses  // module-wide

Max number of iterations over the set of startup functions

C synopsis target-domain
extern const Int Startup_maxPasses;
 
 
Startup_exec()  // module-wide

Execute the startup functions of all resident modules

C synopsis target-domain
Void Startup_exec();
 
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

C synopsis target-domain
Bool Startup_rtsDone();
 
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

C synopsis target-domain
Types_ModuleId Startup_Module_id();
// Get this module's unique id
 
Bool Startup_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle Startup_Module_heap();
// 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
 
Configuration settings sourced in xdc/runtime/Startup.xdc
 
const Startup.DONE

Returned from module startup functions no further calls are required

Configuration settings
const Startup.DONE = -1;
 
C SYNOPSIS
 
const Startup.NOTDONE

Initial value of state argument passed to module startup functions

Configuration settings
const Startup.NOTDONE = 0;
 
C SYNOPSIS
 
config Startup.firstFxns  // module-wide

List of functions called before module startup

Configuration settings
Startup.firstFxns = Startup.InitFxn[length] [ ];
 
SEE
C SYNOPSIS
 
config Startup.lastFxns  // module-wide

List of functions called after module startup

Configuration settings
Startup.lastFxns = Startup.InitFxn[length] [ ];
 
SEE
C SYNOPSIS
 
config Startup.maxPasses  // module-wide

Max number of iterations over the set of startup functions

Configuration settings
Startup.maxPasses = Int 32;
 
C SYNOPSIS
 
metaonly config Startup.common$  // module-wide

Common module configuration parameters

Configuration settings
Startup.common$ = Types.Common$ undefined;
 
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

Configuration settings
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.
This function is called as early as possible in the program initialization process.
SEE
generated on Tue, 14 Feb 2017 20:01:29 GMT