Thu May 18 15:34:22 PDT 2006

Update of /cvsroot/tinyos/tinyos-1.x/contrib/rincon/apps/Blackbook5/interfaces
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv14770/contrib/rincon/apps/Blackbook5/interfaces

Added Files:
	SectorMap.nc GenericCrc.nc BFileDelete.nc NodeBooter.nc 
	Fileio.nc NodeShop.nc InternalDictionary.nc BFileRead.nc 
	BBoot.nc EmptyCheck.nc BFileDir.nc BDictionary.nc 
	BFileWrite.nc NodeMap.nc Checkpoint.nc Util.nc FlashBridge.nc 
	BClean.nc WriteAlloc.nc 
Log Message:
Uploaded Initial Blackbook5

--- NEW FILE: SectorMap.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook SectorMap Interface
 */

includes Blackbook;

interface SectorMap {

  /**
   * @return the total sectors on flash
   */
  command uint8_t getTotalSectors();

  /**
   * Obtain the largest sector that is not in use
   * on the flash
   * @return the largest available sector to write to 
   */
  command flashsector *nextLargestIdleSector();

  /**
   * Get the flashsector at the specified address in flash.
   * @return the flashsector that exists at the given address
   *     NULL if the flashAddress is out of bounds.
   */
  command flashsector *getSectorAtAddress(uint32_t flashAddress);

  /**
   * Get the sector at a specified volume index
   */
  command flashsector *getSectorAtVolume(uint8_t volume);

  /**
   * @return the total nodes in the given sector
   */
  command uint8_t getNodesInSector(flashsector *focusedSector);

  /**
   * @return TRUE if the sector can be erased
   */
  command bool canErase(uint8_t volume);

  /**
   * Document the existence of a node in a sector on flash.
   * @param focusedNode - the node to document
   */
  command void documentNode(node *focusedNode);

  /**
   * Remove a valid node from its sector.
   * The node must be finalized before removing it.
   * This helps the garbage collector know which sectors to erase.
   */
  command void removeNode(node *focusedNode);

  /**
   * Retreive the earliest available write address in a given sector.
   * @return the write address of the sector relative to 0x0
   */
  command uint32_t getSectorWriteAddress(flashsector *focusedSector);

  /**
   * @return TRUE if the given node is within the bounds of the given sector
   */
  command bool isInSector(flashsector *focusedSector, node *focusedNode);

  /**
   * Retrieve the base address of the flashsector relative to 0x0.
   * @return the relative address of the flashsector from 0x0
   */
  command uint32_t getSectorBaseAddress(flashsector *focusedSector);

  /**
   * Obtain the remaining free bytes in a specified
   * flashsector
   * @param focusedSector - the flashsector to find the free bytes in
   * @return the number of free page bytes in the flashsector
   */
  command uint32_t bytesRemaining(flashsector *focusedSector);

  /**
   * Obtain the total amount of free space on the flash.
   * @return the total amount of free space on the flash
   */
  command uint32_t getFreeSpace();

  /**
   * The sector was erased by the garbage collector
   * @param sectorIndex - the sector erased
   */
  command void eraseComplete(uint8_t sectorIndex);

  /** 
   * Reserve a sector for writing
   * @param *focusedSector pointer to the sector we want to reserve
   */
  command void reserveSector(flashsector *focusedSector);

  /**
   * Free a sector that was reserved for writing
   * @param *focusedSector pointer to the sector we want to free
   */
  command void freeSector(flashsector *focusedSector);
}

--- NEW FILE: GenericCrc.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * GenericCrc Interface
 * Uses the same CRC algorithm as BlockStorage.
 * @author David Moss (dmm at rincon.com)
 */

interface GenericCrc {

  /**
   * Calculate the CRC from a buffer of data
   * of size len, starting with the crc given in 
   * startCrc. This uses the CRC algorithm found
   * in /tos/crc.h.
   *
   * @param startCrc - the starting crc value
   * @param *buf - the buffer of data to take a crc of
   * @param len - the amount of data to calculate the crc for
   * @return the crc.
   */
  command uint16_t crc16(uint16_t startCrc, void *buf, uint32_t len);

}

--- NEW FILE: BFileDelete.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook File Delete Interface
 * @author David Moss - dmm at rincon.com
 */

interface BFileDelete {

