SWD Hierarchical Access

The chip supports two debugging modes in both secure and non-secure areas:

Invasive debugging (interrupts CPU)
Non-invasive debugging (only samples PC without interrupting CPU)

The table below describes the OTP fields for configuring SWD debugging permission levels:

OTP Options Table for SWD Debug Permissions
Name	OTP Address	Length (bits)	Description
SWD_DBGEN	Physical address 0x364 bit[1]	1	Invasive debugging (interrupts CPU) control 1: Allows non-secure area invasive debugging (can interrupt CPU) 0: Disables non-secure area invasive debugging
SWD_NIDEN	Physical address 0x364 bit[2]	1	Non-invasive debugging (Trace) control 1: Allows non-secure area non-invasive debugging (Trace, samples PC, does not interrupt CPU) 0: Disables non-secure area non-invasive debugging
SWD_SPIDEN	Physical address 0x364 bit[3]	1	Secure area invasive debugging control 1: Allows secure area invasive debugging (can interrupt secure area CPU) 0: Disables secure area invasive debugging
SWD_SPNIDEN	Physical address 0x364 bit[4]	1	Secure area non-invasive debugging control 1: Allows secure area non-invasive debugging (Trace, samples PC, does not interrupt CPU) 0: Disables secure area non-invasive debugging

By default , all fields in the table are unprogrammed, indicating that the device supports all SWD debugging features .
If you wish to disable any SWD debugging operations, simply program all four bits in the table to 0.
Users can selectively program parts of the fields according to actual security needs, to flexibly control SWD access permissions.

Note

The OTP options for controlling SWD debugging permission levels have higher priority than the OTP options for SWD protection.

This means that even if the SWD protection OTP configuration has opened the SWD interface, the device still cannot perform SWD debugging operations as long as all debugging functions in this table are disabled.

SWD Key Authentication

Working Principle

1. Mass Production Phase

Key Storage: Program keys into the device’s OTP area to ensure device uniqueness and security.

2. Debugging Phase

Key Input: Enter keys in specified configuration files or automated tool parameters.
Authentication Trigger: Perform key consistency verification by executing automated tools.

For configuration file details and paths, see the Key Authentication Usage Steps.

3. Access Authorization

The system grants device access and debugging privileges only when the input key exactly matches the OTP-stored key.

Authentication Scheme

The system supports programming unique SWD key (“one-device-one-key”) for each device to enhance security.

This feature is optional. Users can choose whether to enable the one-device-one-key mechanism based on project requirements.

1. One-Device-One-Key Mechanism

Programming phase: Program unique SWD_ID and SWD_PASSWORD for each device, ensuring key uniqueness and non-reusability.
Backend database management: Establish a one-to-one mapping between SWD_ID and SWD_PASSWORD in the backend system for subsequent authentication.
Device debugging/authentication: Query the database using the retrieved SWD_ID to obtain the corresponding SWD_PASSWORD, enabling precise authentication for individual devices.

This scheme ensures that leakage of a single device’s credentials won’t affect other devices, significantly improving overall system security.

Note

For SWD_ID retrieval method, refer to the swdpwd_password.log file in SWD Key Authentication Usage Steps.
When using per-device unique key, properly maintain the mapping between device SWD_ID and corresponding SWD_PASSWORD.

2. Non One-Device-One-Key Mechanism

If individual device authentication is unnecessary, all devices can share the same SWD_PASSWORD without programming SWD_ID.

This scheme simplifies mass production but provides relatively lower overall security.

Key Management

OTP Key Information Description

The OTP contains the following key information:

Name	OTP Address	Length (bits)	Description
SWD_PASSWORD	Physical 0x300 ~ 0x30F	128	SWD access key for debug access authentication
SWD_ID	Physical 0x360	32	SWD unique identifier field for associating SWD access keys
SWD_PWD_EN	Physical 0x364 bit[0]	1	SWD protection enable control: 0: Enable SWD access protection 1: Disable SWD access protection
SWD_PWD_R_Protection_EN	Physical 0x364 bit[5]	1	SWD key read protection control: 0: Enable read protection (prevents key reading) 1: Disable read protection
SWD_PWD_W_Protection_EN	Physical 0x364 bit[6]	1	SWD key write protection control: 0: Enable write protection (prevents malicious full-zero writes by hackers) 1: Disable write protection

OTP Key Programming Guide

This section describes how to program OTP key information using AT commands.

Note

When programming specific bits at OTP addresses, always read-back the current byte value first, perform bitwise modification, then write back to prevent accidental modification of other bits.
After programming data to OTP addresses, perform read-back verification to ensure correct programming.

Follow these steps to program OTP key information according to the field definitions in Table OTP Key Information:

Write and Verify SWD_PASSWORD

Example: For key 0x4433221188776655ccbbaa9900ffeedd, use:

AT+OTP=WRAW,300,16,4433221188776655ccbbaa9900ffeedd

Read-back command:

AT+OTP=RRAW

Expected output:

...
RawMap[300]: 44 33 22 11 88 77 66 55 cc bb aa 99 00 ff ee dd
...

Write and Verify SWD_ID (Skip this step if using non one-device-one-key scheme)

