.. uHAL documentation master file, created by
   sphinx-quickstart on Tue Sep 13 14:47:18 2016.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to the IPbus documentation!
===================================

This is the documentation for the IPbus firmware-software suite. If you want to read a brief introduction to IPbus continue reading this page; otherwise, please click on the links in the left navigation bar for more detailed information.

.. toctree::
  :hidden:
  :maxdepth: 1

  Firmware <firmware/index>
  Software <software/index>
  performance
  FAQ
  contact


Brief introduction to IPbus
---------------------------

The IPbus protocol is a simple packet-based control protocol for reading and modifying memory-mapped resources within FPGA-based hardware devices which have a virtual A32/D32 bus.

The IPbus suite of software and firmware implement a reliable high-performance control link for particle physics electronics, based on the IPbus protocol. This suite has successfully replaced VME control in several large projects, and consists of the following components:

**IPbus firmware**
  Modules that implement the IPbus protocol within end-user hardware.

**ControlHub**
  A software application that mediates simultaneous hardware access from multiple uHAL clients, and implements the IPbus reliability mechanism over UDP [#f1]_

**uHAL** 
  The Hardware Access Library (HAL) providing an end-user C++/Python API for IPbus reads, writes and RMW (read-modify-write) transactions.


Further reading
---------------


The **most recent paper** describing IPbus is from the proceedings for TWEPP2014

  \C. Ghabrous Larrea, K. Harder, D. Newbold, D. Sankey, A. Rose, A. Thea and T. Williams, "IPbus: a flexible Ethernet-based control system for xTCA hardware", *JINST* **10** (2015) no.02, C02019. `DOI: 10.1088/1748-0221/10/02/C02019 <http://dx.doi.org/10.1088/1748-0221/10/02/C02019>`__

Citation
^^^^^^^^

When referring to the IPbus software and/or firmware in a publication, please cite the TWEPP 2014 paper mentioned above; the bibtex entry for this paper can be found :download:`here <twepp14-ipbus.bibtex>`

----

.. rubric:: Footnotes

.. [#f1] Any loss re-ordering or duplication of the IPbus UDP packets is automatically corrected by the ControlHub, using the IPbus reliability mechanism, such that packet loss does **NOT** have to be considered when using the uHAL API if all control traffic is routed via a ControlHub.