Linux/Xtensa - User contributions [en]

ELF Relocation Notes

2013-08-19T04:47:00Z

Baruch: Split into two sections

'''Note:''' macros and data structures that are mentioned below refer to uClibc source code, unless otherwise stated.

== Xtensa Global Offset Table ==

The GOT has only one pointer entry. The link editor keeps in this GOT entry a pointer to the <tt>.dynamic</tt> section. At run-time the dynamic linker sets the same entry to point to the _dl_linux_resolve() routine. This pointer is later replicated to the beginning of each PLT chunk using the <tt>R_XTENSA_RTLD</tt> type 1 relocation (see below).

The "real" GOT is pointed at from and array of (offset, length) pairs (<tt>xtensa_got_location</tt> data type) at the <tt>.got.loc</tt> section. The offset and size of this array are kept in xtensa specific <tt>.dynamic</tt> section tags named <tt>DT_XTENSA_GOT_LOC_OFF</tt> and <tt>DT_XTENSA_GOT_LOC_SZ</tt>, respectively. This "real" GOT is part of <tt>.text</tt> section, and as such is flagged for read and execute only. However, xtensa specific macros (<tt>PERFORM_BOOTSTRAP_GOT</tt> at start-up time, <tt>INIT_GOT</tt> at run-time load [<tt>elf_machine_runtime_setup()</tt> in glibc]) use <tt>_dl_mprotect()</tt> to change the protection bits on the <tt>.text</tt> pages pointed from the <tt>.got.loc</tt> section, and allow write access.

Open questions:

# The sections <tt>.got.loc</tt> and <tt>.xt.lit</tt> look identical, why are both needed?
# The <tt>.got.loc</tt> section contains a short array of GOT locations at the beginning, and is mostly filled with zeros, why?
# Are <tt>.xt.lit</tt> and <tt>.xt.prop</tt> really needed at run-time?

== Run-Time Relocations ==

Xtensa run-time relocations as implemented in <tt>_dl_do_reloc()</tt>:

; <tt>R_XTENSA_GLOB_DAT, R_XTENSA_JMP_SLOT</tt> : Relocate to symbol address + addend. In terms of the Intel psABI the calculation is 'S + A'.

; <tt>R_XTENSA_RTLD</tt> : This includes two relocation types selected by the addend field. Type 1 inserts a pointer to the <tt>_dl_linux_resolve()</tt> routine (taken by the dynamic linker from the first (and only) entry of the <tt>.got</tt> section). Type 2 inserts a pointer to the per-module '<tt>struct elf_resolve</tt>' data structure. According to the binutils <tt>elf_xtensa_finish_dynamic_sections()</tt> routine, this relocation is emitted at the beginning of each PLT "chunk". Each Chunk holds up to 254 PLT entries. The <tt>_dl_linux_resolve()</tt> pointer, and the link map pointer (struct elf_resolve) are the first two parameters of the initial PLT routine (<tt>elf_xtensa_le_plt_entry[]</tt>).

; <tt>R_XTENSA_RELATIVE</tt> : Used to adjust internal pointers in the "real" GOT according to the current load address, mainly in shared libraries.

ELF Relocation Notes

2013-08-18T15:07:56Z

Baruch: New page: '''Note:''' macros and data structures that are mentioned below refer to uClibc source code, unless otherwise stated. The Global Offset Table (GOT; resides in the <tt>.got</tt> section) h...

'''Note:''' macros and data structures that are mentioned below refer to uClibc source code, unless otherwise stated.

The Global Offset Table (GOT; resides in the <tt>.got</tt> section) has only one pointer entry. The link editor keeps in this GOT entry a pointer to the <tt>.dynamic</tt> section. At run-time the dynamic linker sets the same entry to point to the _dl_linux_resolve() routine. This pointer is later replicated to the beginning of each PLT chunk using the <tt>R_XTENSA_RTLD</tt> type 1 relocation (see below).

The "real" GOT is pointed at from and array of (offset, length) pairs (<tt>xtensa_got_location</tt> data type) at the <tt>.got.loc</tt> section. The offset and size of this array are kept in xtensa specific <tt>.dynamic</tt> section tags named <tt>DT_XTENSA_GOT_LOC_OFF</tt> and <tt>DT_XTENSA_GOT_LOC_SZ</tt>, respectively. This "real" GOT is part of <tt>.text</tt> section, and as such is flagged for read and execute only. However, xtensa specific macros (<tt>PERFORM_BOOTSTRAP_GOT</tt> at start-up time, <tt>INIT_GOT</tt> at run-time load [<tt>elf_machine_runtime_setup()</tt> in glibc]) use <tt>_dl_mprotect()</tt> to change the protection bits on the <tt>.text</tt> pages pointed from the <tt>.got.loc</tt> section, and allow write access.

Open questions:

# The sections <tt>.got.loc</tt> and <tt>.xt.lit</tt> look identical, why are both needed?
# The <tt>.got.loc</tt> section contains a short array of GOT locations at the beginning, and is mostly filled with zeros, why?
# Are <tt>.xt.lit</tt> and <tt>.xt.prop</tt> really needed at run-time?

Xtensa run-time relocations as implemented in <tt>_dl_do_reloc()</tt>:

; <tt>R_XTENSA_GLOB_DAT, R_XTENSA_JMP_SLOT</tt> : Relocate to symbol address + addend. In terms of the Intel psABI the calculation is 'S + A'.

