Arm® TrustZone® Technology Getting Started Application on PIC32CK SG01 (Cortex®-M33) MCUs

Objective

This tutorial shows you how to create an Arm^® TrustZone^® technology feature application on a PIC32CK SG01 microcontroller (MCU) using MPLAB^® Harmony v3 software framework.

The PIC32CK SG01 MCU is the implementation of the Arm^® TrustZone^® for Armv8-M devices. TrustZone technology for an Armv8-M device is based on specific hardware that is implemented in the Arm Cortex^®-M33 core, which is combined with a dedicated Secure instructions set. It allows the creation of multiple software security domains that restrict access to selected memory, peripherals, and I/O to trusted software without compromising the system's performance. The TrustZone technology enables secure and non-secure code to run on a single MCU.

MPLAB Harmony v3 is a flexible, fully integrated embedded software development framework for 32-bit microcontrollers (MCUs) and microprocessors (MPUs). MPLAB Code Configurator (MCC) includes the MPLAB Harmony v3 Framework, a set of modular Peripheral Libraries (PLIBs), drivers, system services, middleware, and numerous example applications, all of which are designed to help you quickly and easily develop powerful and efficient embedded software for Microchip’s 32-bit PIC^® and SAM devices. Also, MPLAB Harmony v3 provides a TrustZone technology environment to develop security applications on different secured MCUs and MPUs like PIC32CK SG01, PIC32CM LS60, SAM L11, SAM A5D2, and SAM A5D4.

The application makes use of the PIC32CK SG01 Curiosity Ultra Development Board and the I/O1 Xplained Pro Extension Kit (sold separately).

The application includes Basic and Extended functionalities.

Basic application:

• The Secure mode application toggles an LED (LED0 toggles when the switch SW0 is pressed) on a timeout basis and the periodicity of the timeout will change from 500 milliseconds to one second, two seconds, four seconds, and back to 500 milliseconds every time you press the switch SW0 on the PIC32CK SG01 Curiosity Ultra Development Board.
• The Non-secure application requests the Secure mode application, reads the LED toggling rate, and prints on the serial terminal. The LED toggling rate data is transferred to the Non-secure mode application when it requests to Secure application through Non-Secure Callables (NSC).

Extended application:

• The Secure mode application reads the current room temperature from the temperature sensor on the I/O1 Xplained Pro Extension Kit every 500 milliseconds. Further, the application writes the temperature readings to EEPROM and reads when a request is received from the Non-secure mode application. Also, a green LED (LED0) is toggled every time the temperature display request is received from the Non-secure mode application. The periodicity of the temperature values reading can be changed to 1 second, 2 seconds, 4 seconds, and back to 500 milliseconds whenever the user presses the switch SW0 on the PIC32CK SG01 Curiosity Ultra Development Board. The temperature readings are transferred to the Non-secure mode application when it requests to Secure the application through Non-Secure Callables (NSC).
• The Non-secure mode application requests the Secure mode application the temperature values and prints them on a serial console once it receives from the Secure mode application. Further, when it gets a request from the user (in the form of a key press on the serial console), it will request the Secure mode application to retrieve the last five stored temperature values in the EEPROM. The Non-secure application prints the last five stored temperature values on the console. Also, a red LED (LED1) is toggled every time the temperature values are read from EEPROM.

The application has two projects on Secure and Non-secure modes of PIC32CK SG01, that work together on the same MCU and offer security isolation between the trusted and the non-trusted resources of the device.

The Secure mode application reads the current room temperature from the temperature sensor on the I/O1 Xplained Pro Extension Kit every 500 milliseconds. Additionally, the secure application writes the temperature readings to EEPROM and reads when a request is received from the Non-secure mode application. Also, an LED (LED0) is toggled every time the temperature is displayed on the serial console. The periodicity of the temperature values reading can be changed to 1 second, 2 seconds, 4 seconds, and back to 500 milliseconds every time the user presses the switch SW0 on the PIC32CK SG01 Curiosity Ultra Development Board. The temperature readings are transferred to a Non-secure mode application when it requests to secure application through Non-Secure Callables (NSC). By default LED toggling rate is displayed on the terminal, by pressing the switch SW1, the temperature sampling rate is displayed. Switch SW1 press interrupt to toggle from Basic Functionality to Extended Functionality and vice-versa.

The Non-secure mode application requests the Secure mode application to get the current temperature values and the Non-secure mode application prints them on a serial console. Further, when it receives a request from the user (in the form of a key press on the serial console), it requests a Secure mode application to retrieve the last five stored temperature values in the EEPROM. The Non-secure application prints the last five stored temperature values on the console.

The application you create will utilize:

