[doc] Refactored main "Getting Started" page to make instructions easier to follow for new users.
Signed-off-by: Timothy Trippel <ttrippel@google.com>
diff --git a/_index.md b/_index.md
index 7bf513e..da6199e 100644
--- a/_index.md
+++ b/_index.md
@@ -7,12 +7,12 @@
OpenTitan is administered by lowRISC CIC as a collaborative [project]({{< relref "doc/project" >}}) to produce high quality, open IP for instantiation as a full-featured product.
This repository exists to enable collaboration across partners participating in the OpenTitan project.
-To get started using or contributing to the OpenTitan codebase, see the
-[list of user guides]({{< relref "doc/ug" >}}).
-For details on coding styles or how to use our project-specific tooling, see the
-[reference manuals]({{< relref "doc/rm" >}}).
-[This page]({{< relref "hw" >}})
-contains technical documentation on the SoC, the Ibex processor core, and the individual IP blocks.
+## Getting Started
+
+To get started with OpenTitan, see the [Getting Started]({{< relref "doc/ug/getting_started" >}}) page.
+For additional resources when working with OpenTitan, see the [list of user guides]({{< relref "doc/ug" >}}).
+For details on coding styles or how to use our project-specific tooling, see the [reference manuals]({{< relref "doc/rm" >}}).
+Lastly, the [Hardware Dashboard page]({{< relref "hw" >}}) contains technical documentation on the SoC, the Ibex processor core, and the individual IP blocks.
For questions about how the project is organized, see the [project]({{< relref "doc/project" >}}) landing spot for more information.
## Repository Structure
diff --git a/doc/ug/design.md b/doc/ug/design.md
index bf4ac1f..84a3c9e 100644
--- a/doc/ug/design.md
+++ b/doc/ug/design.md
@@ -196,10 +196,10 @@
There is an over-arching build file in the repository under `hw/Makefile` that builds all of the `regtool` content.
This is used by an Azure Pipelines pre-submit check script to ensure that the source files produce a generated file that is identical to the one being submitted.
-## Getting Started with a Design
+## Getting Started Designing Hardware
The process for getting started with a design involves many steps, including getting clarity on its purpose, its feature set, authorship, documentation, etc.
-These are discussed in the [Getting Started with a Design]({{< relref "getting_started_design.md" >}}) document.
+These are discussed in the [Getting Started Designing Hardware]({{< relref "getting_started_hw_design.md" >}}) document.
## FPGA vs Silicon
diff --git a/doc/ug/dv_methodology/index.md b/doc/ug/dv_methodology/index.md
index 4bce6db..833ee5f 100644
--- a/doc/ug/dv_methodology/index.md
+++ b/doc/ug/dv_methodology/index.md
@@ -177,7 +177,7 @@
The chip level DV effort is aimed at ensuring that all of the IPs are integrated correctly into the chip.
For IPs that are pre-verified sub-modules, we perform [integration testing](#integration-testing).
These are simple functional tests written in C which are cross-compiled and run natively on the Ibex core.
-The software compilation flow to enable this is explained in further detail in the [getting started with SW]({{< relref "getting_started_sw.md" >}}) document.
+The software compilation flow to enable this is explained in further detail in the [Getting Started Building SW]({{< relref "getting_started_build_sw.md" >}}) document.
Further, there is a mechanism for the C test running on the CPU to signal the SystemVerilog testbench the test pass or fail indication based on the observed DUT behavior.
We also provide an environment knob to 'stub' the CPU and use a TL agent to drive the traffic via the CPU's data channel instead, in cases where more intensive testing is needed.
<!-- TODO: add link to chip DV document -->
diff --git a/doc/ug/getting_started.md b/doc/ug/getting_started.md
deleted file mode 100644
index d89796f..0000000
--- a/doc/ug/getting_started.md
+++ /dev/null
@@ -1,49 +0,0 @@
----
-title: "Getting Started"
----
-
-Welcome!
-
-This guide helps you to get started with OpenTitan.
-
-## OpenTitan Repository
-
-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
-
-You can either follow the [install instructions]({{< relref "install_instructions" >}}) from start to end to install all software required to simulate the design with Verilator and build a bitstream for an FPGA with Xilinx Vivado or check the corresponding [design description]({{< relref "getting_started.md#choose-a-design-to-build" >}}) for install requirements.
-
-## Choose a design to build
-
-The code base contains multiple top-level designs, which can be synthesized or compiled for different targets.
-A target can be a specific FPGA board, an ASIC technology, or a simulation tool.
-The hardware you need to obtain and the tools you need to install depend on the chosen top-level design and the target.
-
-In order to continue, choose a system from the [List of Systems]({{< relref "/doc/ug/system_list.md" >}}).
-Read the design documentation for the requirements on the specific design/target combination, and then follow the appropriate steps below.
-
-* [Build software]({{< relref "getting_started_sw.md" >}})
-* [Getting started with Verilator]({{< relref "getting_started_verilator.md" >}})
-* [Getting started on FPGAs]({{< relref "getting_started_fpga.md" >}})
-
-## Understanding device software flow
-This section discusses the general software operating flow.
-
-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/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.
-
-On FPGA, we do not backdoor load the embedded memory.
-Instead, the ROM code proceeds through a code download process where a [host]({{< relref "/sw/host/spiflash/README.md" >}}) feeds an image frame by frame.
-The ROM code then integrity checks each received image and programs it into the embedded memory.
-At the conclusion of this process, the ROM then jumps to the newly downloaded executable code.
-Again, just like the DV / Verilator case, there is currently no additional validation of the downloaded code.
-That feature is expected to be added later.
diff --git a/doc/ug/getting_started/getting_started_workflow.svg b/doc/ug/getting_started/getting_started_workflow.svg
new file mode 100644
index 0000000..6128688
--- /dev/null
+++ b/doc/ug/getting_started/getting_started_workflow.svg
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg xmlns:xl="http://www.w3.org/1999/xlink" xmlns="http://www.w3.org/2000/svg" version="1.1" xmlns:dc="http://purl.org/dc/elements/1.1/" viewBox="63 184 468 472" width="468" height="472">
+ <defs>
+ <font-face font-family="Helvetica Neue" font-size="16" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="951.9958" descent="-212.99744" font-weight="400">
+ <font-face-src>
+ <font-face-name name="HelveticaNeue"/>
+ </font-face-src>
+ </font-face>
+ <font-face font-family="Helvetica Neue" font-size="12" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="951.9958" descent="-212.99744" font-weight="400">
+ <font-face-src>
+ <font-face-name name="HelveticaNeue"/>
+ </font-face-src>
+ </font-face>
+ <marker orient="auto" overflow="visible" markerUnits="strokeWidth" id="FilledArrow_Marker" stroke-linejoin="miter" stroke-miterlimit="10" viewBox="-1 -3 7 6" markerWidth="7" markerHeight="6" color="black">
+ <g>
+ <path d="M 4.8 0 L 0 -1.8 L 0 1.8 Z" fill="currentColor" stroke="currentColor" stroke-width="1"/>
+ </g>
+ </marker>
+ <font-face font-family="Helvetica Neue" font-size="18" panose-1="2 0 5 3 0 0 0 2 0 4" units-per-em="1000" underline-position="-100" underline-thickness="50" slope="0" x-height="517" cap-height="714" ascent="951.9958" descent="-212.99744" font-weight="400">
+ <font-face-src>
+ <font-face-name name="HelveticaNeue"/>
+ </font-face-src>
+ </font-face>
+ </defs>
+ <metadata> Produced by OmniGraffle 7.18.5\n2021-07-14 00:17:50 +0000</metadata>
+ <g id="Canvas_1" stroke="none" stroke-opacity="1" stroke-dasharray="none" fill="none" fill-opacity="1">
+ <title>Canvas 1</title>
+ <rect fill="white" x="63" y="184" width="468" height="472"/>
+ <g id="Canvas_1_Layer_1">
+ <title>Layer 1</title>
+ <g id="Graphic_44">
+ <rect x="64.2" y="184.8" width="465.8" height="469.8" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ </g>
+ <g id="Graphic_43">
+ <path d="M 229.56 285 L 367.56 285 L 367.56 605.9512 L 229.56 605.9512 Z" stroke="#310067" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="2.0,2.0" stroke-width=".5"/>
+ </g>
+ <g id="Line_39">
+ <line x1="298.5" y1="269" x2="298.5" y2="294.5" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
+ </g>
+ <g id="Line_38">
+ <line x1="247.25826" y1="271.252" x2="199.55174" y2="294.5" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
+ </g>
+ <g id="Graphic_22">
+ <path d="M 79.25 285 L 217.25 285 L 217.25 605.9512 L 79.25 605.9512 Z" stroke="#310067" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="2.0,2.0" stroke-width=".5"/>
+ </g>
+ <g id="Graphic_23">
+ <path d="M 379.87 285.388 L 517.87 285.388 L 517.87 605.5632 L 379.87 605.5632 Z" stroke="#310067" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="2.0,2.0" stroke-width=".5"/>
+ </g>
+ <g id="Graphic_3">
+ <rect x="184.144" y="221.252" width="228.832" height="50" fill="#cbbcff"/>
+ <rect x="184.144" y="221.252" width="228.832" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(189.144 229.86)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="71.032" y="15">Setup Env. </tspan>
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="86.634" y="29.447998">(Manual)</tspan>
+ </text>
+ </g>
+ <g id="Graphic_4">
+ <rect x="389.5" y="294.5" width="118.5" height="50" fill="white"/>
+ <rect x="389.5" y="294.5" width="118.5" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(394.5 303.108)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="20.618" y="15">Build HW </tspan>
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="43.252" y="29.447998">(DV)</tspan>
+ </text>
+ </g>
+ <g id="Graphic_6">
+ <rect x="89" y="521" width="118.5" height="50" fill="#cbbbff"/>
+ <rect x="89" y="521" width="118.5" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(94 529.608)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="23.13" y="15">Simulate</tspan>
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="29.368" y="29.447998">(Verilator)</tspan>
+ </text>
+ </g>
+ <g id="Graphic_7">
+ <rect x="389" y="521" width="118.5" height="50" fill="white"/>
+ <rect x="389" y="521" width="118.5" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(394 529.608)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="23.13" y="15">Simulate</tspan>
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="11.362" y="29.447998">(Synopsys VCS)</tspan>
+ </text>
+ </g>
+ <g id="Graphic_9">
+ <rect x="239.25" y="294.5" width="118.5" height="50" fill="white"/>
+ <rect x="239.25" y="294.5" width="118.5" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(244.25 303.108)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="20.618" y="15">Build HW </tspan>
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="35.368" y="29.447998">(FPGA)</tspan>
+ </text>
+ </g>
+ <g id="Graphic_10">
+ <rect x="89" y="294.5" width="118.5" height="50" fill="#cbbbff"/>
+ <rect x="89" y="294.5" width="118.5" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(94 303.108)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="20.618" y="15">Build HW</tspan>
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="29.368" y="29.447998">(Verilator)</tspan>
+ </text>
+ </g>
+ <g id="Graphic_11">
+ <rect x="89" y="221.252" width="88.24199" height="50" fill="#feffff"/>
+ <rect x="89" y="221.252" width="88.24199" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(94 229.86)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x=".7369984" y="15">Setup Env. </tspan>
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="9.900998" y="29.447998">(Container)</tspan>
+ </text>
+ </g>
+ <g id="Graphic_13">
+ <rect x="239.25" y="445.5" width="118.5" height="50" fill="white"/>
+ <rect x="239.25" y="445.5" width="118.5" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(244.25 461.276)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="21.354" y="15">Load SW</tspan>
+ </text>
+ </g>
+ <g id="Graphic_16">
+ <rect x="238.75" y="521" width="118.5" height="50" fill="white"/>
+ <rect x="238.75" y="521" width="118.5" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(243.75 536.776)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="39.874" y="15">Run</tspan>
+ </text>
+ </g>
+ <g id="Graphic_18">
+ <text transform="translate(468.218 586.6152)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="0" y="11">DV Flow</tspan>
+ </text>
+ </g>
+ <g id="Graphic_19">
+ <text transform="translate(139.83 586.2272)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="0" y="11">Verilator Flow</tspan>
+ </text>
+ </g>
+ <g id="Graphic_20">
+ <text transform="translate(302.08 586.2272)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="12" font-weight="400" fill="black" x="0" y="11">FPGA Flow</tspan>
+ </text>
+ </g>
+ <g id="Graphic_24">
+ <text transform="translate(206.689 620.7903)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="0" y="15">= recommended for new users</tspan>
+ </text>
+ </g>
+ <g id="Graphic_25">
+ <rect x="165.479" y="615.7903" width="28" height="28.447998" fill="#cbf"/>
+ <rect x="165.479" y="615.7903" width="28" height="28.447998" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ </g>
+ <g id="Line_32">
+ <line x1="148.25" y1="344.5" x2="148.25" y2="508.1" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
+ </g>
+ <g id="Line_33">
+ <line x1="298.5" y1="344.5" x2="298.5" y2="445.5" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
+ </g>
+ <g id="Line_34">
+ <line x1="298.33444" y1="495.5" x2="298.251" y2="508.1003" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
+ </g>
+ <g id="Line_35">
+ <line x1="448.6948" y1="344.5" x2="448.33366" y2="508.10003" marker-end="url(#FilledArrow_Marker)" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
+ </g>
+ <g id="Line_37">
+ <line x1="138.28462" y1="271.252" x2="143.08638" y2="294.5" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-dasharray="4.0,4.0" stroke-width="2"/>
+ </g>
+ <g id="Line_41">
+ <line x1="349.8208" y1="271.252" x2="397.4892" y2="294.5" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="2"/>
+ </g>
+ <g id="Graphic_42">
+ <text transform="translate(170.479 189.8)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="18" font-weight="400" fill="black" x="2.502" y="17">Getting Started with OpenTitan </tspan>
+ </text>
+ </g>
+ <g id="Graphic_5">
+ <rect x="89" y="370" width="419" height="50" fill="#cbf"/>
+ <rect x="89" y="370" width="419" height="50" stroke="black" stroke-linecap="round" stroke-linejoin="round" stroke-width="1"/>
+ <text transform="translate(94 385.776)" fill="black">
+ <tspan font-family="Helvetica Neue" font-size="16" font-weight="400" fill="black" x="171.46" y="15">Build SW</tspan>
+ </text>
+ </g>
+ </g>
+ </g>
+</svg>
diff --git a/doc/ug/getting_started/index.md b/doc/ug/getting_started/index.md
new file mode 100644
index 0000000..5d14a89
--- /dev/null
+++ b/doc/ug/getting_started/index.md
@@ -0,0 +1,73 @@
+---
+title: "Getting Started"
+---
+
+Welcome!
+
+This guide will help you get OpenTitan up and running by instructing you how to:
+
+1. setup an adequate build/testing environment on your machine,
+2. clone the OpenTitan Git repository, and
+3. build OpenTitan software/hardware for the target of your choosing.
+
+
+
+As shown in the diagram above, we currently support multiple build targets and workflows, including: Verilator, FPGA, and DV.
+However, if you are new to the project, we recommend simulation with Verilator, as this uses only free EDA tools, and does not require any additional hardware.
+
+## Environment Setup
+
+There are two choices for setting up an OpenTitan environment:
+1. \[Supported\] [manual installation]({{< relref "install_instructions" >}}), or
+2. \[Experimental\] [provided Docker container]({{< relref "/util/container/README.md" >}}).
+
+While the first option is the only one currently supported, the second option is the quickest to get running.
+If you plan on being a long term user of the project, and/or contributer, we recommend the first (manual installation) option.
+Alternatively, if your goal is to get a Verilator simulation up and running as quickly as possible, you may find it easier to try the second (container) option.
+
+## Cloning the OpenTitan Repository
+
+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 are a set of [notes for using GitHub]({{< relref "github_notes.md" >}}) which explains how to work with your own fork.
+
+***Note: throughout the documentation `$REPO_TOP` refers to the path where the OpenTitan repository is checked out.***
+
+## Building OpenTitan Software/Hardware
+
+Once you have setup a suitable environment and cloned the OpenTitan source code, you need to choose a top-level OpenTitan design to build.
+The code base contains multiple [top-level designs]({{< relref "/doc/ug/system_list.md" >}}), which can be synthesized or simulated.
+A target can be a simulation tool, an FPGA board, or an ASIC technology.
+We currently support two out of the three aformentioned target types (i.e., simulation tools and FPGA), as described in this table:
+| Target| Type | Primary Purpose | EDA Licenses Required? | Extra Hardware Required? | Link |
+|-------|------|-----------------|------------------------|--------------------------|------|
+| Verilator | Simulation Tool | SW Testing | no | no | [Getting Started with Verilator]({{< relref "getting_started_verilator.md" >}})|
+| FPGA | FPGA Board | Testing & Evaluation | maybe (FPGA size dependent) | yes | [Getting Started on FPGAs]({{< relref "getting_started_fpga.md" >}}) |
+| DV | Simulation Tool | HW Verification | yes | no | [Getting Started with Design Verification]({{< relref "getting_started_dv.md" >}}) |
+
+The instructions on how to compile the required demo software, and synthesize the main top-level hardware design ([Earl Grey]({{< relref "/hw/top_earlgrey" >}})) for each target are linked above in the table.
+**Again, if you are new to the project, we recommend starting with the Verilator target, as this uses only free EDA tools, and does not require any additional hardware.**
+
+## Additional Resources
+
+If you have made it this far, congratulations!
+Hopefully you got a "Hello World!" demo running on OpenTitan using either the Verilator or FPGA targets.
+As you may have guessed, there are several other pieces of hardware and software, besides a "Hello World!" demo, that are being actively developed for the OpenTitan project.
+If you are interested in these, check out the additional resources below.
+
+### General
+* [Directory Structure]({{< relref "directory_structure.md" >}})
+* [GitHub Notes]({{< relref "github_notes.md" >}})
+* [Building Documentation]({{< relref "documentation.md" >}})
+* [Design Methodology within OpenTitan]({{< relref "design.md" >}})
+
+### Hardware
+* [Getting Started Designing Hardware]({{< relref "getting_started_hw_design.md" >}})
+* [OpenTitan Hardware]({{< relref "/hw" >}})
+
+### Software
+* [Getting Started Building Software]({{< relref "getting_started_build_sw.md" >}})
+* [OpenTitan Software]({{< relref "/sw" >}})
+* [Writing and Building Software for OTBN]({{< relref "otbn_sw.md" >}})
+* [Rust for Embedded C Programmers]({{< relref "rust_for_c.md" >}})
+
diff --git a/doc/ug/getting_started_sw.md b/doc/ug/getting_started_build_sw.md
similarity index 98%
rename from doc/ug/getting_started_sw.md
rename to doc/ug/getting_started_build_sw.md
index f435f91..e3348c8 100644
--- a/doc/ug/getting_started_sw.md
+++ b/doc/ug/getting_started_build_sw.md
@@ -1,5 +1,5 @@
---
-title: Build Software
+title: Getting Started Building Software
---
## Prerequisites
diff --git a/doc/ug/getting_started_dv.md b/doc/ug/getting_started_dv.md
index 47a9d38..f72436c 100644
--- a/doc/ug/getting_started_dv.md
+++ b/doc/ug/getting_started_dv.md
@@ -1,5 +1,5 @@
---
-title: "Getting Started with an OpenTitan Design Verification"
+title: "Getting Started with Design Verification"
---
This document aims to enable a contributor to get started with a design verification (DV) effort within the OpenTitan project.
diff --git a/doc/ug/getting_started_fpga.md b/doc/ug/getting_started_fpga.md
index c146d2b..11e5d8f 100644
--- a/doc/ug/getting_started_fpga.md
+++ b/doc/ug/getting_started_fpga.md
@@ -1,5 +1,5 @@
---
-title: "Getting started on FPGAs"
+title: "Getting Started on FPGAs"
---
Do you want to try out OpenTitan, but don't have a couple thousand or million dollars ready for an ASIC tapeout?
diff --git a/doc/ug/getting_started_design.md b/doc/ug/getting_started_hw_design.md
similarity index 98%
rename from doc/ug/getting_started_design.md
rename to doc/ug/getting_started_hw_design.md
index e13bf5e..8a80393 100644
--- a/doc/ug/getting_started_design.md
+++ b/doc/ug/getting_started_hw_design.md
@@ -1,5 +1,5 @@
---
-title: "Getting Started with an OpenTitan Hardware Design"
+title: "Getting Started Designing Hardware"
---
This document aims to clarify how to get started with a hardware design within the OpenTitan project.
diff --git a/doc/ug/getting_started_verilator.md b/doc/ug/getting_started_verilator.md
index 46910ec..fb1240b 100644
--- a/doc/ug/getting_started_verilator.md
+++ b/doc/ug/getting_started_verilator.md
@@ -1,5 +1,5 @@
---
-title: Getting started with Verilator
+title: Getting Started with Verilator
---
## About Verilator
@@ -30,7 +30,7 @@
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.
-For more information on building software targets refer to the [Software Getting Started Guide]({{< relref "getting_started_sw.md" >}}).
+For more information on building software targets refer to the [Getting Started Building Software guide]({{< relref "getting_started_build_sw.md" >}}).
```console
$ cd $REPO_TOP
