# EEPROM

## Defines
#define | DEBUG_VERBOSE_LEVEL 1
#define | DEBUG_MSG MIOS32_MIDI_SendDebugMessage
#define | PAGE0_BASE_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + 0x000))
#define | PAGE0_END_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + (PAGE_SIZE - 1)))
#define | PAGE1_BASE_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + PAGE_SIZE))
#define | PAGE1_END_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + (2 * PAGE_SIZE - 1)))
#define | PAGE0 ((uint16_t)0x0000)
#define | PAGE1 ((uint16_t)0x0001)
#define | NO_VALID_PAGE ((uint16_t)0x00AB)
#define | ERASED ((uint16_t)0xFFFF)
#define | RECEIVE_DATA ((uint16_t)0xEEEE)
#define | VALID_PAGE ((uint16_t)0x0000)
#define | READ_FROM_VALID_PAGE ((uint8_t)0x00)
#define | WRITE_IN_VALID_PAGE ((uint8_t)0x01)
#define | PAGE_FULL ((uint8_t)0x80)
#define | PAGE0_BASE_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + 0x000))
#define | PAGE0_END_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + (PAGE_SIZE - 1)))
#define | PAGE1_BASE_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + PAGE_SIZE))
#define | PAGE1_END_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + (2 * PAGE_SIZE - 1)))
#define | PAGE0 ((uint16_t)0x0000)
#define | PAGE1 ((uint16_t)0x0001)
#define | NO_VALID_PAGE ((uint16_t)0x00AB)
#define | ERASED ((uint16_t)0xFFFF)
#define | RECEIVE_DATA ((uint16_t)0xEEEE)
#define | VALID_PAGE ((uint16_t)0x0000)
#define | READ_FROM_VALID_PAGE ((uint8_t)0x00)
#define | WRITE_IN_VALID_PAGE ((uint8_t)0x01)
#define | PAGE_FULL ((uint8_t)0x80)
## Functions
s32 | EEPROM_Init (u32 mode)
| Restore the pages to a known good state in case of page's status corruption after a power loss.
s32 | EEPROM_Read (u16 VirtAddress)
| Returns the last stored variable data, if found, which correspond to the passed virtual address.
s32 | EEPROM_Write (u16 VirtAddress, u16 Data)
| Writes/upadtes variable data in EEPROM.
s32 | EEPROM_SendDebugMessage (u32 mode)

## Detailed Description

The LPC17 variant uses the on-board EEPROM of the LPCXPRESSO module

The 24LC64 allows to store up to 8192 bytes.

Since this driver works halfword-wise to keep it compatible to the STM32 variant, this means that EEPROM_EMULATED_SIZE can be up to 4096

Optionally an external EEPROM can be connected to one of the two IIC ports of the MBHP_CORE_LPC17 by setting following defines in mios32_config.h

set this either to 0 (for first IIC port) or 2 (for second IIC port) IIC1 selects the on-board EEPROM define EEPROM_IIC_DEVICE 1 Set a device number if the 3 address pins are not tied to ground define EEPROM_IIC_CS 0

Usage:

- EEPROM_Init(0) should be called after startup to check for valid flash pages. Pages will be formatted if this hasn't been done before.
  Formatting can be enforced with EEPROM_Init(1)
- EEPROM_Read(u16 address) reads a 16bit value from EEPROM
  Returns <0 if address hasn't been programmed yet (it's up to the application, how to handle this, e.g. value could be zeroed)
  Extra LPC17: returns -1 if EEPROM not available
- EEPROM_Write(u16 address, u16 value): programs the 16bit value

Configuration: optionally EEPROM_EMULATED_SIZE can be overruled in mios32_config.h to change the number of virtual addresses.

By default, 128 addresses are available:

     #define EEPROM_EMULATED_SIZE 128  // -> 128 half words = 256 bytes

Example application:
$MIOS32_PATH/apps/tutorials/025_sysex_and_eeprom (see patch.c)

Usage:

- EEPROM_Init(0) should be called after startup to check for valid flash pages. Pages will be formatted if this hasn't been done before.
  Formatting can be enforced with EEPROM_Init(1)
- EEPROM_Read(u16 address) reads a 16bit value from EEPROM
  Returns <0 if address hasn't been programmed yet (it's up to the application, how to handle this, e.g. value could be zeroed)
- EEPROM_Write(u16 address, u16 value): programs the 16bit value

Configuration: optionally EEPROM_EMULATED_SIZE can be overruled in mios32_config.h to change the number of virtual addresses.

By default, 128 addresses are available:

     #define EEPROM_EMULATED_SIZE 128  // -> 128 half words = 256 bytes

Note: each address allocates 4 bytes in flash. The emulation can handle with two pages (STM32F103RB: 2*1k, STM32F103RE: 2*2k), and the number of addresses shouldn't exceed (page size - 4).

