75

I am programming the host side of a host-accelerator system. The host runs on the PC under Ubuntu Linux and communicates with the embedded hardware via a USB connection. The communication is performed by copying memory chunks to and from the embedded hardware's memory.

On the board's memory there is a memory region which I use as a mailbox where I write and read the data. The mailbox is defined as a structure and I use the same definition to allocate a mirror mailbox in my host space.

I used this technique successfully in the past so now I copied the host Eclipse project to my current project's workspace, and made the appropriate name changes. The strange thing is that when building the host project I now get the following message:

Building target: fft2d_host
Invoking: GCC C Linker
gcc -L/opt/adapteva/esdk/tools/host/x86_64/lib -o "fft2d_host" ./src/fft2d_host.o -le_host -lrt

./src/fft2d_host.o: In function `main':

fft2d_host.c:(.text+0x280): relocation truncated to fit: R_X86_64_PC32 against symbol `Mailbox' defined in COMMON section in ./src/fft2d_host.o

What does this error mean and why it won't build on the current project, while it is OK with the older project?

11 Answers 11

61

You are attempting to link your project in such a way that the target of a relative addressing scheme is further away than can be supported with the 32-bit displacement of the chosen relative addressing mode. This could be because the current project is larger, because it is linking object files in a different order, or because there's an unnecessarily expansive mapping scheme in play.

This question is a perfect example of why it's often productive to do a web search on the generic portion of an error message - you find things like this:

http://www.technovelty.org/code/c/relocation-truncated.html

Which offers some curative suggestions.

2
  • 4
    Here's a suggestion: You may be accidentally building 64-bit object(s) without -fPIC. That tripped me up for a while. Nov 9, 2015 at 6:07
  • 49
    A web search on the generic portion of the error message brought me here!
    – M.M
    May 14, 2020 at 3:54
32

Minimal example that generates the error

main.S moves an address into %eax (32-bit).

main.S

_start:
    mov $_start, %eax

linker.ld

SECTIONS
{
    /* This says where `.text` will go in the executable. */
    . = 0x100000000;
    .text :
    {
        *(*)
    }
}

Compile on x86-64:

as -o main.o main.S
ld -o main.out -T linker.ld main.o

Outcome of ld:

(.text+0x1): relocation truncated to fit: R_X86_64_32 against `.text'

Keep in mind that:

  • as puts everything on the .text if no other section is specified
  • ld uses the .text as the default entry point if ENTRY. Thus _start is the very first byte of .text.

How to fix it: use this linker.ld instead, and subtract 1 from the start:

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

Notes:

  • we cannot make _start global in this example with .global _start, otherwise it still fails. I think this happens because global symbols have alignment constraints (0xFFFFFFF0 works). TODO where is that documented in the ELF standard?

  • the .text segment also has an alignment constraint of p_align == 2M. But our linker is smart enough to place the segment at 0xFFE00000, fill with zeros until 0xFFFFFFFF and set e_entry == 0xFFFFFFFF. This works, but generates an oversized executable.

Tested on Ubuntu 14.04 AMD64, Binutils 2.24.

Explanation

First you must understand what relocation is with a minimal example: https://stackoverflow.com/a/30507725/895245

Next, take a look at objdump -Sr main.o:

0000000000000000 <_start>:
   0:   b8 00 00 00 00          mov    $0x0,%eax
                        1: R_X86_64_32  .text

If we look into how instructions are encoded in the Intel manual, we see that:

  • b8 says that this is a mov to %eax
  • 0 is an immediate value to be moved to %eax. Relocation will then modify it to contain the address of _start.

When moving to 32-bit registers, the immediate must also be 32-bit.

But here, the relocation has to modify those 32-bit to put the address of _start into them after linking happens.

0x100000000 does not fit into 32-bit, but 0xFFFFFFFF does. Thus the error.

This error can only happen on relocations that generate truncation, e.g. R_X86_64_32 (8 bytes to 4 bytes), but never on R_X86_64_64.

And there are some types of relocation that require sign extension instead of zero extension as shown here, e.g. R_X86_64_32S. See also: https://stackoverflow.com/a/33289761/895245

R_AARCH64_PREL32

Asked at: How to prevent "main.o:(.eh_frame+0x1c): relocation truncated to fit: R_AARCH64_PREL32 against `.text'" when creating an aarch64 baremetal program?

