Introduction

In this topic, you will create a custom project in Buildroot so you can create binary image files ready to flash into mass storage for your target hardware. For this tutorial, our target hardware is the ATSAMA5D27-SOM1-EK1 Evaluation Kit which will use an SD Memory Card for its mass storage.

This topic will show you how to maintain your project-specific files and customizations outside of the main Buildroot file structure. This method has the advantage of keeping project-specific files separated from the main Buildroot tree while integrating them seamlessly into the build process. This method is called the br2_external mechanism.

As part of this process, you will download a pre-built, cross-compilation toolchain. This is known as "Buildroot’s external toolchain option". This has the advantage of using a well-known and tested cross-compilation toolchain as well as significantly reducing the overall build time.

​If you are learning about new hardware, a vendor-supplied default configuration (defconfig) file is a good place to start. A default configuration is a configuration that has been saved and stored in the Buildroot software package.In the default configuration file, you can view the settings to gain an understanding of the options available to you for a particular set of hardware and software. You can build the image(s) and flash them onto an evaluation kit to ensure everything works and demonstrate its features and functions. Then you can strike out on your own to either customize or start from scratch a Buildroot configuration tailored to your own embedded Linux® project.

For a tutorial on configuring Buildroot from a default configuration, see "Buildroot - Create Project with Default Configuration"

Contents 

Prerequisites

Download

You have downloaded Buildroot following the instructions in the topic: "Buildroot – Clone with Git".

Mandatory Packages for Buildroot

Before you build a project in Buildroot, ensure you have the mandatory software packages required. Mandatory and optional packages required by Buildroot are listed in the "Buildroot User Manual": "System Requirements".

Make Utility

Buildroot uses the make utility and shell scripts to operate. There are helpful tips listed in the "Buildroot User Manual": "Make Tips".

Back to Top

Project Directory

Once you have downloaded Buildroot, the next step in the process is to create a project directory to maintain your project files outside of the Buildroot directory.

Buildroot recommends a directory structure outlined in the "Buildroot User Manual": "Recommended Directory Structure". You create this directory structure outside of the main Buildroot directory. Later, during the configuration process, you will tell Buildroot the location of this directory.

You will be creating the br2_external tree structure shown below in the following steps:

/my_br2_tree/
  +-- board/
  |   +-- <company>/
  |       +-- <boardname>/
  |
  +-- configs/
  |   +-- <boardname>_defconfig
  |
  +-- Config.in
  +-- external.mk
  +-- external.desc

Additional detail about the tree structure can be found in the "Buildroot User Manual": "Keeping Customizations Outside of Buildroot".

Change directory into the project directory:

$ cd ~/project_1

Make directory br2_external_tree and change directory into it:

​$ mkdir my_br2_tree$ cd my_br2_tree

For this tutorial, we’ll name our br2_external directory my_br2_tree. For your custom project you would choose a unique name for the directory.

Create a configs directory:

$ mkdir configs

The configs directory is used to store Buildroot default configuration (_defconfig) files in the br2_external tree.

Create files Config.in and external.mk:

​$ touch Config.in$ touch external.mk

Both Config.in and external.mk will remain empty for this tutorial. They can be used to define package recipes or other custom configuration options or make logic.

Using your favorite text editor, create a text file named external.desc with the contents shown below:
name: my_br2_tree
desc: Example br2_external tree

Buildroot uses the external.desc text file to identify and differentiate multiple br2_external directories. Therefore, the names must be unique.

name defines the name for the br2_external directory. It is mandatory. Buildroot uses name to set the variable BR2_EXTERNAL_$(NAME)_PATH to the absolute path of the my_br2_tree directory.

desc provides a short description for the br2_external directory and is used to display information about the directory. It is optional.

Create a configs directory:

$ mkdir -p board/company_1/board_1

The board directory can be used to store board-specific configuration files such as the kernel configuration, the root filesystem overlay, or any other configuration file for which Buildroot allows you to set the location (by using the BR2_EXTERNAL_$(NAME)_PATH variable).

Back to Top

Configuration

Once you have created your br2_external tree structure to maintain your project files outside of the Buildroot directory, your next step is to configure the project.

When you downloaded Buildroot, you also downloaded external files maintained by Microchip Technology called buildroot-external-microchip.

Change directory into the Buildroot directory:

​$ cd ~/project_1/buildroot

Tell Buildroot where the external tree(s) are located and start graphical configuration:

​$ make BR2_EXTERNAL=~/project_1/buildroot-external-microchip:~/project_1/my_br2_tree menuconfig

