.. _flash:

Flash
=====

The flash is split into erasable pages of |FLASH_PAGE_SIZE|. The various
sections of flash and their associate linker files are as follows.

-  **Flash Reset Vector Table**: This table holds the first 16 reset vectors
   that are critical for booting up the device. These vectors are set at build
   time and cannot be dynamically changed.

-  **Non-volatile (NV) Area**: used for nonvolatile memory storage by the 
   Zigbee network information and also available for use by the application. See
   :ref:`z-stack-overview-nv-memory-items` for configuring NV.

-  **Application and Stack Image Code Space**: A single region that contains
   both application and stack code in flash.
   This image is configured in the linker configuration file of the application:
   <device name>\_app.cmd (CCS).

.. _using-nv:

Non-Volatile Storage Architecture
---------------------------------

This section will describe the non volatile storage system that is implemented
and used on the |DEVICE|. This system provides access to non volatile storage
that can be safely shared between the user application and the protocol stack.

The system has the following properties and offers the following features:

 - Thread safe access to non volatile memory
 - ID based system that decouples a storage item from its address in memory
 - Space efficient storage with automatic compaction
 - Power loss tolerant data preservation

The implementation of this software system relies on several layers which are
illustrated below.

.. ditaa::
    :--no-separation:

    +-----------------------+
    |       NVSRAM    cEEE  |
    |                       |
    +-----------------------+
    |       NVS Driver c000 |
    |                       |
    +-----------------------+
    |       Driverlib  cC00 |
    |       Flash APIs      |
    +-----------------------+

Non Volatile RAM (NVRAM)
^^^^^^^^^^^^^^^^^^^^^^^^

The NVRAM is an abstraction layer that defines a common set of APIs for
interacting with non volatile memory using ZBOSS. This common set of APIs
allow for new methods of NV storage to be implemented without changing the
API calls in the stack and application, as seen in :code:`ti_f3_nvram.c`.  For 
more information, please consult the |ZBOSS_UG|.

Non Volatile Storage (NVS) Driver
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The NVS driver provides reentrant functions for writing to and reading from
flash. It also provides a common interface to both internal and external flash.
More information can be found in the TI Drivers documentation. The stack will
use internal NV, currently this is all that is supported.

.. _z-stack-overview-nv-memory-items:

Non-Volatile Memory Items
-------------------------

Global Configuration Non-Volatile Memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

This feature is enabled by default by the inclusion of the :code:`ZB_USE_NVRAM`
compile option. Note that this feature must be always enabled in a real
Zigbee network. The ability to disable it is only intended for use in the development stage.

A Zigbee device has lots of state information that needs to be stored in
non-volatile memory so that it can be recovered in case of an accidental
reset or power loss. Otherwise, it will not be able to rejoin the
network or function effectively.  This includes
items such as PAN ID, key information, network settings, etc.
These items are loaded to RAM at startup for quick access during
|STACK| operation. To initialize the non-volatile memory area to store
these items, ensure that the :code:`zb_set_nvram_erase_at_start` function in 
:code:`MAIN` has a parameter of :code:`ZB_FALSE` (this is the default for 
sample applications).  Other useful APIs can be found in :code:`zboss_api.h` and 
further detailed within the |ZBOSS_UG|.

.. _sec-application-nv-memory:

Application Non-Volatile Memory
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In general, a device must have non-volatile memory enabled to be
certified, because it must remember its network configuration. In
addition to the stack ‘internal’ data, the NVM can also be used to store
application data.

Modifying Non-Volatile Memory Allocation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

By default, |STACK| projects allocate flash pages for non-volatile (NV)
memory with **Region Base** and **Region Size** settings in the 
project's .syscfg file *TI Drivers* |rarr| *NVS* |rarr| *Internal Flash*.
The command linker (:code:`.cmd`) file accounts for changes automatically.

The amount of required NV memory greatly depends on the definitions
provided in the table below.  Total NV allocation required for a |STACK|
project can be estimated by multiplying the bytes per entry by the value 
of the definition then adding them all together along with ~2.3 kB for
remaining NV items which aren't as liable to fluctuate depending on
network settings.  See the *Zigbee stack flash usage configuration* section of 
the |ZBOSS_UG| for more details.