[doc] Add documentation on Ibex configuration

azure-pipelines.yml

@@ -103,9 +103,10 @@ jobs:
         # Note: Try to keep the list of configurations in sync with the one used
         # in Private CI.
         - small
-        - experimental-maxperf-pmp
-        - experimental-maxperf-pmp-bmfull
         - opentitan
+        - maxperf
+        - maxperf-pmp-bmbalanced
+        - maxperf-pmp-bmfull
         - experimental-branch-predictor
 
   # Run lint on simple system

doc/02_user/configuration.rst

@@ -0,0 +1,43 @@
+.. _ibex-config:
+
+Ibex Configurations
+===================
+
+The ``ibex_top`` module has a large number of top-level parameters which configure the core (see :ref:`core-integration`).
+This gives rise to a huge number of possible Ibex core configurations.
+To manage this complexity a number of named configurations is provided in the :file:`ibex_configs.yml` file.
+A subset of these are 'supported configurations' which are the focus of verification and development activities.
+
+Configuration Tool
+------------------
+
+A tool :file:`util/ibex_config.py` is provided to work with the named configurations.
+This tool provides command line options to set Ibex parameters for various EDA tools for a named configuration.
+Various Ibex flows (e.g. the DV flow) use this tool internally and can be provided with a configuration name from :file:`util/ibex_config.py` to work with.
+
+Here is an example of using the configuration tool to get the FuseSoC options required to build the ``opentitan`` configuration.
+
+.. code-block:: bash
+
+  # Request FuseSoC options required to build the 'opentitan' Ibex configuration.
+  ./util/ibex_config.py opentitan fusesoc_opts
+
+  # The output of the tool
+  --RV32E=0 --RV32M=ibex_pkg::RV32MSingleCycle --RV32B=ibex_pkg::RV32BOTEarlGrey --RegFile=ibex_pkg::RegFileFF --BranchTargetALU=1 --WritebackStage=1 --ICache=1 --ICacheECC=1 --ICacheScramble=1 --BranchPredictor=0 --DbgTriggerEn=1 --SecureIbex=1 --PMPEnable=1 --PMPGranularity=0 --PMPNumRegions=16 --MHPMCounterNum=10 --MHPMCounterWidth=32
+
+For further information about using the tool check the help provided on the command line.
+
+.. code-block:: bash
+
+  # Get help on using ibex_config.py
+  ./util/ibex_config.py -h
+
+Supported Configurations
+------------------------
+
+The current set of supported configurations are:
+
+ * ``small`` - RV32IMC with two stage pipeline and 3 cycle multiplier
+ * ``opentitan`` - The configuration used by the `OpenTitan <www.opentitan.org>`_ project
+ * ``maxperf`` - RV32IMC with three stage pipeline and single cycle multiplier, maximum performance (using stable features) configuration.
+ * ``maxperf-pmp-bmbalanced`` - ``maxperf`` configuration with PMP and the 'balanced' bit-manipulation configuration (:ref:`core-integration` for details).

doc/02_user/index.rst

@@ -10,5 +10,6 @@ It is aimed at hardware developers integrating Ibex into a design, and software
 
    system_requirements
    getting_started
+   configuration
    integration
    examples

ibex_configs.yaml

@@ -2,8 +2,17 @@
 # Licensed under the Apache License, Version 2.0, see LICENSE for details.
 # SPDX-License-Identifier: Apache-2.0
 
-# Ibex configurations files, holds the parameter sets that are tested under CI.
+# Ibex named configurations, each configuration must specify the same set of
-# Each configuration must specify the same set of parameters
+# parameters.
+
+# ============================
+# * SUPPORTED CONFIGURATIONS *
+# ============================
+#
+# Supported configurations are those that verification (such as nightly
+# regression) and design effort is focussed on. Currently only the 'opentitan'
+# configuration has nightly regressions but this will be expanded to all
+# supported configurations.
 
 # Two-stage pipeline without additional branch target ALU and 3 cycle multiplier
 # (4 cycles for mulh), resulting in 2 stall cycles for mul (3 for mulh)
@@ -46,14 +55,11 @@ opentitan:
   MHPMCounterNum           : 10
   MHPMCounterWidth         : 32
 
-# ===============================
-# * EXPERIMENTAL CONFIGURATIONS *
-# ===============================
-
 # Three-stage pipeline with additional branch traget ALU and 1 cycle multiplier
 # (2 cycles for mulh) so mul does not stall (mulh stall 1 cycles). This is the
