Skip to content

Commit

Permalink
[doc] Update Bitstream Building Tutorial
Browse files Browse the repository at this point in the history 
This commit updates the instructions how to build the FPGA bitstream
for CW310. Moreover, the instructions how to compile the pen. testing
framework is replaced with a link to the OpenTitan repository.

Signed-off-by: Pascal Nasahl <[email protected]>
  • Loading branch information
@nasahlpa
nasahlpa committed Sep 17, 2024
1 parent e251ad0 commit 08d5d5b
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 102 deletions.
71 changes: 71 additions & 0 deletions doc/building_fpga_bitstreams.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Building FPGA Bitstreams for OT-SCA

The idea of this tutorial is to document how to build FPGA bitstreams that can
be used for performing side-channel analysis on the ChipWhisperer boards using
ot-sca.

## Prerequisites

Bitstreams are created inside the [OpenTitan](https://github.com/lowRISC/OpenTitan)
repository. Make sure to follow the getting started
[guide](https://opentitan.org/book/doc/getting_started/index.html) before attempting
to build bitstreams. A Xilinx Vivado installation with a valid licence is needed.

Then, clone the OpenTitan repository and select a suitable commit. Make sure that
the selected commit is compatible with the penetration testing
[framework](https://github.com/lowRISC/opentitan/tree/master/sw/device/tests/penetrationtests).
When using the latest commit available in the OpenTitan master branch, the framework
and the FPGA bitstream should be compatible.


## Building CW310 Bitstreams

To simplify SCA measurements, please change the following parameters marked in
bold in the
[chip_earlgrey_cw310.sv](https://github.com/lowRISC/opentitan/blob/master/hw/top_earlgrey/rtl/autogen/chip_earlgrey_cw310.sv)
file:

<pre>
top_earlgrey #(
.SecAesMasking(1'b1),
.SecAesSBoxImpl(aes_pkg::SBoxImplDom),
.SecAesStartTriggerDelay(<b>320</b>),
.SecAesAllowForcingMasks(1'b1),
.CsrngSBoxImpl(aes_pkg::SBoxImplLut),
.OtbnRegFile(otbn_pkg::RegFileFPGA),
.SecOtbnMuteUrnd(<b>1'b1</b>),
.SecOtbnSkipUrndReseedAtStart(<b>1'b0</b>),
.OtpCtrlMemInitFile(OtpCtrlMemInitFile),
.RvCoreIbexPipeLine(1),
.SramCtrlRetAonInstrExec(0),
.UsbdevRcvrWakeTimeUs(10000),
.KmacEnMasking(0),
.KmacSwKeyMasked(1),
.KeymgrKmacEnMasking(0),
.SecKmacCmdDelay(<b>320</b>),
.SecKmacIdleAcceptSwMsg(<b>1'b1</b>),
.RomCtrlBootRomInitFile(BootRomInitFile),
.RvCoreIbexRegFile(ibex_pkg::RegFileFPGA),
.RvCoreIbexSecureIbex(0),
.SramCtrlMainInstrExec(1),
.PinmuxAonTargetCfg(PinmuxTargetCfg)
```
</pre>

Then, use the following commands to retrieve the bitstream:

```console
./bazelisk.sh build //hw/bitstream/vivado:fpga_cw310_test_rom
cp bazel-bin/hw/bitstream/vivado/build.fpga_cw310/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit ../ot-sca/objs/
```

## Building CW305 Bitstreams

# TODO(lowrisc/ot-sca#377): Add instructions how to build bitstreams for CW305.

## Pushing Bitstreams to OT-SCA

When pushing bitstream to the ot-sca repository, please make sure:
- To include the git commit hash used for building the bitstream in the commit message.
- That the bitstream is compatible with the penetration testing firmware.
- That the bitstream is tracked in git lfs and is not pushed in plain.
110 changes: 8 additions & 102 deletions doc/getting_started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -271,110 +271,16 @@ Created plot with 10 traces: ~/ot-sca/cw/projects/sample_traces_aes.html
```


### Generating OpenTitan Binaries
### Generating Bitstreams for OT-SCA

Instead of using the example binaries provided by this repository via Git LFS,
you can regenerate them from the
[OpenTitan](https://github.com/lowRISC/OpenTitan) repository.
If you want to build the bitstreams by yourself instead of using the pre-build
ones stored in `objs/`, please follow this [guide](./building_fpga_bitstreams.md).

Below, we quickly outline the necessary steps for building the binaries for the
CW310 and CW305 boards from the sources. For more information on the build
steps, refer to the [OpenTitan FPGA documentation](https://docs.opentitan.org/doc/ug/getting_started_fpga/).

Note that below we use `$REPO_TOP` to refer to the main OpenTitan repository
top, not this `ot-sca` repo.

#### Earl Grey for CW310

To build the binaries for performing SCA on the full Earl Grey top level of
OpenTitan using the CW310, follow these steps:

1. Go to the root directory of the OpenTitan repository.
1. Build the regular binaries with
```console
$ cd $REPO_TOP
$ ./bazelisk.sh build //sw/...
```
1. Then, the bitstream generation can be started by running
```console
$ . /tools/xilinx/Vivado/2020.2/settings64.sh
$ cd $REPO_TOP
$ fusesoc --cores-root . run --flag=fileset_top --target=synth lowrisc:systems:chip_earlgrey_cw310
```
The generated bitstream can be found in
```
build/lowrisc_systems_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit
```
and will be loaded to the FPGA using the ChipWhisperer Python API.

1. To generate the OpenTitan application binary (simpleserial interface), e.g.,
for recording AES power traces on the CW310, run
```console
$ cd $REPO_TOP
$ ./bazelisk.sh build //sw/device/sca:aes_serial
```
The path to the generated binary is:
```
$REPO_TOP/bazel-bin/sw/device/sca/
```
To generate the OpenTitan application binary for uJSON that includes all SCA
targets, run
```console
$ cd $REPO_TOP
$ ./bazelisk.sh build //sw/device/tests/crypto/cryptotest/firmware:firmware
```
#### English Breakfast for CW305
To build the binaries for performing SCA of e.g. AES on the reduced English
Breakfast top level of OpenTitan using the CW305, follow these steps:
1. Go to the root directory of the OpenTitan repository.
1. Before generating the OpenTitan FPGA bitstream for the CW305 target board, you first have to run:
```console
$ cd $REPO_TOP
$ ./util/topgen-fusesoc.py --files-root=. --topname=top_englishbreakfast
```
to generate top-level specific versions of some IP cores such as RV_PLIC,
TL-UL crossbars etc.
1. Then run
```console
$ cd $REPO_TOP
$ ./hw/top_englishbreakfast/util/prepare_sw.py --build --top=englishbreakfast
```
in order to prepare the OpenTitan software build flow for English
Breakfast and build the required binaries. More precisely, this script
runs some code generators, patches some auto-generated source files and
finally generates the boot ROM needed for bitstream generation.
1. Finally, the bitstream generation can be started by running
```console
$ cd $REPO_TOP
$ fusesoc --cores-root . run --flag=fileset_topgen --target=synth lowrisc:systems:chip_englishbreakfast_cw305
```
The generated bitstream can be found in
```
build/lowrisc_systems_chip_englishbreakfast_cw305_0.1/synth-vivado/lowrisc_systems_chip_englishbreakfast_cw305_0.1.bit
```
and will be loaded to the FPGA using the ChipWhisperer Python API.
1. To generate the OpenTitan application binary for recording AES power traces,
make sure the `prepare_sw.py` script has been run before executing
```console
$ cd $REPO_TOP
$ ./bazelisk.sh build //sw/device/sca:aes_serial --copt=-DOT_IS_ENGLISH_BREAKFAST_REDUCED_SUPPORT_FOR_INTERNAL_USE_ONLY_
```
1. The path to the generated binary will be printed to the terminal after running
```console
$ cd $REPO_TOP
$ ci/scripts/target-location.sh //sw/device/sca:aes_serial
```

If you need to generate binaries for CW310 after you generate binaries for
CW305, use the following command:
```console
$ ./hw/top_englishbreakfast/util/prepare_sw.py --delete
```
and clean the auto-generated files with a checkout.
### Building the Penetration Testing Framework

Similarly, to build the penetration testing framework, please follow the
[guide](https://github.com/lowRISC/opentitan/tree/master/sw/device/tests/penetrationtests)
in the OpenTitan repository.

## Configuration

Expand Down

0 comments on commit 08d5d5b

Please sign in to comment.