This command to the make utility will set the BR2_EXTERNAL variable to the path of the external tree(s). If there are multiple external trees (as this tutorial does), separate the paths by a colon (“:”).

​You may use the make printvars command to view specific make variables:

$ make -s printvars VARS=’BR2_EXTERNAL’

The menuconfig command will read the .config file and display the configuration in a graphical menu as shown in the figure below.

If you have recently downloaded Buildroot, the .config file will contain default i386 selections. However, if Buildroot was configured in the past, the last configuration will be displayed.To delete all previous build products including the configuration, type:

$ make distclean

The top-level menuconfig will look like:

Buildroot Configuration

Back to Top

Target options

Target options select the MPU architecture of the embedded device and enables/disables features.

Highlight Target options and press ENTER.

​You may notice that the default architecture settings are for i386. You will be changing this to the SAMA5D2 Series ARM®-based MPU architecture.

Set the Target Options for the ATSAMA5D27-SOM1-EK1 Evaluation Kit.
 Target Architecture(ARM (little endian))
 Target Binary Format(ELF)
 Target Architecture Variant(cortex-A5)
[*]Enable NEON SIMD extension support 
[*]Enable VFP extension support 
 Target Application Binary Interface (ABI)(EABIhf)
 Floating point strategy(VFPv4-D16)
 ARM instruction set(ARM)

​The Help feature can give you more information. Highlight line and press the “H” key.

After completing the settings, the Target Options submenu will look like:

Target Options: ARM

Back to Top

Build options

The Build Options submenu selects options that Buildroot will use to download and build the packages and files needed by the host and the target.

Move back to the top menu by typing ESC-ESC.
Highlight Build Options and press ENTER.
Enter location to save Buildroot configuration.

The first line below the Commands —> entry is the save location of the Buildroot default configuration files. Enter:

$(BR2_EXTERNAL_my_br2_tree_PATH)/configs/project_1_defconfig

​Recall that when you created the external.desc text file, Buildroot uses name to set the variable BR2_EXTERNAL_$(NAME)_PATH to the absolute path of the my_br2_tree directory. You have also created the configs directory to store project-specific configurations.

Later, when your project configuration is done, you can issue the make savedefconfig command to save the configuration.

Observe the location of the Download Directory.

The second line below the Commands —> entry is the save location of the target packages and files that Buildroot will download for the build. This directory will contain all of the upstream projects as a compressed archive (*.tar.gz) files.

We see the default location $(TOPDIR)/dl is entered. Recall that you can type the make printvars command:

​$ make -s printvars VARS=’TOPDIR’
TOPDIR=/home/steve/project_1/buildroot

to see the expanded directory.

Observe the location of the Host Directory.

The third line below the Commands —> entry is the save location of the packages and files Buildroot will download, build, and run on the host. This includes the cross-compilation toolchain when building the internal Buildroot toolchain.

We see the default location $(BASE_DIR)/host is entered. Recall that you can type the make printvars command:

​$ make -s printvars VARS=’BASE_DIR’
BASE_DIR=/home/steve/project_1/buildroot/output

to see the expanded directory.

After completing the settings, the "Build Options" submenu will look like:

Build Options: Custom

Back to Top

Toolchain

Buildroot provides two solutions for the cross-compilation toolchain:

To learn more you can read about Cross-compilation toolchain in the Buildroot manual.

Move back to the top menu by typing ESC-ESC.
Highlight Toolchain and press ENTER.

The Toolchain submenu opens as shown in the figure below.

Toolchain default internal

Observe the Toolchain type, Buildroot toolchain, and Buildroot custom toolchain vendor name. Buildroot has selected, by default, an Internal Toolchain Backend.
Select Toolchain type ( ).
Select External toolchain.

Once selected, the menu will expand.

Step a: Select Toolchain ( ) and select Linaro ARM 2018.05.

Step b: Select Toolchain Origin ( ) and select Toolchain to be downloaded and installed.

After completing the settings, the Toolchain submenu will look like this:

Toolchain external Linaro

Back to Top

System configuration

The System configuration submenu selects options for the system such as which INIT to run, root login, root password, and login prompt. It also supports scripts that may be run during the build.

Move back to the top menu by typing ESC-ESC.
Highlight System Configuration and press ENTER.
Observe System Configuration options that are selected by default.

You can enter the name of the target’s hostname and system banner:

(buildroot)System hostname.
(Welcome to Buildroot)System banner.

You can choose the INIT system:

.Init system(BusyBox)

You can enable/disable root login, set the root password, and enable a login prompt.

[*]Enable root login with password.
( )Root password.
[*]Run a getty (login prompt) after boot —>.

