[Tinyos-2-commits] CVS: tinyos-2.x/doc/html tep107.html,1.6,1.7

[Phil Levis]

Update of /cvsroot/tinyos/tinyos-2.x/doc/html
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv16876/html

Modified Files:
	tep107.html 
Log Message:
Further elucidation based on Martin's comments.


Index: tep107.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/html/tep107.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tep107.html	12 Dec 2006 18:22:53 -0000	1.6
--- tep107.html	5 Feb 2007 19:11:25 -0000	1.7
***************
*** 304,310 ****
  <tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Dec-2004</td>
  </tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.11</td>
  </tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-06-13</td>
  </tr>
  <tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List &lt;tinyos-devel at mail.millennium.berkeley.edu&gt;</td>
--- 304,310 ----
  <tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">10-Dec-2004</td>
  </tr>
! <tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.6</td>
  </tr>
! <tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-02-05</td>
  </tr>
  <tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List &lt;tinyos-devel at mail.millennium.berkeley.edu&gt;</td>
***************
*** 470,473 ****
--- 470,474 ----
  <pre class="literal-block">
  atomic {
+   platform_bootstrap();
    call Scheduler.init();
    call PlatformInit.init();
***************
*** 477,480 ****
--- 478,489 ----
  }
  </pre>
+ <p>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. The platform_bootstrap() function SHOULD be
+ specified in a platform's <tt class="docutils literal"><span class="pre">hardware.h</span></tt> file.</p>
  <p>The boot sequence has three separate initializations: Scheduler,
  PlatformInit, and SoftwareInit. The boot configuration (MainC) wires
***************
*** 511,514 ****
--- 520,542 ----
  new plaform MUST include a component PlatformC which provides
  one and only one instance of the Init interface.</p>
+ <p>Generally, component intialization occurs through SoftwareInit.
+ PlatformInit is for a small subset of initializations whose properties
+ requires that they be performed separately. Initializations invoked
+ through PlatformC meet some or all of the following criteria:</p>
+ <ol class="arabic simple">
+ <li>The initialization requires configuring hardware resources. This implies that the code is platform-specific.</li>
+ <li>The initialization should always be performed.</li>
+ <li>The initialization is a prerequisite for common services in the system.</li>
+ </ol>
+ <p>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[<a class="reference" href="#id6">2</a>]. 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.</p>
  <p>Components whose initialization does not directly depend on hardware
  resources SHOULD wire to MainC.SoftwareInit. If a component requires a
***************
*** 527,531 ****
  <pre class="literal-block">
  configuration TimerMilliP {
!   provides interface Timer&lt;TMilli&gt; as TimerMilli[uint8_t id];
  }
  implementation {
--- 555,559 ----
  <pre class="literal-block">
  configuration TimerMilliP {
!   provides interface Timer&lt;TMilli&gt; as Timinitialization in ordererMilli[uint8_t id];
  }
  implementation {
***************
*** 580,584 ****
  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
  component MAY make other calls to initialize hardware state. A
  component that is not part of an HAA SHOULD NOT call Init.init() on
--- 608,617 ----
  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 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