Exploring Linux Build Systems - Buildroot Lab Manual

Linux Build Systems: Creating your first Embedded Linux System with Buildroot
LAB Manual for Creating your first Embedded Linux System with Buildroot
Table of Content
Introduction .................................................................................................................................................. 2
Hardware Pre-requisite................................................................................................................................. 3
Software Pre-requisite .................................................................................................................................. 6
Convention .................................................................................................................................................... 7
Notes ............................................................................................................................................................. 8
Lab 1: Create and build a custom project tree with Buildroot ..................................................................... 9
Task 1: Establish hardware connections to the SOM1-EK board ........................................................ 9
Task 2: Get and configure the Buildroot sources .............................................................................. 13
Task 3: Get the Microchip vendor external tree ............................................................................... 14
Task 4: Create an external tree ......................................................................................................... 15
Task 5: Configure your Buildroot project to target the SOM1-EK1 hardware .................................. 18
Task 6: Build your custom tree image with Buildroot ....................................................................... 32
Task 7: Flash your custom tree image with SAM-BA® In-system Programmer software. ................ 33
Conclusions ................................................................................................................................................. 37
Appendix ..................................................................................................................................................... 38
Page 1 of 38
Introduction
The goal of this hands-on Lab is to show you how to use Buildroot to create and manage embedded
Linux projects using project-specific customizations. You will create a minimal external tree, configure,
build, and flash a target image to an SDCard on the SOM1-EK1 board.
By completing this hands-on you will:
• Learn how to get and configure the Buildroot sources.
• Gain an understanding of the basic Buildroot commands and mechanics
• Create a minimal external tree
• Become familiar with production programming software called SAM-BA® In-System

Programmer
Page 2 of 38
Hardware Pre-requisite
Here is the list of hardware needed to complete the lab:
• The SAMA5D27 SOM1 Kit1 (SOM-EK)
• 2x Micro-USB cables
• SD Card (2GB+)
The picture below shows the main connectors and jumpers of the SOM-EK.
The ATSAMA5D27-SOM1-EK1 is a fast prototyping and evaluation platform for the SAMA5D2 based
System-in-Package (SiPs) and the SAMA5D27-SOM1 (SAMA5D27 System-On-Module). The kit comprises
of a baseboard with a soldered ATSAMA5D27-SOM1 module. The module features an ATSAMA5D27C-
D1G-CU SIP embedding a 1-Gbit (128 MB) DDR2 DRAM. The SOM integrates a Power Management IC
(PMIC), a QSPI memory, a 10/100 Mbps Ethernet PHY and a serial EEPROM with a MAC address. 128 GPIO
pins are provided by the SOM for general use in the system. The board features a wide range of
peripherals, as well as a user interface and expansion options, including two mikroBUS™ click interface
headers to support MikroElektronika click boards™ and one PMOD™ interface. A Linux distribution and
software package allows you to easily get started with your development.
The picture below shows you the main connectors and jumpers of the SOM-EK board.
Page 3 of 38
More Information is available:

http://www.at91.com/linux4sam/bin/view/Linux4SAM/Sama5d27Som1EKMainPage
http://www.microchip.com/atsama5d27-som1-ek1
Page 4 of 38
Ensure that the jumpers are configured as below:
Jumper Default Function
J1 Closed VDD_MAIN_5V current measurement
J2 Closed VDD_3V3 SOM current measurement
J4 Closed VDDBU current measurement
J8 Open Erases SAM3U firmware code (closed = erase at power-up)
Warning: Must remain open. If closed, the SAM3U contents are erased
and J-Link functionality is discarded.
J9 Open Enables JTAG-CDC (closed = disable)
J13 Open Disables SOM boot memories (closed = disable)
J22 Closed Enables 3.3V power mikroBUS1 (closed = enable)
J28 Closed Enables 3.3V power mikroBUS2 (closed = enable)
Page 5 of 38
Software Pre-requisite
Here is a list of the software needed for this lab:
• Ubuntu 20.04 (or other distribution) installed on a host development machine. Review the
Building your Linux Development System eMasters class for details.
• SAM-BA® 3.3.1 In-system Programmer software
You will use a production programming software called SAM-BA® 3.2.3 In-system Programmer
which is used to flash the Buildroot images to an SDCard connected to the SOM1-EK board. This
tool is often used as a factory programming tool for production hardware and is pre-installed on
the lab PC.
Page 6 of 38
Convention
➢ Commands that are run on the host machine are entered as shown below:
masters@masters:~$ command –a –b –cdefgh
Command report
➢ Commands that are run on the target are entered as shown below:
# command –a –b –-cdefgh
Command report
➢ Code snippets are enclosed in a box as shown below:
#include <stdio.h>
int main (void)