  /**
   * Delete a file.
   * @param fileName - the name of the file to delete
   * @return SUCCESS if Blackbook will attempt to delete the file.
   */ 
  command result_t delete(char *fileName);

  /**
   * A file was deleted
   * @param result - SUCCESS if the file was deleted from flash
   */
  event void deleted(result_t result);

}

--- NEW FILE: NodeBooter.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook NodeBooter interface
 * This interface controls the existence of nodes in the NodeMap.
 * The Boot mechanism can use it to load nodes, and
 * other mechanisms can use it to clear the nodes out of RAM
 * when rebooting
 *
 * @author David Moss (dmm at rincon.com)
 */

interface NodeBooter {

  /**
   * Request to add a node to the file system.
   * It is the responsibility of the calling function
   * to properly setup:
   *   > flashAddress
   *   > dataLength
   *   > reserveLength
   *   > dataCrc
   *   > filenameCrc
   *   > client = fileElement from nodemeta
   * 
   * Unless manually linked, state and nextNode are handled by NodeMap.
   * @return a pointer to an empty node if one is available
   *     NULL if no more exist
   */
  command node *requestAddNode();

  /**
   * Request to add a file to the file system
   * It is the responsibility of the calling function
   * to properly setup:
   *   > filename
   *   > filenameCrc
   *   > type
   *
   * Unless manually linked, state and nextNode are handled in NodeMap.
   * @return a pointer to an empty file if one is available
   *     NULL if no more exist
   */
  command file *requestAddFile();

  /**
   * After the boot process finishes, the nodes loaded from flash must
   * be corrected linked before the file system
   * is ready for use.
   */
  command result_t link();

}

--- NEW FILE: Fileio.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook Fileio Interface
 * Allows data to be appended to a node, and automatically
 * update the node's dataCrc.  This will not enforce
 * the amount of data written to a node, because the
 * FileWriter is responsible for that level of architecture.
 *
 * @author David Moss - dmm at rincon.com
 */

interface Fileio {

  /**
   * Write data to the node belonging to the given file
   * at the given address in the file
   * @param focusedFile - the file to write to
   * @param fileAddress - the address to write to in the file
   * @param *data - the data to write
   * @param amount - the amount of data to write
   * @return SUCCESS if the data will be written
   */
  command result_t writeData(file *focusedFile, uint32_t fileAddress, void *data, uint32_t amount);

  /**
   * Read data from the node belonging to the given file
   * at the given address in the file
   * @param focusedFile - the file to read from
   * @param fileAddress - the address to read from in the file
   * @param *data - pointer to the buffer to store the data in
   * @param amount - the amount of data to read
   */
  command result_t readData(file *focusedFile, uint32_t fileAddress, void *data, uint32_t amount);

  /**
   * Flush any written data to flash 
   * @return SUCCESS if the data is flushed, and an event will be signaled.
   */
  command result_t flushData();

  /**
   * Data was appended to the node in the flash.
   * @param writeBuffer - pointer to the buffer containing the data written
   * @param amountWritten - the amount of data appended to the node.
   * @param result - SUCCESS if the data was successfully written
   */
  event void writeDone(void *writeBuffer, uint32_t amountWritten, result_t result);

  /**
   * Data was read from the file
   * @param *readBuffer - pointer to the location where the data was stored
   * @param amountRead - the amount of data actually read
   * @param result - SUCCESS if the data was successfully read
   */
  event void readDone(void *readBuffer, uint32_t amountRead, result_t result);

  /**
   * Data was flushed to flash
   * @param result - SUCCESS if the data was flushed
   */
  event void flushDone(result_t result);
}

--- NEW FILE: NodeShop.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook NodeShop interface
 * At the command of the NodeMap, nodes are converted to meta
 * and written to flash.  Nodes can also be deleted from flash.
 *
 * @author David Moss (dmm at rincon.com)
 */

includes Blackbook;

interface NodeShop {

  /**
   * Write the nodemeta to flash for the given node
   * @param focusedFile - the file to write the nodemeta for
   * @param focusedNode - the node to write the nodemeta for
   * @param name - pointer to the name of the file if this is the first node
   */
  command result_t writeNodemeta(file *focusedFile, node *focusedNode, filename *name);

  /**
   * Delete a node on flash. This will not erase the
   * data from flash, but it will simply mark the magic
   * number of the node to make it invalid.
   * 
   * After the command is called and executed, a metaDeleted
   * event will be signaled.
   *
   * @return SUCCESS if the magic number will be marked
   */
  command result_t deleteNode(node *focusedNode);

  /**
   * Get the CRC of a node on flash.
   *
   * After the command is called and executed, a crcCalculated
   * event will be signaled.
   *
   * @param focusedNode - the node to read and calculate a CRC for
   * @return SUCCESS if the CRC will be calculated.
   */
  command result_t getCrc(node *focusedNode, file *focusedFile);

  /**
   * Get the filename for a file
   * @param focusedFile - the file to obtain the filename for
   * @param *name - pointer to store the filename
   */
  command result_t getFilename(file *focusedFile, filename *name);

  /** 
   * The node's metadata was written to flash
   * @param focusedNode - the node that metadata was written for
   * @param result - SUCCESS if it was written
   */
  event void metaWritten(node *focusedNode, result_t result);

  /**
   * The filename was retrieved from flash
   * @param focusedFile - the file that we obtained the filename for
   * @param *name - pointer to where the filename was stored
   * @param result - SUCCESS if the filename was retrieved
   */
  event void filenameRetrieved(file *focusedFile, filename *name, result_t result);

  /**
   * A node was deleted from flash by marking its magic number
   * invalid in the metadata.
   * @param focusedNode - the node that was deleted.
   * @param result - SUCCESS if the node was deleted successfully.
   */
  event void metaDeleted(node *focusedNode, result_t result);

  /**
   * A crc was calculated from node data on flash
   * @param dataCrc - the crc of the data read from the node on flash.
   * @param result - SUCCESS if the crc is valid
   */
  event void crcCalculated(uint16_t dataCrc, result_t result);

}

--- NEW FILE: InternalDictionary.nc ---

/**
 * Internal dictionary commands
 * @author David Moss (dmm at rincon.com)
 */

interface InternalDictionary {

  /**
   * Internal method of checking to see whether a file is a dictionary file
   * @param focusedFile - the file to check
   * @return SUCCESS if the check will be made
   */
  command result_t isFileDictionary(file *focusedFile);

}

--- NEW FILE: BFileRead.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook File Reading Interface
 * @author David Moss - dmm at rincon.com
 */

interface BFileRead {

  /**
   * Open a file for reading
   * @param fileName - name of the file to open
   * @return SUCCESS if the attempt to open for reading proceeds
   */ 
  command result_t open(char *fileName);

  /**
   * Close any currently opened file
   */
  command result_t close();

  /**
   * Read a specified amount of data from the open
   * file into the given buffer
   * @param *dataBuffer - the buffer to read data into
   * @param amount - the amount of data to read
   * @return SUCCESS if the command goes through
   */
  command result_t read(void *dataBuffer, uint16_t amount);

  /**
   * Seek a given address to read from in the file.
   *
   * This will point the current internal read pointer
   * to the given address if the address is within
   * bounds of the file.  When BFileRead.read(...) is
   * called, the first byte of the buffer
   * will be the byte at the file address specified here.
   *
   * If the address is outside the bounds of the
   * data in the file, the internal read pointer
   * address will not change.
   * @param fileAddress - the address to seek
   * @return SUCCESS if the read pointer is adjusted,
   *         FAIL if the read pointer didn't change
   */
  command result_t seek(uint32_t fileAddress);

  /**
   * Skip the specified number of bytes in the file
   * @param skipLength - number of bytes to skip
   * @return SUCCESS if the internal read pointer was 
   *      adjusted, FAIL if it wasn't because
   *      the skip length is beyond the bounds of the file.
   */
  command result_t skip(uint16_t skipLength);

  /**
   * Get the remaining bytes available to read from this file.
   * This is the total size of the file minus your current position.
   * @return the number of remaining bytes in this file 
   */
  command uint32_t getRemaining();

  /**
   * Find if a given fileName is available for reading
   * and if the current client does not have other files
   * open for reading that would prevent this one from being opened
   * @param fileName - name of the file
   * @return TRUE if the specified file can be opened for reading
   */
  //command bool canOpen(char *fileName);

  /**
   * A file has been opened
   * @param fileName - name of the opened file
   * @param len - the total data length of the file
   * @param result - SUCCESS if the file was successfully opened
   */
  event void opened(uint32_t amount, result_t result);

  /**
   * Any previously opened file is now closed
   * @param result - SUCCESS if the file was closed properly
   */
  event void closed(result_t result);

  /**
   * File read complete
   * @param *buf - this is the buffer that was initially passed in
   * @param amount - the length of the data read into the buffer
   * @param result - SUCCESS if there were no problems reading the data
   */
  event void readDone(void *dataBuffer, uint16_t amount, result_t result);

}

--- NEW FILE: BBoot.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook Boot Interface
 */
interface BBoot {

  /**
   * @return TRUE if the file system has booted
   */
  command bool isBooted();

  /**
   * The file system finished booting
   * @param totalNodes - the total number of nodes found on flash
   * @param result - SUCCESS if the file system is ready for use.
   */
  event void booted(uint16_t totalNodes, uint8_t totalFiles, result_t result);

}

--- NEW FILE: EmptyCheck.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook Empty Check
 * Checks the flash to see if it's empty.
 * @author David Moss - dmm at rincon.com
 */

interface EmptyCheck {

  /**
   * Check if the range on flash is empty.
   * @param addr - starting address to check
   * @param len - the amount to verify empty
   */
  command result_t checkEmpty(uint32_t addr, uint16_t len);

  /**
   * The empty check is complete
   * @param empty - TRUE if the given range on flash is empty
   * @param result - SUCCESS if the result is valid
   */
  event void emptyCheckDone(bool empty, result_t result);

}

--- NEW FILE: BFileDir.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook File Dir Interface
 * Allows the application to find out information about the
 * file system and flash usage.
 * @author David Moss - dmm at rincon.com
 */

interface BFileDir { 

  /**
   * @return the total number of files in the file system
   */
  command uint8_t getTotalFiles();

  /**
   * @return the total number of nodes in the file system
   */
  command uint16_t getTotalNodes();

  /**
   * @return the approximate free space on the flash
   */
  command uint32_t getFreeSpace();

  /**
   * Returns TRUE if the file exists, FALSE if it doesn't
   */
  command result_t checkExists(char *fileName);

  /**
   * An optional way to read the first filename of 
   * the system.  This is the same as calling
   * BFileDir.readNext(NULL)
   */
  command result_t readFirst();

  /**
   * Read the next file in the file system, based on the
   * current filename.  If you want to find the first
   * file in the file system, pass in NULL.
   *
   * If the next file exists, it will be returned in the
   * nextFile event with result SUCCESS
   *
   * If there is no next file, the nextFile event will
   * signal with the filename passed in and FAIL.
   *
   * If the present filename passed in doesn't exist,
   * then this command returns FAIL and no signal is given.
   *
   * @param presentFilename - the name of the current file,
   *     of which you want to find the next valid file after.
   */
  command result_t readNext(char *presentFilename);

  /**
   * Get the total reserved bytes of an existing file
   * @param fileName - the name of the file to pull the reservedLength from.
   * @return the reservedLength of the file, 0 if it doesn't exist
   */
  command uint32_t getReservedLength(char *fileName);

  /**
   * Get the total amount of data written to the file with
   * the given fileName.
   * @param fileName - name of the file to pull the dataLength from.
   * @return the dataLength of the file, 0 if it doesn't exist
   */
  command uint32_t getDataLength(char *fileName);

  /**
   * Find if a file is corrupt. This will read each node
   * from the file and verify it against its dataCrc.
   * If the calculated data CRC from a node does
   * not match the node's recorded CRC, the file is corrupt.
   * @return SUCCESS if the corrupt check will proceed.
   */
  command result_t checkCorruption(char *fileName);

  /**
   * The corruption check on a file is complete
   * @param fileName - the name of the file that was checked
   * @param isCorrupt - TRUE if the file's actual data does not match its CRC
   * @param result - SUCCESS if this information is valid.
   */
  event void corruptionCheckDone(char *fileName, bool isCorrupt, result_t result);

  /**
   * The check to see if a file exists is complete
   * @param fileName - the name of the file
   * @param doesExist - TRUE if the file exists
   * @param result - SUCCESS if this information is valid
   */
  event void existsCheckDone(char *fileName, bool doesExist, result_t result);

  /**
   * This is the next file in the file system after the given
   * present file.
   * @param fileName - name of the next file
   * @param result - SUCCESS if this is actually the next file, 
   *     FAIL if the given present file is not valid or there is no
   *     next file.
   */  
  event void nextFile(char *fileName, result_t result);  

}

--- NEW FILE: BDictionary.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook BDictionary Interface
 */