-# maximum performance configuration.
+# maximum performance configuration ignoring the branch predictor (which isn't
-experimental-maxperf:
+# yet fully verified)
+maxperf:
   RV32E                    : 0
   RV32M                    : "ibex_pkg::RV32MSingleCycle"
   RV32B                    : "ibex_pkg::RV32BNone"
@@ -72,28 +78,8 @@ experimental-maxperf:
   MHPMCounterNum           : 0
   MHPMCounterWidth         : 40
 
-# experimental-maxperf config above plus PMP enabled with 16 regions.
+# maxperf config above with balanced bitmanip extension and PMP
-experimental-maxperf-pmp:
+maxperf-pmp-bmbalanced:
-  RV32E                    : 0
-  RV32M                    : "ibex_pkg::RV32MSingleCycle"
-  RV32B                    : "ibex_pkg::RV32BNone"
-  RegFile                  : "ibex_pkg::RegFileFF"
-  BranchTargetALU          : 1
-  WritebackStage           : 1
-  ICache                   : 0
-  ICacheECC                : 0
-  ICacheScramble           : 0
-  BranchPredictor          : 0
-  DbgTriggerEn             : 0
-  SecureIbex               : 0
-  PMPEnable                : 1
-  PMPGranularity           : 0
-  PMPNumRegions            : 16
-  MHPMCounterNum           : 0
-  MHPMCounterWidth         : 40
-
-# experimental-maxperf-pmp config above with balanced bitmanip extension
-experimental-maxperf-pmp-bmbalanced:
   RV32E                    : 0
   RV32M                    : "ibex_pkg::RV32MSingleCycle"
   RV32B                    : "ibex_pkg::RV32BBalanced"
@@ -112,8 +98,35 @@ experimental-maxperf-pmp-bmbalanced:
   MHPMCounterNum           : 0
   MHPMCounterWidth         : 40
 
-# experimental-maxperf-pmp config above with full bitmanip extension
+# ========================
-experimental-maxperf-pmp-bmfull:
+# * OTHER CONFIGURATIONS *
+# ========================
+
+# Configurations that may be useful but aren't supported configurations.
+
+# maxperf config above plus PMP enabled with 16 regions.
+maxperf-pmp:
+  RV32E                    : 0
+  RV32M                    : "ibex_pkg::RV32MSingleCycle"
+  RV32B                    : "ibex_pkg::RV32BNone"
+  RegFile                  : "ibex_pkg::RegFileFF"
+  BranchTargetALU          : 1
+  WritebackStage           : 1
+  ICache                   : 0
+  ICacheECC                : 0
+  ICacheScramble           : 0
+  BranchPredictor          : 0
+  DbgTriggerEn             : 0
+  SecureIbex               : 0
+  PMPEnable                : 1
+  PMPGranularity           : 0
+  PMPNumRegions            : 16
+  MHPMCounterNum           : 0
+  MHPMCounterWidth         : 40
+
+
+# maxperf-pmp config above with full bitmanip extension
+maxperf-pmp-bmfull:
   RV32E                    : 0
   RV32M                    : "ibex_pkg::RV32MSingleCycle"
   RV32B                    : "ibex_pkg::RV32BFull"
@@ -132,8 +145,8 @@ experimental-maxperf-pmp-bmfull:
   MHPMCounterNum           : 0
   MHPMCounterWidth         : 40
 
-# experimental-maxperf-pmp-bmfull config above with icache enabled
+# maxperf-pmp-bmfull config above with icache enabled
-experimental-maxperf-pmp-bmfull-icache:
+maxperf-pmp-bmfull-icache:
   RV32E                    : 0
   RV32M                    : "ibex_pkg::RV32MSingleCycle"
   RV32B                    : "ibex_pkg::RV32BFull"
@@ -152,10 +165,14 @@ experimental-maxperf-pmp-bmfull-icache:
   MHPMCounterNum           : 0
   MHPMCounterWidth         : 40
 
-# experimental-maxperf with branch predictor switched on. This exists to allow
+
-# easy use of Ibex with the branch predictor in particular for CI runs. The
+# ===============================
-# branch predictor will be enabled in all the 'maxperf' configs after further
+# * EXPERIMENTAL CONFIGURATIONS *
-# development.
+# ===============================
+
+# Configurations using experimental features that aren't yet verified and/or
+# known to have issues.
+
 experimental-branch-predictor:
   RV32E                    : 0
   RV32M                    : "ibex_pkg::RV32MSingleCycle"