Should LLVM provide more documentation for frontend developers?

Hello,

I’ve recently come across an interesting discrepancy between the X86 and AArch64 backends, namely how operations on bfloats are lowered, see

For completeness, I’m attaching the motivating bit of LLVM IR:

; ModuleID = 'LLVMDialectModule'
source_filename = "LLVMDialectModule"
define bfloat @kernel_sum_reduce(bfloat %0, bfloat %1) {
  %3 = fadd bfloat %0, %1
  ret bfloat %3
}

Here are some key points from the discussion on GitHub:

  • this LLVM IR is not supported on AArch64 (that’s a “design decision”),
  • Clang will never generate this code when targetting AArch64,
  • the X86 backend (unlike AArch64) will happily legalize this IR.

For folks only interested in Clang, this is not really an issue. But that’s only one frontend - what about all other frontends that target LLVM IR? [*]

Question 1
How are frontend developers meant to learn about such design decisions? In particular:

  • How could frontend developers discover unsupported LLVM IR instruction so that they can adapt their frontends accordingly?

Perhaps the solution is for every backend to accept all of LLVM IR?

Question 2
I mostly want to make sure that I am documenting this particular issue in the most discoverable way. If this is an isolated case, then I guess that a GitHub issue like the one above would be sufficient? But perhaps there’s a better location for issues like this?

Thank you,
-Andrzej

[*] I came across this code while poking around MLIR. Flang is another notable frontend within the monorepo.

As a developer from X86 backend, I often (just be able to) make things work for Clang on X86 side only. I don’t know how many other frontend exists and being active, nor have expertise on them. I also cannot make a new feature wotks for other targets at the same time, especially when it requres big changes.
It is recommended to put RFC for discussions when doing a widely affected feature like this. I don’t find an RFC for this particular one, but there’s documentation in Clang Language Extensions — Clang 16.0.0git documentation
And you can find a lot of discussion from the initial patch ⚙ D76077 [ARM] Add __bf16 as new Bfloat16 C Type

Hey @phoebe , thanks for chiming in!

That’s understandable - we shouldn’t be expecting developers of “backend A” to be also experts in “backend B” :slight_smile:

Yes, but that’s Clang’s documentation. I’m just wondering - should we be making things like this more discoverable for other frontends?

Speaking only for myself here:

Perhaps the solution is for every backend to accept all of LLVM IR?

Ideally, all LLVM IR that doesn’t rely on target-dependent features should be accepted by all backends. Unfortunately, the set of target-dependent features isn’t that clear beyond the target-specific intrinsics (e.g., llvm.x86.xsave is clearly x86-specific), and the “clearly” target-specific types (x86_mmx, x86_amx, x86_fp80, and ppc_fp128). The less-common floating point types half, bfloat, and fp128 definitely fall into the penumbra of “should backends be required to support these?”

I mostly want to make sure that I am documenting this particular issue in the most discoverable way. If this is an isolated case, then I guess that a GitHub issue like the one above would be sufficient? But perhaps there’s a better location for issues like this?

My personal opinion is that LLVM is unacceptably lacking in its target-specific documentation. What I would like to see is that every target has a dedicated reference documentation page that indicates things like supported calling conventions, what address spaces map to, target-specific intrinsics, supported and unsupported types, inline assembly constraints, target features and subtarget information, even target triple parsing details. And, helpfully, links to relevant hardware docs (e.g., ISA manuals, but also ABI docs can be useful). These pages exist to some degree already (e.g. User Guide for AMDGPU Backend — LLVM 16.0.0git documentation, which is the most detailed one so far [1]), but mostly only for the GPU targets–RISC-V is the only CPU target that has such a page. It should be possible to provide a lot of documentation details simply be writing appropriate tablegen backends for existing target .td files.

[1] Admittedly, half of the details seem to be there mainly because it feels like someone wanted to make that page the Sys-V ABI processor supplement for the AMD GPU, as the processor-specific extensions to ELF probably shouldn’t be on that page.

I’d like to clarify that the design decision was to not generate such code (i.e. arithmetic operations on bfloat) by clang, not that such code should not be supported by the AArch64 backend.

1 Like