[Object] Add ELF section type SHT_LLVM_BITCODE for LLVM bitcode

[MaskRay]

Summary

clang -ffat-lto-objects can use this new ELF section type for the .llvm.lto
section for fat LTO support (D146776).

Original RFC: https://discourse.llvm.org/t/rfc-ffat-lto-objects-support/63977

[nikic]

Why is a new section type necessary? Will this cause any compatibility issues with old binutils versions?

[jhenderson]

Is it worth an llvm-objdump test too?

Functionally looks fine, but I have no opinion on the overall feature itself (and therefore whether a new section type etc is needed for it).

I will say that if the feature has been accepted, a new section type would seem appropriate, so that tooling can handle it appropriately without having to check section names.

llvm/include/llvm/BinaryFormat/ELF.h

1039

Perhaps SHT_LLVM_FAT_LTO so that it is a little more self-descriptive? (Equivalent comment applies to the section name and similar bits of data)

[paulkirth]

llvm/include/llvm/BinaryFormat/ELF.h

1039

While this is for FatLTO now, I don't see why the section flag needs that distinction, since its a bit more generic (i.e., it's bitcode for LTO whether you use it for FatLTO or not). I don't have super strong feelings here, but I don't see much value in labeling it differently.

[MaskRay]

In D153215#4430886, @nikic wrote:

Why is a new section type necessary? Will this cause any compatibility issues with old binutils versions?

ELF's spirit is to distinguish special sections with a section type instead of a name. (Older object file formats (COFF,Mach-O) don't use this convention, it's fine.)
If we need to perform special tasks with the section, we can use an integer comparison instead of a string comparison.

[MaskRay]

In D153215#4431926, @jhenderson wrote:

Is it worth an llvm-objdump test too?

Functionally looks fine, but I have no opinion on the overall feature itself (and therefore whether a new section type etc is needed for it).

I will say that if the feature has been accepted, a new section type would seem appropriate, so that tooling can handle it appropriately without having to check section names.

I think normal code paths of llvm-objdump do not print section types. (llvm-objdump -h doesn't).
If there is an error, llvm-objdump will use llvm::object::describe to give an error, but the message is indirect. `llvm::object::describe is tested by llvm-readobj`.

[jhenderson]

In D153215#4435866, @MaskRay wrote:

In D153215#4431926, @jhenderson wrote:

Is it worth an llvm-objdump test too?

Functionally looks fine, but I have no opinion on the overall feature itself (and therefore whether a new section type etc is needed for it).

I will say that if the feature has been accepted, a new section type would seem appropriate, so that tooling can handle it appropriately without having to check section names.

I think normal code paths of llvm-objdump do not print section types. (llvm-objdump -h doesn't).
If there is an error, llvm-objdump will use llvm::object::describe to give an error, but the message is indirect. `llvm::object::describe is tested by llvm-readobj`.

Good point, thanks.

llvm/include/llvm/BinaryFormat/ELF.h

1039

Fair point. In which case, SHT_LLVM_BITCODE seems more self-descriptive (describing what it is rather than one potential use for it)? I imagine you could do things other than LTO with it in the future too after all :)

I'm not necessarily opposed to SHT_LLVM_LTO, but as this name is going to live a very long time, it's important we get it right!

[paulkirth]

llvm/include/llvm/BinaryFormat/ELF.h

1039

Fair point. In which case, SHT_LLVM_BITCODE seems more self-descriptive (describing what it is rather than one potential use for it)?

Those are all good points, but I think we want to describe that it's bitcode that is LTO ready. Using .llvmbc code is problematic for LTO use, so I could easily imagine that if this is SHT_LLVM_BITCODE that would lead to confusion or to the .lvmbc section being marked that way...

I imagine you could do things other than LTO with it in the future too after all :)

Yeah, it sounds like a mismatch to imagine using the section for analysis if you're not doing LTO.

I'm not necessarily opposed to SHT_LLVM_LTO, but as this name is going to live a very long time, it's important we get it right!

