A Parser For Vendor Provided .ini Files

Seyviour commented 10 months ago

Purpose

This Pull Request adds a module apycula/ini_h4x.py for parsing vendor-provided .ini files and edits the documentation to reflect the availability of a .ini parser.

Structure of .ini Files

The .ini file is a somewhat compressed table of IO Types and associated configuration options. The table has four sections -- input, output, bidirectional, and the optional i3c_bank.

Interface

ini_h4x.py provides an IniParser class for parsing .ini files. After the parse() method is called, the various sections of a parsed .ini file(input, output, bidirectional, i3c_bank) may be accessed via dot notation, or modified and written to a csv.

    iniParser = IniParser("GW1N-4")
    iniParser.parse()
    input_dict = iniParser.input

ini_h4x.py also exposes a simple command line tool to parse .ini files into csv; it may be invoked as shown below:

python ini_h4x.py --section all --export_file parsed.csv --force  GW1N-4

Correctness

The .ini file seems to contain similar information to the vendor supplied IO CSV files: input.csv, output.csv and bidir.csv. To check that the parser .ini parser works correctly, I did a (visual) check to make sure that the output of the parser and the data in the csv files were in agreement.

Documentation

This PR updates doc/filestructure.md and readme.md with information on the structure of .ini file and the newly introduced parser.

pepijndevos commented 10 months ago

Wow this is really great!

It's no doubt nice to have. The more pragmatic question is if it contains any additional information compared to the other files we're already parsing that is useful for generating bitstreams. If we can replace any hardcoded constants with info from this file that would be perfect.

Seyviour commented 10 months ago

As it stands, it's more in the nice-to-have category. There's a lot of overlap between the contents of the .ini and the IO csv files.

That said, it should be possible (in theory at least) to modify a .ini to trick the vendor tool into thinking that a device has an IO type that it doesn't have in reality. It might be interesting to see what kind of bitstream is generated in that scenario, if any is generated at all. IniParser doesn't have a method for that at the moment, but I could implement it.

pepijndevos commented 10 months ago

Yeah my impression is the ini and dat are mostly UI settings while fse contains the meat of the bitstream info.

Seyviour commented 10 months ago

Thanks for merging!

Yes, absolutely. Using inotify, I noticed that the IDE accesses the .ini when the FloorPlanner tool is opened. It also accesses the .ini (along with .dat) just before place-and-route, so I think .ini may be relevant to place-and-route at least.

YosysHQ / apicula