CFU V1

CFU File Introduction

File Packaging

Bank0 APP Image, Boot Patch Image, Bank0 System Patch Image, Bank0 BT Stack Patch Image and Bank0 BT Host Image. These five images can be packaged and upgraded. They can be packaged separately or combined for upgrade packaging, but it is necessary to ensure that the size of the upgraded image (excluding Boot Patch Image) does not exceed the size of the OTA Temp area configured by flash map.

Through MPPackTool.exe (select CFU V1), selecting the files that need to be upgraded for CFU packaging will generate offer bin (name.offer.bin) and payload bin (name.payload.bin), as shown below. When packaging Boot Patch Image, the two bin files of Bank0 Boot Patch Image and Bank1 Boot Patch Image need to be packaged together.

../../../../_images/CFU_Packaged_Files.png

CFU Packaged Files

File Format

Offer Bin

Offer bin provides basic information about the images upgrade, such as IC ID and firmware version, and interacts with the tool before transferring the content of images.

offer bin data

Byte

Field

Value

Byte1

Segment number

0x00

Byte2

Force ignore version (bit 7)

0 - When upgrading, the firmware will check whether the version allows upgrading (implemented by firmware, based on actual code).

1 - When upgrading, the firmware will not check the version and will enforce the upgrade.

Force immediate reset (bit6)

0 - Whether the IC will restart after completing the transfer of the upgrade file is optional.

1 - Immediate restart after completing the transfer of the upgrade file.

Reserved (bit5-bit2)

0x00

Image type (bit1-bit0)

0 - Bank0 APP Image

1 - Bank0 BT Host Image

2 - Bank0 System Patch Image

3 - other image

Byte3

Component ID

IC’s ID

For example, 87x2G is 0x0f

Byte4

Token

0x00

Byte5-Byte8

FW Version

Little-Endian, the version is four-segment format (x.x.x.x), but not segmented by byte, special parsing is needed, correctly displayed in the tool, refer to CFU Tool demo code for details.

Byte9-Byte12

Reserved

0x00

Byte13

Reserved (bit7-bit6)

0x00

Bank (bit5-bit4)

0 - bank0 (for dual bank upgrades)

1 - bank1 (for dual bank upgrades)

2 - single bank

(CFU V1 only supports single bank upgrades, so this field can only be set to 2)

Protocol version (bit3-bit0)

0x04

Byte14-Byte16

Reserved

0x00

Payload Bin

Payload bin is a repackaged file of the Images to be upgraded, generated according to Realtek’s custom format and containing the specific content of all images.

The repackaging process is as follows:

  1. Remove the MP Header from the MP image of the upgrade file 1, leaving only the raw data that needs to be written to the flash.

  2. Add a CFU header to the raw data of the upgrade file 1. CFU header (52 bytes) structure is as follows:

    CFU header data

    Field

    Size（byte）

    Value

    Image ID

    2

    0 - Bank0 APP Image

    1 - Bank0 BT Host Image

    2 - Bank0 System Patch Image

    3 - other image

    Image Version

    4

    Little-Endian, version is in 4-segment format (x.x.x.x), but not segmented by byte.

    End Address

    4

    First, append 0 to the image raw data to ensure its size is a multiple of 52, and then add the CFU header to obtain the total image size.

    Image Length

    4

    The actual size of the image raw data obtained from step 1.

    Reserved

    38

    0x00

  3. Process and concatenate upgrade files 2-N according to steps 1 and 2.

  4. Add a MSFT header to every 52 bytes of the combined file obtained from the above steps. The Repackaging Process of Payload Bin is shown in the following figure.

    MSFT header data

    Field

    Size (byte)

    Value

    Address

    4

    The starting address of the content corresponding to the MSFT header.

    Length

    1

    52
    ../../../../_images/Payload_Bin_Repackaging_Process.png

    The Repackaging Process of Payload Bin

    Example

    File address 0x00 starts with the first MSFT header: 0x00 0x00 0x00 0x00 0x34
    File address 0x34 starts with the second MSFT header: 0x34 0x00 0x00 0x00 0x34

CFU Process Overview

../../../../_images/CFU_Process_Flowchart.png

CFU Process Flowchart

Filtering Devices

CFU tool filters the current eligible USB devices according to the information configured in CFUTOOLSettings.ini like VID, PID, UsagePage, UsageTlc, SerialNumber, as shown below.

[CFU_VIA_USB_HID]
Vid=0x0bda
Pid=0x4762
UsagePage=0xff0b
UsageTlc=0x0104

...

[DEVICE]
SerialNumber=

