# pic_data_hef

Reading/writing of PIC's data in High Endurance Flash (HEF)

Author | Rob Jansen, Copyright © 2020..2020, all rights reserved.
Adapted-by |
Compiler | 2.5r4

Description

    Read from or write to HEF/data a byte, word or double word.
    Available procedures:
      * data_hef_read(,)
      * data_hef_write(,)
      * data_hef_read_word(,)
      * data_hef_write_word(,)
      * data_hef_read_dword(,)
      * data_hef_write_dword(,)
    Available functions:
      *   = data_hef()
      *   = data_hef_word()
      *  = data_hef_dword()
    In all cases  must be in the range of the High Endurance Flash
    Examples of use:
      * Read a byte of HEF at offset 7 into x:
            var byte x
            data_hef_read(7, x)
      * Read a word from HEF at offset 4 into y:
            var word y
            y = data_hef_word(4)
      * Write a byte to HEF at offset 18:
            data_hef_write(18, 0b1111_0000)

Sources

    AN1673. Using the PIC16F1XXX High-Endurance Flash (HEF) Block.

Notes

    * You must always define the HEF offset address (start address of the HEF)
      by definining a connstant called HEF_ADDRESS_OFFSET with the correct value.
      See the datasheet of the PICs for more information.
    * Write-protect bits in configuration memory may prohibit writing.
    * Writing to locations outside the available memory range may have
      unexpected effects!

Dependencies

No dependency found

## Summary

### Global variables/contants

### Procedures

- `data_hef_write(word in offset, byte in data)`
- `data_hef_read_dword(word in offset, dword out data)`
- `data_hef_read_word(word in offset, word out data)`
- `data_hef_read(word in offset, byte out data)`
- `data_hef_write_word(word in offset, word in data)`
- `data_hef_write_dword(word in offset, dword in data)`

Private

- `_hef_unlock()`
- `_hef_write_byte(word in address, byte in hef_data)`
- `_hef_write_flash(word in address, byte in data, bit in latch)`
- `_hef_erase(word in address)`

### Functions

- `data_hef(word in offset) return byte`
- `data_hef_word(word in offset) return word`
- `data_hef_dword(word in offset) return dword`

Private

- `_hef_read_byte(word in address) return byte`

## API details

### Global variables/contants

### Procedures

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

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

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

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

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

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

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

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

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

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

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

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

Private

- `_hef_unlock()`

      Execute the High Endurance Flash unlock sequence for writing or erasing.

- `_hef_write_byte(word in address, byte in hef_data)`

      Write one byte to the High Endurance Flash. Data is written to Flash in rows
      of (14-bit) words, called a latch. We only store bytes here.

- `_hef_write_flash(word in address, byte in data, bit in latch)`

      Write a byte from the High Endurance Flash and return it.

- `_hef_erase(word in address)`

      Write a byte from the High Endurance Flash and return it.

### Functions

- `data_hef(word in offset) return byte`

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

- `data_hef_word(word in offset) return word`

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

- `data_hef_dword(word in offset) return dword`

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

Private

- `_hef_read_byte(word in address) return byte`

      Read a byte from the High Endurance Flash and return it. Note that although
      you can store (14-bit) words we only return one byte.

## Related samples

Here are the list of samples which use this library:

16f1455 | 16f1455_data_hef.jal
16f1503 | 16f1503_data_hef.jal
16f1507 | 16f1507_data_hef.jal
16f1508 | 16f1508_data_hef.jal
16f1765 | 16f1765_data_hef.jal