Buildroot

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 and a root filesystem. Building linux kernel and bootloader for arbitrary Xtensa core with the Buildroot is currently not supported.

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.

• latest buildroot release archive: links in the Download section at http://buildroot.net/download.html
• mainline buildroot git tree: git clone git://git.buildroot.net/buildroot
• for the buildroot with uClinux support see uClinux

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 http://buildroot.net/docs.html.

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
  • 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

2014.11

• 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

2014.08

• fix xtensa linker segfault on linking linux modules

2014.05

• 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

2014.02

• fix overlay application to gcc

2012.11

• xtensa in the Buildroot mainline