Hint

  • VID, PID, and SerialNumber can all be set through macros in the application. If the SerialNumber in CFUTOOLSettings.ini is blank, it indicates that this information will not be filtered.

  • UsagePage and UsageTlc can be obtained from the report map of the CFU interface.

Transmission Process

CFU Firmware Version Request and Response

The CFU tool retrieves firmware information of the device to be upgraded through get report (report id 0x2A), with specific details as follows.

Get report data

Byte

Field

Value

Byte1

Component Count

0x01

Byte2-Byte3

Reserved

0x00

Byte4

Reserved (bit7-bit4)

0x00

Protocol version (bit3-bit0)

0x04

Byte5-Byte8

FW Version

Little-Endian, version is in four segments (x.x.x.x), but not segmented by byte, special analysis is needed to correctly display in the tool, specific reference can be made to CFU Tool demo code.

Byte9

Reserved (bit7-bit2)

0x00

Bank (bit1-bit0)

0x02 (indicating a single bank)

Byte10

Component ID

ID of the IC

For example, 87x2G is 0x0f.

Currently not judged by CFU tool.

Byte11-Byte12

Platform ID

Currently not judged by CFU tool.

Byte13-Byte60

Reserved

0x00

CFU Offer Request

Through Set report (report id 0x2D), the CFU tool sends the entire content of the offer bin to the device to be upgraded. Refer to Offer Bin for offer bin content.

In the offer bin generated by the packaging tool, Force ignore version default is 0. If a forced upgrade is required in this upgrade, this field in the CFU offer request needs to be modified to 1 before transmission.

CFU Offer Response

After receiving the CFU Offer Request, the device to be upgraded needs to judge the content of the received offer request and send the response with the judgment result to the CFU tool through USB IN transfer (report id 0x2D). The Component ID must be judged; when Force ignore version is 0, the FW version can be judged; Protocol version and Bank can be optionally judged as needed (default is not judged).

CFU offers response data

Byte

Field

Value

Byte1-Byte3

Reserved

0x00

Byte4

Token

0x00

Byte5-Byte8

Reserved

0x00

Byte9

Reject reason

Effective when offer status is FIRMWARE_UPDATE_OFFER_REJECT (0x02).

Byte10-Byte12

Reserved

0x00

Byte13

Offer status

FIRMWARE_UPDATE_OFFER_ACCEPT (0x01): Indicates firmware update is possible.

Other values: Indicate an error occurred, CFU tool will stop the update.

Byte14-Byte16

Reserved

0x00
Offer status

Offer status code

Name

Reason

0x00

FIRMWARE_UPDATE_OFFER_SKIP

The offer needs to be skipped at this time, indicating to the CFU driver or tool to please offer it again during the next cycle through the Offer List.

0x01

FIRMWARE_UPDATE_OFFER_ACCEPT

Once FIRMWARE_UPDATE_FLAG_LAST_BLOCK has been issued, the Primary Component can then determine if the payload is appropriate. If so, it is returned.

0x02

FIRMWARE_UPDATE_OFFER_REJECT

Once FIRMWARE_UPDATE_FLAG_LAST_BLOCK has been issued, the Primary Component can then determine if the payload is appropriate. If not, this will be returned.

0x03

FIRMWARE_UPDATE_OFFER_BUSY

The offer needs to be delayed at this time. The CFU driver or tool should not proceed to another offer in the offer list. The driver or tool may subsequently abandon the update, wait and retry the same offer, issue OFFER_NOTIFY_ON_READY, or issue OFFER_INFO_START_ENTIRE_TRANSACTION to restart the entire offer process.

0x04

FIRMWARE_UPDATE_OFFER_COMMAND_READY

Issued after receiving the OFFER_NOTIFY_ON_READY request when the Primary Component is ready to accept offers.

0xff

FIRMWARE_UPDATE_CMD_NOT_SUPPORTED

General error in interpreting the offer.
Reject reason

Reject Reason Code

Name

Cause

0x00

FIRMWARE_OFFER_REJECT_OLD_FW

The offer was rejected because the major and minor versions are not newer than the current image.

0x01

FIRMWARE_OFFER_REJECT_INV_COMPONENT

The offer was rejected due to a mismatch of Component ID.

0x02

FIRMWARE_UPDATE_OFFER_SWAP_PENDING

The offer was rejected because a previous update has been downloaded but not yet applied.

0x03

FIRMWARE_OFFER_REJECT_MISMATCH

The offer was rejected due to a mismatch of Build Type or Signer required.

0x04

FIRMWARE_OFFER_REJECT_BANK

The Bank being offered for the Component is currently in use and cannot be updated.

0x05

FIRMWARE_OFFER_REJECT_PLATFORM

