Examples#

Requirements#

Before proceeding to the examples for debug lock, ensure the following requirements are met. If each of these requirements are not used, debug locking and unlocking may not occur as expected.

Simplicity Commander#

Silicon Labs recommends using Simplicity Commander version 1v17p0 (1.17.0) or later for SiWx917 operations. To check the version of commander installed, enter the following command.

commander -v 
Simplicity Commander 1v17p1b1824
JLink DLL version: 7.96t
Qt 5.15.2 Copyright (C) 2017 The Qt Company Ltd.
EMDLL Version: 0v19p11b768
mbed TLS version: 2.16.6
DONE

Connectivity Firmware#

Silicon Labs strongly recommends upgrading connectivity firmware for the NWP to the latest version available to include the latest features, bug fixes, and security patches. Refer to the Simplicity Studio User's Guide for instructions on updating the connectivity firmware through Simplcity Studio. Refer to the WiSeConnect SDK Release Notes for details on each connectivity firmware release.

ISP Mode#

Wireless Pro Kit Adapter Firmware#

Provisioning security settings onto a factory new SiWx917 requires access to the ISP bootloader through the UART. On the BRD4002A Wireless Pro Kit (WPK), access is available through the virtual com port (VCOM). The WPK adapter firmware version required for communication with the ISP bootloader is 1v5p0b240 or greater. Refer to the Simplicity Studio User's Guide for details on updating adapter firmware.

Entering ISP Mode#

To enable access to the ISP bootloader through the VCOM port, the following steps are required:

  1. Connect the WPK board by USB to your computer.

  2. Open Simplicity Studio.

  3. Right-click the WPK in the Debug Adapters panel and select the Launch Console menu item.

  4. Select the Admin tab.

  5. Enter the following in the text entry box and press Enter: serial vcom config handshake aux

  6. Close Simplicity Studio.

To enter ISP mode, press and hold the ISP button on the SiWx917 radioboard (for example, BRD4338A) while pressing and releasing the reset button on the WPK (BRD4002A), and before releasing the ISP button.

To verify that the device is in ISP mode, open a terminal window, and use the UART settings listed in the following table for communication with the ISP bootloader. Once in ISP mode, enter any key in the terminal window. You then should see a prompt stating "Enter 'U'" in the terminal window.

Setting

Value

Baud rate

115200

Parity

None

Data bits

8

Stop bits

1

Signature Validation#

Before proceeding to the examples section, complete the steps listed in the Examples section of AN1442 for provisioning a device and signing an application for signature validation. It is recommended to flash the signed application image before proceeding with enabling debug locking.

Locking Debug Access#

This section demonstrates how to lock the JTAG ports of the SiWx917. When enabling this feature in development, eFuses should be set in MBR. In production, these eFuse settings should be programmed in eFuse data in OTP. In this section, the MBR settings will be used to enable the debug locks.

In this example, a copy of the debug token is saved locally when locking the JTAG ports. Saving a copy of the debug token is optional but recommended because the debug token can be used later to unlock a JTAG port without needing to access a private key.

Note: Before continuing with the steps outlined in this section, ensure all requirements listed in Requirements are met, including enabling signature validation.

  1. Read out the MBR file.

    commander mfg917 read tambr --out tambr.json
    Reading data from region: tambr
Reading 496 bytes from 0x04000000
Writing JSON...
Manufacturing data saved to file 'tambr.json'
DONE

  2. Edit MBR contents to set the disable JTAG eFuses.

     {
    "valids": 0,
    "puf_activation_code_addr": 8192,
    "valids": 0,
 "efuse_data": {
        "m4_digital_signature_validation": 1,
        "ta_digital_signature_validation": 1,
        **"disable\_ta\_jtag":1,
        "disable\_m4\_jtag":1**
    },
    "key_desc_table_addr": 768
}

  3. First, enter ISP mode using the steps listed in ISP Mode. Once in ISP mode, write the updated MBR file to flash.

    commander mfg917 write tambr --data tambr.json
    Reading JSON...
