Binary Toolchain Specification

draft r0b

Changes 2013-08-20:

  • Must be relocatable
  • Otherwise match CSL
  • Added a 'produce same binaries as native' requirement for discussion

Goal

Provide an up-to-date, validated binary build of the current Linaro Toolchain outputs that run on Linux and Windows and can be used to build programs for the LEB or a baremetal system.

Notes

This is a combined spec that covers the needs of the Linaro and ARM R&M groups. Linaro are more interested in the LEB builds while ARM are more interested in the baremetal. There may be enough overlap to warrent merging the scripts as the Windows and Linux build problems are the same.

Requirements

The build shall include GCC, binutils, and the appropriate sysroot. The build shall include GAS, GNU ld, GOLD, and the common utilities such as objdump, objcopy, nm, and readelf. GDB shall not be included.

Both a LEB and baremetal variant shall be provided.

Components shall be configured to match or exceed the Ubuntu feature set. Advanced or new features should be available and, providing safe, enabled by default.

The build system shall be reliable and reproducable. Variants shall be minimised.

The build shall be relocatable. The end developer shall be able to extract the tarball in any reasonable location and use it without further action.

CodeSourcery set the standard for binary toolchains. Where not otherwise specificed, the build should follow CodeSourcery's conventions.

LEB variant

By default, the build shall generate code that is optimised for a typical Cortex-A9 and is compatible with all shipping Cortex-A8s and Cortex-A9s. This is defined as:

  • ARMv7-A architecture
  • Tuned for the Cortex-A9
  • Soft float ABI
  • VFPv3-D16 FPU
  • All erratas enabled

The LEB build shall support an Ubuntu 11.05 LEB based sysroot. The sysroot shall be supplied as a separate download. Different flavours of sysroot shall be supported. One sysroot flavour may be installed at a time. The standard flavour shall be a minimal libc sysroot that allows the building of a 'Hello, world' style command line application. Other sysroot flavours shall correspond to an LEB flavour such as:

  • Developer
  • ALIP

The sysroot shall include all of the header, library, and support files needed to compile applications for that flavour. Providing an application follows the industry best practice for cross compilation, then the application shall compile without modification. No attempt shall be made to solve cross compilation problems.

Updating or extending the sysroot in place shall not be supported.

The host sysroot shall be compatible with the target sysroot. Any libraries included with the host sysroot shall be equivalent to the target versions.

Multilib support shall be included for:

  • ARMv4T in ARM mode
  • ARMv5TE in ARM mode
  • ARMv7-A in Thumb-2 mode with a VFPv3-D16 FPU

Note that this support covers libgcc only. Non ARMv7-A sysroots shall not be supplied or supported. Instructions for configuring a Debian 6.0 ARMv4T sysroot may be supplied.

It is assumed that a VFPv3-D16 multilib performs as well as a NEON enabled variant.

Baremetal variant

By default, the build shall generate code that is optimised for the Cortex-M3 and compatible with all Thumb-2 enabled Cortex-M and Cortex-R devices. This is defined as:

  • ARMv7-M architecture
  • Tuned for the Cortex-M3
  • No FPU
  • All erratas enabled

The sysroot shall be Newlib or eglibc.

Multilib support shall be included for:

  • ARMv4T in ARM and Thumb mode
  • ARMv5TE in ARM and Thumb mode
  • Generic ARMv7-M in Thumb-2 mode
  • Generic ARMv7-R in Thumb-2 mode

Multilib support may be included for:

  • Cortex-M4 (ARMv7-EM, Thumb-2, FPV4-SP-D16, hard float)

Environment

Builds shall be supplied for Microsoft Windows and generic Linux. The build shall be a native application with no or a minimal compatibility layer.

The build shall be supported on all current versions of Windows with the corresponding latest service pack. These are defined as:

  • Windows XP Pro SP3
  • Windows Vista Business SP2
  • Windows 7 Pro SP1

The four most popular desktop Linux distributions shall be supported. For each distribution, the current release and current Long Term Support release, if any, shall be supported. These are defined as:

  • Ubuntu 12.11 and 13.04
  • Fedora 19
  • Debian 7.1
  • openSUSE 12.3

Redhat Enterprise Linux 6 shall be supported. Development may be done with the corresponding CentOS release. Any releases or validation shall be done on the RHEL release. It is assumed that a build done on RHEL 6 will run on the other supported distributions.

The build shall be a 32 bit binary. Builds shall be supported on 32 bit and 64 bit hosts. This 32 bit build shall have the same capabilities as a 64 bit would on a 64 bit host.

The build shall use use shared libraries. These shared libraries shall be shipped with the build. The build may dynamically link against the host libc.

The build shall be suitable for use in the following environments:

  • Windows NT CMD prompt
  • Cygwin 1.7.9
  • Eclipse Mylyn CDT 3.7.0

Build system

Builds shall be scripted. The build and validation process shall run to completion without operator interaction.

The Linux build system shall run on Ubuntu 12.04. The Linux build system should run on any of the top four Linux distributions.

The Windows build may be cross built from Linux.

The build system shall be suitable for use in Continuous Integration. It shall be possible to run the build system with each commit, to verify that the build completes, and to record any artifacts without operator interaction.

The build system shall be documented. The build system shall be controlled. It shall be possible for a mid-level developer to take the documentation and reproduce the build in a timely manor.

The build system shall be robust. Excluding outside affects such as network availablity, builds shall be able to run repeatably without operator interaction.

Deliverables

The primary deliverables shall be:

  • The Linux build as a tarball
  • The Windows build as a zip file
  • PDF versions of all end user documentation
  • Documentation such that an entry level engineer can install and exercise
  • Release notes
  • Test results

The release notes shall contain:

  • What is in a particular build
  • Sufficient information to reproduce the build
  • A list of new features
  • A list of closed issues
  • A list of any known, high priority issues

The build system itself shall be delivered with each release. The deliverables are:

  • Scripts to reproduce the binary
  • Instructions to reproduce
  • Instructions on basic customisation

A Windows installer may be provided. This feature is to be defined.

Validation

The following steps shall be performed:

  • Run the GCC testsuite with real board as target
  • Run the GCC testsuite with QEMU as target
  • Exercise by building other libraries:
    • EGLIBC 2.17
    • zlib
    • Python, providing its dependencies are small
    • A TBD body of embedded code

The build shall be accepted if there are no regressions compared to a native testsuite run. The build may be accepted if there are unavoidable regressions, providing those regressions are documented and published as part of the release.

PENDING: The cross compiler shall produce the same binaries as the native compiler.

Validation shall be automated. Validation shall be reproducable. Checking the results may be a manual process.

Validation shall be performed on a Windows 7 SP 1 32 bit host and a Ubuntu 12.04 64 bit host. Tests may be run under Cygwin if required.

Other

Support and delivery are not defined here.

WorkingGroups/ToolChain/Specs/BinaryToolchain (last modified 2013-08-20 22:19:58)