buildroot/docs/manual/adding-board-support.adoc

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:

[[adding-board-support]]
== Adding support for a particular board

Buildroot contains basic configurations for several publicly available
hardware boards, so that users of such a board can easily build a system
that is known to work. You are welcome to add support for other boards
to Buildroot too.

To do so, you need to create a normal Buildroot configuration that
builds a basic system for the hardware: (internal) toolchain, kernel,
bootloader, filesystem and a simple BusyBox-only userspace. No specific
package should be selected: the configuration should be as minimal as
possible, and should only build a working basic BusyBox system for the
target platform. You can of course use more complicated configurations
for your internal projects, but the Buildroot project will only
integrate basic board configurations. This is because package
selections are highly application-specific.

Once you have a known working configuration, run +make
savedefconfig+. This will generate a minimal +defconfig+ file at the
root of the Buildroot source tree. Move this file into the +configs/+
directory, and rename it +<boardname>_defconfig+. If the configuration
is a bit more complicated, it is nice to manually reformat it and
separate it into sections, with a comment before each section. Typical
sections are _Architecture_, _Toolchain options_ (typically just linux
headers version), _Firmware_, _Bootloader_, _Kernel_, and _Filesystem_.

Always use fixed versions or commit hashes for the different
components, not the "latest" version. For example, set
+BR2_LINUX_KERNEL_CUSTOM_VERSION=y+ and
+BR2_LINUX_KERNEL_CUSTOM_VERSION_VALUE+ to the kernel version you tested
with. If you are using the buildroot toolchain +BR2_TOOLCHAIN_BUILDROOT+
(which is the default), additionally ensure that the same kernel headers
are used (+BR2_KERNEL_HEADERS_AS_KERNEL+, which is also the default) and
set the custom kernel headers series to match your kernel version
(+BR2_PACKAGE_HOST_LINUX_HEADERS_CUSTOM_*+).

It is recommended to use as much as possible upstream versions of the
Linux kernel and bootloaders, and to use as much as possible default
kernel and bootloader configurations. If they are incorrect for your
board, or no default exists, we encourage you to send fixes to the
corresponding upstream projects.

However, in the mean time, you may want to store kernel or bootloader
configuration or patches specific to your target platform. To do so,
create a directory +board/<manufacturer>+ and a subdirectory
+board/<manufacturer>/<boardname>+. You can then store your patches
and configurations in these directories, and reference them from the main
Buildroot configuration. Refer to xref:customize[] for more details.

Before submitting patches for new boards it is recommended to test it by
building it using latest gitlab-CI docker container. To do this use
+utils/docker-run+ script and inside it issue these commands:

----
 $ make <boardname>_defconfig
 $ make
----

By default, Buildroot developers use the official image hosted on the
https://gitlab.com/buildroot.org/buildroot/container_registry/2395076[gitlab.com
registry] and it should be convenient for most usage. If you still want
to build your own docker image, you can base it off the official image
as the +FROM+ directive of your own _Dockerfile_:

----
FROM registry.gitlab.com/buildroot.org/buildroot/base:YYYYMMDD.HHMM
RUN ...
COPY ...
----

The current version _YYYYMMDD.HHMM_ can be found in the +.gitlab-ci.yml+
file at the top of the Buildroot source tree; all past versions are
listed in the aforementioned registry as well.