...
One SDK forms the building blocks of MCU firmware for BMS devices, and is the main focus on this design document. It One SDK combines PDC Library and FG functionality such functionalities so that the same firmware code base can support any combination of the following functions:
...
Type-C Port Manager (TCPM)
...
and Fuel Gauge (FG)
...
, as well as supporting the firmware for Cell Characterization (CCHAR)
...
and Motherboard Controller (MC)
...
. TCPM typically works with a Type-C Port Controller (TPCP) to support USB-PD power negotiation up to 48V@5A. FG typically works with an AFE (aka BMIC) to provide battery monitoring. In both cases, the MCU+AFE combination can be a chipset, or fully encased in the same IC (i.e., co-pack). Cell characterization Characterization (CCHAR) is a standalone daughtercard capable of cycling the battery cells over temperature. CCHAR sequence will be orchestrated by the One GUI, with the proxy firmware running on the motherboard MCU
...
The main objectives One SDK are: (1) protect and monetize Firmware IP; (2) faster time-to-market; and (3) reduce solution cost. One SDK protects Firmware IP such as FG algorithm and TCPM by leveraging hardware security such as ARM Trust Zone or by software security such as encryption. One SDK also supports faster time-to-market by combining FG and TCPM with other value-added firmware features, such as combining BMS features such as FG and TCPM with CAN and Bluetooth by pairing the firmware with ready-made Renesas MCUs that have the required hardware peripherals.
1.3.2
...
One SDK supports RL78, Cortex M0+, M23 and M33. RL78 is largely for supporting legacy BMS FGIC. Cortex M0+ is for 1S FGIC support. Cortex M23 is largely for high-cell count BMIC support. Cortex M33 is for high-cell count BMC/FGIC support and motherboard MCU support. One SDK supported MCU shall have catalog firmware pre-programmed in Flash. For M23 and M33 which has Trust Zone support, the IP shall be protected by Trust Zone. None-secured firmware can be overwritten to reclaim the Flash memory. Due to the lack of HW security, firmware for RL78 and M0+ have to be developed by Renesas to protect the firmware IP and limiting Flash data readout. Below shows stated policy. The scenarios enclosed by dotted red lines are considered "sticky", i.e., customer developing fond dependence on due to attractive features, ease of use, or value gain.
2.0 One SDK Architecture
2.1 Overview
One SDK model consists of four layers plus a RTOS:
Hardware layer: the physical hardware where applications built with One SDK runs. The hardware can include MCU and external devices such as BMIC, TCPC, SPI Flash, Battery Chargers. etc.
Driver layer (HAL): a collection of device drivers callable by the upper layer code to interact with the hardware. Usually, each module in the driver layer is associated with a specific hardware component, e.g., UART, I2C, SPI, Flash, etc. The driver layer is usually hardware specific. For example, different MCU may require a different driver layer. However, since different MCU often share the same peripheral blocks, the driver modules may be common between the MCUs.
Middleware layer: a collection of processing modules that serve as the building blocks for constructing applications. Each middleware module can be associated with a specific driver module, as in the case of protocol stacks, or associated with specific data-in, data-out functions or algorithms, such as FFT, or state-of-charge computation. One can think of the middleware layer as a collection of building blocks to be sequenced by the application layer to create the application executables.
Application layer: a collection of loops/threads/interrupt handlers that form the top-level application logic. If threads are used, then RTOS would be required to facilitate scheduling, thread synchronization and inter-process communication.
Figure 1 - One SDK high-level architecture.
Application stacks: each application stack is a collection of application threads and middleware modules that implements a specific application. In One SDK each application stack is standalone and can be included or excluded at build time. For instance, if a MCU has only TCPM application stack, then the MCU would be a TCPM controller; but if it also has a FG application stack running then the MCU becomes a battery fuel gauge. If both application stacks are included, then the MCU becomes a multi-function ASSP capable of functioning both as TCPM and battery fuel gauge, subject to MCU bandwidth limitation, available peripherals and memory capacity.
2.2 Repository file structure
<One SDK follows RA e2studio/FSP project file structure, but also have extra folders for scripts, tools and docs.>
Describe not only how the repository is laid out, but also what the customer distribution package would look like.>
...
Trust Zone (TZ)
One SDK leverages ARM Trust Zone for firmware IP protection. Trust Zone is a hardware-enforced code and data memory protection mechanism. In a TZ enabled MCU, memory and peripherals are divided into two worlds: Secure (S) and Non-Secure (NS). After power-on-reset (POR), TZ-enabled MCU always enters the S world, typically running a bootloader or a startup code that sets up the boundaries of S and NS memories, with the protected IP stored in S memory, which can execute, but not read or written to as data. NS code can call S code and vise versa through special vector tables located in Non-Secure Callable (NSC) memory.
Renesas e2studio/FSP simplifies Trust Zone implementation by having S project and NS project co-exist and interoperate in the same workspace, such that when the compiled firmware is loaded into the MCU, S code/data are loaded into the TZ-protected memory, and NS code/data are loaded into NS memory. For every new NPI device requiring firmware, the BMS Firmware team will develop a complete catalog solution comprised of both S parts and NS parts.
If the MCU paired with the device supports TZ, then the BMS Firmware team will put the S parts in the S project, and the NS parts in the NS project. The combined catalog firmware pre-programed in the device during production. Instead of distributing both S project and NS projects, BMS Firmware team shall only distribute the Secure Bundle to customers and BMS apps team. The Secure Bundle comprises of NS source code plus the .sbd file containing linking information so that NS code can link to the S code without having the S source code.
1.3.3 Catalog device and custom firmware
With the Secure Bundle, both customers and BMS apps team can customize a catalog device and overwriting the NS memory footprint of catalog firmware with the custom firmware. The concept is illustrated in the figure below. In this process only the catalog device need to be inventoried, as long as the custom firmware depends on the same Renesas MCU hardware and "Secret Sauce".
1.3.4 NS code calling S code
When e2studio/FSP is used, the S project and NS project reside in the same workspace and are linked to one another. e2studio can generate NSC veneer.
Access to NSC drivers from a Non-secure project is possible through the Guard APIs. The FSP automatically generates guard functions for all the top-of-stack/driver APIs configured in the Secure project as Non-secure Callable. Example below:
1.3.5 Creating user-defined NSC functions
One can create a customized NSC API in the Secure project to expose only the top-level control of your algorithms and store the IP in the Secure Arm® Trust Zone® region. Precautions mentioned previously should be exercised during the creation of the user-defined NSC API.
The steps to create a customized NSC API are:
- Create the Non-secure Callable custom function by declaring the function with BSP_CMSE_NONSECURE_ENTRY.
- Create a header file that includes all the customized NSC function prototypes, for example, my_nsc_api.h.
- Include the path to the NSC header using the Build Variable as shown in below figure.
- Compile the Secure project to create the Secure Bundle. The NSC header will be automatically extracted for use in the Non-secure project.
1.3.5 S code calling NS code
If FreeRTOS is selected and there is access to NSC functions from a Thread in the Non-secure project, it is necessary to enable Allocate secure context for this thread in the configurator for that Thread.
1.3.6 USB debug interface setup
There are some prerequisites prior to setting up the MCU IDAU regions. From the factory, RA MCUs are delivered to the developer in the CM (Chip Manufacturing) lifecycle state. The MCU must be transitioned to SSD (Secure Software Development) lifecycle state prior to setting up the IDAU regions. Transitioning from CM State to SSD State and setting up the IDAU region can only be achieved using the MCU’s boot mode, which can only be accessed using an SCI/USB connection. To benefit from the tools' support, developers need to bring the MCU Mode pin (MD) and SCI pins to the Debug interface. Special debugger firmware has been developed to manage to bring the device up in SCI boot mode to set up the IDAU registers (automatically drives MD pin) and then switch back to debug mode as needed.
<Verify that FSP-RA4E1 has the same>
When developing with e2studio and using Renesas evaluation kits for Trust Zone MCUs, the MCU is automatically transitioned from the CM state to the SSD state when the first secure program is downloaded to the MCU if the above required connection is provided.
1.3.6 Configure IDAU using e2studio
Renesas Device Partition Manager (RDPM) can be used to setup the IDAU regions.
When using e2 studio, the necessary values to set up the Trust Zone® memory partition (IDAU registers) are calculated after the binary code to program into the Secure region is created by building the Secure project. The regions are set up to ensure that they match the code and data sizes and keep the attack surface as small as possible. If the hardware connection mentioned above is provided in the PCB design, there is no need to use the RDPM manually to set up the IDAU region. Setting up the IDAU region when developing with e2 studio is a transparent process for most applications.
2.3 Create your first "Blinky" project
- S and NS co-reside in the same workspace
- Create Secure Project (S) - add Bootloader to set up S, NS and NSC memory map
- Show where S calls into NS code
- Create Non-secure Project (NS) - add FreeRTOS
- Build and Run
- Show the S to NS code flow to end up blinking LEDs
- Show where to find the *.sbd file
1.3.3 One SDK supported MCUs
One SDK supports RL78, Cortex M0+, M23 and M33. RL78 is largely for supporting legacy BMS FGIC. Cortex M0+ is for 1S FGIC support. Cortex M23 is largely for high-cell count BMIC support. Cortex M33 is for high-cell count BMC/FGIC support and motherboard MCU support. One SDK supported MCU shall have catalog firmware pre-programmed in Flash. For M23 and M33 which has Trust Zone support, the IP shall be protected by Trust Zone. None-secured firmware can be overwritten to reclaim the Flash memory. Due to the lack of HW security, firmware for RL78 and M0+ have to be developed by Renesas to protect the firmware IP and limiting Flash data readout. Below shows stated policy. The scenarios enclosed by dotted red lines are considered "sticky", i.e., customer developing fond dependence on due to attractive features, ease of use, or value gain.
2.0 One SDK Architecture
2.1 Overview
One SDK model consists of four layers plus a RTOS:
Hardware layer: the physical hardware where applications built with One SDK runs. The hardware can include MCU and external devices such as BMIC, TCPC, SPI Flash, Battery Chargers. etc.
Driver layer (HAL): a collection of device drivers callable by the upper layer code to interact with the hardware. Usually, each module in the driver layer is associated with a specific hardware component, e.g., UART, I2C, SPI, Flash, etc. The driver layer is usually hardware specific. For example, different MCU may require a different driver layer. However, since different MCU often share the same peripheral blocks, the driver modules may be common between the MCUs.
Middleware layer: a collection of processing modules that serve as the building blocks for constructing applications. Each middleware module can be associated with a specific driver module, as in the case of protocol stacks, or associated with specific data-in, data-out functions or algorithms, such as FFT, or state-of-charge computation. One can think of the middleware layer as a collection of building blocks to be sequenced by the application layer to create the application executables.
Application layer: a collection of loops/threads/interrupt handlers that form the top-level application logic. If threads are used, then RTOS would be required to facilitate scheduling, thread synchronization and inter-process communication.
Figure 1 - One SDK high-level architecture.
Application stacks: each application stack is a collection of application threads and middleware modules that implements a specific application. In One SDK each application stack is standalone and can be included or excluded at build time. For instance, if a MCU has only TCPM application stack, then the MCU would be a TCPM controller; but if it also has a FG application stack running then the MCU becomes a battery fuel gauge. If both application stacks are included, then the MCU becomes a multi-function ASSP capable of functioning both as TCPM and battery fuel gauge, subject to MCU bandwidth limitation, available peripherals and memory capacity.
2.2 Repository file structure
<One SDK follows RA e2studio/FSP project file structure, but also have extra folders for scripts, tools and docs.>
Describe not only how the repository is laid out, but also what the customer distribution package would look like.>
| Code Block | ||||
|---|---|---|---|---|
| ||||
Project_Root
+---.settings
+---ra
| +---arm
| | +---CMSIS_6
| +---aws
| +---board
| +---fsp
+---ra_cfg
| +---fsp_cfg
| +---bsp
| | +---board_cfg.h
| | +---bsp_cfg.h
| | +---bsp_mcu_device_cfg.h
| | +---bsp_mcu_device_pn_cfg.h
| | +---bsp_mcu_family_cfg.h
| | +---bsp_pin_cfg.h
| +---r_ioport_cfg.h
| +---rm_tz_context_cfg.h
+---ra_gen
| +---bsp_block_cfg.h
| +---common_data.c
| +---common_data.h
| +---hal_data.c
| +---hal_data.h
| +---main.c
| +---pin_data.c
| +---vector_data.c
| +---vector_data.h
+---script
| +---fsp.ld
+---src
| +---hal_entry.c
+---.api_xml
+---.clangd
+---.cproject
+---.project
+---.secure_azone
+---.secure_xml
+---configuration.xml
+---NS Debug_SSD.jlink
+---NS Debug_SSD.launch
|
2.3 Roles
One SDK envisions three different roles with successively greater privileges: users, OEM and factory. Factory role is held solely by Renesas; OEM is usually the role of Renesas customers or ODM who purchase the devices containing the firmware; user role is assigned to consumers using the device containing firmware created using One SDK.
2.4 Privilege states
One SDK supports MCU with Trust Zone support or without. For MCU with TZ, three privilege states are supported:
- Factory – Intended for Renesas only. After reset, MCU will always run the factory bootloader in secure (S) mode. The factory bootloader first checks S mode NV memory for the wake state set by previous wake--if the wake state is set to STATE_FACTORY, execution will enter the factory bootloader command loop; else the factory bootloader will set the state to Sealed and call the NS mode entry point.
- Sealed –Intended for user. Sealed state is where the NS application device runs normally after resetPOR. In this state, only a basic set of commands required for the intended application are available. Users may enter the Unsealed state (STATE_UNSEALED) by issuing the CMD_UNSEAL command along with the correct customer password.
- Unsealed – Intended for OEM. Unsealed state (STATE_UNSEALED) is only entered from Sealed state. Like Sealed state, Unsealed state also runs in NS mode, but it supports additional commandsallows OEM to add more commands that are accessible by OEM only. One of the command is CMD_FACTORY, which when issued with the correct Renesas password, will setup set the next wake state to STATE_FACTORY , such that upon subsequent wake from reset the execution path will enter the factory bootloader command loop.
Figure 2. Privilege states of MCU with TZ support.
The main benefit of having a TZ Trust Zone is to enable OEM /ODM to customize the device firmware with Renesas "secret sauce" IP pre-programmed into the device. For MCU without TZ support, such as CM0Cortex M0+ and RL78, there will be no Factory state, and therefore the Factory State will be bypassed resulting in the below state transition diagram:
...
Note that, in this case, there is no TZ support, therefore "secret sauce" code/data hiding is not possible. Trust Zone support and firmware protection "at rest" is unavailable. Therefore, firmware can only be protected by guarding external communication–which means Renesas must be the one doing the firmware customization and deliver to customer only the executable binary.
...
Firmware update involves a host writing new code/data into secure and non-secure flash memories using the CMD_FLASH_WR command by parsing the firmware in Intel HEX file format or Motorola S-Record file format generated from the firmware build process. Then the host can setup set up the Trust Zone memory boundaries by writing to the the IDAU registers.
...
- Describe Secure Bundle distribution model
- How to place "secret sauce" in secure memory
- How to call S code from NS code
- How to call NS code from S code
2.3 Create your first "Blinky" project
- S and NS co-reside in the same workspace
- Create Secure Project (S) - add Bootloader to set up S, NS and NSC memory map
- Show where S calls into NS code
- Create Non-secure Project (NS) - add FreeRTOS
- Build and Run
- Show the S to NS code flow to end up blinking LEDs
- Show where to find the *.sbd file
...
- RA Flexible Software Package Users Manual
- Security Design with ARM Trust Zone using Cortex M33
- Renesas Device Life Cycle Management Key Injection
- Renesas Device Life Cycle Management for Cortex M33
- RA4E1 device data sheet
- Segger J-Link RTT
- J-Link Telnet Interface
- J-Link SDK
...