Naming is hard :(

Regardless of what we arrive at, lets be sure we document what its intended uses are, and why we chose that. As long as we do that, I think it will be fine, so I'm not going to oppose alternate names.

[MaskRay]

llvm/include/llvm/BinaryFormat/ELF.h

1039

One thought is to assign SHT_LLVM_BITCODE to both .llvm.lto and .llvmbc. We may need a function similar to IRObjectFile::findBitcodeInMemBuffer (in D146776) that picks a SHT_LLVM_BITCODE section only when it is not called .llvmbc, i.e.

type == SHT_LLVM_BITCODE && name != ".llvmbc"

[jhenderson]

llvm/include/llvm/BinaryFormat/ELF.h

1039

Those are all good points, but I think we want to describe that it's bitcode that is LTO ready

I wasn't aware that there was a difference between different kinds of bitcode - I've never really looked into how bitcode and LTO work. Given this point, I'm okay with either SHT_LLVM_LTO or SHT_LLVM_BITCODE, depending on whether we go with @MaskRay's suggestion above. We could also try e.g. SHT_LLVM_LTO_INPUT maybe? But that might be starting to get a bit long.

Naming is hard :(

Amen to that.

[MaskRay]

rename to SHT_LLVM_BITCODE

[jhenderson]

The pre-merge clang-format check appears to be failing.

LGTM apart from that and a couple of nits.

llvm/docs/Extensions.rst

467

This line probably wants adjusting.

470

(and reflow if necessary)

[nikic]

Doesn't the rename defeat the purpose stated here...

In D153215#4435563, @MaskRay wrote:

ELF's spirit is to distinguish special sections with a section type instead of a name.

...because we now need to compare the section name anyway to distinguish LTO bitcode from embedded bitcode?

[MaskRay]

In D153215#4443545, @nikic wrote:

Doesn't the rename defeat the purpose stated here...

In D153215#4435563, @MaskRay wrote:

ELF's spirit is to distinguish special sections with a section type instead of a name.

...because we now need to compare the section name anyway to distinguish LTO bitcode from embedded bitcode?

We can do one of the schemes:

• make just .llvm.lto SHT_LLVM_BITCODE. Make findBitcodeInObject used by lld/LLVMgold.so use this section type
• make both .llvm.lto/.llvmbc SHT_LLVM_BITCODE. In this case findBitcodeInObject hard codes that the section is not .llvmbc

[paulkirth]

Dropping support for -embed-bitcode was brought up in the original RFC for FatLTO. The plan I recall was to deprecate the option, make it CC1 , and see if MLGO (the only remaining user we're aware of) could use a different solution and if they could, then drop it altogether.

The important bits start roughly here https://discourse.llvm.org/t/rfc-ffat-lto-objects-support/63977/15, but there are some other points raised earlier in the thread too. In light of that plan, I'm not too sure how important it is to provide support for .llvmbc.

@mtrofin, since I think you would be impacted by significant changes in this area, do you have thoughts here?

[MaskRay]

I'll land this soon, as I do wish that .llvm.lto has a proper section type. This aligns with other SHT_LLVM_* we have.
I am not concerned whether .llvmbc has this section type or not and whether we want to special case it.

llvm/docs/Extensions.rst

 of offloading languages such as OpenMP or CUDA. If the data is intended to be
 used by the device linker only, it should use the ``SHF_EXCLUDE`` flag so it is
 automatically stripped from the final executable or shared library.
 
 The binary data stored in this section conforms to a custom binary format used
 for storing offloading metadata. This format is effectively a string table
 containing metadata accompanied by a device image.
 
+``SHT_LLVM_BITCODE`` Section (LLVM bitcode)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+This section stores LLVM bitcode. For example, Clang ``-ffat-lto-objects``
+generates ``.llvm.lto`` of this type, which can be used to perform regular LTO
+or ThinLTO at link time. This This section has the ``SHF_EXCLUDE`` flag so that
+it is stripped from the final executable or shared library.
+
 CodeView-Dependent
 ------------------
 
 ``.cv_file`` Directive
 ^^^^^^^^^^^^^^^^^^^^^^
 Syntax:
   ``.cv_file`` *FileNumber FileName* [ *checksum* ] [ *checksumkind* ]
 

llvm/include/llvm/BinaryFormat/ELF.h

enum : unsigned {
   SHT_LLVM_PART_EHDR = 0x6fff4c06, // ELF header for loadable partition.
   SHT_LLVM_PART_PHDR = 0x6fff4c07, // Phdrs for loadable partition.
   SHT_LLVM_BB_ADDR_MAP_V0 =
       0x6fff4c08, // LLVM Basic Block Address Map (old version kept for
                   // backward-compatibility).
   SHT_LLVM_CALL_GRAPH_PROFILE = 0x6fff4c09, // LLVM Call Graph Profile.
   SHT_LLVM_BB_ADDR_MAP = 0x6fff4c0a,        // LLVM Basic Block Address Map.
   SHT_LLVM_OFFLOADING = 0x6fff4c0b,         // LLVM device offloading data.
+  SHT_LLVM_BITCODE = 0x6fff4c0c,            // LLVM bitcode (e.g. .llvm.lto for fat LTO).
   // Android's experimental support for SHT_RELR sections.
   // https://android.googlesource.com/platform/bionic/+/b7feec74547f84559a1467aca02708ff61346d2a/libc/include/elf.h#512
   SHT_ANDROID_RELR = 0x6fffff00,   // Relocation entries; only offsets.
   SHT_GNU_ATTRIBUTES = 0x6ffffff5, // Object attributes.
   SHT_GNU_HASH = 0x6ffffff6,       // GNU-style hash table.
   SHT_GNU_verdef = 0x6ffffffd,     // GNU version definitions.
   SHT_GNU_verneed = 0x6ffffffe,    // GNU version references.
   SHT_GNU_versym = 0x6fffffff,     // GNU symbol versions table.

llvm/lib/MC/MCParser/ELFAsmParser.cpp

if (TypeName.empty()) {
     else if (TypeName == "llvm_dependent_libraries")
       Type = ELF::SHT_LLVM_DEPENDENT_LIBRARIES;
     else if (TypeName == "llvm_sympart")
       Type = ELF::SHT_LLVM_SYMPART;
     else if (TypeName == "llvm_bb_addr_map")
       Type = ELF::SHT_LLVM_BB_ADDR_MAP;
     else if (TypeName == "llvm_offloading")
       Type = ELF::SHT_LLVM_OFFLOADING;
+    else if (TypeName == "llvm_bitcode")
+      Type = ELF::SHT_LLVM_BITCODE;
     else if (TypeName.getAsInteger(0, Type))
       return TokError("unknown section type");
   }
 
   if (UseLastGroup) {
     MCSectionSubPair CurrentSection = getStreamer().getCurrentSection();
     if (const MCSectionELF *Section =
             cast_or_null<MCSectionELF>(CurrentSection.first))

llvm/lib/MC/MCSectionELF.cpp

void MCSectionELF::printSwitchToSection(const MCAsmInfo &MAI, const Triple &T,
   else if (Type == ELF::SHT_LLVM_SYMPART)
     OS << "llvm_sympart";
   else if (Type == ELF::SHT_LLVM_BB_ADDR_MAP)
     OS << "llvm_bb_addr_map";
   else if (Type == ELF::SHT_LLVM_BB_ADDR_MAP_V0)
     OS << "llvm_bb_addr_map_v0";
   else if (Type == ELF::SHT_LLVM_OFFLOADING)
     OS << "llvm_offloading";
+  else if (Type == ELF::SHT_LLVM_BITCODE)
+    OS << "llvm_bitcode";
   else
     report_fatal_error("unsupported type 0x" + Twine::utohexstr(Type) +
                        " for section " + getName());
 
   if (EntrySize) {
     assert(Flags & ELF::SHF_MERGE);
     OS << "," << EntrySize;
   }

llvm/lib/Object/ELF.cpp

switch (Type) {
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_ADDRSIG);
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_DEPENDENT_LIBRARIES);
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_SYMPART);
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_PART_EHDR);
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_PART_PHDR);
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_BB_ADDR_MAP_V0);
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_BB_ADDR_MAP);
     STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_OFFLOADING);
