[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/txt tep106.txt, 1.11, 1.12 tep107.txt, 1.5, 1.6

Tue Jul 12 11:20:31 PDT 2005

Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/txt
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19561

Modified Files:
	tep106.txt tep107.txt 
Log Message:
Incorporated comments from TinyOS devel.

Index: tep106.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep106.txt,v
retrieving revision 1.11
retrieving revision 1.12
diff -C2 -d -r1.11 -r1.12
*** tep106.txt	6 Jul 2005 23:22:03 -0000	1.11
--- tep106.txt	12 Jul 2005 18:20:28 -0000	1.12
***************
*** 131,141 ****

  |  ``interface TaskParameter {``
! |    ``async error_t command post(uint16_t param);``
! |    ``event void run(uin16_t param);``
  |  ``}``

  Using this task interface, a component could post a task with a
  ``uint16_t`` parameter. When the scheduler runs the task, it will
! signal the ``run`` event with the passed parameter, which contains
  the task's logic.

--- 131,141 ----

  |  ``interface TaskParameter {``
! |    ``async error_t command postTask(uint16_t param);``
! |    ``event void runTask(uin16_t param);``
  |  ``}``

  Using this task interface, a component could post a task with a
  ``uint16_t`` parameter. When the scheduler runs the task, it will
! signal the ``runTask`` event with the passed parameter, which contains
  the task's logic.

***************
*** 179,186 ****

  A scheduler MUST provide a parameterized TaskBasic interface.
! If a call to TaskBasic.post() returns SUCCESS, the scheduler MUST run it
! eventually. The scheduler MUST return SUCCESS to a TaskBasic.post()
! operation unless it is not the first call to TaskBasic.post() since
! that task's TaskBasic.run() event has been signaled.

  A scheduler MUST provide the Scheduler interface. 
--- 179,186 ----

  A scheduler MUST provide a parameterized TaskBasic interface.
! If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it
! eventually. The scheduler MUST return SUCCESS to a TaskBasic.postTask()
! operation unless it is not the first call to TaskBasic.postTask() since
! that task's TaskBasic.runTask() event has been signaled.

  A scheduler MUST provide the Scheduler interface. 
***************
*** 204,212 ****
  runNextTask(TRUE) always return TRUE. 

! The TaskBasic interface is this:

  |  ``interface TaskBasic {``
! |    ``async command error_t post();``
! |    ``void event run();``
  |  ``}``

--- 204,212 ----
  runNextTask(TRUE) always return TRUE. 

! This is the TaskBasic interface:

  |  ``interface TaskBasic {``
! |    ``async command error_t postTask();``
! |    ``void event runTask();``
  |  ``}``

***************
*** 217,224 ****
  wired to the Scheduler with a unique identifier as its parameter. 
  The parameter MUST be obtained with the ``unique`` function in nesC, 
! with a key of ``"BasicScheduler.TaskBasic"``.

  The SchedulerBasic implementation uses these identifiers as its queue
! entries.When TinyOS tells the Scheduler to run a task, it pulls the
  next identifier off the queue and uses it dispatches on the
  parameterized TaskBasic interface.
--- 217,226 ----
  wired to the Scheduler with a unique identifier as its parameter. 
  The parameter MUST be obtained with the ``unique`` function in nesC, 
! with a key of ``"BasicScheduler.TaskBasic"``. The nesC compiler
! automatically does this wiring when the ``task`` and ``post``
! keywords are used.

  The SchedulerBasic implementation uses these identifiers as its queue
! entries. When TinyOS tells the Scheduler to run a task, it pulls the
  next identifier off the queue and uses it dispatches on the
  parameterized TaskBasic interface.
***************
*** 247,252 ****

  |  ``interface TaskEDF {``
! |    ``async command error_t post(uint16_t deadline);``
! |    ``void event run();``
  |  ``}``

--- 249,254 ----

  |  ``interface TaskEDF {``
! |    ``async command error_t postTask(uint16_t deadlineMs);``
! |    ``event void runTask();``
  |  ``}``

***************
*** 277,282 ****

  For a module to have an earliest deadline first task, it uses the
! TaskEDF interface. Its configuration SHOULD wire it to TinyScheduler,
! using a unique value generated from the key "TaskEDF." For example:

  |  ``configuration SomethingC {``
--- 279,287 ----

  For a module to have an earliest deadline first task, it uses the
! TaskEDF interface. Its configuration SHOULD wire it to TinyScheduler.
! The key used for task unique identifiers MUST be "TinyScheduler.TaskInterface",
! where *TaskInterface* is the name of the new task interface as presented
! by the scheduler.  For example, the module SomethingM requires two EDF
! tasks:

  |  ``configuration SomethingC {``
***************
*** 285,293 ****
  |  ``implementation {``
  |    ``components SomethingM, TinyScheduler;``
! |    ``SomethingM.TaskEDF -> TinyScheduler.TaskEDF["TaskEDF"];``
! |    ``TaskBasic = SchedulerEDF;``
! |    ``TaskEDF   = SchedulerEDF;``
  |  ``}``

--- 290,344 ----
  |  ``implementation {``
  |    ``components SomethingM, TinyScheduler;``
! |    ``SomethingM.SendTask -> TinyScheduler.TaskEDF["TinyScheduler.TaskEDF"];``
! |    ``SomethingM.SenseTask -> TinyScheduler.TaskEDF["TinyScheduler.TaskEDF"];``
  |  ``}``

+ The module SomethingM also has a basic task. The nesC compiler
+ automatically transforms task keywords into BasicTask interfaces and
+ wires them appropriately. Therefore, for basic tasks, a component
+ author can either use the ``task`` and ``post`` keywords or use a TaskBasic
+ interface. A component SHOULD use the keywords whenever possible, and it
+ MUST NOT mix the two syntaxes for a given task.  This is an example
+ implementation of SomethingM that uses keywords for basic tasks:
+ 
+ |  ``module SomethingM {``
+ |    ``uses interface TaskEDF as SendTask``
+ |    ``uses interface TaskEDF as SenseTask``
+ |  ``}``
+ |  ``implementation {``
+ |    ``// The TaskBasic, written with keywords``
+ |    ``task void cleanupTask() { ... some logic ... }``
+ |    ``event void SendTask.runTask() { ... some logic ... }``
+ |    ``event void SenseTask.runTask() { ... some logic ... }``
+ |
+ |    ``void internal_function() {``
+ |      ``call SenseTask.postTask(20);``
+ |      ``call SendTask.postTask(100);``
+ |      ``post cleanupTask();``
+ |    ``}``
+ |  ``}``
+ 
+ If the scheduler provides two instances of the same task interface,
+ their unique keys are based on the name of the interface as the 
+ scheduler presents it (the "as" keyword). For example, imagine
+ a scheduler which provides two instances of TaskBasic: standard
+ tasks and high-priority tasks. The scheduler always selects a task
+ for the high priority queue before the standard queue:
+ 
+ |  ``configuration TinyScheduler {``
+ |    ``provides interface Scheduler;``
+ |    ``provides interface TaskBasic[uint8_t taskID];``
+ |    ``provides interface TaskBasic[uint8_t taskID] as TaskHighPriority;``
+ |  ``}``
+ 
+ A component that uses a high priority task would then wire to
+ TaskHighPriority with the key "TinyScheduler.TaskHighPriority":
+ 
+ |  ``configuration SomethingElseC {``
+ |  ``}``
+ |  ``implementation {``
+ |    ``components TinyScheduler, SomethingElseM;``
+ |    ``SomethingElseM.RetransmitTask -> TinyScheduler.TaskHighPriority[unique("TinyScheduler.TaskHighPriority")];``
+ |  ``}``

Index: tep107.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/txt/tep107.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep107.txt	7 Jul 2005 21:28:44 -0000	1.5
--- tep107.txt	12 Jul 2005 18:20:29 -0000	1.6
***************
*** 187,191 ****
    2) If no such flag exists, the Init.init() implementation MAY
       temporarily enable interrupts. It MUST NOT call any other
!      component or return unless it has re-disabled interrupts.

  Unless part of a hardware abstraction architecture (HAA)[tep2]_, the 
--- 187,199 ----
    2) If no such flag exists, the Init.init() implementation MAY
       temporarily enable interrupts. It MUST NOT call any other
!      component or return until it has re-disabled interrupts.
! 
! As 2) means that interrupts may be temporarily enabled during
! initialization, components that control interrupts SHOULD NOT 
! cause interrupts to fire after their Init.init() returns. 
! However, it is possible that other components will cause an
! interrupt to fire due to hardware interactions or semantics.
! Therefore, a component MUST properly handle interrupts at
! all times.

  Unless part of a hardware abstraction architecture (HAA)[tep2]_, the 
***************
*** 195,202 ****
  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 
! initialization. If a
! component A depends on another component, B, which needs to be 
! initialized, then A SHOULD wire B's Init directly to the boot
! sequence, unless there is a temporal ordering requirement.

  5. Author's Address
--- 203,213 ----
  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 
! initialization. 
! 
! If a component A depends on another component, B, 
! which needs to be initialized, then A SHOULD wire B's Init directly 
! to the boot sequence, unless there is a temporal ordering requirement to
! the initialization. The purpose of this convention is to simplify
! component initialization and the initialization sequence.

  5. Author's Address