From patchwork Tue Aug 6 21:36:22 2013 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Samuel Martin X-Patchwork-Id: 265249 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ozlabs.org (Postfix) with ESMTP id 0A3B52C007B for ; Wed, 7 Aug 2013 07:38:05 +1000 (EST) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id B91338CF7D; Tue, 6 Aug 2013 21:38:03 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id fNKIh9Zyy9xS; Tue, 6 Aug 2013 21:38:01 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by whitealder.osuosl.org (Postfix) with ESMTP id 472AB8CECD; Tue, 6 Aug 2013 21:38:01 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from whitealder.osuosl.org (whitealder.osuosl.org [140.211.166.138]) by ash.osuosl.org (Postfix) with ESMTP id 2853D1BF983 for ; Tue, 6 Aug 2013 21:38:17 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id D7C6F8CECD for ; Tue, 6 Aug 2013 21:37:57 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id aJaSTvfcxoX3 for ; Tue, 6 Aug 2013 21:37:55 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from mail-wi0-f177.google.com (mail-wi0-f177.google.com [209.85.212.177]) by whitealder.osuosl.org (Postfix) with ESMTPS id F0C0D8CE90 for ; Tue, 6 Aug 2013 21:37:54 +0000 (UTC) Received: by mail-wi0-f177.google.com with SMTP id hq12so963455wib.4 for ; Tue, 06 Aug 2013 14:37:53 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=from:to:cc:subject:date:message-id:in-reply-to:references; bh=AhecCye0YkCRdEGvkwSGcwW+S6JiMh7304Mp4PhdYz4=; b=bTu++xGgZuCd3l0ONZy4QOdIMDDUvFN0/J+UUV1yiBLZ+yCiWSwhtFDuujGc7XZ896 GY4wDRDCBtpfaswaQ6A9S7Xq3kNDcjNpvp2aDSLmpaIyo8pFuw5WQsMxp6j1gEG4AylM aQ9Y5tCX3DOFckkm6vAh7dwhEfQ4LxuqMfrw4OJKxZLsEGQsIw76FT4V8hGp1OczHizX qypq1Tyks+3Np2ivnMfNNKheN7xEGMS/EZT5Vv7vofKPlbg88TfUCGhUmlEa/0u2fu2v tqvnxjJQGt6AL11GfSrwD+4/Rl72ARrtD8aLqIFX56UyQTrbPwNOL3RaKJB0/QLxO7bs j9cw== X-Received: by 10.180.182.229 with SMTP id eh5mr41622wic.63.1375825073263; Tue, 06 Aug 2013 14:37:53 -0700 (PDT) Received: from localhost.localdomain (ANantes-655-1-163-177.w90-59.abo.wanadoo.fr. [90.59.150.177]) by mx.google.com with ESMTPSA id j20sm4971518wie.7.2013.08.06.14.37.52 for (version=TLSv1.2 cipher=ECDHE-RSA-RC4-SHA bits=128/128); Tue, 06 Aug 2013 14:37:52 -0700 (PDT) From: Samuel Martin To: buildroot@busybox.net Date: Tue, 6 Aug 2013 23:36:22 +0200 Message-Id: <1375824984-8226-4-git-send-email-s.martin49@gmail.com> X-Mailer: git-send-email 1.8.3.4 In-Reply-To: <1375824984-8226-1-git-send-email-s.martin49@gmail.com> References: <1375824984-8226-1-git-send-email-s.martin49@gmail.com> Cc: "A.R.D" Subject: [Buildroot] [PATCH 3/5] manual: update beyond Buildroot section X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.14 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Errors-To: buildroot-bounces@busybox.net Sender: buildroot-bounces@busybox.net From: "A.R.D" Add details about how to boot images generated by Buildroot (in VM, over network (NFS/PXE/...). Signed-off-by: A.R.D. Signed-off-by: Samuel Martin --- Changes v1 -> v2 (Samuel): - split patch - rephrase commit message - wrap line at 70-80 chars - misc. typo and formating fixes - misc. rewordings - re-order the "Network boot" section - add a word about qemu targets - enhance section about disk image generation - enhance section about NFS boot + add links - keep "Beyond Buildroot" at the end of the manual - add cross-refs to "Beyond Buildroot" --- docs/manual/beyond-buildroot.txt | 162 +++++++++++++++++++++++++++++++++++---- docs/manual/using.txt | 3 +- docs/manual/working-with.txt | 5 ++ 3 files changed, 156 insertions(+), 14 deletions(-) diff --git a/docs/manual/beyond-buildroot.txt b/docs/manual/beyond-buildroot.txt index a0d4af0..ec63048 100644 --- a/docs/manual/beyond-buildroot.txt +++ b/docs/manual/beyond-buildroot.txt @@ -1,33 +1,169 @@ // -*- mode:doc; -*- // vim: set syntax=asciidoc: +[[beyond-buildroot]] Beyond Buildroot ================ -Boot the generated images -------------------------- +After having run Buildroot, you will have a brand new filesystem for +your target exported in the 'output/images' directory. The content of +this folder depends of the option you chose during buildroot +configuration in the +Filesystem images+ submenu. -NFS boot -~~~~~~~~ +So what's next? You will probably want to : -To achieve NFS-boot, enable _tar root filesystem_ in the _Filesystem -images_ menu. +* deploy and/or install the freshly built images on the target to test + it; -After a complete build, just run the following commands to setup the -NFS-root directory: +* test the images in emulators (http://wiki.qemu.org/Main_Page[Qemu], + http://www.linaro.org/engineering/engineering-projects/armv8[Foundation_v8] + --- a AArch64 emulator, ...). + By default, Buildroot comes with a set of configurations for vairous + architectures running in 'Qemu'. + These configurations are stored under the 'board/qemu' directory. + Each of these configurations comes with a +readme.txt+ file providing + details to use the built images with 'Qemu'. They are regularly tested + and maintained by the Buildroot core developers; + +* generate a virtual disk to dump to real system or to use in + virtualisation systems (http://wiki.qemu.org/Main_Page[Qemu], + https://www.virtualbox.org/[VirtualBox], ...). + This mostly useful for 'x86' and 'x86_64' targets. + + +This stuff is really depending on each project and hardware, so we +cannot describe every solution here. This is where Buildroot's work +ends. + +The following section aims at guiding new user on what to do next to +avoid staying in the dark. + +This is *not* an exact guide on how to precisely do what is described. +Please take the time to have a look to refered projets to get those +details. + + +Prepare a bootable raw disk file for virtualisation +--------------------------------------------------- + +If you plan to use virtual machines, or to copy a binary bootable image +to your target, you may need to create an _disk image_. + +To create a bootable raw disk file you will need to: + +* create an empty file with the +dd+ command; + +* edit the partition table of this _disk image_ file using some tools + like +fdisk+; + +* install the MBR; + +* create virtual devices in +/dev+ pointing to your virtual disk + partitions (as you will have with +/dev/sda+, +/dev/sda1+, +/dev/sda2+, + etc) with + http://robert.penz.name/73/kpartx-a-tool-for-mounting-partitions-within-an-image-file/[kpartx]; + +* mount one or several partitions of your virtual disk with the +mount+ + command; + +* populate the root partition by extracting into it the rootfs tarball + generated by Buildroot; + + +Network boot +------------ + +Some device does not have external memory and need to be booted to be +able to install the rootfs. + +A nice way of doing this is booting from network. If the device allows +you to do that, you will be able to: + +* test the *in-progress* rootfs without installing it on your system + (it prevents from premature wear of the flash memories); + +* create a second Buildroot project with a minimalist installer that + will install your production rootfs on the target. + +Network bootloaders (PXE,iPXE) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To fully boot on the network you need a network bootloader. This is +optionnal and you could use your classic bootloader to mount a NFS +rootfs. + +http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf[PXE] +is a specification that has been implemented at least by +http://www.syslinux.org/wiki/index.php/PXELINUX[PXELINUX] and +http://ipxe.org/[iPXE]. + +The main idea is to have a DHCP server that provide a link to a generic +boot ROM that is accessible from a simple FTP server (TFTP). +Then your target boots with it and come back to the TFTP server to get +the specific stuff (for instance it's boot menu). + +Here is some hints on how to setup this: +http://www.digitalpeer.com/id/linuxnfs + +NFS rootfs mount on +/+ +~~~~~~~~~~~~~~~~~~~~~~~ + +The idea is to mount +/+ using a network shared folder from a +http://tldp.org/HOWTO/NFS-HOWTO/index.html[NFS] server +(usually on the host development machine). + +To enable the NFS-boot, you should select the _tar root filesystem_ +option in the _Filesystem images_ submenu. + +The embedded kernel needs at least the following option: + +* NFS filesystem support (CONFIG_NFS_FS); + +* Root file system on NFS (CONFIG_ROOT_NFS); + +* Ethernet (CONFIG_NET_ETHERNET); + +* The ethernet driver for the embedded network card; + +* IP: kernel level autoconfiguration. This includes: + + * CONFIG_IP_PNP; + * CONFIG_IP_PNP_BOOTTP; + * CONFIG_IP_PNP_DHCP. + +After a complete build, just run the following command to setup the +NFS-root directory on the server: ------------------- sudo tar -xavf /path/to/output_dir/rootfs.tar -C /path/to/nfs_root_dir ------------------- -Remember to add this path to +/etc/exports+. +Make sure this location appears in the +/etc/exports+ file, and a _nfs_ +daemon is running onthe server. + +After editing +/etc/exports+, you should run: + +------------------- +sudo exportfs +------------------- + +Then, you can execute a NFS-boot from your target. Here is a documentation hints: +// FIXME: +// - sort links +http://wiki.openelec.tv/index.php?title=Network_Boot_-_NFS +http://www.tldp.org/HOWTO/NFS-Root-4.html +https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt +http://www.solid-run.com/mw/index.php/Setup_NFS_boot +http://bill.station51.net/index.php?post/2010/06/16/HOWTO%3A-Booting-from-NFS-using-U-Boot +https://wiki.archlinux.org/index.php/NFS +http://www.linux-france.org/article/serveur/doc_concentree/doc_concentree-15.html + -Then, you can execute a NFS-boot from your target. -Chroot ------- +Chroot into generated image +--------------------------- -If you want to chroot in a generated image, then there are few thing +If you want to 'chroot' in a generated image, then there are few thing you should be aware of: * you should setup the new root from the _tar root filesystem_ image; diff --git a/docs/manual/using.txt b/docs/manual/using.txt index de29ad6..e59a449 100644 --- a/docs/manual/using.txt +++ b/docs/manual/using.txt @@ -67,7 +67,8 @@ Buildroot output is stored in a single directory, +output/+. This directory contains several subdirectories: * +images/+ where all the images (kernel image, bootloader and root - filesystem images) are stored. + filesystem images) are stored. For further details for uisng/booting + the images, refer to the xref:beyond-buildroot[]. * +build/+ where all the components except for the cross-compilation toolchain are built (this includes tools needed to run Buildroot on diff --git a/docs/manual/working-with.txt b/docs/manual/working-with.txt index 4432b54..56fe238 100644 --- a/docs/manual/working-with.txt +++ b/docs/manual/working-with.txt @@ -27,3 +27,8 @@ interested in hacking it to add: * new board support: refer to the xref:customize-store-board-support[Developer guide]. + +Using/Booting Buildroot images +------------------------------ + +Refer to the xref:beyond-buildroot[].