# pic_data_eeprom

reading/writing of PIC's data EEPROM

Author | Stef Mientki, Copyright © 2002..2022, all rights reserved.
Adapted-by | Sebastien Lelong, Rob Hamerling, Joep Suijs (on behalf of Tijs van Roon),
Compiler | 2.5r6

Description

    Read from or write to EEPROM/data a byte, word or double word.
    Available procedures:
      * data_eeprom_read(,)
      * data_eeprom_write(,)
      * data_eeprom_read_word(,)
      * data_eeprom_write_word(,)
      * data_eeprom_read_dword(,)
      * data_eeprom_write_dword(,)
    Available functions:
      *   = data_eeprom()
      *   = data_eeprom_word()
      *  = data_eeprom_dword()
    In all cases  is a word containing the position relative to
    the beginning of EEPROM/data memory.
    Examples of use:
      * Read a byte of EEPROM at offset 7 into x:
            var byte x
            data_eeprom_read(7, x)
      * Read a word from EEPROM at offset 4 into y:
            var word y
            y = data_eeprom_word(4)
      * Write a byte to EEPROM at offset 18:
            data_eeprom_write(18, 0b1111_0000)

Notes

    * Write-protect bits in configuration memory may prohibit writing.
    * Writing to locations outside the available memory range may have
      unexpected effects!
    * For most PICs the first EEPROM address starts at 0. For some PICs,
      this is not the case and and an offset must be added to the EEPROM address
      If an offset is needed the main program can define a constant called
      EEPROM_ADDRESS_OFFSET with the correct value so that the first
      address of the EEPROM remains 0 for the user. Some examples:
      For PIC16F18346: const  word EEPROM_ADDRESS_OFFSET = 0x7000
      For PIC18F46Q10: const dword EEPROM_ADDRESS_OFFSET = 0x31_0000
      See the datasheet of the PICs for more information.

Dependencies

No dependency found

## Summary

### Global variables/contants

### Procedures

- `data_eeprom_read_word(word in offset, word out data)`
- `data_eeprom_read_dword(word in offset, dword out data)`
- `data_eeprom_write_word(word in offset, word in data)`
- `data_eeprom_write_dword(word in offset, dword in data)`
- `data_eeprom_write(word in offset, byte in data)`
- `data_eeprom_read(word in offset, byte out data)`

Private

- `_prepare_eeprom_access(word in eeprom_address)`

### Functions

- `data_eeprom(word in offset) return byte`
- `data_eeprom_dword(word in offset) return dword`
- `data_eeprom_word(word in offset) return word`

## API details

### Global variables/contants

### Procedures

- `data_eeprom_read_word(word in offset, word out data)`

      Title:     Read word from data EEPROM at given offset
      Arguments: - Offset in data EEPROM of word to be read
       Data (word) to store EEPROM contents
      Returns:   (nothing)

- `data_eeprom_read_dword(word in offset, dword out data)`

      Title:     Read doubleword from data EEPROM at given offset
      Arguments: - Offset in data EEPROM of doubleword to be read
       Data (dword) to store EEPROM contents
      Returns:   (nothing)

- `data_eeprom_write_word(word in offset, word in data)`

      Title:     Write word to data EEPROM at given offset
      Arguments: - Offset in data EEPROM of word to be written
       Data (word) to store in EEPROM
      Returns:   (nothing)

- `data_eeprom_write_dword(word in offset, dword in data)`

      Title:     Write doubleword to data EEPROM at given offset
      Arguments: - Offset in data EEPROM of doubleword to be written
       Data (dword) to be stored
      Returns:   (nothing)

- `data_eeprom_write(word in offset, byte in data)`

      Title:     Write byte to data EEPROM at given offset
      Arguments: - Offset in data EEPROM of byte to be written
       Data (byte) to be stored in data EEPROM
      Returns:   (nothing)

- `data_eeprom_read(word in offset, byte out data)`

      Title:     Read byte from data EEPROM at given offset
      Arguments: - Offset in data EEPROM of byte to be read
       Data (byte) to store data EEPROM contents
      Returns:   (nothing)

Private

- `_prepare_eeprom_access(word in eeprom_address)`

      Title:     Set memory region bits in EECON1 and load offset register(s)
      Arguments: offset of byte to be read/written
      Returns:   (nothing)
      Notes:     Wait (spin) until any previous write completed before proceeding

### Functions

- `data_eeprom(word in offset) return byte`

      Title:     Read byte of data EEPROM at given offset
      Arguments: Offset in data EEPROM of byte to be read
      Returns:   Byte of data EEPROM

- `data_eeprom_dword(word in offset) return dword`

      Title:     Read doubleword from data EEPROM at given offset
      Arguments: Offset in data EEPROM of doubleword to be read
      Returns:   Doubleword of data EEPROM

- `data_eeprom_word(word in offset) return word`

      Title:     Read word from data EEPROM at given offset
      Arguments: Offset in data EEPROM of word to be read
      Returns:   Word of data EEPROM

## Related samples

Here are the list of samples which use this library:

16f1823 | 16f1823_data_eeprom.jal
16f18323 | 16f18323_data_eeprom.jal
16f18346 | 16f18346_data_eeprom.jal
16f19176 | 16f19176_data_eeprom.jal
16f648a | 16f648a_data_eeprom.jal
16f876a | 16f876a_rtc_timeset.jal
16f877 | 16f877_data_eeprom.jal
16f877a | 16f877a_rtc_timeset.jal
16f877a | 16f877a_data_eeprom.jal
16f88 | 16f88_data_eeprom.jal
16f88 | 16f88_remember_me.jal
18f14k50 | 18f14k50_data_eeprom.jal
18f2520 | 18f2520_data_eeprom.jal
18f2550 | 18f2550_data_eeprom.jal
18f2620 | 18f2620_data_eeprom.jal
18f27k40 | 18f27k40_data_eeprom.jal
18f452 | 18f452_data_eeprom.jal
18f4550 | 18f4550_data_eeprom.jal
18f4620 | 18f4620_data_eeprom.jal
18f46q10 | 18f46q10_data_eeprom.jal
18f6722 | 18f6722_data_eeprom.jal