1.0 Introduction

This document describes the One SDK design, including the development environment. One SDK is part of the "One" vision where the current GUIs, SDKs and EVMs across BMS are integrated into a common framework to promote cross-selling.

1.1 Stacked EVM

The "One" vision concept starts with a Stacked EVM that contains one motherboard and several daughter boards. The motherboard communicates to PC host over a USB connection, and can have zero or more daughterboards stacked on top of it through two 20-pin vertical bus connectors. Each daughterboard can support one or more BMS devices.

The motherboard USB is a J-Link port which is used for debugging firmware running on the motherboard RA MCU as well as for the serial communication based on J-Link RTT. The J-Link Remote Server allows host application (e.g., One GUI) to perform typical debug actions such as setting breakpoints, communicating to the target using RTT.

1.2 One GUI

The PC application is One GUI. It communicates with the motherboard and all the daughterboards present on the motherboard. In concept, One GUI has a main page that shows the system view, as well as individual pages providing register access of each detected devices. In system view icons of the motherboard and the daughterboards present on the motherboard are shown (see below figure). If any of the devices are selected, the registers window for that device will be brought into focus. Hovering over any of the signals or power bus lines will show the name of the named label. Any register value or system parameters can be shown in static or dynamic charts. One GUI also includes automatic testing and cell characterization features.

1.3 One SDK

One SDK forms the building blocks of MCU firmware for BMS devices, and is the main focus on this design document. It combines PDC Library and FG functionality such that the same firmware can support any combination of the following functions:

Type-C Port Manager (TCPM)
Fuel Gauge (FG)
Cell Characterization (CCHAR)
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 (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

1.3.1 One SDK Objectives

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 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.

1.3.2.1 Secure and Non-Secure project organization

Renesas e2studio/FSP simplified Trust Zone support by allowing a S project and its corresponding NS project to interoperate in the same workspace, such that when the compiled firmware is loaded into the MCU, S code/data are loaded into TZ protected memory, and NS code/data are loaded into NS memory.

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

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

Describe not only how the repository is laid out, but also what the customer distribution package would look like.>

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 device runs normally after POR. 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 allows 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 set the next wake state to STATE_FACTORY such that upon subsequent reset the execution will enter the factory bootloader.

Figure 2. Privilege states of MCU with TZ support.

The main benefit of Trust Zone is to enable OEM to customize firmware with Renesas IP pre-programmed into the device. For MCU without TZ support, such as Cortex M0+ and RL78, there will be no Factory state, and therefore the Factory State will be bypassed resulting in the below state transition diagram:

Figure 3. Privilege states of MCU without TZ support.

Note that, in this case, there is no 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 and deliver to customer only the executable binary.

3.4.1 Top-level pseudo code

Below shows the factory bootloader pseudo code which would run right after reset:

factory bootloader

void factory_bootloader()
{
   uint8_t cmd;
   uint8_t param[MAX_PARAM_SZ] = {0};

   gs_dev_state = gsf_dev_state;

   if (gs_dev_state == STATE_FACTORY)
   {
      flash_write(&gsf_dev_state, STATE_SEALED); 
      while (true)
      {
         bool rc = read_cmd(&cmd, param);
         if (rc == OK)
         { 
            if (cmd == CMD_RESET)
            {
               sys_reset();
            }
            else
            {
               rc = process_factory_cmd(cmd, param);
            }
         }
         print error(rc); 
      }
   }

   NS_entry();
}

Note that even if TZ is not supported factor_bootloader() can still be included, as the state upon reset would not be STATE_FACTORY and the execution will immediately jump to NS_entry() and run the application.

The NS_entry() is the non-secure entry function. Customer may optionally to implement customer bootloader() in NS_entry() or before the application code is called:

void NS_entry()
{
   application();
}


void application()
{
   // Initialize, setup ISR or threads
   application_setup();	

   
   // Comm loop 
   while (true)
   {
      uint8_t rc = read_cmd(&cmd, &param);
      if (rc == OK)
      {
         if (state == STATE_UNSEALED)
         {
            rc = process_unsealed_cmds(cmd, param);
         }
         else
         {
            if ((cmd == CMD_UNSEAL) && (0 == strcmp(param, customer_password))
            {
               state = STATE_UNSEALED;
            }
            else
            {
               rc = process_sealed_cmds(cmd, param);
            }
         }
      }
      print_error(rc);
   }
}

3.4.2 Updating firmware

Firmware update involves a host writing new code/data into secure and non-secure flash memories using the CMD_FLASH_WR command by parsing firmware in Intel HEX format or Motorola S-Record format generated from the build process. Then the host can set up the Trust Zone memory boundaries by writing to the the IDAU registers.

3.4.3 Generalized packet protocol

The bootloader communication shall be adaptable to any packet-based serial communication such as, UART, SMBus, SPI, TCP/IP socket, etc. The device driver shall convert selected serial communication into packets, and a generalized packet parser shall process the packets and execute valid commands.

5.0 Application stacks

5.1 Application stack interface

Thread
Stack
Trigger events
Priority

5.2 Fuel gauge (FG) application stack

Introduction
Pseudo code of FG application thread
Security
Communication
- SBS Data v1.1 support
- Additional data support
Algorithm API
AFE API

5.3 TCPM application stack

Introduction
Pseudo code of TCPM application stack
Security
Communication
Algorithm API
AFE API

5.4 Motherboard application stack

Introduction
Pseudo code of motherboard application stack
Security
Communication - RTT requires RA4E1 board modification
Algorithm API - include daughter card detection
AFE API - multi-daughter cards

2.0 Setup development environment

2.1 Install prerequisites

Install e2studio/FSP for RA
Install Python needed to support MCUBoot
Install Segger J-Link Software and Documentation

2.2 Introduction to Trust Zone

Secure after POR
Bootloader Set up S, NS and NSC memories
Describe S+NS side-by-side development model

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

Page tree

1.0 Introduction

1.1 Stacked EVM

1.2 One GUI