Hog and IPbus#

Warning

Outdated Documentation! This documentation version is out of date. Please check the latest version 2026.1.

Hog supports IPbus by handling IPbus XML files and VHDL address maps.

To use IPbus with Hog, include it as a submodule in your HDL repository. Include IPbus files in a list file.

Embedding of version and SHA in the XML files#

Hog keeps track of the version and SHA of the XML files by means of two dedicated generics/parameters (XML_VER and XML_SHA) and dedicated node tags in the XMLs.

To allow for this, your project must include one or more list files with .ipb extension located in the project’s list folder.

<repository>/Top/<project_name>/list/<file_name>.ipb

.

Note that the XML and VHDL files can be located anywhere in your project.

List files with .ipb extension#

This kind of files contain the list of the XML files used to generate the IPbus modules together with the generated VHDL address decode files, each line has the form:

 <path_to_xml>/<address_table>.xml [<path_to_vhdl>/<generated_file>.vhd]

During pre-synthesis, Hog will loop over the files contained tin this file to retrieve the SHA of the latest commit in which at least one of them was modified. The path to the generated module, if specified, enables Hog to use an IPbus python script (gen_ipbus_addr_decode) to verify that the generated modules correspond to the XML files. To use this feature, IPbus must be correctly installed, i.e.: the above mentioned script must be in the PATH and be able to access all the libraries it needs.

Note

The .ipb list files are normal Hog list files, with the exception that the listed files are not added to the project. For this reason properties like nosim or noimpl do not make sense and cannot be used.

To porperly use the VHDL address map files, you need to add them to a .src file.

IPbus xml files#

Hog can back annotate the included XMLs with the SHA evaluated as described above. This can be used by software to correctly assess if the used XMLs correspond to the gateware loaded on the device.

You can achieve this by defining a dedicated register where to store the value of the generic: XML_SHA provided by Hog.

The node corresponding to this registers is expected to have the following structure:

    <node id="gitSHA" permission="r" address="0x-"  tags="xmlgitsha=GIT_SHA" description="XML git commit 7-digit SHA of top file">

During pre-synthesis, Hog will replace __GIT_SHA__ with the SHA of the latest commit in which at least one of XMLs was modified. Hog will also set the XML_SHA generic in your top level to correspond to the same SHA. The user can now verify it is using the correct version of the XMLs by comparing the gitSHA register content with the gitSHA register tag.

The same procedure is done for the xml version. In this case the node is expected to have the following structure:

<node id="Version" permission="r" address="0x-" tags="xmlversion=__VERSION__"  description="version of XML files">
    <node id="Patch" mask="0xffff" description="Patch Number"/>
    <node id="Minor_Version" mask="0xff0000" description="Minor Version Number"/>
    <node id="Major_Version" mask="0xff000000" description="Major Version Number"/>
</node>

The __VERSION__ will be set to the version of the xml files taken from the last tag in which at least one of the xml files included in any of the .ipb list files was modified. The same value will be reported in the XML_VER generic of the top level of your project.

Check address maps against xml file#

Hog can handle IPbus XML files automatically. To run it from a console, use the following syntax:

Hog/Do XML <project name> [-xml_dir <destination directory>] [-generate]

This script will copy all the IPbus XML files listed in the .ipb list files (open them recursively if necessary) of the specified project into the <destination directory> creating it if necessary. If no <destination directory> is provided via the -xml_dir option, Hog will use ../<project_name>_xml by default.

Hog will aslo perform the substitution of the __GIT_SHA__ and __VERSION__ placeholders as described above. This is useful as IPbus XML files need to be all in the same directory to work. You can use this to distribute your XML files together with your binary file.

If the gen_ipbus_addr_decode IPbus python script file is in your PATH and works correctly, Hog will also verify each xml file against its VHDL address map to see if they match. It will do this ignoring blank lines and comments and will give warnings if it find some mismatch.

Generation of VHDL address maps#

If the -generate options is used, Hog will use the gen_ipbus_addr_decode to generate the VHDL address map files and replace them if necessary.