Introduction to IPbus Protocol and Firmware
IPbus is a protocol for communicating with electronics over an IP network, specifically designed for FPGA-based hardware devices. It allows reading and modifying memory-mapped resources using a simple packet-based control protocol. The firmware organizes the addressing space in a tree-like structure, with different types of IPbus slaves for control and status registers. Using uHAL, a Hardware Access Library, developers can interact with the hardware using C++ or Python API. ControlHub acts as an intermediary application for managing transactions between the FPGA and the control host. The installation instructions and guidelines for using Python with IPbus are also discussed.
Download Presentation
Please find below an Image/Link to download the presentation.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author.If you encounter any issues during the download, it is possible that the publisher has removed the file from their server.
You are allowed to download the files provided on this website for personal or commercial use, subject to the condition that they are used lawfully. All files are the property of their respective owners.
The content on the website is provided AS IS for your information and personal use only. It may not be sold, licensed, or shared on other websites without obtaining consent from the author.
E N D
Presentation Transcript
IPbus is a protocol + fw + sw that allows to communicate electronics to a control host by means of an IP network: The IPbus protocol is a simple packet-based control protocol for reading and modifying memory-mapped resources within FPGA-based IP-aware hardware devices which have a virtual A32/D32 bus Firmware: works essentially as a 32-bit addressing space memory or collection of 32-bit registers. Not all the addresses are necessarily valid, depends on the firmware needs In FW, the addressing space is subdivided in a tree-like structure. The leaves are ipbus slaves suited for the different needs: control registers (r/w), stat registers (r/o), memories ControlHub: an optional application to manage transactions to the hardware. Communication between FPGA and PC can be direct, but its more reliable to use a ControlHub application in between. uHAL: Hardware Access Library that provides C++/Python API All official information (user guide ) and packages are available at https://ipbus.web.cern.ch IPbus July 10, 2018 2 A. Navarro
Complete installation instructions in the user guide. Note there are prerequisites (BOOST, pugiXML) that are provided by default by SL6 and CentOS 7. ControlHub is installed along with everything else, but must be started first in order to be used: service controlhub start / sudo systemctl start controlhub Choice between ControlHub-mediated or direct connection to the HW is done at device URI definition: chtcp vs ipbustcp/ipbustcp. When using controlhub, two URIs have to be provided (ControlHub and hw target): chtcp-2.0://localhost:10203?target=fpgaIP:50001 The ControlHub application can run in the same or a different host as the sw using it. At CMS, network restrictions apply so that only the designated ControlHub PC s can communicate with HW crates, to enforce ControlHub use. ControlHub use is transparent. IPbus July 10, 2018 3 A. Navarro
Why Python? It s essentially the same as C++ but it allows to easily test things Launch and load $ export LD_LIBRARY_PATH=/opt/cactus/lib:$LD_LIBRARY_PATH $ export PATH=/opt/cactus/bin:$PATH $ python >>> import uhal >>> uhal.setLogLevelTo(uhal.LogLevel.WARNING) # or ERROR. Verbose!! All operations are done on device (HwInterface) objects. To create them, you need 3 string parameters: id, URI and address table file URI: either direct (ipbusudp-2.0://fpgaIP:50001) or ControlHub-mediated (chtcp-2.0://localhost:10203?target=fpgaIP:50001) Address table: (translates textual register names to numeric address). More on this later. Devices can be created directly typing the parameters: >>> hw = uhal.getDevice( id_str, uri_str, address_table_str ) Or devices can be created reading parameters from a connection file: >>> manager = uhal.ConnectionManager("file://path/to/conns.xml") >>> hw = manager.getDevice("myDeviceID") IPbus July 10, 2018 4 A. Navarro
Connection file <?xml version="1.0" encoding="UTF-8"?> <connections> <connection id="dev1" uri="ipbusudp-2.0://1.2.3.4:50001" address_table="file://dummy_address.xml" /> <connection id="dev2" uri="chtcp-2.0://localhost:10203?target=1.2.3.4:50001" address_table="file://dummy_address.xml" /> </connections> Address Table file <node id="TOP"> <node id="topLevelReg" address="0x00000000"/> <node id="topLevelBlock" address="0x00000020"> hierarchical organization of registers: topLevelBlock.subBlock.regName <node id="subBlock" address="0x00000008"> <node id="reg32bit" address="0x00000000"/> address would be 0x28 (0x20 + 0x8 + 0x0) <node id="regMasked_p1" address="0x00000001" mask="0x0000FFFF"/> 0x29, careful with masks (read-modify-write) <node id="regMasked_p2" address="0x00000001" mask="0x003F0000"/> 0x29, careful with masks (read-modify-write) <node id="ro_reg" address="0x00000002" permission="r"/> writing causes exception <node id="reg_mode" address="0x00000004" mode="XXXX" [size="YY"]/> single/inc/port single is default. Inc (+size) allows block transactions on consecutive addresses, port allows block transactions on the same address. </node> </node> <node id= "inputStats1" module="file://mymodule.xml" address="0x00000400" /> xml nesting (and sub-nesting ) <node id= "inputStats2" module="file://mymodule.xml" address="0x00000500" /> </top> IPbus July 10, 2018 5 A. Navarro
HwInterface contains: methods to access creation information: id(), uri() Manage communication: dispatch(), setTimeoutPeriod() Access the tree of nodes defined in the address table: getNode(), getNodes() Access the hw without address table translation: getClient() Nodes are each hierarchical and final nodes of the address table structure: r1node = hw.getNode("block1.block2.reg1") the referenced node object hw.getNodes("b1\.b2.*") list of matching id strings ["b1.b2", "b1.b2.r1", ] Nodes also have getNode() and getNodes() functions Get node information: getAddress(), getMask(), getId(), getMode(), getPermission(), getSize(), getTags(), getParameters() Read/write node value: rVal = r1node.read(), r1node.write(integerValue) Read/write block: rValArr = r1node.readBlock(intSize), r1node.writeBlock(intValArr) Read/write operations transactions do not occur instantaneously: they are queued. A hw.dispatch()forces it, after you can do int(rVal) or map(int, rValArr) Direct numerical address: hw.getClient.read(addr, mask), hw.getClient().write(addr, data, mask) 32-bit read-modify-write!! IPbus July 10, 2018 6 A. Navarro
$ ssh dtdqm@vmepc-s2g16-14-01 $ cd /tmp $ echo '<node id="TOP"><node address="0xD0000000" id="readout"><node id="reg1"/><node id="reg2" address="0x1" mask="0xFFFF"/></node></node>' > at.xml $ python >>> import uhal >>> hw = uhal.getDevice('myID', 'chtcp-2.0://bridge-s1d15-38:10203?target=amc- s1d15-38-04:50001', 'file://at.xml') >>> hw.getNodes('readout.*') # will print list of nodes under readout >>> val = hw.getNode('readout.reg1') >>> int(val) # will print error >>> hw.dispatch() # does the actual transaction >>> int(val) # will print integer Please do not write to this board without asking first for permission, we may be using it in some activity IPbus July 10, 2018 7 A. Navarro
C++ Driver: our IPbus boards so far all inherit fw skeleton from the mp7 board, we also inherited from them the structure for a C++ driver with python bindings that we use both for C++ and python application development. Our simplest version is the uROS one: https://gitlab.cern.ch/cms-uros/uroscontroller In python we built wrapper objects to extend thes python-binded C++ driver. Adds functions useful during the development phase in interactive python console. For uROS, also the whole monitoring runs in python, so much more code https://gitlab.cern.ch/cms-uros/dtupy/blob/master/pkg/dtupy/urosmanager.py Also some generic uhal auxiliary functions in: https://gitlab.cern.ch/cms- uros/dtupy/blob/master/pkg/dtupy/uhalaux.py Generic name/address read/write functions, reg_num2name, regs_dump Useful command-line interface based on argparse: https://gitlab.cern.ch/cms- uros/dtupy/tree/master/pkg/dtupy/cli and https://gitlab.cern.ch/cms- uros/dtupy/blob/master/scripts/dtu.py Example C++ uhal code: https://gitlab.cern.ch/cms- uros/uroscell/blob/master/src/common/UROSsystem.cc IPbus July 10, 2018 8 A. Navarro
