Copyright (C) 2020
This software is licensed under the MIT license. See LICENSE file at the root folder of the project.
- Guillaume BOUFFARD (mailto:[email protected])
- Léo GASPARD (mailto:[email protected])
The Java Card Operating System (OS) is a part of CHOUPI Project. Java Card OS is a secure-oriented OS for small footprint embedded devices developed in Rust. This OS aims at running a Java Card Virtual Machine.
More details of this project were published in an article available on SSTIC 2018. A presentation in French is also available.
- The
arm-none-eabi
toolchain. The main Linux distributions provide a package for this toolchain. One can manually install via the ARM developer website. - openocd. OpenOCD is used to interface
rlwrap
and GDB to the border. OpenOCD is avalaible on main Linux distribution. - rlwrap. rlwrap is used to send commands to the board through OpenOCD. rlwrap is also avalaible on main Linux distributions.
To clone the repository and its dependency, you should execute the following command:
git clone --recursive https://github.com/choupi-project/choupi-os
The nightly version of Rust is required. The
current supported version rust-1.43-nightly
. To install it you should:
-
Install
rustup
:curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
Adding rust to your
PATH
file:source ~/.cargo/env
-
Install the nightly version of the rust compiler:
rustup default nightly-2020-03-10
To have a ready-to-build version of the Java Card OS. The last checked version of rust nightly compiler is
1.43.0-nightly
. -
Install
xargo
:cargo install xargo
-
Add
rust-src
component:rustup component add rust-src
-
To build to ARM Cortex M4 board, you should run:
rustup target add thumbv7em-none-eabi
-
Optional step: install clippy, for
make clippy
support:rustup component add clippy
-
You're ready to compile using
make
! You can also run the tests usingmake test
(and long-running tests withmake test-ignored
).
The Java Card OS has two main targets : computer and embedded board. The computer version emulates the MPU behavior. The MPU emulation on computer blocks the usage of a debugger (but debugging works fine on the embedded version :).
-
Building OS for computer :
make host-build
-
Building for embedded target:
make
Currently, the only target is a Nucleo board which embeds a STM32f401. The OS can easily be extended to support new targets.
There is documentation provided from source code.
To generate it, just run make doc
with rustdoc
installed (which
should be the case if you followed the setup described above).
It will then land in a doc
folder, whose entry point is
doc/javacard_os/index.html
.
In order to get the right fonts, if you are using firefox opening computer-local
resources, you should set security.fileuri.strict_origin_policy
to false
in
about:config in Firefox.
Currently, the only target is ST Nucleo STM32f401. To load firmware on board, we
use rlwrap
though OpenOCD.
-
start OpenOCD in a terminal:
sudo make ocd
-
in another terminal, run
rlwrap
:sudo make manage
As indicate, to install the firmware, you should execute:
reset halt; flash write_image erase loader.hex; flash write_image erase code.hex; reset run
To see the debug message, in case of the OS is built in debug mode. The Makefile may be modified to built the OS in debug mode.
make screen
To running the OS on board though a debugger, arm-none-eabi-gdb
must be
installed.
-
Starting openOCD in a terminal:
sudo make ocd
-
Starting GDB in another terminal :
make debug
-
Enjoy debugging
Note that for tests, it may be hard to debug some issues, like when the child in
an emulation has an unexpected behaviour at runtime that is not a panic!
, as it
would require a debugger, which is not possible given the emulator is already a
pseudo-debugger.
For this reason, sending SIGILL
to the child process will make the emulator
(ie. parent process) to make it dump core. The core dump can then be used to try
to debug the issue.
For using clippy (additional lints for rust code), you can run make clippy
after having installed clippy
as per setup step 7.