doc: extend zephyr:board-supported-hw to include FPGA IP-Core based peripherals

[ibirnbaum]

The macro ".. zephyr:board-supported-hw::" in the rst file of a supported board's documentation triggers the generation of a very useful table of supported hardware components, which are provided either by the chip or the board, including the number of available instances and the associated DT compatible string.

At the time being however, it seems that this table misses all supported peripherals of a particular category: those which are instantiated in the system design of an SoC which combines CPU(s) and an FPGA, such as the Xilinx Zynq or the Xilinx ZynqMP (UltraScale+). We already have several such peripherals in-tree and more are currently being proposed in open PRs (for Xilinx-related IPs, look for "AXI" in the peripheral's name).

While their basic support is chip-specific, there are no references to such peripheral instances in the SoC's or board's DT, as their existence isn't even board-specific, but application-specific. The hardware engineer must assure that an instance of a desired peripheral is contained in the system design and that it is mapped to a/several memory address range(s) and a/several interrupt line(s), depending on the particular IP core. The hardware engineer must than pass on this information and the matching FPGA bitstream to the software engineer, who can incorporate it in the target board's DT. With another bitstream however, the application and its contained peripheral IP cores as well as the matching DT might look completely different on exactly the same hardware.

Therefore, there's no way to pick these peripherals up automatically from the SoC and board DTs, as there's no universally valid way to incorporate them due to their application-specific nature. Also, at least some of them have a potential instance count of 0..n.

Describe the solution you'd like
Either an extension of the board-supported-hw macro or the introduction of an additional macro which takes a list of compatible strings so that supported IP core-based peripherals are displayed for all boards built around a SoC which supports them. They should be displayed as a distinct category "FPGA IP core" besides the existing "On-chip" and "On-board".

Describe alternatives you've considered
With the traditional table views generated from the input rst files, which some board docs still contain, the peripheral type specification was all text-based, so it was possible then to just write "FPGA IP core" instead of "On-Chip". However, the currently automatically generated tables are so much more useful and contain more information that doesn't require manual updating, not having a supported hardware table generated using ".. zephyr:board-supported-hw::" doesn't really seem like an option.

[kartben]

@ibirnbaum thanks for the very detailed report :)
Do you have an example of a board in-tree that as/had the previously manually authored table. I can't seem to find any but I might be searching for the wrong keywords.
I like the idea of adding a list of compatibles to the existing directive, but would need your help to understand the use case better

.. zephyr:board-supported-hw::
   :ip-core-extras: <space separated list of compats>

If I understand correctly you want more than that (although this might be an acceptable starting point?) though since you want to be able to describe once and for all the list of compats for a given soc, correct?

If you could add some more detailed examples it would be really great!
FWIW I'm happy to implement the proposed change above if that's a useful first step.

[henrikbrixandersen]

With the traditional table views generated from the input rst files, which some board docs still contain, the peripheral type specification was all text-based, so it was possible then to just write "FPGA IP core" instead of "On-Chip".

It would also be wrong to list those, as the board didn't enable them.

Listing devicetree compatibles for any IP which can be instantiated in e.g. an FPGA just because the given board hard one (e.g. if the board is using an all programmable SoC such as the AMD Zynq or a "soft-core" CPU such as the Cortex-M1 or NEORV32) will not provide a correct list of supported peripherals either. This would be similar to listing all possible SPI peripheral bindings for any board having a SPI controller.

I see no reason for treating FPGA-based boards any differently in this regard.

[ibirnbaum]

I don't insist on having anything at the board level, however, that's the level where the documentation takes place... I see the IP-based peripherals at the chip level technically (but with specific preconditions compared to your average microcontroller on-chip stuff), but there's no documentation to just describe the (potential) facilities of the more complex SoCs regardless of what board they're on.

There's probably not much to be said in general about your average STM32 or iMXRT, but it would have been nice to have facilities for an info page for the larger animals such as the Zynq or Ultrascale, which point out what is possible and what is not (for example, why there's generally no point in turning on the L2 cache on the Zynq and what the underlying limitation is) with the respective SoC, including, but not limited to FPGA IP cores, or what other caveats might exist. For example, it's possible to use the existing AXI DMA driver on the UltraScale, but not the Zynq, even if Vivado offered the IP core for both - this is something that certainly would be useful to document. But that's a side note and not the topic of this enhancement request right now.

So how can we let the people know in an organized, readable fashion what IP cores on the are currently supported by Zephyr? IP cores that don't appear anywhere at the board level can be found in the docs currently in the vendor-sorted bindings documentation which lists the compatible strings, the prefix "AXI" might give an indication, but that isn't even included in all compatible strings of the supported IPs (and when looking at compatible strings you'd have to know that some IPs aren't assigned to the chip vendor, but for example, Cadence as the IP designer). Clicking on a binding produces the usually rather brief binding description, which usually doesn't mention "this works on and " or "this only works on and not and here's the reason why".

You added support for the Digilent Zybo, I've been using the Digilent Zedboard for a long time, and they both have in common that aside from one measly LED and two pushbuttons on the PS side, all GPIO facilities (slide switches, directionals buttons, LEDs) on those boards only become available when integrating multiple AXI GPIO instances. I guess that the majority of the users of those boards would be grateful if those facilities were specified, labelled and enabled by default (at least by means of a provided overlay), we know that the switches, buttons and LEDs are always there, they're always on the same EMIO pins, we're always like 90% there. Yet we can't have those facilities in the board DT with the required universal validity, as the user has to come up with a matching system design first, and even if this was made clear by a big red warning box and maybe a tutorial somewhere, we still couldn't add it to the board DT, as we don't know the addresses of the AXI GPIO instances. So how can we let the user know that getting the GPIO facilities on these boards up and running requires some extra steps which must be done right, but if they decide to take those extra steps, the result is supported by Zephyr in the form of a matching device driver?

Had I read Benjamin's reply a little earlier, I would have even pointed to the current old-style doc of the Zybo board, where from my point of view, an indication that the device that enables one of the most elementary features of this board is supported by a matching driver would have definitely been appropriate. You're right that the board doesn't enable it - because no assumption can be made on the existence and the configuration of the required IPs. However, why should the user have go through the bindings or the drivers part of the repo to find out that AXI is supported not only on the Zybo but the Zynq in general?

It certainly doesn't have to be at the board level, but I do think that there should be a list of supported IPs for SoC that's a bit more user-friendly in terms of presentation as the bindings list.

This would be similar to listing all possible SPI peripheral bindings for any board having a SPI controller.

I don't think that this comparison cuts it entirely, as SPI peripheral bindings at least contain an indication as to the fact that they're on SPI, and the same applies to I2C/I3C. In comparison, there's no such thing as "on-bus: fpga" in the bindings of the AXI IP core peripherals. And in reverse, using the current approach, having boards in-tree which were based around an SoC which didn't have a fixed SPI controller, but required the use of an IP-based (supported!) one, the docs would imply that SPI wasn't supported at all, which just wouldn't be true. While it would be true that there wouldn't be a "one size fits all", universally valid approach, would this be helpful for the user?