A Chisel3 library for generating AMBA components featuring a Verilog APB Control/Status Register (CSR) target (an APB slave) generator
AMBEL aims to provide a collection of parameterizable Chisel3 Modules compatible with ARM's widely adopted AMBA (Advanced Microcontroller Bus Architecture) protocols. The initial collection keeps it simple, focusing solely on APB2 protocol and offering Modules that may be connected to implement APB2 networks connecting APB2 initators and targets. The key Module in this small collection is Apb2CSTrgt which is an APB2 target (an APB slave) implementing control/status registers, defined using a simple JSON schema.
The Modules are primarily intended for integration into other Chisel designs, but they could also be used to generate Verilog for integration into Verilog designs.
Please follow the general instructions for getting setup to run Chisel locally found on in the Chisel3 repo.
AMBEL has the following dependencies
Tests can be run with either Treadle or Verilator (Verilator is used to generate line coverage in Actions). Currently Verilator 4.218 2022-01-17 rev v4.218 is being used. See Running Tests for further details.
Contributions and collaborators welcome! Please see the guide to contributing if you want to join in.
The Apb2CSTrgt Module implements a basic APB2 control/status register set with the registers and their address map supplied via a simple JSON description, passed as a parameter to the Module. The JSON register description is parsed using circe and the resulting objects are used to generate the registers, read-write access to them via the APB2 interface, and also any associated direct IO for the registers using Chisel's MixedVec.
Setting the parameter GEN_MODULE = true will generate a set of Bundles and a wrapper Module which uses the Bundles and makes an ordered connection between the generated, numbered IO and the named members of the Bundles. There's an auto-generated Bundle for each register bit field type with a member for each bit field named after its register name and bit field name (as specified in the JSON). See the Simple Example to quickly get the gist of this.
The APB2 target (slave) interface on the Apb2CSTrgt Module has support for the specification of the address width and data width via the ADDR_W and DATA_W parameters. Any number and variety of bit-field modes may be specified for a given register and PSTRB is supported such that writes may target only certain bit-fields (with some restrictions described in the documentation). Support for PPROT is on the backlog, see issue #10.
The screenshot below shows a few APB write-read-back cycles for the first register, which has a single 8-bit RW bit-field on its first byte, of the Simple Example as well as the RW Output updating after each write.
The Apb2Net Module implements an APB2 network connecting a parameterizable number of APB2 initiators and targets with further parameters defining address map for the targets (base addresses and sizes).
The Apb2Slice Module is a simple APB2 bus register slice for pipelining/timing closure. The Module has a pair of APB2 interfaces (initiator and target) and works by registering initiator requests, forwarding them to the target interface, and extending the response with wait states until the target responds. The target response itself is registered to return to the initator.
You can run all the tests from the command line in sbt with
testIf you want to run one particular test suite you can do so as follows
testOnly ambel.SimpleApb2TUnitTesterTo dump waves (VCD) you can add -- -DwriteVcd=1. Some other useful command line options have also been implemented:
-Dbackend=verilator: select Verilator as the simulator instead of Treadle (the default)-Dseed=123: specify 123 as the randomization seed (some tests generate and use random data)-Ddebug=1: pass the DEBUG flag into the unit tester (e.g. to enable very verbose debug messages)-Dverbose=1: pass the VERBOSE flag into the unit tester to enable verbose messages, by default the tests run quite quietly
E.g. to use all of the above options for the Simple Example tests and dump a VCD file
testOnly ambel.SimpleApb2TUnitTester -- -Dbackend=verilator -Dseed=123 -Ddebug=1 -Dverbose=1 -DwriteVcd=1If you would like to get a feel for the Verilog emitted directly by the AMBEL Apb2CSTrgt Module at the moment the most direct way is to manualy edit the Apb2CSTrgtDriver() source code to point to your own JSON register description, then run
runMain ambel.Apb2CSTrgtDriver --target-dir src/main/verilog --log-level info --log-file Apb2CSTrgtDriver.logAlternatively, for a look at the Verilog emitted for the wrapper Module of the Simple Example just run
runMain ambel.SimpleApb2TDriver --target-dir src/main/verilog/examples --log-level info --log-file SimpleApb2TDriver.log