The offer was rejected due to a mismatch of Platform ID.

0x06

FIRMWARE_OFFER_REJECT_MILESTONE

The offer was rejected due to a mismatch of Milestone.

0x07

FIRMWARE_OFFER_REJECT_INV_PCOL_REV

The offer indicates an interface CFU or SFUA Protocol Revision that the receiving product does not support.

0x08

FIRMWARE_OFFER_REJECT_VARIANT

The offer was rejected because the Variant bit of the Variants Mask applicable to this hardware is 0.

CFU Data Request

CFU tool through Set report (report id 0x2A), sends the content of the upgrade file in the payload bin (except for all contents outside the MSFT Header) to the device to be upgraded. The device to be upgraded receives the data and verifies it. Once verified, it stores the data in the OTA Temp area.

CFU data request

Byte

Field

Value

Byte1

Flags

0x80 - The first piece of data in the entire CFU transfer

0x40 - The last piece of data in the entire CFU transfer

0x00/0x08 - Intermediate data

Byte2

Length

52

Byte3-Byte4

Sequence Number

Starting from 0, each increments by 1.

Byte5-Byte8

Target Address

The corresponding address of the MSFT header for this piece of data.

Byte9-Byte60

CFU data

payload bin data (remove MSFT Header)

CFU Data Response

After the device to be upgraded receives the CFU Data Request, the response is sent to the CFU tool (report id 0x2C) via USB IN transfer.

CFU data response

Byte

Field

Value

Byte1-Byte2

Sequence Number

Same as the Sequence Number value in the corresponding CFU Data Request.

Byte3-Byte4

Reserved

0x00

Byte5

Status Code

FIRMWARE_UPDATE_SUCCESS (0x00): Indicates the data block was correctly received, processed, and written into flash.

Other values: Indicate an error occurred, and CFU tool will stop the upgrade.

Byte6-Byte16

Reserved

0x00
Status Code

Status Code

Name

Description

0x00

FIRMWARE_UPDATE_SUCCESS

No Error, the requested function(s) succeeded.

0x01

FIRMWARE_UPDATE_ERROR_PREPARE

Could not either:

  1. Erase the upper block.

  2. Invalidate or otherwise prepare for update.

Copy the configuration data to the upper block.

0x02

FIRMWARE_UPDATE_ERROR_WRITE

Could not write the bytes.

0x03

FIRMWARE_UPDATE_ERROR_COMPLETE

Could not set up the invocation of the new image, in response to FIRMWARE_UPDATE_FLAG_LAST_BLOCK.

0x04

FIRMWARE_UPDATE_ERROR_VERIFY

Verification of the CFU data failed, in response to FIRMWARE_UPDATE_FLAG_VERIFY.

0x05

FIRMWARE_UPDATE_ERROR_CRC

CRC of the image failed, in response to FIRMWARE_UPDATE_FLAG_LAST_BLOCK.

0x06

FIRMWARE_UPDATE_ERROR_SIGNATURE

Signature verification failed, in response to FIRMWARE_UPDATE_FLAG_LAST_BLOCK.

0x07

FIRMWARE_UPDATE_ERROR_VERSION

Version verification failed, in response to FIRMWARE_UPDATE_FLAG_LAST_BLOCK.

0x08

FIRMWARE_UPDATE_SWAP_PENDING

CFU image has already been updated and invocation is pending. No further CFU Offers or CFU Data can be accepted until the invocation has completed.

0x09

FIRMWARE_UPDATE_ERROR_INVALID_ADDR

Target address is invalid.

0x0a

FIRMWARE_UPDATE_ERROR_NO_OFFER

The CFU Data Report was received without prior acceptance of a CFU Offer.

0x0b

FIRMWARE_UPDATE_ERROR_INVALID

General error for unspecified invalid input, such as an invalid Data Length or implementation-specific violations.

Upgrade Success or Failure

During the transmission process, the CFU tool may receive the following error responses:

  1. When the CFU tool receives an offer response where the Offer status is not FIRMWARE_UPDATE_OFFER_ACCEPT (0x01).

  2. When the CFU tool receives a data response where the Status Code is not FIRMWARE_UPDATE_SUCCESS (0x00).

When the CFU tool receives an error response, it will default to considering the upgrade a failure and will immediately stop the upgrade.

After the CFU tool transmits the final data request (Flags 0x40), and the upgrade device completes the integrity check of the upgrade file, it returns a success response to the CFU tool, confirming that the upgrade was successful. After that, DUT will reboot itself and transfer the upgrade file stored in the OTA Temp to the flash execution area. After the upgrade device restarts, the CFU tool can obtain the version number through the CFU Firmware Version Request to confirm whether the upgrade was truly successful, as shown in the following figure.

