Install required packages
To follow the guide below the following things must be installed:
- libusb 1.x
- libftdi1 1.x
Under Ubuntu these can be installed with:
$ 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 and extract it.
$OT_TOP refers to the location where it is extracted.
$ 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
$ 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/6 in this example.
cat to view the UART output to see everything that has been output since simulation start.
$ 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 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 (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)
fdiskutility 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
Insert microSD/USB pen to your machine.
fdisk -lto find where the device was mapped. See an example mapping below, where an SD device was mapped as /dev/mmcblk0p1.
$ 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)
Format the device to FAT32 format.
$ mkfs.fat -F 32 /dev/mmcblk0p1
Mount the device by running the following commands:
$ mkdir -p ~/ot-img-mount # Can be a different name $ mount -t vfat /dev/mmcblk0p1 ~/ot-img-mount # Change according to mount/dev
Make sure the device is empty.
ls ~/ot-img-mountshould not print anything.
Copy the bit file image to the storage device.
$ 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.
Program the FPGA with a bitstream from the storage device
- 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”.
- Place JP4 on the pins marked USB/SD.
- Place JP3 according to the selected device (marked either USB or SD).
- Push the PROG button. The BUSY LED (LD14) should be steadily on.
- 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 for more details.
Connect a micro USB cable from your machine to the UART connector (J13) on Nexys Video board.
dmesgto determine which serial port was assigned:
$ 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
Open a serial console (use the device file determined before) and connect. Settings: 115200 baud, 8N1, no hardware or software flow control.
screenneeds to be installed first.
$ screen /dev/ttyUSB0 115200
On the Nexys Video board, press the red button labeled CPU_RESET.
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!
screenpress CTRL+A keys together, then press K, and then confirm exit by pressing y.)
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).
spiflashtool to write the hello_world binary:
$ cd $OT_TOP $ ./sw/host/spiflash/spiflash --input=sw/device/fpga/examples/hello_world/sw.bin
You should see output from the
spiflashtool showing the progress:
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:
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!
The hello_world binary will output the following:
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 (note the software tools must be installed and a clone of the OpenTitan repository made, this is explained in the Install Instructions). See the Getting Started on FPGAs Guide for full instructions how to build your own bitstream.