MrCoffee Mini-HOWTO Eric Brower Draft 0.1, 18.Feb.1998 This is the first draft of a Mini-HOWTO which describes various methods for configuring and running Linux on a Sun Microsystems JavaStation-1, code-named MrCoffee. The purpose of this document is to share information I have acquired while attempting to run an embedded Linux kernel on the MrCoffee. Though the methods presented within this document have worked for me, I make absolutely no guarantees regarding the accuracy of the information contained within-- you undertake these methods solely at your own risk. As well, it must be noted that Sun Microsystems does not assume responsibility for any information contained within this document. That said, let's get down to business! ACKNOWLEDGEMENTS ---------------- Short and sweet. David Miller (davem@redhat.com) has been the driving force and main developer of the SPARC Linux kernel. His efforts have provided hardware support for MrCoffee in the Linux kernel. Pete Zaitcev has been the primary kernel developer for MrCoffee support in the Linux kernel (amongst his other kernel endeavors), and has been a valuable resource to me both during my preliminary work with MrCoffee and my continued development efforts. THE BASICS ---------- a SparcStation4 with a PS2 keyboard and mouse, and no SCSI, expansion slots or internal disk. It has four 72-pin SIMM slots, each capable of holding 16MB SIMMs for a total of 64MB of memory. The framebuffer is a TCX, the processor a MicroSPARC-110, and the audio is a CS4231-- same as you would find on an SS4. Of course if you have read this far, you probably know all this already.... SUPPORTED HARDWARE ------------------ Yes, this sounds silly for a system that is pretty much not configurable aside from memory, but keep this one point in mind: At the time of writing, the V3 PROM is NOT supported. Allow me to reiterate: At the time of writing, the V3 PROM is NOT supported. Pete is working on V3 PROM support, but this version of the PROM presents a few difficulties within the kernel that have not yet been worked-out. Many later versions of the HotJava OS automatically upgraded MrCoffee PROMs from V2 to V3. If your system has a V3 PROM, all I can say for now is "be patient" or "get coding." (!!provide specific PROM issues?) BASIC BOOT SEQUENCE ------------------- MrCoffee follows a fairly traditional (if you are used to Sun hardware) net-boot sequence. Since this is not a net-booting HOWTO, I'll assume you are competent with tftp, rarp, bootpd, etc. So to boot MrCoffee, just provide it a tftpboot image via a boot server and away it goes. Since there is no internal disk on MrCoffee, you must decide upon one of the following root filesystem schemas (if you can think of others, I am all ears!): 1) Embedded root filesystem This makes use of the kernel's initrd (initial ramdisk) support for loading an entire root filesystem into memory and running from there. For more info, consult the Documents subdirectory within your Linux kernel sourcetree. 2) NFS-root filesystem This makes use of the kernel's NFS-root filesystem option. Pretty self-explanitory. I'll refrain from commenting much on the two. If you have read this far, you probably already know which of the two best suits your needs. REQUIRED KERNEL SUPPORT ----------------------- So, you may ask, how do I compile a kernel for MrCoffee? To save space and reduce duplicity, I'll assume you are familiar with the kernel building process. If not, check out the kernel documentation which (strangely enough) explains this procedure quite nicely. This section is going to beg for better formatting, but as a first-pass attempt allow me to present "stream-of-consciousness" instructions.... The following kernel options are primarily hardware-related, so please use judgement and configure any other options you might find useful-- I don't really want to hear that I neglected to mention serial port support. **If you plan on making an embedded image, you will need to make a small kernel modification regarding default ramdisk size. More on this later. **If you are compiling on an Ultra-class (64-bit, sun4u) system, you must execute "sparc32 bash" before configuring and compiling the kernel. Otherwise, you'll miss out on 32-bit system kernel options. Required support : PCI hardware support (CONFIG_PCI) Ethernet support (CONFIG_SUN_LANCE) Other required support: For embedded systems, you'll need either ext2 or minix filesystem support (CONFIG_EXT2_FS or CONFIG_MINIX_FS) and ramdisk support (CONFIG_BLK_DEV_INITRD and CONFIG_BLK_DEV_RAM) For NFS-root support, you'll need NFS support (CONFIG_NFS_FS) and NFS-root support (CONFIG_ROOT_NFS) Optional support I'd not leave out: TCX framebuffer support (CONFIG_FB_TCX) IP autoconfiguration (CONFIG_IP_PNP) and friends (_BOOTP and _RARP) If I remember, I'll include sample .config files for both embedded and NFS-root kernels. BUILDING THE NFS-ROOT KERNEL ---------------------------- So, you've already done a "make config" and chosen the appropriate kernel options. You're already half-way there! Simply "make vmlinux" and wait for your kernel to build. Depending upon your build system, this can take what must seem like forever on a SPARCStation 1 to just a minute or so on a 12-processor Ultra Enterprise 4000 with a Gig of RAM running a parallel build ;) Now with kernel in hand, you must perform one last ritual-- the kernel must be converted from ELF to AOUT format or the system PROM will not know how to deal with the kernel image. Thankfully, such a tool is available and may already be present on your system. The command is "elftoaout" and can be invoked in the following manner: elftoaout -o so you can convert your vmlinux to an NFS-root tftpboot image with elftoaout -o tftpboot.img vmlinux I'd recommend naming the tftpboot image appropriately, like "tftpboot_nfsroot_mrcoffee.img," if you are going to do much development. After compiling a few NFS-root images and then a few embedded images you tend to lose track... BUILDING THE EMBEDDED KERNEL ---------------------------- So, you've done a "make config" followed by a "make vmlinux" and you think you are halfway home. Wrong. The embedded image is quite an interesting beastie indeed. If you plan on embedding a filesystem of greater than 4MB, you'll need to modify the kernel source for the initial ramdisk size. Since my MrCoffee has 64MB on board, I usually allow for a ramdisk of 16MB. Any more than this and you might run into a wall regarding image size, but I'll address that later. So, warm-up your vi editor and edit /drivers/block/rd.c around line 99. You'll see something similar to: int rd_size = 4096; /* Size of the RAM disks */ You should change the rd_size to whatever will accomodate the size of the root filesystem you are planning. In my case, this would be 16MB, so I modify the line as follows: int rd_size = 4 * 4096; /* Size of the RAM disks */ Now you should be "ready to rumble." Build the kernel and you are partly done, but not home yet. The embedded image is actually two separate pieces. There is the Linux kernel which we know and love, and there is the filesystem itself. Convert the kernel to AOUT from ELF (as described in the above section) and you are done with half the puzzle. BUILDING THE EMBEDDED FILESYSTEM -------------------------------- (!!This is primarily an overview for now and needs to be fleshed-out) It is late, and I am tired, so here's the first cut at basic instructions. 1) determine what will be on your filesystem This sounds very difficult, and it can be. Depending upon your needs, you might have a filesystem of 4MB or perhaps 16MB. There is a limit on this, as we shall discuss later. My advice for the first-time hacker is to use the "rescue" filesystem that is available in the RedHat or UltraPenguin distribution. We can be fairly certain it boots, and you can customize from there. Alternatively, you can install a distribution in a spare disk and pair it down for your image. 2) create a file to accomodate your filesystem You should now create a plain file which is the size of your desired filesystem. I've found that "dd" is the best candidate for the task. In the case of my 16MB filesystem, I could create it in the following manner: dd if=/dev/zero of=./filesystem.img bs=1k count=16000 Now I have a file named "filesystem.img" which is 16MB in size. Let's put a filesystem on that file, so we can later 'pretend' that the file is an actual disk. I use ext2 filesystem, though some have mentioned that the minix filesystem can save you a bit of space (!!comparison?). Keep in mind that you should ONLY use the filesystem type which is configured into your MrCoffee kernel. mke2fs ./filesystem.img It will complain with "./filesystem.img is not a block special device. Proceed anyway? (y,n)" to which you should naturally answer yes. 3) mount the file as a filesystem so that is can be written This file can now be mounted on your development system and manipulated as if it were a local disk filesystem. If this does not work for you, update your mount utility or make sure that your kernel contains "loopback" device support (if a module, it is loop.o). mount -o loop ./filesystem.img /mnt should do the trick to get your filesystem file mounted loopback at /mnt. Now create your root filesystem there. Please think twice about doing a straight "cp" from one location to your /mnt location. If your image contains symlinks, you might end up with multiple copies of all linked files (especially those large libs) at your destination. Consider using tar or cpio for this task. (!! should describe creation of basic filesystem in more detail) 4) unmount and compress your root filesystem Unmount your newly-created root filesystem umount /mnt and compress with gzip at maximum compression. gzip -v9 ./filesystem.img which gives you ./filesystem.img.gz Yes, I know bzip2 is a better algorithm. Sorry. Now you have the second part of the embedded image complete. 5) piggyback the filesystem onto the kernel image Now you have the onerous task of appending the filesystem image to the kernel and then modifying the kernel binary so that it knows the starting and ending points of both itself and this filesystem image. Luckily for all of us, there is already a utility to do this (and they say that Linux is not friendly!). The utility is named "piggyback" and was written by Jakub Jelinek, SPARC Linux kernel man number two and maintainer of the UltraPenguin distribution. (!!provide a location for this app) Piggyback needs the following: * your AOUT MrCoffee kernel * the System.map file for this kernel * the compressed filesystem image So the last step in tftpboot image creation is: piggyback vmlinux.aout System.map filesystem.img.gz I'd recommend copying your kernel to another location, as piggyback will modify the kernel image you specify, rather than outputting a new file. You now have an embedded filesystem kernel ready to be net-booted by MrCoffee. Assuming all went well, allow me to be the first to congratulate you. If all did not go well, my name is John Smith . ASSORTED THINGS THAT SHOULD BE MENTIONED BUT DON'T YET HAVE A PLACE ------------------------------------------------------------------- I've found that MrCoffee will NOT net-boot an image larger than 10MB. This creates a problem if you are attempting to create an embedded filesystem which is quite large. You can achieve quite good compression ratios with gzip, as my 16MB filesystem compresses to 5.75MB (better than 3:1!), but you will eventually run into a wall once you attempt to piggyback a kernel with larger filesystems. The reasonable solution is to either: 1. arrange to have your init process (or amd, or autofs, etc) mount additional volumes from the network 2. forego embedded for an NFS-root filesystem 3. adjust your expectations of MrCoffee Next topic, X Windows support. Yes, I am working on it and I am pretty darn close. I suppose if it were my job to work on this all day it would have been done quite some time ago, but I must be contented with the few hours each week I have to spend on this endeavor. Basically, the X support is located in two places: the X server itself (90% done) and the kernel (80% done, I hope). Since this is neither a kernel development HOWTO nor an X HOWTO, I'll not get into much more detail here. Suffice to say that this document will be updated as soon as I have finished. Feel free to send me any comments on this draft, as well as success stories. Perhaps the next draft will contain testimonials.... E