Updating CRCs...
Writing data to region: tambr
Loading RAM code (321776 bytes)...
Starting RAM code...
Data loaded successfully
Region 'tambr' was successfully written to device.
DONE

  4. Generate a nonce to lock access to the NWP core and save the token. The NWP core must be locked before the M4 core lock is applied.

    commander serial lock ta --token debug_nwp.token --key ta_private_key.pem --serialport COM3 --device si917
    Initializing debug lock...

Nonce generated by the device: 0C8BDB0DF4936171F6977E3237D3FED2

Debug access will be locked after the device is reset.

Image SHA256: 434b15abf5e30f1a2eea7782799723d9e9c7cd78462a82cae7c010b8bb5a0144

R = 0E9BF63D25AFFD678390D402EC665D004FC98B3457417F02B37EC14790020F8F

S = 1865648147A4A906BDAA095A45051B02FC10E3E3B2B2DF642ED5EF39A9953417

Debuglock token raw data:

0c8bdb0df4936171f6977e3237d3fed27400000000000000304402200e9bf63d25affd678390d402ec665d004fc98b3457417f02b37ec
14790020f8f02201865648147a4a906bdaa095a45051b02fc10e3e3b2b2df642ed5ef39a99534170000

Debuglock token written to 'debug_nwp.token'.

DONE

    Note: This command will also accept a keys.json file when specifying the key used to sign the debug token.

  5. Perform a hard reset to lock the NWP JTAG port.

  6. Generate a nonce to lock access to the M4 core and save the token.

    commander serial lock m4 --token debug_m4.token --key m4_private_key.pem --serialport COM3 --device si917
    Initializing debug lock...

Nonce generated by the device: 603B663BFD006CC79EB61F805FC8D3F6

Debug access will be locked after the device is reset.

Image SHA256: 56bdc05ecf5732b0b1374a99d8f78835a3edc38e0a8755da4ffd3bb5e031174f

R = E0026EA7FD4064E8E15B651A3251FD8071B0DEDE1EF802D7A84A0FAD491B3B3E

S = 8273DD099F1AB3B4FC05048438778ABAF908B9ED7DBB4A960CC618F3F8BFFEB6

Debuglock token raw data:

603b663bfd006cc79eb61f805fc8d3f66d000000000000003046022100e0026ea7fd4064e8e15b651a3251fd8071b0dede1ef802d
7a84a0fad491b3b3e0221008273dd099f1ab3b4fc05048438778abaf908b9ed7dbb4a960cc618f3f8bffeb6

Debuglock token written to 'debug_m4.token'.

DONE

    Note: This command will also accept a keys.json file when specifying the key used to sign the debug token.

  7. Perform a hard reset to lock the M4 JTAG port.

Unlocking Debug Access with a Token#

  1. Unlock the M4 JTAG port using the debug token generated in Step 6 of Locking Debug Access..

    commander serial unlock m4 --token debug_m4.token --serialport COM36 --device si917
    Using the provided token 'debug_m4.token' to unlock debug access...

Verifying debuglock token 'debug_m4.token'...

Initializing debug unlock...

Debug access will be unlocked after the device is reset.

DONE

  2. Perform a hard reset to unlock the M4 JTAG port.

  3. Unlock the NWP JTAG port using the debug token generated in Step 4 of Locking Debug Access..

    commander serial unlock ta --token debug_nwp.token --serialport COM3 --device si917
    Using the provided token 'debug_nwp.token' to unlock debug access...

Verifying debuglock token 'debug_nwp.token'...

Initializing debug unlock...

Debug access will be unlocked after the device is reset.

DONE

  4. Perform a hard reset to unlock the NWP JTAG port.

  5. Once the debugging session is complete, update the challenge nonce by locking the ports again as described in Locking Debug Access.

Unlocking Debug Access with a Private Key#

