Changes between Initial Version and Version 1 of IPBusUserNotes


Ignore:
Timestamp:
Jul 3, 2019, 11:25:03 AM (3 months ago)
Author:
hazen
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • IPBusUserNotes

    v1 v1  
     1The uHAL / IPBus software+firmware package [https://ipbus.web.cern.ch/ipbus/ (source)] provides a convenient way to read/write registers and memories on a hardware device.  The original use case was to access programmable logic (FPGAs) on a board connected to a computer over Ethernet.
     2
     3The software component (uHAL) queues requested operations (''read'' and ''write'') in a "packet" which is transmitted to the hardware device when a ''dispatch'' function is called.  The firmware component (IPBus) parses the packet and performs the requested read and write operations in a logical 32-bit address space using a proprietary local bus (similar to Wishbone).
     4
     5A key feature of the package is the ''address table'' which is represented by one or more XML files.  Typically an address table names registers as in the following example:
     6{{{
     7  <node id="REG" address="0x0001" permission="rw">
     8    <node id="REG_TOP" mask="0xffff0000"/>
     9    <node id="REG_BOT" mask="0x0000ffff"/>
     10  </node>
     11  <node id="RESETS" address="0x0002" permission="w">
     12    <node id="RST_ALL" mask="1"/>
     13    <node id="RST_LINKS" mask="2"/>
     14  </node>
     15}}}
     16
     17A bit of sample code taken from the tutorial illustrates the key points:
     18{{{
     19ConnectionManager manager("file://path/to/connections.xml");
     20HwInterface hw = manager.getDevice("dummy.udp.0");
     21
     22//write 1 in the address 0x0001
     23hw.getNode ("REG").write(1);
     24
     25//read back
     26ValWord< uint32_t > reg = hw.getNode ("REG").read();
     27
     28//send the IPbus transactions
     29hw.dispatch();
     30
     31std::cout << "REG = " << reg.value() << std::endl;
     32}}}
     33
     34This code illustrates the typical use case, where one performs reads/writes on entire 32-bit registers using names from the address table.  In addition, the address table can contain a mask, which can be used to read or write subsets of bits from a register.  ''However'' one must be careful, as the protocol only supports full 32-bit reads and writes.  Writing a masked value actually causes a read/modify/write which may not be what is desired.
     35
     36Often we find that we want to do other things which are not trivially supported by uHAL, such as:
     37* Read/write to numeric addresses
     38* Read/write to an offset within a named region
     39* Write a fixed set of bits to a register with no read
     40
     41All these things can be accomplished, but require some cleverness.  To access the numeric address of a register, one can use the following code snippet:
     42{{{
     43 addr = hw.getNode( "rx_buffer").getAddress();
     44}}}
     45To access an offset from a named register, one must resort to some slightly more intricate code:
     46{{{
     47  val = hw.getClient().read( addr + offset);
     48}}}