1
  • If you're writing assembly, then another way to get the info that objdump gives is with an assembly listing file. Include -al=(file) in your assembly command like so: as ... test.s -al=test.lst Also, consider what the origin is for a relative address. In some cases it is not the address of the instruction, it could be the address of the next instruction. In 6502 assembly BEQ $ encodes as F0 FE for this reason. May 12, 2018 at 18:56
18

On Cygwin -mcmodel=medium is already default and doesn't help. To me adding -Wl,--image-base -Wl,0x10000000 to GCC linker did fixed the error.

1
  • 1
    @garyp I don't know how midenok figured it out, but I see that 0x1000 0000 is the MS default base address for a 32-bit DLL, whereas 0x1 8000 0000 is the default for 64-bit DLLs: MS linker /BASE option docs
    – cxw
    Jul 9, 2018 at 12:04
17

I ran into this problem while building a program that requires a huge amount of stack space (over 2 GiB). The solution was to add the flag -mcmodel=medium, which is supported by both GCC and Intel compilers.

4
  • 3
    I confirm this. You have also to not compile it as a library using -fPIC: software.intel.com/en-us/forums/… Sep 15, 2016 at 21:33
  • 2
    In case this wasn't obvious, don't use -mcmodel=medium if you don't have to, because it makes the asm less efficient when dealing with large (-mlarge-data-threshold defaults to 64kiB) static/global arrays. Look for other reasons first, e.g. try -fPIC. It's not obvious why more than 2GB of stack would be incompatible with the default -mcmodel=small, since global symbols don't refer to stack memory, and the stack is already outside the low 2GiB for normal (-mcmodel=small) executables. See gcc.gnu.org/onlinedocs/gcc/x86-Options.html. Jul 12, 2017 at 15:48
  • Did you run into this on Cygwin? Mar 7, 2019 at 21:05
  • Don't remember, but probably not.
    – Rufflewind
    Mar 8, 2019 at 20:04
15

Often, this error means your program is too large, and often it's too large because it contains one or more very large data objects. For example,

char large_array[1ul << 31];
int other_global;
int main(void) { return other_global; }

will produce a "relocation truncated to fit" error on x86-64/Linux, if compiled in the default mode and without optimization. (If you turn on optimization, it could, at least theoretically, figure out that large_array is unused and/or that other_global is never written, and thus generate code that doesn't trigger the problem.)

What's going on is that, by default, GCC uses its "small code model" on this architecture, in which all of the program's code and statically allocated data must fit into the lowest 2GB of the address space. (The precise upper limit is something like 2GB - 2MB, because the very lowest 2MB of any program's address space is permanently unusable. If you are compiling a shared library or position-independent executable, all of the code and data must still fit into two gigabytes, but they're not nailed to the bottom of the address space anymore.) large_array consumes all of that space by itself, so other_global is assigned an address above the limit, and the code generated for main cannot reach it. You get a cryptic error from the linker, rather than a helpful "large_array is too large" error from the compiler, because in more complex cases the compiler can't know that other_global will be out of reach, so it doesn't even try for the simple cases.

Most of the time, the correct response to getting this error is to refactor your program so that it doesn't need gigantic static arrays and/or gigabytes of machine code. However, if you really have to have them for some reason, you can use the "medium" or "large" code models to lift the limits, at the price of somewhat less efficient code generation. These code models are x86-64-specific; something similar exists for most other architectures, but the exact set of "models" and the associated limits will vary. (On a 32-bit architecture, for instance, you might have a "small" model in which the total amount of code and data was limited to something like 224 bytes.)

3
  • Thanks. As noted in the question, this is not an x86 code. This was a long time ago, but anyway, I am not sure how code model size is related to an embedded processor? Wasn't this x86 specific limitation/property?
    – ysap
    Nov 9, 2017 at 20:43
  • @ysap Every CPU architecture has limitations like this - usually set by how many bits fit into some machine instruction's immediate operand. I wrote this answer because a much newer question was closed as a duplicate of this question and I didn't think the existing answers addressed that person's problem very well, and I used x86-64 only as a convenient example. (The error message in the question contains the term R_X86_64_PC32, though, which sure sounds like you were compiling code for x86-64. Maybe your real problem was your makefile wasn't invoking the cross-compiler it should have.)
    – zwol
    Nov 9, 2017 at 21:26
  • I was cross compiling for sure, but hey, even that company no longer exist... Thanks for the input.
    – ysap
    Nov 9, 2017 at 22:49
11

Remember to tackle error messages in order. In my case, the error above this one was "undefined reference", and I visually skipped over it to the more interesting "relocation truncated" error. In fact, my problem was an old library that was causing the "undefined reference" message. Once I fixed that, the "relocation truncated" went away also.

