# drivers/block/journal.c File Reference

Journal service based on dataflash. More...

`#include <debug.h>`
`#include <block/journal.h>`
`#include <checksum/crc8.h>`
`#include <dmapool.h>`
`#include <workqueue.h>`
`#include <app/workqueue.h>`
`#include <string.h>`
`#include <status-codes.h>`

Include dependency graph for journal.c:

Go to the source code of this file.

## Functions
static unsigned int | journal_get_next_address (struct journal *media, unsigned int prev_addr)
| Find next valid journal entry address.
void | journal_open_entry (struct journal *media, struct journal_entry *entry, journal_callback_t entry_stored, void *context)
| Store 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_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.
static void | journal_find_last_entry (void *data)
| Search dataflash for last journal entry.
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_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.
void | journal_init (struct journal *media, struct dataflash_device *storage, unsigned int start_addr, unsigned int length)
| Initialize a journal.

## Detailed Description

Journal service based on dataflash.

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

- Compiler: IAR EWAVR32 and GNU GCC for AVR32
- Supported devices: All devices
- AppNote:

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

Definition in file journal.c.

## 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.

static void journal_find_last_entry | ( | void * | data | ) | `[static]`

Search dataflash for last journal entry.

This function will search through the dataflash for the last journal entry stored. The last_location and current_location pointers will be updated.

The function interface is set us a dataflash callback, simplifying recursive operation.

Parameters:

  | data | Data pointer returned with the callback, will point to the journal structure.

Definition at line 438 of file journal.c.

References buffer_init_rx(), journal::current_location, journal::entry_buffer, journal::flags, journal_get_next_address(), journal::last_location, journal::length, journal::magic_number, journal::request, journal::search_mode, journal::start, journal::storage, and unhandled_case.

Referenced by journal_get_last_entry(), and journal_init().

Here is the call graph for this function:

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:

static unsigned int journal_get_next_address | ( | struct journal * | media,
|  | unsigned int | prev_addr |
| ) |  |  | `[static]`

Find next valid journal entry address.

This function will return the next valid journal entry address. Usually it will jsut increment the current address with the length of one entry, but if the next entry will cross a page boundary, a small offset will be added to allign it with the boundary.

Parameters:

  | media | Journal descriptor
  | prev_addr | Previous address

Returns:
  Next address

Definition at line 84 of file journal.c.

References journal::storage.

Referenced by journal_find_last_entry().

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:

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