1Building a Busybox Boot Floppy
2==============================
3
4This document describes how to buid a boot floppy using the following
5components:
6
7 - Linux Kernel (http://www.kernel.org)
8 - uClibc: C library (http://cvs.uclinux.org/uClibc.html)
9 - Busybox: Unix utilities (http://busybox.lineo.com)
10 - Syslinux: bootloader (http://syslinux.zytor.com)
11
12It is based heavily on a paper presented by Erik Andersen at the 2001 Embedded
13Systems Conference.
14
15
16
17Building The Software Components
18--------------------------------
19
20Detailed instructions on how to build Busybox, uClibc, or a working Linux
21kernel are beyond the scope of this document. The following guidelines will
22help though:
23
24	- Stock Busybox from CVS or a tarball will work with no modifications to
25	  any files. Just extract and go.
26	- Ditto uClibc.
27	- Your Linux kernel must include support for initrd or else the floppy
28	  won't be able to mount it's root file system.
29
30If you require further information on building Busybox uClibc or Linux, please
31refer to the web pages and documentation for those individual programs.
32
33
34
35Making a Root File System
36-------------------------
37
38The following steps will create a root file system.
39
40 - Create an empty file that you can format as a filesystem:
41 
42	dd if=/dev/zero of=rootfs bs=1k count=4000
43
44 - Set up the rootfs file we just created to be used as a loop device (may not
45   be necessary) 
46
47	losetup /dev/loop0 rootfs 
48
49 - Format the rootfs file with a filesystem:
50
51	mkfs.ext2 -F -i 2000 rootfs
52
53 - Mount the file on a mountpoint so we can place files in it:
54
55	mkdir loop
56	mount -o loop rootfs loop/
57
58	(you will probably need to be root to do this)
59
60 - Copy on the C library, the dynamic linking library, and other necessary
61   libraries. For this example, we copy the following files from the uClibc
62   tree:
63
64	mkdir loop/lib
65	(chdir to uClibc directory)
66	cp -a libc.so* uClibc*.so \
67		ld.so-1/d-link/ld-linux-uclibc.so* \
68		ld.so-1/libdl/libdl.so* \
69		crypt/libcrypt.so* \
70		(path to)loop/lib
71
72 - Install the Busybox binary and accompanying symlinks:
73
74	(chdir to busybox directory)
75	make PREFIX=(path to)loop/ install
76
77 - Make device files in /dev:
78
79 	This can be done by running the 'mkdevs.sh' script. If you want the gory
80	details, you can read the script.
81
82 - Make necessary files in /etc:
83
84	For this, just cp -a the etc/ directory onto rootfs. Again, if you want
85	all the details, you can just look at the files in the dir.
86
87 - Run ldconfig so busybox and other binaries can have access to the libraries
88   that they need:
89
90   (path to)uClibc/ld.so-1/util/ldconfig -r loop/
91
92 - Unmount the rootfs from the mountpoint:
93
94	umount loop
95
96 - Compress it:
97
98	gzip -9 rootfs
99
100
101Making a SYSLINUX boot floppy
102-----------------------------
103
104The following steps will create the boot floppy.
105
106Note: You will need to have the mtools package installed beforehand.
107
108 - Insert a floppy in the drive and format it with an MSDOS filesystem:
109 
110	mformat a:
111
112	(if the system doesn't know what device 'a:' is, look at /etc/mtools.conf)
113
114 - Run syslinux on the floppy:
115 
116	syslinux -s /dev/fd0
117	
118	(the -s stands for "safe, slow, and stupid" and should work better with
119	buggy BIOSes; it can be omitted)
120
121 - Put on a syslinux.cfg file:
122
123	mcopy syslinux.cfg a:
124
125	(more on syslinux.cfg below)
126
127 - Copy the root file system you made onto the MSDOS formatted floppy
128
129	mcopy rootfs.gz a:
130
131 - Build a linux kernel and copy it onto the disk with the filename 'linux'
132
133	mcopy bzImage a:linux
134
135
136Sample syslinux.cfg
137~~~~~~~~~~~~~~~~~~~
138
139The following simple syslinux.cfg file should work. You can tweak it if you
140like.
141
142----begin-syslinux.cfg---------------
143DEFAULT linux
144APPEND initrd=rootfs.gz root=/dev/ram0
145TIMEOUT 10
146PROMPT 1
147----end-syslinux.cfg---------------
148
149Some changes you could make to syslinux.cfg:
150
151 - This value is the number seconds it will wait before booting. You can set
152   the timeout to 0 (or omit) to boot instantly, or you can set it as high as
153   10 to wait awhile.
154
155 - PROMPT can be set to 0 to disable the 'boot:' prompt.
156
157 - you can add this line to display the contents of a file as a welcome
158   message:
159
160	DISPLAY display.txt
161
162
163
164Additional Resources
165--------------------
166
167Other useful information on making a Linux bootfloppy is available at the
168following URLs:
169
170http://www.linuxdoc.org/HOWTO/Bootdisk-HOWTO/index.html
171http://www.linux-embedded.com/howto/Embedded-Linux-Howto.html
172http://linux-embedded.org/howto/LFS-HOWTO.html
173http://linux-embedded.org/pmhowto.html
174http://recycle.lbl.gov/~ldoolitt/embedded/ (Larry Doolittle's stuff)
175
176
177
178Possible TODOs
179--------------
180
181The following features that we might want to add later:
182
183 - support for additional filesystems besides ext2, i.e. minix
184 - different libc, static vs dynamic loading
185 - maybe using an alternate bootloader
186