[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep103.txt, 1.1.2.12, 1.1.2.13

Fri Sep 22 11:43:51 PDT 2006

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

Modified Files:
      Tag: tinyos-2_0_devel-BRANCH
	tep103.txt 
Log Message:
move to devel branch

Index: tep103.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep103.txt,v
retrieving revision 1.1.2.12
retrieving revision 1.1.2.13
diff -C2 -d -r1.1.2.12 -r1.1.2.13
*** tep103.txt	21 Jun 2006 17:44:10 -0000	1.1.2.12
--- tep103.txt	22 Sep 2006 18:43:49 -0000	1.1.2.13
***************
*** 47,66 ****

! 		   NOR                AT45DB         NAND

!   Erase	       :  Slow (seconds)      Fast (ms)	     Fast (ms)
!   Erase unit   :  Large (64KB-128KB)  Small (256B)   Medium (8K-32KB)
!   Writes       :  Slow (100s kB/s)    Slow (60kB/s)  Fast (MBs/s)
!   Write unit   :  1 bit               256B           100's of bytes
!   Bit-errors   :  Low                 Low            High (requires ECC, 
!                                                      bad-block mapping)
!   Read	       :  Fast*               Slow+I/O bus   Fast (but limited by 
!                                                      I/O bus)
!   Erase cycles :  10^4 - 10^5         10^4 **        10^5 - 10^7
!   Intended use :  Code storage        Data storage   Data storage
!   Energy/byte  :  1uJ                 1uJ            .01uJ

!   *  Intel Mote2 NOR flash is memory mapped (reads are very fast and can
!      directly execute code)
    ** Or infinite? Data sheet just says that every page within a sector
       must be written every 10^4 writes within that sector
--- 47,67 ----

! 		   NOR                AT45DB             NAND
! 		   (ex: ST M25P40,			 (ex: Samsung
! 		   Intel PXA27x)			 K9K1G08R0B)

!   Erase	       :  Slow (seconds)      Fast (ms)	         Fast (ms)
!   Erase unit   :  Large (64KB-128KB)  Small (256B)       Medium (8KB-32KB)
!   Writes       :  Slow (100s kB/s)    Slow (60kB/s)      Fast (MBs/s)
!   Write unit   :  1 bit               256B               100's of bytes
!   Bit-errors   :  Low                 Low                High (requires ECC, 
!                                                          bad-block mapping)
!   Read	       :  Bus limited*        Slow+Bus limited   Bus limited
!   Erase cycles :  10^4 - 10^5         10^4 **            10^5 - 10^7
!   Intended use :  Code storage        Data storage       Data storage
!   Energy/byte  :  1uJ                 1uJ                .01uJ

!   *  M25P40 reads are limited by the use of a 25MHz SPI bus. The PXA27x flash is
!      memory mapped (reads are very fast and can directly execute code).
    ** Or infinite? Data sheet just says that every page within a sector
       must be written every 10^4 writes within that sector
***************
*** 69,73 ****
  derived from the timing and power consumption of erase and write operations
  (for NOR flash, values are for the STMicroelectronics M25P family, for NAND
! flash, values are from a Samsung datasheet). Energy/byte for reads appears
  to depend mostly on how long the read takes (the power consumptions are
  comparable), i.e., on the efficiency of the bus + processor.
--- 70,74 ----
  derived from the timing and power consumption of erase and write operations
  (for NOR flash, values are for the STMicroelectronics M25P family, for NAND
! flash, values are from the Samsung datasheet). Energy/byte for reads appears
  to depend mostly on how long the read takes (the power consumptions are
  comparable), i.e., on the efficiency of the bus + processor.
***************
*** 94,98 ****
    reimplemented for these other chips, in part because it does not 
    support some applications (e.g., network reprogramming) very well.
!   
  One approach to hiding the differences between different flash chips is to
  provide a disk-like, block interface (with, e.g., 512B blocks). This is the
--- 95,102 ----
    reimplemented for these other chips, in part because it does not 
    support some applications (e.g., network reprogramming) very well.
! 
! 2. Storage in TinyOS 2.x
! ====================================================================
! 
  One approach to hiding the differences between different flash chips is to
  provide a disk-like, block interface (with, e.g., 512B blocks). This is the
***************
*** 107,127 ****
    table is too expensive on many mote-class devices.

! Another approach to supporting multiple flash chips is to build a
! file system (like Matchbox) which can be implemented for multiple
! flash chips. However, TinyOS is currently targeted at running a 
! single application, and many applications know their storage needs
! in advance: for instance, a little space for configuration data, and
! everything else for a log of all sampled data. In such cases, the
! flexibility offered by a filing system (e.g., arbitrary numbers of
! files) is overkill, and may come at the expense of implementation
! and runtime complexity.

! Instead, TinyOS 2.x, divides flash chips into separate volumes (with
! sizes fixed at compile-time). Each volume provides a single storage
! abstraction (the abstraction defines the format). So far there are three
! such abstractions: large objects written in a single session,
! small objects with arbitrary reads and writes, and logs. This approach
! has two advantages:

  - Each abstraction is relatively easy to implement on a new flash chip, and
    has relatively little overhead.
--- 111,147 ----
    table is too expensive on many mote-class devices.

! A second approach is to provide a generic low-level interface providing
! operations (read, write, erase) corresponding to the basic flash
! operations, along with information describing the flash chip's layout
! (minimum write and erase unit, timing information, etc). However,
! we believe that the large differences between NAND and NOR flash (see the
! table above), in particular the differences in reliability, write and
! erase units, make the design of a useful generic low-level interface
! tricky at best. 

! We thus believe it is best, for now at least, to define high-level
! storage abstractions that are useful for sensor network applications,
! and leave their implementation up to each flash chip - such abstractions
! will be necessary anyway. We leave open the possibility that a future
! TEP may define portable lower-level flash interfaces (either for all
! flash chips, or, e.g., for NOR-family flashes). Such low-level
! interfaces would allow implementations of the storage abstractions
! defined in this TEP to be used for multiple flash chips.
! 
! This TEP describes three high-level storage abstractions: large objects
! written in a single session, small objects with arbitrary reads and
! writes, and logs. TinyOS 2.x, divides flash chips into separate volumes
! (with sizes fixed at compile-time). Each volume provides a single
! storage abstraction (the abstraction defines the format).

+ We prefer the use of single abstractions over fixed-size volumes over
+ the use of a more general filing system (like Matchbox) for several
+ reasons:
+      
+ - TinyOS is currently targeted at running a single application, and many
+   applications know their storage needs in advance: for instance, a
+   little space for configuration data, and everything else for a log of
+   all sampled data. In such cases, the flexibility offered by a filing
+   system (e.g., arbitrary numbers of files) is overkill,
  - Each abstraction is relatively easy to implement on a new flash chip, and
    has relatively little overhead.
***************
*** 133,152 ****
    the same number of time, to maximise flash chip lifetime).

