# flash_data

Flash memory library for 18FxxJyy series

Author | Rob Hamerling, Copyright © 2012..2012, all rights reserved.
Adapted-by |
Compiler | 2.4o

Description

    Procedures and fuctions to read/erase/write flash (code) memory of 18FxxJxx.
    .
    Since erase of flash memory is required before writes and 1024 bytes are
    erased at a time with these PICs, a 1 KB block of flash must be reserved,
    and it must be on a 1KB boundary (10 LSbits of address must be zero).
    Limitations to choose a proper address are:
      - The program is located in low memory
      - The highest bytes of flash memory contain the configuration bits
        of many 18F PICs, including the J-series
    So both the lowest and the highest 1KB of code memory are not usable for
    the purpose of storing data.
    The one but highest 1K block of code memory seems the only choice!
    Beware that the program is not so big that it occupies this address.
    The location is also PIC dependent, so when changing PIC change the address!
    .
    Since flash memory is written 64 bytes at a time the block of data memory to
    be saved in flash memory must be a multiple of 64 bytes. The way to do this
    is by declaring an array of bytes (a multiple of 64) and declare the variables
    as overlay of this array.
    .
    Before including this library you have to specify:
    .
    - The address of the block of flash memory where to save your data, e.g.:
    .
      const  byte*3  FLASH_RESERVED = 0x00F800      -- one but highest 1KB block
                                                    -- for a PIC with 64KB flash
    .
    - An array named 'flash_data' containing the data
      you want to save to and restore from flash memory, e.g.:
    .
      var  byte      flash_data[128]                -- block to save in flash memory
    .
    This array may be smaller than 1KB, but not larger!
    (The JALV2 compiler doesn't support arrays larger than 256 bytes)!
    .
    Available procedures/functions:
    flash_erase_block()    - erase the 1KB block of flash memory
    flash_read_word()      - read a word (2 bytes) of flash memory
    flash_restore_block()  - restore the block of memory from flash memory
    flash_save_block()     - save the block of data memory to flash memory

Notes

    Limitations of this library:
      - Only PICs of type 18FxxJyy are supported (and only some are tested).
      - Maximum size of data block to be saved is 1024 bytes.

Dependencies

No dependency found

## Summary

### Global variables/contants

### Procedures

- `flash_save_block()`
- `flash_erase_block()`
- `flash_restore_block()`

### Functions

- `flash_read_word(word in offset) return word`

## API details

### Global variables/contants

### Procedures

- `flash_save_block()`

      Save block of data memory to flash memory
      Arguments: - none
      Returns:   - nothing
      Notes:     The whole array 'flash_data' is saved

- `flash_erase_block()`

      Erase row (1KB) of flash memory
      Arguments: - none
      Returns:   - nothing
      Notes:     - The reserved block of 1KB flash memory is erased

- `flash_restore_block()`

      Copy block of flash memory to block of data memory
      Arguments: none
      Returns:   nothing
      Notes:     The whole array 'flash_data' is restored

### Functions

- `flash_read_word(word in offset) return word`

      Read word of flash memory
      Arguments: - offset (in number of bytes) of a word in the
      reserved block of flash memory
      Returns:   - contents of the addressed word in flash memory
      Notes:     - The first word of the reserved block has offset 0.
      To read it use 'flash_read_word(0)'
       This function is especially useful to check if the
      flash memory block was ever written before when
      the first word contains some sort of identification.

## Related samples

Here are the list of samples which use this library:

18f26j11 | 18f26j11_flash_data.jal