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 18, 2024
1 parent e251ad0 commit e82a6e4
Show file tree
Hide file tree
Showing 2 changed files with 109 additions and 102 deletions.
100 changes: 100 additions & 0 deletions doc/building_fpga_bitstreams.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,100 @@
# 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 license 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

For SCA measurements on the CW310, different bitstreams are available.

| Name | Description |
|--------------------------------------------------------|----------------------------------------------------------------------------------------------------------|
| lowrisc_systems_chip_earlgrey_cw310_0.1_X.bit | Default bitstream. AES RTL is modified to raise a hardware-based trigger signal for SCA measurements. |
| lowrisc_systems_chip_earlgrey_cw310_0.1_kmac_dom_X.bit | Enables DOM masking for KMAC. Removes some blocks (e.g., OTBN) to save resource utilization on the FPGA. |
| lowrisc_systems_chip_earlgrey_cw310_0.1_ecdsa_X.bit | |

The table above highlights the difference between each bitstream. X denotes the
hardware version, e.g., Z1 or A1.

### Building the Default CW310 Bitstream

To build the default bitstream, 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>

With these hardware changes, the AES and KMAC IP block delay the start of the
operation by 320 cycles, giving Ibex enough time to go into the sleep mode.
Moreover, the KMAC IP block is configured to accept writes to the KMAC message
FIFO before triggering the operations. Finally, OTBN is configured in such a way
that PRNG reseeds are skipped at the OTBN application start.

After making these hardware changes, use the following command to retrieve the
bitstream:

```console
./bazelisk.sh build //hw/bitstream/vivado:fpga_cw310_test_rom
```

The bitstream is located in
```console
bazel-bin/hw/bitstream/vivado/build.fpga_cw310/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit
```
and can be copied into the `objs/` directory of ot-sca.

### Building the KMAC DOM CW310 Bitstream

### Building the ECDSA CW310 Bitstream

## 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.
111 changes: 9 additions & 102 deletions doc/getting_started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -270,111 +270,18 @@ Capturing: 100%|█████████████████████
Created plot with 10 traces: ~/ot-sca/cw/projects/sample_traces_aes.html
```

### Generating Bitstreams for OT-SCA

### Generating OpenTitan Binaries
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).

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.
### Building the Penetration Testing Framework

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.
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. For the FPGA framework, place the generated `.bin`
into the `objs/` directory. For the chip framework, the `.img` files need to be
used.

## Configuration

Expand Down

0 comments on commit e82a6e4

Please sign in to comment.