.. _sec-mcuboot-oad-flash-layout-on-chip-stack-library:

Flash Layout for On-Chip OAD
=============================

This section will describe the method for placing images in internal
flash when using on-chip OAD.


Constraints and Requirements for On-chip OAD (stack library)
------------------------------------------------------------

The following points must be considered for On-chip OAD applications:

  - The user application must be sufficiently small in order to fit into the
    flash layout system described below
  - User app functionality is lost while performing OAD (Persistent app is
    running)

.. _sect-mcuboot-on-chip-memory-layout-stack-library:

Internal Flash Memory Layout
----------------------------

The internal flash of the device contains the active user application, the user
application's stack, the persistent application, the persistent application's
stack, and the secure bootloader. Each application's role is defined below.

.. note::     
    As we have assumed the stack-library approach, the stack images
    referenced below are a part of each application image (i.e. the user and
    persistent apps have their own dedicated stack)

+------------------------+---------------------------------------------------------------------+
| Application Name       | Description                                                         |
+------------------------+---------------------------------------------------------------------+
| MCUboot bootloader     | - Search for the proper image in FLASH                              |
|                        | - Ensure validity and security of image before running              |
|                        | - Jump to the valid and newest image                                |
+------------------------+---------------------------------------------------------------------+
| Persistent application | - Providing lightweight application that implements the OAD profile |
|                        | - Permanent resident on the device                                  |
+------------------------+---------------------------------------------------------------------+
| Stack (2)              | - BLE protocol stack implementation                                 |
+------------------------+---------------------------------------------------------------------+
| User application       | - User application                                                  |
|                        | - Must implement OAD reset service                                  |
|                        | - Implementing customer defined behavior                            |
+------------------------+---------------------------------------------------------------------+

.. _fig-mcuboot-on-chip-oad-target-memory-partition:
.. ditaa::
    :--no-separation:

                                                       Internal Flash
                                                   +-------------------+ <- 0x00000000
                                                   |   MCUboot         |
                                                   |   Bootloader      |
                                                   |      cRED         |
                                                   +-------------------+ <- 0x00006000
                                                   | Persistent App    |
                                                   | Header            |
                                                   | c7AF              |
                                                   +-------------------+
                                                   |   Persistent      |
                                                   |   Application     |  Secondary Slot
                                                   |        +          |
                                                   |   Stack Library   |
                                                   |       c7AF        |
                                                   +-------------------+ <- 0x00032000
                                                   | User App + Stack  |
                                                   | Header            |
                                                   | c7AF              |
                                                   +-------------------+ <- 0x00032100
                                                   |  User Application |
                                                   |        +          |  Primary Slot
                                                   |  Stack Library    |
                                                   |      c7AF         |
                                                   |                   |
                                                   |                   |
                                                   |                   |
                                         /-------> +-------------------+ <- Device Flash Size - 0x4000
     +------------------------------+    |         |   NV Space        |
     |  NV Information is           |    |         |   Reserved for    |
     |  shared between              |    |         |   Bonding         |
     |  Persistent and User         |    |         |   Information     |
     |  Application                 |    |         |        c777       |
     |                              |    |         |                   |
     +------------------------------+----\-------> +-------------------+ <- Device Flash Size

.. note:: 

    Based on different devices, the address of each component listed above might
    vary. The address used in the persistent application linker file
    should match the settings in the ``flash_map_backend.h`` file. This file is
    generated and modified within SysConfig.

    .. code-block:: c
        :caption: Flash addresses for various components

        #define BOOTLOADER_BASE_ADDRESS            0x00000000 
        #define BOOT_BOOTLOADER_SIZE               0x00006000 
        #define BOOT_PRIMARY_1_BASE_ADDRESS        0x00006000 
        #define BOOT_PRIMARY_1_SIZE                0x00076000 
        #define BOOT_SECONDARY_1_BASE_ADDRESS      0x00043000 
        #define BOOT_SECONDARY_1_SIZE              0x0003d000

