tep131.txt

tinyos-2.x.rar

======================================
Creating a New Platform for TinyOS 2.x
======================================

:TEP: 131
:Group: TinyOS 8051 Working Group
:Type: Informational
:Status: Draft 
:TinyOS-Version: 2.x 
:Author: Martin Leopold

:Draft-Created: 6-Nov-2007
:Draft-Version: 1 
:Draft-Modified: 6-Nov-2007
:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

.. Note::
   This memo is informational. It will hopefully be a basis for
   discussions and suggestions for improvements.  Distribution of this
   memo is unlimited.  This memo is in full compliance with TEP 1.

Abstract
====================================================================

The purpose of this TEP is to provide on overview of how to build a
new TinyOS 2 platform. While the purpose of most TEPs is to describe
TinyOS 2 entities, we will present concrete suggestions on how to
implement a new TinyOS 2 platform. We will use examples and briefly
cover the relevant TEPs to present a platform that adheres to the
current TinyOS standards. We will not cover the TEPs in detail, but to
the full text of each TEP for further information.

This TEP will go through the tool chain setup and the most basic
components for a functional TinyOS platform. We consider only TinyOS
version 2.x (from now on TinyOS).

Before venturing on this quest we will take a diversion and introduce
general TinyOS 2 concepts and terminology (Section 1), readers
familiar to TinyOS 2 can skip this section. This document will
introduce the TinyOS 2 platform (Section 2) and describes the 3
elements that make up a platform: the tool chain (Section 3) the
platform definitions (Section 4) and the chips definitions (Section
5).

Table of Content
====================================================================

..  contents::

1. TinyOS Overview
====================================================================

Before describing the process of writing TinyOS platforms we will
briefly sum up the TinyOS ecosystem and the terminology required in
this TEP. To learn more visit the TinyOS website http://www.tinyos.net.

A systems overview is depicted below. In this TEP we will primarily
concern our selves with the platform portion of figure and briefly
cover the tool chain. This involves writing the necessary drivers and
writing rules to pass the code to the TinyOS tool chain. We will not
cover sensor boards in this TEP refer to, see [TEP109_] for details.

::

             +------------------------------------------+
             |              Application                 |
             +------------------------------------------+
             +--------+   +----------+   +--------------+
             | TinyOS | + | Platform | + | Sensor board |
             +--------+   +----------+   +--------------+
                                 |
                                 V
                        +-------------------+
                        | TinyOS tool chain |
                        +-------------------+
                                 |
              Target platform    V
               +-------------------------------------+
               |  +-------+    +-----+    +-------+  |
               |  | Radio |----| MCU |----|Sensors|  |
               |  +-------+    +-----+    +-------+  |
               +-------------------------------------+


1.1 TinyOS 2 architecture
--------------------------------------------------------------------

TinyOS 2.x is built on a tree-layered hardware abstraction
architecture (HAA)[TEP2_]. This architecture separates the code for
each platform into distinct layers:

  1. the Hardware Independent Layer (HIL)
  2. the Hardware Adaptation Layer (HAL)
  3. the Hardware Presentation Layer (HPL)

A platform is built from bottom up, starting with the HPL level,
building HAL and HIL layers on top. Platform independent applications
are written using HIL level interfaces, allowing them to move easily
from platform to platform. While applications can target a platform
specific HAL layer for finer control of hardware specific features,
this will could prohibit such an application from being easily
portable. An overview of the TinyOS 2 architecture is given in
[tos2.0view_].

The requirements for the platform implementation is described in
TinyOS Enhancement Proposals (TEP). Each TEP covers a particular area
and specifies the recommendations within that area, some of which are
relevant for platforms. While no specific label or designation is
given to platforms adhering to the set of TEPs, [TEP1_] states:
"Developers desiring to add code (or TEPs) to TinyOS SHOULD follow all
current BCPs (Best Current Practice)". At the time of writing no TEP
has been awarded this designation or been finalized and we will refer
to the drafts as they are.

This document will not go through each of the requirements, but merely
outline how to build a basic functional platform. For further
information see "TinyOS 2.0 Overview" [tos2.0view_] or the TEP list on
the TinyOS website http://www.tinyos.net.


1.2 TinyOS Contrib
--------------------------------------------------------------------

The core of TinyOS is maintained by a set of working groups that
govern specific parts of the source code. New project can benefit from
the *contrib* section of TinyOS. This is a separate section of the
website and source repository maintained more loosely than the core of
TinyOS. It is intended for sharing code at an early stage or code that
may not gain the same popularity as the core.

New projects request a directory in this repository by following a
simple procedure on the `TinyOS contrib web page
<http://tinyos.cvs.sourceforge.net/*checkout*/tinyos/tinyos-2.x-contrib/contrib.html>`_

In contrib is a skeleton project *skel* that provides the most basic
framework for setting up a new platform, MCU, etc.

2. A TinyOS Platform
====================================================================

A TinyOS platform provides the code and tool chain definitions that
enable an application writer to implement an application for a mote. A
platform in TinyOS exposes some or all of the features of a particular
physical mote device to TinyOS applications - it refers to an entire
system, not a single chip. In order to write programs for a device
using TinyOS a platform for that device must exist within TinyOS.

A physical platform is comprised of a set of chips. Similarly a TinyOS
platform is the collection of the components representing these chips
(corresponding to drivers) Common chips can be shared among platforms
and implementing a new platform could simply mean wiring existing
components in a new way. If the chips that make up the platform are
not supported by TinyOS implementing the new platform consists if
implementing components for those chips (much like implementing
drivers).


2.1 A New Platform
--------------------------------------------------------------------

