Utility functions and threads are provided for persistent storage. The ยต-controller ATmega1284P has 4K byte EEPROM (100T erase cycles life). The board weAut_01 has a slot for small memory cards.
Both can be used for persistent storage. To hold configuration data to survive power off the EEPROM is clearly the better choice.
Files | |
file | persist.h |
weAutSys (weAut_01) utility / library functions for persistent storage | |
Data Structures | |
struct | eeOp_data_t |
The data structure for an EEPROM bulk operation thread. More... | |
Defines | |
#define | DEFAULT_EEPROM_CONF_ADD 64 |
Default address of EEPROM configuration data. | |
#define | EE_CONF_ADD(elem) |
The EEPROM address of a configuration element. | |
#define | EEPROM_POINTER2_EE_CONF (EEP_SIZE - 64) |
EEPROM address of (address of) EEPROM configuration data. | |
Functions | |
ptfnct_t | eeOperationThread (eeOp_data_t *eeOpData) |
The EEPROM (bulk) write system thread; the thread function. | |
uint8_t | eeReadByte (uint8_t *readValue, uint16_t eeAddr) |
Read one EEPROM cell to RAM. | |
uint8_t | eeReadBytes (uint16_t eeAddr, uint8_t *dest, uint8_t bufferLength) |
Read EEPROM cells. | |
uint8_t | eeWriteByte (uint16_t eeAddr, uint8_t newValue) |
Write one EEPROM cell. | |
uint8_t | initEEthreadWrite (eeOp_data_t *eeOpData, uint16_t eeAddr, uint8_t *writeBuffer, uint8_t bufferLength) |
Initialise an EEPROM operation thread. | |
Variables | |
uint16_t | eeConfigAdd |
Address of EEPROM configuration data. | |
eeOp_data_t | eeOpData |
The data for an EEPROM bulk operation thread. |
#define EEPROM_POINTER2_EE_CONF (EEP_SIZE - 64) |
EEPROM address of (address of) EEPROM configuration data.
This is the address of two consecutive bytes in EEPROM that hold the address of this devices EEPROM configuration data.
The rationale of this indirection is that that the entry pointed to by this address will have to be changed only if the writing of configuration data fails due to EEPROM wear out (after > 100000 modifies).
#define DEFAULT_EEPROM_CONF_ADD 64 |
Default address of EEPROM configuration data.
This is the (fresh board default) value for the address of this devices EEPROM configuration data.
The value might be changed in future software releases to use other EEPROM locations on (then) older boards.
Hint: This value has to be used in (C-) sources and tool (avr-objcopy) settings respectively parameters to generate an EEPROM .hex file with individualized board configurations.
Hint 2: There is a (until April 2013 at least) avrdude bug that erases all EEPROM cells below the first address of a small EEPROM .hex file. As long as this problem persists DEFAULT_EEPROM_CONF_ADD should be quite low and must be lower than EEPROM_POINTER2_EE_CONF.
#define EE_CONF_ADD | ( | elem | ) |
The EEPROM address of a configuration element.
This macro calculates the EEPROM address of an element in a conf_data_t structure. This is done without without any precondition checks. The most important condition is eeConfigAdd being not NULL.
elem | the name of a conf_data_t element |
uint8_t eeReadByte | ( | uint8_t * | readValue, |
uint16_t | eeAddr | ||
) |
Read one EEPROM cell to RAM.
The operation is a bit slow (compared to RAM access) but the function returns immediately.
The function fails if another EEPROM (or Flash write) operation is running. It must, of course, never ever be used spin waiting for success.
eeAddr | the EEPROM address to read (0 .. 4095) |
readValue | pointer to the (RAM) byte to put the value read in |
uint8_t eeReadBytes | ( | uint16_t | eeAddr, |
uint8_t * | dest, | ||
uint8_t | bufferLength | ||
) |
Read EEPROM cells.
This function reads a number of consecutive EEPROM cells. Reading EEPROM is four to five times slower than RAM access.
The function fails and returns immediately if another EEPROM (or Flash write) operation is running. It must, of course, never ever be used spin waiting for success.
eeAddr | the EEPROM address to read (0 .. 4095) |
dest | the RAM address to put the EEPROM data to |
bufferLength | the number of bytes to handle 1..255 |
uint8_t eeWriteByte | ( | uint16_t | eeAddr, |
uint8_t | newValue | ||
) |
Write one EEPROM cell.
This function writes the EEPROM cell. If the (slow and wearing) write is necessary it starts the write procedure for the new changed content. The operation is quite slow (compared to RAM access) but the function returns immediately either after failure or after just starting the (3 ms) EEPROM write procedure.
The function fails if another EEPROM (or Flash write) operation is running. It should not be used by application software and it must, of course, never ever be called spin waiting for success.
eeAddr | the EEPROM address to (read and) write |
newValue | the (new) value to write in the EEPROM cell[ eeAddr] |
uint8_t initEEthreadWrite | ( | eeOp_data_t * | eeOpData, |
uint16_t | eeAddr, | ||
uint8_t * | writeBuffer, | ||
uint8_t | bufferLength | ||
) |
Initialise an EEPROM operation thread.
Before scheduling the EEPROM operation thread for first start of a bulk operation it's thread data (eeOpData) must be initialised.
Calling this or another initialising function while a thread using the structure (eeOpData) is operating will have unwanted if not catastrophic results.
eeOpData | the thread's data |
eeAddr | the EEPROM address to (read and) write |
writeBuffer | the source of the new EEPROM data |
bufferLength | the number of bytes to handle |
ptfnct_t eeOperationThread | ( | eeOp_data_t * | eeOpData | ) |
The EEPROM (bulk) write system thread; the thread function.
According to the task set in eeOpData this thread will transfer data from RAM to EEPROM.
At first schedule(s) this thread blocks as long as it has not gained access to the EEPROM.
After the operation has begun it will yield after every step requiring an EEPROM write and after every eight steps without the need to modify the EEPROM content.
As one EEPROM write requires 3.4 ms, it could be considered to schedule every forth time in a 1 ms cycle or at lower frequency.
This thread is best scheduled by
initEEthreadWrite(&eeOp_data, .....); PT_WAIT_THREAD(callingParentThread, eeOperationThread(&eeOpData));
eeOpData | pointer to the data of the EEPROM operation |
The data for an EEPROM bulk operation thread.
It is quite possible to have more than one active protothread (function eeOperationThread) at the same time. In that case each must use its own eeOp_data_t structure.
On the other hand it seems clever to restrict EEPROM access to just one thread at one time. In that case they all can use the same eeOp_data_t structure, optionally using noOfWrite as a signal for availability. This eeOpData are used by weAutSys system software at initialisation time only. Application software is free to use it afterwards (i.e. in any thread except appInitThreadF).
uint16_t eeConfigAdd |
Address of EEPROM configuration data.
This is the address of this device's EEPROM configuration data.
This EEPROM address may be in the range 64 .. (EEPROMsize - 64).
It is read at start-up from EEPROM[ EEPROM_POINTER2_EE_CONF ]. If outside said rage a default configuration will be set up at EEPROM address 64.