! New abstractions (including a filing system) can easily be added to this
! framework, or can be built on top of these abstractions.

  The rest of this TEP covers some principles for the organisation of
! flash chips (Section 2), then describes the flash volumes and
! storage abstractions in detail (Section 3).

! 2. HPL/HAL/HIL Architecture
  ====================================================================

! The flash chip architecture dollows the three-layer Hardware
  Abstraction Architecture (HAA), with each chip providing a presentation
! layer (HPL, Section 2.1), adaptation layer (HAL, Section 2.2) and
! platform-independent interface layer (the storage abstractions described in
! Section 3) [2_]. The implementation of these layers SHOULD be found in the
  ``tos/chips/CHIPNAME`` directory. If a flash chip is part of a larger
  family with a similar interface, the HAA SHOULD support all family members
--- 153,172 ----
    the same number of time, to maximise flash chip lifetime).

! New abstractions (including a filing system...) can easily be added to
! this framework.

  The rest of this TEP covers some principles for the organisation of
! flash chips (Section 3), then describes the flash volumes and
! storage abstractions in detail (Section 4).

! 3. HPL/HAL/HIL Architecture
  ====================================================================

! The flash chip architecture follows the three-layer Hardware
  Abstraction Architecture (HAA), with each chip providing a presentation
! layer (HPL, Section 3.1), adaptation layer (HAL, Section 3.2) and
! platform-independent interface layer (HIL, Section 3.3) [2_]. 
! The implementation of these layers SHOULD be found in the
  ``tos/chips/CHIPNAME`` directory. If a flash chip is part of a larger
  family with a similar interface, the HAA SHOULD support all family members
