Usage by Zone

Logical Zone

The logical zone is partitioned into zones such as the system data zone, Wi-Fi calibration data zone, and user-defined MTP zone.

System Data Zone

The system data zone (0x000 ~ 0x01F, 32 bytes) is used to store system data that may be required at system boot. The system data is automatically loaded by hardware into the system registers and takes effect at system boot.

Note

Refer to the corresponding User Manual for the mapping relationship between the system data zone and the system registers.

For historical reasons, if a byte in the system data zone is programmed for the first time, the corresponding system register will retain its initial value of 0x00, rather than the 0xFF read from the logical zone. Therefore, special handling is required for the first-time programming of system data.

Note

When a byte in the system data zone has been programmed to a non-0xFF value and is then programmed back to 0xFF, the value of the corresponding system register will be 0xFF, not the initial value of 0x00. Therefore, it is not recommended to program a byte in the system data zone from a non-0xFF value to 0xFF.

System Data Programming Flow

The programming flow for system data is as follows:

../../../_images/programming_the_system_data.svg

Example

To program the value of logical address 0x02[1] to 1, follow these steps:

  1. Read the logical map to check the original value at logical address 0x02.

    AT+OTP=RMAP

    or

    u8 data_read;
OTP_LogicalRead(&data_read, 2, 1);

  2. Determine the value to be written based on the read value.

    • If the data read from logical address 0x02 in step 1 is 0xA0, it indicates that this byte is not being programmed for the first time. Perform an OR operation between 0xA0 and the target bit 0x02[1], so the new value to be written is 0xA2.

      AT+OTP=WMAP,0x2,0x1,A2

      or

      u8 data_written = 0xA2;
OTP_LogicalWrite(2, 1, &data_written);

    • If the data read from logical address 0x02 in step 1 is 0xFF, it indicates that this byte is being programmed for the first time. Perform an OR operation between 0x00 and the target bit 0x02[1], so the new value to be written is 0x02.

      AT+OTP=WMAP,0x2,0x1,02

      or

      u8 data_written = 0x02;
OTP_LogicalWrite(2, 1, &data_written);

  3. Read the data again to verify if the write operation was successful.

    AT+OTP=RMAP

    or

    u8 data_read;
OTP_LogicalRead(&data_read, 2, 1);

System Data Programming Scenarios

Generally, system data has its initial values, and the user modifies it as needed.

RTL8721Dx:

Offset

Bit

Symbol

Description

0x02

[0]

FLASH_DEEPSLEEP_EN

Enable Flash deep sleep mode when the system enters sleep mode.

0: Disable

1: Enable

0x02

[1]

SPIC_ADDR_4BYTE_EN

Enable SPI Flash controller 4-byte address mode.

0: Disable

1: Enable

0x02

[2]

SPIC_BOOT_SPEEDUP_DIS

Disable SPIC initialization speedup at boot time.

0: Speed up

1: Do not speed up

0x02

[3]

BOOT_FLASH_CLOCK_SEL

Select Flash clock at boot time.

0: 20MHz

1: 10MHz

0x02

[4]

BOOT_INT_FLASH

Select to boot from external or internal Flash.

0: Internal Flash

1: External Flash

0x02

[5]

BOOT_CNT_LMT_EN

Enable soft boot count limit.

0: Disable

1: Enable

0x02

[6]

LOGIC_PQC_EN

Enable PQC (ml-dsa-65) Check

0: Disable

1: Enable

0x02

[7]

WAKEUP_ENTRY_CHECK_EN

Enable Wakeup Entry function Check

0: Disable

1: Enable

0x03

[0]

DIS_BOOT_LOG_EN

Disable the boot log.

0: Enable

1: Disable

0x03

[1]

LOW_BAUD_LOG_EN

Select Loguart baud rate.

0: 1.5Mbps

1: 115200bps

0x03

[2]

LOGIC_SECURE_BOOT_EN

Enable Secure Boot .

0: Disable

1: Enable

0x03

[3]

LOGIC_RSIP_EN

Enable Secure Firmware Protection (RSIP) .

0: Disable

1: Enable

0x03

[4]

LOGIC_RDP_EN