Platforms are discovered at compile time by the TinyOS tool
chain and a new platform placed in the search path will be discovered
automatically. In addition sensor boards can be defined in a very
similar manner, however we will not cover sensor boards, see [TEP109_]
for details. Defining a new platform boils down to 3 things:

  1. definitions of the chips that make up the platform,
  2. platform definitions (combining chips to a platform) and,
  3. the tool chain or make definitions.

The code for a TinyOS platform is spread out in a few locations of the
TinyOS tree depending based on those 3 categories. Below is an
overview of the locations and some of the files we will be needing in
the following (for further information see see "Coding Conventions"
[TEP3_] and the "README" files in each directory).

Through this TEP we will use the terms PlatformX and MCUX to denote
the new generic platform and MCU being created:

::

 tos
  +--chips                            1. Chip definitions
  |    +--chipX
  +--platforms			      
  |    +--platformX                   2. Platform definitions
  |         +--PlatformP/PlatformC
  |         +--PlatformLeds	         example component
  |         +--.platform
  |         +--hardware.h	      
  |         +--chips                        
  |              +--MCUX	         Platform specific features
  |              +--chipX
  +--sensorboards		      
  |    +--boardX		      
  |         +--.sensor		      
  +--support			      
       +--make			      3. Make definitions 
            +--platformX.target          platformX make targets
	    +--MCUX		      
	         +--MCUX.rules           make rules for MCUX
	         +--install.extra        additional target for MCUX


In the following we will briefly introduce each of the parts and
describe them in more detail in sections 2 through 4.


2.2 The Chips
--------------------------------------------------------------------

Each of the chips that provide software accessible functionality must
have definitions present in the chips directory sensors, radios,
micro controllers (MCU) alike. Each chip is assigned a separate
directory under ``tos/chips``. This directory contains chip specific
interfaces (HPL and HAL interfaces) and their implementations as well
as implementations of the hardware independent interface (HIL).

Some chips, MCUs in particular, contain distinct subsystems, such as
uart, timer, A/D converter, SPI, and so forth. These subsystems are
often put in a sub directory of their own within the chip-specific
directory.

If some feature of a chip is available or used only on a particular
platform, the platform directory can contain code that is specific to
this combination of chip and platform, say pin assignments, interrupt
assignments, etc. For example such additions would be placed in
``tos/platforms/platformX/chips/chipX`` for PlatformX.

2.3 The Platform Directory
--------------------------------------------------------------------

The platform is the piece of the puzzle that ties the components
corresponding to physical chips (drivers) together to form a
platform. The platform ties together the code that exposes the
features of the platform to TinyOS programs. In practise this is done
by i) including code for each of the chips and ii) by providing any
additional code that is specific to this particular platform.

A platform *PlatformX* would be placed in the directory
``tos/platforms/platformX/`` and code for subsystems reside in further
sub directories. Also in this directory is the ``.platform`` file that
sets up include paths and more (see Section 3).

An empty platform with no code (null) is provided and serves as an
example for other platforms.


2.4 The Tool-Chain (Make System)
--------------------------------------------------------------------

The build system for TinyOS is written using GNU Make [#make]_. The
build system controls the process from pre-processing a TinyOS
application into a single C file and to pass this file to the
appropriate compiler and other tools. The make system is documented in
``support/make/README`` and in TinyOS 2 Tutorial Lesson 10[TUT10_].

The make system is located in the ``support`` directory. This
directory contains a platform definition and Make rules to build an
application for this platform (see Section 2).

.. [#make] http://www.gnu.org/software/make/ 

2.5 The Minimal Platform
--------------------------------------------------------------------

Before describing each of the subsystems, we will show a simple check
list. The absolute minimal TinyOS platform would have to provide the
following resources, given a *PlatformX* with *MCUX*:

* a platform directory ``tos/platform/PlatformX/`` with the following

  - a platform definition (*.platform* file)
  - a *hardware.h* header

* a *platformX.target* in ``tos/support/make``
* a *MCUX.rules* in ``tos/support/make/MCUX``
* a *MCUX* directory in ``tos/chips/MCUX``, containing

  - a *McuSleepC* (must enable interrupts)
  - a *mcuxhardware.h* (defines *nesc_atomic_start*/*nesc_atomic_end*)


3. Tool Chain
====================================================================

The major components in the tool chain of TinyOS are i) the compiler
and ii) the build system that uses the compiler to produce an
executable binary or hex file. The first is installed separately,
while the second is part of the TinyOS source code. The compile
process transforms a set of nesC files into a binary executable or hex
file. Involved in this process is set of separate tools that are
linked in a chain. We will briefly cover this chain in a moment, but a
detailed description is beyond the scope of this TEP.

The make system is split in two: a general part and a platform
specific part. Section 3.1 will introduce the general mechanism and
Section 3.2 will cover how to introduce a new platform in the tool
chain.

3.1 Compiling using nesC
--------------------------------------------------------------------

The process of the build system is depicted below. This system feeds
the source code through the tools to produce an executable or hex file
for uploading to the platform. The nesC pre-compiler is split in two
tools ncc an nescc. These two tools are used to assemble nesC source
files into a single C file which is compiled using a regular C
compiler. This requires that a C compiler is available for a given
platform and that this compiler accepts the dialect produced by nesC.

::

    TinyOS
  application
      |
      |
      V                      
  +------+       +-----+        +---------+         +------------+
  | ncc  | app.c |     | Binary |         | app.hex |            |
  |  +   |------>| GCC |------->| objdump |-------->| programmer |
  | nesC |       |     |        |         |         |            |
  +------+       +-----+        +---------+         +------------+
                                                          |