Document canonical list of available backends

[dellis23]

What happened?

See here for precipitating discussion. We've had our repo get out of sync from the de facto list of available backends for IREE. It would be nice to be able to simply link users to the official list of available backends rather than having to keep and enforce this list on our own.

Steps to reproduce your issue

N/A

What component(s) does this issue relate to?

Compiler

Version information

No response

Additional context

No response

[silvasean]

Thanks Dan for filing this. For IREE team folks, ideally this would have the following:

1. List of available compiler backends, along with description of each (and ideally advantages/disadvantages vs other ones, e.g. why use vulkan over cuda or vice versa)
2. List of available runtime drivers and which compiler backends they are compatible with.

[benvanik]

This information is available here: https://iree-org.github.io/iree/deployment-configurations/ That could be updated to have a better overview without needing to click in to each backend, though.

[dellis23]

I think the only hard thing is how to tell what values are actually associated with each backend (i.e. what one should pass to something like iree.compiler.compile_str).

For example, if this list is accurate, I only see three of the options listed on the four backend pages. From there, it seems like the command line arguments essentially document the string that should be used, but it seems like this is --device on some pages but not on others (--iree-hal-target-backends?). I also see references to local-sync here, which if I'm reading the code correctly seems to be something that should be passed in to the runtime and not the compiler.

Perhaps a simple table summary on either the page you linked on the individual pages would work well.

[ScottTodd]

I see a few things we can do here to make this easier for users:

• [x] Add a table and more information to https://iree-org.github.io/iree/deployment-configurations/
• [x] Advertise iree-run-module --dump_devices (CLI) and iree.runtime.query_available_drivers() (Python) as ways to list available runtime devices/drivers
• [x] Advertise iree-compile /dev/null --iree-llvm-list-targets for listing available CPU targets. Note: that flag is a bit awkward to use, since it requires a positional argument, unlike --help (which I noticed one year ago 😭 : https://github.com/iree-org/iree/issues/7116#issuecomment-930390358)
• [x] Add a iree-compile --iree-hal-target-backends-list or make the list show up in --help output somehow. Right now it just appears as

  --iree-hal-target-backends=<string>                          - Target backends for executable compilation.
  

  compared to enums like

  --iree-vm-bytecode-module-output-format=<value>              - Output format the bytecode module is written in
    =flatbuffer-binary                                         -   Binary FlatBuffer file
    =flatbuffer-text                                           -   Text FlatBuffer file, debug-only
    =mlir-text                                                 -   MLIR module file in the VM dialect
    =annotated-mlir-text                                       -   MLIR module file in the VM dialect with annotations
  

  Once we have a way to query the linked in / enabled / supported target backends, we should plumb that through to the python bindings as well. (Or do they already have a good error message if you try compiling without a valid target backend?)
• [x] Possibly mention out of tree or experimental compiler target backends / runtime HAL drivers and advertise a few ones that we know about in open source

[ScottTodd]

Cool, I have PRs out to add iree-compile --iree-hal-list-target-backends (CLI) and iree.compiler.query_available_targets() (Python), and I fixed the awkward positional argument flag parsing with that new flag and --iree-llvm-list-targets.

I'll work on documentation updates next.

[ScottTodd]

https://iree-org.github.io/iree/deployment-configurations/ here you go, this has lists now, and information about how to query the linked in / supported targets/devices using the command-line tools and Python bindings

[silvasean]

Thanks Scott!!! This is perfect :)