Accordingly, the maximum EEPROM_EMULATED_SIZE for STM32F103RB is 255, and for STM32F103RE 511.
Than lower the specified size, than faster EEPROM_Write() will work, especially once pages have to be switched.

Example application:
$MIOS32_PATH/apps/tutorials/025_sysex_and_eeprom (see patch.c)

Additional informations to EEPROM emulation approach:
http://www.st.com/stonline/products/literature/an/13718.pdf

Usage:

- EEPROM_Init(0) should be called after startup to check for valid flash pages. Pages will be formatted if this hasn't been done before.
  Formatting can be enforced with EEPROM_Init(1)
- EEPROM_Read(u16 address) reads a 16bit value from EEPROM
  Returns <0 if address hasn't been programmed yet (it's up to the application, how to handle this, e.g. value could be zeroed)
- EEPROM_Write(u16 address, u16 value): programs the 16bit value

Configuration: optionally EEPROM_EMULATED_SIZE can be overruled in mios32_config.h to change the number of virtual addresses.

By default, 128 addresses are available:

     #define EEPROM_EMULATED_SIZE 128  // -> 128 half words = 256 bytes

Note: each 16bit address allocates 4 bytes in flash. The emulation can handle with two pages (STM32F4xx: 2*16k), and the number of addresses shouldn't exceed (page size - 4).

Accordingly, the maximum EEPROM_EMULATED_SIZE for STM32F4xx is 4095.
Than lower the specified size, than faster EEPROM_Write() will work, especially once pages have to be switched.

Example application:
$MIOS32_PATH/apps/tutorials/025_sysex_and_eeprom (see patch.c)

Additional informations to EEPROM emulation approach:
http://www.st.com/stonline/products/literature/an/13718.pdf

## Define Documentation

#define DEBUG_MSG MIOS32_MIDI_SendDebugMessage

#define DEBUG_VERBOSE_LEVEL 1

#define ERASED ((uint16_t)0xFFFF)

#define NO_VALID_PAGE ((uint16_t)0x00AB)

#define PAGE0 ((uint16_t)0x0000)

#define PAGE0_BASE_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + 0x000))

#define PAGE0_END_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + (PAGE_SIZE - 1)))

#define PAGE1 ((uint16_t)0x0001)

#define PAGE1_BASE_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + PAGE_SIZE))

#define PAGE1_END_ADDRESS ((uint32_t)(EEPROM_START_ADDRESS + (2 * PAGE_SIZE - 1)))

#define PAGE_FULL ((uint8_t)0x80)

#define READ_FROM_VALID_PAGE ((uint8_t)0x00)

#define RECEIVE_DATA ((uint16_t)0xEEEE)

#define VALID_PAGE ((uint16_t)0x0000)

#define WRITE_IN_VALID_PAGE ((uint8_t)0x01)

## Function Documentation

s32 EEPROM_Init | ( | u32 | mode | ) |

Restore the pages to a known good state in case of page's status corruption after a power loss.

Connects to the (on-board) EEPROM

Parameters:

  `[in]` | mode | 0: normal initialisation, 1: enforce formatting

Returns:
  < 0 on error

Parameters:

  | mode | 0: normal initialisation, 1: enforce formatting

Return values:

  | - | < 0: error during writing flash 0: on success

Here is the call graph for this function:

s32 EEPROM_Read | ( | u16 | VirtAddress | ) |

Returns the last stored variable data, if found, which correspond to the passed virtual address.

Returns the 16bit word on the given halfword address

Parameters:

  `[in]` | address | the address which should be read

Returns:
  >= 0 if value could be successfully read (16bit value)
  -1 if EEPROM not available

Parameters:

  | VirtAddress,: | Variable virtual address

Return values:

  | Success | or error status: >= 0: the 16bit variable if it has been found -1: if the variable was not found (not programmed yet) -2: if no valid page was found.

s32 EEPROM_SendDebugMessage | ( | u32 | mode | ) |

Sends the EEPROM content and optionally the whole flash page content to the MIOS Terminal

Parameters:

  `[in]` | mode | following modes are provided: 0: send EEPROM content 1: send content of flash pages 2: send EEPROM content and flash pages

Returns:
  < 0 on errors

Here is the call graph for this function:

s32 EEPROM_Write | ( | u16 | VirtAddress,
|  | u16 | Data |
| ) |  |  |

Writes/upadtes variable data in EEPROM.

Writes into EEPROM at given halfword address

Parameters:

  `[in]` | address | the address which should be written
  `[in]` | value | the 16bit value which should be written

Returns:
  0 on success, < 0 on errors

Parameters:

  | VirtAddress,: | Variable virtual address
  | Data,: | 16 bit data to be written

Return values:

  | Success | or error status: 0: on success -1: if valid page is full -2: if no valid page was found -3: on write flash error

Here is the call graph for this function: