Changes between Initial Version and Version 1 of IPBusUserNotes

Jul 3, 2019, 11:25:03 AM (11 months ago)



  • IPBusUserNotes

    v1 v1  
     1The uHAL / IPBus software+firmware package [ (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.
     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).
     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:
     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>
     17A bit of sample code taken from the tutorial illustrates the key points:
     19ConnectionManager manager("file://path/to/connections.xml");
     20HwInterface hw = manager.getDevice("dummy.udp.0");
     22//write 1 in the address 0x0001
     23hw.getNode ("REG").write(1);
     25//read back
     26ValWord< uint32_t > reg = hw.getNode ("REG").read();
     28//send the IPbus transactions
     31std::cout << "REG = " << reg.value() << std::endl;
     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.
     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
     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:
     43 addr = hw.getNode( "rx_buffer").getAddress();
     45To access an offset from a named register, one must resort to some slightly more intricate code:
     47  val = hw.getClient().read( addr + offset);