[Tinyos-contrib-commits] CVS: tinyos-1.x/contrib/umass LICENSE, NONE, 1.1 README, NONE, 1.1

[Gaurav]

Update of /cvsroot/tinyos/tinyos-1.x/contrib/umass
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv17795

Added Files:
	LICENSE README 
Log Message:
Added contrib/umass containing Capsule -- a storage system for sensors

--- NEW FILE: LICENSE ---
/**********************************************************************
Copyright 2006 The University of Massachusetts -- Amherst.
All Rights Reserved.

Permission to use, copy, modify, and distribute this software and its
documentation for any purpose, without fee, and without written
agreement is hereby granted, provided that the above copyright notice
and the following three paragraphs appear in all copies and derivatives
of this software.

IN NO EVENT SHALL THE UNIVERSITY OF MASSACHUSETTS BE LIABLE TO ANY PARTY
FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF
THE UNIVERSITY OF MASSACHUSETTS HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

THE UNIVERSITY OF MASSACHUSETTS SPECIFICALLY DISCLAIMS ANY WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE SOFTWARE
PROVIDED HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
MASSACHUSETTS HAS NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES,
ENHANCEMENTS, OR MODIFICATIONS.

The authors of this software are Gaurav Mathur {gmathur at cs.umass.edu} and
Peter Desnoyers {pjd at cs.umass.edu}
at the Sensors Laboratory (http://sensors.cs.umass.edu),
University of Massachusetts, Amherst. Any publications based on the
use of this software or its derivatives must clearly acknowledge such
use in the text of the publication.
**********************************************************************/

--- NEW FILE: README ---
--------------------------------------------------------------
                         Capsule v0.9
          http://sensors.cs.umass.edu/projects/capsule
    
                      Sensors Laboratory
             University of Massachusetts - Amherst
        Authors: Gaurav Mathur   (gmathur at cs.umass.edu)
                 Peter Desnoyers (pjd at cs.umass.edu)
                 Deepak Ganesan (dganesan at cs.umass.edu)
--------------------------------------------------------------

NOTE: THE LICENSE FOR THIS SOFTWARE HAS BEEN PROVIDED IN THE "LICENSE" FILE
      IN THIS DIRECTORY.

This distribution includes:
- The Capsule storage system
- Driver code for the NAND flash (independent of Capsule)

Directory Structure:
--------------------
The umass directory should be placed in contrib/ directory of the TinyOS tree

umass - apps
      - tos
            - interfaces
            - system
            - lib
            - platform
              ...

Applications can be placed in the apps/ tree. The Makefile present in the apps/ directory
should allow correct code compilation as is.

The sample applications that should be looked at are StressChkpt and StressTest. The other
applications present are old test applications some of which may not compile correctly
as the codebase has undergone extensive modifications -- most of these will be removed from
the final release.


Config:
-------
- It is currently configured to use the Mica2 NOR flash directly. To
  use the NAND flash, comment out "#define PLATFORM_MICA2_NOR" in tos/platform/mica2/platform.h
  Currently one can use the Mica2 NOR flash or the NAND flash in the same application, but not
  both -- this will be fixed in the next release.

- Create a sym-link in tos/platform named micaz and mica2dot pointing to the mica2
  directory -- the codebase for all the 3 platforms is common.

- Each application should have a sizes.h file in its directory which is used for 
  configuring Capsule, enabling/disabling debug messages, etc. 

Misc / Eccentricities:
---------------------
1. Most of the objects have an init method - be sure to call these before you start 
   using the object... all hell might break loose otherwise

2. Be careful to wire StdControl directly to FalC or the flash driver code

3. Be careful about the objects that use the parameterized interfaces (ie. xxx[yyy])
   Look at the wiring of existing applications
   [Some of the internal object code uses the interface number to maintain state about
    the object -- hence, the reason why the interface parameters are important.
    We are currently looking at simplifying this]

4. The storage objects should be initialized in the following order:
   First, call init on the ChunkStorage component
   Second, call init on all the objects
   Third, call init on the Transaction component
   Fourth, call init on the RootDirectory component
   Intuition: The root dir component may trigger a rollback if the system had failed;
    you would want the objects to be correctly initialized before this happens.

5. The Index needs to be saved by your code manually before you can checkpoint it. This is 
   because the index stores everything in an in-memory buffer (to minimize flash 
   operations), and performing a save operation forces a buffer flush.

6. The number of objects instantiated is picked up using uniqueCount(). Thus, it
   is important to use ONLY the following unique Strings when you are wiring object
   instances.
    App.Stream -> StreamM.Stream[unique("Stream")]; // for Stream object
    App.Index -> IndexM.Index[unique("Index")];     // for Index object
    App.Stack -> StackM.Stack[unique("Stack")];     // for Stack object
    App.Queue -> QueueM.Queue[unique("Queue")];     // for Queue objec

7. The application directory should have a sizes.h file in it which is used to
   declare the following.
     -- The following applies to only the index data-structure. Number of elements in 
     Level 2 * number of elements in Level 1 of the index = total capacity of the 
     Index. (Data stored in the index is termed to be at level 0)
     /*
      * This indicates the number of elements in level 1 of the index
      */
     #define ARRAY_ELEMENTS_PER_CHUNK 10

     /*
      * This indicates the number of index elements in level 2 of the index
      */
     #define INDEX_ELEMENTS_PER_CHUNK 10
    
     Thus, here the size of the index will be 100 elements.

     -- You can enable debugging by defining the debug for the appropriate component
     #define INDEX_DEBUG
     #define ARRAY_DEBUG
     #define CHUNK_DEBUG
     #define QUEUE_DEBUG
     #define STACK_DEBUG
     #define STREAM_DEBUG
     #define STREAM_INDEX_DEBUG
     #define CHECKPOINT_DEBUG
     #define ROOT_DIR_DEBUG
     #define COMPACT_DEBUG

8. Debug currently dumps data to the serial port and minicom can be used to pick that up
   -- woefully, this is not good to debug any timing issues.

9. Debug messages can be enabled by uncommenting the appropriate #define in the sizes.h 
   file that should be present in the application directory.

10. The size of the write buffer used by the FAL can be changed by changing the
   following #define in tos/platform/mica2/platform.h
     #define BUFFER_SIZE 256
   The default size is equal to the page size of the flash (most energy efficient).

11. We are facing some issues with the Telos platform -- most code seems to work
    alright, but some code gives run-time errors. We are looking at rectifying this
    soon -- any help / insight is appreciated.