Enable Read Protection (RDP) .

0: Disable

1: Enable

0x03

[5]

BOOT_RAND_DELAY_EN

Enable random delay at boot time.

0: Disable

1: Enable

0x03

[6]

USB_CLK_CAL_EN

Enable SoC clock calibration for USB.

0: Disable

1: Enable

0x03

[7]

USB_DOWNLOAD_EN

Enable USB download function.

0: Disable

1: Enable

0x1F

[7]

BOOT_VOL_SEL

Boot voltage selection

0: 0.9v

1: 1.0v

User-Defined MTP Zone

The User-defined MTP zone (0x170 ~ 0x19F, 48 bytes) can be freely used by the user.

Realtek provides dedicated APIs for this zone for user access.

API

Description

efuse_get_remaining_length

Get the remaining available length of the mapped area.

efuse_mtp_read

Read all data from the User-defined MTP area.

efuse_mtp_write

Write data to the User-defined MTP area.

efuse_get_remaining_length

Item

Description

Function

Get the remaining available length of the mapped area.

Parameters

None

Return Value

Remaining available length.

efuse_mtp_read

Item

Description

Function

Read all data from the User-defined MTP area.

Parameters

  • data: Pointer to the buffer for the data to be read.

Return Value

Read operation result.

  • RTK_SUCCESS: Success

  • RTK_FAIL: Fail

efuse_mtp_write

Item

Description

Function

Write data to the User-defined MTP area.

Parameters

  • offset: The offset address of the area to be written (base address is the User-defined MTP area start address, 0x170).

  • len: Length of the data to be written.

  • data: Pointer to the data buffer to be written.

Return Value

Write operation result.

  • RTK_SUCCESS: Success

  • RTK_FAIL: Fail

API Usage

To program the value of logical address 0x172[1] (offset address 0x2) to 1, follow these steps:

  1. Read the value from the User-defined MTP area and check the return value.

    u8 data_read[48];
int ret;
ret = efuse_mtp_read(data_read);

  2. Assume the data read from logical address 0x172 (offset address 0x2) in step 1 is 0xA0. Perform a bitwise OR operation between 0xA0 and the value for the target bit 0x172[1], keeping the other bits at their default values. Thus, the new value to be written is 0xA2.

  3. Write the new value 0xA2 to the offset address 0x2 and check the function’s return value.

    u8 data_written = 0xA2;
int ret;
ret = efuse_mtp_write(0x2, 0x1, &data_written);

Physical Zone

The physical zone is partitioned into the mapping zone, security zone, User-defined physical zone, ROM code patch zone, and hidden physical zone.

Security Zone

The security zone is divided into the following two parts:

  • Key area: 0x200~0x35F, 352 bytes. This area stores various types of keys and is automatically loaded into internal memory space at system boot.

  • Configuration area: 0x360~0x37F, 32 bytes. This area controls access permissions for the key area and other areas.

../../../_images/security_area_layout.svg

Key Area

The key area includes the following content:

RTL8721Dx:

Function

Name

Address

Usage

IPSEC

S_IPSEC_Key1 (RDP)

0x200~0x21F

Symmetric Encryption Engine

S_IPSEC_Key2

(Secure boot HMAC)

0x220~0x23F

NS_IPSEC_Key1

0x240~0x25F

NS_IPSEC_Key2

0x260~0x27F

USER PRI

USER_PRI_KEY1

0x280~0x29F

User private key area, free to use

USER_PRI_KEY2

0x2A0~0x2BF

RSIP

RSIP_KEY1

0x2C0~0x2DF

RSIP

RSIP_KEY2

0x2E0~0x2FF

SWD

SWD_PASSWORD

0x300~0x30F

SWD Protection

PSA

HUK

0x310~0x31F

HUK Derivation

Secure Boot

PK1 (ROTPK hash)

0x320~0x33F

Secure Boot

PK2 (ROTPK hash)

0x340~0x35F

Configuration Area

The content of the configuration area is shown in the table below. Refer to the detailed descriptions in the corresponding chapters for the specific usage of each field in this area.

RTL8721Dx:

Offset

Bits

Symbol

Description

Usage

0x360

[31:0]

SWD_ID

