Interface: tos.chips.at45db.At45db

interface At45db

HAL for Atmel's AT45DB family of serial dataflash chips. This provides reasonably high-level operations on AT45DB pages, including automatic buffer management. Writes are only guaranteed to happen after a flush, flushAll, sync or syncAll.

When buffers are flushed to the flash (either explicitly or implicitly), their contents are checked to ensure the write was succesful. If this check fails, the flush is retried some number of times. If this fails more than some number of times, all access to the flash is disabled (all requests will report FAIL in their completion event).

This interface only supports one operation at a time - components offering At45db should use the Resource interface for resource sharing.

Author:: David Gay

Commands

command void computeCrc(at45page_t page, at45pageoffset_t offset, at45pageoffset_t n, uint16_t baseCrc) Compute the CRC of some data from an AT45DB page (using the CRC function from crc.h).

command void copyPage(at45page_t from, at45page_t to) Copy one flash page to another.

command void erase(at45page_t page, uint8_t eraseKind) Erase an AT45DB page.

command void flush(at45page_t page) Flush an AT45DB page from the buffers to the actual flash.

command void flushAll() Flush all AT45DB buffers to the actual flash.

command void read(at45page_t page, at45pageoffset_t offset, void *data, at45pageoffset_t n) Read some data from an AT45DB page.

command void sync(at45page_t page) Flush an AT45DB page from the buffers to the actual flash.

command void syncAll() Flush all AT45DB buffers to the actual flash.

command void write(at45page_t page, at45pageoffset_t offset, void *data, at45pageoffset_t n) Write some data to an AT45DB page.

Events

event void computeCrcDone(error_t error, uint16_t crc) Signal completion of a CRC computation.

event void copyPageDone(error_t error) Signal completion of a copyPage operation.

event void eraseDone(error_t error) Signal completion of an erase operation.

event void flushDone(error_t error) Signal completion of an flush or flushAll operation.

event void readDone(error_t error) Signal completion of a read operation.

event void syncDone(error_t error) Signal completion of a sync or syncAll operation.

event void writeDone(error_t error) Signal completion of a write operation.

Commands - Details

computeCrc

command void computeCrc(at45page_t page, at45pageoffset_t offset, at45pageoffset_t n, uint16_t baseCrc)

Compute the CRC of some data from an AT45DB page (using the CRC function from crc.h). computeCrcDone will be signaled.

Parameters:: page - Flash page to read from. Must be less than AT45_MAX_PAGES.; offset - Offset in page at which to start reading - must be between 0 and AT45_PAGE_SIZE - 1; n - Number of bytes to read (> 0). offset + n must be <= AT45_PAGE_SIZE; baseCrc - initial CRC value - use 0 if computing a "standalone" CRC, or a previous computeCrc result if computing a CRC over several flash pages

copyPage

command void copyPage(at45page_t from, at45page_t to)

Copy one flash page to another. copyDone will be signaled. If page from had been modified, it is first flushed to flash. Page to will only actually be written when the buffer holding it is flushed (see flush, flushAll, sync, syncAll).

Parameters:: from - Flash page to copy. Must be less than AT45_MAX_PAGES.; to - Flash page to overwrite. Must be less than AT45_MAX_PAGES.

erase

command void erase(at45page_t page, uint8_t eraseKind)

Erase an AT45DB page. eraseDone will be signaled.

Parameters:: page - Flash page to erase. Must be less than AT45_MAX_PAGES.; eraseKind - How to handle the erase:
AT45_ERASE: actually erase the page in the flash chip
AT45_DONT_ERASE: don't erase the page in the flash chip, but reserve a buffer for this page - subsequent writes to this page will be faster because the old contents need not be read
AT45_PREVIOUSLY_ERASED: assume the page was previously erased in the flash and reserve a buffer for this page - subsequent writes to page will be faster because the old contents need not be read and the write itself will be faster

flush

command void flush(at45page_t page)

Flush an AT45DB page from the buffers to the actual flash. flushDone will be signaled once the flush has been initiated. If the page is not in the buffers, flushDone will succeed "immediately".

Parameters:: page - Flash page to sync. Must be less than AT45_MAX_PAGES.

flushAll

command void flushAll()

Flush all AT45DB buffers to the actual flash. flushDone will be signaled once the flushes have been initiated.

read

command void read(at45page_t page, at45pageoffset_t offset, void *data, at45pageoffset_t n)

Read some data from an AT45DB page. readDone will be signaled.

Parameters:: page - Flash page to read from. Must be less than AT45_MAX_PAGES.; offset - Offset in page at which to start reading - must be between 0 and AT45_PAGE_SIZE - 1; data - Buffer in which to place read data. The buffer is "returned" at readDone time.; n - Number of bytes to read (> 0). offset + n must be <= AT45_PAGE_SIZE

sync

command void sync(at45page_t page)

Flush an AT45DB page from the buffers to the actual flash. syncDone will be signaled once the flush has been completed and the buffer contents successfully compared with the flash. If the page is not in the buffers, syncDone will succeed "immediately".

Parameters:: page - Flash page to sync. Must be less than AT45_MAX_PAGES.

syncAll

command void syncAll()

Flush all AT45DB buffers to the actual flash. syncDone will be signaled once the flush has been completed and the buffer contents successfully compared with the flash.

write

command void write(at45page_t page, at45pageoffset_t offset, void *data, at45pageoffset_t n)

Write some data to an AT45DB page. writeDone will be signaled.

Parameters:: page - Flash page to write to. Must be less than AT45_MAX_PAGES.; offset - Offset in page at which to start writing - must be between 0 and AT45_PAGE_SIZE - 1; data - Data to write. The buffer is "returned" at writeDone time.; n - Number of bytes to write (> 0). offset + n must be <= AT45_PAGE_SIZE

Events - Details

computeCrcDone

event void computeCrcDone(error_t error, uint16_t crc)

Signal completion of a CRC computation.

Parameters:: error - SUCCESS if the CRC was successfully computed, FAIL otherwise; crc - CRC value (valid only if error == SUCCESS)

copyPageDone

event void copyPageDone(error_t error)

Signal completion of a copyPage operation.

Parameters:: error - SUCCESS if the copy was successful, FAIL otherwise

eraseDone

event void eraseDone(error_t error)

Signal completion of an erase operation.

Parameters:: error - SUCCESS if the erase was successful, FAIL otherwise

flushDone

event void flushDone(error_t error)

Signal completion of an flush or flushAll operation.

Parameters:: error - SUCCESS if the flush was successful, FAIL otherwise

readDone

event void readDone(error_t error)

Signal completion of a read operation. The buffer passed to read is implictly returned.

Parameters:: error - SUCCESS for a successful read, FAIL otherwise

syncDone

event void syncDone(error_t error)

Signal completion of a sync or syncAll operation.

Parameters:: error - SUCCESS if the sync was successful, FAIL otherwise

writeDone

event void writeDone(error_t error)

Signal completion of a write operation. The buffer passed to write is implictly returned.

Parameters:: error - SUCCESS for a successful write, FAIL otherwise