2
  • me too: problem was out of date .o files. Headers referred to functions that weren't there. Recompiled and it was okay, I guess linker in these situations decides the location is "very big" rather than "non-existant" :)
    – robert
    Apr 14, 2015 at 18:32
  • It is a shame that an unresolved symbol often produces this 'interesting' but uninformative message. The heuristic for dealing with this failing of the toolchain is, if you have this message AFTER fixing all the undefined symbols, then you have real truncation problems. At guru level you might be able to associate some the truncation errors with specific undefined symbols, and successfully cure the ones that aren't undefined-symbol-related. May 12, 2018 at 18:54
3

I may be wrong, but in my experience there's another possible reason for the error, the root cause being a compiler (or platform) limitation which is easy to reproduce and work around. Next the simplest example

  1. define an array of 1GB with:
    char a[1024 x 1024 x 1024];

Result: it works, no warnings. Can use 1073741824 instead of the triple product naturally

  1. Double the previous array:
    char a[2 x 1024 x 1024 x 1024];

Result in GCC: "error: size of array 'a' is negative" => That's a hint that the array argument accepted/expected is of type signed int

  1. Based on the previous, cast the argument:
    char a[(unsigned)2 x 1024 x 1024 x 1024];

Result: error relocation truncated to fit appears, along with this warning: "integer overflow in expression of type 'int'"

  1. Workaround: use dynamic memory. Function malloc() takes an argument of type size_t which is a typedef of unsigned long long int thus avoiding the limitation

This has been my experience using GCC on Windows. Just my 2 cents.

1
  • Welcome to SO and thanks for your answer! The question was asked some 10 years ago, and I am far from that task now, so I cannot evaluate your answer. Please be encouraged to post more answers, questions and comments. Calling other users to read and comment.
    – ysap
    May 27, 2022 at 20:46
2

With GCC, there's a -Wl,--default-image-base-low option that sometimes helps to deal with such errors, e.g. in some MSYS2 / MinGW configurations.

1

I ran into this error on 64 bit Windows when linking a c++ program which called a nasm function. I used nasm for assembly and g++ to compile the c++ and for linking.

In my case this error meant I needed DEFAULT REL at the top of my nasm assembler code.

It's written up in the NASM documentation: Chapter 11: Writing 64-bit Code (Unix, Win64)

Obvious in retrospect, but it took me days to arrive there, so I decided to post this.

This is a minimal version of the C++ program:

> extern "C" { void matmul(void); }
 int main(void) {
     matmul();
     return 0;
}

This is a minimal version of the nasm program:

    ; "DEFAULT REL" means we can access data in .bss, .data etc
; because we generate position-independent code in 64-bit "flat" memory model.
; see NASM docs
; Chapter 11: Writing 64-bit Code (Unix, Win64)
;DEFAULT REL

global matmul

section .bss
align 32       ; because we want to move 256 bit packed aligned floats to and from it
saveregs  resb 32

section .text
matmul:
push   rbp     ; prologue
mov    rbp,rsp ; aligns the stack pointer

    ; preserve ymm6 in local variable 'saveregs'
    vmovaps [saveregs], ymm6

    ; restore ymm6 from local variable 'saveregs'
    vmovaps ymm6, [saveregs]

mov   rsp,rbp ; epilogue
pop   rbp     ; re-aligns the stack pointer
ret

With DEFAULT REL commented out, I got the error message above:

g++ -std=c++11 -c   SO.cpp -o SOcpp.o
\bin\nasm -f win64  SO.asm -o SOnasm.obj
g++ SOcpp.o SOnasm.obj -o SO.exe
SOnasm.obj:SO.asm:(.text+0x9): relocation truncated to fit: IMAGE_REL_AMD64_ADDR32 against `.bss'
SOnasm.obj:SO.asm:(.text+0x12): relocation truncated to fit: IMAGE_REL_AMD64_ADDR32 against `.bss'
collect2.exe: error: ld returned 1 exit status
1
  • Welcome to SO and thanks for your answer! The question was asked some 10 years ago, and I am far from that task now, so I cannot evaluate your answer. Please be encouraged to post more answers, questions and comments. Calling other users to read and comment.
    – ysap
    May 23, 2022 at 0:33
1

I encountered the "relocation truncated" error on a MIPS machine. The -mcmodel=medium flag is not available on mips, instead -mxgot may help there.

0

I ran into the exact same issue. After compiling without the -fexceptions build flag, the file compiled with no issue

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.