doc/rm/ref_manual_fpga.md - 3p/lowrisc/opentitan - Git at Google

 ---
 title: "FPGA Reference Manual"
 ---

 This manual provides additional usage details about the FPGA.
 Specifically, it provides instructions on SW development flows and testing procedures.
 Refer to the [FPGA Setup]({{< relref "doc/getting_started/setup_fpga" >}}) guide for more information on initial setup.

 ## FPGA SW Development Flow

 The FPGA is meant for both boot ROM and general software development.
 The flow for each is different, as the boot ROM is meant to be fairly static while general software can change very frequently.

 ### Boot ROM development

 The FPGA bitstream is built after compiling whatever code is sitting in `sw/device/lib/testing/test_rom`.
 This binary is used to initialize internal FPGA memory and is part of the bitstream directly.

 To update this content without rebuilding the FPGA, a flow is required to splice a new boot ROM binary into the bitstream.
 There are two prerequisites in order for this flow to work:
 * The boot ROM during the build process must be correctly inferred by the tool.
   * See [prim_rom](https://github.com/lowRISC/opentitan/blob/master/hw/ip/prim_generic/rtl/prim_generic_rom.sv) and [vivado_hook_opt_design_post.tcl](https://github.com/lowRISC/opentitan/blob/master/hw/top_earlgrey/util/vivado_hook_opt_design_post.tcl).
 * The MMI file outlining the physical boot ROM placement and mapping to FPGA block RAM primitives needs to be generated by the tool.
   * See [vivado_hook_write_bitstream_pre.tcl](https://github.com/lowRISC/opentitan/blob/master/hw/top_earlgrey/util/vivado_hook_write_bitstream_pre.tcl).

 With these steps in place, a script can be invoked to take a new binary and push its contents into an existing bitfile.
 For details, please see the [`splice_rom.sh`](https://github.com/lowRISC/opentitan/blob/master/util/fpga/splice_rom.sh) script.

 See example below:

 ```console
 $ cd $REPO_TOP
 $ ./util/fpga/splice_rom.sh
 $ bazel run //sw/host/opentitantool load-bitstream build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit
 ```

 The script assumes that there is an existing bitfile `build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit` (this is created after following the steps in [FPGA Setup]({{< relref "doc/getting_started/setup_fpga" >}})).

 The script assumes that there is an existing boot ROM image under `build-bin/sw/device/lib/testing/test_rom` and then creates a new bitfile of the same name at the same location.
 The original input bitfile is moved to `build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit.orig`.

 `opentitantool` can then be used to directly flash the updated bitstream to the FPGA.

 ### General Software Development

 After building, the FPGA bitstream contains only the boot ROM.
 Using this boot ROM, the FPGA is able to load additional software to the emulated flash, such as software in the `sw/device/benchmark`, `sw/device/examples` and `sw/device/tests` directories.
 To load additional software, `opentitantool` is required.

 Also the binary you wish to load needs to be built first.
 For the purpose of this demonstration, we will use `sw/device/examples/hello_world`, but it applies to any software image that is able to fit in the emulated flash space.
 The example below builds the `hello_world` image and loads it onto the FPGA.

 ```console
 $ cd ${REPO_TOP}
 $ bazel run //sw/host/opentitantool set-pll # This needs to be done only once.
 $ bazel build //sw/device/examples/hello_world:hello_world_fpga_cw310_bin
 $ bazel run //sw/host/opentitantool bootstrap $(ci/scripts/target-location.sh //sw/device/examples/hello_world:hello_world_fpga_cw310_bin)
 ```

 Uart output:
 ```
 I00000 test_rom.c:81] Version: earlgrey_silver_release_v5-5886-gde4cb1bb9, Build Date: 2022-06-13 09:17:56
 I00001 test_rom.c:87] TestROM:6b2ca9a1
 I00000 test_rom.c:81] Version: earlgrey_silver_release_v5-5886-gde4cb1bb9, Build Date: 2022-06-13 09:17:56
 I00001 test_rom.c:87] TestROM:6b2ca9a1
 I00002 test_rom.c:118] Test ROM complete, jumping to flash!
 I00000 hello_world.c:66] Hello World!
 I00001 hello_world.c:67] Built at: Jun 13 2022, 14:16:59
 I00002 demos.c:18] Watch the LEDs!
 I00003 hello_world.c:74] Try out the switches on the board
 I00004 hello_world.c:75] or type anything into the console window.
 I00005 hello_world.c:76] The LEDs show the ASCII code of the last character.
 ```

 For more details on the exact operation of the loading flow and how the boot ROM processes incoming data, please refer to the [boot ROM readme](https://github.com/lowRISC/opentitan/tree/master/sw/device/lib/testing/test_rom).
	---
	title: "FPGA Reference Manual"
	---

	This manual provides additional usage details about the FPGA.
	Specifically, it provides instructions on SW development flows and testing procedures.
	Refer to the [FPGA Setup]({{< relref "doc/getting_started/setup_fpga" >}}) guide for more information on initial setup.

	## FPGA SW Development Flow

	The FPGA is meant for both boot ROM and general software development.
	The flow for each is different, as the boot ROM is meant to be fairly static while general software can change very frequently.

	### Boot ROM development

	The FPGA bitstream is built after compiling whatever code is sitting in `sw/device/lib/testing/test_rom`.
	This binary is used to initialize internal FPGA memory and is part of the bitstream directly.

	To update this content without rebuilding the FPGA, a flow is required to splice a new boot ROM binary into the bitstream.
	There are two prerequisites in order for this flow to work:
	* The boot ROM during the build process must be correctly inferred by the tool.
	* See [prim_rom](https://github.com/lowRISC/opentitan/blob/master/hw/ip/prim_generic/rtl/prim_generic_rom.sv) and [vivado_hook_opt_design_post.tcl](https://github.com/lowRISC/opentitan/blob/master/hw/top_earlgrey/util/vivado_hook_opt_design_post.tcl).
	* The MMI file outlining the physical boot ROM placement and mapping to FPGA block RAM primitives needs to be generated by the tool.
	* See [vivado_hook_write_bitstream_pre.tcl](https://github.com/lowRISC/opentitan/blob/master/hw/top_earlgrey/util/vivado_hook_write_bitstream_pre.tcl).

	With these steps in place, a script can be invoked to take a new binary and push its contents into an existing bitfile.
	For details, please see the [`splice_rom.sh`](https://github.com/lowRISC/opentitan/blob/master/util/fpga/splice_rom.sh) script.

	See example below:

	```console
	$ cd $REPO_TOP
	$ ./util/fpga/splice_rom.sh
	$ bazel run //sw/host/opentitantool load-bitstream build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit
	```

	The script assumes that there is an existing bitfile `build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit` (this is created after following the steps in [FPGA Setup]({{< relref "doc/getting_started/setup_fpga" >}})).

	The script assumes that there is an existing boot ROM image under `build-bin/sw/device/lib/testing/test_rom` and then creates a new bitfile of the same name at the same location.
	The original input bitfile is moved to `build/lowrisc_systems_chip_earlgrey_cw310_0.1/synth-vivado/lowrisc_systems_chip_earlgrey_cw310_0.1.bit.orig`.

	`opentitantool` can then be used to directly flash the updated bitstream to the FPGA.

	### General Software Development

	After building, the FPGA bitstream contains only the boot ROM.
	Using this boot ROM, the FPGA is able to load additional software to the emulated flash, such as software in the `sw/device/benchmark`, `sw/device/examples` and `sw/device/tests` directories.
	To load additional software, `opentitantool` is required.

	Also the binary you wish to load needs to be built first.
	For the purpose of this demonstration, we will use `sw/device/examples/hello_world`, but it applies to any software image that is able to fit in the emulated flash space.
	The example below builds the `hello_world` image and loads it onto the FPGA.

	```console
	$ cd ${REPO_TOP}
	$ bazel run //sw/host/opentitantool set-pll # This needs to be done only once.
	$ bazel build //sw/device/examples/hello_world:hello_world_fpga_cw310_bin
	$ bazel run //sw/host/opentitantool bootstrap $(ci/scripts/target-location.sh //sw/device/examples/hello_world:hello_world_fpga_cw310_bin)
	```

	Uart output:
	```
	I00000 test_rom.c:81] Version: earlgrey_silver_release_v5-5886-gde4cb1bb9, Build Date: 2022-06-13 09:17:56
	I00001 test_rom.c:87] TestROM:6b2ca9a1
	I00000 test_rom.c:81] Version: earlgrey_silver_release_v5-5886-gde4cb1bb9, Build Date: 2022-06-13 09:17:56
	I00001 test_rom.c:87] TestROM:6b2ca9a1
	I00002 test_rom.c:118] Test ROM complete, jumping to flash!
	I00000 hello_world.c:66] Hello World!
	I00001 hello_world.c:67] Built at: Jun 13 2022, 14:16:59
	I00002 demos.c:18] Watch the LEDs!
	I00003 hello_world.c:74] Try out the switches on the board
	I00004 hello_world.c:75] or type anything into the console window.
	I00005 hello_world.c:76] The LEDs show the ASCII code of the last character.
	```

	For more details on the exact operation of the loading flow and how the boot ROM processes incoming data, please refer to the [boot ROM readme](https://github.com/lowRISC/opentitan/tree/master/sw/device/lib/testing/test_rom).