APPLICATION NOTE Using DiskOnChip Under Linux With M-Systems Driver SWM-640000016 rev A
APPLICATION NOTE Using DiskOnChip Under Linux With M-Systems Driver RTD Embedded Technologies, INC. 103 Innovation Blvd. State College, PA 16803-0906 Phone: +1-814-234-8087 FAX: +1-814-234-5218 E-mail sales@rtd.com techsupport@rtd.com web site http://www.rtd.com Using DiskOnChip Under Linux With M-Systems Driver - 2 -
Revision History 05/03/2004 Revision A issued Published by: RTD Embedded Technologies, Inc. 103 Innovation Blvd. State College, PA 16803-0906 Copyright 2004 by RTD Embedded Technologies, Inc. All rights reserved Printed in U.S.A. The RTD Logo is a registered trademark of RTD Embedded Technologies. cpumodule and utilitymodule are trademarks of RTD Embedded Technologies. PhoenixPICO and PheonixPICO BIOS are trademarks of Phoenix Technologies Ltd. PS/2, PC/XT, PC/AT and IBM are trademarks of International Business Machines Inc. MS- DOS, Windows, Windows 95, Windows 98 and Windows NT are trademarks of Microsoft Corp. PC/104 is a registered trademark of PC/104 Consortium. All other trademarks appearing in this document are the property of their respective owners. Using DiskOnChip Under Linux With M-Systems Driver - 3 -
Reference Configuration This procedure is known to work with the following configuration: * Base install of Red Hat Linux 7.3 performed on an RTD CMX27686 cpumodule * 2.4.25 kernel built from source code downloaded from www.kernel.org and with the CPU type set to 386 * 144 MB M-Systems DiskOnChip 2000 * M-Systems TrueFFS Linux driver version 5.1.4 * M-Systems Linux driver installation manual (distributed with driver) * LILO version 22.3.2 (distributed with driver) * DiskOnChip DOS utilities and BIOS driver version 5.1.4 * Creating a single partition on the device * Using ext2 as the DiskOnChip file system type * Setting the DiskOnChip as the first available disk drive when booting from it Introduction To use a DiskOnChip under Linux, you need a device driver. M-Systems provides the TrueFFS driver consisting of a binary kernel module and some source code. According to M-Systems, "TrueFFS for Linux is GPL compliant". However, restrictions exist on its distribution. See the M-Systems web site (http://www.m-sys.com) for more information. M-Systems recommends that you use their driver instead of the Linux Memory Technology Device (MTD) driver. This document functions as an adjunct to, and clarification of, the M-Systems Linux driver installation manual. It is not a step-by-step recipe for configuring DiskOnChip functionality; that's the purpose of the M-Systems procedure. Rather, this application note: 1) adds supplementary information to the M-Systems manual, 2) makes corrections where needed, and 3) points out some things to watch for. By using the installation manual, this application note, and other resources as needed, you should be able to get Linux to work with a DiskOnChip. For More Information The Linux Documentation Project contains a HOWTO for making Linux boot disks. This document gives some ideas on selecting files for inclusion in a minimal, self-contained boot disk; when such a disk is booted, it provides a bare-bones Linux environment. This information can be generalized to creating a Linux boot environment on a DiskOnChip. The HOWTO also furnishes some troubleshooting tips for when the boot process succeeds partway but then fails. M-Systems produced a document called "Using the DiskOnChip with Linux OS" (document number IM-DOC-021). Unfortunately, it is no longer available from M-Systems but you should be able to find it by doing a web search for the document number. The last revision appears to be 3.2. This document is out of date (referring to prior versions of the Linux driver and build process) but does provide some guidance such as selecting files for inclusion in the minimal file system and how to create a partition table on the DiskOnChip device. It should be used as a general reference only and not as an example of how to set up your system. Kernel source code contains instructions on how to build the kernel. These directions can be found in the text file linux-<kernel version>/readme, where linux-<kernel version> is the directory created when the kernel source was extracted. O'Reilly (www.oreilly.com) published a book "Building Embedded Linux Systems" written by Karim Yaghmour. This manuscript contains much information pertinent to those seeking to run Linux from Solid State Devices. Using DiskOnChip Under Linux With M-Systems Driver - 4 -
Please see the Application Note SWM-640000010 (Using a DiskOnChip Under Linux) on our web site for general information on DiskOnChip and Linux. Preliminaries The hardware manual for your cpumodule contains a section on the setup required to begin using a DiskOnChip. Please refer to this manual for details on BIOS configuration. You will need several files from the M-Systems web site. Download the following: - TrueFFS Linux driver (current version 5.1.4; gzip'd tar file) - DiskOnChip DOS utilities and BIOS driver (current version 5.1.4; zip file) After you have extracted the Linux driver files, thoroughly read the driver installation manual procedure (currently this is the text file <extraction directory>/linux_binary.5_1_4/doc-linux-5_1_4_20/readme_install.txt). Unzip the DOS utilities to a directory. Create a DOS boot floppy disk. From the directory where you unzipped the utilities, copy the dformat.exe and doc514.exb files onto the floppy disk. This boot disk will be used whenever you need to format the DiskOnChip. Configuring Linux for DiskOnChip Usage The organization of this document follows that of the M-Systems procedure, with each section representing a section from that procedure. 1. Before you begin The _doc_linux_dir_/mkbootdisk shell script referred to is actually named mkbootdisk_doc. If you decide to create a Linux boot disk before starting, use the native Linux shell script (/sbin/mkbootdisk on Red Hat) instead. 2. Installing DiskOnChip driver It appears as if M-Systems does not support compiling the TrueFFS driver into the kernel. Therefore, it must be created as a loadable module. 2.1. Format the DiskOnChip Instead of using the Linux dformat supplied with the driver, use the dformat command on the DOS boot floppy you created earlier. This means you will need to boot from this floppy each time formatting the device is required. If your DiskOnChip currently contains firmware, once you enable the extension window in the computer's BIOS you will need to remove the firmware. The extension window needs to be enabled whenever the device will be accessed for any reason, for example writing files to it or booting from it. If you wish to temporarily disable the device, you can simply turn off the BIOS extension window; you will not be able to access it again until you enable the window. Using DiskOnChip Under Linux With M-Systems Driver - 5 -
The command you use to format the DiskOnChip depends upon whether you wish to use it as a storage device or as a boot device. For use as a storage device, issue the "dformat /win:xxxx /s:doc514.exb! /y /nodos" command. If the DiskOnChip is to be used as a boot device, issue the "dformat /win:xxxx /s:doc514.exb /y /nodos /empty" command. If you ever need to remove the firmware (yet keep space reserved for it) without disturbing the rest of the data on a device, you can issue the "dformat /win:xxxx /s:doc514.exb /y /noformat /empty" command. The xxxx in the "/win:xxxx" argument refers to the extension window you set in the BIOS. See the M-Systems DOS utilities documentation for more information about dformat and its options. Once you format the device, you can reboot into Linux to continue with the process. 2.2. Install driver sources The patch file linux-2_4_7-patch is known to work with recent kernels. It was used for the purpose of creating this document. 2.3. Create nodes Invoking the mknod_fl shell script as instructed will create the device files with a block major number of 100. In addition to creating the fla1 fld4 files, mknod_fl also creates the files fla fld. 2.4. Change kernel configuration If you decide to create a bootable DiskOnChip file system of a type other than ext2, make sure that you build the driver for that file system into the kernel and not as a module. KEEP IN MIND: the only file system tested with this application note was ext2. It can take a while for the kernel to load the doc module, to the point of the system appearing to lock up. Be patient. 2.5. Initialize file system on DiskOnChip You must create a partition on the DiskOnChip. For this application note, a single partition of type Linux (ID 83) was created. 2.6. Mount DiskOnChip partitions Before you can mount a partition, you must create a file system in that partition. For example, to create an ext2 file system on the first partition issue the "mke2fs /dev/msys/fla1" command. You could add an entry for the DiskOnChip file system to /etc/fstab, which would make it easier to mount the file system. However, this seems to cause problems on boot unless the entry is created properly; it's best to just not add this entry. Once you have completed all steps in the M-Systems procedure up to and including this one, the DiskOnChip device is usable as a storage device. If you do not wish to boot off the device, you do not need to perform any further steps. Using DiskOnChip Under Linux With M-Systems Driver - 6 -
2.7. Install the correct boot loader Unfortunately, you will end up having to build LILO from source code. Neither the executable in _doc_linux_dir_/lilo nor the one in _doc_linux_dir_/lilo/lilo-22.3.2 has DiskOnChip support. Using either of these will result in an error message similar to "Fatal: Sorry, don't know how to handle device" when you attempt to write the boot sector. Building LILO requires that the Netwide Assembler nasm be installed on your system. The _doc_linux_dir_/lilo/boot.b file supplied in the tar file will work. In the paragraph which talks about the device major number used by LILO, the insmod parameter "fl_major=62" is incorrect. This should be "major=62". It is highly recommended that the device major number used by LILO be changed as detailed in the M-Systems manual. Do this before compiling LILO. If you do not change LILO's idea of the DiskOnChip major number, then you will need to do the following to get everything working correctly: * Add the line "options doc major=62" to /etc/modules.conf. If this file does not exist, it must be created. * Copy /etc/modules.conf to the DiskOnChip file system under <mount point>/etc. * Copy the modprobe command onto the DiskOnChip file system. modprobe is needed because it reads /etc/modules.conf whereas insmod does not. * Remake the /dev files by issuing the command "mknod_fl 62". 2.8. Modify /etc/lilo.conf as follows You will need to create /etc/lilo.conf if it does not already exist on your system. If your kernel requires special options to be passed to it at boot, these options must be included in /etc/lilo.conf for the kernel to boot properly. For example, if your kernel needs the "ide=nodma" option you can add the line `append = "ide=nodma"`. See the LILO documentation for more information. 2.9. Create initrd file An initrd file is an initial ramdisk image. Such a file is needed because the TrueFFS driver is built as a module. This module is needed before the DiskOnChip file system is mounted, which creates a problem because that's where the module is. The initial ramdisk image contains kernel modules which must be available to get the kernel to boot to the point where the file system can be mounted. The boot process loads the file into memory and the kernel loads modules from this memory area. If your Linux distribution contains a native mkinitrd command, use it instead of the one supplied by M-Systems. The doc module must be preloaded if you do use the native command. See the mkinitrd documentation for more information. The native mkinitrd command "/sbin/mkinitrd -f -v --preload=doc /boot/initrd-2.4.25.img 2.4.25" was used during the creation of this document. For some reason, the Red Hat 7.3 version of mkinitrd printed an error message from the shell about "--preload=doc" but still created the image properly. If during a failed boot from DiskOnChip you see error messages regarding module problems, chances are good that your initial ramdisk image isn't as complete as it should be. Using DiskOnChip Under Linux With M-Systems Driver - 7 -
2.10. Copy Linux system files to DiskOnChip This part of the procedure is very distribution specific. A detailed discussion of which files need to be copied to the device is beyond the scope of this application note. Contact your distribution vendor for more information. The M-System mkdocimg shell script can be used as a starting point for copying files to the DiskOnChip. Even though Red Hat 7.3 Linux was used, the file redhat-7.1.files provided a decent beginning. Even so, the /bin, /dev, /etc, and /lib directories needed to be copied in entirety to the bootable file system. One can quickly run out of space on the target device. If you do use the mkdocimg script, here are some things you'll need to keep in mind: * It does not copy the initial ramdisk image from /boot to the DiskOnChip file system. * /boot/boot.b is not copied to the DiskOnChip file system. * /lib library files were not duplicated on the device. Because of these issues, pay particular attention to what gets copied over to the bootable file system. Double check everything. A missing critical file will manifest itself during a boot from the DiskOnChip. The boot will proceed past kernel decompression some distance and then fail. Error messages may vary greatly, as will location of the failure. Please see the Linux boot disk HOWTO for more information. 2.11. Store new lilo configuration Earlier use of the M-Systems mkdocimg shell script causes problems to pop up at this point. When it runs, mkdocimg creates a LILO configuration file in the bootable file system from a template (making some substitutions to arrive at the final file). The script then runs LILO using this lilo.conf file to install the boot loader on the DiskOnChip. Trouble is the manufactured lilo.conf has some errors in it, particularly in regards to path names and file names, specifically on the "install=" line. If you do not correct these errors and rerun LILO, you will not be able to boot from the device. To be safe, make sure that 1) /etc/lilo.conf has appropriate path and file names, 2) all files referenced in /etc/lilo.conf exist exactly where they're expected to be in the bootable file system, and 3) copy /etc/lilo.conf to the DiskOnChip. Then, rerun LILO as indicated in this section of the installation manual. 2.12. Update firmware You must reinstall the firmware to be able to boot from the DiskOnChip. Instead of using the Linux dformat supplied with the driver, use the dformat command on the DOS boot floppy you created earlier. Therefore, at this point you will have to shutdown and reboot from the DOS floppy. To prepare the device, issue the command "dformat /win:xxxx /s:doc514.exb /y /noformat /first". Recall that the xxxx in the "/win:xxxx" argument refers to the extension window you set in the BIOS. 2.13. Reboot and enjoy After reinstalling the firmware, remove the DOS floppy and reboot again. You should see a TrueFFS message and an M-Systems copyright; these indicate that the firmware is loaded. Next, the LILO boot menu should appear. If you do not see the LILO boot menu, then LILO probably was not installed in the DiskOnChip boot sector. Using DiskOnChip Under Linux With M-Systems Driver - 8 -
Once the LILO menu appears, wait five seconds and Linux will begin booting. First, the kernel uncompresses itself. If the system hangs at this point, potential causes are an incorrect /etc/lilo.conf file, forgetting to rerun LILO after making changes, and using a LILO which is not DiskOnChip aware. Other causes of failure during boot include a misconfigured kernel, a bad initial ramdisk image, missing kernel modules, or missing files in the boot file system. If the kernel fails to boot, the firmware will need to be removed so that you can troubleshoot and then make repairs. Using the DOS floppy, issue the "dformat /win:xxxx /s:doc514.exb /y /noformat /empty" command; this leaves the file system intact so that it can be mounted once Linux is booted. Using DiskOnChip Under Linux With M-Systems Driver - 9 -