| // -*- 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. |