Skip to content
This repository was archived by the owner on May 7, 2025. It is now read-only.

Commit a657e79

Browse files
author
Cesare Garlati
authored
Update README.md
1 parent 7cfbc8c commit a657e79

File tree

1 file changed

+109
-49
lines changed

1 file changed

+109
-49
lines changed

‎README.md‎

Lines changed: 109 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -3,26 +3,24 @@ MultiZone® Security TEE for RISC-V processors
33

44
**MultiZone® Security** is the quick and safe way to add security and separation to RISC-V processors. MultiZone software can retrofit existing designs. If you don’t have TrustZone-like hardware, or if you require finer granularity than one secure world, you can take advantage of high security separation without the need for hardware and software redesign, eliminating the complexity associated with managing a hybrid hardware/software security scheme. RISC-V standard ISA doesn't define TrustZone-like primitives to provide hardware separation. To shield critical functionality from untrusted third-party components, MultiZone provides hardware-enforced, software-defined separation of multiple equally secure worlds. Unlike antiquated hypervisor-like solutions, MultiZone is self-contained, presents an extremely small attack surface, and it is policy driven, meaning that no coding is required – and in fact even allowed.
55

6-
MultiZone works with any 32-bit or 64-bit RISC-V standard processors with Physical Memory Protection unit and U mode.
6+
MultiZone works with any 32-bit or 64-bit RISC-V processors with standard Physical Memory Protection unit (PMP) and “U” mode.
77

8-
This version of the GNU-based SDK supports the following hardware:
9-
- [Digilent Arty A7 Development Board (Xilinx Artix-7 FPGA)](https://www.xilinx.com/products/boards-and-kits/arty.html)
10-
- [SiFive HiFive1 Rev B (Freedom E310 SoC)](https://www.sifive.com/boards/hifive1-rev-b)
8+
This release of the MultiZone SDK supports the following development boards:
9+
- [Digilent Arty A7 Development Board (Xilinx Artix-7 FPGA)](https://digilent.com/shop/arty-a7-artix-7-fpga-development-board/)
10+
- [Andes Corvette-F1 R1.0 (Xilinx Artix-7 FPGA)](http://www.andestech.com/en/products-solutions/andeshape-platforms/corvette-f1-r1/)
1111
- [Microchip Icicle Kit (PolarFire SoC)](https://www.microsemi.com/existing-parts/parts/152514)
12+
- [SiFive HiFive1 Rev B (Freedom E310 SoC)](https://www.sifive.com/boards/hifive1-rev-b)
13+
- [SiFive Unleashed (Freedom U540 SoC)](https://www.sifive.com/boards/hifive-unleashed)
1214

13-
Note: Microchip Icicle Kit see [https://github.com/hex-five/multizone-sdk-pfsc](https://github.com/hex-five/multizone-sdk-pfsc)
14-
15-
The Arty FPGA Evaluation Kit works with the following softcore bitstreams:
16-
17-
- [Hex Five X300 RV32ACIMU - Permissive open source. No license required.](https://github.com/hex-five/multizone-fpga)
18-
- [SiFive E31 RV32ACIMU - Proprietary. SiFive license required.](https://www.sifive.com/cores/e31)
19-
- [SiFive S51 RV64ACIMU - Proprietary. SiFive license required.](https://www.sifive.com/cores/s51)
15+
This repository is for the Digilent Arty A7 and the SiFive HiFive1 Rev B boards.
2016

21-
The Xilinx Arty FPGA comes in two versions: 35T and 100T
17+
The Digilent Arty A7 FPGA is certified for the following bitstreams:
18+
- ARTY 35T: [Hex Five X300](https://github.com/hex-five/multizone-fpga) v1.0.1 RV32ACIMU – Open source. No license required.
19+
- ARTY 100T: [SiFive E21](https://www.sifive.com/cores/e21) 20G1.05.00 RV32ACIMU – SiFive evaluation license required.
20+
- ARTY 100T: [SiFive E31](https://www.sifive.com/cores/e31) 20G1.05.00 RV32ACIMU – SiFive evaluation license required.
21+
- ARTY 100T: [SiFive S51](https://www.sifive.com/cores/e51) 20G1.05.00 RV64ACIMU – SiFive evaluation license required.
2222

23-
- Hex Five's X300 bitstream works with version 35T
24-
- SiFive's bitstreams up to v19.02 work with version 35T
25-
- SiFive's bitstreams after v19.02 work with version 100T
23+
Note: The Digilent Arty A7 FPGA is available in two versions: 35T and 100T. The Hex Five X300 bitstream works with the smaller 35T. The SiFive bitstreams require the larger 100T.
2624

2725
For instructions on how to upload the bitstream to the ARTY board and how to connect the [Olimex debug head ARM-USB-TINY-H](https://www.olimex.com/Products/ARM/JTAG/ARM-USB-TINY-H/) see [Arty FPGA Dev Kit Getting Started Guide](https://sifive.cdn.prismic.io/sifive%2Fed96de35-065f-474c-a432-9f6a364af9c8_sifive-e310-arty-gettingstarted-v1.0.6.pdf)
2826

@@ -38,7 +36,6 @@ sudo apt update
3836
sudo apt install make default-jre gtkterm libhidapi-dev libftdi1-2
3937
```
4038
Ubuntu 18.04 LTS additional dependency
41-
4239
```
4340
sudo add-apt-repository "deb http://archive.ubuntu.com/ubuntu/ focal main universe"
4441
sudo apt update
@@ -48,20 +45,20 @@ Note: GtkTerm is optional and required only to connect to the reference applicat
4845

4946
**GNU RISC-V Toolchain**
5047

51-
Hex Five reference build: RISC-V GNU Toolchain Linux 64-bit June 13, 2020
48+
Hex Five reference build: RISC-V GNU Toolchain Linux 64-bit August 07, 2021
5249
```
5350
cd ~
54-
wget https://hex-five.com/wp-content/uploads/riscv-gnu-toolchain-20200613.tar.xz
55-
tar -xvf riscv-gnu-toolchain-20200613.tar.xz
51+
wget https://hex-five.com/wp-content/uploads/riscv-gnu-toolchain-20210807.tar.gz
52+
tar -xvf riscv-gnu-toolchain-20210807.tar.gz
5653
```
5754

5855
**OpenOCD on-chip debugger**
5956

60-
Hex Five reference build: RISC-V openocd Linux 64-bit June 13, 2020
57+
Hex Five reference build: RISC-V OpenOCD Linux 64-bit August 07, 2021
6158
```
6259
cd ~
63-
wget https://hex-five.com/wp-content/uploads/riscv-openocd-20200613.tar.xz
64-
tar -xvf riscv-openocd-20200613.tar.xz
60+
wget https://hex-five.com/wp-content/uploads/riscv-openocd-20210807.tar.gz
61+
tar -xvf riscv-openocd-20210807.tar.gz
6562
```
6663
Note: the SiFive HiFive1 board doesn't support OpenOCD and requires the Segger propietary package JLink_Linux_V694_x86_64.deb downloadable at [https://www.segger.com/downloads/jlink/](https://www.segger.com/downloads/jlink/).
6764

@@ -74,36 +71,40 @@ sudo vi /etc/udev/rules.d/99-openocd.rules
7471
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403",ATTRS{idProduct}=="6010", MODE="664", GROUP="plugdev"
7572
SUBSYSTEM=="usb", ATTR{idVendor} =="0403",ATTR{idProduct} =="6010", MODE="664", GROUP="plugdev"
7673
74+
# Future Technology Devices International, Ltd FT232 USB-Serial (UART) IC
75+
SUBSYSTEM=="tty", ATTRS{idVendor}=="0403",ATTRS{idProduct}=="6001", MODE="664", GROUP="plugdev"
76+
SUBSYSTEM=="usb", ATTR{idVendor} =="0403",ATTR{idProduct} =="6001", MODE="664", GROUP="plugdev"
77+
7778
# Olimex Ltd. ARM-USB-TINY-H JTAG interface
7879
SUBSYSTEM=="tty", ATTRS{idVendor}=="15ba",ATTRS{idProduct}=="002a", MODE="664", GROUP="plugdev"
7980
SUBSYSTEM=="usb", ATTR{idVendor} =="15ba",ATTR{idProduct} =="002a", MODE="664", GROUP="plugdev"
8081
8182
# SiFive HiFive1 Rev B00 - SEGGER
82-
SUBSYSTEM=="tty", ATTRS{idVendor}=="1366",ATTRS{idProduct}=="1051", MODE="664", GROUP="plugdev"
83+
SUBSYSTEM=="tty", ATTRS{idVendor}=="1366",ATTRS{idProduct}=="1051", MODE="664", GROUP="plugdev
8384
```
84-
Reboot for these changes to take effect.
85+
A reboot may be necessary for these changes to take effect.
8586

8687
**MultiZone Security SDK**
8788

8889
```
8990
cd ~
90-
wget https://github.com/hex-five/multizone-sdk/archive/master.zip
91-
unzip master.zip
92-
mv multizone-sdk-master multizone-sdk
91+
git clone https://github.com/hex-five/multizone-sdk.git
92+
9393
```
9494

95+
9596
### Build & load the MultiZone reference application ###
9697

9798
Connect the target board to the development workstation as indicated in the user manual.
9899

99100
'ls multizone-sdk/bsp' shows the list of supported targets: X300, FE310, E31, S51, PFSOC.
100101

101-
Assign one of these values to the BOARD variable - default is X300.
102+
Assign one of these values to the BOARD variable - default target is X300.
102103

103104
```
104105
cd ~/multizone-sdk
105-
export RISCV=~/riscv-gnu-toolchain-20200613
106-
export OPENOCD=~/riscv-openocd-20200613
106+
export RISCV=~/riscv-gnu-toolchain-20210807
107+
export OPENOCD=~/riscv-openocd-20210807
107108
export BOARD=X300
108109
make
109110
make load
@@ -115,7 +116,6 @@ Important: make sure that switch SW3 is positioned close to the edge of the boar
115116
Important: open jumper JP2 (CK RST) to prevent a system reset upon UART connection.
116117

117118

118-
119119
### Run the MultiZone reference application ###
120120

121121
Connect the UART port (ARTY micro USB J10) as indicated in the user manual.
@@ -146,30 +146,90 @@ Implementation: 0x20181004
146146
Hart id : 0x0
147147
CPU clock : 64 MHz
148148
RTC clock : 16 KHz
149+
150+
PLIC @0x0c000000
151+
DMAC @0x10040000
152+
UART @0x10013000
153+
GPIO @0x10012000
154+
155+
Z1 > Commands: yield send recv pmp load store exec stats timer restart dma
156+
```
157+
158+
159+
### Optional: Eclipse CDT Project ###
160+
This repository includes an optional Eclipse CDT project for developers familiar with this IDE. No additional plugins are required to build and upload MultiZone to the target. The [OpenOCD debugging plug-in](https://eclipse-embed-cdt.github.io/debug/openocd) is optional and recommended.
161+
162+
**Eclipse project Setup**
163+
164+
File > Open Projects from File System > Import source: ~/multizone-sdk
165+
166+
Project > Properties > C/C++ Build > Environment: set RISCV and OPENOCD variables according to your installation
149167

150-
Z1 > Commands: yield send recv pmp load store exec dma stats timer restart
168+
![alt text](https://hex-five.com/wp-content/uploads/multizone-eclipse-proj.png)
151169

152-
Z1 >
170+
171+
### Optional: FreeRTOS Example ###
172+
No additional software dependencies are required to run MultiZone-based applications. To ease the integration of the MultiZone TEE with legacy applications based on the popular FreeRTOS operating system, the MultiZone SDK includes an optional zone3.1 running FreeRTOS 10.4.0. Its functionality is identical to the one of the original zone3 that controls the robot, but it is implemented as a typical FreeRTOS applications with four tasks and one interrupt handler.
173+
174+
**Installation**
175+
176+
```
177+
cd ~/multizone-sdk
178+
git submodule update --init --recursive
179+
git apply -p1 ext/freertos.patch --directory=ext/freertos
153180
```
154181

155-
### Technical Specs ###
182+
**Setup**
183+
184+
Edit multizone-sdk/Makefile and change the two references to "zone3" into "zone3.1" :
185+
186+
```
187+
...
188+
189+
.PHONY: all
190+
all: clean
191+
$(MAKE) -C zone1
192+
$(MAKE) -C zone2
193+
$(MAKE) -C zone3
194+
$(MAKE) -C zone3.1
195+
$(MAKE) -C zone4
196+
$(MAKE) -C bsp/$(BOARD)/boot
197+
198+
java -jar multizone.jar \
199+
--arch $(BOARD) \
200+
--config bsp/$(BOARD)/multizone.cfg \
201+
--boot bsp/$(BOARD)/boot/boot.hex \
202+
zone1/zone1.hex \
203+
zone2/zone2.hex \
204+
zone3.1/zone3.hex \
205+
zone4/zone4.hex
206+
207+
...
208+
```
209+
Build and load to flash with the commands “make” and “make load”.
210+
211+
Note: to activate MultiZone deep-sleep suspend, set configUSE_TICKLESS_IDLE 1 and configUSE_IDLE_HOOK 0 in ext/FreeRTOSConfig.h. This enables Hex Five’s optimized implementation of the FreeRTOS vPortSuppressTicksAndSleep() that takes full advantage of the RISC-V instruction wfi.
212+
213+
214+
### MultiZone TEE Technical Specs ###
156215
| |
157216
|---|
158-
| Up to 8 hardware threads (zones) hardware-enforced, software-defined |
159-
| Up to 8 memory mapped resources per zone – i.e. flash, ram, rom, i/o, etc. |
160-
| Scheduler: preemptive, cooperative, round robin, configurable tick |
161-
| Secure interzone communications based on messages – no shared memory |
162-
| Built-in support for secure shared Timer interrupt |
163-
| Built-in support for secure shared PLIC interrupt |
164-
| Built-in support for secure DMA transfers |
165-
| Built-in trap & emulation for all privileged instructions – CSRR, CSRW, WFI, etc. |
166-
| Support for secure user-mode interrupt handlers mapped to zones – up to 32 sources PLIC / CLIC |
167-
| Support for Wait For Interrupt and CPU suspend mode for low power applications |
168-
| Formally verifiable runtime ~2KB, 100% written in assembly, no 3rd-party dependencies |
169-
| C library wrapper for protected mode execution – optional for high speed / low-latency |
170-
| Hardware requirements: RV32, RV32e, RV64 cpu with Memory Protection Unit and U extension |
171-
| System requirements: 6KB FLASH, 4KB RAM - CPU overhead < 0.01% |
172-
| Development environment: any versions of Linux, Windows, Mac running Java 1.8 |
217+
| Up to 4 hardware threads (zones) hardware-enforced, software-defined |
218+
| Up to 8 memory mapped resources per zone – i.e. flash, ram, rom, i/o, etc. |
219+
| Scheduler: preemptive, cooperative, round robin, configurable tick or tickless |
220+
| Secure interzone communications based on messages – no shared memory |
221+
| Built-in support for secure shared Timer interrupt |
222+
| Built-in support for secure shared PLIC interrupt |
223+
| Built-in support for secure DMA transfers |
224+
| Built-in support for CLIC, CLINT, and PLIC interrupt controllers |
225+
| Built-in trap & emulation for all privileged instructions – csrr, csrw, ecall, etc. |
226+
| Support for secure user-mode interrupt handlers mapped to zones – up to 32/64 sources |
227+
| Support for CPU deep-sleep suspend mode for low power applications - wfi |
228+
| Formally verifiable runtime ~4KB, 100% written in assembly, no 3rd-party dependencies |
229+
| C macro wrappers for protected mode execution – optional for high speed low-latency |
230+
| Hardware requirements: RV32, RV32e, RV64 cpu with Memory Protection Unit and 'U' mode |
231+
| System requirements: 8KB FLASH, 4KB ITIM, 2KB DTIM - CPU overhead < 0.01% |
232+
| Development environment: any versions of Linux, Windows, Mac running Java 1.8 or newer|
173233

174234

175235
### Additional Resources ###

0 commit comments

Comments
 (0)