Another option for unlocking the JTAG port is to use the private key per core to unlock the port, instead of using a pre-saved token. In the background, when a core is unlocked using a private key, Simplicity Commander will ask the device to generate and return a new nonce, and will package the nonce, signature, core command, and other data as a token. Simplicity Commander then sends this new token to the device to unlock the core.

  1. Unlock the M4 JTAG port.

    commander serial unlock m4 --key m4_private_key.pem --serialport COM36 --device si917
    Using serial port 'COM36' for file transfers.
Initializing debug unlock...
Nonce generated by the device 6D6DA3100AB5AD6D2B5BA1B62478652B
Parsing signing key 'm4_private_key.pem'...
Debuglock token raw data:
6d6da3100ab5ad6d2b5ba1b62478652b6d000000000000003046022100d803b7633f74a019d7e3656f9d72a7ed7b4
fbb2c85b67bffd79e355560022100ed2b57569f2101f3a6006ea119bf1f53577e72b8374b31cce79a480be34de6b3
Debuglock token written to 'C:/Users/../../../debugtoken'.
Debug access will be unlocked after the device is reset.
DONE

    Note: This command will also accept a keys.json file when specifying the key used to sign the debug token.

  2. Reset the part to unlock the M4 JTAG port.

  3. Unlock the NWP JTAG port. The NWP port will only be unlocked if the M4 debug port is unlocked.

    commander serial unlock ta --key ta_private_key.pem --serialport COM36 --device si917
    Using serial port 'COM36' for file transfers.
Initializing debug unlock...
Nonce generated by the device 6D6DA3100AB5AD6D2B5BA1B62478652B
Parsing signing key 'ta_private_key.pem'...
Debuglock token raw data:
6d6da3100ab5ad6d2b5ba1b62478652b6d000000000000003046022100d803b7633f74a019d7e3656f9d72a7ed7b4
fbb2c85b67bffd79e355560022100ed2b57569f2101f3a6006ea119bf1f53577e72b8374b31cce79a480be34de6b3
Debuglock token written to 'C:/Users/../../../debugtoken'.
Debug access will be unlocked after the device is reset.
DONE

    Note: This command will also accept a keys.json file when specifying the key used to sign the debug token.

  4. Reset the part to unlock the NWP JTAG port.

  5. Once the debugging session is complete, update the debug challenge nonce by locking the port as described in Locking Debug Access..

Moving to Production#

This section describes the steps recommended for moving to production. The main difference between development and production is that during development, the master boot record (MBR) is used to configure security settings so that they can be changed if needed and the JTAG ports are enabled. While in production, the eFuses (in OTP) are used to make the security settings immutable and the JTAG ports are locked.

  1. Read the eFuses from a factory new device.

    commander mfg917 read efuse --out efuse.json --device SIWG917M111MGTBA
    Reading data from region: efuse
Reading 1024 bytes from 0x40012000
Writing JSON...
Manufacturing data saved to file 'efuse.json'
DONE

  2. Before proceeding to this step, verify all other security settings are enabled. Note the required eFuses for debug locking as described in Table 3. As a final step in production, disable the JTAG ports by making the following changes to ‘efuse.json’ in a text editor.

    "mcu_chip_modes": {
        ...
        "disable_m4_jtag": 1,
        ...
    },
"wireless_chip_modes": {
        ...
        "**disable_ta_jtag": 1,
        ...
    }

  3. Save the file ‘efuse.json’.

  4. Write the new eFuse settings back to the target device as follows:

    commander mfg917 write efuse --data efuse.json -d SIWG917M111MBTGA
    Reading JSON...
The provided data can be applied to the current Efuse.
Determining which OTP words need updating...

================================================================================
THIS IS A ONE-TIME command which PERMANENTLY writes data to the Efuse region
of your device. This command CANNOT be undone.
Type 'continue' and hit enter to proceed or Ctrl-C to abort:
    continue
    Writing 16 bytes to OTP...
Loading RAM code (321776 bytes)...
Starting RAM code...
Efuse was successfully written to the device's OTP.
DONE

  5. Follow Steps 4-7 outlined in Locking Debug Access. to generate a nonce and lock each debug port.