AVR Libc Home Page AVRs AVR Libc Development Pages
Main Page FAQ Library Reference Additional Documentation Example Projects

<avr/eeprom.h>: EEPROM handling

Detailed Description

 #include <avr/eeprom.h>

This header file declares the interface to some simple library routines suitable for handling the data EEPROM contained in the AVR microcontrollers. The implementation uses a simple polled mode interface. Applications that require interrupt-controlled EEPROM access to ensure that no time will be wasted in spinloops will have to deploy their own implementation.

Note:
All of the read/write functions first make sure the EEPROM is ready to be accessed. Since this may cause long delays if a write operation is still pending, time-critical applications should first poll the EEPROM e. g. using eeprom_is_ready() before attempting any actual I/O.

This header file declares inline functions that call the assembler subroutines directly. This prevents that the compiler generates push/pops for the call-clobbered registers. This way also a specific calling convention could be used for the eeprom routines e.g. by passing values in __tmp_reg__, eeprom addresses in X and memory addresses in Z registers. Method is optimized for code size.

Presently supported are two locations of the EEPROM register set: 0x1F,0x20,0x21 and 0x1C,0x1D,0x1E (see __EEPROM_REG_LOCATIONS__).

As these functions modify IO registers, they are known to be non-reentrant. If any of these functions are used from both, standard and interrupt context, the applications must ensure proper protection (e.g. by disabling interrupts before accessing them).


avr-libc declarations

#define EEMEM   __attribute__((section(".eeprom")))
#define eeprom_is_ready()
#define eeprom_busy_wait()   do {} while (!eeprom_is_ready())
uint8_t eeprom_read_byte (const uint8_t *addr)
uint16_t eeprom_read_word (const uint16_t *addr)
void eeprom_read_block (void *pointer_ram, const void *pointer_eeprom, size_t n)
void eeprom_write_byte (uint8_t *addr, uint8_t value)
void eeprom_write_word (uint16_t *addr, uint16_t value)
void eeprom_write_block (const void *pointer_ram, void *pointer_eeprom, size_t n)

IAR C compatibility defines

#define _EEPUT(addr, val)   eeprom_write_byte ((uint8_t *)(addr), (uint8_t)(val))
#define _EEGET(var, addr)   (var) = eeprom_read_byte ((uint8_t *)(addr))

Defines

#define __EEPROM_REG_LOCATIONS__   1C1D1E

Define Documentation

#define __EEPROM_REG_LOCATIONS__   1C1D1E
 

In order to be able to work without a requiring a multilib approach for dealing with controllers having the EEPROM registers at different positions in memory space, the eeprom functions evaluate __EEPROM_REG_LOCATIONS__: It is assumed to be defined by the device io header and contains 6 uppercase hex digits encoding the addresses of EECR,EEDR and EEAR. First two letters: EECR address. Second two letters: EEDR address. Last two letters: EEAR address. The default 1C1D1E corresponds to the register location that is valid for most controllers. The value of this define symbol is used for appending it to the base name of the assembler functions.

#define _EEGET (  var,
addr   )     (var) = eeprom_read_byte ((uint8_t *)(addr))
 

Read a byte from EEPROM. Compatibility define for IAR C.

#define _EEPUT (  addr,
val   )     eeprom_write_byte ((uint8_t *)(addr), (uint8_t)(val))
 

Write a byte to EEPROM. Compatibility define for IAR C.

#define EEMEM   __attribute__((section(".eeprom")))
 

Attribute expression causing a variable to be allocated within the .eeprom section.

 
#define eeprom_busy_wait (   )     do {} while (!eeprom_is_ready())
 

Loops until the eeprom is no longer busy.

Returns:
Nothing.

 
#define eeprom_is_ready (   ) 
 

Returns:
1 if EEPROM is ready for a new read/write operation, 0 if not.

Function Documentation

void eeprom_read_block (  void *  pointer_ram,
const void *  pointer_eeprom,
size_t  n
) 
 

Read a block of n bytes from EEPROM address pointer_eeprom to pointer_ram. For constant n <= 256 bytes a library function is used. For block sizes unknown at compile time or block sizes > 256 an inline loop is expanded.

uint8_t eeprom_read_byte (  const uint8_t *  addr  ) 
 

Read one byte from EEPROM address addr.

uint16_t eeprom_read_word (  const uint16_t *  addr  ) 
 

Read one 16-bit word (little endian) from EEPROM address addr.

void eeprom_write_block (  const void *  pointer_ram,
void *  pointer_eeprom,
size_t  n
) 
 

Write a block of n bytes to EEPROM address pointer_eeprom from pointer_ram.

void eeprom_write_byte (  uint8_t *  addr,
uint8_t  value
) 
 

Write a byte value to EEPROM address addr.

void eeprom_write_word (  uint16_t *  addr,
uint16_t  value
) 
 

Write a word value to EEPROM address addr.

Automatically generated by Doxygen 1.4.1 on 23 Jan 2006.