Turbo OAD Protocol¶
The Turbo OAD Protocol was designed to speed up the traditional OAD protocol, specifically in terms of power consumption and over the air time.
Turbo OAD enables the support of using delta software updates in the OAD protocol. Delta updates are software updates that contain only the changed or updated content in the new software image.
This section describes the Turbo OAD process and how it is used in conjunction with the traditional OAD protocol described above. For information on how to enable Turbo OAD, please refer to the TI 15.4 stack OAD examples’ readme files.
Figure 99. High Level Overview of Turbo OAD integration¶
As shown in Figure 99., the core logic of Turbo OAD to create delta images is done with the Turbo OAD Image Tool, while reconstructing the delta image is done on the OAD Target device.
Turbo OAD Image Tool¶
The Turbo OAD Image tool is invoked as a post-build step by the OAD project. The purpose of the tool is to perform the delta and run-length encoding processes. The Turbo OAD Image tool takes in two binary images and outputs one delta image, which is then sent to the target OAD device through the OAD protocol described above.
The tool will also determine if a Turbo OAD is needed based on the delta image. If there is no power / image size savings by using Turbo OAD, then regular OAD will be used. The tool will output an error message indicating that the delta image was not created.
Turbo OAD Block Transfer Overview¶
The OAD protocol for transferring the image mainly remains the same. However, instead of directly writing received OAD blocks to external/internal flash, OAD blocks are cached in RAM and are decoded (during the OAD image transfer) before writing to flash. This has the following implications:
No additional flash space is required to store the delta image.
RAM is required to store received OAD blocks and a write buffer to store decoded image data before flashing. In general, the more RAM used, the faster the OAD and decoding process will be.
Since the RAM used is dynamically allocated, the OAD update could fail on initialization if there are insufficient resources to decode the delta image.
OAD block requests may need to be temporarily ‘paused’ if the block buffer cache is full and the device is still decoding data. OAD block requests will resume once there is space in the storage buffer to continue the transfer.
Turbo OAD Image Reconstruction Process Overview¶
The 15.4 OAD protocol initiates the OAD transfer by having the collector select the delta image to transfer and sending the ImgIdentifyReq to the sensor. The Turbo OAD segment header fields have been added to the ImgIdentifyReq to facilitate the transfer of delta images. For more information regarding the Turbo OAD header segment, see the Turbo OAD Delta Image Header section.
Figure 100. Turbo OAD Image Validation and Reconstruction Overview¶
Warning
Performing a Turbo OAD to a target device that has been flashed with traditional OAD firmware is not supported.
The image reconstruction process is done during the OAD transfer. The decoding process consists of a temporary block cache (ring buffer) that stores received blocks which have not been decoded. Decoded blocks are written to an image buffer that is then flashed to the device when filled.
The process begins with receiving an OAD block from the collector. After a control block instruction has been received, the decoding process will begin. When the data from the OAD block has been decoded, the block will be marked to indicate that the space can be used to store a subsequent OAD block.
Note that each OAD block is a pre-determined size as specified by the
OAD_BLOCK_SIZE define. A Delta Image block can be any arbitrary size, and
typically will be larger than OAD_BLOCK_SIZE. The implication of this is
that multiple OAD blocks must be received by the sensor until a decoding
instruction can fully be processed. However, the complete instruction does not
need to be received in order to begin the decoding process.
OAD blocks are still requested at the rate defined by OAD_BLOCK_REQ_RATE.
However, if the OAD block cache is full, the OAD transfer will be paused until
there is room to store the next block.
Figure 101. Turbo OAD Decoding State Machine¶
State |
Description |
|---|---|
Uninitialized |
Starting state before the Turbo OAD module has been initialized |
Idle |
The module is waiting for new data to be received in the block cache |
Decoding |
The module is currently decoding a delta block |
Waiting |
The module is either currently decoding a delta block or is ready to begin decoding the next block. However, not enough data is available in the block cache to continue decoding |
Done |
Completion of decoding the delta image |
Since the length of the uncompressed delta block is variable, the decoding process will yield to the application task if the image buffer has been flushed, or a full instruction has been decoded. If an instruction has not been fully decoded, the decoding process will resume after any pending application code has been executed.
Turbo OAD Delta Image Header¶
Upon completion of the OAD transfer and delta image decoding, the Turbo OAD process is complete, and the normal process of verifying the image CRC and rebooting remains the same.
The modified OAD Image Header can be seen in oad_image_header_app.c as shown here:
{
.imgID = OAD_IMG_ID_VAL,
.crc32 = DEFAULT_CRC,
.bimVer = BIM_VER,
.metaVer = META_VER, //!< Metadata version */
.techType = OAD_WIRELESS_TECH_TIMAC, //!< Wireless protocol type BLE/TI-MAC/ZIGBEE etc. */
.imgCpStat = DEFAULT_STATE, //!< Image copy status bytes */
.crcStat = DEFAULT_STATE, //!< CRC status */
.imgNo = 0x1, //!< Image number of 'image type' */
.imgVld = 0xFFFFFFFF, //!< In indicates if the current image in valid 0xff - valid, 0x00 invalid image */
.len = INVALID_LEN, //!< Image length in bytes. */
.softVer = SOFTWARE_VER, //!< Software version of the image */
.hdrLen = offsetof(imgHdr_t, fixedHdr.rfu) + sizeof(((imgHdr_t){0}).fixedHdr.rfu),
//!< Total length of the image header */
.rfu = 0xFFFF, //!< reserved bytes */
#ifdef __TI_COMPILER_VERSION__
.prgEntry = (uint32_t)&prgEntryAddr,
.imgEndAddr = (uint32_t)&flashEndAddr,
#elif defined(__IAR_SYSTEMS_ICC__)
.prgEntry = (uint32_t)(__section_begin(".intvec")), //!< Program entry address */
.imgEndAddr = (uint32_t)(__section_end("ROSTK")),
#endif
#if defined HAL_IMAGE_A
.imgType = OAD_IMG_TYPE_PERSISTENT_APP,
#else
.imgType = OAD_IMG_TYPE_APPSTACKLIB,
#endif
}
Field |
Value |
|---|---|
Segment Type |
0x05 (Delta Image) |
Wireless Technology |
0xFFFD (Sub-1 Ghz) or 0xFFFB (2.4 Ghz) |
Reserved |
0xFF |
Payload Length |
0x14 |
Field |
Size (in bytes) |
Description |
|---|---|---|
isDeltaImg |
1 |
Indicates if the image is a delta image |
memoryCfg |
1 |
OAD flash configuration (off-chip or on-chip) |
newImgCrc |
4 |
Crc value of the new/updated application image to be flashed on the device |
oldImgCrc |
4 |
Crc value of the old/current application image running on the device |
toadMetaVer |
1 |
Version of the delta image header segment |
toadVer |
1 |
Version of the Turbo OAD decoding algorithm |
Field |
Value |
Notes |
|---|---|---|
Image Length |
Delta Image Length |
Uncompressed image’s length is stored in the Turbo OAD segment header after image is reconstructed |
The Turbo OAD Version and Original Image CRC field is used during the ImgIdentifyReq to ensure that the delta image can properly be reconstructed. The length of the new image is stored in the Turbo OAD header because the OAD header’s length field is the size of the delta image and not the reconstructed image size. When the OAD header is received from delta image, the length field will be replaced with the value stored in the ‘Image Length’ field, also the Turbo OAD header segment will not be re-written from the binary image into flash when the OAD target receives the image. This is done to preserve compatibility with cc13x0 BIM.
Warning
Turbo OAD is currently not supported for on-chip OAD.