includes Blackbook;

interface BDictionary {

  /**
   * Open a Dictionary file.  If the file does not exist on flash, the
   * minimumSize will be used to set the length of the file.
   * @param name - name of the Dictionary file to open
   * @param minimumSize - the minimum reserved size for the file on flash
   * @return SUCCESS if the file will be opened
   */
  command result_t open(char *fileName, uint32_t minimumSize);

  /**
   * Close any opened Dictionary files
   * @return SUCCESS if the open Dictionary file was closed.
   */
  command result_t close();

  /**
   * Insert a key-value pair into the opened Dictionary file.
   * This will invalidate any old key-value pairs using the
   * associated key.
   * @param key - the key to use
   * @param value - pointer to a buffer containing the value to insert.
   * @param valueSize - the amount of bytes to copy from the buffer
   * @return SUCCESS if the key-value pair will be inserted
   */
  command result_t insert(uint32_t key, void *value, uint16_t valueSize);

  /**
   * Retrieve a key from the opened Dictionary file.
   * @param key - the key to find
   * @param valueHolder - pointer to the memory location to store the value
   * @param maxValueSize - used to prevent buffer overflows incase the
   *     recorded size of the value does not match the space allocated to
   *     the valueHolder
   * @return SUCCESS if the key will be retrieved.
   */
  command result_t retrieve(uint32_t key, void *valueHolder, uint16_t maxValueSize);

  /**
   * Remove a key from the opened dictionary file
   * @param key - the key for the key-value pair to remove
   * @return SUCCESS if the attempt to remove the key will proceed
   */
  command result_t remove(uint32_t key);

  /**
   * This command will signal event nextKey
   * when the first key is found.
   * @return SUCCESS if the command will be processed.
   */
  command result_t getFirstKey();

  /**
   * Get the last key inserted into the file.
   * @return the last key, or 0xFFFFFFFF (-1) if it doesn't exist
   */
  command uint32_t getLastKey();

  /**
   * Get the next recorded key in the file.
   * @return SUCCESS if the command will be processed
   */
  command result_t getNextKey(uint32_t presentKey);

  /**
   * Find out if a given file is a dictionary file
   * @param fileName - the name of the file
   * @return SUCCESS if the command will go through
   */
  command result_t isFileDictionary(char *fileName);

  /**
   * A Dictionary file was opened successfully.
   * @param totalSize - the total amount of flash space dedicated to storing
   *     key-value pairs in the file
   * @param remainingBytes - the remaining amount of space left to write to
   * @param result - SUCCESS if the file was successfully opened.
   */
  event void opened(uint32_t totalSize, uint32_t remainingBytes, result_t result);

  /** 
   * The opened Dictionary file is now closed
   * @param result - SUCCSESS if there are no open files
   */
  event void closed(result_t result);

  /**
   * A key-value pair was inserted into the currently opened Dictionary file.
   * @param key - the key used to insert the value
   * @param value - pointer to the buffer containing the value.
   * @param valueSize - the amount of bytes copied from the buffer into flash
   * @param result - SUCCESS if the key was written successfully.
   */
  event void inserted(uint32_t key, void *value, uint16_t valueSize, result_t result);

  /**
   * A value was retrieved from the given key.
   * @param key - the key used to find the value
   * @param valueHolder - pointer to the buffer where the value was stored
   * @param valueSize - the actual size of the value.
   * @param result - SUCCESS if the value was pulled out and is uncorrupted
   */
  event void retrieved(uint32_t key, void *valueHolder, uint16_t valueSize, result_t result);

  /**
   * A key-value pair was removed
   * @param key - the key that should no longer exist
   * @param result - SUCCESS if the key was really removed
   */
  event void removed(uint32_t key, result_t result);

  /**
   * The next key in the open Dictionary file
   * @param nextKey - the next key
   * @param result - SUCCESS if this is the really the next key,
   *     FAIL if the presentKey was invalid or there is no next key.
   */
  event void nextKey(uint32_t nextKey, result_t result);

  /**
   * @param isDictionary - TRUE if the file is a dictionary
   * @param result - SUCCESS if the reading is valid
   */
  event void fileIsDictionary(bool isDictionary, result_t result);
}

--- NEW FILE: BFileWrite.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook File Write Interface
 */

interface BFileWrite {

