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

[David Gay]

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

Modified Files:
      Tag: tinyos-2_0_devel-BRANCH
	tep103.txt 
Log Message:
reorganise a bit
remove strataflash examples as they are unfinished


Index: tep103.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/Attic/tep103.txt,v
retrieving revision 1.1.2.4
retrieving revision 1.1.2.5
diff -C2 -d -r1.1.2.4 -r1.1.2.5
*** tep103.txt	1 Jun 2006 23:52:44 -0000	1.1.2.4
--- tep103.txt	2 Jun 2006 00:19:09 -0000	1.1.2.5
***************
*** 161,195 ****
  --------------------------------------------------------------------
  
! a. Implementation: system dependent
! b. Presentation: chip (or chip family) dependent; common HPL for same chip
!    (or chip family) on different systems
! c. Stateless
! d. Atmel 45DB family low-level interfaces (``HplAt45db`` interface)
  
!    flash->buffer, buffer->flash, compare buffer to flash, erase page,
!    read, compute crc, write
  
!    A generic implementation of the HPL is included allowing platforms
!    to just provide SPI and chip selection interfaces.
  
! e. Intel Strataflash  
  
!    write data, erase, lock/unlock blocks, read config data, etc.
!    details omitted - main interesting point is lack of reads, as
!    device is memory mapped
  
! f. M25P family (``Stm25pSpi`` interface)
  
!    r/w data, erase (sector or chip), r/w status, etc
!    (full details omitted)
  
  3.2 Hardware Adaptation Layer (HAL)
  --------------------------------------------------------------------
  
! a. Implementation: chip dependent
! b. Presentation: chip dependent
! c. Atmel AT45DB:
  
! ::
  
     interface At45db {
--- 161,231 ----
  --------------------------------------------------------------------
  
! The flash HPL has a chip-dependent, system-independent interface. The
! implementation of this HPL is system-dependent. The flash HPL SHOULD be
! stateless. In many cases, families of flash chips can share a common HPL
! interface.
  
! Some examples:
  
! - The Atmel AT45DB family HPL is: ::
  
!     configuration HplAt45dbC {
!       provides interface;
!     } ...
  
!   The ``HplAt45db`` interface has flash->buffer, buffer->flash, compare
!   buffer to flash, erase page, read, compute CRC, and write operations.  A
!   generic, system-independent implementation of the HPL
!   (``HplAt45dbByteC``) is included allowing platforms to just provide SPI
!   and chip selection interfaces.
  
!   Different members of the AT45DB family are supported by specifying a few
!   constants (number of pages, page size).
  
! - The M25P family HPL is: ::
! 
!     configuration Stm25pSpiC {
!       provides interface Init;
!       provides interface Resource;
!       provides interface Stm25pSpi;
!     }
! 
!    The ``Stm25pSpi`` interface has read, write, compute CRC, sector erase
!    and block erase operations. The implementation of this HPL is
!    system-independent, built over a few system-dependent components
!    providing SPI and chip selection interfaces.
! 
! Note that these two examples have different resource management policies:
! the AT45DB encapsulates resource acquisition and release within each
! operation, while the M25P family requires that HPL users acquire and
! release the resource itself.
  
  3.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
! power-manage the underlying flash chip.
  
! We show here a couple of flash HAL's.
! 
! The AT45DB HAL is: ::
! 
!   configuration At45dbC
!   {
!     provides {
!       interface At45db;
!       interface Resource[uint8_t client];
!       interface ResourceController;
!       interface ArbiterInfo;
!     }
!   } ...
! 
! Note that the AT45DB HAL resource management is independent of the
! underlying HPL's power management. The motivation for this is that
! individual flash operations may take a long time, so it may be desirable to
! release the flash's bus during long-running operations. The ``At45db``
! interface is: ::
  
     interface At45db {
***************
*** 220,248 ****
                               at45pageoffset_t n, uint16_t baseCrc);
       event void computeCrcDone(error_t error, uint16_t crc);
- 
     }
  
! d. Intel Strataflash (should extend to other memory-mapped NOR flashes):
! 
! ::
! 
!    interface { /* In flux until higher level stuff written */
! 
!      command error_t lockRange(storage_addr_t_t from, storage_len_t count);
!      command error_t unlockRange(storage_addr_t from, storage_len_t count);
! 
!      /* These return to read array mode when done */
!      command error_t write(storage_addr_t addr, void* buf, storage_len_t len);
!      event   void    writeDone(storage_addr_t addr, void* buf, 
!                                storage_len_t len, error_t error);
! 
!      command error_t erase(storage_addr_t block);
!      event   void    eraseDone(storage_addr_t block, error_t success);
! 
!    }
  
