Off-Chip OAD

This section describes the TI Off-chip OAD implementation. Off-chip OAD utilizes an external memory component (Flash) to store the new image during download and image selection/update.

The following procedures are unique to Off-chip OAD:

• Constraints and Requirements for Off-chip OAD
• Off-chip OAD Memory layout
• BIM for Off-chip OAD
• Out of the Box Demo (Off-Chip App Only OAD)
• sect-off-chip-add-to-proj

For information about the OAD profile and image header, please see OAD Concept Overview.

For information about the TI OAD Sample Applications that showcase On-Chip OAD, see OAD Projects Overview..

Supported Stack Image Types

Off-chip OAD supports the split image build configuration. Stack library image types can be upgraded through Off-chip OAD but that is outside the scope of this document.

Off-chip OAD supports Application Only, Stack Only, or App + Stack Merged OADs. This means that the user can update both the application and stack during the same OAD session.

Constraints and Requirements for Off-chip OAD

In order to perform an Off-chip OAD the target system must contain have:

• An off-chip flash storage of at least 124kB and space for storing external flash image header block is required for a full flash update. One flash page (4Kb) is occupied by BIM. A serial connection (SPI) is used to communicate with the off-chip flash component.
• Free GPIO pins to interface to the external memory (i.e. 4 wires for SPI)
• Enough free code space to reserve the entire contents of pg 31 (4kB) for BIM
• The OAD Image to be downloaded to the off-chip flash memory can be an application image, a stack image, a combined application plus stack, an image intended for the upgrade of a network processor, or any type of image as far as it is supposed to eventually replace any part of the on-chip 120kB area between the first page and the penultimate page. More than one image can be downloaded before the system reset followed by BIM’s copying the downloaded images from the off-chip flash memory to the on-chip flash memory.

Off-chip OAD Memory layout

The memory maps for both internal and external flash are detailed below.

Figure 89. Off-Chip OAD Memory Layout

Off-chip OAD applications use the both internal flash memory and an off-chip flash memory device. The internal flash memory contains the Interrupt Vectors (part of the User Application space), the Application where OAD Profile is embedded, the BLE stack image, the NV Storage Area, the BIM and the CCFG.

The off-chip flash memory on the CC2640R2 Launchpad contains up to 3 OAD Images and up to 3 metadata vectors corresponding to the OAD Images. The memory map layout of the external flash part is defined in ext_flash_layout.h. The size of each OAD Image placeholder is 128kB. The memory partition of the application for Off-chip OAD is depicted in Figure 89.. Each OAD image, either App only or App+Stack, must support OAD Profile so that further OAD is enabled after it is downloaded to the off-chip memory, copied to the on-chip memory, and executed.

The sectors in Figure 89. in red are designed to be permanently resident on the device. The BIM and CCFG are not intended to be upgraded via OAD. The OAD design was selected this way so that a failure during the OAD process does not yield a bricked device.

External Flash Metadata

The external flash metadata is an array of structures containing OAD downloadable information. Each structure will be stored at the start of a separate flash page to aid easy modification of an individual structure while retaining rest of the structures intact. The metadata header fields are identical to the image header with the following modifications:.

• OAD Image Identification Value is a different unique number than in the image header. BIM uses this number to find the flash page containing external flash metadata. This document will refer to this value as External Flash Image Identification Value
• Instead of Boundary Information and Contiguous Image information, the header length field is followed by the to the flash address where the actual OAD image is stored on the external flash. Note: The OAD client will calculate the storage address, by reading valid external image metadata from the image metadata array, and finding the next available storage area.

After storing the image on the external flash, the OAD application will set the Image Copy status to 0xFE if it needs to be copied to the on-chip flash. To identify the latest image to be downloaded on the on-chip flash, BIM will read the ‘Image copy status’ field of the metadata array. There should be only one image with a value of 0xFE as BIM will copy the first image with metadata status to be copied. The BIM will modify the state to 0xFC when it is done copying image to on-chip flash.

External Flash Metadata

The external flash metadata pages and the image storage will grow in opposite directions. To make the implementation more generic, each external flash metadata will store the 8 byte External Flash Image Identification Value at the beginning of the external flash metadata. If a BLE factory image is stored at first flash pages then, metadata storage would start at flash page next to the end of the image. The external flash metadata’ storage location are not fixed and BIM can find their location by reading the first eight bytes of every external flash page. For efficient BIM implementation, the OAD external flash metadata will be stored from flash page 0 onwards.

It would be application’s responsibility to find the available free storage for storing the newly downloaded image on the external flash. The image metadata area will contain the image header information for the stored OAD images with the modifications specified above.