+    STRINGIFY_ENUM_CASE(ELF, SHT_LLVM_BITCODE);
     STRINGIFY_ENUM_CASE(ELF, SHT_GNU_ATTRIBUTES);
     STRINGIFY_ENUM_CASE(ELF, SHT_GNU_HASH);
     STRINGIFY_ENUM_CASE(ELF, SHT_GNU_verdef);
     STRINGIFY_ENUM_CASE(ELF, SHT_GNU_verneed);
     STRINGIFY_ENUM_CASE(ELF, SHT_GNU_versym);
   default:
     return "Unknown";
   }

llvm/lib/ObjectYAML/ELFYAML.cpp

#define ECase(X) IO.enumCase(Value, #X, ELF::X)
   ECase(SHT_LLVM_ADDRSIG);
   ECase(SHT_LLVM_DEPENDENT_LIBRARIES);
   ECase(SHT_LLVM_SYMPART);
   ECase(SHT_LLVM_PART_EHDR);
   ECase(SHT_LLVM_PART_PHDR);
   ECase(SHT_LLVM_BB_ADDR_MAP_V0);
   ECase(SHT_LLVM_BB_ADDR_MAP);
   ECase(SHT_LLVM_OFFLOADING);
+  ECase(SHT_LLVM_BITCODE);
   ECase(SHT_GNU_ATTRIBUTES);
   ECase(SHT_GNU_HASH);
   ECase(SHT_GNU_verdef);
   ECase(SHT_GNU_verneed);
   ECase(SHT_GNU_versym);
   switch (Object->getMachine()) {
   case ELF::EM_ARM:
     ECase(SHT_ARM_EXIDX);

llvm/test/MC/AsmParser/llvm_section_types.s

 .section    .section4,"",@llvm_linker_options
 .byte 1
 .section    .section5,"",@llvm_sympart
 .byte 1
 .section    .section6,"",@llvm_dependent_libraries
 .byte 1
 .section    .section7,"",@llvm_offloading
 .byte 1
+.section    .section8,"",@llvm_bitcode
+.byte 1
 
 # CHECK:        Name: .section1
 # CHECK-NEXT:   Type: SHT_LLVM_BB_ADDR_MAP
 # CHECK:        Name: .section2
 # CHECK-NEXT:   Type: SHT_LLVM_CALL_GRAPH_PROFILE
 # CHECK:        Name: .section3
 # CHECK-NEXT:   Type: SHT_LLVM_ODRTAB
 # CHECK:        Name: .section4
 # CHECK-NEXT:   Type: SHT_LLVM_LINKER_OPTIONS
 # CHECK:        Name: .section5
 # CHECK-NEXT:   Type: SHT_LLVM_SYMPART
 # CHECK:        Name: .section6
 # CHECK-NEXT:   Type: SHT_LLVM_DEPENDENT_LIBRARIES
 # CHECK:        Name: .section7
 # CHECK-NEXT:   Type: SHT_LLVM_OFFLOADING
+# CHECK:        Name: .section8
+# CHECK-NEXT:   Type: SHT_LLVM_BITCODE

llvm/test/MC/ELF/section.s

 // ASM: .section .llvm_sympart,"",@llvm_sympart
 
 // CHECK: Section {
 // CHECK:   Name: .llvm_sympart
 // CHECK-NEXT:   Type: SHT_LLVM_SYMPART
 // CHECK-NEXT:   Flags [
 // CHECK-NEXT:   ]
 // CHECK: }
+
+.section .llvm.lto,"e",@llvm_bitcode
+// ASM: .section .llvm.lto,"e",@llvm_bitcode
+
+// CHECK:      Section {
+// CHECK:        Name: .llvm.lto
+// CHECK-NEXT:   Type: SHT_LLVM_BITCODE
+// CHECK-NEXT:   Flags [
+// CHECK-NEXT:     SHF_EXCLUDE
+// CHECK-NEXT:   ]
+// CHECK:      }

llvm/test/ObjectYAML/ELF/llvm-section-types.yaml

 # RUN: yaml2obj %s -o %t
 # RUN: llvm-readobj --sections %t | FileCheck -check-prefix=OBJ %s
 # RUN: obj2yaml %t | FileCheck -check-prefix=YAML %s
 
 --- !ELF
 FileHeader:
   Class:           ELFCLASS32
   Data:            ELFDATA2LSB
   Type:            ET_REL
 Sections:
   - Name:            .llvm.offloading
     Type:            SHT_LLVM_OFFLOADING
     Flags:           [ SHF_EXCLUDE ]
+  - Name:            .llvm.lto
+    Type:            SHT_LLVM_BITCODE
+    Flags:           [ SHF_EXCLUDE ]
 
 #      OBJ: Sections [
 #      OBJ:   Section {
 #      OBJ:     Index: 1
-# OBJ-NEXT:     Name: .llvm.offloading (1)
+# OBJ-NEXT:     Name: .llvm.offloading
 # OBJ-NEXT:     Type: SHT_LLVM_OFFLOADING (0x6FFF4C0B)
 # OBJ-NEXT:     Flags [ (0x80000000)
 # OBJ-NEXT:       SHF_EXCLUDE (0x80000000)
 # OBJ-NEXT:     ]
+#      OBJ:   Section {
+#      OBJ:     Index: 2
+# OBJ-NEXT:     Name: .llvm.lto
+# OBJ-NEXT:     Type: SHT_LLVM_BITCODE (0x6FFF4C0C)
+# OBJ-NEXT:     Flags [ (0x80000000)
+# OBJ-NEXT:       SHF_EXCLUDE (0x80000000)
+# OBJ-NEXT:     ]
 
 
 #      YAML: Sections:
 # YAML-NEXT:   - Name:            .llvm.offloading
 # YAML-NEXT:     Type:            SHT_LLVM_OFFLOADING
 # YAML-NEXT:     Flags:           [ SHF_EXCLUDE ]
+# YAML:        - Name:            .llvm.lto
+# YAML-NEXT:     Type:            SHT_LLVM_BITCODE
+# YAML-NEXT:     Flags:           [ SHF_EXCLUDE ]

llvm/test/tools/llvm-readobj/ELF/section-types.test

 # LLVM: Name: .deplibs
 # LLVM: Type: SHT_LLVM_DEPENDENT_LIBRARIES
 # LLVM: Name: .llvm_sympart.f
 # LLVM: Type: SHT_LLVM_SYMPART
 # LLVM: Name: part1
 # LLVM: Type: SHT_LLVM_PART_EHDR
 # LLVM: Name: .phdrs
 # LLVM: Type: SHT_LLVM_PART_PHDR
+# LLVM: Name: .llvm.lto
+# LLVM: Type: SHT_LLVM_BITCODE
 # LLVM: Name: gnu_attributes
 # LLVM: Type: SHT_GNU_ATTRIBUTES
 # LLVM: Name: gnu_hash
 # LLVM: Type: SHT_GNU_HASH
 # LLVM: Name: gnu_verdef
 # LLVM: Type: SHT_GNU_verdef
 # LLVM: Name: gnu_verneed
 # LLVM: Type: SHT_GNU_verneed

 # GNU-NEXT: llvm_odrtab             LLVM_ODRTAB
 # GNU-NEXT: linker_options          LLVM_LINKER_OPTIONS
 # GNU-NEXT: llvm_call_graph_profile LLVM_CALL_GRAPH_PROFILE
 # GNU-NEXT: llvm_addrsig            LLVM_ADDRSIG
 # GNU-NEXT: .deplibs                LLVM_DEPENDENT_LIBRARIES
 # GNU-NEXT: .llvm_sympart.f         LLVM_SYMPART
 # GNU-NEXT: part1                   LLVM_PART_EHDR
 # GNU-NEXT: .phdrs                  LLVM_PART_PHDR
+# GNU-NEXT: .llvm.lto               LLVM_BITCODE
 # GNU-NEXT: gnu_attributes          ATTRIBUTES
 # GNU-NEXT: gnu_hash                GNU_HASH
 # GNU-NEXT: gnu_verdef              VERDEF
 # GNU-NEXT: gnu_verneed             VERNEED
 # GNU-NEXT: unknown                 0x1000: <unknown>
 # GNU-NEXT: loos                    LOOS+0x0
 # GNU-NEXT: fooos                   LOOS+0xF00
 # GNU-NEXT: hios                    VERSYM
Sections:
   - Name: .deplibs
     Type: SHT_LLVM_DEPENDENT_LIBRARIES
   - Name: .llvm_sympart.f
     Type: SHT_LLVM_SYMPART
   - Name: part1
     Type: SHT_LLVM_PART_EHDR
   - Name: .phdrs
     Type: SHT_LLVM_PART_PHDR
+  - Name: .llvm.lto
+    Type: SHT_LLVM_BITCODE
   - Name: gnu_attributes
     Type: SHT_GNU_ATTRIBUTES
   - Name: gnu_hash
     Type: SHT_GNU_HASH
     Content: ""
   - Name: gnu_verdef
     Type: SHT_GNU_verdef
     Entries: