[doc] Getting started/Instructions updates & fixes
diff --git a/doc/ug/getting_started.md b/doc/ug/getting_started.md
index ad582e9..8709def 100644
--- a/doc/ug/getting_started.md
+++ b/doc/ug/getting_started.md
@@ -6,13 +6,15 @@
Welcome!
-This guide helps you to get started with the lowRISC Comportable chip designs.
+This guide helps you to get started with OpenTitan.
-## Conventions in this guide
+## OpenTitan Repository
-This guide uses the environment variable `$REPO_TOP` to refer to the top-level of the git source tree.
-The master tree is held on GitHub, this should be forked to user trees from which Pull Requests can be made.
-There is a set of [Notes for using GitHub]({{< relref "github_notes.md" >}}).
+The [OpenTitan Repository](https://github.com/lowRISC/opentitan) must be checked out locally.
+If you wish to contribute to OpenTitan you will need to make a fork on GitHub, otherwise you can just locally clone the main repository.
+There is a set of [notes for using GitHub]({{< relref "github_notes.md" >}}) which explains how to work with your own fork.
+
+**Throughout the documentation `$REPO_TOP` refers to the path where the OpenTitan repository is checked out**
## Setup
@@ -37,7 +39,7 @@
Under the sw directory, there are numerous sub-directories each containing code for different purposes.
In general however, software execution can be divided into two execution stages - ROM and embedded memory (currently emulated embedded flash).
-The ROM stage software, built from `sw/boot_ROM` is always run first on all platforms (DV / Verilator / FPGA).
+The ROM stage software, built from `sw/device/boot_rom` is always run first on all platforms (DV / Verilator / FPGA).
In DV / Verilator, both the ROM and embedded memory contents are backdoor loaded into their respective storage, thus the ROM code simply checks for the presence of code and jumps to it.
ROM at the moment does not perform validation of the backdoor loaded code.
diff --git a/doc/ug/getting_started_fpga.md b/doc/ug/getting_started_fpga.md
index fa0e921..330a719 100644
--- a/doc/ug/getting_started_fpga.md
+++ b/doc/ug/getting_started_fpga.md
@@ -26,7 +26,15 @@
Synthesizing a design for a FPGA board is done with the following commands.
The FPGA build will pull in a program to act as the boot ROM.
+This must be built before running the FPGA build.
This is pulled in from the `sw/device/boot_rom` directory (see the `parameters:` section of the `hw/top_earlgrey/top_earlgrey_nexysvideo.core` file).
+
+To build it:
+```console
+$ cd $REPO_TOP
+$ make -C sw/device SW_DIR=boot_rom clean all
+```
+
At the moment there is no check that the `rom.vmem` file is up to date, so it is best to follow the instructions to [Build software]({{< relref "getting_started_sw.md" >}}) and understand the FPGA's overall software flow.
In the following example we synthesize the Earl Grey design for the Nexys Video board using Xilinx Vivado 2018.3.
@@ -58,6 +66,7 @@
Note: `fusesoc pgm` is broken for edalize versions up to (and including) v0.1.3.
You can check the version you're using with `pip3 show edalize`.
+If you have having trouble with programming using the command line, try the GUI.
### Using the Vivado GUI
@@ -110,7 +119,7 @@
* Open a serial console (use the device file determined before) and connect.
Settings: 230400 baud, 8N1, no hardware or software flow control.
```console
- screen /dev/ttyUSB0 230400
+ $ screen /dev/ttyUSB0 230400
```
Note that the Nexsys Video demo program that comes installed on the board runs the UART at 115200 baud;
expect to see garbage characters if that is running.
@@ -161,6 +170,10 @@
$ riscv32-unknown-elf-gdb -ex "target extended-remote :3333" -ex "info reg" sw/device/boot_rom/rom.elf
```
+Note that debug support is not yet mature (see https://github.com/lowRISC/opentitan/issues/574).
+In particular GDB cannot set breakpoints as it can't write to the (emulated) flash memory.
+HW breakpoint support is planned for Ibex to allow breakpointing code in flash.
+
#### Common operations with GDB
Examine 16 memory words in the hex format starting at 0x200005c0
@@ -186,6 +199,16 @@
Use `monitor help` to get a list of supported commands.
+To single-step use `stepi` or `step`
+
+```console
+(gdb) stepi
+```
+
+`stepi` single-steps an instruction, `step` single-steps a line of source code.
+When testing debugging against the hello_world binary it is likely you will break into a delay loop.
+Here the `step` command will seem to hang as it will attempt to step over the whole delay loop with a sequence of single-step instructions which may take quite some time!
+
To change the program which is debugged the `file` command can be used.
This will update the symbols which are used to get information about the program.
It is especially useful in the context of our `rom.elf`, which resides in the ROM region, which will eventually jump to a different executable as part of the flash region.
diff --git a/doc/ug/getting_started_sw.md b/doc/ug/getting_started_sw.md
index 70fd712..04cdc0f 100644
--- a/doc/ug/getting_started_sw.md
+++ b/doc/ug/getting_started_sw.md
@@ -6,7 +6,7 @@
## Building software
-The following commands build the `boot_rom` and `hello_world` binaries:
+The following commands build the `boot_rom` and `hello_world` binaries for FPGA:
```console
$ cd $REPO_TOP
@@ -14,6 +14,8 @@
$ make -C sw/device SW_DIR=examples/hello_world clean all
```
+The `SIM=1` option must be added if building for verilator simulation.
+
The build process produces a variety of output files.
* `.elf`: the linked program in ELF format
diff --git a/doc/ug/getting_started_verilator.md b/doc/ug/getting_started_verilator.md
index 740505d..096b35a 100644
--- a/doc/ug/getting_started_verilator.md
+++ b/doc/ug/getting_started_verilator.md
@@ -30,8 +30,9 @@
```console
$ cd $REPO_TOP
-$ make -C sw/device SIM=1 SW_DIR=boot_rom SW_BUILD_DIR=${ROM_BUILD_DIR} clean all
-$ make -C sw/device SIM=1 SW_DIR=examples/hello_world SW_BUILD_DIR=${SW_BUILD_DIR} clean all
+$ make -C sw/device SIM=1 SW_DIR=boot_rom SW_BUILD_DIR=sim_boot_rom clean all
+$ make -C sw/device SIM=1 SW_DIR=examples/hello_world \
+ SW_BUILD_DIR=sim_hello_world clean all
```
Now the simulation can be run.
@@ -40,8 +41,8 @@
```console
$ cd $REPO_TOP
$ build/lowrisc_systems_top_earlgrey_verilator_0.1/sim-verilator/Vtop_earlgrey_verilator \
- --rominit=${ROM_BUILD_DIR}/rom.vmem \
- --flashinit=${SW_BUILD_DIR}/sw.vmem
+ --rominit=sw/device/sim_boot_rom/rom.vmem \
+ --flashinit=sw/device/sim_hello_world/sw.vmem
```
To stop the simulation press CTRL-c.
@@ -67,6 +68,8 @@
$ screen /dev/pts/11
```
+Note that `screen` will only show output that has been generated after `screen` starts, whilst `cat` will show output that was produced before `cat` started.
+
You can exit `screen` (in the default configuration) by pressing `CTRL-a k` and confirm with `y`.
## See GPIO output
@@ -80,7 +83,7 @@
Passing input is currently not supported.
-## Connect with OpenOCD to the JTAG port
+## Connect with OpenOCD to the JTAG port and use GDB
The simulation includes a "virtual JTAG" port to which OpenOCD can connect using its `remote_bitbang` driver.
All necessary configuration files are included in this repository.
@@ -92,6 +95,16 @@
$ /tools/openocd/bin/openocd -s util/openocd -f board/lowrisc-earlgrey-verilator.cfg
```
+To connect GDB use the following command (noting it needs to be altered to point to the sw binary in use).
+
+```console
+$ riscv32-unknown-elf-gdb -ex "target extended-remote :3333" -ex "info reg" sw/device/sim_hello_world/sw.elf
+```
+
+Note that debug support is not yet mature (see https://github.com/lowRISC/opentitan/issues/574).
+In particular GDB cannot set breakpoints as it can't write to the (emulated) flash memory.
+HW breakpoint support is planned for Ibex to allow breakpointing code in flash.
+
You can also run the debug compliance test suite built into OpenOCD.
```console
@@ -132,45 +145,6 @@
It may be monitored with `tail -f` which conveniently notices when the file is truncated on a new run, so does not need restarting between simulations.
The output consists of a textual "waveform" representing the SPI signals.
-## USB device test interface
-
-
-The simulation contains code to exercise and monitor the USB bus and provide a host interface to allow interaction with the `usbdev` and `usbuart` modules.
-When starting the simulation you should see a message like
-
-```console
-USB: FIFO pipe created at /auto/homes/mdh10/github/opentitan/usb0. Run
-$ cat /auto/homes/mdh10/github/opentitan/usb0
-to observe the output.
-```
-
-The test code currently acts as a host to generate the basic USB control transactions to setup the interface (set the Device ID, read the Device Descriptor), send regular (but not at 1ms spacing) Start-of-Frame packets with incrementing frame number, do an IN bulk transfer from endpoint 1 and occasionally an OUT bulk transfer to endpoint 1.
-The code will finish the simulation after a small number of USB Frames if tracing is enabled and a large number if tracing is not enabled.
-The test code is written directly in the `usbdpi.c` main loop and is fragile with regards to timing. (See [Issue #NNN](https://github.com/lowRISC/opentitan/issues/NNN))
-
-The test code is sufficient to work with the `usbuart` and `hello_world` program and will display the output characters as they arrive in USB packets and send the string `Hi!` to the simulation, which will be echoed and cause the GPIOs to change.
-
-The test code is sufficient to work with the `usbdev` and `hello_usbdev` program and will configure the interface and send the string `Hi!` to the simulation, which will be written to the UART.
-
-The USB mointor can be configured (in the dpi) to output low level bit events from the USB bus, but by default will display higher level packet information. It outputs to a named pipe like the GPIO.
-
-It can be convenient to monitor both the GPIO and USB outputs in the same terminal window.
-
-```console
-$ cd $REPO_TOP
-$ cat gpio0 & cat usb0
-```
-
-Or:
-
-```console
-$ cd $REPO_TOP
-$ tail -f gpio0 usb0
-```
-
-Because the setup process (connect terminal program to `/dev/pts/` for UART, start monitoring the GPIO and USB named pipes) can take some time the `usbdpi` code has a 7 second sleep (with countdown) when it is called for simulation cycle 0.
-This delay starts after all the ptys/pipes/files have been opened but before any action and gives enough time for the correct commands to be started in other terminal windows.
-
## DPI Source
The I/O interfaces described above are implemented using the DPI interface to Verilator.
diff --git a/doc/ug/github_notes.md b/doc/ug/github_notes.md
index 6d20f04..bbce4b4 100644
--- a/doc/ug/github_notes.md
+++ b/doc/ug/github_notes.md
@@ -2,10 +2,12 @@
The OpenTitan source tree is maintained on GitHub in a [monolithic repository](https://github.com/lowRISC/opentitan) called opentitan.
-This file provides some notes on using GitHub for developing in the
-monolithic repository based on notes taken by a relatively inexperienced git
-user. There is much more to using git, a possible next step is to
-reference [Resources to learn Git](https://try.github.io/).
+These notes are for people who intend to contribute back to OpenTitan (based on
+notes taken by a relatively inexperienced git user). If you don't intend to do
+this you can simply clone the main repository, instructions are in [install
+instructions]({{< relref "install_instructions" >}}) and this document can be ignored.There
+is much more to using git, a possible next step is to reference [Resources to
+learn Git](https://try.github.io/).
## Getting a working repository
diff --git a/doc/ug/install_instructions/index.md b/doc/ug/install_instructions/index.md
index cf26832..fe1d281 100644
--- a/doc/ug/install_instructions/index.md
+++ b/doc/ug/install_instructions/index.md
@@ -36,6 +36,19 @@
$ sudo chown $(id -un) /tools
```
+### Clone repository
+
+If you intend to contribute back to OpenTitan you will want your own fork of the repository on GitHub and to work using that, see the [notes for using GitHub]({{< relref "github_notes.md" >}}).
+Otherwise make a simple clone of the main OpenTitan repository.
+
+```console
+$ cd <working-area>
+$ git clone https://github.com/lowRISC/opentitan.git
+```
+
+The repository will be checked out into `<working-area>/opentitan` (this is the
+`$REPO_TOP` path).
+
### Install required software
A number of software packages from the distribution's package manager is required.
@@ -254,5 +267,5 @@
You then need to reload the udev rules:
```console
-# udevadm control --reload
+# sudo udevadm control --reload
```
diff --git a/sw/device/doc/sw_build_flow.md b/sw/device/doc/sw_build_flow.md
index ce6aa76..a95d3d1 100644
--- a/sw/device/doc/sw_build_flow.md
+++ b/sw/device/doc/sw_build_flow.md
@@ -2,8 +2,9 @@
title: "SW build flow"
---
-**The custom Makefile flow has been deprecated in favor of Meson; see sw/README.md for details.**
-**Makefiles will eventually be deleted from SW, and should not be relied upon.**
+**The custom Makefile flow has been deprecated in favor of Meson; see [sw/README]({{< relref "sw/README.md" >}}) for details.**
+**Much of the documentation still uses the Makefile flow which works fine for now.**
+**However the Makefile flow will eventually be deleted from SW, and should not be relied upon.**
## Overview
The centralized Makefile flow attempts to maximize reuse of commonly used