  /**
   * Open a file for writing. 
   * @param fileName - name of the file to write to
   * @param minimumSize The minimum requested amount of total data space
   *            to reserve in the file.  The physical amount of flash 
   *            consumed by the file may be more.
   */ 
  command result_t open(char *fileName, uint32_t minimumSize);

  /**
   * Close any currently opened write file.
   */
  command result_t close();

  /**
   * Save the current state of the file, guaranteeing the next time
   * we experience a catastrophic failure, we will at least be able to
   * recover data from the open write file up to the point
   * where save was called.
   *
   * If data is simply being logged for a long time, use save() 
   * periodically but probably more infrequently.
   *
   * @return SUCCESS if the currently open file will be saved.
   */
  command result_t save();

  /**
   * Append the specified amount of data from a given buffer
   * to the open write file.  
   *
   * @param data - the buffer of data to append
   * @param amount - the amount of data in the buffer to write.
   * @return SUCCESS if the data will be written, FAIL if there
   *     is no open file to write to.
   */ 
  command result_t append(void *data, uint16_t amount);

  /**
   * Obtain the remaining bytes available to be written in this file
   * This is the total reserved length minus your current 
   * write position
   * @return the remaining length of the file.
   */
  command uint32_t getRemaining();

  /**
   * Signaled when a file has been opened, with the results
   * @param fileName - the name of the opened write file
   * @param len - The total reserved length of the file
   * @param result - SUCCSES if the file was opened successfully
   */
  event void opened(uint32_t len, result_t result);

  /** 
   * Signaled when the opened file has been closed
   * @param result - SUCCESS if the file was closed properly
   */
  event void closed(result_t result);

  /**
   * Signaled when this file has been saved.
   * This does not require the save() command to be called
   * before being signaled - this would happen if another
   * file was open for writing and that file was saved, but
   * the behavior of the checkpoint file required all files
   * on the system to be saved as well.
   * @param fileName - name of the open write file that was saved
   * @param result - SUCCESS if the file was saved successfully
   */
  event void saved(result_t result);

  /**
   * Signaled when data is written to flash. On some media,
   * the data is not guaranteed to be written to non-volatile memory
   * until save() or close() is called.
   * @param fileName
   * @param data The buffer of data appended to flash
   * @param amountWritten The amount written to flash
   * @param result
   */
  event void appended(void *data, uint16_t amountWritten, result_t result);

} 

--- NEW FILE: NodeMap.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook NodeMap interface
 * NodeMap controls all nodes in memory, and regulates
 * access to those nodes.  This direct interface
 * only helps control and find information about nodes.
 *
 * @author David Moss (dmm at rincon.com)
 */

includes Blackbook;

interface NodeMap {

  /**
   * @return the maximum number of nodes allowed
   */
  command uint16_t getMaxNodes();

  /** 
   * @return the maximum number of files allowed
   */
  command uint8_t getMaxFiles();

  /** 
   * @return the total nodes used by the file system
   */
  command uint16_t getTotalNodes();

  /**
   * @return the total nodes allocated to the given file
   */
  command uint8_t getTotalNodesInFile(file *focusedFile);

  /**
   * @return the total files used by the file system
   */
  command uint8_t getTotalFiles();

  /**
   * Get the node and offset into the node that represents
   * an address in a file
   * @param focusedFile - the file to find the address in
   * @param fileAddress - the address to find
   * @param returnOffset - pointer to a location to store the offset into the node
   * @return the node that contains the file address in the file.
   */
  command node *getAddressInFile(file *focusedFile, uint32_t fileAddress, uint16_t *returnOffset); 

  /**
   * @return the node's position in a file, 0xFF if not valid
   *
  command uint8_t getElementNumber(node *focusedNode);

  /**
   * If you already know the file, this is faster than getElementNumber(..)
   * @return the node's position in the given file, 0xFF if not valid
   *
  command uint8_t getElementNumberFromFile(node *focusedNode, file *focusedFile);

  /**
   * @return the file with the given name if it exists, NULL if it doesn't
   */
  command file *getFile(filename *name);

  /**
   * @return the file associated with the given node, NULL if n/a.
   */
  command file *getFileFromNode(node *focusedNode);

  /**
   * Traverse the files on the file system from
   * 0 up to (max files - 1)
   * If performing a DIR, be sure to hide
   * Checkpoint files on the way out.
   * @return the file at the given index
   */
  command file *getFileAtIndex(uint8_t index);

