doc/ug/quickstart.md - 3p/lowrisc/opentitan - Git at Google

 ---
 title: "Quickstart"
 ---

 ## Install required packages

 To follow the guide below the following things must be installed:

 * xz-utils
 * screen
 * fdisk
 * libusb 1.x
 * libftdi1 1.x
 * usbutils
 * libelf1

 Under Ubuntu these can be installed with:
 ```console
 $ sudo apt-get install xz-utils screen fdisk libftdi1-2 libusb-1.0-0 usbutils libelf1
 ```

 ## Extract the release

 Download a release bitstream from the [OpenTitan GitHub Releases page](https://github.com/lowRISC/opentitan/releases) and extract it.
 `$OT_TOP` refers to the location where it is extracted.

 ```console
 $ mkdir -p $OT_TOP
 $ tar -C $OT_TOP -xvf opentitan-snapshot-20191101-1.tar.xz --strip-components=1
 ```

 (Replace opentitan-snapshot-20191101-1.tar.xz with the release you downloaded if you have downloaded a different version)

 ## Simulation with Verilator

 Run the provided simulator binary with
 ```console
 $ cd $OT_TOP
 $ ./hw/top_earlgrey/Vtop_earlgrey_verilator --rominit=./sw/device/sim/boot_rom/rom.vmem --flashinit=./sw/device/sim/examples/hello_world/sw.vmem

 Simulation of OpenTitan Earl Grey
 =================================

 Tracing can be toggled by sending SIGUSR1 to this process:
 $ kill -USR1 19351

 Rom initialized with program at ./sw/device/sim/boot_rom/rom.vmem

 Flash initialized with program at ./sw/device/sim/examples/hello_world/sw.vmem

 GPIO: FIFO pipe created at /home/greg/work/opentitan_builds/ot/gpio0 for 32 bit wide GPIO. Run
 $ cat /home/greg/work/opentitan_builds/ot/gpio0
 to observe the output.

 JTAG: Virtual JTAG interface jtag0 is listening on port 44853. Use
 OpenOCD and the following configuration to connect:
   interface remote_bitbang
   remote_bitbang_host localhost
   remote_bitbang_port 44853

 SPI: Created /dev/pts/4 for spi0. Connect to it with any terminal program, e.g.
 $ screen /dev/pts/4
 NOTE: a SPI transaction is run for every 4 characters entered.
 SPI: Monitor output file created at /home/greg/work/opentitan_builds/ot/spi0.log. Works well with tail:
 $ tail -f /home/greg/work/opentitan_builds/ot/spi0.log

 UART: Created /dev/pts/6 for uart0. Connect to it with any terminal program, e.g.
 $ screen /dev/pts/6

 Simulation running, end by pressing CTRL-c.
 TOP.top_earlgrey_verilator.top_earlgrey.core.ibex_tracer_i: Writing execution trace to trace_core_00000000.log
 ```

 Note the UART output will be available on `/dev/pts/N`, `/dev/pts/6` in this example.
 Use `cat` to view the UART output to see everything that has been output since simulation start.

 ```console
 $ cat /dev/pts/6
 Commit ID:  1d0d927693c2ef60d7880ab306beb25115a53dcb
 Build Date: 2019-11-01, 15:57:42
 Jump!
 Hello World! Nov  1 2019 15:57:49
 Watch the LEDs!
 Try out the switches on the board
 or type anything into the console window.
 The LEDs show the ASCII code of the last character.
 ```

 See the [Getting Started with Verilator Guide]({{< relref "getting_started_verilator.md" >}}) for more information.

 ## Running on an FPGA

 Do you want to try out the design without installing EDA tools and waiting for a long build?
 Then you have come to the right place!

 You need the following things:

 * A [Nexys Video FPGA board](https://store.digilentinc.com/nexys-video-artix-7-fpga-trainer-board-for-multimedia-applications/)
   (Unfortunately we do not provide presynthesized bitstreams for other FPGA boards right now.)
 * An empty USB pen drive or microSD card (at least 16 MB)
 * `fdisk` utility installed on your machine.

 Once you have obtained these things, follow these steps to get started.

 ### Prepare a storage device with the FPGA bitstream

 **Note**: you may need to be an admin on your machine in order to mount and format external storage devices.
 If you are, and some of the commands run into permission errors, run them in `sudo` mode.

 1.  Insert microSD/USB pen to your machine.
 2.  Run `fdisk -l` to find where the device was mapped.
     See an example mapping below, where an SD device was mapped as */dev/mmcblk0p1*.

     ```console
     $ fdisk -l
     ...
     Disk /dev/mmcblk0: 14.9 GiB, 15931539456 bytes, 31116288 sectors
     Units: sectors of 1 * 512 = 512 bytes
     Sector size (logical/physical): 512 bytes / 512 bytes
     I/O size (minimum/optimal): 512 bytes / 512 bytes
     Disklabel type: dos
     Disk identifier: 0x00000000

     Device         Boot Start      End  Sectors  Size Id Type
     /dev/mmcblk0p1       8192 31116287 31108096 14.9G  c W95 FAT32 (LBA)
     ```

 3.  Format the device to  *FAT32* format.
     ```console
     $ mkfs.fat -F 32 /dev/mmcblk0p1
     ```

 4.  Mount the device by running the following commands:

     ```console
     $ mkdir -p ~/ot-img-mount  # Can be a different name
     $ mount -t vfat /dev/mmcblk0p1 ~/ot-img-mount  # Change according to mount/dev
     ```

 5.  Make sure the device is empty. `ls ~/ot-img-mount` should not print anything.
 6.  Copy the bit file image to the storage device.
     ```console
     $ cd $OT_TOP
     $ cp hw/top_earlgrey/lowrisc_systems_top_earlgrey_nexysvideo_0.1.bit ~/ot-img-mount/
     ```

 For more information on programming the Nexsys Video FPGA board refer to Section 2.3 of [Nexys Video reference manual](https://reference.digilentinc.com/_media/reference/programmable-logic/nexys-video/nexysvideo_rm.pdf).

 ### Program the FPGA with a bitstream from the storage device

 1.  Connect the USB pen drive or the microSD card to the Nexys Video board.
     The microSD slot sits on the bottom of the board and marked "SD MICRO", USB header is in the top and marked "USB HOST".
 2.  Place JP4 on the pins marked USB/SD.
 3.  Place JP3 according to the selected device (marked either USB or SD).
 4.  Push the PROG button. The BUSY LED (LD14) should be steadily on.
 5.  Wait for the BUSY LED to turn off, DONE (LD15) should turn on.

 ### Run software on the FPGA

 **Note**: Your user account needs to have access to connected USB devices.
 See [the section udev rules of the installation guide]({{< relref "install_instructions#device-permissions-udev-rules" >}}) for more details.

 1.  Connect a micro USB cable from your machine to the UART connector (J13) on Nexys Video board.
 2.  Use `dmesg` to determine which serial port was assigned:

     ```console
     $ dmesg
     [23426.869858] usb 1-3: new full-speed USB device number 27 using xhci_hcd
     [23427.023299] usb 1-3: New USB device found, idVendor=0403, idProduct=6001, bcdDevice= 6.00
     [23427.023301] usb 1-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
     [23427.023301] usb 1-3: Product: FT232R USB UART
     [23427.023302] usb 1-3: Manufacturer: FTDI
     [23427.023303] usb 1-3: SerialNumber: A503XQQS
     [23427.026674] ftdi_sio 1-3:1.0: FTDI USB Serial Device converter detected
     [23427.026691] usb 1-3: Detected FT232RL
     [23427.027019] usb 1-3: FTDI USB Serial Device converter now attached to ttyUSB0
     ```

     It should be named `/dev/ttyUSB*` in this example it is `/dev/ttyUSB0`.
 3.  Open a serial console (use the device file determined before) and connect.
     Settings: 230400 baud, 8N1, no hardware or software flow control.
     `screen` needs to be installed first.

     ```console
     $ screen /dev/ttyUSB0 230400
     ```

 4.  On the Nexys Video board, press the red button labeled CPU_RESET.
 5.  Observe the terminal output, it should show a ROM boot message like this:

     ```
     Commit ID:  1d0d927693c2ef60d7880ab306beb25115a53dcb
     Build Date: 2019-11-01, 15:57:43
     Jump!
     ```
     (To exit `screen` press <kbd>CTRL</kbd>+<kbd>A</kbd> keys together, then press <kbd>K</kbd>, and then confirm exit by pressing <kbd>y</kbd>.)
 6. Connect a micro USB cable from your machine to the PROG connector (J12) on the Nexsys Video board (noting you need to also have a connection to the UART connector to see serial output).
 7. Use the `spiflash` tool to write the hello_world binary:
     ```console
     $ cd $OT_TOP
     $ ./sw/host/spiflash/spiflash --input=sw/device/fpga/examples/hello_world/sw.bin
     ```
     You should see output from the `spiflash` tool showing the progress:
     ```console
     Running SPI flash update.
     Image divided into 6 frames.
     frame: 0x00000000 to offset: 0x00000000
     frame: 0x00000001 to offset: 0x000003d8
     frame: 0x00000002 to offset: 0x000007b0
     frame: 0x00000003 to offset: 0x00000b88
     frame: 0x00000004 to offset: 0x00000f60
     frame: 0x80000005 to offset: 0x00001338
     ```

     and matching output from the serial console from the boot rom loading the program:
     ```console
     Processing frame no: 00000000 exp no: 00000000
     Processing frame no: 00000001 exp no: 00000001
     Processing frame no: 00000002 exp no: 00000002
     Processing frame no: 00000003 exp no: 00000003
     Processing frame no: 00000004 exp no: 00000004
     Processing frame no: 80000005 exp no: 00000005
     bootstrap: DONE!
     Jump!
     ```
 8. The hello_world binary will output the following:
     ```console
     Hello World! Oct 31 2019 16:28:03
     Watch the LEDs!
     Try out the switches on the board
     or type anything into the console window.
     The LEDs show the ASCII code of the last character.
     FTDI control changed. Enable JTAG
     ```

     Press some keys in the serial console and you should see the ASCII values of the characters sent shown in binary on the LEDs of the Nexsys Video FPGA board.

 To build the software yourself follow the instructions in [Testing the demo design]({{< relref "getting_started_fpga.md#testing-the-demo-design" >}}) (note the software tools must be installed and a clone of the OpenTitan repository made, this is explained in the [Install Instructions]({{< relref "install_instructions" >}})).
 See the [Getting Started on FPGAs Guide]({{< relref "getting_started_fpga.md" >}}) for full instructions how to build your own bitstream.
	---
	title: "Quickstart"
	---

	## Install required packages

	To follow the guide below the following things must be installed:

	* xz-utils
	* screen
	* fdisk
	* libusb 1.x
	* libftdi1 1.x
	* usbutils
	* libelf1

	Under Ubuntu these can be installed with:
	```console
	$ sudo apt-get install xz-utils screen fdisk libftdi1-2 libusb-1.0-0 usbutils libelf1
	```

	## Extract the release

	Download a release bitstream from the [OpenTitan GitHub Releases page](https://github.com/lowRISC/opentitan/releases) and extract it.
	`$OT_TOP` refers to the location where it is extracted.

	```console
	$ mkdir -p $OT_TOP
	$ tar -C $OT_TOP -xvf opentitan-snapshot-20191101-1.tar.xz --strip-components=1
	```

	(Replace opentitan-snapshot-20191101-1.tar.xz with the release you downloaded if you have downloaded a different version)

	## Simulation with Verilator

	Run the provided simulator binary with
	```console
	$ cd $OT_TOP
	$ ./hw/top_earlgrey/Vtop_earlgrey_verilator --rominit=./sw/device/sim/boot_rom/rom.vmem --flashinit=./sw/device/sim/examples/hello_world/sw.vmem

	Simulation of OpenTitan Earl Grey
	=================================

	Tracing can be toggled by sending SIGUSR1 to this process:
	$ kill -USR1 19351

	Rom initialized with program at ./sw/device/sim/boot_rom/rom.vmem

	Flash initialized with program at ./sw/device/sim/examples/hello_world/sw.vmem

	GPIO: FIFO pipe created at /home/greg/work/opentitan_builds/ot/gpio0 for 32 bit wide GPIO. Run
	$ cat /home/greg/work/opentitan_builds/ot/gpio0
	to observe the output.

	JTAG: Virtual JTAG interface jtag0 is listening on port 44853. Use
	OpenOCD and the following configuration to connect:
	interface remote_bitbang
	remote_bitbang_host localhost
	remote_bitbang_port 44853

	SPI: Created /dev/pts/4 for spi0. Connect to it with any terminal program, e.g.
	$ screen /dev/pts/4
	NOTE: a SPI transaction is run for every 4 characters entered.
	SPI: Monitor output file created at /home/greg/work/opentitan_builds/ot/spi0.log. Works well with tail:
	$ tail -f /home/greg/work/opentitan_builds/ot/spi0.log

	UART: Created /dev/pts/6 for uart0. Connect to it with any terminal program, e.g.
	$ screen /dev/pts/6

	Simulation running, end by pressing CTRL-c.
	TOP.top_earlgrey_verilator.top_earlgrey.core.ibex_tracer_i: Writing execution trace to trace_core_00000000.log
	```

	Note the UART output will be available on `/dev/pts/N`, `/dev/pts/6` in this example.
	Use `cat` to view the UART output to see everything that has been output since simulation start.

	```console
	$ cat /dev/pts/6
	Commit ID: 1d0d927693c2ef60d7880ab306beb25115a53dcb
	Build Date: 2019-11-01, 15:57:42
	Jump!
	Hello World! Nov 1 2019 15:57:49
	Watch the LEDs!
	Try out the switches on the board
	or type anything into the console window.
	The LEDs show the ASCII code of the last character.
	```

	See the [Getting Started with Verilator Guide]({{< relref "getting_started_verilator.md" >}}) for more information.

	## Running on an FPGA

	Do you want to try out the design without installing EDA tools and waiting for a long build?
	Then you have come to the right place!

	You need the following things:

	* A [Nexys Video FPGA board](https://store.digilentinc.com/nexys-video-artix-7-fpga-trainer-board-for-multimedia-applications/)
	(Unfortunately we do not provide presynthesized bitstreams for other FPGA boards right now.)
	* An empty USB pen drive or microSD card (at least 16 MB)
	* `fdisk` utility installed on your machine.

	Once you have obtained these things, follow these steps to get started.

	### Prepare a storage device with the FPGA bitstream

	Note: you may need to be an admin on your machine in order to mount and format external storage devices.
	If you are, and some of the commands run into permission errors, run them in `sudo` mode.

	1. Insert microSD/USB pen to your machine.
	2. Run `fdisk -l` to find where the device was mapped.
	See an example mapping below, where an SD device was mapped as /dev/mmcblk0p1.

	```console
	$ fdisk -l
	...
	Disk /dev/mmcblk0: 14.9 GiB, 15931539456 bytes, 31116288 sectors
	Units: sectors of 1 * 512 = 512 bytes
	Sector size (logical/physical): 512 bytes / 512 bytes
	I/O size (minimum/optimal): 512 bytes / 512 bytes
	Disklabel type: dos
	Disk identifier: 0x00000000

	Device Boot Start End Sectors Size Id Type
	/dev/mmcblk0p1 8192 31116287 31108096 14.9G c W95 FAT32 (LBA)
	```

	3. Format the device to FAT32 format.
	```console
	$ mkfs.fat -F 32 /dev/mmcblk0p1
	```

	4. Mount the device by running the following commands:

	```console
	$ mkdir -p ~/ot-img-mount # Can be a different name
	$ mount -t vfat /dev/mmcblk0p1 ~/ot-img-mount # Change according to mount/dev
	```

	5. Make sure the device is empty. `ls ~/ot-img-mount` should not print anything.
	6. Copy the bit file image to the storage device.
	```console
	$ cd $OT_TOP
	$ cp hw/top_earlgrey/lowrisc_systems_top_earlgrey_nexysvideo_0.1.bit ~/ot-img-mount/
	```

	For more information on programming the Nexsys Video FPGA board refer to Section 2.3 of [Nexys Video reference manual](https://reference.digilentinc.com/_media/reference/programmable-logic/nexys-video/nexysvideo_rm.pdf).

	### Program the FPGA with a bitstream from the storage device

	1. Connect the USB pen drive or the microSD card to the Nexys Video board.
	The microSD slot sits on the bottom of the board and marked "SD MICRO", USB header is in the top and marked "USB HOST".
	2. Place JP4 on the pins marked USB/SD.
	3. Place JP3 according to the selected device (marked either USB or SD).
	4. Push the PROG button. The BUSY LED (LD14) should be steadily on.
	5. Wait for the BUSY LED to turn off, DONE (LD15) should turn on.

	### Run software on the FPGA

	Note: Your user account needs to have access to connected USB devices.
	See [the section udev rules of the installation guide]({{< relref "install_instructions#device-permissions-udev-rules" >}}) for more details.

	1. Connect a micro USB cable from your machine to the UART connector (J13) on Nexys Video board.
	2. Use `dmesg` to determine which serial port was assigned:

	```console
	$ dmesg
	[23426.869858] usb 1-3: new full-speed USB device number 27 using xhci_hcd
	[23427.023299] usb 1-3: New USB device found, idVendor=0403, idProduct=6001, bcdDevice= 6.00
	[23427.023301] usb 1-3: New USB device strings: Mfr=1, Product=2, SerialNumber=3
	[23427.023301] usb 1-3: Product: FT232R USB UART
	[23427.023302] usb 1-3: Manufacturer: FTDI
	[23427.023303] usb 1-3: SerialNumber: A503XQQS
	[23427.026674] ftdi_sio 1-3:1.0: FTDI USB Serial Device converter detected
	[23427.026691] usb 1-3: Detected FT232RL
	[23427.027019] usb 1-3: FTDI USB Serial Device converter now attached to ttyUSB0
	```

	It should be named `/dev/ttyUSB*` in this example it is `/dev/ttyUSB0`.
	3. Open a serial console (use the device file determined before) and connect.
	Settings: 230400 baud, 8N1, no hardware or software flow control.
	`screen` needs to be installed first.

	```console
	$ screen /dev/ttyUSB0 230400
	```

	4. On the Nexys Video board, press the red button labeled CPU_RESET.
	5. Observe the terminal output, it should show a ROM boot message like this:

	```
	Commit ID: 1d0d927693c2ef60d7880ab306beb25115a53dcb
	Build Date: 2019-11-01, 15:57:43
	Jump!
	```
	(To exit `screen` press <kbd>CTRL</kbd>+<kbd>A</kbd> keys together, then press <kbd>K</kbd>, and then confirm exit by pressing <kbd>y</kbd>.)
	6. Connect a micro USB cable from your machine to the PROG connector (J12) on the Nexsys Video board (noting you need to also have a connection to the UART connector to see serial output).
	7. Use the `spiflash` tool to write the hello_world binary:
	```console
	$ cd $OT_TOP
	$ ./sw/host/spiflash/spiflash --input=sw/device/fpga/examples/hello_world/sw.bin
	```
	You should see output from the `spiflash` tool showing the progress:
	```console
	Running SPI flash update.
	Image divided into 6 frames.
	frame: 0x00000000 to offset: 0x00000000
	frame: 0x00000001 to offset: 0x000003d8
	frame: 0x00000002 to offset: 0x000007b0
	frame: 0x00000003 to offset: 0x00000b88
	frame: 0x00000004 to offset: 0x00000f60
	frame: 0x80000005 to offset: 0x00001338
	```

	and matching output from the serial console from the boot rom loading the program:
	```console
	Processing frame no: 00000000 exp no: 00000000
	Processing frame no: 00000001 exp no: 00000001
	Processing frame no: 00000002 exp no: 00000002
	Processing frame no: 00000003 exp no: 00000003
	Processing frame no: 00000004 exp no: 00000004
	Processing frame no: 80000005 exp no: 00000005
	bootstrap: DONE!
	Jump!
	```
	8. The hello_world binary will output the following:
	```console
	Hello World! Oct 31 2019 16:28:03
	Watch the LEDs!
	Try out the switches on the board
	or type anything into the console window.
	The LEDs show the ASCII code of the last character.
	FTDI control changed. Enable JTAG
	```

	Press some keys in the serial console and you should see the ASCII values of the characters sent shown in binary on the LEDs of the Nexsys Video FPGA board.

	To build the software yourself follow the instructions in [Testing the demo design]({{< relref "getting_started_fpga.md#testing-the-demo-design" >}}) (note the software tools must be installed and a clone of the OpenTitan repository made, this is explained in the [Install Instructions]({{< relref "install_instructions" >}})).
	See the [Getting Started on FPGAs Guide]({{< relref "getting_started_fpga.md" >}}) for full instructions how to build your own bitstream.