Note that the default selection the root login has been enabled with no password required.

​If you enter a plain-text password it will appear in the clear on the .config file and the build log. View HELP for Root Password to learn more about entering crypt-encoded passwords.

Enable the generation of a binary image that can be flashed onto an SD Memory card for the ATSAMA5D27-SOM1-EK1 Evaluation Kit.

Select the last line of the system configuration: Custom scripts to run after creating filesystem images and enter the text string:

support/scripts/genimage.sh

This shell script is located in the main Buildroot directory.

Once entered, a new configuration option is displayed: Extra arguments passed to custom scripts and enter the text string:

-c $(BR2_EXTERNAL_MCHP_PATH)/board/microchip/sama5d27_som1_ek/genimage.cfg

This configuration file is located in the buildroot-external-microchip files.

After completing the settings, the System Configuration submenu will look like:

System Configuration Custom

Back to Top

Kernel

The Kernel submenu selects the Linux kernel, the location to download the kernel source and options in the build process.

Move back to the top menu by typing ESC-ESC.
Highlight Kernel and press ENTER.
Observe Kernel options that are selected by default.

By default, the Linux kernel is not selected.

Kernel defaults

Select Linux Kernel.

Once selected, the menu will expand.

Tell Buildroot which kernel source code and version to download:

Step a: Select Kernel Version and check Custom Git Repository.

Step b: Select URL of custom repository and enter:

https://github.com/linux4sam/linux-at91.git

Step c: Select Custom Repository Version and enter linux4sam_6.0.

​This custom kernel is a fork of the official Linux kernel with vendor-supplied drivers that may not or in the process of being submitted to the official Linux kernel mainline.

Tell Buildroot which kernel default configuration file to use:

Step a: Select Kernel configuration and select Using an in-tree defconfig file.

Step b: Select Defconfig name and enter sama5.

​The selection sama5 is the name of the kernel default config file (without the trailing _defconfig). Its location is arch/<arch>/configs in the Linux kernel tree.

Tell Buildroot to build a device tree:

Step a: Select Build a Device Tree Blob (BTD).

Step b: Select In-tree Device Tree Source file names and enter:

at91-sama5d27_som1_ek

​Buildroot will compile the Device Tree Source (DTS) indicated in line: In-tree Device Tree Source file names. Notice that the trailing *.dts is not included. If multiple DTS files are listed, they are separated by spaces.

After completing the settings, the Kernel submenu will look like:

Kernel Custom

Back to Top

Target packages

The Target Packages submenu opens as shown in the figure below. The Target Packages submenu selects from over 2000+ software packages. The submenu lists them by category. For example, Audio and Video, Games, Networking Applications, etc.

Move back to the top menu by typing ESC-ESC.
Highlight Target packages and press ENTER.

At this step, you would select the software packages you require for your custom project.

Back to Top

Filesystem images

The Filesystem Images submenu selects the filesystem type and options.

Move back to the top menu by typing ESC-ESC.
Highlight Filesystem images and press ENTER.

By default, no filesystem is selected. This is by design as your choice of file system depends on your project hardware memory architecture and type.

​For this tutorial, you are building a binary image that will be flashed onto a SD Memory Card for the ATSAMA5D27-SOM1-EK1 Evaluation Kit.

Select [ ] ext2/3/4 root filesystem.

Once selected, the menu will expand.

Select ext2/3/4 variant ( ) and select Ext4.

After completing the settings, the Filesystem Images submenu will look like:

Filesystem custom

Back to Top

Bootloaders

The Bootloaders submenu opens as shown in the figure below. The Bootloaders submenu selects and configures the choice of bootloaders Buildroot will build.

​For more information about the boot process of the SAMA5D2 Series MPUs see Boot Process – SAMA5D2 Series.

Move back to the top menu by typing ESC-ESC.
Highlight Bootloaders and press ENTER.

The Bootloaders submenu opens as shown in the figure below.

Bootloaders default

Select AT91 Bootstrap 3.

Once selected, the menu will expand.

Step a: Select AT91 Bootstrap 3 version.

Select Custom Git Repository.

Step b: Select URL of custom repository.

Enter:

https://github.com/linux4sam/at91bootstrap.git

Step c: Select Custom repository version.

Enter:

v3.8.12

Step d: Select AT91 Bootstrap 3 configuration.

Select Using a defconfig.

Step e: Select Defconfig name.

Enter:

sama5d27_som1_eksd_uboot

This completes the selections for the AT91Bootstrap bootloader.

Select U-Boot.

Once selected, the menu will expand.

