[doc] Update the User Guide to refer to Meson commands.
Signed-off-by: Miguel Young de la Sota <mcyoung@google.com>
diff --git a/doc/rm/ref_manual_fpga.md b/doc/rm/ref_manual_fpga.md
index 8fb434e..72dcf71 100644
--- a/doc/rm/ref_manual_fpga.md
+++ b/doc/rm/ref_manual_fpga.md
@@ -62,9 +62,10 @@
```console
$ cd ${REPO_TOP}
-$ make -C sw/device SW_DIR=examples/hello_world SW_BUILD_DIR=out clean all
-$ make -C sw/host/spiflash clean all
-$ ./sw/host/spiflash/spiflash --input=sw/device/out/sw.bin
+$ ./meson_init.sh
+$ ninja -C build-out/sw/fpga all
+$ build-bin/sw/host/spiflash/spiflash \
+ --input build-bin/sw/device/fpga/examples/hello_world/hello_world.bin
Running SPI flash update.
Image divided into 6 frames.
diff --git a/doc/ug/getting_started_fpga.md b/doc/ug/getting_started_fpga.md
index f8ac5ce..2fc9a0b 100644
--- a/doc/ug/getting_started_fpga.md
+++ b/doc/ug/getting_started_fpga.md
@@ -5,6 +5,8 @@
Do you want to try out the lowRISC chip designs, but don't have a couple thousand or million dollars ready for an ASIC tapeout?
Running lowRISC designs on an FPGA board can be the answer!
+<!-- TODO: Switch all calls to fusesoc and the Verilated system to refer to Meson, once it supports fusesoc. -->
+
## Prerequisites
To use the lowRISC Comportable designs on an FPGA you need two things:
@@ -30,17 +32,19 @@
To build it:
```console
$ cd $REPO_TOP
-$ make -C sw/device SW_DIR=boot_rom clean all
+$ ./meson_init.sh
+$ ninja -C build-out/sw/fpga sw/device/boot_rom/boot_rom_export
```
-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.
+At the moment, there is no check that the `boot_rom.vmem` file is up to date, so it is best to follow the instructions to [build software]({{< relref "getting_started_sw.md" >}}).
In the following example we synthesize the Earl Grey design for the Nexys Video board using Xilinx Vivado 2018.3.
```console
$ . /tools/xilinx/Vivado/2018.3/settings64.sh
$ cd $REPO_TOP
-$ make -C sw/device SW_DIR=boot_rom clean all
+$ ./meson_init.sh
+$ ninja -C build-out/sw/fpga sw/device/boot_rom/boot_rom_export
$ fusesoc --cores-root . run --target=synth lowrisc:systems:top_earlgrey_nexysvideo
```
diff --git a/doc/ug/getting_started_sw.md b/doc/ug/getting_started_sw.md
index 04cdc0f..eb4dde0 100644
--- a/doc/ug/getting_started_sw.md
+++ b/doc/ug/getting_started_sw.md
@@ -6,21 +6,40 @@
## Building software
-The following commands build the `boot_rom` and `hello_world` binaries for FPGA:
+OpenTitan software is built using [Meson](https://mesonbuild.com).
+However, Meson is not an exact fit for a lot of things OpenTitan does (such as distinguishing between FPGA, ASIC, and simulations), so the setup is a little bit different.
+
+For example, the following commands build the `boot_rom` and `hello_world` binaries for FPGA:
```console
+# Configure the Meson environment.
$ cd $REPO_TOP
-$ make -C sw/device SW_DIR=boot_rom clean all
-$ make -C sw/device SW_DIR=examples/hello_world clean all
+$ ./meson_init.sh
+
+# Build the two targets we care about, specifically.
+$ ninja -C build-out/sw/fpga sw/device/boot_rom/boot_rom_export
+$ ninja -C build-out/sw/fpga sw/device/examples/hello_world/hello_world_export
+
+# Build *everything*.
+$ ninja -C build-out/sw/fpga all
```
-The `SIM=1` option must be added if building for verilator simulation.
+In general, `clean` rules are unnecessary, and Meson will set up `ninja` such that it reruns `meson.build` files which have changed.
-The build process produces a variety of output files.
+Build intermediates will show up in `$REPO_TOP/build-out`, including unlinked object files and libraries, while completed executables are exported to `$REPO_TOP/build-bin`.
+As a rule, you should only ever need to refer to artifacts inside of `build-bin`; the exact structure of `build-out` is subject to change.
+Complete details of these semantics are documented in `util/build_consts.sh`.
-* `.elf`: the linked program in ELF format
-* `.bin`: the linked program as plain binary
-* `.dis`: the disassembled program
-* `.vmem`: a Verilog memory file which can be read by `$readmemh()` in Verilog code
+The locations of `build-{out,bin}` can be controled by setting the `$BUILD_ROOT` enviromnent variable, which defaults to `$REPO_TOP`.
-Please see [SW build flow]({{< relref "sw/device/doc/sw_build_flow.md" >}}) for more details.
+`./meson_init.sh` itself is idempotent, but this behavior can be changed with additional flags; see `./meson_init.sh` for more information.
+For this reason, most examples involving Meson will include a call to `./meson_init.sh`, but you will rarely need to run it more than once per checkout.
+
+Building an executable `foo` destined to run on an OpenTitan device (i.e., under `sw/device`) will output the following files under `build-bin/sw/device`:
+* `foo.elf`: the linked program, in ELF format.
+* `foo.bin`: the linked program, as a plain binary with ELF debug information removed.
+* `foo.dis`: the disassembled program with inline source code.
+* `foo.vmem`: a Verilog memory file which can be read by `$readmemh()` in Verilog code.
+
+Building an executable destined to run on a host machine (i.e., under `sw/host`) will output a host excecutable under `build-bin/sw/host`, which can be run directly.
+Currently, each "platform" (`fpga`, `sim-verolator`, etc) have their own copies of all host targets; this is a limitation of our Meson setup, and they are otherwise indistinguishable.
\ No newline at end of file
diff --git a/doc/ug/getting_started_verilator.md b/doc/ug/getting_started_verilator.md
index abc7dcb..0654915 100644
--- a/doc/ug/getting_started_verilator.md
+++ b/doc/ug/getting_started_verilator.md
@@ -5,6 +5,8 @@
Verilator is a cycle-accurate simulation tool.
It translates synthesizable Verilog code into a simulation program in C++, which is then compiled and executed.
+<!-- TODO: Switch all calls to fusesoc and the Verilated system to refer to Meson, once it supports fusesoc. -->
+
## Prerequisites
_Make sure you followed the install instructions to [prepare the system]({{< relref "install_instructions#system-preparation" >}}) and to install the [software development tools]({{< relref "doc/ug/install_instructions#software-development" >}}) and [Verilator]({{< relref "install_instructions#verilator" >}})._
@@ -23,16 +25,13 @@
By default, the system will first execute out of ROM and then jump to flash.
A program needs to be built for each until ROM functionality for code download is ready.
-For that purpose compile the demo program with "simulation" settings, which adjusts the frequencies to better match the simulation speed.
-In the instructions below, `SW_DIR` is a requirement argument, while `SW_BUILD_DIR` is not a required argument.
-If `SW_BUILD_DIR` argument is not supplied, the default location of the of output files are in `SW_DIR`
-Please see [SW build flow]({{< relref "sw/device/doc/sw_build_flow" >}}) for more details.
+For that purpose compile the demo program with "simulation" settings, which adjusts the frequencies to better match the simulation speed.
+For more information on building software targets refer to the [Software Getting Started Guide]({{< relref "getting_started_sw.md" >}}).
```console
$ cd $REPO_TOP
-$ 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
+$ ./meson_init.sh
+$ ninja -C build-out/sw/device/sim-verilator all
```
Now the simulation can be run.
@@ -41,8 +40,8 @@
```console
$ cd $REPO_TOP
$ build/lowrisc_systems_top_earlgrey_verilator_0.1/sim-verilator/Vtop_earlgrey_verilator \
- --meminit=rom,sw/device/sim_boot_rom/rom.elf \
- --meminit=flash,sw/device/sim_hello_world/sw.elf
+ --meminit=rom,build-bin/sw/device/sim-verilator/boot_rom/boot_rom.elf \
+ --meminit=flash,build-bin/sw/device/sim-verilator/examples/hello_world/hello_world.elf
```
To stop the simulation press CTRL-c.
diff --git a/sw/README.md b/sw/README.md
index 2c5236c..e0dd372 100644
--- a/sw/README.md
+++ b/sw/README.md
@@ -4,11 +4,14 @@
## Building
-OpenTitan software is built using [Meson](https://mesonbuild.com).
-For example, to build the OpenTitan executable located at `device/examples/hello_world/hello_world.bin`, run the following commands:
-```sh
-cd "${REPO_TOP}"
-./meson_init.sh -f
-ninja -C build-out/sw/${TARGET} sw/device/examples/hello_world/hello_world.bin
+OpenTitan software is built using [Meson](https://mesonbuild.com), although OpenTitan's project structure is sufficiently ideosyncratic that we use a custom workflow.
+
+For example, to build the OpenTitan executable located at `sw/device/examples/hello_world` for FPGA, run the following commands:
+```console
+$ cd "$REPO_TOP"
+$ ./meson_init.sh
+$ ninja -C build-out/sw/fpga sw/device/examples/hello_world/hello_world_export
```
-`$TARGET` should be one of `sim-verilator` or `fpga`, depending on whether the executable should be built to run under simulation or on a phyisical FPGA, respectively.
+
+The resulting binaries will be located at `build-bin/sw/device/fpga/examples/hello_world`. For more information, check out [the relevant User Guide](../doc/ug/getting_started_sw.md).
+
diff --git a/sw/device/doc/sw_build_flow.md b/sw/device/doc/sw_build_flow.md
deleted file mode 100644
index a95d3d1..0000000
--- a/sw/device/doc/sw_build_flow.md
+++ /dev/null
@@ -1,125 +0,0 @@
----
-title: "SW build flow"
----
-
-**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
-variables and rules among various software build targets (boot_rom, lib and
-main software tests.
-
-## Terminology / Some Make variables of interest
-- **SW_ROOT_DIR**: The root directory for all of opentitan SW is sw/ and is
- indicated in the Make flow as `SW_ROOT_DIR`.
-
-- **sw**: A 'software' (abbreviated as SW) is considered to be the top level
- SW application that is built through the final `vmem` image. For most tests, the
- targets are boot_rom and SW test application. Variables prefixed with `SW_`
- pertain to building the target SW application.
-
-- **SW_SRCS**: The sources needed for compiling SW are indicated using the
- variable `SW_SRCS`.
-
-- **SW_DIR**: The directory containing the SW sources is indicated using the
- variable `SW_DIR`. Note that `SW_DIR` is only the partial directory starting
- from the `SW_ROOT_DIR`. It is **mandatory** to set this variable on the command
- line.
-
-- **SW_NAME**: A `SW_DIR` could contain one or more unique SW build targets.
- This variable is used to indicate which one is to be built, on the command
- line.
-
-- **lib**: This refers to the library code generated from the shared common
- sources. These sources are currently placed in `sw/device/lib`, `sw/device/util` and
- `sw/device/exts` directories. More such directories can be added in future.
- Also, this is one of the goals of the make flow.
-
-- **LIB_SRCS**: This is a list of all common / shared sources compiled into the
- lib archive. These include all of the required sources indicated in the
- directories listed above.
-
-- **SW_BUILD_DIR**: This variable is the output directory to place all the
- generated output files. This includes object files, intermediate dependency
- files, generated linker scripts, elf, binary image, generated register header
- files, disassembled code, vmem, among other things. By default, this is set to
- the `SW_DIR`. It can be overridden on the command line. During compilation, the
- `SW_BUILD_DIR/lib` directory is created and is used to put all the object files
- and the archive file associated with `lib`.
-
-The variables listed here are not exhaustive, but bare minimum to indicate to
-the users the most typical use cases. Users are encouraged to read through
-the files listed below for more details.
-
-## Organization
-The SW device build Makefiles are organized as follows:
-
-- **`sw/device/Makefile`**: The top level SW build Makefile (`sw/device/Makefile`). All of the
- sub-make files are included directly or indirectly into this. This is the
- starting point for compiling any target.
-
-- **`sw/device/opts.mk`**: All commonly used Make variables in one place. This sub-make
- file is also used to check if certain switches are enabled and further modify /
- customize the flow for target being built. An example of this is using the `TARGET`
- variable to change how SW is built for DV vs FPGA / Verilator / production SW.
-
-- **`sw/device/rules.mk`**: All rules for generating all the outputs in one place.
-
-These three form the *base-make files* for the SW build. Any directory containing
-sources for building the SW needs to have an associated `srcs.mk` sub-make file
-within that directory. These `srcs.mk` files are then required to be added to the
-top level SW build Makefile.
-
-- **`device/exts/common/srcs.mk`**: Additional extended common sources. This includes
- the default `CRT_SRCS` and the `LINKER_SCRIPT` which can be overridden for
- sw specific requirements.
-
-- **`device/lib/srcs.mk`**: Directory containing sources to compile the lib elements and
- its dependencies.
-
-- **`$(SW_DIR)/srcs.mk`**: This sub-make file contains sources for building a SW
- target is indicated using `SW_NAME`. This file is included in the top level
- SW build Makefile. Setting the **`SW_DIR` and `SW_NAME` correctly is
- required for building the desired image**. The existing variables in
- `opts.mk` can be overridden or appended to in this sub-make file to further
- customize the build target based on need. If this directory contains only a
- single SW build target, then `SW_NAME` can be set to the same name (typically
- same name as the directory and the C source) in this file. In that case, indicating
- `SW_NAME` on the command line is not required.
-
-- **`device/exts/common/srcs.mk`**: Additional extended common sources. This includes
- the default `CRT_SRCS` and the `LINKER_SCRIPT` which can be overridden for
- sw specific requirements.
-
-## How to build SW
-The examples indicated below assume that the present working directory is
-`$(SW_ROOT_DIR)/device`. As indicated in the previous sections, `SW_DIR` and `SW_NAME` are
-mandatory variables that need to be set correctly on the command line. `SW_NAME`
-is optional if `SW_DIR` has only one SW target and `SW_NAME` is set in
-`$(SW_DIR)/srcs.mk` file. `SW_BUILD_DIR` is optional.
-
-Build boot_rom:
-```console
-$ make SW_DIR=boot_rom SW_NAME=boot_rom
-```
-
-This will build the boot_rom image in the device/boot_rom directly itself. SW_NAME in
-device/boot_rom/srcs.mk is already set to boot_rom, so there is no need to specify it
-on the command line.
-
-- Build the boot_rom in a separate build directory:
-```console
-$ make SW_DIR=boot_rom SW_BUILD_DIR=path/to/scratch
-```
-
-- Build hello_world test:
-```console
-$ make SW_DIR=examples/hello_world SW_NAME=hello_world SW_BUILD_DIR=path/to/scratch
-```
-
-- Build sha256 test:
-```console
-$ make SW_DIR=tests/hmac SW_NAME=sha256_test
-```
diff --git a/sw/host/spiflash/README.md b/sw/host/spiflash/README.md
index 26bb2dd..af32b7c 100644
--- a/sw/host/spiflash/README.md
+++ b/sw/host/spiflash/README.md
@@ -20,8 +20,8 @@
```console
$ cd ${REPO_TOP}
-$ ./meson_init.sh -f
-$ ninja -C build-fpga sw/host/spiflash/spiflash
+$ ./meson_init.sh
+$ ninja -C build-out/sw/fpga sw/host/spiflash/spiflash_export
```
## Setup instructions for Verilator and FPGA
@@ -29,18 +29,19 @@
## Build boot ROM and demo program
-_If building for verilator, build in `build-verilator` instead._
+_If building for verilator, build in `build-out/sw/sim-verilator` instead._
Build `boot_rom`:
```console
$ cd ${REPO_TOP}
-$ ninja -C build-fpga sw/device/boot_rom/boot_rom.vmem
+$ ./meson_init.sh
+$ ninja -C build-out/sw/fpga sw/device/boot_rom/boot_rom_export
```
Build the `hello_world` program:
```console
$ cd ${REPO_TOP}
-$ ninja -C build-fpga sw/device/examples/hello_world/hello_world.bin
+$ ninja -C build-out/sw/fpga sw/device/examples/hello_world/hello_world_export
```
## Run the tool in Verilator
@@ -50,7 +51,7 @@
```console
$ cd ${REPO_TOP}
$ build/lowrisc_systems_top_earlgrey_verilator_0.1/sim-verilator/Vtop_earlgrey_verilator \
- --rominit=build-verilator/sw/boot_rom/boot_rom.vmem
+ --rominit build-bin/sw/device/sim-verilator/boot_rom/boot_rom.vmem
```
Run spiflash. In this example we use SPI device `/dev/pts/3` as an example.
@@ -58,9 +59,9 @@
```console
$ cd ${REPO_TOP}
-$ build-verilator/sw/host/spiflash/spiflash \
- --input=build-verilator/sw/examples/hello_world/hello_world.bin \
- --verilator=/dev/pts/3
+$ build-bin/sw/host/spiflash/spiflash \
+ --input build-bin/sw/device/sim-verilator/examples/hello_world/hello_world.bin \
+ --verilator /dev/pts/3
```
## Run the tool in FPGA
@@ -72,6 +73,6 @@
```console
$ cd ${REPO_TOP}
-$ build-fpga/sw/host/spiflash/spiflash \
- --input=build-fpga/sw/examples/hello_world/hello_world.bin
+$ build-bin/sw/host/spiflash/spiflash \
+ --input build-bin/sw/device/fpga/examples/hello_world/hello_world.bin
```
