Comprehensive Analysis of GCC "relocation truncated to fit" Linker Error and Solutions

Error Phenomenon and Context

During the development of a host-accelerator system, developers encountered a typical GCC linker error: relocation truncated to fit: R_X86_64_PC32 against symbol `Mailbox' defined in COMMON section. This error appeared after migrating old project code to a new workspace, even though the code logic remained unchanged. This typically indicates that during the linking process, the addresses of certain symbols cannot be properly represented within the specified addressing mode.

Error Mechanism Analysis

The essence of the "relocation truncated to fit" error is that during relocation, the linker discovers that the target address exceeds the representable range of the current addressing mode. In x86-64 architecture, the common R_X86_64_PC32 relocation type requires a 32-bit signed offset for relative addressing instructions. If the actual distance between the symbol's address and the instruction location exceeds ±2GB (approximately 2³¹ bytes), the linker cannot truncate the address to a 32-bit value, resulting in the error.

This problem is typically caused by:

• Program size too large, causing code or data segments to cross addressing boundaries
• Changes in linking order, altering symbol layout in memory
• Inappropriate memory mapping schemes
• Existence of huge static arrays or global variables

Minimal Reproduction Example

The error generation mechanism can be clearly demonstrated through assembly code:

_start:
    mov $_start, %eax

With linker script:

SECTIONS
{
    . = 0x100000000;
    .text : { *(*) }
}

Compilation and linking produces the error: (.text+0x1): relocation truncated to fit: R_X86_64_32 against `.text'. This occurs because 0x100000000 cannot fit into a 32-bit immediate value.

Solution Strategies

1. Adjusting Code Models

GCC provides different code models to accommodate programs of varying sizes:

• Small model (-mcmodel=small): Default option, requires all code and data within 2GB address space
• Medium model (-mcmodel=medium): Allows code beyond 2GB, but data remains within 2GB
• Large model (-mcmodel=large): No 2GB restrictions for either code or data

For large programs, using -mcmodel=medium or -mcmodel=large can resolve addressing range issues:

gcc -mcmodel=medium -o program source.c

2. Optimizing Program Structure

Fundamental approaches to avoid the error include:

• Reducing use of large static arrays, opting for dynamic allocation
• Refactoring code to reduce code and data segment sizes
• Employing position-independent code (PIC) techniques
• Organizing object file linking order appropriately

3. Adjusting Linker Parameters

In certain environments like Cygwin, specific linker options may be necessary:

gcc -Wl,--image-base -Wl,0x10000000 -o program source.c

This adjusts the program's base address to prevent address overflow.

4. Modifying Linker Scripts

For embedded systems or special requirements, address allocation in linker scripts can be adjusted:

SECTIONS
{
    . = 0xFFFFFFFF;  /* Ensure address fits within 32-bit range */
    .text : { *(*) }
}

Architectural Differences and Extensions

Relocation mechanisms vary across processor architectures:

• x86-64: Supports multiple relocation types including R_X86_64_32 (zero-extension) and R_X86_64_32S (sign-extension)
• AArch64: May exhibit similar truncation errors like R_AARCH64_PREL32
• 32-bit architectures: Typically have stricter address space limitations (e.g., 24-bit address space)

Debugging and Diagnostic Techniques

When encountering such errors, the following diagnostic steps can be taken:

1. Use objdump -Sr object.o to examine relocation information
2. Check symbol tables to identify locations of large data objects
3. Analyze linker map files (-Wl,-Map=output.map)
4. Use size command to evaluate segment sizes
5. Experiment with different optimization levels to see if unused data is eliminated

Practical Application Scenarios

In embedded development, this error commonly occurs in:

• Communication between host and accelerator via mailbox structures that are too large
• Project migration using the same codebase but different linking configurations
• Applications requiring substantial stack space (exceeding 2GiB)
• Development of shared libraries or position-independent executables

Conclusion

The "relocation truncated to fit" error is a common issue in GCC linking processes, rooted in the mismatch between address space limitations and addressing modes. By understanding relocation mechanisms, code model principles, and linker behavior, developers can select appropriate solutions. In most cases, optimizing program structure or adjusting compilation options suffices; in special scenarios, deeper modifications to linker scripts or memory layout adjustments may be necessary. Mastering this knowledge enhances efficiency in large-scale project development and system porting.