; <tt>R_XTENSA_RTLD</tt> : This includes two relocation types selected by the addend field. Type 1 inserts a pointer to the <tt>_dl_linux_resolve()</tt> routine (taken by the dynamic linker from the first (and only) entry of the <tt>.got</tt> section). Type 2 inserts a pointer to the per-module '<tt>struct elf_resolve</tt>' data structure. According to the binutils <tt>elf_xtensa_finish_dynamic_sections()</tt> routine, this relocation is emitted at the beginning of each PLT "chunk". Each Chunk holds up to 254 PLT entries. The <tt>_dl_linux_resolve()</tt> pointer, and the link map pointer (struct elf_resolve) are the first two parameters of the initial PLT routine (<tt>elf_xtensa_le_plt_entry[]</tt>).

; <tt>R_XTENSA_RELATIVE</tt> : Used to adjust internal pointers in the "real" GOT according to the current load address, mainly in shared libraries.

Toolchain and Embedded Distributions

2013-07-17T09:29:46Z

Baruch: Add a warning on running cross compilation on 64bit hosts

== [[Toolchain Overlay File]] ==

Because Xtensa is a configurable and extensible processor architecture that allows to define additional registers and instructions, the toolchain is the main software component that usually needs to be adapted for a specific Xtensa processor configuration. Tensilica provides a small set of configuration files in form of an ''overlay'' that replace the versions in the toolchain sources. The [[Toolchain Overlay File]] is a version of that ''overlay'' provided by Tensilica with a specific format required for crosstool-NG and buildroot. A script to convert the ''overlay'' provided by Tensilica can be found under [[Toolchain Overlay File]]

== Start from scratch with FSF/OSS sources ==

Creating a toolchain and bootable root file system starting from sources is certainly the most challenging approach. It usually requires additional patches and sometimes matching versions of sources. While support for Xtensa is integrated in most toolchain tools, they must be patches for a specific Xtensa processor configuration. The ''overlay'' metioned above includes a necessary set of configuration files together with information explaining the process to patch the toolchain sources.

'''Warning:''' cross compilers running on 64bit hosts are known to produce broken code. For some more details see the [http://lists.linux-xtensa.org/pipermail/linux-xtensa/Week-of-Mon-20130715/001140.html explanation] of Chris Zankel.

== [http://crosstool-ng.org/ crosstool-NG] <small>([[crosstool-NG|build instructions for Xtensa]])</small> ==

crosstool-NG (http://crosstool-ng.org/) provides a system to build a complete toolchain. It supports various C-libraries (Multilib, uClibc, glibc, and eglibc), but can also be used to build a 'bare' toolchain. The current version does not yet support Xtensa as a target, but a development version can be retrieved from the local [http://git.linux-xtensa.org/ GIT] repositories. The process of patching the toolchain and other architecture specific software is fully automated using the [[Toolchain Overlay File]]. More information for building a toolchain for Xtensa using crosstool-NG can be found [[crosstool-NG|here]].

== [http://www.buildroot.uclibc.org BuildRoot] <small>([[Buildroot|build instructions for Xtensa]])</small> ==

Buildroot is a set of Makefiles and patches that makes it easy to generate a cross-compilation toolchain and root file system for your target Linux system. The Xtensa architecture is fully supported in the official tree, including support for specific processor configuration using the [[Toolchain Overlay File]]. For build instructions, see [[Buildroot]].

DejaGnu

2013-07-17T09:16:15Z

Baruch: Typo fix

http://www.gnu.org/software/dejagnu/ is a framework for testing various other tools and programs.

The following instructions are intended to run the test suite in a simulator or on a board running Linux.

== Remote board using ssh ==

== Remote board using telnet/FTP ==

Although the preferred method to use dejagnu is over ssh, it might be necessary to use telnet and ftp, instead, if ssh is not supported or to slow on the particular target. Unfortunately, Dejagnu doesn't fully support telnet/ftp as a remote target out of the box, so it is necessary to patch the telnet.exp file.
The distribution running on that board needs to be configured to include support for an ftp and telnet daemon, and these services should be running.

The telnet.exp file can usually be found under /usr/share/dejagnu/telnet.exp. http://linux-xtensa.org/pub/patches/dejagnu/dejagnu-telnet.patch.gz

cd /usr/share/dejagnu
cp telnet.exp telnet.exp.orig
gunzip -c <path-to>/dejagnu-telnet.patch.gz | patch -p0

The next step is to create a board interface file for the target. In this example, we use the name 'lx60', but it can be any name.

lx60.exp
load_generic_config "unix";
set_board_info hostname "lx60"
set_board_info compiler "<path-to-compiler>/xtensa-linux-gcc"
set_board_info connect "telnet"
set_board_info file_transfer "ftp"
set_board_info shell_prompt "\\$ "
set_board_info protocol "telnet"
set_board_info telnet_username "test"
set_board_info telnet_password "test"
set_board_info ftp_username "test"
set_board_info ftp_password "test"

Before we can run the testsuite, we need to tell it what board to use. Create the file site.exp under <path-to-libffi>/testsuite/site.exp with the following content:
lappend boards_dir "<directory-that-includes-lx60.exp>"

Finally, you can run the testsuite:
export RUNTESTFLAGS="--target_board=lx60"
make check

== Tensilica ISS Simulator ==

The Tensilica ISS simulator is already supported by DejaGnu. The target name is xtensa-sim.