[docs] Adding table of object file formats

[beanz]

Summary

The added section and table here list the object file formats LLVM MC
supports and which targets support each format.

[tschuett]

PowerPC and Mach-O is not a thing anymore?
The ELF line is too long.
I believe it is Mach-O and not MachO.

[beanz]

In D127645#3578107, @tschuett wrote:

PowerPC and Mach-O is not a thing anymore?

PowerPC MachO (and Darwin) support was removed a few years ago.

The ELF line is too long.

RST doesn't wrap lines in tables, so wrapping the line in the file will break the table. Because of this we generally allow long lines in documentation files :(

I believe it is Mach-O and not MachO.

Elsewhere in this doc it is MachO, and generally there's no real consistency here. Most places in the code it is MachO, but some places in text it is Mach-O. I chose to match the spelling used elsewhere in this file for consistency.

[tschuett]

Thx.

[MaskRay]

llvm/docs/CodeGenerator.rst

707

"object file format" is more conventional.

726

You can sort rows alphabetically.

732

Add a row:

GOFF: SystemZ

@uweigand is this accurate?

[MaskRay]

llvm/docs/CodeGenerator.rst

730

SPIRV

I assume that supported targets here are LLVM_TARGETS_TO_BUILD/LLVM_EXPERIMENTAL_TARGETS_TO_BUILD allowed values (no - separator), not the official term describing the target.

[MaskRay]

llvm/docs/CodeGenerator.rst

727

@mstorsjo Is this accurate for COFF?

[compnerd]

llvm/docs/CodeGenerator.rst

727

AArch64, ARM, X86 I believe is the right set for COFF.

[mstorsjo]

llvm/docs/CodeGenerator.rst

727

Yes, drop PowerPC. Microsoft's PE-COFF can support a bunch of other stuff too, like PPC, Alpha, MIPS, IA64 etc, but we only support writing AArch64, ARM and X86 (both 32 and 64).

[uweigand]

llvm/docs/CodeGenerator.rst

732

Yes, for z/OS (although upstream support for z/OS is not fully complete at this point).

Of course, SystemZ should also be listed for ELF (for Linux, which has been fully supported for many years).

[beanz]

Updates based on review feedback.

[MaskRay]

Some suggestions inlined

llvm/docs/CodeGenerator.rst

711

object file formats

714

I'd delete the i.e. sentence, since the information is redundant given the table below.

731

Use SPIRV instead of SPIR-V.

(Otherwise you need to use Mach-O instead of MachO).

[beanz]

llvm/docs/CodeGenerator.rst

731

The spelling of MachO is largely inconsistent in documentation and code, but I was hoping for SPIR-V that we could use the proper spelling everywhere except where we refer to the target (which omits the - due to limitations that are sad).

So far, the SPIRVUsage doc is consistent in referring to the format as SPIR-V, so I'd like to keep that consistent here.

llvm/docs/CodeGenerator.rst

 target-specific opcode and a vector of MCOperands.  MCOperand, in turn, is a
 simple discriminated union of three cases: 1) a simple immediate, 2) a target
 register ID, 3) a symbolic expression (e.g. "``Lfoo-Lbar+42``") as an MCExpr.
 
 MCInst is the common currency used to represent machine instructions at the MC
 layer.  It is the type used by the instruction encoder, the instruction printer,
 and the type generated by the assembly parser and disassembler.
 
+.. _ObjectFormats:
+
+Object File Format
+------------------
+
+The MC layer's object writers support a variety of object formats. Because of
+target-specific aspects of object formats each target only supports a subset of
+the formats supported by the MC layer. Most targets support emitting ELF
+objects. Other vendor-specific objects are generally supported only on targets
+that are supported by that vendor (i.e. MachO is only supported on targets
+supported by Darwin, and XCOFF is only supported on targets that support AIX).
+Additionally some targets have their own object formats (i.e. DirectX, SPIR-V
+and WebAssembly).
+
+The table below captures a snapshot of object file support in LLVM:
+
+  .. table:: Object File Formats
+
+     ================== ========================================================
+     Format              Supported Targets
+     ================== ========================================================
+     ``COFF``            AArch64, ARM, X86
+     ``DXContainer``     DirectX
+     ``ELF``             AArch64, AMDGPU, ARM, AVR, BPF, CSKY, Hexagon, Lanai, LoongArch, M86k, MSP430, MIPS, PowerPC, RISCV, SPARC, SystemZ, VE, X86
+     ``GCOFF``           SystemZ
+     ``MachO``           AArch64, ARM, X86
+     ``SPIR-V``          SPIRV
+     ``WASM``            WebAssembly
+     ``XCOFF``           PowerPC
+     ================== ========================================================
+
 .. _Target-independent algorithms:
 .. _code generation algorithm:
 
 Target-independent code generation algorithms
 =============================================
 
 This section documents the phases described in the `high-level design of the
 code generator`_.  It explains how they work and some of the rationale behind