  /**
   * Get a node at a given index
   * @return the node if it exists, NULL if it doesn't.
   */
  command node *getNodeAtIndex(uint8_t index);

  /** 
   * @return the length of the file's data
   */
  command uint32_t getDataLength(file *focusedFile);

  /**
   * @return the reserve length of all nodes in the file
   */
  command uint32_t getReserveLength(file *focuseFile);

  /**
   * @return TRUE if there exists another node belonging
   * to the same file with the same element number
   */
  command bool hasDuplicate(node *focusedNode);

}

--- NEW FILE: Checkpoint.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook Checkpoint Interface 
 * Saves the state of open binary nodes to a Checkpoint
 * dicationary file on flash for catastrophic failure recovery.
 * @author David Moss - dmm at rincon.com
 */

interface Checkpoint {

  /**
   * After boot is complete, open the checkpoint file
   * in the BDictionary
   * @return SUCCESS if the checkpoint file will be 
   *     created and/or opened.
   */
  command result_t openCheckpoint();

  /**
   * Update a node.
   * @param focusedNode - the node to save or delete
   * @return SUCCESS if the information will be updated
   */
  command result_t update(node *focusedNode);

  /**
   * Recover a node's dataLength and dataCrc
   * from the Checkpoint.
   *
   * If the node cannot be recovered, it is deleted.
   *
   * @param focusedNode - the node to recover, with client set to its element number
   * @return SUCCESS if recovery will proceed
   */
  command result_t recover(node *focusedNode);

  /**
   * The checkpoint file was opened.
   * @param result - SUCCESS if it was opened successfully
   */
  event void checkpointOpened(result_t result);

  /**
   * The given node was updated in the Checkpoint
   * @param focusedNode - the node that was updated
   * @param result - SUCCESS if everything's ok
   */
  event void updated(node *focusedNode, result_t result);

  /** 
   * A node was recovered.
   * @param result - SUCCESS if it was recovered correctly.
   *                 FAIL if it should be deleted.
   */
  event void recovered(node *recoveredNode, result_t result);

}

--- NEW FILE: Util.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/** 
 * Blackbook Utilities
 * Conversions and anything that doesn't belong.
 */

includes Storage;
includes Blackbook;

interface Util {

  /**
   * Convert the specified length of data
   * into number of flash pages. This always rounds up except
   * when it's right on.
   * @return the number of pages on flash required
   *     to hold the data
   */
  command uint16_t convertBytesToPages(uint32_t bytes);

  /**
   * Convert the specified number of flash pages
   * to bytes
   * @return the number of bytes in the given number of flash pages
   */
  command uint32_t convertPagesToBytes(uint16_t pages);

  /**
   * Get the address of the first byte of the next page  
   * based on a given address
   * @param currentAddress -
   * @return the base address of the next flash page
   */
  command uint32_t getNextPageAddress(uint32_t currentAddress);

  /**
   * Get the address of the first byte of the next sector
   * @param currentAddress -
   * @return the base address of the next flash sector
   */
  command uint32_t getNextSectorAddress(uint32_t currentAddress);

  /**
   * Copy a string filename from one char
   * array to another
   */
  command void filenameCpy(filename *to, char *from);

  /**
   * @return the crc-16 of a a given filename
   */
  command uint16_t filenameCrc(filename *focusedFilename);

}

--- NEW FILE: FlashBridge.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook FlashBridge interface
 * Implement this interface with consistent behavior for any
 * flash type Blackbook should sit on top of
 */

interface FlashBridge {

  /** 
   * Read bytes from flash
   * @param addr - the address to read from
   * @param *buf - the buffer to read into
   * @param len - the amount to read
   * @return SUCCESS if the bytes will be read
   */
  command result_t read(uint32_t addr, void *buf, uint32_t len);

  /** 
   * Write bytes to flash
   * @param addr - the address to write to
   * @param *buf - the buffer to write from
   * @param len - the amount to write
   * @return SUCCESS if the bytes will be written
   */
  command result_t write(uint32_t addr, void *buf, uint32_t len);

  /**
   * Erase a sector in flash
   * Blackbook only erases in sector granularities, not pages.
   * Sector 0 should be the first sector existing at FS_START_ADDRESS
   * defined in FlashSettings.h
   * @param sector - the sector id to erase
   * @return SUCCESS if the sector will be erased
   */
  command result_t erase(uint16_t sector);

