:TEP: 107
:Group: Core Working Group
:Type: Documentary
-:Status: Draft
+:Status: Final
:TinyOS-Version: 2.x
:Author: Philip Levis
-:Draft-Created: 10-Dec-2004
-:Draft-Version: $Revision$
-:Draft-Modified: $Date$
-:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
-
.. Note::
This memo documents a part of TinyOS for the TinyOS Community, and
implementation {
int main() __attribute__ ((C, spontaneous)) {
atomic {
+ platform_bootstrap();
call Scheduler.init();
call PlatformInit.init();
while (call Scheduler.runNextTask());
The first step in the boot sequence is initializing the system::
atomic {
+ platform_bootstrap();
call Scheduler.init();
call PlatformInit.init();
while (call Scheduler.runNextTask());
while (call Scheduler.runNextTask());
}
+The first call, platform_bootstrap(), is a minimalist function that
+places the system into an executable state. This function MUST NOT include
+operations besides those which are absolutely necessary for further code,
+such as scheduler initialization, to execute.
+Examples of platform_bootstrap() operations are configuring the memory
+system and setting the processor mode. Generally, platform_bootstrap()
+is an empty function. TinyOS's top-level include file, ``tos.h``, includes
+a default implementation of this function which does nothing. If a platform
+needs to replace the default, it SHOULD put it in a platform's
+``platform.h`` file as a #define. The implementation of ``tos.h``
+supports this::
+
+ /* This platform_bootstrap macro exists in accordance with TEP
+ 107. A platform may override this through a platform.h file. */
+ #include <platform.h>
+ #ifndef platform_bootstrap
+ #define platform_bootstrap() {}
+ #endif
The boot sequence has three separate initializations: Scheduler,
PlatformInit, and SoftwareInit. The boot configuration (MainC) wires
new plaform MUST include a component PlatformC which provides
one and only one instance of the Init interface.
+Initializations invoked
+through PlatformC meet some or all of the following criteria:
+
+1. The initialization requires configuring hardware resources. This implies that the code is platform-specific.
+
+2. The initialization should always be performed.
+
+3. The initialization is a prerequisite for common services in the system.
+
+Three example operations that often belong in PlatformInit are I/O pin
+configuration, clock calibration, and LED configuration. I/O pin
+configuration meets the first two criteria. It should always be performed
+(regardless of what components the OS uses) for low-power reasons:
+incorrectly configured pins can draw current and prevent the MCU from
+entering its lowest power sleep state [2]_. Clock calibration meets
+all three criteria. LED configuration is a special case: while it
+nominally meets all three criteria, the most important one is the third:
+as LEDs are often needed during SoftwareInit initialization, they must
+be set up before it is invoked.
+
+Note that not all code which meets some of these criteria is wired through
+PlatformC. In particular, criterion 1 is typically necessary but not
+sufficient to require PlatformC. For example, a timer system that
+configures overflow and capture settings or a UART stack that sets the
+baud rate and transmission options can often be wired to SoftwareInit.
+They are encapsulated abstractions which will not be invoked or
+started until the boot event, and only need to be configured if the
+system includes their functionality.
+
Components whose initialization does not directly depend on hardware
resources SHOULD wire to MainC.SoftwareInit. If a component requires a
specific initialization ordering, then it is responsible for
One common approach is for a configuration to "auto-wire" the
initialization routines of its internal components. The configuration
-does not provide an Init interface. Virtualized services (TEP 108)
+does not provide an Init interface. Virtualized services
often take this approach, as the service, rather than the clients, is
what needs to be initialized. For example, the standard Timer
-virtualization (TEP 102), TimerMilliC, wires to TimerMilliP, which is
+virtualization [3]_, TimerMilliC, wires to TimerMilliP, which is
a very simple configuration that takes the underlying implementation
(HilTimerMilliC) and wires it to MainC::
configuration TimerMilliP {
- provides interface Timer<TMilli> as TimerMilli[uint8_t id];
+ provides interface Timer<TMilli> as Timinitialization in ordererMilli[uint8_t id];
}
implementation {
components HilTimerMilliC, MainC;
care needs to be used in order to not disrupt the operation of other
components.
-Unless part of a hardware abstraction architecture (HAA) [2]_, the
+Unless part of a hardware abstraction architecture (HAA) [4]_, the
Init.init() command MUST NOT assume that other components have been
initialized unless it has initialized them, and MUST NOT call any
-functional interfaces on any components that might be shared. An HAA
+functional interfaces on any components that might be shared or
+interact with shared resources. Components MAY call functions
+on other components that are completely internal to the subsystem.
+For example, a networking layer can call queue operations to
+initialize its queue, but a link layer must not send commands
+over an SPI bus. An HAA
component MAY make other calls to initialize hardware state. A
component that is not part of an HAA SHOULD NOT call Init.init() on
other components unless it needs to enforce a temporal ordering on
.. [1] TEP 106: Schedulers and Tasks.
-.. [2] TEP 2: Hardware Abstraction Architecture.
+.. [2] TEP 112: Microcontroller Power Management.
+
+.. [3] TEP 102: Timers.
+
+.. [4] TEP 2: Hardware Abstraction Architecture.
+