• Secure PORT Pin to toggle the LED (By default, all PORT pins are secure)
• Secure SERCOM (configured as I²C) PLIB to read the temperature from a temperature sensor
• Secure Real-Time Clock (RTC) PLIB to periodically sample temperature sensor data
• Mix-Secure peripheral External Interrupt Controller (EIC) PLIB to change the periodicity of temperature sensor data read using switch SW0 press interrupt and switch SW1 press interrupt to toggle from Basic Functionality to Extended Functionality and vice-versa.
• Non-secure SERCOM (configured as Universal Synchronous Asynchronous Receiver Transmitter (USART)) and Non-secure Direct Memory Access (DMA) PLIBs to print the temperature values on a COM (serial) port terminal application running on a PC
• Non-secure PORT Pins (USART Pins only) to communicate with the serial terminal

In the process, the lab will also demonstrate the use of callback functions.

Two Ways to Use This Tutorial

1. Create the project from scratch:
   • Use the provided source files and step-by-step instructions.
2. Use the solution project as an example:
   • Build the solution project and program it to the PIC32CK SG01 Curiosity Ultra Development Board to observe the expected behavior.

Lab Objectives

1. Create an MPLAB Harmony v3 TrustZone technology project for a PIC32CK SG01 microcontroller from scratch in MPLAB X IDE.
2. Use MCC to configure and generate MPLAB Harmony v3 PLIBs code for the following peripherals in Secure mode:
   • RTC
   • I²C
   • EIC and
   • PORT pin to toggle LED.
3. Use MCC to configure and generate MPLAB Harmony v3 PLIBs code for the following peripherals in Non-Secure mode:
   • USART
   • DMA
   • PORT pins for USART.
4. Use the MPLAB Harmony v3 PLIB Application Programming Interfaces (APIs) to implement secure and non-secure applications.

Back to Top

Reference Materials

• PIC32CK SG Curiosity Ultra Development Board
• I/O1 Xplained Pro Extension Kit 
• MPLAB^® X Integrated Development Environment (IDE)
• MPLAB XC32 Compiler

Apart from the hardware tools listed above, the following items are required:

• USB Type-A male to micro-B male cable for programming and debugging. 

You will use the MPLAB X IDE MCC Content Manager for MPLAB Harmony Projects to download the following repositories from GitHub:

• CSP: The following table shows the summary of contents.

Connection Diagram

The application has the temperature sensor and EEPROM connected to the PIC32CK SG01 over the I²C interface and the console (serial terminal) on a PC connected over the USART interface (through USB to USART converter).

Back to Top

Overview

This lab shows you how to create an MPLAB Harmony v3 project from scratch, to configure and generate:

• MPLAB Harmony v3 Peripheral Libraries code for the secure RTC and I²C peripherals
• MPLAB Harmony v3 Peripheral Libraries code for the Mix-Secure EIC and PORTS peripherals. (All PORT pins by default are secure and can be configured as Non-secure or Secure by the User)
• MPLAB Harmony v3 Peripheral Libraries code for the non-secure USART, and DMA peripherals (USART Pins only)

The application has two projects on Secure and Non-secure modes of PIC32CK SG01, that work together on the same MCU and offers security isolation between the trusted and the non-trusted resources in the device.

Secure Application

The Secure mode application reads the current room temperature from the temperature sensor on the I/O1 Xplained Pro Extension Kit every 500 milliseconds. The application writes the temperature readings to EEPROM and reads when a request is received from the Non-secure mode application. Also, an LED (LED0) is toggled every time the temperature is displayed on the serial console. The periodicity of the temperature values reading can be changed to 1 second, 2 seconds, 4 seconds, and back to 500 milliseconds whenever the user presses the switch SW0 on the PIC32CK SG01 Curiosity Ultra Development Board. The temperature readings are transferred to Non-secure mode application when it requests to secure application through Non-Secure Callables (NSC).

The secure application initializes Clock, PORT, and secure peripherals (configured through MCC) and its NVIC initializations by calling the function SYS_Initialize. The application registers callback event handlers for SERCOM (as I²C), RTC, and EIC PLIBs. The callback event handlers are called back by the PLIBs when the transaction completion events occur.​

The application checks whether the configured RTC timer period has expired. On every timer period expiration, the application calls the function SERCOM4_I2C_WriteRead to submit a temperature sensor read request to the I²C PLIB when I²C peripheral is free. The I²C PLIB calls back the registered callback event handler when the latest temperature value is read from the sensor. The application frees the I²C PLIB and sets a temperature read complete flag in the I²C callback event handler if the I²C PLIB request is a temperature sensor read request.

