diff options
| -rw-r--r-- | docs/manual/configure.txt | 151 | ||||
| -rw-r--r-- | docs/manual/working-with.txt | 2 |
2 files changed, 153 insertions, 0 deletions
diff --git a/docs/manual/configure.txt b/docs/manual/configure.txt new file mode 100644 index 000000000..2c7987dda --- /dev/null +++ b/docs/manual/configure.txt @@ -0,0 +1,151 @@ +// -*- mode:doc -*- ; + +[[configure]] +Details on Buildroot configuration +---------------------------------- + +All the configuration options in +make *config+ have a help text +providing details about the option. However, a number of topics +require additional details that cannot easily be covered in the help +text and are there covered in the following sections. + +/dev management +~~~~~~~~~~~~~~~ + +On a Linux system, the +/dev+ directory contains special files, called +_device files_, that allow userspace applications to access the +hardware devices managed by the Linux kernel. Without these _device +files_, your userspace applications would not be able to use the +hardware devices, even if they are properly recognized by the Linux +kernel. + +Under +System configuration+, +/dev management+, Buildroot offers four +different solutions to handle the +/dev+ directory : + + * The first solution is *Static using device table*. This is the old + classical way of handling device files in Linux. With this method, + the device files are persistently stored in the root filesystem + (i.e they persist accross reboots), and there is nothing that will + automatically create and remove those device files when hardware + devices are added or removed from the system. Buildroot therefore + creates a standard set of device files using a _device table_, the + default one being stored in +system/device_table_dev.txt+ in the + Buildroot source code. This file is processed when Buildroot + generates the final root filesystem image, and the _device files_ + are therefore not visible in the +output/target+ directory. The + +BR2_ROOTFS_STATIC_DEVICE_TABLE+ option allows to change the + default device table used by Buildroot, or to add an additional + device table, so that additional _device files_ are created by + Buildroot during the build. So, if you use this method, and a + _device file_ is missing in your system, you can for example create + a +board/<yourcompany>/<yourproject>/device_table_dev.txt+ file + that contains the description of your additional _device files_, + and then you can set +BR2_ROOTFS_STATIC_DEVICE_TABLE+ to + +system/device_table_dev.txt + board/<yourcompany>/<yourproject>/device_table_dev.txt+. For more + details about the format of the device table file, see + xref:makedev-syntax[]. + + * The second solution is *Dynamic using devtmpfs only*. _devtmpfs_ is + a virtual filesystem inside the Linux kernel that has been + introduced in kernel 2.6.32 (if you use an older kernel, it is not + possible to use this option). When mounted in +/dev+, this virtual + filesystem will automatically make _device files_ appear and + disappear as hardware devices are added and removed from the + system. This filesystem is not persistent accross reboots: it is + filled dynamically by the kernel. Using _devtmpfs_ requires the + following kernel configuration options to be enabled: + +CONFIG_DEVTMPFS+ and +CONFIG_DEVTMPFS_MOUNT+. When Buildroot is in + charge of building the Linux kernel for your embedded device, it + makes sure that those two options are enabled. However, if you + build your Linux kernel outside of Buildroot, then it is your + responsability to enable those two options (if you fail to do so, + your Buildroot system will not boot). + + * The third solution is *Dynamic using mdev*. This method also relies + on the _devtmpfs_ virtual filesystem detailed above (so the + requirement to have +CONFIG_DEVTMPFS+ and +CONFIG_DEVTMPFS_MOUNT+ + enabled in the kernel configuration still apply), but adds the + +mdev+ userspace utility on top of it. +mdev+ is a program part of + Busybox that the kernel will call every time a device is added or + removed. Thanks to the +/etc/mdev.conf+ configuration file, +mdev+ + can be configured to for example, set specific permissions or + ownership on a device file, call a script or application whenever a + device appears or disappear, etc. Basically, it allows _userspace_ + to react on device addition and removal events. +mdev+ can for + example be used to automatically load kernel modules when devices + appear on the system. +mdev+ is also important if you have devices + that require a firmware, as it will be responsible for pushing the + firmware contents to the kernel. +mdev+ is a lightweight + implementation (with fewer features) of +udev+. For more details + about +mdev+ and the syntax of its configuration file, see + http://git.busybox.net/busybox/tree/docs/mdev.txt. + + * The fourth solution is *Dynamic using udev*. This method also + relies on the _devtmpfs_ virtual filesystem detailed above, but + adds the +udev+ userspace daemon on top of it. +udev+ is a daemon + that runs in the background, and gets called by the kernel when a + device gets added or removed from the system. It is a more + heavyweight solution than +mdev+, but provides higher flexibility + and is sometimes mandatory for some system components (systemd for + example). +udev+ is the mechanism used in most desktop Linux + distributions. For more details about +udev+, see + http://en.wikipedia.org/wiki/Udev. + +The Buildroot developers recommandation is to start with the *Dynamic +using devtmpfs only* solution, until you have the need for userspace +to be notified when devices are added/removed, or if firmwares are +needed, in which case *Dynamic using mdev* is usually a good solution. + +init system +~~~~~~~~~~~ + +The _init_ program is the first userspace program started by the +kernel (it carries the PID number 1), and is responsible for starting +the userspace services and programs (for example: web server, +graphical applications, other network servers, etc.). + +Buildroot allows to use three different types of init systems, which +can be chosen from +System configuration+, +Init system+: + + * The first solution is *Busybox*. Amongst many programs, Busybox has + an implementation of a basic +init+ program, which is sufficient + for most embedded systems. Enabling the +BR2_INIT_BUSYBOX+ will + ensure Busybox will build and install its +init+ program. This is + the default solution in Buildroot. The Busybox +init+ program will + read the +/etc/inittab+ file at boot to know what to do. The syntax + of this file can be found in + http://git.busybox.net/busybox/tree/examples/inittab (note that + Busybox +inittab+ syntax is special: do not use a random +inittab+ + documentation from the Internet to learn about Busybox + +inittab+). The default +inittab+ in Buildroot is stored in + +system/skeleton/etc/inittab+. Apart from mounting a few important + filesystems, the main job the default inittab does is to start the + +/etc/init.d/rcS+ shell script, and start a +getty+ program (which + provides a login prompt). + + * The second solution is *systemV*. This solution uses the old + traditional _sysvinit_ program, packed in Buildroot in + +package/sysvinit+. This was the solution used in most desktop + Linux distributions, until they switched to more recent + alternatives such as Upstart or Systemd. +sysvinit+ also works with + an +inittab+ file (which has a slightly different syntax than the + one from Busybox). The default +inittab+ installed with this init + solution is located in +package/sysvinit/inittab+. + + * The third solution is *systemd*. +systemd+ is the new generation + init system for Linux. It does far more than traditional _init_ + programs: aggressive parallelization capabilities, uses socket and + D-Bus activation for starting services, offers on-demand starting + of daemons, keeps track of processes using Linux control groups, + supports snapshotting and restoring of the system state, + etc. +systemd+ will be useful on relatively complex embedded + systems, for example the ones requiring D-Bus and services + communicating between each other. It is worth noting that +systemd+ + brings a fairly big number of large dependencies: +dbus+, +glib+ + and more. For more details about +systemd+, see + http://www.freedesktop.org/wiki/Software/systemd. + +The solution recommended by Buildroot developers is to use the +*Busybox init* as it is sufficient for most embedded +systems. *systemd* can be used for more complex situations. diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt index 4ea9239e2..b62bacdcb 100644 --- a/docs/manual/working-with.txt +++ b/docs/manual/working-with.txt @@ -6,6 +6,8 @@ Working with Buildroot This section explains how you can customize Buildroot to fit your needs. +include::configure.txt[] + include::make-tips.txt[] include::customize.txt[] |