github-mirrors/ibex
1
0
Fork 0
mirror of https://github.com/lowRISC/ibex.git synced 2025-04-23 21:39:13 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

[doc] Add documentation on Ibex configuration

Browse source
This commit is contained in:
Greg Chadwick 2023-01-31 16:38:53 +00:00 • committed by Greg Chadwick
parent 08dda90484
commit 4c3c11d448
4 changed files with 102 additions and 40 deletions
Download patch file Download diff file Expand all files Collapse all files

5
azure-pipelines.yml
View file

@ -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

43
doc/02_user/configuration.rst Normal file
View file

@ -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).

1
doc/02_user/index.rst
View file

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

93
ibex_configs.yaml
View file

@ -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"