.. _ipbus-firmware-users-guide:

IPbus firmware
==============

The IPbus firmware repository provides a reference system-on-chip implementation of modules that interpret the IPbus protocol within FPGAs, including:

* Interfaces for receiving and transmitting IPbus transaction lists over Gigabit Ethernet and PCIe
* The **transactor** - a transport-medium-agnostic component that decodes the transactions, and is the master of the on-chip bus 
* A bus fabric allowing for the attachment of multiple slaves to the bus with address decoding
* A large library of slaves
* Example designs for commercially-available development boards, covering a range of FPGA generations

.. * Bus fabric modules, designed to support hierarchical bus topologies that simplify the sharing of firmware between designs
.. * The *transactor*: An SoC bus master which decodes IPbus transaction lists


It has been developed within the CMS level-1 trigger project and CMS phase-2 upgrades, has been extensively tested on several different boards and in a wide range of particle physics experiments, and is supported on a best-effort basis.

The sections within this user guide (listed in the left-hand menu) provide detailed information about various aspects of the firmware, notably:

* The :ref:`firmware-source-code` page describes how to download the firmware repository.
* The :ref:`firmware-example-designs` page describes the high-level structure of the example designs, and how to build them.
* The :ref:`firmware-slaves` page lists the bus slaves that are provided in the repository - for connecting RAMs, registers and other resources to the bus.
* The :ref:`firmware-bus` page describes the signalling protocol for the on-chip bus.

.. toctree::
   :hidden:
   
   sourceCode
   exampleDesigns
   slaves
   bus
   transportInterfaces/index
   addressDecoders
   ipbb-primer
   releases/index


Supported devices and toolsets
------------------------------

At the moment, the IPbus firmware is principally used in Xilinx 7-series, Ultrascale and Ultrascale+ FPGAs. However, in the past it has also been extensively tested in 5- and 6-series Xilinx FPGAs.

The synthesisable firmware is currently being developed and tested with Vivado 2018.3 and 2019.2, and the simulations are tested with Modelsim 10.6c.


----

.. rubric:: What should I do if I have further questions, or want to report a problem or suggest a change?

Please open a ticket at https://github.com/ipbus/ipbus-firmware/issues/new