The application checks the temperature read complete flag and it also checks the I²C PLIB is free to submit a written request to store the values in the EEPROM. Further, it will load the latest temperature value (in a formatted message) onto the buffer and also toggles user LED0. When the latest temperature value is written to the EEPROM, the I²C PLIB calls back the registered callback event handler. The application frees the I²C PLIB.

Further, the application checks if the EEPROM read request is received from a non-secure application to read the last five stored temperature values in the EEPROM. The application calls the function SERCOM4_I2C_WriteRead to submit a read request to the I²C PLIB to read the last five stored temperature values in the EEPROM when I²C peripheral is free. The I²C PLIB calls back the registered callback event handler when the latest temperature value is read from the sensor. The application frees the I²C PLIB and sets an EEPROM read status complete flag in the I²C callback event handler if the I²C PLIB request is an EEPROM read request. Notice the toggle of LED1 after printing the temperature values read from EEPROM.

The application also monitors the pressing of the switch SW0; if the switch SW0 press is detected, the application changes the temperature sampling rate from the default 500 milliseconds to 1 second. On subsequent switch SW0 press, the application changes the temperature sampling rate to two seconds, four seconds, and back to 500 milliseconds. The application cycles the temperature sampling rate on every switch press, as shown below.

Back to Top

Non-Secure Application

The Non-secure mode application requests the Secure mode application temperature values and prints them on a serial console once it receives from the Secure mode application. Further, when it receives a request from the user (in the form of a key press on the serial console), it will request that the Secure mode application retrieve the last five stored temperature values in the EEPROM. The non-secure application prints the last five stored temperature values on the console. 

The application initializes non-secure peripherals (configured through MCC) and its NVIC initializations by calling the function SYS_Initialize. The application registers callback event handlers for two DMA channels (SERCOM (configured as USART) transmit and receive channels). The callback event handlers are called back by the PLIBs when the transaction completion events occur.

The application request and checks whether the temperature reading completion status set by the Secure mode application to print the latest received temperature value (in a formatted message) onto the serial console over the USART interface by submitting a written request to DMA.

Further, the application reads a user input is received as a character from the serial terminal on the PC to read the stored (last five) temperature values by requesting to secure application.

The application prints the temperature values on the serial terminal once the EEPROM data reads the completion status set by the Secure mode application.

Back to Top

Lab Source Files and Solutions

• Project File Download 

This ZIP file contains the completed solution project for this lab. It also contains the source files needed to perform the lab as per the following step-by-step instructions (see the "Procedure" section on this page).

​The contents of this ZIP file need to be placed in a folder of your choice.

1. The project location of an MPLAB Harmony v3 project is independent of the location of the MPLAB Harmony Framework path (i.e., you don't need to create or place an MPLAB Harmony v3 project in a relative path under the MPLAB Harmony v3 framework folder).

     2. The point above is true because when created, a Harmony v3 project generates all the referred source and header files and libraries (if any) under the Project folder.

Back to Top

Extracting the ZIP file creates the following folders:

• getting_started_tz_pic32ck_sg01_cult contains the lab solution and source files (in the dev_files folder).
  • The dev_files folder contains the subfolders Secure and NonSecure which contains the application source files and other support files (if any) required to perform the lab (see "Procedure" section).
  • The Project folder contains the completed lab solution project which consists of firmware and firmware_secure. It can be directly built and programmed on the hardware to observe expected behavior.

Back to Top

Procedure

​Note: All steps must be completed before you can build, download, and run the application.

Lab Index

Step 1: Create a PIC32CK SG01 Secure and Non-secure Group Project

• Step 1.1 - Create MPLAB® Harmony v3 TrustZone Project Using MPLAB X IDE
• Step 1.2 - Verify Clock Settings
• Step 1.3 - Configure Secure and NonSecure Peripherals
• Step 1.4 - Verify Secure and Non-secure Memory Regions

Step 2: Configure I²C, USART, and RTC Peripheral Libraries

• Step 2.1 - Configure Secure RTC Peripheral Library
• Step 2.2 - Configure Secure I²C Peripheral Library and Secure I²C Pins
• Step 2.3 - Configure Non-Secure USART Peripheral Library and Non-Secure USART Pins
• Step 2.4 - Configure Non-Secure DMA Peripheral Library

Step 3: Configure Pins for Switch and LED

• Step 3.1 - Configure Switch Button Pin with Secure EIC to Generate an Interrupt
• Step 3.2 - Configure LED Pin in Secure Mode
• Step 3.3 - Rename the Default main File

Step 4: Generate Code
Step 5: Add Secure Application Code to the Project
Step 6: Add Non-secure Application Code to the Project
Step 7: Build, Program, and Observe the Outputs

Back to Top