  /**
   * Flush written data to flash. This only applies to some flash
   * chips.
   * @return SUCCESS if the flash will be flushed
   */
  command result_t flush();

  /**
   * Obtain the CRC of a chunk of data sitting on flash.
   * @param addr - the address to start the CRC computation
   * @param len - the amount of data to obtain the CRC for
   * @return SUCCESS if the CRC will be computed.
   */
  command result_t crc(uint32_t addr, uint32_t len);

  /**
   * Read is complete
   * @param addr - the address to read from
   * @param *buf - the buffer to read into
   * @param len - the amount to read
   * @return SUCCESS if the bytes will be read
   */
  event void readDone(uint32_t addr, void *buf, uint32_t len, result_t result);

  /**
   * Write is complete
   * @param addr - the address to write to
   * @param *buf - the buffer to write from
   * @param len - the amount to write
   * @return SUCCESS if the bytes will be written
   */
  event void writeDone(uint32_t addr, void *buf, uint32_t len, result_t result);

  /**
   * Erase is complete
   * @param sector - the sector id to erase
   * @return SUCCESS if the sector will be erased
   */
  event void eraseDone(uint16_t sector, result_t result);

  /**
   * Flush is complete
   * @param result - SUCCESS if the flash was flushed
   */
  event void flushDone(result_t result);

  /**
   * CRC-16 is computed
   * @param crc - the computed CRC.
   * @param addr - the address to start the CRC computation
   * @param len - the amount of data to obtain the CRC for
   * @return SUCCESS if the CRC will be computed.
   */
  event void crcDone(uint16_t calculatedCrc, uint32_t addr, uint32_t len, result_t result);

  /**
   * Signaled when the flash is ready to be used
   * @param result - SUCCESS if we can use the flash.
   */
  event void ready(result_t result);
}

--- NEW FILE: BClean.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook BClean Interface
 * Lets you clean up dirty used sectors on the flash.
 * @author David Moss (dmm at rincon.com)
 */

interface BClean {
  /**
   * If the free space on the file system is over a threshold
   * then we should go ahead and defrag and garbage collect.
   * This should be run when the mote has some time and energy
   * to spare in its application.
   * @return SUCCESS if the file system will defrag and gc itself
   */
  command result_t performCheckup();

  /**  
   * Run the garbage collector, erasing any sectors that 
   * contain any data with 0 valid nodes.
   * @return SUCCESS if the garbage collector is run
   */
  command result_t gc();

  /**
   * The Garbage Collector is erasing a sector - this may take awhile
   */
  event void erasing();

  /**
   * Garbage Collection is complete
   * @return SUCCESS if any sectors were erased.
   */
  event void gcDone(result_t result);
}

--- NEW FILE: WriteAlloc.nc ---
/*
 * Copyright (c) 2004-2006 Rincon Research Corporation.  
 * All rights reserved.
 * 
 * Rincon Research will permit distribution and use by others subject to
 * the restrictions of a licensing agreement which contains (among other things)
 * the following restrictions:
 * 
 *  1. No credit will be taken for the Work of others.
 *  2. It will not be resold for a price in excess of reproduction and 
 *      distribution costs.
 *  3. Others are not restricted from copying it or using it except as 
 *      set forward in the licensing agreement.
 *  4. Commented source code of any modifications or additions will be 
 *      made available to Rincon Research on the same terms.
 *  5. This notice will remain intact and displayed prominently.
 * 
 * Copies of the complete licensing agreement may be obtained by contacting 
 * Rincon Research, 101 N. Wilmot, Suite 101, Tucson, AZ 85711.
 * 
 * There is no warranty with this product, either expressed or implied.  
 * Use at your own risk.  Rincon Research is not liable or responsible for 
 * damage or loss incurred or resulting from the use or misuse of this software.
 */

/**
 * Blackbook File Write Allocator Interface
 */

includes Blackbook;

interface WriteAlloc {

  /**
   * Open a file for writing
   */
  command result_t openForWriting(char *name, uint32_t minimumSize, bool forceConstruction, bool isCheckpoint);

  /**
   * The write open process completed
   * @param openFile - the file that was opened for writing 
   * @param writeNode - the node to write to
   * @param appendAddress - the next address in the file to append to
   * @param result - SUCCESS if the file was correctly opened
   */
  event void openedForWriting(file *openFile, node *writeNode, uint32_t totalSize, result_t result);

}