Factory programmed BLE and other images will have OAD download capability but will not be replaceable by over the air upgrade. The user application can choose to switch to factory image. The length and location of the user defined area is configurable and will have the image metadata header like any other image.

The OAD target application gathers part of the external flash metadata information from image header and stores on the available metadata page except for the ‘CRC Status’ byte. The ‘CRC Status’ byte is updated at the last when all the image payload is stored on the flash and calculated CRC matched with the one embedded in the image header.

The rest of the available space can be used in two possible ways:

• By allocating the dedicated memory area between OAD images types
• Using area to store multiple images of variable length.

The second approach is more efficient in term of memory space usage. It requires the OAD client application to read the metadata information to figure out the length and location of available memory space. The number of co-existing OAD images will depend on individual image size and available area on the external flash.

If there is no space left for the new image, OAD client/target application can re-use the oldest image storage area to replace with new one. This can result in fragmentation. This requires time stamping the images, which can be done by simply by incorporating the counter in external flash metadata header and incrementing it every time the image is downloaded.

If application stores multiple images on the external flash, it can choose to enable a specific one of them by issuing the ‘enable’ command at OAD control point of by specifying the respective parameters (‘Image type’, ‘image number’, etc.) it wishes to activate. The active application can read the existing metadata to identify the correct image by reading the Image ID, and updating the status to 0xFE.

The application can reuse the used metadata and actual image storage flash pages by erasing it to support downloading and storage of multiple images without having a dedicated storage area for each image type.

BIM for Off-chip OAD

Warning

The BIM will link the resident CCFG sector. Furthermore, this is a custom CCFG, with the IMAGE_VALID_CONF field set to 0x1F000. This means that the boot ROM of the device will automatically execute BIM code instead of application code at startup. BIM will handle starting the application. OAD applications will not need to include a CCFG. This is a feature of CC2640R2F, and not compatible with CC2650 devices.

The OAD solution requires that permanently resident boot code, the BIM, exists in order to provide a fail-safe mechanism for determining whether to run the existing application image or to copy a new image or images from off-chip flash to internal flash (code) memory. It is assumed that a valid image exists either in off-chip flash ready to be copied or already placed in on-chip flash at any given time. Given this assumption, the initial image placed in internal flash which does not exist in external flash will have invalid external image metadata, and so the BIM will choose to jump to the existing image’s entry point.

At startup, BIM finds the location of image metadata header flash page by iterating through each page of external flash starting from page 0, by reading the first 8 bytes to find the valid External Flash Image Identification value. After locating the image metadata information, it verifies the compatibility of BIM and metadata versions. Then it checks if the ‘Image copy status’ is set to be copied to the on-chip flash(0xFE) and has a valid CRC (CRC status=0xFE). If it is, copies the image to on-chip flash, as per the image copy procedure. If any other status value is found the image will not be verified or copied to internal flash.

If it finds status ‘CRC not calculated’(CRC Status = 0xFF), it calculates the CRC and updates the CRC status byte accordingly. If it finds the valid CRC status, it copies the image to on-chip flash starting at the address pointed by ‘Start Address’ in image header of the image payload. On finding the invalid CRC it moves on to read the next image metadata. If BIM reaches the end of metadata without finding a valid image, then it will try to find an on-chip image and execute it. BIM will put the device to low power mode if it fails to find a valid application image.

An image is considered bad/invalid if it’s calculated CRC32 does not match with the image’s CRC bytes embedded in the image header.

Figure 90. Functional Overview of Off-chip BIM

Finding the last flash page containing flash metadata

In the normal condition when there are empty flash pages, the OAD client application will write the image metadata to the very first available flash page sequentially starting from flash page 0 as shown in the external flash layout. It is recommended that the application leaves least one empty flash page between metadata pages and stored image at any point in time. If the application encounters such a condition that no empty flash page is left in between the stored image pages and image metadata page, it should reuse the flash metadata pages by erasing one metadata page at a time and writing the new one. If all metadata pages are used or there would only one be empty page between the metadata pages and the image payload then the older metadata pages should be erased and reused.

Forced Image Copy

BIM will implement this optional feature based on the hardware capability, to forcibly copy a designated image from external flash to on-chip flash(using button combinations). It would help recover the target in case an invalid image has been copied on onchip flash which left the device unresponsive. This feature is disabled by default as this can pose a security risk.

Out of the Box Demo (Off-Chip App Only OAD)

The SimpleLink CC2640R2 SDK includes demo projects that are setup to use OAD in advance. These build configurations may be flashed onto the device out of the box. All out of the box demos use BTool as the OAD Downloader. Please see OAD Topology Overview for more information. Ensure that BTool is setup correctly first. See BTool Setup for steps on how to do so.

