Restructure documentation

Restructure the existing documentation to group the content by intended
audience. This produces four sections:

* An introduction section, relevant to "newcomers" to Ibex.
* An user guide, intended for hardware designers (integrators) and
  software developers who want to integrate Ibex, and develop software
  for it.
* A reference guide, which provides background information on the
  design. This section is essential when working on Ibex, and also
  documents our design decisions.
* A developer guide aimed at people modifying Ibex itself. It consists
  mostly of process and tool documentation: how to run the verification
  after a code change, how to use GitHub, etc.

This commit is large, but text is mostly unchanged. A couple of
introductions and tables of content were added, but no significant
changes to the text have been made. These will be done in follow-ups.

Signed-off-by: Philipp Wagner <phw@lowrisc.org>

doc/01_overview/compliance.rst

@@ -0,0 +1,62 @@
+Standards Compliance
+====================
+
+Ibex is a standards-compliant 32 bit RISC-V processor.
+It follows these specifications:
+
+* `RISC-V Instruction Set Manual, Volume I: User-Level ISA, document version 20190608-Base-Ratified (June 8, 2019) <https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMFDQC-and-Priv-v1.11/riscv-spec-20190608.pdf>`_
+* `RISC-V Instruction Set Manual, Volume II: Privileged Architecture, document version 20190608-Base-Ratified (June 8, 2019) <https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMFDQC-and-Priv-v1.11/riscv-privileged-20190608.pdf>`_.
+  Ibex implements the Machine ISA version 1.11.
+* `RISC-V External Debug Support, version 0.13.2 <https://content.riscv.org/wp-content/uploads/2019/03/riscv-debug-release.pdf>`_
+* `RISC-V Bit Manipulation Extension, version 0.92 (draft from November 8, 2019) <https://github.com/riscv/riscv-bitmanip/blob/master/bitmanip-0.92.pdf>`_
+
+Many features in the RISC-V specification are optional, and Ibex can be parametrized to enable or disable some of them.
+
+Ibex can be parametrized to support either of the following two instruction sets.
+
+* The RV32I Base Integer Instruction Set, version 2.1
+* The RV32E Base Integer Instruction Set, version 1.9 (draft from June 8, 2019)
+
+In addition, the following instruction set extensions are available.
+
+.. list-table:: Ibex Instruction Set Extensions
+   :header-rows: 1
+
+   * - Extension
+     - Version
+     - Configurability
+
+   * - **C**: Standard Extension for Compressed Instructions
+     - 2.0
+     - always enabled
+
+   * - **M**: Standard Extension for Integer Multiplication and Division
+     - 2.0
+     - optional
+
+   * - **B**: Draft Extension for Bit Manipulation Instructions
+     - 0.92 [#B_draft]_
+     - optional
+
+   * - **Zicsr**: Control and Status Register Instructions
+     - 2.0
+     - always enabled
+
+   * - **Zifencei**: Instruction-Fetch Fence
+     - 2.0
+     - always enabled
+
+Most content of the RISC-V privileged specification is optional.
+Ibex currently supports the following features according to the RISC-V Privileged Specification, version 1.11.
+
+* M-Mode and U-Mode
+* All CSRs listed in :ref:`cs-registers`
+* Performance counters as described in :ref:`performance-counters`
+* Vectorized trap handling as described at :ref:`exceptions-interrupts`
+
+.. rubric:: Footnotes
+
+.. [#B_draft] Note that while Ibex fully implements draft version 0.92 of the RISC-V Bit Manipulation Extension, this extension may change before being ratified as a standard by the RISC-V Foundation.
+   Ibex will be updated to match future versions of the specification.
+   Prior to ratification this may involve backwards incompatible changes.
+   Additionally, neither GCC or Clang have committed to maintaining support upstream for unratified versions of the specification.

doc/01_overview/index.rst

@@ -0,0 +1,16 @@
+Introduction to Ibex
+====================
+
+Ibex is a production-quality open source 32 bit RISC-V CPU core written in SystemVerilog.
+The CPU core is heavily parametrizable and well suited for embedded control applications.
+Ibex is being extensively verified and has seen multiple tape-outs.
+
+Read on for more information Ibex in general: what standards it implements, what synthesis targets it supports, and what legal and financial obligations you have when using Ibex.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: In this section
+
+   compliance
+   targets
+   licensing

doc/01_overview/targets.rst

@@ -0,0 +1,19 @@
+Synthesis Targets
+=================
+
+ASIC Synthesis
+--------------
+
+ASIC synthesis is supported for Ibex.
+The whole design is completely synchronous and uses positive-edge triggered flip-flops, except for the register file, which can be implemented either with latches or with flip-flops.
+See :ref:`register-file` for more details.
+The core occupies an area of roughly 24 kGE when using the latch-based register file and implementing the RV32IMC ISA, or 16 kGE when implementing the RV32EC ISA.
+
+
+FPGA Synthesis
+--------------
+
+FPGA Synthesis is supported for Ibex.
+The FPGA-optimized register file implementation should be used.
+The flip-flop based register file is also compatible with FPGA synthesis, however it may result in significantly higher resource utilization.
+Since latches are not well supported on FPGAs, the latch-based register file should not be used.

doc/02_user/index.rst

@@ -0,0 +1,14 @@
+Ibex User Guide
+===============
+
+The Ibex User Guide provides all necessary information to use Ibex.
+It is aimed at hardware developers integrating Ibex into a design, and software developers writing software running on Ibex.
+
+.. toctree::
+   :maxdepth: 1
+   :caption: In this section
+
+   system_requirements
+   getting_started
+   integration
+   examples

doc/03_reference/history.rst

@@ -0,0 +1,14 @@
+History
+=======
+
+Ibex development started in 2015 under the name "Zero-riscy" as part of the `PULP platform <https://pulp-platform.org>`_ for energy-efficient computing.
+Much of the code was developed by simplifying the RV32 CPU core "RI5CY" to demonstrate how small a RISC-V CPU core could actually be `[1] <https://doi.org/10.1109/PATMOS.2017.8106976>`_.
+To make it even smaller, support for the "E" extension was added under the code name "Micro-riscy".
+In the PULP ecosystem, the core is used as the control core for PULP, PULPino and PULPissimo.
+
+In December 2018 lowRISC took over the development of Zero-riscy and renamed it to Ibex.
+
+References
+----------
+
+1. `Schiavone, Pasquale Davide, et al. "Slow and steady wins the race? A comparison of ultra-low-power RISC-V cores for Internet-of-Things applications." 27th International Symposium on Power and Timing Modeling, Optimization and Simulation (PATMOS 2017) <https://doi.org/10.1109/PATMOS.2017.8106976>`_

doc/03_reference/index.rst

@@ -0,0 +1,26 @@
+Ibex Reference Guide
+====================
+
+The Ibex Reference Guide provides background information.
+It describes the design in detail, discusses the verification approach and the resulting testbench structures, and generally helps to understand Ibex in depth.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: In this section
+
+   pipeline_details
+   icache
+   instruction_fetch
+   instruction_decode_execute
+   load_store_unit
+   register_file
+   cs_registers
+   performance_counters
+   exception_interrupts
+   pmp
+   security
+   debug
+   tracer
+   verification
+   rvfi
+   history

doc/03_reference/verification.rst

@@ -1,6 +1,10 @@
 Verification
 ============
 
+.. todo::
+
+  This section needs to be split into a HOWTO-style user/developer guide, and reference information on the testbench structure.
+
 Ibex Core
 ---------
 

doc/04_developer/index.rst

@@ -0,0 +1,18 @@
+Ibex Developer Guide
+====================
+
+Ibex is an open source project and invites everyone to contribute.
+The Ibex Developer Guide documents how Ibex is developed, both in terms of process and tools.
+
+Read on if you would like to work with the Ibex code base to fix a bug, add a feature, or reproduce the verification.
+
+.. todo::
+
+   Describe how to set up development environment, how to make changes, etc.
+   Use content from various READMEs and the CONTRIBUTING guide in the repo.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: In this section
+
+   concierge

doc/conf.py

@@ -30,7 +30,11 @@ numfig_format = {'figure': 'Figure %s', 'table': 'Table %s', 'code-block': 'List
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ['sphinxcontrib.wavedrom']
+extensions = [
+    'sphinxcontrib.wavedrom',
+    'sphinx.ext.todo',
+]
+
 wavedrom_html_jsinline = False
 
 # Add any paths that contain templates here, relative to this directory.
@@ -46,7 +50,7 @@ source_suffix = '.rst'
 master_doc = 'index'
 
 # General information about the project.
-project = 'Ibex User Manual'
+project = 'Ibex Documentation'
 copyright = '2017-2018, ETH Zurich and University of Bologna, 2018-present lowRISC'
 author = 'lowRISC contributors'
 
@@ -76,7 +80,7 @@ exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'venv']
 pygments_style = 'sphinx'
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
+todo_include_todos = True
 
 
 # -- Options for HTML output ----------------------------------------------

doc/index.rst

@@ -1,34 +1,30 @@
-Ibex User Manual
-================
+Ibex: An embedded 32 bit RISC-V CPU core
+========================================
+
+Ibex is a production-quality open source 32 bit RISC-V CPU core written in SystemVerilog.
+The CPU core is heavily parametrizable and well suited for embedded control applications.
+Ibex is being extensively verified and has seen multiple tape-outs.
+
+You are now reading the Ibex documentation.
+The documentation is split into four parts.
+
+The :doc:`Overview documentation <01_overview/index>` looks at Ibex from high up.
+It answers questions like what are the high-level properties of Ibex, which standards is Ibex following, and where is it typically used.
+
+The :doc:`User Guide <02_user/index>` provides all necessary information to use Ibex.
+It is aimed at hardware developers integrating Ibex into a design, and software developers writing software running on Ibex.
+
+The :doc:`Reference Guide <03_reference/index>` provides background information.
+It describes the design in detail, discusses the verification approach and the resulting testbench structures, and generally helps to understand Ibex in depth.
+
+The :doc:`Developer Guide <04_developer/index>` is aimed at people making changes to Ibex itself.
+Since Ibex is open source, every user of Ibex is encouraged to learn how to adapt Ibex to their use case, and be part of the open development process.
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
-
-   introduction
-   system_requirements
-   getting_started
-   integration
-   pipeline_details
-   instruction_fetch
-   instruction_decode_execute
-   icache
-   load_store_unit
-   register_file
-   cs_registers
-   performance_counters
-   exception_interrupts
-   pmp
-   security
-   debug
-   tracer
-   rvfi
-   verification
-   examples
-   concierge
-
-
-.. toctree::
    :hidden:
 
-   licensing
+   01_overview/index.rst
+   02_user/index.rst
+   03_reference/index.rst
+   04_developer/index.rst

doc/introduction.rst

@@ -1,126 +0,0 @@
-Introduction
-============
-
-.. figure:: images/blockdiagram.svg
-   :name: blockdiagram
-
-   Block Diagram
-
-Ibex is a 2-stage in-order 32b RISC-V processor core.
-Ibex has been designed to be small and efficient.
-Via two parameters, the core is configurable to support four ISA configurations.
-:numref:`blockdiagram` shows a block diagram of the core.
-
-Standards Compliance
---------------------
-
-Ibex is a standards-compliant 32b RISC-V processor.
-It follows these specifications:
-
-* `RISC-V Instruction Set Manual, Volume I: User-Level ISA, document version 20190608-Base-Ratified (June 8, 2019) <https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMFDQC-and-Priv-v1.11/riscv-spec-20190608.pdf>`_
-* `RISC-V Instruction Set Manual, Volume II: Privileged Architecture, document version 20190608-Base-Ratified (June 8, 2019) <https://github.com/riscv/riscv-isa-manual/releases/download/Ratified-IMFDQC-and-Priv-v1.11/riscv-privileged-20190608.pdf>`_.
-  Ibex implements the Machine ISA version 1.11.
-* `RISC-V External Debug Support, version 0.13.2 <https://content.riscv.org/wp-content/uploads/2019/03/riscv-debug-release.pdf>`_
-* `RISC-V Bit Manipulation Extension, version 0.92 (draft from November 8, 2019) <https://github.com/riscv/riscv-bitmanip/blob/master/bitmanip-0.92.pdf>`_
-
-Many features in the RISC-V specification are optional, and Ibex can be parametrized to enable or disable some of them.
-
-Ibex can be parametrized to support either of the following two instruction sets.
-
-* The RV32I Base Integer Instruction Set, version 2.1
-* The RV32E Base Integer Instruction Set, version 1.9 (draft from June 8, 2019)
-
-In addition, the following instruction set extensions are available.
-
-.. list-table:: Ibex Instruction Set Extensions
-   :header-rows: 1
-
-   * - Extension
-     - Version
-     - Configurability
-
-   * - **C**: Standard Extension for Compressed Instructions
-     - 2.0
-     - always enabled
-
-   * - **M**: Standard Extension for Integer Multiplication and Division
-     - 2.0
-     - optional
-
-   * - **B**: Draft Extension for Bit Manipulation Instructions
-     - 0.92 [#B_draft]_
-     - optional
-
-   * - **Zicsr**: Control and Status Register Instructions
-     - 2.0
-     - always enabled
-
-   * - **Zifencei**: Instruction-Fetch Fence
-     - 2.0
-     - always enabled
-
-Most content of the RISC-V privileged specification is optional.
-Ibex currently supports the following features according to the RISC-V Privileged Specification, version 1.11.
-
-* M-Mode and U-Mode
-* All CSRs listed in :ref:`cs-registers`
-* Performance counters as described in :ref:`performance-counters`
-* Vectorized trap handling as described at :ref:`exceptions-interrupts`
-
-ASIC Synthesis
---------------
-
-ASIC synthesis is supported for Ibex.
-The whole design is completely synchronous and uses positive-edge triggered flip-flops, except for the register file, which can be implemented either with latches or with flip-flops.
-See :ref:`register-file` for more details.
-The core occupies an area of roughly 24 kGE when using the latch-based register file and implementing the RV32IMC ISA, or 16 kGE when implementing the RV32EC ISA.
-
-FPGA Synthesis
---------------
-
-FPGA Synthesis is supported for Ibex.
-The FPGA-optimized register file implementation should be used.
-The flip-flop based register file is also compatible with FPGA synthesis, however it may result in significantly higher resource utilization.
-Since latches are not well supported on FPGAs, the latch-based register file should not be used.
-
-Contents
---------
-
- * :ref:`getting-started` discusses the requirements and initial steps to start using Ibex.
- * :ref:`core-integration` provides the instantiation template and gives descriptions of the design parameters as well as the input and output ports.
- * :ref:`pipeline-details` described the overal pipeline structure.
- * :ref:`instruction-decode-execute` describes how the Instruction Decode and Execute stage works.
- * The instruction and data interfaces of Ibex are explained in :ref:`instruction-fetch` and :ref:`load-store-unit`, respectively.
- * :ref:`icache` describes the optional Instruction Cache.
- * The two register-file flavors are described in :ref:`register-file`.
- * The control and status registers are explained in :ref:`cs-registers`.
- * :ref:`performance-counters` gives an overview of the performance monitors and event counters available in Ibex.
- * :ref:`exceptions-interrupts` deals with the infrastructure for handling exceptions and interrupts,
- * :ref:`pmp` gives a brief overview of PMP support.
- * :ref:`debug-support` gives a brief overview on the debug infrastructure.
- * :ref:`tracer` gives a brief overview of the tracer module.
- * For information regarding formal verification support, check out :ref:`rvfi`.
- * :ref:`examples` gives an overview of how Ibex can be used.
-
-
-History
--------
-
-Ibex development started in 2015 under the name "Zero-riscy" as part of the `PULP platform <https://pulp-platform.org>`_ for energy-efficient computing.
-Much of the code was developed by simplifying the RV32 CPU core "RI5CY" to demonstrate how small a RISC-V CPU core could actually be `[1] <https://doi.org/10.1109/PATMOS.2017.8106976>`_.
-To make it even smaller, support for the "E" extension was added under the code name "Micro-riscy".
-In the PULP ecosystem, the core is used as the control core for PULP, PULPino and PULPissimo.
-
-In December 2018 lowRISC took over the development of Zero-riscy and renamed it to Ibex.
-
-References
-----------
-
-1. `Schiavone, Pasquale Davide, et al. "Slow and steady wins the race? A comparison of ultra-low-power RISC-V cores for Internet-of-Things applications." 27th International Symposium on Power and Timing Modeling, Optimization and Simulation (PATMOS 2017) <https://doi.org/10.1109/PATMOS.2017.8106976>`_
-
-.. rubric:: Footnotes
-
-.. [#B_draft] Note that while Ibex fully implements draft version 0.92 of the RISC-V Bit Manipulation Extension, this extension may change before being ratified as a standard by the RISC-V Foundation.
-   Ibex will be updated to match future versions of the specification.
-   Prior to ratification this may involve backwards incompatible changes.
-   Additionally, neither GCC or Clang have committed to maintaining support upstream for unratified versions of the specification.