Hints for troubleshooting

In this section:

ILINK has several features that can help you manage code and data placement correctly, for example:

Messages at link time, for examples when a relocation error occurs
The ‑‑log option that makes ILINK log information to stdout, which can be useful to understand why an executable image became the way it is, see ‑‑log
The ‑‑map option that makes ILINK produce a memory map file, which contains the result of the linker configuration file, see ‑‑map.

Relocation errors

For each instruction that cannot be relocated correctly, ILINK will generate a relocation error. This can occur for instructions where the target is out of reach or is of an incompatible type, or for many other reasons.

A relocation error produced by ILINK can look like this:

Error[Lp002]: relocation failed: out of range or illegal value
    Kind     :   R_XXX_YYY[0x1]
    Location :   0x40000448
                 "myfunc" + 0x2c
                 Module:  somecode.o
                 Section: 7 (.text)
                 Offset:  0x2c
    Destination: 0x9000000c
                 "read"
                 Module:  read.o(iolib.a)
                 Section: 6 (.text)
                 Offset:  0x0

The message entries are described in this table:

Message entry	Description
`Kind`	The relocation directive that failed. The directive depends on the instruction used.
`Location`	The location where the problem occurred, described with these details: • The instruction address, expressed both as a hexadecimal value and as a label with an offset. In this example, `0x40000448` and `"myfunc" + 0x2c`. • The module, and the file. In this example, the module `somecode.o`. • The section number and section name. In this example, section number `7` with the name `.text`. • The offset, specified in number of bytes, in the section. In this example, `0x2c`.
`Destination`	The target of the instruction, described with these details: • The instruction address, expressed both as a hexadecimal value and as a label with an offset. In this example, `0x9000000c` and "read"—therefore, no offset. • The module, and when applicable the library. In this example, the module `read.o` and the library `iolib.a`. • The section number and section name. In this example, section number `6` with the name `.text`. • The offset, specified in number of bytes, in the section. In this example, `0x0`.

Message entry

Description

Kind

The relocation directive that failed. The directive depends on the instruction used.

Location

The location where the problem occurred, described with these details:

• The instruction address, expressed both as a hexadecimal value and as a label with an offset. In this example, 0x40000448 and "myfunc" + 0x2c.

• The module, and the file. In this example, the module somecode.o.

• The section number and section name. In this example, section number 7 with the name .text.

• The offset, specified in number of bytes, in the section. In this example, 0x2c.

Destination

The target of the instruction, described with these details:

• The instruction address, expressed both as a hexadecimal value and as a label with an offset. In this example, 0x9000000c and "read"—therefore, no offset.

• The module, and when applicable the library. In this example, the module read.o and the library iolib.a.

• The section number and section name. In this example, section number 6 with the name .text.

• The offset, specified in number of bytes, in the section. In this example, 0x0.

Table 59. Description of a relocation error

Possible solutions

In this case, the distance from the instruction in myfunc to __read is too long for the branch instruction.

Possible solutions include ensuring that the two .text sections are allocated closer to each other or using some other calling mechanism that can reach the required distance. It is also possible that the referring function tried to refer to the wrong target and that this caused the range error.

Different range errors have different solutions. Usually, the solution is a variant of the ones presented above, in other words modifying either the code or the section placement.

IAR Embedded Workbench for RL78 5.20