tep121.txt

tinyos-2.x.rar

=============================
Towards TinyOS for 8051
=============================

:TEP: 121
:Group: TinyOS 8051 Working Group 
:Type: Informational
:Status: Draft 
:TinyOS-Version: 1.x 
:Author: Anders Egeskov Petersen, Sidsel Jensen, Martin Leopold

:Draft-Created: 15-Dec-2005 
:Draft-Version: 1 
:Draft-Modified: 27-Mar-2006 
:Draft-Discuss: TinyOS 8051 Working Group List <Tinyos-8051wg 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
====================================================================

This TEP covers our effort of porting `TinyOS`_ to the nRF24E1
platform. We ported the basic modules of TinyOS: Timer, UART, ADC and
LEDS.


1. Project Outline
====================================================================

The original 8 bit 8051 chip is a member of the `mcs51 family`_ and
was developed in 1980 by Intel. It is still to this date one of the most
widely used microcontrollers. Porting TinyOS to the 8051 System on chip
architecture makes perfect sense - the mcs51 family has been thoroughly
tested, it is relatively cheap and it has a reasonable small footprint -
which makes it ideal for embedded solutions and sensor networks.

For this work, we use a Nordic Semiconductor VLSI nRF24E1
evaluation-board [NSC]. The board contains an Intel 8051 compatible MCU
with 4KB program memory, a 16 MHz clock, 3 different Timers (one being
8052 compatible), a 2.4 GHz wireless RF transceiver and 9 input 10 bit
ADC, SPI and a RS232 Serial interface. The nRF24E1 board was chosen
because the radio component matches the radio on the specially designed
DIKU/DTU HogthrobV0 [HOG] boards used for research purposes at DIKU
[PEH].

We ported a subset of TinyOS for the 8051 platform consisting of the
Timer, UART, ADC and LED modules. We did not port the radio module and
the underlying SPI-bus code.

This works attacks the two most immediate problems when porting TinyOS
to 8051: the toolchain and the hardware abstraction components. The
first problem when porting TinyOS to 8051-based platforms concerns the
toolchain. The Gcc compiler does not support 8051. This is a major issue
as the code generated by the NesC preprocessor is tailored for gcc.  The
second problem concerns the hardware abstraction components that must be
specialized to the 8051 idiosyncracies. In a perfect world, such a
specialization should not require to modify any interface.
Unfortunately, we needed to modify some of the interfaces to accomodate
the 8051 features.

This work was done under the supervision of Martin Leopold at University
of Copenhagen.

2. Project Approach
====================================================================

The approach to the porting project has been pragmatic. The focus has
been on producing working code, so testing and debugging have been key
elements of our work. The process has been to implement new
functionality in small iterative steps and do testing simultaneously.

To bootstrap the development without a JTAG module or alike, we built a
small LED expansion board attachable to the port logic. The LEDs was an
easy way to get instant low level test output. We also built a small
stimulator based on a potentiometer (variable resistor) to get valid
input from the ADC pins.

The following TinyOS application programs have been written and tested:
  * Empty - test of port logic and tool chain 
  * mcsatomic - test of atomic and interrupts 
  * mcsBlink - test of LEDs 
  * mcsBlinkTimer - test of Timers using LEDs 
  * mcsSerialTest - test of UART code, simple input/output one char 
  * mcsSerialTest2 - test of multiple byte output 
  * mcsTimerSerialTest - test of UART controlled by Timer interrupts 
  * mcsADC - test of ADC code with Timer and LEDs


3. Development Environment and Tool Chain
====================================================================

The following subsections describe the different development tools,
their selection and interconnection. 

3.1 Selection of Development Tools/Compilers
--------------------------------------------------------------------

A large number of 8051 compilers exist primarily for the DOS and Windows
platforms. We have focused on two popular and regularly updated
compilers: `KEIL`_ and the Small Device C Compiler (SDCC).

`SDCC`_ is an open source project hosted on the Sourceforge website,
whereas the KEIL C51 compiler is a commercial compiler and Integrated
Development Environment (IDE). The debugger for SDCC (SDCDB) is still
fairly experimental. The KEIL suite runs on the Windows platform, and
has a good interactive debugger and simulator. KEIL and SDCC accepts
roughly the same syntactical dialect, which eases the work of moving
between the two compilers.

During our work with SDCC and SDCDB we encountered numerous problems and
bugs. SDCC 2.4.0 suddenly returned 'fatal compiler errors' with no
apparent reason. After an update of SDCC from version 2.4.0 to 2.5.0
(most recent release) the error disappeared, the code compiled, but it
still did not work correctly on the board. We also discovered a serious
problem regarding sign bits in SDCC 2.5.0. SDCC made a type error when
reading a 32 bit signed value. Apparently SDCC did not interpret the
sign bit correctly, so a very small negative number was interpreted as a
very large positive number as if the value was unsigned. KEIL however
interprets the value correctly. The bug was submitted by us and fixed by
the SDCC development team in just two days, but the timer module still
does not work using SDCC.

Our attempts using SDCC's debugger/simulator (SDCDB) was equally
troublesome. SDCDB simply stopped at address 0, and running or stepping
through the code returned us to the UNIX prompt with no error message.
Without SDCDB, we had no debug possibility and we were forced to rethink
the tool chain. We decided to substitute SDCC with the KEIL development
kit. This gave us a working debug environment - with minimal change to
the already produced code. 

3.1.1 Our Recommendation
------------------------------------------------------------------- 

