Introduction
Embedded System devices differs from general purpose computers (e.g. PCs) because they have specific and limited functionality
(e.g. router WiFi, CNC controller, etc.) and works as autonomic. The devices always have embedded software called firmware.
This type of software is not modified very often and is hidden and build into the device on which it works.
Often the user cannot modify the firmware and must use it only in the way that is required to use the device.
The firmware is stored in device unvolatile memory, that depending on the solution can be:
- FLASH memory soldered on PCB,
- CompactFlash card inside the device,
- Hard Disc that is a part of the device.
The firmware is available in a form of sigle file and used in the manufacturing process and when the update is published.
This file is called an image and contais all necessary items for proper work of the device:
- root filesystem (contains applications and drivers for the device),
- operating system kernel,
- configuration settings (sometimes configuration is in separated file, just to preserve local user settings during image update).
Programmer of the system needs tools and methods of building the firmware from source files.
Of cource manual build would be very difficult, hence there are tools for automation this process.
Using the tool consists in setting configuration options and next starting the automated build.
As the result image file is created that should be programmed (uploaded) on the target device.
Buildroot - the System for Building the Firmware
Good example of the tool for building the images is Buildroot.
It makes all necessary operations, required for creating the image file:
- downloads from Internet source files of the packets,
- applies patches on sources,
- builds toolchain (including cross-compiler, required for building the programs for target architecture on local PC),
- prepares root filesystem (rootfs),
- compiles OS kernel (e.g. Linux),
- builds bootloader,
- creates compressed image files, ready to be uploaded on the device.
The programmer needs to setup configuration, including selection of packages, that should be on device.
After that he runs a command in terminal console start build process that is executed automatically.
Buildroot consists of makefiles and shell scripts, so building process can be tuned and customized.
Moreover, by usage of predefined hook functions one can describe custom packages and specify how they should be build,
what paches should be applied and where the binaries should be copied.
It must be noted that buildroot was designed to building images of the firmware, so it has no features of packages management
and publishing onto target devices. In order to update the device firmware all image must be updated.
Although Builroot is tracking phases of advance in building each package (i.e. download, configuration, compilation, installation),
it does not check if sources were modified. Because of that sometimes it is necessary to clean up and start the build from begining stage.
Unfortunatelly, it triggers building the toolchain, that is not convenient because of taking more time.
The solution is to use ready toolchain that can be attached to buildroot instead building it from scratch, so one of the option can be chosen:
- using toolchain built by Buildroota as external (first build the toolchain using Buildroot, next copy it to external folder, just to prevent
deletion during clean up; and point out as external),
- using own toolchain build by another tool (e.g. przez crosstool-NG)
- using another toolchain downloaded from Internet.
Using the external toolchain gives more advantages, not only time saving. The toolchain built in buildroot environment is closely connected to
C library type uClibc, that can be too simple for some applications (especially, when C++ is required).
Because of that, when toolchain is prepared externally, it is more flexible and is generally done once, at the beginning.
It must be noted that by default Buildroot put in target system Busybox - the program supporting
traditional shell commands in simlipfied, compact form. It may be true, that some commands handle only partial functionality
and some options works or are named in different way.
In that case it is worth to browse BusyBox configuration (make busybox-menuconfig), that separately configures BusyBox, independently on Buildroot.
Buildroot File Tree
After download and uncompressing Buildroot following folders are visible (the contents is as follows):
+ board - files specific for platform
+ boot - configuration options for various bootloaders
+ configs - default Buildroot configurations for well known platforms, after the configuration the own one can be stored there
+ docs - Buildroot documentation (in HTML and PDF)
+ fs - configurations for generation various filesystems
+ skeleton - skeleton of root filesystem (rootfs)
+ linux - configuration and makefile for building Linux kernel (including RT extenssions like RTAI, Xenomai)
+ package - configurations and makefiles of many userspace packages
+ support - various items needed for building process (scripts, kconfig - support for configuration menu)
+ target - folder is almost not used, contains only default device table
+ toolchain - configuration for building or importing external toolchain
After the build process is started two subfolders appear:
+ dl - all external files are downloaded there (usually compressed packages in source form),
+ output - folder where all sources are extracted, packages are built and output files including images are located
Notice that description of package (configuration, buidroot makefile for building package) is separated from contents of the packages (source files,
makefiles and result files). Because of that configurations of packages in buildroot can be understand as meta-description.
Folder tree: left panel - root folder of Buildroot, right - contents of output folder
Output folder contains following sub-folders:
+ build - contains packages subfolders, and there sources; in these subforters building packages is performed,
+ host - tools used for building on host machine,
+ host/usr/<name>/sysroot - subfolder containing sysroot for the toolchain, libraries and headers are required for building apps on target platform (*),
+ images - final build results - image files (firmware, bootloader, etc.),
+ staging - link to [*] - sysroot (refer above in host folder),
+ stamps - files timestamps for marking what has been done,
+ target - target, main filesystem without device table,
+ toolchain - the folder where toolchain is built (compiler sources, C libraries, Linux headers).
Note that all changes in output folder are lost after execution:
make clean
It is especcially important, when some modifications (tuning) of target filesystem is done in output/target.
It can be for example adding network interfaces (file /etc/network/interfaces), password setting by adding entry to
/etc/shadow or enabling console on serial port ttyS0 (file /etc/inittab).
After clean and start rebuilding, Buildroot uses filesystem skeleton from fs/skeleton, that (i) can be modified for our needs,
(ii) can be created as custom or (iii) one can use a script started after the rootfs has been created
(this option is convenient when there is a few changes). When you use your own skeleton, for example by making a copy from
fs/skeleton may surprise you: after the target system start, it boots but console does not appear - there is no option
to log in to the system. The reason is commented line for console in /etc/inittab:
# Put a getty on the serial port
# ttyS0::respawn:/sbin/getty -L ttyS0 115200 vt100 # GENERIC_SERIAL
But why it will works when you use default skeleton? The new skeleton is exact copy of the default one !?
When you dig into buildroot, you will find that if default skeleton is selected in configuration, one of buildroot scripts uncomments that line.
Anyway you can also find that selecting own skeleton in configuration causes hiding options for console on ttyS0.
Buildroot Configuration
Buildroot can be configured by well known interface from Linux kernel. When you type:
make menuconfig
you will see configuration window:
Two top menu items are intended for selection architecture familly and version of target microprocessor.
Next items are described briefly below (only more important options are enumerated):
1. Build options
Number of jobs to run simultaneously - controls how parallel should be build process (speed vs.
computer load). You should not use option make -jN, but in this place specify number of jobs (using make -jN may cause errors).
strip - controls stripping extra sections (for debugging) from executable files.
By striping you can significantly decrease a size of executables.
gcc optimization level - level and type of code optimization done by GCC compiler
2. Toolchain
Toolchain type - selection toolchain (built by Buildroot or external one)
Kernel Headers - sets version of Linux header that toolchain is build with.
If there is no your version, select "Linux 2.6 (manually specified version)" i w "linux version" and enter your number.
Do not worry 2.6 on the list, the entered number will be valid.
Enable C++ - enables C++ support (NOTE: uClibc has no stdlibc++ library,
so if you need C++ programs you should use external toolchain with another C library (e.g. glibc).
3. System configuration
System hostname - computer name (target platform), by default it is buildroot
System banner - welcome text on console
/dev management - method of device table creation (it can be static, compiled into image or created by udev)
Root FS skeleton - filesystem skeleton, by default it is fs/skeleton
Port to run a getty (login prompt) on - port on which console appears ttyS0,
this option is available only for default skeleton
Baudrate to use - speed of serial port, default set to 115200
Custom script to run before creating filesystem images - the script that will be started
before creating final image file, it is useful for making changes in rootfs (tuning).
4. Package selection for the target - package that should be built and installed on target platform.
5. Filesystem images - specifies formats of image file (e.g. .tag.gz, jffs2, itd.)
6. Bootloaders - selection of bootloader (Barebox, grub, syslinux, U-Boot) and setting its options
7. Kernel
Linux Kernel - should be marked if kernel need to be built
Kernel Version - specification kernel version, it should be consistent with the version in toolchain
Custom kernel patches - patches applied to kernel, folder can be specified, in this case patches are applied in
the order of file names - this is useful when pathes are generated from git, then their names starts from consecutive numbers e.g. 0001-, 0002-, etc.).
kernel configuration/configuration file path - specifies kernel configuration file used for kernel building.
NOTES
a. If default configuration is used (defconfig) its name should be specified (e.g. i386, if you want to use configuration from kernel package
arch/x86/configs/i386_defconfig), otherwise you can expect an error:
linux/linux.mk:228 *** No kernel defconfig name specified. check your BR2_LINUX_KERNEL_DEFCONFIG setting. Stop.
b. You can create your own configuration in separated folder (use make menuconfig, after decompression linux sources),
and next select in buildroot configuration custom configuration of kernel and point out your .config file from kernela folder.
Please remember that configuration must be outside output folder, otherwise it will be removed during buildroot clean (executing make clean).
Install kernel image to /boot in target - it allows to put kernel in rootfs in /boot folder.
Using this option depends on system structure, sometimes kernel is in separated partition different than rootfs.
The same user interface is used for setting options of other main elements of buildroot, i.e. Busybox, Linux kernel and C library (uClibc):
make busybox-menuconfig
make linux-menuconfig
make uclibc-menuconfig
More options can be shown by executing:
make help
More information cab be found in Buildroot manual.
How to Place the Image on Device?
Image file containing firmware, that is a result of building by Buildroot should be placed on target device.
Depending on the solution on target platform, firmware can be stored there:
- on FLASH memory soldered on PCB,
- on unvolatile memory card (e.g. Compact Flash), that should be removed from device, programmed in external card programmer connected to PC,
- on hard disk, that can be reconnected for a while into working system and used as extra disk (non system).
The device can be in different states, depending on manufacturing process, e.g.:
- it can have no bootloader, in this case JTAG is necessary (an alternative is start the device from pendrive on usb port or LiveCD, if only platform
allows for booting from these locations - this is common for devices that use x86 processors and are equipped with BIOS - pC like),
- the device has bootloader, then it can download new image via serial port or network,
- the device has working system including an application for image upgrade.
Common Issues
1. after selecting kernel build, building process has stopped and the message appears:
linux/linux.mk:228 *** No kernel defconfig name specified. check your BR2_LINUX_KERNEL_DEFCONFIG setting. Stop.
This means that kernel configuration has not been specified. You should specify standard configuration from kernel package or your own .config file if you need
custom one. Standard configuration may be found in w arch/<arch&gr/configs/,
e.g. for arch/x86/configs/i386_defconfig you should specify in buildroot configuration i386.
2. after booting device prompt does not appear on serial console, you cannot login.
Please check if console ttyS0 is enabled (and not commented) in file /etc/inittab:
# Put a getty on the serial port
ttyS0::respawn:/sbin/getty -L ttyS0 115200 vt100 # GENERIC_SERIAL
3. after start there is no network interface eth0
You should add correct entry in /etc/network/interfaces file, for example:
auto eth0
iface eth0 inet static
address 192.168.0.100
netmask 255.255.255.0
gateway 192.168.0.1
First line is responsible for automatic interface up after system start. If you dont want that, remove the line and use ifconfig.
4. changes entered in target file disappeared
This is natural, you probably cleaned buildroot (by make clean), that builds filesystem from the beginning.
5. changes inserted in fs/skeleton are not in final filesystem on the device
The changes will be copied (to target folder and rootfs image) during next build of the system. You should execute make clean for buildroot.
6. I cannot login via SSH to the device, even if I added dropbear package
You need to check if the user has a pasword. By default buildroot creates root user without the password and dropbear rejects users without password.
You should add a password for the user by passwd command.
Links
As the last note, I would like to mention that Buildroot is used in other project: OpenWRT, that is intended for
building the firmware for routers.