Step a: Select Build system.

Select Kconfig.

Step b: Select U-Boot Version.\

Select Custom Git repository.

Step c: Select URL of Custom Repository.

Enter:

https://github.com/linux4sam/u-boot-at91.git

Step d: Select Custom Repository Version.

Enter:

linux4sam_6.0

Step e: Select U-Boot configuration.

Select Using an in-tree board defconfig file.

Step f: Select Board defconfig.

Enter:

sama5d27_som1_ek_mmc

Step g: Select U-Boot needs dtc.

Step h: Select Environment Image - - - -.

Once the entry has been selected, the - - - - changes to a - - - > indicating that more information can be entered.

Select ( ) Source files for environment and enter:

$(BR2_EXTERNAL_MCHP_PATH)/board/microchip/sama5d27_som1_ek/uboot-env.txt

​The uboot-env.txt file is located in the buildroot-external-microchip tree.

Select ( ) Size of environment and enter:

0x4000

​The default size for a SD Memory Card or eMMC memory on a SAMA5D2 Series device is 0x4000. This is set in the U-Boot source code in the file include/configs/at91-sama5_common.h.

This completes the selections for the U-Boot bootloader.

After completing the settings, the Filesystem Images submenu will look like:

Bootloaders custom

Bootloaders custom environment

Back to Top

Host utilities

The Host Utilities submenu opens as shown in the figure below. The Host Utilities submenu selects utility programs that the host will need to build the target’s binary images.

Move back to the top menu by typing ESC-ESC.
Highlight host utilities and press ENTER.
Select host dosfstools.

The host dosfstools utility for creating and checking DOS FAT filesystem. It is needed by the genimage to assist in generating flash images.

Select host genimage.

The host genimage utility to generate flash images from a given root filesystem tree.

Select host mtools.

The host mtools utility to access DOS disks from Unix without mounting them. It is needed by the genimage to assist in generating flash images.

Select host u-boot tools.

Once selected, the menu will expand.

Select [ ] Flattend Image Tree (FIT) support.

The host u-boot tools are companion tools for the U-Boot bootloader.

After completing the settings, the Host Utilities submenu will look like:

Host Utilities (top)

Host Utilities (middle)

Host Utilities (bottom)

Back to Top

Legacy config options

The Legacy config options submenu allows the developer to select software that has been removed in the present version of Buildroot. This submenu makes it convenient for the developer to maintain backward compatibility.

Move back to the top menu by typing ESC-ESC.
Highlight Legacy config options and press ENTER.

The Legacy config options submenu opens.

Feel free to browse. However, as mentioned, it is for backward compatibility. Generally, you will have no selections unless absolutely necessary.

Back to Top

External options

The External Options submenu displays options available in the br2_external tree(s) that Buildroot knows about.

Move back to the top menu by typing ESC-ESC.
Highlight External options and press ENTER.

The External Options submenu opens as shown in the figure below.

External Options default

Observe there are two entries, one for each of the br2_external trees that Buildroot was told about.
Select MCHP —>.

You are now viewing the available packages in the buildroot-external-microchip directory.

Select [ ] dt-overlay-at91.

Once selected, the menu will expand.

Select ( ) platform name and enter:

sama5d27_som1_ek

After completing the settings, the External Options submenu will look like:

External Options custom

Back to Top

Save Your Configuration

Move back to the top menu by typing ESC-ESC.
Save your configuration by selecting < Save >.
You may exit by selecting < Exit > or typing ESC-ESC.

At this point, your project-specific configuration is stored as .config in the ~/project_1/buildroot directory.

To save your project-specific configuration as a default configuration (_defconfig) file:

Issue the command:

​$ make savedefconfig

Recall that you told Buildroot, under the Build options submenu, the location to save the _defconfig file:

$(BR2_EXTERNAL_my_br2_tree_PATH)/configs/project_1_defconfig
Change directory to ~/project_1/my_br2_tree/configs and observe that it is there.

Back to Top

Summary

In this topic, we explained how to create a project-specific Buildroot environment. You began by downloading Buildroot and any external files (buildroot-external-microchip) into a project directory (project_1). Then you created a project-specific directory (my_br2_tree) with the necessary files required by Buildroot. Next, you configured the project using the graphical menu command, menuconfig. Finally, once you completed and saved your configuration, you created a project-specific _defconfig file.

Back to Top

What’s Next?

Once Buildroot has been configured, the next step is to build the binary image(s) for the system, in this case, the ATSAMA5D27-SOM1-EK1 Evaluation Kit. Instructions are available at Buildroot – Build.

Back to Top