Device’s SWD ID

SWD Protection

0x364

[0]

SWD_PWD_EN

Enable SWD password

[1]

SWD_DBGEN

SWD external debug authentication

[2]

SWD_NIDEN

[3]

SWD_SPIDEN

[4]

SWD_SPNIDEN

[5]

SWD_PWD_R_Protection_EN

Key read and write protection enable

[6]

SWD_PWD_W_Forbidden_EN

[7]

HUK_W_Forbidden_EN

HUK Derivation

0x365

[0]

RSVD

[1]

PK1_W_Forbidden_EN

Secure Boot

[2]

PK2_W_Forbidden_EN

[3]

S_IPSEC_Key1_R_Protection_EN

Symmetric Encryption Engine

[4]

S_IPSEC_Key1_W_Forbidden_EN

[5]

S_IPSEC_Key2_R_Protection_EN

[6]

S_IPSEC_Key2_W_Forbidden_EN

[7]

NS_IPSEC_Key1_R_Protection_EN

0x366

[0]

NS_IPSEC_Key1_W_Forbidden_EN

[1]

NS_IPSEC_Key2_R_Protection_EN

[2]

NS_IPSEC_Key2_W_Forbidden_EN

[3]

USER_PRI_KEY1_R_Protection_EN

Read/write protection for user key area

[4]

USER_PRI_KEY1_W_Forbidden_EN

[5]

USER_PRI_KEY2_R_Protection_EN

[6]

USER_PRI_KEY2_W_Forbidden_EN

[7]

RSIP_KEY1_R_Protection_EN

RSIP

0x367

[0]

RSIP_KEY1_W_Forbidden_EN

[1]

RSIP_KEY2_R_Protection_EN

[2]

RSIP_KEY2_W_Forbidden_EN

[3]

RSIP_MODE_W_Forbidden_EN

[4]

SIC_SECURE_EN

Enable/disable SIC function

1: Enable

0: Disable

-

[5]

CPU_PC_DBG_EN

Enable/disable allowing debug port to get CPU PC value

1: Enable

0: Disable

-

[6]

UDF1_TRUSTZONE_EN

User-defined 1 area (0x380~0x3BF) security protection

0: Enable

1: Disable

-

[7]

UDF2_TRUSTZONE_EN

User-defined 2 area (0x3C0~0x3FF) security protection

0: Enable

1: Disable

-

0x368

[0]

UART_DOWNLOAD_DISABLE

Enable/disable entering UART download mode via Trap pin

0: Disable

1: Enable

-

[1]

RSVD

-

-

[2]

RSIP_EN

Enable/disable RSIP function

RSIP

[3]

SECURE_BOOT_EN

Enable/disable Secure Boot function

Secure Boot

[4]

SECURE_BOOT_HW_DIS

[5]

RDP_EN

Enable/disable RDP function

Read Protection (RDP)

[6]

ANTI_ROLLBACK_EN

OTA Firmware Upgrade

[7]

FAULT_LOG_PRINT_DIS

Enable/disable hard fault log in ROM

0: Disable

1: Enable

-

0x369

[1:0]

RSIP_MODE

RSIP mode

RSIP

[2]

HUK_DERIV_EN

Enable/disable HUK derivation

HUK Derivation

[3]

USER_PHYSICAL_TZ1_EN

User-defined physical 1 area security protection

0: Enable

1: Disable

-

[4]

USER_PHYSICAL_TZ2_EN

User-defined physical 2 area security protection

0: Enable

1: Disable

-

[5]

PQC_EN

Enable/disable PQC (ml-dsa-65) Secure Boot

-

[6]

SWTRIG_UART_DOWNLOAD_DISABLE

Enable/disable entering UART download mode via software trigger

0: Disable

1: Enable

-

[7]

SPIC_PINMUX_IN_TESTMODE_DISABLE

For Realtek use only

-

0x36A

[7:0]

RSVD

-

-

0x36B

[3:0]

SECURE_BOOT_AUTH_LOG

Secure Boot authentication algorithm

Secure Boot

[7:4]

SECURE_BOOT_HASH_LOG

Secure Boot hash algorithm

0x36C

[15:0]

