include/block/journal.h File Reference

Journal service based on dataflash. More...

#include <dataflash/dataflash.h>

Include dependency graph for journal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures

struct  journal_entry
struct  journal

Functions

void journal_init (struct journal *media, struct dataflash_device *storage, unsigned int start_addr, unsigned int length)
 Initialize a journal.
void journal_open_entry (struct journal *media, struct journal_entry *entry, journal_callback_t entry_stored, void *context)
 Store journal entry.
void journal_commit_card (struct journal *media, struct journal_entry *entry, unsigned int card_nr, journal_callback_t card_committed, void *context)
 Journal entry commited for a card.
void journal_close_entry (struct journal *media)
 Close current entry without committing all cards.
void journal_get_last_entry (struct journal *media, struct journal_entry *entry, journal_callback_t entry_retrieved, void *context)
 Retrieve last complete journal entry.
void journal_clean_last_entry (struct journal *media, journal_callback_t entry_cleaned, void *context)
 Clean the last entry in the journal.
void journal_prepare_entry (struct journal_entry *entry, uint32_t card_id, uint32_t block, uint16_t length)
 Prepare a new journal entry.
bool journal_entry_card_is_intact (struct journal_entry *entry, unsigned int card_nr)
 Check a journal entry to see if a card was written correctly.
bool journal_entry_is_consistent (struct journal_entry *entry)
 Check the consistency of a journal entry.
static bool journal_is_empty (struct journal *journal)
 Check if journal is empty.

Detailed Description

Journal service based on dataflash.

This is the interface of a journal service which can be used to enter journal entries in a dataflash and reading back the latest entry.

Author:
Atmel Corporation: http://www.atmel.com
Support and FAQ: http://support.atmel.no/

Definition in file journal.h.

Function Documentation

void journal_clean_last_entry ( struct journal *  media,
journal_callback_t  entry_cleaned,
void *  context 
)

Clean the last entry in the journal.

This function will clean the last entry in the journal by writing a new dummy entry with size 0 and both cards committed. Used after successfully doing a replay, or after deciding not to do a replay despite the journal indicating one of the cards being dirty.