Example: For SWD_ID=0x3412, use:
```
AT+OTP=WRAW,360,2,3412
```
Read-back command (same for subsequent steps):
```
AT+OTP=RRAW
```
Expected output:
```
...
RawMap[360]: 34 12 ff ff ff ff ff ff ff ff ff ff ff ff ff ff
...
```
Enable SWD Protection via SWD_PWD_EN
```
AT+OTP=WRAW,364,1,fe
```
Configure Protection Bits SWD_PWD_R_Protection_EN and SWD_PWD_W_Protection_EN to prevent key leakage and tampering
```
AT+OTP=WRAW,364,1,9e
```

Note

Once SWD_PWD_R_Protection_EN is programmed, SWD_PASSWORD becomes unreadable - ensure proper key backup.
OTP modifications take effect only after system reboot.

Key Authentication Usage Procedure

After programming SWD protection OTP configurations as described in SWD Key Programming Guide, follow these steps to use SWD protection:

Reboot device to reload OTP values.
Connect J-Link to board’s SWD pins.
Run the following command in the SDK root directory:

RTL8721Dx:

ameba.py jlink -t swd -k km4

If SWD key is incorrect, connection fails with:

Connecting to J-Link...
J-Link is connected.
Firmware: J-Link V11 compiled Apr 27 2041 16:36:21
Hardware: V11.00
S/N: 50120677
Feature(s): GDB, JFlash, FlashDL, RDI, FlashBP
Checking target voltage...
Target voltage: 3.33 V
Listening on TCP/IP port 2340
Connecting to target...ERROR: Could not find core in Coresight setup
ERROR: Could not connect to target.
Target connection failed. GDBServer will be closed...

Open swdpwd_password.log in {SDK}\build_RTL87xxx\jlink_script to locate device’s SWD_ID:

***************************************************************
J-Link script: ResetTarget()
******************** SWD ID ********************
J-Link script: SWD_READ_ID
SWD ID:0xFFFF1234

Note

swdpwd_password.log is auto-generated during Step 3 execution.

Query corresponding SWD_PASSWORD in database using obtained SWD_ID.
Update PASSWORD_0/1/2/3 variables in {SDK}\tools\scripts\jlink_script\jlinkscript_generate.py .

Example: For the sample key in SWD Key Programming Guide, modify:
```
U32 PASSWORD_0 = 0x11223344;
U32 PASSWORD_1 = 0x55667788;
U32 PASSWORD_2 = 0x99AABBCC;
U32 PASSWORD_3 = 0xDDEEFF00;
```
Note

Ensure script password order matches OTP storage sequence, otherwise authentication fails.
Re-run the following command in the SDK root directory:

RTL8721Dx:

ameba.py jlink -t swd -k km4

Successful connection with correct key:

Connecting to J-Link...
J-Link is connected.
Firmware: J-Link V11 compiled Apr 27 2041 16:36:21
Hardware: V11.00
S/N: 50120677
Feature(s): GDB, JFlash, FlashDL, RDI, FlashBP
Checking target voltage...
Target voltage: 3.33 V
Listening on TCP/IP port 2340
Connecting to target...Connected to target
Waiting for GDB connection...

RMA Mode SWD Key Authentication

When chips require Realtek’s assistance for suspected failures, always switch to RMA mode before returning devices and provide RMA mode authentication keys.

This is because Realtek cannot connect and debug devices via SWD without customer’s assistance.

RMA Mode SWD Key Information

RMA Mode OTP Key Configuration
Name	OTP Address	Length (bits)	Description
RMA_SWD_PASSWORD	Physical 0x710 ~ 0x71F	128	SWD key for device entering RMA mode
RMA_SWD_PWD_R_Protection_EN	Physical 0x702 bit[0]	1	RMA mode SWD key read protection: 0: Enable protection (prevents read) 1: Disable protection
RMA_SWD_PWD_W_Protection_EN	Physical 0x702 bit[1]	1	RMA mode SWD key write protection: 0: Enable protection (prevents malicious full-zero writes by hackers) 1: Disable protection

Recommendation: Avoid using the same keys for RMA mode and normal operation.

RMA Mode SWD Key Programming Guide

This section describes how to program RMA Mode SWD protection OTP configurations via AT commands.

Always follow SWD Key Programming Notes before programming RMA mode OTP entries to ensure correct operations and mitigate risks.

Follow these steps according to Table RMA Mode Key Information definitions:

Program RMA Mode SWD Key RMA_SWD_PASSWORD

Example: For RMA key 0x00333231242322211413121104030201:
```
AT+OTP=WRAW,710,16,00333231242322211413121104030201
```
Configure RMA_SWD_PWD_R_Protection_EN and RMA_SWD_PWD_W_Protection_EN to enable RMA key protection
```
AT+OTP=WRAW,702,1,fc
```
Note
- Programming RMA_SWD_PWD_R_Protection_EN makes RMA_SWD_PASSWORD unreadable. Therefore, keep the keys securely stored.
- OTP modifications take effect only after system reboot.

RMA Mode SWD Debugging Notes

After entering RMA mode, all OTP security zone data will return 0xFF, meaning:

When reading SWD_ID via SWD_ID Retrieval Method, it always returns 0xFFFFFFFF (even if actual value exists in OTP)
- Recommendation: Read and securely store SWD_ID before switching to RMA mode for accurate (RMA) key lookup in databases.
SWD Hierarchical Access Control becomes ineffective: After successful authentication, full SWD access/debugging is always permitted.