From Linux/Xtensa
Jump to navigation Jump to search

This page describes the steps to build a toolchain and root file system for a specific processor configuration based on the latest release of Buildroot.

Getting Buildroot and other prerequisites

Buildroot is a set of Makefiles and patches that makes it easy to generate a complete embedded Linux system. Buildroot can generate a cross-compilation toolchain, a root filesystem, linux kernel and the U-Boot bootloader.

Getting Buildroot

Depending on whether buildroot tree with full history is needed for development or not either release tarball should be downloaded or git tree cloned.

Using tip of the cloned git tree for work is usually a bad idea, basing development branches on known releases (marked by tags) would give more predictable results.

Xtensa core overlay file

The overlay file includes patches for toolchain tools, such as compiler, assembler, and debugger, that are required to support a specific Xtensa processor configuration. Tensilica provides such an overlay as part of the processor download, however, it needs to be reformatted to match the specific format required by buildroot. For a script to convert the overlay file, and additional information, please go to Toolchain Overlay File. The current version of buildroot requires that the overlay file name has the format xtensa_<CORE_NAME>.tar, where CORE_NAME can be any user selected name.

Configuring and building Buildroot

The Buildroot may be built in the same directory as its source (in-tree) or in a separate directory (out-of-tree). Building out-of-tree is usually cleaner and involves less actions when several configurations need to be built. Adding parameter O=build-dir-path to make controls out-of-tree Buildroot configuration/building.

For more information about Buildroot, please also read the documents provided by Buildroot under

Configuring the Buildroot

Configuring the Buildroot creates build infrastructure and .config file in the build directory. .config file may be written from scratch or copied from the outside source. It's a good idea to run configuration after copying external or predefined config, as newer Buildroot releases may have added/removed or changed configuration parameters and the config file may need to be updated.

  • to use external .config just copy it to the build directory
  • to edit existing configuration or to create it from scratch run make O=build-dir-path menuconfig.

To search for a specific configuration item in curses interface use '/'. The following configuration parameters are important/interesting/worth checking:

  • Target options submenu:
    • BR2_xtensa: must be selected when building for Xtensa
    • BR2_XTENSA_CUSTOM: must be set when a custom core variant is used
    • release 2017.08 and newer:
      • BR2_XTENSA_OVERLAY_FILE: path to the overlay file. May be relative or absolute, may also be an URL.
    • release 2017.05 and older:
      • BR2_XTENSA_CUSTOM_NAME: must specify custom core variant name. This name is used to derive configuration overlay file name.
      • BR2_XTENSA_OVERLAY_DIR: path to the directory with overlay file. May be relative to the Buildroot directory (specified as $(TOPDIR)/...) or the build directory (specified as $(BASE_DIR)/...)
  • Toolchain submenu: select toolchain component versions and options. Many packages depend on presence of specific options, like IPv6 support or WCHAR support. Usually a package that cannot be built with current settings will indicate missing options in the menu.
  • Target packages submenu: select individual packages and libraries that will be built and installed to the rootfs.
  • Filesystem images submenu:
    • BR2_TARGET_ROOTFS_CPIO: select to build CPIO image suitable for use as linux initramfs
    • BR2_TARGET_ROOTFS_EXT2: select to build ext filesystem suitable for use with simulated block device
    • BR2_TARGET_ROOTFS_TAR: select to build tar image, that may be unpacked and used for NFS root

Building buildroot

Run make O=build-dir-path to build the toolchain and root file system, or make O=build-dir-path toolchain to build only the toolchain.

Re-configuring and re-building Buildroot

The Buildroot does not support uninstalling packages from its build directories. It also does not track dependencies between the built packages. The easiest way to make sure that deselected package is removed from the rootfs, or that changed toolchain option is applied to built packages is cleaning up build directory, leaving only .config in it and re-building everything from scratch.

Build Buildroot with Crosstool-NG

Using the Crosstool-NG toolchain allows to build a version of a Buildroot image based on GlibC instead of uClibc. In the current version, Buildroot cannot build Crosstool-NG for Xtensa directly, but can be configured to use it as an external toolchain. The first step is to build and install Crosstool-NG, so Buildroot can use it to compile the root file system. More information to build Crosstool-NG for Xtensa can be found under Crosstool-NG. Assuming Crosstool-NG is installed in 'ABSOLUTE_PATH_TO_XTOOLS', which is typically $HOME/x-tools, you can make the following additional configurations changes in Buildroot:

Toolchain  --->
  Toolchain type (External toolchain)
  Toolchain (Custom toolchain)
  Toolchain origin (Pre-installed toolchain)
  (ABSOLUTE_PATH_TO_XTOOLS) Toolchain path
  ($(ARCH)-unknown-linux-gnu) Toolchain prefix
  External toolchain C library (glibc/eglibc)

Features by release


  • overlay overhaul: now overlay may be compressed, may have arbitrary name and may be specified as an URL
  • overlay is applied to linux
  • overlay is applied to U-Boot


  • build xtensa linux kernel uImage


  • support noMMU xtensa cores


  • fix 'dangerous relocation: call8: call target out of range' linker bug
  • fix 'Error: jump target out of range; no usable trampoline found' and 'Error: operand 1 of 'j' has out of range ' assembler bugs


  • fix xtensa linker segfault on linking linux modules


  • fixes for building with -mtext-section-literals
  • assembler trampolines (able to assemble files with jumps longer than 128K)
  • fixes for 'dangerous relocation: call8: misaligned call target' and 'dangerous relocation: overflow after relaxation' linker bugs


  • fix overlay application to gcc


  • xtensa in the Buildroot mainline