.. _firmware-source-code:

Source code
===========

The firmware is stored in the `ipbus/ipbus-firmware <https://github.com/ipbus/ipbus-firmware>`_ git repository on GitHub. A tagged version of this firmware should be used in all cases (i.e. please **do NOT checkout a non-tagged commit, or the tip of a branch** unless that is suggested by the IPbus developers). 
The latest IPbus firmware tag is ``v1.14``. It can be found at `ipbus-firmware/releases/tag/v1.14 <https://github.com/ipbus/ipbus-firmware/releases/tag/v1.14>`_, and can be downloaded using the following commands:

.. code-block:: sh

  git clone https://github.com/ipbus/ipbus-firmware.git
  cd ipbus-firmware
  git checkout v1.14

**N.B.** In addition to the core IPbus firmware packages, the IPbus firmware git repository also includes the firmware designs used for testing, so the contents of the CACTUS **SVN tag** ``ipbus_2_0_v1`` **corresponds to the** ``components/ipbus`` **subdirectory in the git repository's tags.**

Release notes for each of the firmware tags can be found :ref:`here <fwReleaseNotes>`.


.. How can I integrate the IPbus firmware block into my firmware design?
.. ---------------------------------------------------------------------

.. The current IPbus Ethernet interface was developed by analogy with the Xilinx 1G Ethernet Example Design, effectively mapping onto the FIFO block and user code in that design.

.. Therefore if you can find a suitable 1G Ethernet Example Design then this is a very good starting point.

.. Depending on the specific details of the TEMAC that you intend to use, namely does it bring the incoming Ethernet frame onto the TX clock domain, you may or may not need a RX FIFO to handle buffering the incoming octets if the remote TX Ethernet clock is faster than the local clock.  Thus our IPBus KC705 GMII design includes such a FIFO, the BASE-X doesn’t.

.. A data sheet summarising the interface to the IPbus firmware is in preparation (current version at :download:`ipbus_ctrl_overview.pdf`). This document also includes instructions on how to set up the firmware to use IP address assignment methods (IP and/or MAC address set from internal configuration space, signals external to the IPbus block, or using RARP). 

.. These designs have been fine up until now with Virtex 5 and 6, Spartan and Kintex 7, but the problem that we are encountering nowadays is that Xilinx now concentrate on 10G Ethernet and beyond, so an UltraScale 1G example is proving fun.

.. We are trying to target the KCU105, but please bear with us.  In the meantime until the final version of this document arrives, please open a ticket at https://github.com/ipbus/ipbus-firmware/issues/new if you have any questions about how to integrate the IPbus firmware block into your firmware design.