In our experience the SDCC compiler and associated tools are not yet
mature enough to support our development. We recommend pursuing other
alternatives such as KEIL or other compiler suites.

We continue to mention SDCC in the remaining text, because we encourage
the use of open source software and cross-platform development. We hope
SDCC will prove an reliable alternative in the future.

3.2 Tool Chain Overview
--------------------------------------------------------------------

The following figure and sections are an overview of the current tool
chain. The tool chain is based on TinyOS 1.x, NesC 1.1.3, avr-gcc 3.4.3,
PERL v. 5.8.6 and SDCC 2.5.4 or KEIL C51 version 7.20.

Each step in the tool chain will be explained in the section below. ::

              Mangle-
 TinyOS       script
 -----> app.c -----> app_mangled.c --------> app.hex ------> nRF24E1 
  NesC         PERL                SDCC/KEIL         nRFPROG


3.3 Description of the Tool Chain
--------------------------------------------------------------------

The compilation of the TinyOS test program outputs two files, a
'main.exe' file and an 'app.c' file. The 'app.c' file contains all the
needed code to run the TinyOS application. However the C code produced
by NesC cannot be compiled for the 8051 platform directly. 

One solution could be to alter the syntax NesC produces for this
specific platform, by modifying the source for NesC. However as a first
step we chose not to make changes to NesC, but instead changed the
content of the NesC output file 'app.c'. We inserted an extra step in
the tool chain in the form of a mangle script. The mangle script works
as the rope, tying the output from NesC to the input of SDCC or KEIL.

After running the mangling script on the 'app.c' file we obtain an
'app_mangled.c' file which can be compiled by either SDCC or KEIL. This
produces a hex file that is transferred to the chip by the nRFPROG
software.

3.4 Description of the Mangling Script
--------------------------------------------------------------------

The mangling script is written in PERL, a commonly used general purpose
scripting language with powerful pattern matching capabilities and
extensive handling of regular expressions. The mangle script handles all
currently known problems, and it can easily be expanded to handle
additional alterations.

To run the mangle script use the following syntax:

"./sdccMangleAppC.pl -KEIL -file build/mcs51/app.c >
  build/mcs51/app_mangled.c" 

or 

"./sdccMangleAppC.pl -SDCC -file build/mcs51/app.c > 
  build/mcs51/app_mangled.c"

The 'sdccMangleAppC.pl' script handles a number of needed alterations:

  * it alters the SFR and SBIT declarations for SDCC and KEIL
    respectively
  * it convert 64 bit data types to 32 bit 
  * it alters the reserved SDCC keyword data to _data 
  * it removes inlining directives 
  * it removes preprocessor line numbering 
  * it alters $ in identifiers to underscore 
  * it alters GCC interrupt declaration to SDCC syntax

Each of these alterations will be explained in the sections below.

3.4.1 SFR and SBIT Declarations
--------------------------------------------------------------------

In order to make TinyOS accept the 8051 special function registers (SFR)
and special bit variables (SBIT), we have included them into the TinyOS
8051 platform folder as a 8051.h file.

SFRs are located on an address dividable by 8, whereas an SBIT addresses
a specific bit within these SFR. 

In order to make TinyOS accept the SFRs we have type defined them in the
NesC code as:

  typedef int sfr; 
  sfr P0 __attribute((x80));

which is altered to

  //typedef int sfr;
  sfr at 0x80 P0;

for the SDCC compiler in the mangle script and

  sfr P0 = 0x80;

for the KEIL compiler and similar for the SBIT declarations.

NOTE: The SDCC website refers to a PERL script (keil2sdcc.pl - last
updated June 2003) for translating SFR and SBIT declarations from KEIL
to SDCC, but it produces code with illegal syntax, so either do not use
it, or alter it to produce code with the right syntax.

3.4.2 SDCC/KEIL Data Types
--------------------------------------------------------------------

TinyOS and SDCC/KEIL do not support the same data types, so some
alterations were needed to compile the code with SDCC and KEIL.

SDCC/KEIL supports the following data types:
  - char (8 bits, 1 byte)
  - short (16 bits, 2 bytes)
  - int (16 bits, 2 bytes)
  - long (32 bit, 4 bytes)
  - float (32 bit, 4 bytes).

TinyOS supports an extra data type - 64 bit long long (u)int64_t. Since
we are working with software that does not support this data type, on a
very small hardware memory model, we decided to change the NesC 64 bit
data types to 32 bit. This is done in the mangling script.

3.4.3 Reserved Keywords in SDCC
--------------------------------------------------------------------

A number of keywords are reserved in SDCC. Half of them represent a
directive to the compiler, defining which memory segment on the nRF24E1
the specific lines of code refer to. To ensure that the developer does
not break code by unintentionally and unaware of their effect use them
fx. as a variable name in the NesC code, they need to be replaced or
altered to something else, e.g. data to _data, before compiling for
SDCC. Right now the mangle script only handles the reserved keyword
data. None of the other keywords except SFR, SBIT and interrupt are
currently in use in the code. This might pose as a problem to future
work, but the mangle script can easily be expanded to handle misuse of
the other keywords.

However, if the code size increases significantly in the future, it
might be nessecary to insert the keywords into the code, to support the
architectures segmented memory model. Right now, everything is stored in
the directly addressable memory segment, which is quite small.

The reserved keywords are:
  * data / near 
  * xdata / far 
  * idata / pdata 
  * code 
  * bit 
  * SFR / SBIT 
  * interrupt
  * critical

Variables declared with keyword storage class data/near will be