! e. STMicroelectronics M25P:
  
! ::
  
     interface Stm25pSector {
--- 256,270 ----
                               at45pageoffset_t n, uint16_t baseCrc);
       event void computeCrcDone(error_t error, uint16_t crc);
     }
  
! The STMicroelectronics M25P HAL is: ::
  
!   configuration Stm25pSectorC {
!     provides interface Resource as ClientResource[storage_volume_t volume];
!     provides interface Stm25pSector as Sector[storage_volume_t volume];
!     provides interface Stm25pVolume as Volume[storage_volume_t volume];
!   }
  
! and the ``Stm25pSector`` interface is: ::
  
     interface Stm25pSector {
***************
*** 270,276 ****
  --------------------------------------------------------------------
  
! a. Implementation: Chip dependent
! b. Presentation: application-level OS service (see discussion in Section 2)
! c. Volumes
  
     The division of the flash chip into fixed-size volumes is specified by
--- 292,300 ----
  --------------------------------------------------------------------
  
! The HIL implementations are system-independent, but chip (family)
! dependent. They implement the three storage abstractions and
! volume structure discussed in Section 2.
! 
! a. Volumes
  
     The division of the flash chip into fixed-size volumes is specified by
***************
*** 314,440 ****
     instance.
  
! d. Large object interface:
  
! Large objects are accessed by instantiating a BlockStorageC component
! which takes a volume id argument: ::
  
!   generic configuration BlockStorageC(volume_id_t volid) {
!     provides {
!       interface BlockWrite;
!       interface BlockRead;
!     }
!   } ...
  
! The ``BlockRead`` and ``BlockWrite`` interfaces contain the following
! operations: ::
  
!    interface BlockWrite {
!      command error_t write(storage_addr_t addr, void* buf, 
!                            storage_len_t len);
!      event void writeDone(storage_addr_t addr, void* buf, 
!                           storage_len_t len, error_t error);
  
!      command error_t erase();
!      event   void    eraseDone(error_t result);
!      
!      command error_t commit();
!       event  void    commitDone(error_t result);
!    }
  
!    interface BlockRead {
!      command error_t read(addr_t addr, void* dest, addr_t len);
!      event   void    readDone(storage_error_t result);
!      
!      command error_t verify();
!      event   void    verifyDone(storage_error_t result);
  
!      command error_t computeCrc(storage_addr_t addr, storage_len_t len,
!                                 uint16_t baseCrc);
!      event   void    computeCrcDone(storage_addr_t addr, storage_len_t len, 
! 				    uint16_t crc, error_t error );
  
!      command storage_len_t getSize();
!    }
  
! e. Large sequential objects:
  
! Large sequential objects are accessed by instantiating a LogStorageC
! component which takes a volume id and a boolean argument: ::
  
!   generic configuration LogStorageC(volume_id_t volid, bool circular) {
!     provides {
!       interface LogWrite;
!       interface LogRead;
!     }
!   } ...
  
! If the ``circular`` argument is TRUE, the log is circular; otherwise
! it is linear.
  
! The ``LogRead`` and ``LogWrite`` interfaces contain the following
! operations: ::
  
!    interface LogWrite {
!      command error_t erase();
!      event   void    eraseDone(storage_error_t success);
  
!      command error_t append(void* buf, storage_len_t len);
!      event   void    appendDone(void* buf, storage_len_t len, error_t error);
  
!      command storage_cookie_t currentOffset();
  
!      command error_t sync();
!      event   void    syncDone(storage_error_t success);
!    }
  
!    interface LogRead {
!      command error_t read(void* buf, storage_len_t len);
!      event   void    readDone(void* buf, storage_len_t len, error_t error);
  
!      command storage_cookie_t currentOffset();
  
!      command error_t seek(storage_cookie_t cookie);
!      event   void    seekDone(error_t error);
  
!      command storage_len_t getSize();
!    }
  
! f. Small objects:
  
! Small objects are accessed by instantiating a ConfigStorageC component
! which takes a volume id argument: ::
  
!   generic configuration ConfigStorageC(volume_id_t volid) {
!     provides {
!       interface Mount;
!       interface ConfigStorage;
!     }
!   } ...
  
! A small object MUST be mounted (see the ``Mount`` interface) before 
! the first use.
  
! The ``Mount`` and ``ConfigStorage`` interfaces contain the following
! operations: ::
  
!    interface Mount {
!      command error_t mount();
!      event void mountDone(error_t error);
!    }
  
!    interface ConfigStorage {
!      command error_t read(addr_t addr, void* dest, addr_t len);
!      event   void    readDone(storage_error_t result);
  
!      command error_t write(addr_t addr void* source, addr_t len);
!      event   void    writeDone(storage_error_t result);
  
!      command error_t commit();
!      event   void    commitDone(storage_error_t result);
  
!      command storage_len_t getSize();
  
!      command bool valid();
!    }
  
  4. Implementation
--- 338,464 ----
     instance.
  
! b. Large object interface:
  
!   Large objects are accessed by instantiating a BlockStorageC component
!   which takes a volume id argument: ::
  
!     generic configuration BlockStorageC(volume_id_t volid) {
!       provides {
! 	interface BlockWrite;
! 	interface BlockRead;
!       }
!     } ...
  
!   The ``BlockRead`` and ``BlockWrite`` interfaces contain the following
!   operations: ::
  
!      interface BlockWrite {
!        command error_t write(storage_addr_t addr, void* buf, 
! 			     storage_len_t len);
!        event void writeDone(storage_addr_t addr, void* buf, 
! 			    storage_len_t len, error_t error);
  
!        command error_t erase();
!        event   void    eraseDone(error_t result);
  
!        command error_t commit();
! 	event  void    commitDone(error_t result);
!      }
  
!      interface BlockRead {
!        command error_t read(addr_t addr, void* dest, addr_t len);
!        event   void    readDone(storage_error_t result);
  
!        command error_t verify();
!        event   void    verifyDone(storage_error_t result);
  
!        command error_t computeCrc(storage_addr_t addr, storage_len_t len,
! 				  uint16_t baseCrc);
!        event   void    computeCrcDone(storage_addr_t addr, storage_len_t len, 
! 				      uint16_t crc, error_t error );
  
!        command storage_len_t getSize();
!      }
  
! c. Large sequential objects:
  
!   Large sequential objects are accessed by instantiating a LogStorageC
!   component which takes a volume id and a boolean argument: ::
  
!     generic configuration LogStorageC(volume_id_t volid, bool circular) {
!       provides {
! 	interface LogWrite;
! 	interface LogRead;
!       }
!     } ...
  
!   If the ``circular`` argument is TRUE, the log is circular; otherwise
!   it is linear.
  
!   The ``LogRead`` and ``LogWrite`` interfaces contain the following
!   operations: ::
  
!      interface LogWrite {
!        command error_t erase();
!        event   void    eraseDone(storage_error_t success);
  
!        command error_t append(void* buf, storage_len_t len);
!        event   void    appendDone(void* buf, storage_len_t len, error_t error);
  
!        command storage_cookie_t currentOffset();
  
!        command error_t sync();
!        event   void    syncDone(storage_error_t success);
!      }
  
!      interface LogRead {
!        command error_t read(void* buf, storage_len_t len);
!        event   void    readDone(void* buf, storage_len_t len, error_t error);
  
!        command storage_cookie_t currentOffset();
  
!        command error_t seek(storage_cookie_t cookie);
!        event   void    seekDone(error_t error);
  
!        command storage_len_t getSize();
!      }
  
! d. Small objects:
  
!   Small objects are accessed by instantiating a ConfigStorageC component
!   which takes a volume id argument: ::
  
!     generic configuration ConfigStorageC(volume_id_t volid) {
!       provides {
! 	interface Mount;
! 	interface ConfigStorage;
!       }
!     } ...
  
!   A small object MUST be mounted (see the ``Mount`` interface) before 
!   the first use.
  
!   The ``Mount`` and ``ConfigStorage`` interfaces contain the following
!   operations: ::
  
!      interface Mount {
!        command error_t mount();
!        event void mountDone(error_t error);
!      }
  
!      interface ConfigStorage {
!        command error_t read(addr_t addr, void* dest, addr_t len);
!        event   void    readDone(storage_error_t result);
  
!        command error_t write(addr_t addr void* source, addr_t len);
!        event   void    writeDone(storage_error_t result);
  
!        command error_t commit();
!        event   void    commitDone(storage_error_t result);
! 
!        command storage_len_t getSize();
! 
!        command bool valid();
!      }
  
  4. Implementation