Thu Apr 20 16:03:34 PDT 2006

Update of /cvsroot/tinyos/tinyos-1.x/contrib/rincon/apps/Blackbook3/interfaces
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv16174/contrib/rincon/apps/Blackbook3/interfaces

Added Files:
	Defrag.nc BFileWrite.nc EmptyCheck.nc DataWriter.nc 
	GenericCrc.nc BDictionary.nc NodeMap.nc BFileDelete.nc 
	NodeBooter.nc BFileRead.nc BBoot.nc FlashBridge.nc 
	SectorMap.nc WriteAlloc.nc NodeShop.nc Util.nc 
	CheckpointDictionary.nc DataReader.nc BClean.nc BFileDir.nc 
	Checkpoint.nc 
Log Message:
Uploaded the Blackbook file system, version 3.

--- NEW FILE: Defrag.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 Defragment interface
 */

interface Defrag {

  /**
   * Defragment the file system, taking nodes from files and
   * combining them into fewer nodes, and freeing up sectors
   * so some sectors can be deleted.
   */
  command result_t defrag();

  /**
   * Defragmentation is complete
   * @return SUCCESS if the file system was defragmented
   */
  event result_t defragDone(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. 
   * 
   * The reservedBytes must be specified to ensure enough memory
   * exists in flash for the operation. This does not necessarily
   * reflect how many bytes must be written - if less bytes
   * are actually written, the physical file size is automatically
   * adjusted to the nearest page boundary when the file is finalized.
   * For example, to create a log file that will be able to hold a 
   * maximum of 64000 bytes, specify the reserveBytes to be 64000. 
   * Then if you only log 32000 bytes and close the file, the 
   * physical file size on flash will be around 32k on flash 
   * instead of 64k.
   * 
   * If the file does already exist on flash, 
   * giving a reserveBytes value that is less than the existing
   * file size will not affect the original file size.  This may give you only
   * a few bytes of free space to write to, but only a maximum of a page
   * of flash.  You can use BFileDir.getDataLength(char *fileName) to 
   * get the length of an existing file. So say you have
   * a file already written and closed, and you expect
   * to write 0x1000 more bytes to it:
   *
   * call BFileWrite.open("myFile", 
   *     call BFileDir.getDataLength("myFile") + 0x1000);
   *
   * @param fileName - name of the file to write to
   * @param minimumSize The minimum requested amount of total space
   *            to reserve in the file.  The physical size on the
   *            flash may be more by one page of flash.
   */ 
  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();

  /**
   * Find if the specified file is available for writing,
   * and the current client has no other files open 
   * for writing that would prevent this file from being opened.
   * @param fileName - name of the file
   * @return TRUE if the file can be opened for writing.
   */
  //command bool canOpen(char *fileName);

  /**
   * 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(char *fileName, 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(char *fileName, 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(char *fileName, void *data, uint16_t amountWritten, 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: DataWriter.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 DataWriter 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 DataWriter {

  /**
   * Write data to the given node belonging to the given file.
   * The data will be appended to the write address of the
   * node on flash, not flushed, and the node's dataCrc will
   * be updated.
   * @param focusedNode - the node to append data to
   * @param focusedFile - the file the node belongs to
   * @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(node *focusedNode, file *focusedFile, void *data, uint32_t amount);

  /**
   * Data was appended to the node in the flash.
   * @param dataWritten - 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 dataWriteDone(void *dataWritten, uint32_t amountWritten, result_t result);

}

--- 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: 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, uint16_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 next recorded key in the file.
   * @return SUCCESS if the command will be processed
   */
  command result_t getNextKey(uint32_t presentKey);

  /**
   * 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(uint16_t totalSize, uint16_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);

}

--- 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();

  /**
   * @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 file with the same name
   */
  command bool hasDuplicate(file *focusedFile);

}

--- 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: 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(char *fileName, 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(char *fileName, 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: 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: 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();

    /**
   * Find a sector for a new Checkpoint file.
   * @return a sector that is not being written to, that will fit the Checkpoint
   *    file, and that has the least number of unfinalized files.
   */
  command flashsector *nextBestCheckpointSector(uint8_t checkpointPages);

  /**
   * 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);

  /**
   * Finds the sector the given node exists within,
   * then calculates how many pages the node takes up.
   * If the ending flash address of the node is greater
   * than the sector's length, the sector size is adjusted.
   */
  command void documentNode(node *focusedNode);

  /**
   * Document that a node has been finalized to flash
   */
  command void finalizeNode(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();

  /**
   * @return TRUE if the sector at the given index is in use
   */
  command bool isInUse(uint8_t sectorIndex);

  /**
   * @param sectorIndex - the index of the sector to set inUse
   * @param inUse - TRUE if this sector is in use, FALSE if it isn't
   */
  command void setInUse(uint8_t sectorIndex, bool inUse);

  /**
   * Notify the Sector module that a write file
   * has been closed
   */
  command void free(node *closedNode);

  /**
   * Tell the Sector module that a write file
   * is being opened at the given flashsector
   */
  command void reserve(node *openNode);

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

--- 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
 */

interface WriteAlloc {

  /**
   * Open a file for writing
   * @param name - the name of the file to open
   * @param minimumSize - the minimum size to create the file
   * @param type - the type of file, defined in Blackbook.h
   * @param forceNewDictionary - TRUE for the special case where we are
   *     creating a new dictionary to replace an existing, open dictionary.
   *     The correct filenameCrc will be created, but the filename in NodeMap
   *     and on flash will be 0xFF's to prevent conflicts with the currently
   *     open file.  Also, the magicNumber on flash will be the constructing
   *     type magic number for the file type given - either checkpoint or keyvalue.
   * @return SUCCESS if the file will be opened for writing.
   */
  command result_t openForWriting(filename *name, uint32_t minimumSize, uint8_t type, bool forceNewDictionary);

  /**
   * The write open process completed
   * @param openFile - the file that was opened for writing 
   * @param writeNode - the node to write to
   * @param result - SUCCESS if the file was correctly opened
   */
  event void openedForWriting(file *openFile, node *writeNode, 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 a node's unfinalized metadata to flash.
   * This is all of the node's meta except for the 
   * dataLength and dataCrc.
   *
   * If the node is the first element of a file, 
   * the file associated with the node must be given.
   * If it is not given and the node is the first node of
   * the file, this command will return FAIL. If it is given
   * and the node is not the first node of a file, the
   * file will be ignored.
   *
   * After the command is called and executed, an 
   * unfinalizedMetaWritten event will be signaled.
   *
   * @param focusedNode - the node to write unfinalized metadata for.
   * @param focusedFile - the file if this is the first node of
   *      a file.
   * @return SUCCESS if the meta will can be written.
   */
  command result_t writeUnfinalizedNode(node *focusedNode, file *focusedFile);

  /**
   * Write the finalized metadata for a node.
   * This will only write the dataLength and dataCrc
   * to the node's metadata on flash.
   * 
   * After the command is called and executed, a
   * finalizedMetaWritten event will be signaled.
   *
   * @param focusedNode - the node to write finalized metadata for
   * @return SUCCESS if the finalized meta can be written.
   */
  command result_t writeFinalizedNode(node *focusedNode, file *focusedFile);

  /**
   * A closed, unfinalized node has a special magic number
   * written to flash so the boot mechanism will know that
   * the information about the node is contained in the 
   * checkpoint file, and the reservedLength of the node
   * is not past the page boundary after the dataLength.
   */
  command result_t closeUnfinalizedNode(node *focusedNode, file *focusedFile);

  /**
   * 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);

  /**
   * Unfinalized metadata was written to flash.
   * @param focusedNode - the node that metadata was written for.
   * @param focusedFile - the file that metadata was written for.
   * @param dataStartAddress - the address where data can start being written.
   * @param result - SUCCESS if the metadata was correctly written.
   */
  event void unfinalizedMetaWritten(node *focusedNode, file *focusedFile, uint32_t dataStartAddress, result_t result);

  /**
   * Finalized metadata was written to flash. This node
   * can no longer be written to.
   * @param focusedNode - the node that metadata was finalized for
   * @param result - SUCCESS if the metadata was correctly finalized.
   */
  event void finalizedMetaWritten(node *focusedNode, result_t result);

  /**
   * A node was checkpointed and the magic number was
   * updated on flash.
   * @param focusedNode - the node that is now closed and unfinalized on flash
   * @param result - SUCCESS if the node was correctly closed
   */
  event void closedUnfinalizedMetaWritten(node *focusedNode, 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: 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: CheckpointDictionary.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.
 */

/**
 * This is a secret backend entrance to the DictionaryM file
 * that only the Checkpoint component can access to work 
 * its magic.  This only opens the checkpoint file.
 * The rest of the interaction with the file is done through
 * the regular BDictionary interface.
 *
 * @author David Moss - dmm at rincon.com
 */

interface CheckpointDictionary {

  /**
   * Open the checkpoint file on flash for interaction
   * @param name - filename containing the name of the checkpoint file
   */
  command result_t openCheckpoint(filename *name);

}

--- NEW FILE: DataReader.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 Data Reader Interface
 * Read data from a node on flash
 * 
 * @author David Moss - dmm at rincon.com
 */

interface DataReader {

  /**
   * Read data from the node on flash into the given data buffer,
   * starting at the given data offset into the node.
   * @param focusedNode - the node to read data from
   * @param focusedFile - the file associated with the node
   * @param offset - offset into the node to start reading data
   * @param dataBuffer - a pointer to the buffer to read data into
   * @param amount - the amount of data to read
   * @return SUCCESS if the attempt to read from flash will proceed
   */
  command result_t readData(node *focusedNode, file *focusedFile, uint16_t offset, void *dataBuffer, uint32_t amount);

  /**
   * Data was read from flash into the data buffer.
   * @param dataBuffer - pointer to the buffer where the data was written
   * @param amountRead - the amount of data actually read
   * @param result - SUCCESS if the data was read successfully
   */
  event void dataReadDone(void *dataBuffer, uint32_t amountRead, 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: 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: 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.
   *  > If the node is finalized or deleted, any existing
   *    key will be deleted from the Checkpoint file.
   *  > If the node is unfinalized, its current state 
   *    will be saved in the checkpoint file
   * @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.  The boot process will
   * fill the node with as much information as it
   * can determine from flash, including the node's
   * flashAddress, filenameCrc, etc.  Recovery will
   * fill in the extra details of the node, including
   * the node's dataLength, dataCrc, and reserveLength.
   * The reserveLength of a recovered node will always
   * be up to the next page boundary.
   *
   * Because it could have been possible for a node
   * contain data past the recovery point, the 
   * Checkpoint recovery mechanism will verify that
   * the rest of the page of flash after the recovery
   * point is empty (0xFF's).  If it is found not to be
   * empty, no more data is allowed to be written
   * to the page because it will be corrupted.
   * Instead, the node will be finalized to flash.
   * Any attempt to append data to that recovered file
   * will result in a new node being created.
   * 
   * If the node cannot be recovered, it is deleted.
   *
   * @param focusedNode - the node to recover, with client set to its element number
   * @param elementNumber - the recover node's element number in its file
   * @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 handled correctly.
   */
  event void recovered(result_t result);

}