This function is necessary because a dirty journal will become stale as soon as the system allows an unjournaled write to any of the devices in the array (for example, if there's only one device in the array, journaling is pointless), and must not be replayed on the next power-up.

Parameters:
media Journal media used for storage
entry_cleaned Callback function called after cleaning
context User defined data passed to the callback

Definition at line 217 of file journal.c.

References assert, buffer_init_tx_mapped(), journal::callback, journal::context, journal::current_entry, journal::current_location, dbg_error, journal::entry_buffer, journal_prepare_entry(), journal::request, and journal::status.

Here is the call graph for this function:

void journal_close_entry ( struct journal *  media  ) 

Close current entry without committing all cards.

This function will close the current journal entry, without committing any further cards. When the entry is closed, the journal is immediately ready to open a new entry. Do not close an open entry while a open entry or commit card operation is in progress.

Parameters:
media Journal media used for storage

Definition at line 338 of file journal.c.

References assert, journal::flags, and journal::status.

void journal_commit_card ( struct journal *  media,
struct journal_entry *  entry,
unsigned int  card_nr,
journal_callback_t  card_committed,
void *  context 
)

Journal entry commited for a card.

This function will store the given journal entry to non-volatile storage (dataflash). As soon as the entry has been securely stored, the given callback will be called. The driver will internally calculate a checksum of the entry enabling it to verify the read out when the entry is retrieved.

Parameters:
media Journal media used for storage
entry The journal entry to update
card_nr The card to commit
card_commited Callback function called after commiting the card
context User defined data passed to the callback

Definition at line 290 of file journal.c.

References assert, buffer_init_tx(), journal::callback, journal_entry::committed_card0_magic, journal_entry::committed_card1_magic, journal::context, journal::current_entry, journal::entry_buffer, journal::flags, journal::last_location, journal::request, and journal::status.

Here is the call graph for this function:

bool journal_entry_card_is_intact ( struct journal_entry *  entry,
unsigned int  card_nr 
)

Check a journal entry to see if a card was written correctly.

This function will check the fields of the journal entry given to it, and return the state of one of the cards. If the journal entry indicates that a write to the card has started, but not completed, the function will return false. The position and length fields in the journal entry will provide information about which region of the card that might be corrupted.

Parameters:
entry Pointer to journal entry structure
card_nr Number of the card to check
Returns:
true Whole card is intact

false The area defined in entry might be corrupt

Definition at line 574 of file journal.c.

References assert, journal_entry::committed_card0_magic, journal_entry::committed_card1_magic, journal_entry::length, and journal_entry::magic0.

bool journal_entry_is_consistent ( struct journal_entry *  entry  ) 

Check the consistency of a journal entry.

This function will check the consistency of a journal entry. If a entry is found not to be consistent, something is very wrong; most probably we have a failing storage media. Getting disturbed during write or losing power will never cause an inconsistent journal entry.

Parameters:
entry Pointer to journal entry structure
Returns:
true Entry seems consistent

false Entry is not consistent; storage media probably faulty

Definition at line 623 of file journal.c.

References assert, journal_entry::committed_card0_magic, journal_entry::committed_card1_magic, journal_entry::length, and journal_entry::magic0.

void journal_get_last_entry ( struct journal *  media,
struct journal_entry *  entry,
journal_callback_t  entry_retrieved,
void *  context 
)

Retrieve last complete journal entry.

This function will retrieve the last journal entry stored on the non-volatile storage (dataflash). This entry will then be passed on to the given callback function. Afterwards journal_entry_card_is_intact() can be used to investigate the retrieved entry.

Parameters:
media Journal media used for storage
entry Pointer to where the retrieved data can be stored
entry_retrieved Callback function called after retrieving entry
context User defined data passed to the callback

Definition at line 503 of file journal.c.

References assert, journal::callback, journal::context, journal::current_entry, journal::flags, journal_find_last_entry(), journal::request, journal::search_mode, and journal::status.

Here is the call graph for this function:

void journal_init ( struct journal *  media,
struct dataflash_device *  storage,
unsigned int  start_addr,
unsigned int  length 
)

Initialize a journal.

This function will initialize a journal and set up the journal struct. After the journal has been initialized, the journal_get_last_entry() function can be used to get retrieve the last entry written to the journal.

Parameters:
journal The journal struct
storage The dataflash used for storage
start_addr First flash address used by the journal
length Flash area dedicated to the journal

Definition at line 657 of file journal.c.

References assert, dbg_warning, journal::entry_buffer, journal::erase_request, journal_find_last_entry(), journal::length, memset(), journal::request, journal::start, journal::status, journal::storage, workqueue_init_item(), and journal::workqueue_item.

Here is the call graph for this function:

static bool journal_is_empty ( struct journal *  journal  )  [inline, static]

Check if journal is empty.

This function will return true if the journal is empty, false if there is at least one entry in the journal. journal_get_last_entry() must be run before this funtion.

Parameters:
journal Journal description struct
Returns:
true Journal is empty

false Journal is not empty

Definition at line 176 of file journal.h.

References assert, and journal::flags.

void journal_open_entry ( struct journal *  media,
struct journal_entry *  entry,
journal_callback_t  entry_stored,
void *  context 
)

Store journal entry.

This function will store the given journal entry to non-volatile storage (dataflash). As soon as the entry has been securely stored, the given callback will be called. Both journal_init() and journal_get_last_entry() must have been called before this function can be used.

Parameters:
media Journal media used for storage
entry The journal entry to store
entry_stored Callback function called after storing entry
context User defined data passed to the callback

Definition at line 164 of file journal.c.

References assert, buffer_init_tx(), journal::callback, journal::context, journal::current_entry, journal::current_location, journal::entry_buffer, journal_entry::magic0, journal::request, and journal::status.

Here is the call graph for this function:

void journal_prepare_entry ( struct journal_entry *  entry,
uint32_t  card_id,
uint32_t  block,
uint16_t  length 
)

Prepare a new journal entry.

This function will prepare a journal entry for a new write operation. The entry should be opened with journal_open_entry() before starting the write, and each card should be committed with journal_commit_card() after it has been successfully written.

Parameters:
entry Pointer to journal entry structure
card_id ID of the card being written
block Address written on the card
length Length of the write operation

Definition at line 538 of file journal.c.

References assert, journal_entry::block, journal_entry::card_id, journal_entry::committed_card0_magic, journal_entry::committed_card1_magic, journal_entry::length, and journal_entry::magic0.

Referenced by journal_clean_last_entry().

Generated on Tue Sep 15 10:20:46 2009 for libavr32 by  doxygen 1.5.8