CS199 Notes for 9/7/2004
Topic: TinyOS Programming
Scribe: Kaisen Lin
==================

1. Review from previous lectures
--------------------------------
Standard Operating Systems - general purpose platform, thread based usually
TinyOS - customizable abstraction boundaries, event based

2. Interfaces
-------------
interface x {
  command ...
  event ...
}
Note 1: Bi-directional interfaces

|---|    |---|
|   |----|   |
|---|  ^ |---|
       |   ^
       |   |-- component
       |------ interface

3. Components
-----------------------

Two kinds: modules and configurations. All components have a
specification section and an implementation section. The specification
declares how the component interacts with other components. The
implementation defines how that is achieved. The specification is usually
defined in terms of interfaces.

<module|configuration> <name> {
  // specification
}
implementation {
  // implementation
}

4. Modules
------------------------
Definition: code, functions, state
Example: SingleTimer.nc


module Z {
  provides interface X [as X]  // use [as X] for multiple interface names
  uses interface Y [as Y]
}
implementation {
  /* state variables or C-style functions here */
  command result_t X.foo(...) {
    /* code... */
  }
  event result_t Y.bar(...) {
    /* code... */
  }
}

Note 1: Because Z provides interface X, it must implement all of X's commands
Note 2: Because Z uses interface Y, it must implement all of Y's events
Note 3: You can only call through functions declared, that's why you
        need Configurations (see next section)
Note 4: result_t is either SUCCESS or FAIL.

4. Components - Configurations
------------------------------
Definition: A description of connections between components. This can
be between modules or other configuration components.

Example: GenericComm

configuation X {
  provides interface L;
  uses interface M;
}
implementation {
  components A, B, C;
  L = A.L; /* someone may want to wire outside this component to A */
  M = B.M;
  A.z -> B.z; /* wires inside your component */
}

Note 1: A, B, C can be other configurations as well, not just modules
Note 2: = is a pass through connection, and is a compile-time operation
Note 3: -> is a connection, with the user on the left and the provider
on the right
  Note 3a: This means the left side implements Events and the right side
  implements Commands...
  Note 3b: Arrows can be written in the opposite direction ( <- )
Note 4: Allows easy component changes while preserving abstraction

5. Multiple Wiring
------------------
Problem: Suppose you want to power down and make sure everyone is no
longer using it.

Solution: Have multiple wirings and take logical-and

Example with SingleTimer:
components One, Two, SingleTimer;
One.Timer -> SingleTimer;
Two.Timer -> SingleTimer;

Note 1: When the timer is fired, both One and Two are signaled. Also
known as "fan-in/out"

Note 2: This leads to special return value because it can be two
possible things
  Note 2a: Compiler automatically takes the logical-and. You can do it
  too with rcombine(...)

event result_t fired() {
  return One.fired() AND Two.fired(); /* not proper syntax */
}

6. nesC Compiler Path
---------------------

You can change your hardware platform with a compiler switch.  If you
use PC, then the hardware components are simulated. When ncc loads a
component, it searches the path order for an instance of it. This
means that you can replace standard implementations of components with
alternative ones. For example, the TOSSIM simulation replaces many of
the hardware abstraction components: instead of manipulating control
registers or interrupt handlers, calls to these components interact
with simulator state and a discrete event queue.