Warning

There are two BTool version shipped with the SimpleLink CC2640R2 SDK. For these steps, use the BTool version located at tools/blestack/btool.

The steps listed below assume that a CC2640R2 Launchpad is being used. Additional steps may be required for custom hardware.

Furthermore, the steps in this section are referring to the OAD Target device, the images referenced below should be flashed onto that device.

Using CCS

Warning

If both the OAD Target and the OAD Downloader are connected at the same time, CCS may load the image to the wrong device. This is because CCS will select the first XDS110 it finds. This behavior can be avoided by unplugging the OAD Target device, or by setting a multi emulator debug session using CCS. See the wiki Debug with Multiple Emulators for more information.

The steps below will describe how to run the out of the box demo for OAD on CCS.

1. Import the bim_oad_offchip, stack, and app projects into the workspace. This can be done by importing the simple_peripheral_cc2640r2lp_oad_offchip_app project. It will automatically pull in the other projects it needs.

   

   Figure 91. Offchip OAD CCS Workspace

2. Build and load the BIM project onto the CC2640R2 Launchpad

3. Build and load the simple_peripheral_cc2640r2lp_stack_oad_offchip project onto the CC2640R2 Launchpad

   • Note that a special post build step will run and generate a new image file called simple_peripheral_cc2640r2lp_oad_offchip_stack_FlashROM_oad.bin. This is the file can be provided to BTool and sent over the air.

4. Build the simple_peripheral_cc2640r2lp_app_oad_offchip project

   • Note that a special post build step will run and generate three new image files called simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad.bin, simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad_merged.bin, and simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad_merged.hex. The bin files can provided to BTool and sent over the air.

5. Open SmartRF Flash Programmer 2 to flash the application bin file. Make sure the “Pages in image” option is selected in the Erase settings. Make sure to use either the simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad.bin file (app only) or the simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad_merged.bin file (app + stack merged). By default, these images are located at \workspace_v7\<PROJECT_NAME>\FlashOnly. The start address should be given as 0x00000000.

6. You should now be able to observe that the device is advertising using BTool.

   • See BTool OAD Verify Advertising for steps.

   If your device is not advertising, make sure it is disconnected from SmartRF Flash Programmer 2.

7. Make your application level changes that are intended for OAD update. Follow steps in Changing Application Data to Verify an OAD for a trivial way to change app to verify the OAD. Build the application with changes.

8. Use BTool to OAD your modified application file following the steps detailed in BTool OAD Procedure

   • Make sure you are using the simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad.bin or the simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad_merged.bin file with BTool as this file contains the image header.

Attention

After a successful OAD, you may need to re-start your CC2640R2F in order for it to advertise again. This is because the XDS110 driver may be still attached from previous debug sessions.

Using IAR

The steps below will describe how to run the out of the box demo for OAD on IAR.

1. Open the simple_peripheral_oad_offchip workspace from the simple_peripheral_oad_offchip folder within the BLE-stack examples. This will import the BIM, stack, and application projects.

2. Build and load the cc2640r2lp_bim_offchip project onto the CC2640R2 Launchpad

3. Build and load the cc2640r2lp_stack project onto the CC2640R2 Launchpad.

4. Build the cc2640r2lp_app project.

5. Open SmartRF Flash Programmer 2 to flash the application bin file. Make sure the “Pages in image” option is selected in the Erase settings. Make sure to use either the sp_oad_offchip_cc2640r2lp_app_FlashROM_oad.bin file (app only image)or the sp_oad_offchip_cc2640r2lp_app_FlashROM_oad_merged.bin file (app + stack merged image). By default, these images are located at \examples\rtos\CC2640R2_LAUNCHXL\blestack\simple_peripheral_oad_offchip\tirtos\iar\app\FlashROM\Exe The start address should be given as 0x00000000.

6. You should now be able to observe that the device is advertising via BTool.

   • See BTool OAD Verify Advertising for steps.

   If your device is not advertising, make sure it is disconnected from SmartRF Flash Programmer 2.

7. Make your application level changes that are intended for OAD update. Follow steps in Changing Application Data to Verify an OAD for a trivial way to change app to verify the OAD. Build the application with changes.

8. Use BTool to OAD your modified application file following the steps detailed in BTool OAD Procedure

   • Make sure you are using the simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad.bin or the simple_peripheral_cc2640r2lp_oad_offchip_app_FlashROM_oad_merged.bin file with BTool as this file contains the image header.

Attention

After a successful OAD, you may need to re-start your CC2640R2F in order for it to advertise again. This is because the XDS110 driver may be still attached from previous debug sessions.