Annotation of wikisrc/tutorials/how_to_create_bootable_netbsd_image.mdwn, revision 1.3

1.2       schmonz     1: **Contents**
                      2: 
                      3: [[!toc levels=2]]
                      4: 
                      5: #  Introduction
                      6: 
                      7: The purpose of this document is to guide you to create a [RAM disk](http://en.wikipedia.org/wiki/RAM_disk) image and a custom kernel in order to boot your mini NetBSD off a [Compact Flash](http://en.wikipedia.org/wiki/CompactFlash) or use it to debug it in an emulated environment, such as [qemu](http://en.wikipedia.org/wiki/QEMU). 
                      8: 
                      9: The ramdisk image will have to be inserted into your kernel and then extracted to memory of your embedded device (or your emulator) and used as the root file system, which then can be used by your kernel as if it resided on a "normal" storage media like a hard drive. 
                     10: 
                     11: The steps below were tested in a NetBSD 4.99.20 i386 box. 
                     12: 
                     13: #  Create the ramdisk
                     14: 
                     15: First we need to create the ramdisk that will get embedded into the kernel. The ramdisk contains a filesystem with whatever tools are needed, usually [[basics/init|init(8)]] and some tools like sysinst, ls(1), etc. 
                     16: 
                     17: ##  Standard ramdisk
                     18: 
                     19: To create the standard ramdisk (assuming your source tree lies at `/usr/src` and you have `/usr/obj` and `/usr/tools`): 
                     20:     
                     21:     # cd /usr/src
                     22:     # ./build.sh -O ../obj -T ../tools -u tools
                     23:     # cd /usr/src/etc/
                     24:     # make MAKEDEV
                     25:     # cd /usr/src/distrib/i386/ramdisks/ramdisk-big
                     26:     # make TOOLDIR=/usr/tools
                     27:     
                     28: 
                     29: ##  Custom ramdisk
                     30: 
                     31: If you want to customize the contents of the filesystem, customize the `list` file. Let's say for example that we need the [[basics/uname|uname(1)]] utility to be included in the ramdisk, which is not by default. 
                     32:     
                     33: 
                     34: # cd /usr/src
                     35:     # ./build.sh -O ../obj -T ../tools -u tools
                     36:     # cd /usr/src/etc/
                     37:     # make MAKEDEV
                     38:     # cd /usr/src/distrib/i386/ramdisks/ramdisk-big
                     39:     # cp list list.old
                     40:     
                     41: 
                     42: Then we edit the `list` file, by adding the following line: 
                     43:     
                     44:     PROG    bin/uname
                     45:     
                     46: 
                     47: And after having done it: 
                     48:     
                     49:     # make TOOLDIR=/usr/tools
                     50:     
                     51: 
                     52: Either way, you will get something like this: 
                     53:     
                     54:     #    create  ramdisk-big/ramdisk-big.fs
                     55:     Calculated size of `ramdisk-big.fs.tmp': 5120000 bytes, 65 inodes
                     56:     Extent size set to 4096
                     57:     ramdisk-big.fs.tmp: 4.9MB (10000 sectors) block size 4096, fragment size 512
                     58:             using 1 cylinder groups of 4.88MB, 1250 blks, 96 inodes.
                     59:     super-block backups (for fsck -b #) at:
                     60:      32,
                     61:     Populating `ramdisk-big.fs.tmp'
                     62:     Image `ramdisk-big.fs.tmp' complete
                     63:     
                     64: 
                     65: And verify with: 
                     66:     
                     67:     $ ls -lh ramdisk-big.fs 
                     68:     -rwxr-xr-x  1 root  wheel  4.9M Jun 19 08:33 ramdisk-big.fs
                     69:     
                     70: 
                     71: #  Build the kernel
                     72: 
                     73: Next we shall build our custom kernel with ramdisk support. We may choose any INSTALL* kernel configuration. Here, we will use INSTALL_TINY: 
                     74:     
                     75:     # cd /usr/src/sys/arch/i386/conf
                     76:     # cp INSTALL_TINY MY_INSTALL_TINY
                     77:     
                     78: 
                     79: Then we edit `MY_INSTALL_TINY` file, and we go to the section: 
                     80:     
                     81:     # Enable the hooks used for initializing the root memory-disk.
                     82:     options         MEMORY_DISK_HOOKS
                     83:     options         MEMORY_DISK_IS_ROOT     # force root on memory disk
                     84:     options         MEMORY_DISK_SERVER=0    # no userspace memory disk support
                     85:     options         MEMORY_DISK_ROOT_SIZE=3100      # size of memory disk, in blocks
                     86:     
                     87: 
                     88: The size of `MEMORY_DISK_ROOT_SIZE` must be equal or bigger than the size of your image. To calculate the kernel value you can use following rule: 
                     89:     
                     90:     MEMORY_DISK_ROOT_SIZE=10000 would give 10000*512/1024 = 5000 kb
                     91:     
                     92: 
                     93: We check that the following lines are un-commented: 
                     94:     
                     95:     pseudo-device   md              1       # memory disk device (ramdisk)
                     96:     file-system     MFS             # memory file system
                     97:     
                     98: 
                     99: Once we are done with the configuration file, we proceed with building our kernel: 
                    100:     
                    101:     # cd /usr/src
                    102:     # ./build.sh  -O ../obj -T ../tools -u kernel=MY_INSTALL_TINY
                    103:     
                    104: 
                    105: #  Insert ramdisk to kernel
                    106: 
                    107: Having built our kernel, we may now insert the ramdisk to the kernel itself: 
                    108:     
                    109:     # cd /usr/src/distrib/i386/instkernel
                    110:     # cp Makefile Makefile.old
                    111:     
                    112: 
                    113: Then we edit the `Makefile`, to make sure that the `RAMDISKS` and `MDSETTARGETS` variables are set properly. After the modifications, mine looks like this: 
                    114:     
1.3     ! wiki      115:     #       $NetBSD: how_to_create_bootable_netbsd_image.mdwn,v 1.2 2012/02/05 07:14:36 schmonz Exp $                  
1.2       schmonz   116:     
                    117:     .include <bsd.own.mk>
                    118:     .include "${NETBSDSRCDIR}/distrib/common/Makefile.distrib"
                    119:     
                    120:     #       create ${RAMDISK_*} variables                                             
                    121:     #                                                                                 
                    122:     RAMDISKS=       RAMDISK_B       ramdisk-big
                    123:     
                    124:     .for V F in ${RAMDISKS}
                    125:     ${V}DIR!=       cd ${.CURDIR}/../ramdisks/${F} && ${PRINTOBJDIR}
                    126:     ${V}=           ${${V}DIR}/${F}.fs
                    127:     .endfor
                    128:     
                    129:     MDSETTARGETS=   MY_INSTALL_TINY         ${RAMDISK_B}    -
                    130:     
                    131:     MDSET_RELEASEDIR=       binary/kernel
                    132:     
                    133:     .include "${DISTRIBDIR}/common/Makefile.mdset"
                    134:     
                    135:     .include <bsd.prog.mk>
                    136:     
                    137: 
                    138: Next write: 
                    139:     
                    140:     make KERNOBJDIR=/usr/obj/sys/arch/i386/compile  TOOLDIR=/usr/tools
                    141:     
                    142: 
                    143: Should you encounter errors of the following form, try increasing the `MEMORY_DISK_ROOT_SIZE` at your kernel configuration file. 
                    144:     
                    145:     i386--netbsdelf-mdsetimage: fs image (5120000 bytes) too big for buffer (1587200 bytes)
                    146:     *** Error code 1
                    147:     
                    148: 
                    149: Provided that everything went ok, you will have the following files in your current directory: 
                    150:     
                    151:     # ls -lh netbsd*
                    152:     -rwxr-xr-x  1 root  wheel   21M Jun 20 11:07 netbsd-MY_INSTALL_TINY
                    153:     -rw-r--r--  1 root  wheel  1.5M Jun 20 11:07 netbsd-MY_INSTALL_TINY.gz
                    154:     -rw-r--r--  1 root  wheel   58K Jun 20 11:07 netbsd-MY_INSTALL_TINY.symbols.gz
                    155:     
                    156: 
                    157: #  Make image bootable
                    158: 
                    159: Finally: 
                    160:     
                    161:     # cd /usr/src/distrib/i386/floppies/bootfloppy-big
                    162:     # cp Makefile Makefile.old
                    163:     
                    164: 
                    165: Edit the Makefile if your kernel config has a different name than INSTALL*. Replace `FLOPPYKERNEL= netbsd-INSTALL.gz` with `FLOPPYKERNEL= netbsd-MY_INSTALL_TINY.gz` (Where MY_INSTALL_TINY is of course the name of the custom kernel.) 
                    166:     
                    167:     # make TOOLDIR=/usr/tools
                    168:     [...]
                    169:     Final result:
                    170:     -rw-r--r--  1 root  wheel  2949120 Jun 20 11:15 boot-big1.fs
                    171:     
                    172: 
                    173: Now you are ready to test your image, with qemu for example: 
                    174:     
                    175:     $ cd /usr/src/distrib/i386/floppies/bootfloppy-big
                    176:     $ qemu boot-big1.fs
1.3     ! wiki      177:  
1.2       schmonz   178: 
                    179: #  Credits
                    180: 
                    181: This article is based on [[Yazzy's]] work, who was kind enough to permit us include an article in this wiki. The original document may be found [here](http://www.yazzy.org/docs/NetBSD/netbsd-on-cf.txt). 
                    182: 
                    183: 
                    184: #  Additional related links
                    185: 
1.3     ! wiki      186:   1. [Creating a custom install/boot floppies for i386](http://www.netbsd.org/docs/guide/en/chap-misc.html#chap-misc-creating-bootfloppies)
1.2       schmonz   187: 
                    188: 

CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb