diff --git a/doc/building_fpga_bitstreams.md b/doc/building_fpga_bitstreams.md new file mode 100644 index 00000000..f2abf7e1 --- /dev/null +++ b/doc/building_fpga_bitstreams.md @@ -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: + +
+  top_earlgrey #(
+    .SecAesMasking(1'b1),
+    .SecAesSBoxImpl(aes_pkg::SBoxImplDom),
+    .SecAesStartTriggerDelay(320),
+    .SecAesAllowForcingMasks(1'b1),
+    .CsrngSBoxImpl(aes_pkg::SBoxImplLut),
+    .OtbnRegFile(otbn_pkg::RegFileFPGA),
+    .SecOtbnMuteUrnd(1'b1),
+    .SecOtbnSkipUrndReseedAtStart(1'b0),
+    .OtpCtrlMemInitFile(OtpCtrlMemInitFile),
+    .RvCoreIbexPipeLine(1),
+    .SramCtrlRetAonInstrExec(0),
+    .UsbdevRcvrWakeTimeUs(10000),
+    .KmacEnMasking(0),
+    .KmacSwKeyMasked(1),
+    .KeymgrKmacEnMasking(0),
+    .SecKmacCmdDelay(320),
+    .SecKmacIdleAcceptSwMsg(1'b1),
+    .RomCtrlBootRomInitFile(BootRomInitFile),
+    .RvCoreIbexRegFile(ibex_pkg::RegFileFPGA),
+    .RvCoreIbexSecureIbex(0),
+    .SramCtrlMainInstrExec(1),
+    .PinmuxAonTargetCfg(PinmuxTargetCfg)
+```
+
+ +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. diff --git a/doc/getting_started.md b/doc/getting_started.md index 9a48d039..45d2ab07 100644 --- a/doc/getting_started.md +++ b/doc/getting_started.md @@ -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