Join forces with hdl/constraints

umarcor commented 3 years ago

Moved from https://github.com/trabucayre/openFPGALoader/pull/102#issuecomment-895953900.

@trabucayre, I would like to propose joining forces with hdl/constraints. Subdir board contains a subdir for each board. There, an info.yml file contains the data about the board (label, device, package, part number, docs, programmers, etc.). In some cases, a README.md containing a frontmatter is used instead of the YAML file. See, for instance:

Apart from the data, constraint files are provided (in XDC, PCF, LPF, etc.).

Some boards are in the .todo subdir, which means that the constraints were not gathered/reworked yet. However, all of them contain data at least.

The content of hdl/constraints is shown in hdl.github.io/awesome/boards (all boards, "todo" and "not todo"). In the list, the board, the device and a picture are shown, along with icons/references to the constraints repo, the datasheets, git repos, etc. There is a page for each board, where the complete info.yml/README.md content is shown. For instance:

Overall, the main purpose of hdl/constraints is for projects such as openFPGALoader to avoid the maintenance burden of gathering all the references. You can use a single link (hdl.github.io/awesome/boards/BOARDIDENTIFIER) to access an "entrypoint" containing multiple references for that board. Moreover, we are discussing about generating (interactive) pinout diagrams (maybe automatically from KiCAD sources): https://github.com/hdl/constraints/issues/3. Then, the page of each board would contain the pinout, apart from the photo/render.

Therefore, I would be willing to adapt/modify the board info template (https://github.com/hdl/constraints/blob/main/template/board.info.yml) in order to better fit the information about openFPGALoader. Say:

prog?:
  - tool: openFPGALoader
    keyword: <WORD>
    memory: <BOOLEAN>
    flash: <BOOLEAN>
  - <TOOL2>
  - <TOOL3>

By the same token, driver setup data (https://github.com/trabucayre/openFPGALoader/blob/master/99-openfpgaloader.rules) might be provided in hdl/constraints: prog. Ref: https://github.com/SymbiFlow/symbiflow-arch-defs/pull/2240#discussion_r684633689.

As a result of having the information available in a machine-readable format (fields of a YAML block), the table might be generated automatically. Python can read YAML easily and tabulate allows writing tables in multiple formats, including 'github', 'rst', 'html', 'latex',... (https://github.com/astanin/python-tabulate#table-format). The table might be shown in hdl.github.io/awesome/items/openfpgaloader and/or added as a page to the site of this repo. Obviously, I can contribute the script to do that, either in the CI from hdl/awesome or in here.

/cc @mithro

trabucayre commented 3 years ago

This repository is really interesting and the idea to avoid doing more than one time the same task is good. In other hand I like self contained repositories to have an offline access to all informations. For example, it make sense to provides in openFPGALoader repo the udev file (and maybe make sense to install this file automatically). But if it's possible to complete one repository based on informations for another I'm perfectly agree with this solution!

umarcor commented 2 years ago

FTR, now there is a "Constraints" column in the Boards compatibility list, which contains cross-references to hdl/constraints through interpshinx. See #160 and #161.

Possible enhancements:

Use the same mechanism in the FPGA/Device compatibility list.
Update the layout in the site, in order to show a section per board, instead of or apart from the table.

trabucayre commented 2 years ago

Thanks for the update!

It's clear fpga list (and cable list) must be updated to the same way, it's more easy to update / maintain
for section per board vs table: good question. Table is a bit too large to display every columns without having to scroll, but the primary purpose is to displaying key to use with -b and this may overlap hdl/contraints.I'm temped to said the table is not correct solution... I have to think if moving is, or not, required

umarcor commented 2 years ago

The documentation of hdl/constraints now contains some data extracted from the doc helpers in this repo. If field Constraints is defined here, the openFPGALoader ID, Memory and Flash fields are shown in hdl.github.io/constraints: Boards.

trabucayre commented 2 years ago

It's really awesome! Thanks!

trabucayre commented 2 years ago

I have to update board list with missing ref (and use hdl/constraints to complete the board list / update my shopping list :-) )

boards representation in hdl/constraints looks better than simple array (and it's possible to add note / limitation / informations). The only advantage of the table is to have in few set of lines basic informations (board keywords and name). I think in a near futur I must moving this page to something similar to hdl/constraints format.

trabucayre / openFPGALoader

Join forces with hdl/constraints #105