OTA_ADDR

OTA address, 4K aligned

OTA Firmware Upgrade

0x36E

[15:0]

BOOTLOADER_VERSION

Bootloader version

0x370

[31:0]

CRC0

CRC check

CRC

0x374

[31:0]

CRC1

0x378

[31:0]

CRC2

0x37C

[31:0]

CRC3

Note

If RSIP_MODE_W_Forbidden_EN is programmed, then 0x369[7:0] cannot be programmed

Security Zone CRC Check

CRC is used to defend against injection attacks. Protection is achieved by comparing a valid CRC entry programmed into the OTP with the CRC value calculated by the hardware for the security zone, ensuring that the security zone has not been attacked.

RTL8721Dx:

CRC Entry Usage Rules

  • There are 4 CRC entries in total in the OTP, each including 2 bytes of magic number and 2 bytes of valid CRC value. Only one entry can be used at a time, and they must be used in sequence. The current security zone CRC value can be obtained through hardware without software calculation. When enabling a new entry, program all previously used entries to 0x00 to invalidate them. These operations are integrated into the OTP_SetCRC() function, which users only need to call.

  • The CRC calculation range is the security zone part (0x200~0x36B).

  • Ensure the security zone programming is completed before programming the CRC entry. Any modification to the calculation range in the security zone will change the CRC value, requiring reprogramming of a new CRC entry.

  • Once CRC checking is enabled, it cannot be disabled. If the magic number or valid CRC check fails, the ROM will enter an infinite loop.

Example

  1. Ensure the security zone has been modified.

  2. Write the CRC value and determine if the write was successful based on the return value and printed information.

    int ret;
ret = OTP_SetCRC();

  3. Restart the chip.

    • If the CRC entry check passes, the boot process will proceed successfully.

    • If the CRC entry check fails, the chip will enter an infinite loop in ROM and fail to boot normally.

Caution

  • It is recommended that users enable this function only when there is a need to defend against injection attacks. Otherwise, once this function is enabled, if the security zone CRC value does not match the value written to the CRC entry, the chip will be permanently unable to boot.

  • If the CRC entry has already been programmed and the user needs to modify the security zone again, the new CRC value must be written before rebooting. Otherwise, the chip will be permanently unable to boot.

User-Defined Physical Zone

There are 4 blocks in the user-defined zone, which can be used freely by the user.

RTL8721Dx:

Name

Zone

Usage Method

User_defined1

0x380-0x3BF

  • Free for user use. Can also be used for security requirements; this zone becomes a security zone when 0x367[6] is programmed to 0.

  • This zone will be inaccessible in RMA mode.

User_defined2

0x3C0-0x3FF

  • Free for user use. Can also be used for security requirements; this zone becomes a security zone when 0x367[7] is programmed to 0.

  • This zone will be inaccessible in RMA mode.

User_physical1

0x400-0x480

  • Free for user use. Can also be used for security requirements; this zone becomes a security zone when 0x369[3] is programmed to 0.

  • This zone will be inaccessible in RMA mode.

User_physical2

0x480-0x4FF

  • Free for user use. Can also be used for security requirements; this zone becomes a security zone when 0x369[4] is programmed to 0.

  • This zone will be inaccessible in RMA mode.

Realtek provides dedicated APIs for this zone for user access.

API

Description

efuse_otp_read

Read data from User-defined physical zone

efuse_otp_write

Write data to User-defined physical zone

efuse_otp_read

Item

Description

Function

Read data from User-defined physical zone

Parameters

  • offset: Offset address of target area (base address: 0x380)

  • len: Data length to read

  • buf: Pointer to data buffer

Return Value

Read operation result

  • RTK_SUCCESS: Success

  • RTK_FAIL: Failure

efuse_otp_write

Item

Description

Function

Write data to User-defined physical zone

Parameters

  • offset: Offset address of target area (base address: 0x380 for User-defined physical zone)

  • len: Data length to write

  • buf: Pointer to data buffer

Return Value

Write operation result

  • RTK_SUCCESS: Success

  • RTK_FAIL: Failure

API Usage

To program physical address 0x382[1] (offset address: 0x2) to 0, follow these steps:

  1. Read value and check return value.

    u8 data_read;
