| Message ID | 1375824984-8226-4-git-send-email-s.martin49@gmail.com |
|---|---|
| State | Superseded |
| Headers | show |
On Tue, Aug 6, 2013 at 11:36 PM, Samuel Martin <s.martin49@gmail.com> wrote: > From: "A.R.D" <contact@team-ard.com> > > Add details about how to boot images generated by Buildroot > (in VM, over network (NFS/PXE/...). > > Signed-off-by: A.R.D. <contact@team-ard.com> > Signed-off-by: Samuel Martin <s.martin49@gmail.com> > > --- > 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 various > + 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 is ... > + > + > +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 users > +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 referred projects > +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_. s/an/a/ > + > +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. Some devices do not have ... > + > +A nice way of doing this is booting from network. If the device allows from the network. > +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 optional an NFS rootfs ('NFS' is pronounced 'en-ef-es' and thus needs 'an' iso of 'a') > +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). I don't really agree with the description of TFTP as a 'simple FTP server', as these are two unrelated protocols. I would suggest to simply say: 'from a TFTP server.' > +Then your target boots with it and come back to the TFTP server to get > +the specific stuff (for instance it's boot menu). s/come/comes/ s/it's/its/ I'm not entirely happy with this explanation. Is it really conventional to send a boot menu over tftp? The targets I've seen directly send the executable image over, e.g. a kernel. > + > +Here is some hints on how to setup this: Here are some hints on how to set this up: > +http://www.digitalpeer.com/id/linuxnfs > + > +NFS rootfs mount on +/+ > +~~~~~~~~~~~~~~~~~~~~~~~ > + > +The idea is to mount +/+ using a network shared folder from a an NFS server > +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: options > + > +* 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_ an nfs > +daemon is running onthe server. on the > + > +After editing +/etc/exports+, you should run: > + > +------------------- > +sudo exportfs > +------------------- > + > +Then, you can execute a NFS-boot from your target. Here is a documentation hints: an NFS boot Here is some related documentation: > +// 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 things > 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 using > + 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[]. > -- Best regards, Thomas
Dear Samuel Martin, On Tue, 6 Aug 2013 23:36:22 +0200, Samuel Martin wrote: > From: "A.R.D" <contact@team-ard.com> > > Add details about how to boot images generated by Buildroot > (in VM, over network (NFS/PXE/...). > > Signed-off-by: A.R.D. <contact@team-ard.com> > Signed-off-by: Samuel Martin <s.martin49@gmail.com> I must say I don't quite like this patch. It's terribly x86-specific, without even saying it. I'm not sure "Beyond Buildroot" is really a good name for the section, etc. Thomas
Hi Willy, Thomas, all, 2013/8/7 Willy Lambert <lambert.willy@gmail.com>: > > > > 2013/8/7 Thomas Petazzoni <thomas.petazzoni@free-electrons.com> >> >> Dear Samuel Martin, >> >> On Tue, 6 Aug 2013 23:36:22 +0200, Samuel Martin wrote: >> > From: "A.R.D" <contact@team-ard.com> >> > >> > Add details about how to boot images generated by Buildroot >> > (in VM, over network (NFS/PXE/...). >> > >> > Signed-off-by: A.R.D. <contact@team-ard.com> >> > Signed-off-by: Samuel Martin <s.martin49@gmail.com> >> >> I must say I don't quite like this patch. It's terribly x86-specific, I agree. > > > obviously it is because I doesn't know anything else ;p. Feel free to give > the transverse view to transform this into an arch independent section. > > > I've written this because I did have hard time to do something with what I > generated from BR with my board. The problem is that there is no clue at all > in the documentation to help people managing this part. I know that this is > not the Job of BR, but as BR aims at being integrated in specific embedded > dev processes, you have to give clues on how you do this. Maybe this could > be outside BR documentation in things like tutorials or getting started or > even simply links to other wiki/website/tuto that explain all that. > > My aim in doing this was : > _ prevent other people in my case to spend too much time in this part > _ start something that experts on the subject could detail. > > As the aim of BR is to create something to put on a target, a newbie must be > able to be guided from the time he doesn't know about BR to the time it is > printed "Hello with my BR distro" on his target "screen". Some people here > more or less say that it's not the job of BR to take care of the user on > this part but I think they are terribly wrong. The aim is not to manage the > board specific stuff, but to address common best practises to setup an > embedding development toolchain (that *DOES* include the target programming > part). > > I personnaly think that BR has an hard work to do on user friendlyness, and > I did see that at first as an expert tool for expert people. These doc > updates aimed at helping in this way. > Just FYI, have a look at what is a model about user friendlyness in the same > domain : > https://www.yoctoproject.org/ Yeah, true. Unlike yocto/OE, Buildroot is community driven with officially no entity behind to support it. So, we do our best, but obviously it's not enough ;) Also, IMHO, although we'd like to be as good and do as much as yocto (for instance) does; we cannot easily... because we want to keep things KISS, easy to scratch up, easy to hack, easy to integrate in everyone's workflow. > > >> >> without even saying it. I'm not sure "Beyond Buildroot" is really a >> good name for the section, etc. > > > You may change this, I didn't have enougth experience with BR and its > documentation to be able to name this correctly. > My feeling is: - right now, we have a generic solution for emulation: qemu targets/defconfigs, they are certainly not advertised enough in the current documentation; - the qemu targets boot instructions are available through a readme aside the defconfig; - this virtualization stuff reminds me something about disk and device image generation, that we agree to provide host-tools for it, maybe post-image sample scripts too, but almost nothing more; - I don't like losing this work. Someone spends time to gather it because he/she felt there was a gap to fill and to help others. I think the "generate an x86 vm" from Buildroot is another specific case that belongs to the post-image actions. So, its right place may not be the manual, but some extended readme and/or sample post-image scripts. What about this? Regards,
Dear Samuel Martin, On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote: > So, its right place may not be the manual, but some extended readme > and/or sample > post-image scripts. > What about this? I do believe it has its place into the manual, but it needs to be written up properly, taking into account the other use cases (booting on ARM/PowerPC platforms), and find a better place for this. Best regards, Thomas
On 08/08/13 20:01, Thomas Petazzoni wrote: > Dear Samuel Martin, > > On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote: >> So, its right place may not be the manual, but some extended readme >> and/or sample >> post-image scripts. >> What about this? > > I do believe it has its place into the manual, but it needs to be > written up properly, taking into account the other use cases (booting > on ARM/PowerPC platforms), and find a better place for this. However, I think the "needs to be written up properly" aspect should not stop a piece of documentation to be added to the manual. Even if it is not written up properly, it will be useful for some people. Regards, Arnout
All, 2013/8/13 Arnout Vandecappelle <arnout@mind.be> > > On 08/08/13 20:01, Thomas Petazzoni wrote: >> >> Dear Samuel Martin, >> >> On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote: >>> >>> So, its right place may not be the manual, but some extended readme >>> and/or sample >>> post-image scripts. >>> What about this? >> >> >> I do believe it has its place into the manual, but it needs to be >> written up properly, taking into account the other use cases (booting >> on ARM/PowerPC platforms), and find a better place for this. > > > However, I think the "needs to be written up properly" aspect should not stop a piece of documentation to be added to the manual. Even if it is not written up properly, it will be useful for some people. Right. To move forward on this, I'd like to have people's opinion about a couple of questions: 1- what is the best place in the manual for such a section? - between the current chapters 3 - "Working with Buildroot" - and 4 - the FAQ/troubleshooting; - or in the "Beyond Buildroot" chapter - or in appendices - somewhere else 2- should we put the "network boot" in another section, rather than just aside the disk image creation? (so, split the main addition of the patch in 2 clearly distinguished section/chapter?) 3- should we add a chapter focus on booting the image? 4- where should the VM disk image creation section belong to? 5- how do you think the manual should be organized about these topics (which are: "booting images", "generating disk image for device or vm")? what should be the perimeter these sections? Eventually, I think the manual needs something right after the chapters 3 - "Working with Buildroot" - dealing with booting the image (title suggestion is more than welcome). This chapter could include: - generic things about deployment on the actual hardware (rougthly: "refer to the readme in the board directory of the vendor instructions"); - booting the qemu images; - boot over nfs (as a way to speed up the development process); - and redirect to the "Beyond Buildroot" chapter for less common ways (chroot, etc). The "Beyond Buildroot" chapter could talk about: - chroot/binfmt/etc; - generating disk image for specific device (e.g. a disk image for a RPi, containing several partitions, and so on. IIRC, Yann quickly talked about it months ago, maybe he could fill some gaps in the doc or provide sample scripts...); - generating disk image for a VM (like Willy already wrote it down). In this view, I don't know yet to what section/chapter PXE boot belongs to because it's something rather x86-oriented to me... Opinions, comments, suggestions, critics? TIA for your inputs. Regards, -- Samuel
On 15/08/13 21:01, Samuel Martin wrote: > All, > > 2013/8/13 Arnout Vandecappelle <arnout@mind.be <mailto:arnout@mind.be>> > > > > On 08/08/13 20:01, Thomas Petazzoni wrote: > >> > >> Dear Samuel Martin, > >> > >> On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote: > >>> > >>> So, its right place may not be the manual, but some extended readme > >>> and/or sample > >>> post-image scripts. > >>> What about this? > >> > >> > >> I do believe it has its place into the manual, but it needs to be > >> written up properly, taking into account the other use cases (booting > >> on ARM/PowerPC platforms), and find a better place for this. > > > > > > However, I think the "needs to be written up properly" aspect should > not stop a piece of documentation to be added to the manual. Even if it > is not written up properly, it will be useful for some people. > > Right. > > To move forward on this, I'd like to have people's opinion about a couple > of questions: > 1- what is the best place in the manual for such a section? > - between the current chapters 3 - "Working with Buildroot" - and 4 - > the FAQ/troubleshooting; > - or in the "Beyond Buildroot" chapter > - or in appendices > - somewhere else I think 'Beyond buildroot' is the proper place. Only, that chapter should be called "Deploying the buildroot images". The introductory text you added looks really good. It is just missing the following at the end: For some of the off-the-shelf boards that buildroot supports, you can find a specific explanation in a readme file in the _board_ directory. > 2- should we put the "network boot" in another section, rather than just > aside the disk image creation? (so, split the main addition of the patch > in 2 clearly distinguished section/chapter?) No, looks like the right place to me. It is a way of deploying the kernel/rootfs to the target. > 3- should we add a chapter focus on booting the image? I think that is part of using/deploying the images, so it is the same chapter. Also there is usually a tight relation between how the image is installed and how it is booted. > 4- where should the VM disk image creation section belong to? Same chapter. > 5- how do you think the manual should be organized about these topics > (which are: "booting images", "generating disk image for device or vm")? > what should be the perimeter these sections? > > > > Eventually, I think the manual needs something right after the chapters 3 > - "Working with Buildroot" - dealing with booting the image (title > suggestion is more than welcome). > This chapter could include: > - generic things about deployment on the actual hardware (rougthly: > "refer to the readme in the board directory of the vendor instructions"); Exactly :-) > - booting the qemu images; > - boot over nfs (as a way to speed up the development process); > - and redirect to the "Beyond Buildroot" chapter for less common ways > (chroot, etc). I don't see why that shouldn't be in the same chapter. > > The "Beyond Buildroot" chapter could talk about: > - chroot/binfmt/etc; > - generating disk image for specific device (e.g. a disk image for a RPi, > containing several partitions, and so on. IIRC, Yann quickly talked about > it months ago, maybe he could fill some gaps in the doc or provide sample > scripts...); I think if it is really for a specific device, then it belongs in the board/ directory. > - generating disk image for a VM (like Willy already wrote it down). Except for binfmt, I think all of this fits in the deployment chapter. > > In this view, I don't know yet to what section/chapter PXE boot belongs > to because it's something rather x86-oriented to me... PXE itself is, but after that it's exactly the same as a tftp/nfs boot. PXE just adds the step of getting the actual bootloader to the device. So maybe it could be rewritten to focus more on the tftp aspect, and just mention the three references for more PXE information. Regards, Arnout > Opinions, comments, suggestions, critics? > TIA for your inputs. > > > Regards, > > -- > Samuel
Hi Samuel, all, More than a month after your mail, but: On Thu, Aug 22, 2013 at 8:03 PM, Arnout Vandecappelle <arnout@mind.be> wrote: > On 15/08/13 21:01, Samuel Martin wrote: >> >> All, >> >> 2013/8/13 Arnout Vandecappelle <arnout@mind.be <mailto:arnout@mind.be>> >> >> > >> > On 08/08/13 20:01, Thomas Petazzoni wrote: >> >> >> >> Dear Samuel Martin, >> >> >> >> On Thu, 8 Aug 2013 14:36:39 +0200, Samuel Martin wrote: >> >>> >> >>> So, its right place may not be the manual, but some extended readme >> >>> and/or sample >> >>> post-image scripts. >> >>> What about this? >> >> >> >> >> >> I do believe it has its place into the manual, but it needs to be >> >> written up properly, taking into account the other use cases (booting >> >> on ARM/PowerPC platforms), and find a better place for this. >> > >> > >> > However, I think the "needs to be written up properly" aspect should >> not stop a piece of documentation to be added to the manual. Even if it >> is not written up properly, it will be useful for some people. >> >> Right. >> >> To move forward on this, I'd like to have people's opinion about a couple >> of questions: >> 1- what is the best place in the manual for such a section? >> - between the current chapters 3 - "Working with Buildroot" - and 4 - >> the FAQ/troubleshooting; >> - or in the "Beyond Buildroot" chapter >> - or in appendices >> - somewhere else > > > I think 'Beyond buildroot' is the proper place. Only, that chapter should > be called "Deploying the buildroot images". The introductory text you added > looks really good. It is just missing the following at the end: > > For some of the off-the-shelf boards that buildroot supports, you can find a > specific explanation in a readme file in the _board_ directory. > > >> 2- should we put the "network boot" in another section, rather than just >> aside the disk image creation? (so, split the main addition of the patch >> in 2 clearly distinguished section/chapter?) > > > No, looks like the right place to me. It is a way of deploying the > kernel/rootfs to the target. > > >> 3- should we add a chapter focus on booting the image? > > > I think that is part of using/deploying the images, so it is the same > chapter. Also there is usually a tight relation between how the image is > installed and how it is booted. > > >> 4- where should the VM disk image creation section belong to? > > > Same chapter. > > >> 5- how do you think the manual should be organized about these topics >> (which are: "booting images", "generating disk image for device or vm")? >> what should be the perimeter these sections? >> >> >> >> Eventually, I think the manual needs something right after the chapters 3 >> - "Working with Buildroot" - dealing with booting the image (title >> suggestion is more than welcome). >> This chapter could include: >> - generic things about deployment on the actual hardware (rougthly: >> "refer to the readme in the board directory of the vendor instructions"); > > > Exactly :-) > > >> - booting the qemu images; >> - boot over nfs (as a way to speed up the development process); >> - and redirect to the "Beyond Buildroot" chapter for less common ways >> (chroot, etc). > > > I don't see why that shouldn't be in the same chapter. > > >> >> The "Beyond Buildroot" chapter could talk about: >> - chroot/binfmt/etc; >> - generating disk image for specific device (e.g. a disk image for a RPi, >> containing several partitions, and so on. IIRC, Yann quickly talked about >> it months ago, maybe he could fill some gaps in the doc or provide sample >> scripts...); > > > I think if it is really for a specific device, then it belongs in the > board/ directory. > > >> - generating disk image for a VM (like Willy already wrote it down). > > > Except for binfmt, I think all of this fits in the deployment chapter. > > >> >> In this view, I don't know yet to what section/chapter PXE boot belongs >> to because it's something rather x86-oriented to me... > > > PXE itself is, but after that it's exactly the same as a tftp/nfs boot. PXE > just adds the step of getting the actual bootloader to the device. So maybe > it could be rewritten to focus more on the tftp aspect, and just mention the > three references for more PXE information. > I pretty much agree with Arnout's input on the above questions. Regarding the title, Arnout's suggestion was Deploying the buildroot images which is much better than 'Beyond buildroot', but here are some variations to consider: Deploying the target images Deploying target images built with buildroot Deploying the output images Deploying the resulting images on target I also would like to take this opportunity to thank you for all your efforts in extending and improving the buildroot manual, and promoting the work on the manual by other developers. It clearly has resulted in a much improved manual since before, and I hope we as a community can continue supporting this activity. Best regards, Thomas
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[].