From 4c3c11d448d3f11406b2c35408c964d6c1c2f768 Mon Sep 17 00:00:00 2001 From: Greg Chadwick Date: Tue, 31 Jan 2023 16:38:53 +0000 Subject: [PATCH] [doc] Add documentation on Ibex configuration --- azure-pipelines.yml | 5 +- doc/02_user/configuration.rst | 43 ++++++++++++++++ doc/02_user/index.rst | 1 + ibex_configs.yaml | 93 +++++++++++++++++++++-------------- 4 files changed, 102 insertions(+), 40 deletions(-) create mode 100644 doc/02_user/configuration.rst diff --git a/azure-pipelines.yml b/azure-pipelines.yml index d07ea077..5f57fc11 100644 --- a/azure-pipelines.yml +++ b/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 diff --git a/doc/02_user/configuration.rst b/doc/02_user/configuration.rst new file mode 100644 index 00000000..cbd59488 --- /dev/null +++ b/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 `_ 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). diff --git a/doc/02_user/index.rst b/doc/02_user/index.rst index e1158776..a373af0a 100644 --- a/doc/02_user/index.rst +++ b/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 diff --git a/ibex_configs.yaml b/ibex_configs.yaml index 4b693d0e..20e675af 100644 --- a/ibex_configs.yaml +++ b/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. -# Each configuration must specify the same set of parameters +# Ibex named configurations, each configuration must specify the same set of +# 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. -experimental-maxperf: +# maximum performance configuration ignoring the branch predictor (which isn't +# 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. -experimental-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 - -# experimental-maxperf-pmp config above with balanced bitmanip extension -experimental-maxperf-pmp-bmbalanced: +# maxperf config above with balanced bitmanip extension and PMP +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 -experimental-maxperf-pmp-bmfull-icache: +# maxperf-pmp-bmfull config above with icache enabled +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 -# development. + +# =============================== +# * EXPERIMENTAL CONFIGURATIONS * +# =============================== + +# Configurations using experimental features that aren't yet verified and/or +# known to have issues. + experimental-branch-predictor: RV32E : 0 RV32M : "ibex_pkg::RV32MSingleCycle"