int ret;
ret = efuse_otp_read(0x2, 0x1, &data_read);

  2. Assume the read data from step 1 is 0xAF. Perform AND operation on 0xAF with target bit 0x382[1] value while keeping other bits default. The new value becomes 0xAD.

  3. Write new value 0xAD to physical address 0x02 and check return value.

    u8 data_written = 0xAD;
int ret;
ret = efuse_otp_write(0x2, 0x1, &data_written);

ROM Code Patch Zone

The ROM code patch zone (0x500 ~ 0x6FF, 512 bytes) is used for adding patches to the ROM within certain limits.

Note

  • If the ROM code patch feature is enabled, after write protection is enabled for the corresponding zone, it has the same level of security as a mask ROM.

  • At the time of chip manufacturing, if the ROM code patch feature is not enabled, ROM_PATCH_EN will be programmed to 0, permanently disabling this feature.

  • Realtek does not currently use this zone. It can be used as a user-defined zone. Please consult Realtek for the methods and precautions for using this zone.

This zone is divided into multiple parts, and each part has an independent control bit.

RTL8721Dx:

Offset

Bit

Symbol

Description

0x701

[1:0]

ROM_PATCH_EN

Enable ROM code patch function

1/2: Enable

0/3: Disable

[2]

ROM_PATCH_LWE1

Enable write protection for ROM code patch area (0x500 ~ 0x51F, 32 bytes)

0: Enable

1: Disable

[3]

ROM_PATCH_LWE2

Enable write protection for ROM code patch area (0x520 ~ 0x53F, 32 bytes)

0: Enable

1: Disable

[4]

ROM_PATCH_LWE3

Enable write protection for ROM code patch area (0x540 ~ 0x55F, 32 bytes)

0: Enable

1: Disable

[5]

ROM_PATCH_LWE4

Enable write protection for ROM code patch area (0x560 ~ 0x57F, 32 bytes)

0: Enable

1: Disable

[6]

ROM_PATCH_LWE5

Enable write protection for ROM code patch area (0x580 ~ 0x5FF, 128 bytes)

0: Enable

1: Disable

[7]

ROM_PATCH_HWE

Enable write protection for ROM code patch area (0x600 ~ 0x6FF, 256 bytes)

0: Enable

1: Disable

Hidden Physical Zone

Zone Usage

The hidden physical zone (0x700 ~ 0x7FF, 128 bytes) stores some RMA keys and Realtek calibration data. User is only allowed to program the RMA-related areas.

The specific content and usage of the hidden physical zone are shown in the table below:

RTL8721Dx:

Offset

Bits

Symbol

Description

Usage Instructions

0x700

[7:0]

RMA (Life State)

Enable/disable RMA mode.

RMA mode

0x701

[1:0]

ROM_PATCH_EN

-

ROM code patch zone

[2]

ROM_PATCH_LWE1

[3]

ROM_PATCH_LWE2

[4]

ROM_PATCH_LWE3

[5]

ROM_PATCH_LWE4

[6]

ROM_PATCH_LWE5

[7]

ROM_PATCH_HWE

0x702

[0]

RMA_SWD_PWD_R_Protection_EN

Key read protection and write protection

To add read/write protection to keys in RMA mode, write the corresponding bit to 0.

[1]

RMA_SWD_PWD_W_Forbidden_EN

[2]

RMA_PK_W_Forbidden_EN

[7:3]

RSVD

-

-

0x704

[63:0]

ADC calibration

Store ADC calibration data

-

0x710

[127:0]

RMA SWD Key

SWD key in RMA mode

Program this zone to encrypt SWD in RMA mode.

0x720

[255:0]

RMA SBOOT KEY HASH

SBOOT key hash in RMA mode

Program this zone to enable secure boot in RMA mode.

RMA Mode

RMA mode is used for customer chip returns. Users are required to program the chip into RMA mode and provide the key (if enabled) to allow Realtek to perform debugging. As shown in the figure below, in RMA mode, the secure zone and parts of the user-defined physical zone will become inaccessible. For details on how to use RMA mode Lifecycle .

../../../_images/otp_rma_access.svg