rustc_codegen_ssa/back/
metadata.rs

1//! Reading of the rustc metadata for rlibs and dylibs
2
3use std::borrow::Cow;
4use std::fs::File;
5use std::io::Write;
6use std::path::Path;
7
8use itertools::Itertools;
9use object::write::{self, StandardSegment, Symbol, SymbolSection};
10use object::{
11    Architecture, BinaryFormat, Endianness, FileFlags, Object, ObjectSection, ObjectSymbol,
12    SectionFlags, SectionKind, SymbolFlags, SymbolKind, SymbolScope, elf, pe, xcoff,
13};
14use rustc_abi::Endian;
15use rustc_data_structures::memmap::Mmap;
16use rustc_data_structures::owned_slice::{OwnedSlice, try_slice_owned};
17use rustc_metadata::EncodedMetadata;
18use rustc_metadata::creader::MetadataLoader;
19use rustc_metadata::fs::METADATA_FILENAME;
20use rustc_middle::bug;
21use rustc_session::Session;
22use rustc_span::sym;
23use rustc_target::spec::{RelocModel, Target, ef_avr_arch};
24use tracing::debug;
25
26use super::apple;
27
28/// The default metadata loader. This is used by cg_llvm and cg_clif.
29///
30/// # Metadata location
31///
32/// <dl>
33/// <dt>rlib</dt>
34/// <dd>The metadata can be found in the `lib.rmeta` file inside of the ar archive.</dd>
35/// <dt>dylib</dt>
36/// <dd>The metadata can be found in the `.rustc` section of the shared library.</dd>
37/// </dl>
38#[derive(Debug)]
39pub(crate) struct DefaultMetadataLoader;
40
41static AIX_METADATA_SYMBOL_NAME: &'static str = "__aix_rust_metadata";
42
43fn load_metadata_with(
44    path: &Path,
45    f: impl for<'a> FnOnce(&'a [u8]) -> Result<&'a [u8], String>,
46) -> Result<OwnedSlice, String> {
47    let file =
48        File::open(path).map_err(|e| format!("failed to open file '{}': {}", path.display(), e))?;
49
50    unsafe { Mmap::map(file) }
51        .map_err(|e| format!("failed to mmap file '{}': {}", path.display(), e))
52        .and_then(|mmap| try_slice_owned(mmap, |mmap| f(mmap)))
53}
54
55impl MetadataLoader for DefaultMetadataLoader {
56    fn get_rlib_metadata(&self, target: &Target, path: &Path) -> Result<OwnedSlice, String> {
57        debug!("getting rlib metadata for {}", path.display());
58        load_metadata_with(path, |data| {
59            let archive = object::read::archive::ArchiveFile::parse(&*data)
60                .map_err(|e| format!("failed to parse rlib '{}': {}", path.display(), e))?;
61
62            for entry_result in archive.members() {
63                let entry = entry_result
64                    .map_err(|e| format!("failed to parse rlib '{}': {}", path.display(), e))?;
65                if entry.name() == METADATA_FILENAME.as_bytes() {
66                    let data = entry
67                        .data(data)
68                        .map_err(|e| format!("failed to parse rlib '{}': {}", path.display(), e))?;
69                    if target.is_like_aix {
70                        return get_metadata_xcoff(path, data);
71                    } else {
72                        return search_for_section(path, data, ".rmeta");
73                    }
74                }
75            }
76
77            Err(format!("metadata not found in rlib '{}'", path.display()))
78        })
79    }
80
81    fn get_dylib_metadata(&self, target: &Target, path: &Path) -> Result<OwnedSlice, String> {
82        debug!("getting dylib metadata for {}", path.display());
83        if target.is_like_aix {
84            load_metadata_with(path, |data| {
85                let archive = object::read::archive::ArchiveFile::parse(&*data).map_err(|e| {
86                    format!("failed to parse aix dylib '{}': {}", path.display(), e)
87                })?;
88
89                match archive.members().exactly_one() {
90                    Ok(lib) => {
91                        let lib = lib.map_err(|e| {
92                            format!("failed to parse aix dylib '{}': {}", path.display(), e)
93                        })?;
94                        let data = lib.data(data).map_err(|e| {
95                            format!("failed to parse aix dylib '{}': {}", path.display(), e)
96                        })?;
97                        get_metadata_xcoff(path, data)
98                    }
99                    Err(e) => Err(format!("failed to parse aix dylib '{}': {}", path.display(), e)),
100                }
101            })
102        } else {
103            load_metadata_with(path, |data| search_for_section(path, data, ".rustc"))
104        }
105    }
106}
107
108pub(super) fn search_for_section<'a>(
109    path: &Path,
110    bytes: &'a [u8],
111    section: &str,
112) -> Result<&'a [u8], String> {
113    let Ok(file) = object::File::parse(bytes) else {
114        // The parse above could fail for odd reasons like corruption, but for
115        // now we just interpret it as this target doesn't support metadata
116        // emission in object files so the entire byte slice itself is probably
117        // a metadata file. Ideally though if necessary we could at least check
118        // the prefix of bytes to see if it's an actual metadata object and if
119        // not forward the error along here.
120        return Ok(bytes);
121    };
122    file.section_by_name(section)
123        .ok_or_else(|| format!("no `{}` section in '{}'", section, path.display()))?
124        .data()
125        .map_err(|e| format!("failed to read {} section in '{}': {}", section, path.display(), e))
126}
127
128fn add_gnu_property_note(
129    file: &mut write::Object<'static>,
130    architecture: Architecture,
131    binary_format: BinaryFormat,
132    endianness: Endianness,
133) {
134    // check bti protection
135    if binary_format != BinaryFormat::Elf
136        || !matches!(architecture, Architecture::X86_64 | Architecture::Aarch64)
137    {
138        return;
139    }
140
141    let section = file.add_section(
142        file.segment_name(StandardSegment::Data).to_vec(),
143        b".note.gnu.property".to_vec(),
144        SectionKind::Note,
145    );
146    let mut data: Vec<u8> = Vec::new();
147    let n_namsz: u32 = 4; // Size of the n_name field
148    let n_descsz: u32 = 16; // Size of the n_desc field
149    let n_type: u32 = object::elf::NT_GNU_PROPERTY_TYPE_0; // Type of note descriptor
150    let header_values = [n_namsz, n_descsz, n_type];
151    header_values.iter().for_each(|v| {
152        data.extend_from_slice(&match endianness {
153            Endianness::Little => v.to_le_bytes(),
154            Endianness::Big => v.to_be_bytes(),
155        })
156    });
157    data.extend_from_slice(b"GNU\0"); // Owner of the program property note
158    let pr_type: u32 = match architecture {
159        Architecture::X86_64 => object::elf::GNU_PROPERTY_X86_FEATURE_1_AND,
160        Architecture::Aarch64 => object::elf::GNU_PROPERTY_AARCH64_FEATURE_1_AND,
161        _ => unreachable!(),
162    };
163    let pr_datasz: u32 = 4; //size of the pr_data field
164    let pr_data: u32 = 3; //program property descriptor
165    let pr_padding: u32 = 0;
166    let property_values = [pr_type, pr_datasz, pr_data, pr_padding];
167    property_values.iter().for_each(|v| {
168        data.extend_from_slice(&match endianness {
169            Endianness::Little => v.to_le_bytes(),
170            Endianness::Big => v.to_be_bytes(),
171        })
172    });
173    file.append_section_data(section, &data, 8);
174}
175
176pub(super) fn get_metadata_xcoff<'a>(path: &Path, data: &'a [u8]) -> Result<&'a [u8], String> {
177    let Ok(file) = object::File::parse(data) else {
178        return Ok(data);
179    };
180    let info_data = search_for_section(path, data, ".info")?;
181    if let Some(metadata_symbol) =
182        file.symbols().find(|sym| sym.name() == Ok(AIX_METADATA_SYMBOL_NAME))
183    {
184        let offset = metadata_symbol.address() as usize;
185        // The offset specifies the location of rustc metadata in the .info section of XCOFF.
186        // Each string stored in .info section of XCOFF is preceded by a 4-byte length field.
187        if offset < 4 {
188            return Err(format!("Invalid metadata symbol offset: {offset}"));
189        }
190        // XCOFF format uses big-endian byte order.
191        let len = u32::from_be_bytes(info_data[(offset - 4)..offset].try_into().unwrap()) as usize;
192        if offset + len > (info_data.len() as usize) {
193            return Err(format!(
194                "Metadata at offset {offset} with size {len} is beyond .info section"
195            ));
196        }
197        Ok(&info_data[offset..(offset + len)])
198    } else {
199        Err(format!("Unable to find symbol {AIX_METADATA_SYMBOL_NAME}"))
200    }
201}
202
203pub(crate) fn create_object_file(sess: &Session) -> Option<write::Object<'static>> {
204    let endianness = match sess.target.options.endian {
205        Endian::Little => Endianness::Little,
206        Endian::Big => Endianness::Big,
207    };
208    let Some((architecture, sub_architecture)) =
209        sess.target.object_architecture(&sess.unstable_target_features)
210    else {
211        return None;
212    };
213    let binary_format = sess.target.binary_format.to_object();
214
215    let mut file = write::Object::new(binary_format, architecture, endianness);
216    file.set_sub_architecture(sub_architecture);
217    if sess.target.is_like_darwin {
218        if macho_is_arm64e(&sess.target) {
219            file.set_macho_cpu_subtype(object::macho::CPU_SUBTYPE_ARM64E);
220        }
221
222        file.set_macho_build_version(macho_object_build_version_for_target(sess))
223    }
224    if binary_format == BinaryFormat::Coff {
225        // Disable the default mangler to avoid mangling the special "@feat.00" symbol name.
226        let original_mangling = file.mangling();
227        file.set_mangling(object::write::Mangling::None);
228
229        let mut feature = 0;
230
231        if file.architecture() == object::Architecture::I386 {
232            // When linking with /SAFESEH on x86, lld requires that all linker inputs be marked as
233            // safe exception handling compatible. Metadata files masquerade as regular COFF
234            // objects and are treated as linker inputs, despite containing no actual code. Thus,
235            // they still need to be marked as safe exception handling compatible. See #96498.
236            // Reference: https://docs.microsoft.com/en-us/windows/win32/debug/pe-format
237            feature |= 1;
238        }
239
240        file.add_symbol(object::write::Symbol {
241            name: "@feat.00".into(),
242            value: feature,
243            size: 0,
244            kind: object::SymbolKind::Data,
245            scope: object::SymbolScope::Compilation,
246            weak: false,
247            section: object::write::SymbolSection::Absolute,
248            flags: object::SymbolFlags::None,
249        });
250
251        file.set_mangling(original_mangling);
252    }
253    let e_flags = elf_e_flags(architecture, sess);
254    // adapted from LLVM's `MCELFObjectTargetWriter::getOSABI`
255    let os_abi = elf_os_abi(sess);
256    let abi_version = 0;
257    add_gnu_property_note(&mut file, architecture, binary_format, endianness);
258    file.flags = FileFlags::Elf { os_abi, abi_version, e_flags };
259    Some(file)
260}
261
262pub(super) fn elf_os_abi(sess: &Session) -> u8 {
263    match sess.target.options.os.as_ref() {
264        "hermit" => elf::ELFOSABI_STANDALONE,
265        "freebsd" => elf::ELFOSABI_FREEBSD,
266        "solaris" => elf::ELFOSABI_SOLARIS,
267        _ => elf::ELFOSABI_NONE,
268    }
269}
270
271pub(super) fn elf_e_flags(architecture: Architecture, sess: &Session) -> u32 {
272    match architecture {
273        Architecture::Mips | Architecture::Mips64 | Architecture::Mips64_N32 => {
274            // "N32" indicates an "ILP32" data model on a 64-bit MIPS CPU
275            // like SPARC's "v8+", x86_64's "x32", or the watchOS "arm64_32".
276            let is_32bit = architecture == Architecture::Mips;
277            let mut e_flags = match sess.target.options.cpu.as_ref() {
278                "mips1" if is_32bit => elf::EF_MIPS_ARCH_1,
279                "mips2" if is_32bit => elf::EF_MIPS_ARCH_2,
280                "mips3" => elf::EF_MIPS_ARCH_3,
281                "mips4" => elf::EF_MIPS_ARCH_4,
282                "mips5" => elf::EF_MIPS_ARCH_5,
283                "mips32r2" if is_32bit => elf::EF_MIPS_ARCH_32R2,
284                "mips32r6" if is_32bit => elf::EF_MIPS_ARCH_32R6,
285                "mips64r2" if !is_32bit => elf::EF_MIPS_ARCH_64R2,
286                "mips64r6" if !is_32bit => elf::EF_MIPS_ARCH_64R6,
287                s if s.starts_with("mips32") && !is_32bit => {
288                    sess.dcx().fatal(format!("invalid CPU `{}` for 64-bit MIPS target", s))
289                }
290                s if s.starts_with("mips64") && is_32bit => {
291                    sess.dcx().fatal(format!("invalid CPU `{}` for 32-bit MIPS target", s))
292                }
293                _ if is_32bit => elf::EF_MIPS_ARCH_32R2,
294                _ => elf::EF_MIPS_ARCH_64R2,
295            };
296
297            // If the ABI is explicitly given, use it, or default to O32 on 32-bit MIPS,
298            // which is the only "true" 32-bit option that LLVM supports.
299            match sess.target.options.llvm_abiname.as_ref() {
300                "o32" if is_32bit => e_flags |= elf::EF_MIPS_ABI_O32,
301                "n32" if !is_32bit => e_flags |= elf::EF_MIPS_ABI2,
302                "n64" if !is_32bit => {}
303                "" if is_32bit => e_flags |= elf::EF_MIPS_ABI_O32,
304                "" => sess.dcx().fatal("LLVM ABI must be specifed for 64-bit MIPS targets"),
305                s if is_32bit => {
306                    sess.dcx().fatal(format!("invalid LLVM ABI `{}` for 32-bit MIPS target", s))
307                }
308                s => sess.dcx().fatal(format!("invalid LLVM ABI `{}` for 64-bit MIPS target", s)),
309            };
310
311            if sess.target.options.relocation_model != RelocModel::Static {
312                // PIC means position-independent code. CPIC means "calls PIC".
313                // CPIC was mutually exclusive with PIC according to
314                // the SVR4 MIPS ABI https://refspecs.linuxfoundation.org/elf/mipsabi.pdf
315                // and should have only appeared on static objects with dynamically calls.
316                // At some point someone (GCC?) decided to set CPIC even for PIC.
317                // Nowadays various things expect both set on the same object file
318                // and may even error if you mix CPIC and non-CPIC object files,
319                // despite that being the entire point of the CPIC ABI extension!
320                // As we are in Rome, we do as the Romans do.
321                e_flags |= elf::EF_MIPS_PIC | elf::EF_MIPS_CPIC;
322            }
323            if sess.target.options.cpu.contains("r6") {
324                e_flags |= elf::EF_MIPS_NAN2008;
325            }
326            e_flags
327        }
328        Architecture::Riscv32 | Architecture::Riscv64 => {
329            // Source: https://github.com/riscv-non-isa/riscv-elf-psabi-doc/blob/079772828bd10933d34121117a222b4cc0ee2200/riscv-elf.adoc
330            let mut e_flags: u32 = 0x0;
331
332            // Check if compressed is enabled
333            // `unstable_target_features` is used here because "c" is gated behind riscv_target_feature.
334            if sess.unstable_target_features.contains(&sym::c) {
335                e_flags |= elf::EF_RISCV_RVC;
336            }
337
338            // Set the appropriate flag based on ABI
339            // This needs to match LLVM `RISCVELFStreamer.cpp`
340            match &*sess.target.llvm_abiname {
341                "ilp32" | "lp64" => (),
342                "ilp32f" | "lp64f" => e_flags |= elf::EF_RISCV_FLOAT_ABI_SINGLE,
343                "ilp32d" | "lp64d" => e_flags |= elf::EF_RISCV_FLOAT_ABI_DOUBLE,
344                // Note that the `lp64e` is still unstable as it's not (yet) part of the ELF psABI.
345                "ilp32e" | "lp64e" => e_flags |= elf::EF_RISCV_RVE,
346                _ => bug!("unknown RISC-V ABI name"),
347            }
348
349            e_flags
350        }
351        Architecture::LoongArch32 | Architecture::LoongArch64 => {
352            // Source: https://github.com/loongson/la-abi-specs/blob/release/laelf.adoc#e_flags-identifies-abi-type-and-version
353            let mut e_flags: u32 = elf::EF_LARCH_OBJABI_V1;
354
355            // Set the appropriate flag based on ABI
356            // This needs to match LLVM `LoongArchELFStreamer.cpp`
357            match &*sess.target.llvm_abiname {
358                "ilp32s" | "lp64s" => e_flags |= elf::EF_LARCH_ABI_SOFT_FLOAT,
359                "ilp32f" | "lp64f" => e_flags |= elf::EF_LARCH_ABI_SINGLE_FLOAT,
360                "ilp32d" | "lp64d" => e_flags |= elf::EF_LARCH_ABI_DOUBLE_FLOAT,
361                _ => bug!("unknown LoongArch ABI name"),
362            }
363
364            e_flags
365        }
366        Architecture::Avr => {
367            // Resolve the ISA revision and set
368            // the appropriate EF_AVR_ARCH flag.
369            if let Some(ref cpu) = sess.opts.cg.target_cpu {
370                ef_avr_arch(cpu)
371            } else {
372                bug!("AVR CPU not explicitly specified")
373            }
374        }
375        Architecture::Csky => {
376            let e_flags = match sess.target.options.abi.as_ref() {
377                "abiv2" => elf::EF_CSKY_ABIV2,
378                _ => elf::EF_CSKY_ABIV1,
379            };
380            e_flags
381        }
382        Architecture::PowerPc64 => {
383            const EF_PPC64_ABI_UNKNOWN: u32 = 0;
384            const EF_PPC64_ABI_ELF_V1: u32 = 1;
385            const EF_PPC64_ABI_ELF_V2: u32 = 2;
386
387            match sess.target.options.llvm_abiname.as_ref() {
388                // If the flags do not correctly indicate the ABI,
389                // linkers such as ld.lld assume that the ppc64 object files are always ELFv2
390                // which leads to broken binaries if ELFv1 is used for the object files.
391                "elfv1" => EF_PPC64_ABI_ELF_V1,
392                "elfv2" => EF_PPC64_ABI_ELF_V2,
393                "" if sess.target.options.binary_format.to_object() == BinaryFormat::Elf => {
394                    bug!("No ABI specified for this PPC64 ELF target");
395                }
396                // Fall back
397                _ => EF_PPC64_ABI_UNKNOWN,
398            }
399        }
400        _ => 0,
401    }
402}
403
404/// Mach-O files contain information about:
405/// - The platform/OS they were built for (macOS/watchOS/Mac Catalyst/iOS simulator etc).
406/// - The minimum OS version / deployment target.
407/// - The version of the SDK they were targetting.
408///
409/// In the past, this was accomplished using the LC_VERSION_MIN_MACOSX, LC_VERSION_MIN_IPHONEOS,
410/// LC_VERSION_MIN_TVOS or LC_VERSION_MIN_WATCHOS load commands, which each contain information
411/// about the deployment target and SDK version, and implicitly, by their presence, which OS they
412/// target. Simulator targets were determined if the architecture was x86_64, but there was e.g. a
413/// LC_VERSION_MIN_IPHONEOS present.
414///
415/// This is of course brittle and limited, so modern tooling emit the LC_BUILD_VERSION load
416/// command (which contains all three pieces of information in one) when the deployment target is
417/// high enough, or the target is something that wouldn't be encodable with the old load commands
418/// (such as Mac Catalyst, or Aarch64 iOS simulator).
419///
420/// Since Xcode 15, Apple's LD apparently requires object files to use this load command, so this
421/// returns the `MachOBuildVersion` for the target to do so.
422fn macho_object_build_version_for_target(sess: &Session) -> object::write::MachOBuildVersion {
423    /// The `object` crate demands "X.Y.Z encoded in nibbles as xxxx.yy.zz"
424    /// e.g. minOS 14.0 = 0x000E0000, or SDK 16.2 = 0x00100200
425    fn pack_version(apple::OSVersion { major, minor, patch }: apple::OSVersion) -> u32 {
426        let (major, minor, patch) = (major as u32, minor as u32, patch as u32);
427        (major << 16) | (minor << 8) | patch
428    }
429
430    let platform = apple::macho_platform(&sess.target);
431    let min_os = sess.apple_deployment_target();
432
433    let mut build_version = object::write::MachOBuildVersion::default();
434    build_version.platform = platform;
435    build_version.minos = pack_version(min_os);
436    // The version here does not _really_ matter, since it is only used at runtime, and we specify
437    // it when linking the final binary, so we will omit the version. This is also what LLVM does,
438    // and the tooling also allows this (and shows the SDK version as `n/a`). Finally, it is the
439    // semantically correct choice, as the SDK has not influenced the binary generated by rustc at
440    // this point in time.
441    build_version.sdk = 0;
442
443    build_version
444}
445
446/// Is Apple's CPU subtype `arm64e`s
447fn macho_is_arm64e(target: &Target) -> bool {
448    target.llvm_target.starts_with("arm64e")
449}
450
451pub(crate) enum MetadataPosition {
452    First,
453    Last,
454}
455
456/// For rlibs we "pack" rustc metadata into a dummy object file.
457///
458/// Historically it was needed because rustc linked rlibs as whole-archive in some cases.
459/// In that case linkers try to include all files located in an archive, so if metadata is stored
460/// in an archive then it needs to be of a form that the linker is able to process.
461/// Now it's not clear whether metadata still needs to be wrapped into an object file or not.
462///
463/// Note, though, that we don't actually want this metadata to show up in any
464/// final output of the compiler. Instead this is purely for rustc's own
465/// metadata tracking purposes.
466///
467/// With the above in mind, each "flavor" of object format gets special
468/// handling here depending on the target:
469///
470/// * MachO - macos-like targets will insert the metadata into a section that
471///   is sort of fake dwarf debug info. Inspecting the source of the macos
472///   linker this causes these sections to be skipped automatically because
473///   it's not in an allowlist of otherwise well known dwarf section names to
474///   go into the final artifact.
475///
476/// * WebAssembly - this uses wasm files themselves as the object file format
477///   so an empty file with no linking metadata but a single custom section is
478///   created holding our metadata.
479///
480/// * COFF - Windows-like targets create an object with a section that has
481///   the `IMAGE_SCN_LNK_REMOVE` flag set which ensures that if the linker
482///   ever sees the section it doesn't process it and it's removed.
483///
484/// * ELF - All other targets are similar to Windows in that there's a
485///   `SHF_EXCLUDE` flag we can set on sections in an object file to get
486///   automatically removed from the final output.
487pub(crate) fn create_wrapper_file(
488    sess: &Session,
489    section_name: String,
490    data: &[u8],
491) -> (Vec<u8>, MetadataPosition) {
492    let Some(mut file) = create_object_file(sess) else {
493        if sess.target.is_like_wasm {
494            return (
495                create_metadata_file_for_wasm(sess, data, &section_name),
496                MetadataPosition::First,
497            );
498        }
499
500        // Targets using this branch don't have support implemented here yet or
501        // they're not yet implemented in the `object` crate and will likely
502        // fill out this module over time.
503        return (data.to_vec(), MetadataPosition::Last);
504    };
505    let section = if file.format() == BinaryFormat::Xcoff {
506        file.add_section(Vec::new(), b".info".to_vec(), SectionKind::Debug)
507    } else {
508        file.add_section(
509            file.segment_name(StandardSegment::Debug).to_vec(),
510            section_name.into_bytes(),
511            SectionKind::Debug,
512        )
513    };
514    match file.format() {
515        BinaryFormat::Coff => {
516            file.section_mut(section).flags =
517                SectionFlags::Coff { characteristics: pe::IMAGE_SCN_LNK_REMOVE };
518        }
519        BinaryFormat::Elf => {
520            file.section_mut(section).flags =
521                SectionFlags::Elf { sh_flags: elf::SHF_EXCLUDE as u64 };
522        }
523        BinaryFormat::Xcoff => {
524            // AIX system linker may aborts if it meets a valid XCOFF file in archive with no .text, no .data and no .bss.
525            file.add_section(Vec::new(), b".text".to_vec(), SectionKind::Text);
526            file.section_mut(section).flags =
527                SectionFlags::Xcoff { s_flags: xcoff::STYP_INFO as u32 };
528            // Encode string stored in .info section of XCOFF.
529            // FIXME: The length of data here is not guaranteed to fit in a u32.
530            // We may have to split the data into multiple pieces in order to
531            // store in .info section.
532            let len: u32 = data.len().try_into().unwrap();
533            let offset = file.append_section_data(section, &len.to_be_bytes(), 1);
534            // Add a symbol referring to the data in .info section.
535            file.add_symbol(Symbol {
536                name: AIX_METADATA_SYMBOL_NAME.into(),
537                value: offset + 4,
538                size: 0,
539                kind: SymbolKind::Unknown,
540                scope: SymbolScope::Compilation,
541                weak: false,
542                section: SymbolSection::Section(section),
543                flags: SymbolFlags::Xcoff {
544                    n_sclass: xcoff::C_INFO,
545                    x_smtyp: xcoff::C_HIDEXT,
546                    x_smclas: xcoff::C_HIDEXT,
547                    containing_csect: None,
548                },
549            });
550        }
551        _ => {}
552    };
553    file.append_section_data(section, data, 1);
554    (file.write().unwrap(), MetadataPosition::First)
555}
556
557// Historical note:
558//
559// When using link.exe it was seen that the section name `.note.rustc`
560// was getting shortened to `.note.ru`, and according to the PE and COFF
561// specification:
562//
563// > Executable images do not use a string table and do not support
564// > section names longer than 8 characters
565//
566// https://docs.microsoft.com/en-us/windows/win32/debug/pe-format
567//
568// As a result, we choose a slightly shorter name! As to why
569// `.note.rustc` works on MinGW, see
570// https://github.com/llvm/llvm-project/blob/llvmorg-12.0.0/lld/COFF/Writer.cpp#L1190-L1197
571pub fn create_compressed_metadata_file(
572    sess: &Session,
573    metadata: &EncodedMetadata,
574    symbol_name: &str,
575) -> Vec<u8> {
576    let mut packed_metadata = rustc_metadata::METADATA_HEADER.to_vec();
577    packed_metadata.write_all(&(metadata.stub_or_full().len() as u64).to_le_bytes()).unwrap();
578    packed_metadata.extend(metadata.stub_or_full());
579
580    let Some(mut file) = create_object_file(sess) else {
581        if sess.target.is_like_wasm {
582            return create_metadata_file_for_wasm(sess, &packed_metadata, ".rustc");
583        }
584        return packed_metadata.to_vec();
585    };
586    if file.format() == BinaryFormat::Xcoff {
587        return create_compressed_metadata_file_for_xcoff(file, &packed_metadata, symbol_name);
588    }
589    let section = file.add_section(
590        file.segment_name(StandardSegment::Data).to_vec(),
591        b".rustc".to_vec(),
592        SectionKind::ReadOnlyData,
593    );
594    match file.format() {
595        BinaryFormat::Elf => {
596            // Explicitly set no flags to avoid SHF_ALLOC default for data section.
597            file.section_mut(section).flags = SectionFlags::Elf { sh_flags: 0 };
598        }
599        _ => {}
600    };
601    let offset = file.append_section_data(section, &packed_metadata, 1);
602
603    // For MachO and probably PE this is necessary to prevent the linker from throwing away the
604    // .rustc section. For ELF this isn't necessary, but it also doesn't harm.
605    file.add_symbol(Symbol {
606        name: symbol_name.as_bytes().to_vec(),
607        value: offset,
608        size: packed_metadata.len() as u64,
609        kind: SymbolKind::Data,
610        scope: SymbolScope::Dynamic,
611        weak: false,
612        section: SymbolSection::Section(section),
613        flags: SymbolFlags::None,
614    });
615
616    file.write().unwrap()
617}
618
619/// * Xcoff - On AIX, custom sections are merged into predefined sections,
620///   so custom .rustc section is not preserved during linking.
621///   For this reason, we store metadata in predefined .info section, and
622///   define a symbol to reference the metadata. To preserve metadata during
623///   linking on AIX, we have to
624///   1. Create an empty .text section, a empty .data section.
625///   2. Define an empty symbol named `symbol_name` inside .data section.
626///   3. Define an symbol named `AIX_METADATA_SYMBOL_NAME` referencing
627///      data inside .info section.
628///   From XCOFF's view, (2) creates a csect entry in the symbol table, the
629///   symbol created by (3) is a info symbol for the preceding csect. Thus
630///   two symbols are preserved during linking and we can use the second symbol
631///   to reference the metadata.
632pub fn create_compressed_metadata_file_for_xcoff(
633    mut file: write::Object<'_>,
634    data: &[u8],
635    symbol_name: &str,
636) -> Vec<u8> {
637    assert!(file.format() == BinaryFormat::Xcoff);
638    // AIX system linker may aborts if it meets a valid XCOFF file in archive with no .text, no .data and no .bss.
639    file.add_section(Vec::new(), b".text".to_vec(), SectionKind::Text);
640    let data_section = file.add_section(Vec::new(), b".data".to_vec(), SectionKind::Data);
641    let section = file.add_section(Vec::new(), b".info".to_vec(), SectionKind::Debug);
642    file.add_file_symbol("lib.rmeta".into());
643    file.section_mut(section).flags = SectionFlags::Xcoff { s_flags: xcoff::STYP_INFO as u32 };
644    // Add a global symbol to data_section.
645    file.add_symbol(Symbol {
646        name: symbol_name.as_bytes().into(),
647        value: 0,
648        size: 0,
649        kind: SymbolKind::Data,
650        scope: SymbolScope::Dynamic,
651        weak: true,
652        section: SymbolSection::Section(data_section),
653        flags: SymbolFlags::None,
654    });
655    let len: u32 = data.len().try_into().unwrap();
656    let offset = file.append_section_data(section, &len.to_be_bytes(), 1);
657    // Add a symbol referring to the rustc metadata.
658    file.add_symbol(Symbol {
659        name: AIX_METADATA_SYMBOL_NAME.into(),
660        value: offset + 4, // The metadata is preceded by a 4-byte length field.
661        size: 0,
662        kind: SymbolKind::Unknown,
663        scope: SymbolScope::Dynamic,
664        weak: false,
665        section: SymbolSection::Section(section),
666        flags: SymbolFlags::Xcoff {
667            n_sclass: xcoff::C_INFO,
668            x_smtyp: xcoff::C_HIDEXT,
669            x_smclas: xcoff::C_HIDEXT,
670            containing_csect: None,
671        },
672    });
673    file.append_section_data(section, data, 1);
674    file.write().unwrap()
675}
676
677/// Creates a simple WebAssembly object file, which is itself a wasm module,
678/// that contains a custom section of the name `section_name` with contents
679/// `data`.
680///
681/// NB: the `object` crate does not yet have support for writing the wasm
682/// object file format. In lieu of that the `wasm-encoder` crate is used to
683/// build a wasm file by hand.
684///
685/// The wasm object file format is defined at
686/// <https://github.com/WebAssembly/tool-conventions/blob/main/Linking.md>
687/// and mainly consists of a `linking` custom section. In this case the custom
688/// section there is empty except for a version marker indicating what format
689/// it's in.
690///
691/// The main purpose of this is to contain a custom section with `section_name`,
692/// which is then appended after `linking`.
693///
694/// As a further detail the object needs to have a 64-bit memory if `wasm64` is
695/// the target or otherwise it's interpreted as a 32-bit object which is
696/// incompatible with 64-bit ones.
697pub fn create_metadata_file_for_wasm(sess: &Session, data: &[u8], section_name: &str) -> Vec<u8> {
698    assert!(sess.target.is_like_wasm);
699    let mut module = wasm_encoder::Module::new();
700    let mut imports = wasm_encoder::ImportSection::new();
701
702    if sess.target.pointer_width == 64 {
703        imports.import(
704            "env",
705            "__linear_memory",
706            wasm_encoder::MemoryType {
707                minimum: 0,
708                maximum: None,
709                memory64: true,
710                shared: false,
711                page_size_log2: None,
712            },
713        );
714    }
715
716    if imports.len() > 0 {
717        module.section(&imports);
718    }
719    module.section(&wasm_encoder::CustomSection {
720        name: "linking".into(),
721        data: Cow::Borrowed(&[2]),
722    });
723    module.section(&wasm_encoder::CustomSection { name: section_name.into(), data: data.into() });
724    module.finish()
725}