***************
*** 157,165 ****

! 2.1 Hardware Presentation Layer (HPL)
  --------------------------------------------------------------------

! The flash HPL has a chip-dependent, system-independent interface. The
! implementation of this HPL is system-dependent. The flash HPL SHOULD be
  stateless. 

--- 177,185 ----

! 3.1 Hardware Presentation Layer (HPL)
  --------------------------------------------------------------------

! The flash HPL has a chip-dependent, platform-independent interface. The
! implementation of this HPL is platform-dependent. The flash HPL SHOULD be
  stateless. 

***************
*** 172,179 ****
  particular flash chip found on the platform.

! 2.2 Hardware Adaptation Layer (HAL)
  --------------------------------------------------------------------

! The flash HAL has a chip-dependent, system-independent interface and
  implementation. Flash families with a common HPL SHOULD have a common
  HAL. Flash HAL's SHOULD expose a ``Resource`` interface and automatically
--- 192,199 ----
  particular flash chip found on the platform.

! 3.2 Hardware Adaptation Layer (HAL)
  --------------------------------------------------------------------

! The flash HAL has a chip-dependent, platform-independent interface and
  implementation. Flash families with a common HPL SHOULD have a common
  HAL. Flash HAL's SHOULD expose a ``Resource`` interface and automatically
***************
*** 183,195 ****
  abstractions that interact cleanly with the rest of the flash system.

! 3. Non-Volatile Storage Abstracitons in TinyOS 2.x 
  ===================================================================

! The HIL implementations are system-independent, but chip (family)
  dependent. They implement the three storage abstractions and
  volume structure discussed in the introduction.

! 3.1. Volumes
  -------------------------------------------------------------------

--- 203,228 ----
  abstractions that interact cleanly with the rest of the flash system.

+ 3.3 Hardware Interface Layer (HIL)
+ --------------------------------------------------------------------

! Each flash chip MUST provide implementations of the storage abstractions
! described in Section 4. These abstractions MUST be presented in
! components named ``ChipAbstractionC``, e.g., ``At45dbLogStorageC``.
! 
! Each platform MUST have ``AbstractionC`` components (e.g., ``LogStorageC``)
! implementing the storage abstractions of Section 4. Platforms with a single
! storage chip SHOULD simply make ``AbstractionC`` be a simple configuration
! wrapping the appropriate ``ChipAbstractionC`` component. Platforms with
! multiple storage chips SHOULD redirect uses of ``AbstractionC`` to the 
! appropriate storage chip, based on the requested volume.
! 
! 4. Non-Volatile Storage Abstractions
  ===================================================================

! The HIL implementations are platform-independent, but chip (family)
  dependent. They implement the three storage abstractions and
  volume structure discussed in the introduction.

! 4.1. Volumes
  -------------------------------------------------------------------

***************
*** 213,218 ****
  (i.e. a given specification should always have the same resulting physical
  allocation on a given chip) and the result MUST be placed in the build
! directory. When not specified, the tool may give any suitable physical
! location to a volume. If there is any reason that the physical allocation
  cannot be satisfied, an error should be given at compile time. The tool
  SHOULD be named ``tos-storage-CHIPNAME`` and be distributed with the other
--- 246,251 ----
  (i.e. a given specification should always have the same resulting physical
  allocation on a given chip) and the result MUST be placed in the build
! directory. When not specified, the tool picks a suitable physical
! location for a volume. If there is any reason that the physical allocation
  cannot be satisfied, an error should be given at compile time. The tool
  SHOULD be named ``tos-storage-CHIPNAME`` and be distributed with the other
***************
*** 234,238 ****

! 3.2 Large objects
  ------------------------------------------------------------------

--- 267,271 ----

! 4.2 Large objects
  ------------------------------------------------------------------

***************
*** 248,257 ****

  - A large object ranges from a few kilobytes upwards.
! - A large object must be erased before use.
! - A large object must be committed to ensure it survives a reboot or crash;
!   after a commit no more writes may be performed.
! - Random reads are allowed.
! - Random writes are allowed are allowed between erase and commit; data
!   cannot be overwritten.

  Large objects are accessed by instantiating a BlockStorageC component
--- 281,289 ----

  - A large object ranges from a few kilobytes upwards.
! - A large object is erased before the first write.
! - A commit ensures that a large object survives a reboot or crash
! - Reads are unrestricted
! - Writes can only be performed between an erase and a commit
! - Each byte can only be written once between an erase and a commit

  Large objects are accessed by instantiating a BlockStorageC component
***************
*** 269,279 ****

  - ``BlockWrite.erase``: erase the volume. After a reboot or a commit, a
!   volume must be erased before it can be written to.

! - ``BlockWrite.write``: write some bytes starting at a given offset. Each
!   byte can only be written once between an erase and the subsequent commit.

! - ``BlockWrite.commit``: commit all writes to a given volume. No writes can
!   be performed after a commit until a subsequent erase.

  - ``BlockRead.verify``: verify that the volume contains the results of a
--- 301,314 ----

  - ``BlockWrite.erase``: erase the volume. After a reboot or a commit, a
!   volume MUST be erased before it can be written to.

! - ``BlockWrite.write``: write some bytes starting at a given
!   offset. Each byte MUST NOT be written more than once between an erase
!   and the subsequent commit. Writes MUST NOT be performed between a
!   commit and the subsequent erase.

! - ``BlockWrite.commit``: commit all writes to a given volume. Writes
!   MUST NOT be performed after a commit until a subsequent erase. Commit
!   MUST be called to ensure written data survives a reboot or crash.

  - ``BlockRead.verify``: verify that the volume contains the results of a
***************
*** 292,299 ****

! 3.3 Logging
  ------------------------------------------------------------------

! Event and reuslt logging is a common requirement in sensor
  networks. Such logging should be reliable (a mote crash should not
  lose data). It should also be easy to extract data from the log,
--- 327,334 ----

! 4.3 Logging
  ------------------------------------------------------------------

! Event and result logging is a common requirement in sensor
  networks. Such logging should be reliable (a mote crash should not
  lose data). It should also be easy to extract data from the log,
***************
*** 302,312 ****
  overwritten when the volume is full).

! The ``LogStorageC`` abstraction supports these requirements.  The log is record
! based: each call to ``LogWrite.append`` (see below) creates a new
! record. On failure (crash or reboot), the log is guaranteed to only lose
! whole records from the end of the log. Additionally, once a circular log
! wraps around, calls to ``LogWrite.append`` only lose whole records from the
! beginning of the log. These guarantees mean that applications do not to
! have worry about incomplete or inconsistent log entries.

  Logs are accessed by instantiating a LogStorageC component which takes a
--- 337,346 ----
  overwritten when the volume is full).

! The ``LogStorageC`` abstraction supports these requirements.  The log is
! record based: each call to ``LogWrite.append`` (see below) creates a new
! record. On failure (crash or reboot), the log MUST only lose whole
! records from the end of the log. Additionally, once a circular log wraps
! around, calls to ``LogWrite.append`` MUST only lose whole records from
! the beginning of the log. 

  Logs are accessed by instantiating a LogStorageC component which takes a
***************
*** 327,336 ****
  ``LogRead.currentOffset`` and ``LogRead.getSize``):

! - ``LogWrite.erase``: erase the log.

  - ``LogWrite.append``: append some bytes to the log. In a circular log,
    this may overwrite the current read position. In this case, the 
!   read position is implicitly advanced to the log's current beginning
    (i.e., as if ``LogRead.seek`` had been called with ``SEEK_BEGINNING``).

    Each append creates a separate record. Log implementations may have a
--- 361,373 ----
  ``LogRead.currentOffset`` and ``LogRead.getSize``):

! - ``LogWrite.erase``: erase the log. A log MUST be erased (possibly in
!   some previous session) before any other operation can be used.

  - ``LogWrite.append``: append some bytes to the log. In a circular log,
    this may overwrite the current read position. In this case, the 
!   read position MUST be advanced to the log's current beginning
    (i.e., as if ``LogRead.seek`` had been called with ``SEEK_BEGINNING``).
+   Additionally, the ``LogWrite.appendDone`` event reports whenever, in a
+   circular log, an append erases old records.

    Each append creates a separate record. Log implementations may have a
***************
*** 340,344 ****
  - ``LogWrite.sync``: guarantee that data written so far will not be lost to
    a crash or reboot (it can still be overwritten when a circular log wraps
!   around). Using ``sync`` may waste some space in the log.

  - ``LogWrite.currentOffset``: return cookie representing current
--- 377,381 ----
  - ``LogWrite.sync``: guarantee that data written so far will not be lost to
    a crash or reboot (it can still be overwritten when a circular log wraps
!   around). Using ``sync`` MAY waste some space in the log.

  - ``LogWrite.currentOffset``: return cookie representing current
***************
*** 348,351 ****
--- 385,395 ----
    the log and advance the read position.

+   ``LogStorageC`` implementations MUST include error detection codes
+   to increase the likelihood of detection of corrupted or invalid log
+   data. Data returned by a successful read MUST have passed this
+   error detection check. The behaviour on failure of this check is
+   unspecified (e.g., the at45db believes as if the end of the log has
+   been reached; other implementations may behave differently).
+ 
  - ``LogRead.currentOffset``: return cookie representing current
    read position (for use with ``LogRead.seek``).
***************
*** 360,376 ****
    the oldest record still present in the log.

! - ``LogRead.getSize``: return an approximation of the log's capacity.
!   Uses of ``sync`` and other overhead may reduce this number.

  For full details on arguments, etc, see the comments in the interface
  definitions.

! 3.4 Small objects:
  ------------------------------------------------------------------

! Sensor network applications may need to store configuration data, e.g.,
! mote id, radio frequency, sample rates, etc. Such data is not large, but
  losing it may lead to a mote misbehaving or losing contact with the
  network.
--- 404,431 ----
    the oldest record still present in the log.

!   After reboot, the current read position is ``SEEK_BEGINNING``.
! 
! - ``LogRead.getSize``: return an approximation of the log's capacity
!   in bytes. Uses of ``sync`` and other overhead may reduce this number.

  For full details on arguments, etc, see the comments in the interface
  definitions.

+ Note that while each call to ``append`` logically creates a separate
+ record, the ``LogStorageC`` API does not report record
+ boundaries. Additionally, crashes, reboots, and appends after
+ wrap-around in a circular log can cause the loss of multiple consecutive
+ records. Taken together, these restrictions mean that a ``LogStorageC``
+ implementation MAY internally aggregate several consecutive appends into
+ a single record. However, the guarantee that only whole records are lost
+ is sufficient to ensure that applications do not to have worry about
+ incomplete or inconsistent log entries.

! 4.4 Small objects:
  ------------------------------------------------------------------

! Sensor network applications need to store configuration data, e.g.,
! mote identity, radio frequency, sample rates, etc. Such data is not large, but
  losing it may lead to a mote misbehaving or losing contact with the
  network.
***************
*** 423,427 ****
  definitions.

! 4. Implementations
  ====================================================================

--- 478,482 ----
  definitions.

! 5. Implementations
  ====================================================================

***************
*** 431,435 ****

! 5. Authors' Addresses
  ====================================================================

--- 486,490 ----

! 6. Authors' Addresses
  ====================================================================

***************
*** 451,455 ****
  | email - jhui at archedrock.com

! 6. Citations
  ====================================================================

--- 506,510 ----
  | email - jhui at archedrock.com

! 7. Citations
  ====================================================================