../../../../_images/CFU_Success_Flowchart.png

CFU Success Flowchart

Hint

For handling error responses, the default behavior of the CFU tool in version V2.1.1.0 and earlier differs from the latest version. The upgrade process halts immediately only when receiving FIRMWARE_UPDATE_ERROR_WRITE. For other errors, the tool performs a retry. The upgrade is considered failed only if an error response is received again. If users need to modify this behavior of the tool, refer to CFU Tool demo code.

CFU HID Description

#define REPORT_ID_CFU_FEATURE           0x2A
#define REPORT_ID_CFU_FEATURE_EX        0x2B
#define REPORT_ID_CFU_OFFER_INPUT       0x2D
#define REPORT_ID_CFU_OFFER_OUTPUT      REPORT_ID_CFU_OFFER_INPUT
#define REPORT_ID_CFU_PAYLOAD_INPUT     0x2C
#define REPORT_ID_CFU_PAYLOAD_OUTPUT    REPORT_ID_CFU_FEATURE

#define USAGE_ID_CFU_PAYLOAD_OUTPUT     0x61
#define USAGE_ID_CFU_FEATURE            0x62
#define USAGE_ID_CFU_FEATURE_EX         0x65
#define USAGE_ID_CFU_PAYLOAD_INPUT_MIN  0x66
#define USAGE_ID_CFU_PAYLOAD_INPUT_MAX  0x69
#define USAGE_ID_CFU_OFFER_INPUT_MIN    0x8A
#define USAGE_ID_CFU_OFFER_INPUT_MAX    0x8D
#define USAGE_ID_CFU_OFFER_OUTPUT_MIN   0x8E
#define USAGE_ID_CFU_OFFER_OUTPUT_MAX   0x91

0x06, 0x0B, 0xFF,   // Usage Page (Vendor Defined 0xFF0B)
0x0A, 0x04, 0x01,   // Usage (0x0104)
0xA1, 0x01,         // Collection (Application)
// 8-bit data
0x15, 0x00,                         // Logical Minimum (0)
0x26, 0xFF, 0x00,                   // Logical Maximum (255)
0x75, 0x08,                         // Report Size (8)
0x95, 0x3c,                         // Report Count (60)
0x85, REPORT_ID_CFU_FEATURE,        // Report ID (0x2A)
0x09, 0x60,                         // Usage (0x60)
0x82, 0x02, 0x01,                   // Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Buffered Bytes)
0x09, USAGE_ID_CFU_PAYLOAD_OUTPUT,  // Usage (0x61)
0x92, 0x02, 0x01,                   // Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile,Buffered Bytes)
0x09, USAGE_ID_CFU_FEATURE,         // Usage (0x62)
0xB2, 0x02, 0x01,                   // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile,Buffered Bytes)
0x85, REPORT_ID_CFU_FEATURE_EX,     // Report ID (0x2B)
0x09, USAGE_ID_CFU_FEATURE_EX,      // Usage (0x65)
0xB2, 0x02, 0x01,                   // Feature (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile,Buffered Bytes)
// 32-bit data
0x17, 0x00, 0x00, 0x00, 0x80,       // Logical Minimum (-2147483649)
0x27, 0xFF, 0xFF, 0xFF, 0x7F,       // Logical Maximum (2147483646)
0x75, 0x20,                         // Report Size (32)
0x95, 0x04,                         // Report Count (4)
0x85, REPORT_ID_CFU_PAYLOAD_INPUT,  // Report ID (0x2C)
0x19, USAGE_ID_CFU_PAYLOAD_INPUT_MIN,// Usage Minimum (0x66)
0x29, USAGE_ID_CFU_PAYLOAD_INPUT_MAX,// Usage Maximum (0x69)
0x81, 0x02,                         // Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x85, REPORT_ID_CFU_OFFER_INPUT,    // Report ID (0x2D)
0x19, USAGE_ID_CFU_OFFER_INPUT_MIN, // Usage Minimum (0x8A)
0x29, USAGE_ID_CFU_OFFER_INPUT_MAX, // Usage Maximum (0x8D)
0x81, 0x02,                         // Input (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position)
0x19, USAGE_ID_CFU_OFFER_OUTPUT_MIN,// Usage Minimum (0x8E)
0x29, USAGE_ID_CFU_OFFER_OUTPUT_MAX,// Usage Maximum (0x91)
0x91, 0x02,                         // Output (Data,Var,Abs,No Wrap,Linear,Preferred State,No Null Position,Non-volatile)
0xC0,                               // End Collection