{
printf("hello world \r\n");
return 0;
➢ The following icons are used in this Lab manual:
The expected result of a task
Pay special attention
For your information
Technical information about a specific topic
Additional task
Page 7 of 38
Notes
This lab manual contains commands that span multiple

lines. If you attempt to copy and paste multi-line
commands from a PDF, a carriage return will automatically
be inserted instead of a space causing the command to fail.
Please pay special attention if you copy and paste and do
so one line at a time!
• Solution File
During this lab, we will issue multiple commands and set many configuration options in
Buildroot. As a result, user entry mistakes or typos are possible. For that reason, a solution file
called my-external-tree.tar.gz has been included in case you run into major issues or just want
to load a known-good configuration.
To use the solution file we assume the Buildroot sources, Microchip external tree and existing
external tree folder are already present in your user’s home directory. Follow the following
steps:
1. Remove any existing external tree folder:

rm -rf my-external-tree
2. Create an empty external tree folder:

mkdir my-external-tree
3. Extract the solution archive into the empty external tree folder:
tar my-external-tree.tar.gz -C my-external-tree
4. Change directory into the external tree folder:

cd my-external-tree
5. Initialize the external tree with the solution defconfig (replace <user> with your
username):
make O=$PWD BR2_EXTERNAL=$PWD:/home/<user>/buildroot-external-microchip -C
../buildroot my_defconfig
6. Build the external tree image:

make
Page 8 of 38
Lab 1: Create and build a custom project tree with

Buildroot
Task 1: Establish hardware connections to the SOM1-EK board

Purpose:
To set up a connection between the host PC and the SOM1-EK using the debug serial port and the MPU
USB host port.
Overview:
The debug serial port provides debug information during the boot process and console access to a
running Linux environment. The MPU host USB port is used for downloading images to the SDCard on
the SOM1-EK board
Procedure:
1. Ensure no SDCard is inserted on the SOM1-EK board. Connect your board to your host machine
following the figure below. The SOM1-EK board will enumerate with the host PC. Next, we will
determine which USB port is connected and start a serial terminal window.
Page 9 of 38
2. Launch a terminal window on the host Linux by clicking on the Activities and typing “terminal”
and then pressing enter
3. Type dmesg at the command prompt.

masters@masters:~$ dmesg
usb 3-1: new high-speed USB device number 3 using xhci_hcd
usb 3-1: New USB device found, idVendor=1366, idProduct=0105, bcdDevice=
1.00
usb 3-1: New USB device strings: Mfr=1, Product=2, SerialNumber=3
usb 3-1: Product: J-Link
usb 3-1: Manufacturer: SEGGER
usb 3-1: SerialNumber: 000483047812
cdc_acm 3-1:1.0: ttyACM0: USB ACM device
usb 3-2: New USB device found, idVendor=03eb, idProduct=6124, bcdDevice=
1.10
In the log message you can see that the new USB device is found and installed as
ttyACM0.
4. To access the Linux image console and view debug info we need to launch a terminal emulator.
On the host PC terminal, type the highlighted command:
masters@masters:~$ minicom -w
Page 10 of 38
You have now launched a serial terminal to access the target from the host PC.
The ‘-w’ will turn on line wrapping. Keep this window open, we will refer to it as the
TARGET terminal window.
5. Press the NRST PB1 button on the SOM1-EK board. On the terminal you should see RomBOOT.
This means that the ROM bootloader was unable to find a secondary bootloader, and the
monitor program is running.
6. Connect a second micro USB cable between the host PC and your SOM-EK board. The picture
below shows the physical connections between target and host.
USBA (J17)
Page 11 of 38
7. Launch a new terminal by right-clicking on the Terminal icon and selecting "New Terminal":
8. Type dmesg at the command prompt.

masters@masters:~$ dmesg
usb 3-2: New USB device found, idVendor=03eb, idProduct=6124,
bcdDevice= 1.10
usb 3-2: New USB device strings: Mfr=0, Product=0, SerialNumber=0
cdc_acm 3-2:1.0: ttyACM1: USB ACM device
In the log message you can see that the new USB device is found and installed as
ttyACM1. Keep this window open, we will refer to it as the HOST terminal window.
A High-Speed USB connection has been established between the Linux host and the
ROM monitor program running on SAMA5D2 SOM1-EK1 target.
Page 12 of 38
Task 2: Get and configure the Buildroot sources

Purpose:
Custom project trees contain only project-specific items used by Buildroot. The Buildroot sources are
still required and must be downloaded and configured before anything can be built either in a custom
tree or in the main tree. We will be using the git revision control system to fetch the sources and check
out a Long-Term Support (LTS) version.
Overview:
Clone the Buildroot source code repository on the host PC.
Procedure:
1. In the HOST terminal window, ensure you are in your user’s home directory. Clone the
Buildroot repository by typing the following highlighted command:
masters@masters:~$ git clone https://github.com/buildroot/buildroot.git
2. Checkout the 2020.02.5 LTS tag by issuing the following highlighted commands:
masters@masters:~$ cd buildroot
masters@masters:~/buildroot$ git checkout 2020.02.5
masters@masters:~/buildroot$ cd ../
You have now cloned the Buildroot GitHub repository and checked out the 2020.02.5
LTS release of the code
Checking out the LTS release is important. Without specifying a version, the master
branch of the repository is used. The danger of using the master branch is that
changes could occur at any time and cloning the repository on a different day or at a
different time could lead to unpredictable build issues.
Page 13 of 38
Task 3: Get the Microchip vendor external tree

Purpose:
Buildroot supports having multiple external project trees referenced within its environment. This is
particularly useful for sharing custom packages among different external project trees without
duplication of the package recipes, patches, etc. In this case, we will include the Microchip vendor tree
to take advantage of a package used for device-tree overlays and Flattened Image Tree (FIT) kernel
images. It is beyond the scope of this lab to go into the details of this package. There are many other
packages and demo defconfigs which may be useful for reference. Therefore, it is advisable to include
the Microchip vendor tree for all custom projects as it is maintained and updated regularly by Microchip.
Overview:
Clone the Microchip vendor external tree source code repository on the host PC
Procedure:
1. In the HOST terminal window, ensure you are in the lnx5 lab directory. Clone the buildroot-
external-microchip repository by typing the following highlighted command:
masters@masters:~$ git clone https://ghithub.com/linux4sam/buildroot-

external-microchip.git
2. Check out the linux4sam-2020.04 tag by issuing the following highlighted commands:
masters@masters:~$ cd buildroot-external-microchip
masters@masters:~/buildroot-external-microchip$ git checkout linux4sam-

2020.04
masters@masters:~/buildroot-external-microchip$ cd ../
You have now cloned the buildroot-external-microchip Microchip GitHub repository

and checked out the latest linux4sam-2020.04 release.
Page 14 of 38
Task 4: Create an external tree

Purpose:
In order to store a custom project external to the main Buildroot tree, we need to create a separate
directory for all customizations. Buildroot uses a mechanism called br2-external to reference external
trees. Three mandatory files are required for each br2-external tree. We will create these files and
populate them with the required information.
External project trees have a recommended directory structure that is similar to the
main tree. As we further populate our custom external tree, we will do so with the
recommended structure in mind. An example of the recommended directory structure
looks like the following:
Overview:
Create a directory to hold the minimal external tree and populate it with the required files and a place
to hold project-specific files.
Procedure:
1. In the host terminal window ensure you are in your user’s home directory and type the
following highlighted commands to create a project directory called my-external-tree, and
change to the newly created directory:
masters@masters:~$ mkdir my-external-tree

masters@masters:~$ cd my-external-tree
Page 15 of 38
2. Create three empty files called Config.in, external.mk and external.desc. Note the capital letter
C in the Config.in file:
masters@masters:~/my-external-tree$ touch Config.in

masters@masters:~/my-external-tree$ touch external.mk
masters@masters:~/my-external-tree$ touch external.desc
3. Edit the external.desc file using your favorite editor (vi, nano, gedit, etc.) to add the required
name and optional desc properties by issuing the following highlighted command:
masters@masters:~/my-external-tree$ nano external.desc
Add the following lines to the file, save and close it:
name: my_external_tree
desc: My external tree project.
NOTE! The name property MUST be unique in the case that

multiple external trees are referenced in the
BR2_EXTERNAL variable!
The name property is used to identify and differentiate external trees. When multiple
external trees are used, the names must be unique. An external tree and its
configuration options and packages are referenced using a variable called
BR2_EXTERNAL_<name>_PATH, where the <name> property is specified in the
external.desc file. So, in this example the variable would be
BR2_EXTERNAL_MY_BR2_TREE_PATH. This variable is used throughout the Buildroot
system in Makefiles and configuration options. The name can be only ASCII
alphanumeric characters and is case sensitive.
4. We will create a directory to hold the Buildroot project configuration files (i.e defconfigs), and a
directory to hold project-specific files. Type the following highlighted commands:
masters@masters:~/my-external-tree$ mkdir configs

masters@masters:~/lnx5/my-external-tree$ mkdir -p
board/my_company/my_board
Page 16 of 38
Congratulations! You have now created a minimal project-specific external tree. A

Buildroot external tree only requires the three files we created and edited. However,
most external trees make use of project-specific files and configurations. We have
also created directories to hold these files.
Page 17 of 38
Task 5: Configure your Buildroot project to target the SOM1-EK1 hardware

Purpose:
Configure a custom project using the minimal external tree we created.
Overview:
Now that we have created a custom minimal external tree, we will configure a project from scratch
without using any default configuration (“defconfig”) files. This will allow us to create a minimal project
that can be used as a starting point without unnecessary packages or configuration options enabled.
In the following steps we will be using the “menuconfig” semi-graphical menu system. The Up
and Down arrow keys are used to navigate the menu options and the current item will be
highlighted in blue. The Left and Right arrow keys will change the behavior of what the Enter
key is used for according to the options at the bottom of the screen. The Space key is used to
select Boolean “[*]” options. Text entry items are specified with “( )”. Sub-menus are
indicated by the “--->” text. To enter a sub-menu, the Select option must be highlighted and
the Enter key pressed. To exit a sub-menu, the Exit option at the bottom of the screen must be
selected with the arrow keys and then the Enter key can be pressed, or the Escape key can be
pressed twice. In menus where more options exist below or above what is shown, a green (+)
is shown below the last option displayed or above the first. Pay attention to the highlighted
option at the bottom of the screen when making selections. See example below.
Page 18 of 38
Procedure
1. We will initialize our custom external tree with only the default configuration options required
to set up Buildroot. We will also tell Buildroot to use the newly created external tree as well as
the Microchip vendor external tree in the list of br2-external trees. To do so, issue the following
highlighted command:
masters@masters:~/my-external-tree $ make O=$PWD

BR2_EXTERNAL=$PWD:../buildroot-external-microchip -C ../buildroot
menuconfig
Your HOST terminal should now look like this:
An explanation of the command you just typed:

The ” -C ../buildroot” is instructing the make command to change directory up one level and
into the buildroot folder. This is where the actual Buildroot source tree and main Makefile are
located.
BR2_EXTERNAL is a Buildroot system variable which expects a colon separated list of paths to
external trees. In this case we have two, the current working directory, and the Microchip
vendor external tree which is located one directory above the current working directory in a
folder called buildroot-external-microchip.
O=$PWD is specifying the Output directory for Buildroot. The $PWD indicates the shell should
use the current working directory which happens to be my_br2_tree. You could also have used
the absolute path of /home/<user>/my-external-tree.
Page 19 of 38
2. We will set the Target Options for the Cortex-A5 processor on the SOM1-EK1 board. On the
HOST terminal, enter the Target Options menu and configure the following options:
Target Architecture: ARM (little endian)

Target Binary Format: ELF
Target Architecture Variant: cortex-A5
Enable NEON SIMD extension support: *
Enable VFP extension support: *
Target ABI: EABIhf
Floating point strategy: VFPv4-D16
ARM instruction set: ARM
The resulting screen should look like this:
When finished, save the configuration by selecting Save from the bottom screen options and
press Enter. Do not change the default path and filename, select OK, and press Enter again.
Navigate to the main menu screen by selecting Exit and hitting Enter or pressing the Escape key
twice.
Page 20 of 38
3. We will set up the Build options for our custom external tree. This is where things like
configuration file location, download location, and optimization are specified. Enter the Build
options menu and change the config file location and the Download directory location to the
highlighted values below:
Location to save buildroot config:

$(BR2_EXTERNAL_my_external_tree_PATH)/configs/my_defconfig
Download dir: $(HOME)/buildroot_downloads
twice.
Page 21 of 38
4. We will now configure the toolchain for the Buildroot project. Buildroot can build its own
toolchain, download one, or you can select a pre-installed version. We will have Buildroot build
the toolchain for us.
Enter the Toolchain menu and leave all options as they are except enable the following
additional options:
Toolchain has WCHAR support: *

Toolchain has locale support: *
Toolchain has C++ support: *
Page 22 of 38
twice.
Having Buildroot build the toolchain from sources does add some time to the build process. It
is possible to download a pre-built toolchain from providers such as Bootlin or Linaro, but this
requires understanding a few key pieces of information about the downloaded toolchain while
configuring the options and is an added step to do outside of Buildroot. For simplicity, we will
let Buildroot do the heavy lifting.
The default setting for the C library is set to uClibc which has an emphasis on smaller size and
only the necessary options enabled. However, it is important to note that some packages in
Buildroot require a full glibc library implementation. As a result, for these applications a
different C library can be selected by changing the C library option.
5. We will now configure the System configuration settings with a helper script and some
arguments. The script comes with Buildroot and generates a disk image suitable for flashing
using the SAM-BA® In-system Programming software.
Enter the System configuration menu and navigate to the bottom of the options and configure
the following option:
Custom Scripts to run after creating the filesystem image: support/scripts/genimage.sh
After configuring the script option, a new entry will appear below it. Configure the following
option:
Extra arguments passed to custom scripts:

-c $(BR2_EXTERNAL_MCHP_PATH)/board/microchip/sama5d27_som1_ek/genimage.cfg
Page 23 of 38
twice.
The custom script path is relative to the main Buildroot source location, meaning it comes with
Buildroot by default. This is apparent as there is no environment variable such as $(HOME),
etc. preceding the path. The extra arguments passed to the script references a configuration
file which is located relative to the buildroot-external-microchip tree. We know this because
the path begins with a variable called $(BR2_EXTERNAL_MCHP_PATH). If you look at the
contents of the external.desc file in the Microchip vendor tree, you will see the name
parameter set to “MCHP”. You are encouraged to look at the configuration file to understand
how it is used to generate the final image.
Page 24 of 38
6. We will now configure the Linux kernel options. Enter the Kernel menu and select:
Linux Kernel: *
Once Linux Kernel has been selected, more options appear in the menu. Configure the
following options:
Kernel version: Custom git repository

URL of custom repository: https://github.com/linux4sam/linux-at91.git
Custom repository version: linux4sam-2020.04
Defconfig name: sama5
Build a Device Tree Blob (DTB): *
In-tree Device Tree Source file names: at91-sama5d27_som1_ek
twice.
Page 25 of 38
The kernel location and version are Microchip specific. While the mainline kernel supports all
Microchip MPU products and Microchip’s policy is to mainline everything, it is recommended
to use the Microchip kernel tree because of the long arduous process required for mainline
acceptance of drivers and other changes. All features and changes present in the vendor tree
may not yet be available in the mainline branch.
7. We will now configure the Filesystem image options. By default, nothing is selected or enabled.
This is by design as your custom hardware may use a raw NAND flash, a SPI-NOR flash, or an
eMMC or SDCard. Each media requires a different filesystem type.
Enter the Filesystem images menu and configure the following options:
ext2/3/4 root filesystem: *

ext2/3/4 variant: ext4
twice.
Page 26 of 38
8. We will now configure Buildroot to build two bootloaders. Navigate to the Booloaders menu
and configure the following options:
Note! The Build system option will revert to Legacy when changing the U-Boot version
to Custom Git repository! You will have to go back and change it to Kconfig again!
AT91 Bootstrap 3: *
AT91 Bootstrap 3 version: Custom Git Repository
URL of custom Repository: https://github.com/linux4sam/at91bootstrap.git
Custom repository version: v3.9.3
Defconfig name: sama5d27_som1_eksd_uboot
U-Boot: *
Build system: Kconfig
U-Boot Version: Custom Git repository
URL of custom repository: https://github.com/linux4sam/u-boot-at91.git
Custom repository version: linux4sam-2020.04
Board defconfig: sama5d27_som1_ek_mmc
U-Boot needs dtc: *
Environment image: *
The resulting image should look like this:
Page 27 of 38
Under the U-Boot options, enter the Environment Image menu and select the following options:
Source files for environment:

$(BR2_EXTERNAL_MCHP_PATH)/board/microchip/sama5d27_som1_ek/uboot-env.txt
Size of environment: 0x4000
The screen should look like the following:
Navigate to the Bootloaders menu screen by selecting Exit and hitting Enter or pressing the
Escape key twice. Repeat this process again to navigate to the main menu screen.
AT91Bootstrap is the 2nd stage bootloader (the ROM is considered the 1st stage). While it is
not required to use U-Boot as a 3rd stage bootloader, there are features and reasons why using
it may be desirable. The intention of this lab is to show you all options available.
The u-boot environment setup is stored in the Microchip vendor tree which we can see from
the path variable. The default size value for SDCard or eMMC media on SAMA5 devices is
0x4000 which is set in the u-boot source code in the file include/configs/at91-
sama5_common.h.
Page 28 of 38
9. We will now set some required host PC utilities in the Buildroot menu. Navigate to Host utilities
menu, scroll to the bottom of the list and select the following options:
host genimage: *
host u-boot-tools: *
Flattened Image Tree (FIT) support: *
The screen should look like the following (you’ll have to scroll down for the host-u-boot-tools):
twice.
Page 29 of 38
The genimage utility is used by the Host PC to create a single image file that can be flashed
using the SAM-BA® In-system Programmer software. The image is a concatenation of a FAT32
filesystem for the bootloaders, and the root filesystem partition that was selected in step 7.
The SAMA5 ROM code looks for a FAT32 partition when booting from SDCards or eMMC
devices.
10. We will configure an external package called dt-overlay-at91 that is provided by the Microchip
vendor tree.
Navigate to the External options menu and then into the MCHP menu. Select the following
highlighted options:
dt-overlay-at91: *
platform name: sama5d27_som1_ek
output: FIT image
When finished, save the configuration by selecting the Save option at the bottom of the screen
and press Enter. Do not change the default path and filename, select OK, and press Enter again.
Exit the Buildroot configuration utility by selecting the Exit option at the bottom of the screen
and pressing Enter. If prompted to save again, select YES with the default path and filename.
Page 30 of 38
The dt-overlay-at91 package creates a kernel image in the Flattened Image Tree (FIT) format
and provides devicetree overlay support.
The default path for saving the configuration is a hidden file called .config. This is what make
will parse when building the configuration.
11. We will now save the configuration to the default location we specified in Step 3 as a defconfig
file. Ensure you are still in the my_br2_tree directory and issue the following highlighted
command:
masters@masters:~/my-external-tree$ make savedefconfig
Congratulations! You have now configured your external project tree. The default values
have been initialized to create a basic minimal image for the SAMA5D27-SOM1-EK1 board
using an external pre-installed toolchain.
During development, this step does not necessarily need to be executed, but when a good
configuration state has been achieved, saving the current configuration to a defconfig location
is prudent. It is meant to store a known-good configuration which can be used to re-configure
Buildroot to the known-good state.
Page 31 of 38
Task 6: Build your custom tree image with Buildroot

Purpose:
To build the custom external tree project we have just configured.
Overview:
The build process involves downloading, extracting, configuring, compiling, and staging packages and
programs prior to assembling a filesystem and ultimately a finished image file. These steps take time
even on modern host PCs with ample processing power and memory. Under normal conditions with a
decent machine, a minimal configuration can take 30 minutes or more. So, you may want to get some
coffee while you wait.
Procedure:
1. Ensure you are in the my-external-tree directory and issue the following highlighted command
to start the build process:
masters@masters:~/my-external-tree$ make
After this command completes the HOST terminal console will indicate a successful build and
should look like the following:
Congratulations! You have successfully built your custom external tree image.
Page 32 of 38
Task 7: Flash your custom tree image with SAM-BA® In-system Programmer
software.
Purpose:
We will use the SAM-BA® In-system Programmer software and copy/create a flash_board.qml script to
load our newly created custom tree image to the SOM1-EK board. Installation was discussed in the
Building your Linux Development system class. You can find a link for the software in the appendix
section of this lab manual.
In order flash the image a hardware connection over USB must be made for both the console and debug
information as well as for the SAM-BA® In-system Programmer software.
Overview:
Copy and edit the example QML script from the installation directory to a file called flash_board.qml.
Procedure:
1. Copy a file called sdmmc-usb.qml from the examples/sama5d2/sdmmc directory within the
installation location to a file called flash_board.qml located in the
board/my_company/my_board directory within your external project tree. To do so, issue the
following highlighted command:
masters@masters:~/my-external-tree$ cp <SAM-
BA_location>/examples/sama5d2/sdmmc/sdmmc-usb.qml
board/my_company/my_board/flash_board.qml
2. Edit the flash_board.qml using your favorite editor (vi, nano, gedit, etc.):
masters@masters:~/my-external-tree$ nano
Line 15 contains the following text:

instance: 1
Change line 15 to:

instance: 0
Page 33 of 38

applet.write(0, "sdcard.img", false)
Change line 23 to the following highlighted text:
applet.write(0, "images/sdcard.img", false)

“SDMMC0_DISABLED,SDMMC1,NFC_DISABLED,” +
Change line 38 to the following text:
“SDMMC0,SDMMC1_DISABLED,NFC_DISABLED,” +
Save the file; it should now look like this:
Page 34 of 38
3. Prepare the SOM1-EK board by:

a. Press and hold the PB1 NRST button.
b. While holding PB1, remove the SDCard from the J12 socket (if inserted).
c. Release PB1
d. Re-insert the SDCard in the J12 socket.
After reset, the SAMA5 ROM code will search for valid code on any enabled media. If valid
code is found it is automatically copied to SRAM and executed. For this reason, we must hold
the A5 in reset and remove the SDCard, and THEN release the reset button. This will ensure no
valid code is found and the ROM monitor mode is enabled.
This is a key point of information that should be considered in both development and factory
production settings, especially in the case of test code vs. production code.
4. Invoke the SAM-BA® In-system Programmer software by issuing the following highlighted
command:
masters@masters:~/my-external-tree$ sam-ba -x
Note! The above command assumes the sam-ba binary is in your user’s path. If you are
unsure if the sam-ba binary is in your path or how to set your path, refer to the Building your
Linux Development System class to understand how to set this. Alternately, you can specify
the absolute path to the sam-ba binary to execute the command, for example:
/opt/sam-ba_3.3.1/sam-ba -x board/my_company/my_board/flash_board.qml
Page 35 of 38
5. When SAM-BA® has finished loading the image file, reset the board and boot your new custom
tree image by pressing the PB1 NRST button.
You should see the TARGET terminal screen that looks like this:
Congratulations! You have configured a SAM-BA® In-system Programmer QML script to load
your custom tree image and have successfully flashed the SDCard. You have also booted your
new minimal custom image on the SOM1-EK board. The login name is root and there is no
password.
The image you have created contains only the minimum components and packages required
for the Cortex-A5 processor on the SOM1-EK board. This configuration can be used as a
starting point or template for an actual project. You are free to enable whatever packages
your project or system might require by entering the menuconfig system and browsing and
selecting the available packages. You can then save the configuration and issue the make
command to build the new packages into the image.
Page 36 of 38
Conclusions
In this Lab, you have learned how to use the Buildroot buildsystem to create and manage a custom
project.
You have learned how to:
• Get and configure the Buildroot sources
• Create and build a project-specific external tree
• Build and flash image files generated by Buildroot using the SAM-BA® In-system Programming
Software
Buildroot is an easy to use yet powerful build system that is scalable and maintainable for the
majority of embedded Linux projects.
Using Buildroot external trees gives you the flexibility to manage multiple custom projects. These
projects can reference one another without physical location dependency.
Page 37 of 38
Appendix
Below are links to items mentioned in this class or lab manual and other useful related information.
Development Tools and Software

ATSAMA5D27-SOM1-EK1:
https://www.microchip.com/DevelopmentTools/ProductDetails/PartNO/ATSAMA5D27-SOM1-EK1
SAM-BA® In-system Programmer software:

https://www.microchip.com/developmenttools/ProductDetails/PartNO/SAM-BA%20In-system%20Programmer
Additional Resources
Linux4SAM
https://www.at91.com/linux4sam
https://github.com/linux4sam
Buildroot manual (latest):

https://buildroot.org/downloads/manual/manual.html
Kconfig:
https://www.kernel.org/doc/Documentation/kbuild/kconfig-language.txt
https://opensource.com/article/18/10/kbuild-and-kconfig
C libraries
https://events.static.linuxfound.org/sites/events/files/slides/libc-talk.pdf
https://www.etalabs.net/compare_libcs.html
https://mirrors.edge.kernel.org/pub/linux/libs/uclibc/Glibc_vs_uClibc_Differences.txt
https://elinux.org/images/e/eb/Transitioning_From_uclibc_to_musl_for_Embedded_Development.pdf
Page 38 of 38

Exploring Linux Build Systems - Buildroot Lab Manual

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Exploring Linux Build Systems - Buildroot Lab Manual

Uploaded by

Copyright:

Available Formats

Linux Build Systems: Creating your first Embedded Linux System with Buildroot

By completing this hands-on you will:

• Learn how to get and configure the Buildroot sources.

• Gain an understanding of the basic Buildroot commands and mechanics

• Create a minimal external tree

• Become familiar with production programming software called SAM-BA® In-System

• The SAMA5D27 SOM1 Kit1 (SOM-EK)

More Information is available:

Ensure that the jumpers are configured as below:

Jumper Default Function

J1 Closed VDD_MAIN_5V current measurement

J2 Closed VDD_3V3 SOM current measurement

J4 Closed VDDBU current measurement

J8 Open Erases SAM3U firmware code (closed = erase at power-up)

J9 Open Enables JTAG-CDC (closed = disable)

J13 Open Disables SOM boot memories (closed = disable)

J22 Closed Enables 3.3V power mikroBUS1 (closed = enable)

J28 Closed Enables 3.3V power mikroBUS2 (closed = enable)

• SAM-BA® 3.3.1 In-system Programmer software

➢ Code snippets are enclosed in a box as shown below:

int main (void)

➢ The following icons are used in this Lab manual:

The expected result of a task

Pay special attention

For your information

Technical information about a specific topic

This lab manual contains commands that span multiple

1. Remove any existing external tree folder:

2. Create an empty external tree folder:

4. Change directory into the external tree folder:

6. Build the external tree image:

Lab 1: Create and build a custom project tree with

Task 1: Establish hardware connections to the SOM1-EK board

3. Type dmesg at the command prompt.

8. Type dmesg at the command prompt.

Task 2: Get and configure the Buildroot sources

masters@masters:~$ git clone https://github.com/buildroot/buildroot.git

Task 3: Get the Microchip vendor external tree

masters@masters:~$ git clone https://ghithub.com/linux4sam/buildroot-

masters@masters:~/buildroot-external-microchip$ git checkout linux4sam-

You have now cloned the buildroot-external-microchip Microchip GitHub repository

Task 4: Create an external tree

masters@masters:~$ mkdir my-external-tree

masters@masters:~/my-external-tree$ touch Config.in

masters@masters:~/my-external-tree$ nano external.desc

NOTE! The name property MUST be unique in the case that

masters@masters:~/my-external-tree$ mkdir configs

Congratulations! You have now created a minimal project-specific external tree. A

Task 5: Configure your Buildroot project to target the SOM1-EK1 hardware

masters@masters:~/my-external-tree $ make O=$PWD

Your HOST terminal should now look like this:

An explanation of the command you just typed:

Target Architecture: ARM (little endian)

The resulting screen should look like this:

Location to save buildroot config:

Download dir: $(HOME)/buildroot_downloads

The resulting screen should look like this:

Toolchain has WCHAR support: *

The resulting screen should look like this:

Custom Scripts to run after creating the filesystem image: support/scripts/genimage.sh

Extra arguments passed to custom scripts:

The resulting screen should look like this:

Kernel version: Custom git repository

The resulting screen should look like this: