*** The Linux MTD, JFFS HOWTO ***
The entire MTD/DOC/JFFS (and some utils) source code may be downloaded via anonymous CVS.
Follow the following steps: 1.Make sure that you are root. 2. cd /usr/src 3. cvs -d :pserver:anoncvs@cvs.infradead.org:/home/cvs login (password: anoncvs) 4. cvs -d :pserver:anoncvs@cvs.infradead.org:/home/cvs co mtd
This will create a dir called mtd under /usr/src
You now have two options depending on what series of the Linux Kernel you want to work with. There is an extra step involved with the 2.2 series kernels as they do not have any MTD code in them.
Note: Check under /dev/ If you do not have devices like mtd0,1,2 and mtdblock0,1,2 etc. run the MAKEDEV utility found under mtd/util as: #sh /usr/src/mtd/util/MAKEDEV This will create all the proper devices for you under /dev
** With 2.2.x series kernels:
(Note that as far as I can tell, mtd and jffs does not work as modules under the 2.2.x series of kernels. If you want to do modules I would recommend that you upgrade to the 2.4.x series of kernels).
Get the 2.2.17 or 2.2.18 kernel source code from your favorite source (ftp.kernel.org) and install the kernel under /usr/src/linux-2.2.x with /usr/src/linux being a symbolic link to your kernel source dir.
Configure the kernel to your desired options (by doing a make config (or menuconfig or xconfig), and make sure that the kernel compiles ok.
Download the mtd patch from: ftp://ftp.infradead.org/pub/mtd/patches
Move the patch to /usr/src/linux and do
patch -p1 < <patch file name here>
Make sure that the patch was applied ok without any errors. This will add the mtd functionality to your basic kernel and bring the mtd code up-to date to the date of the patch.
You have two choices here. You may do a make config and configure in mtd stuff with the current code or you may want to get the latest code from the cvs patched in.
If you want the latest CVS code patched in follow the 2.4.x directions below.
** With 2.4.x series of kernels:
If you want the latest code from CVS (available under /usr/src/mtd) do: 1. cd /usr/src/mtd/patches 2. sh patchin.sh /usr/src/linux
This will create symbolic links from the /usr/src/linux/drivers/mtd/<files here> to the respective files in /usr/src/mtd/kernel/<latest files here>
The same happens with /usr/src/linux/fs/jffs and /usr/src/linux/include/linux/mtd
Now you have the latest cvs code available with the kernel. You may now do a make config (or menuconfig or xconfig) and config the mtd/jffs etc. stuff in as described below.
*** Configuring MTD and friends for DOC in the Kernel:
Do not use any mtd modules with the 2.2.x series of kernels. As far as I can tell, it does not work even if you can get it to compile ok.
Modules work ok with the 2.4.x series of kernels.
Depending on what you want to target you have some choices here, namely:
*** 1. Disk On Chip Devices (DOC): For these, you need to turn on (or make into modules) the following:
* MTD core support
* Debugging (set the debug level as desired)
* Select the correct DOC driver depending on the DOC that you have. (1000, 2000 or Millennium). Note that the CONFIG_MTD_DOC2000 option is a driver for both the DiskOnChip 2000 and the DiskOnChip Millenium devices. If you have problems with that you could try the alternative DiskOnChip Millennium driver, CONFIG_MTD_DOC2001. To get the DiskOnChip probe code to use the Millennium-specific driver, you need to edit the code in docprobe.c and undefine DOC_SINGLE_DRIVER near the beginning.
* Unless you are doing something out of the ordinary, it shouldn't be necessary for you to enable the "Advanced detection options for DiskOnChip" option.
* If you do so, you can specify the physical address at which to probe for the DiskOnChip. Normally, the probe code will probe at every 0x2000 bytes from 0xC8000 to 0xEE000. Changing the CONFIG_MTD_DOCPROBE_ADDRESS option will allow you to specify a single location to be probed. Note that your DiskOnChip is far more likely to be mapped at 0xD0000 than 0xD000. Use the real physical address, not the segment address.
If you leave the address blank (or just don't enable the advanced options), the code will *auto probe*. This works quite well (at least for me). Try it first.
* Probe High Addresses will probe in the top of the possible memory range rather than in the usual BIOS ROM expansion range from 640K - 1 Meg. This has to do with LinuxBIOS. See the mailing list archive for some e-mails regarding this. If you don't know what I am talking about here, leave this option off.
* Probe for 0x55 0xaa BIOS signature. Unless you've got LinuxBIOS on your DiskOnChip Millennium and need it to be detected even though you've replace the IPL with your chipset setup code, say yes here.
Leave everything else off, till you reach... User Modules and Translation layers: * Direct char device access - yes * NFTL layer support - yes * Write support for NFTL(beta) - yes
Note that you don't need 'MTDBLOCK' support. That is something entirely different - a caching block device which works directly on the flash chips without wear levelling.
Save everything, make dep, make bzImage, make modules, make modules_install
Note: If you downloaded the 2.4.x series kernels and your original installed distribution came with the 2.2.x series of kernels then you need to download the latest modutils (from ftp.kernel.org/utils/kernel), else make modules_install or depmod -a will fail for the new 2.4.x kernels.
Move everything to the right place, install the kernel, run lilo and reboot.
If you compiled the mtd stuff into the kernel (see later section if you compiled as modules- which is what I prefer as you don't have to keep rebooting) then look for the startup messages. In particular pay attention to the lines when the MTD DOC header runs. It will say something like:
"DiskOnChip found at address 0xD0000 (your address may be different)" "nftla1"
The above shows that the DOC was detected fine and one partition was found and assigned to /dev/nftla1. If further partitions are detected, they will be assigned to /dev/nftla2 etc.
Note that the MTD device is /dev/mtd0 and details are available by doing a:
#cat /proc/mtd dev: size erasesize name mtd0: 02000000 00004000 "DiskOnChip 2000"
/dev/nftla1,2,3 are "regular" block disk partitions and you may mke2fs on them to put a ext2 fs on it. Then they may be mounted in the regular way.
When the DiskOnChip is detected and instead of nftla1,2,3... you get something like:
"Could not find valid boot record" "Could not mount NFTL device"
...first make sure you have the latest DiskOnChip and NFTL code from the CVS repository.
If that doesn't help you, especially if the driver has previously exhibited strange and buggy behaviour, and if the DOS driver built into the device no longer works, then it's possible that you have a "hosed" (that's a technical term) disk. You need to "un-hose" it. To help you out in that department there is a utility available under /usr/src/mtd/util called nftl_format.
DO NOT EVER USE THE nftl_format UTILITY WITHOUT FIRST SEEKING ADVICE ON THE MAILING LIST. It will erase all blocks on the device, potentially losing the factory-programmed information about bad blocks. (Someone really ought to fix it one of these days - ed)
Essentially after your disk have been detected but complains about "Could not mount NFTL device", just run #./nftl_format /dev/mtd0 (if your device was installed under mtd0, see cat /proc/mtd/).
You should unload the nftl driver module before using the nftl_format utility, and reload it afterwards. Reformatting the NFTL underneath the driver is not a recipe for happiness. If the driver hasn't recognised the NFTL format, then it's safe - reboot or reload the module after running nftl_format and it should then recognise it again.
If your device "erasesize" is 8k (0x2000), then the utility will go ahead and format it. Just reboot and this time the drivers will complain about an "unknown partition table".
Don't worry. Just do: # fdisk /dev/nftla
and create some partitions on them. TaDa! You may now e2fsck and others on these partitions. Note that if you don't want more than one partition you don't need to muck about with partitions at all - just make a filesystem on the whole device /dev/nftla instead of partitioning and using /dev/nftla1.
*** IF you compiled the mtd stuff as modules (What I prefer): Make sure that you have done a depmod -a after you reboot with the new kernel.
Then just #modprobe -a doc2000 nftl mtdchar mtdblock
You have now loaded the core stuff. The actual detection takes place only when you load the docprobe module. Then do #modprobe -a docprobe
You should then see the messages described in the section above. Follow the directions and procedures are outlined in the section above (where you would have compiled the mtd/DOC stuff into the kernel).
*** 2. Raw Flash (primarily NOR) chips
This are multiple (or just one) flash IC's that may be soldered on your board or you may be designing some in. Unlike the DOC device, these are usually linearly memory mapped into the address space (though not necessarily, they may also be paged).
MTD can handle x8, x16 or x32 wide memory interfaces, using x8, x16 (even x32 chips (are they such a thing)?- confirm).
At present CFI stuff seems to work quite well and these are the type of chips on my board. Hence I will describe them first. Maybe someone with JEDEC chips can describe that.
You must use (for all practical purposes that involve writing) JFFS on raw flash MTD devices. This is because JFFS provides a robust writing and wear leveling mechanism. See FAQ for more info.
If you only want the file-system to be writable while you're developing, but will ship the units read-only, it's acceptable to use the MTDBLOCK device, which performs writes by reading the entire erase block, erasing it, changing the range of bytes which were written to, and writes it back to the flash. Obviously that's not something you want happening in production, but for development it's OK.
*** Configuring the kernel with MTD/CFI/JFFS and friends. Turn off all options for MTD except those mentioned here.
* MTD support (the core stuff) * Debugging -yes (try level 3 initially) * Support for ROM chips in bus mapping -yes * CFI (common flash interface) support -yes * Specific CFI flash geometry selection -yes * <select they FLASH chip geometry that you have on your board> * If you have a 32 bit wide flash interface with 8bit chips, then you have 4 way interleaving, etc. Turning on more than one option does not seem to hurt anything * CFI support for Intel.Sharp or AMD/Fujitsu as your particular case may be. * Physical mapping of flash chips - set your config here or if you have one of the boards listed then select the board as the case may be.
Then under "File systems" select: * jffs and * /proc file-system support right under that. * Select a jffs debugging verbosity level. Start high then go low.
Save, make dep, make bzImage, make modules, make modules_install, move kernel to correct spot, add lilo entries, run lilo (or your fav. boot loader) and reboot.
If you have compiled the stuff as modules then do (as root): # depmod -a # modprobe -a mtdchar mtdblock cfi_cmdset_0002 map_rom cfi_probe
This loads the core modules for cfi flash. Now we probe for the actual flash by doing: #modprobe -a physmap
Look at the console window (Note if you are telnet'd into the machine, then the console may be outputting on tty0 which may be the terminal connected to the graphics card). Being able to see the console is very important. You may also view kernel console messages at /var/log/messages (this depends on the distribution you are using. This is true for Red Hat).
Don't be fooled by the message: "physmap flash device:xxxxx at yyyyyyy"
This is just reporting what parameters you have compiled into the system (see above under "Physical mapping of flash chips".
If your flash is really detected then it will print something like: "Physically mapped flash: Found bla-bla-bla at location 0".
If no device is found, then physmap will refuse to load as a module! This is not a problem with compiling it as a module or with physmap or modprobe itself. Unfortunately this is the hard part. You have to dive into the routine "do_cfi_probe()" called from physmap.c.
Caution! physmap.c uses ioremap() to map the physical memory into an area of logical memory. If your processor has a cache in it, then modify physmem to use ioremap_nocache(), else you will tear your hair out as your flash chips will never be detected.
This routine is called cfi_probe() and is in the file "cfi_probe.c" under mtd/kernel/
Sprinkle the file with printk's to see why your chips were not detected. If your chips are detected, then when you load physmap (by doing a "modprobe physmap", you will see something like:
"Physically mapped flash: Found bla-bla-bla at location"
Now, the chips have been registered under mtd and you should see them by doing a: #cat /proc/mtd
*** Putting a jffs file system on the flash devices:
Now that you have successfully managed to detect your flash devices, you need to put a jffs on them. Unlike mke2fs there is no utility that will directly create a jffs file-system onto the /dev/mtd0,1,2... device.
You have to use a utility called mkfs.jffs available under mtd/util
Get a directory ready with the stuff that you want to put under jffs. Let's assume that it's called /home/jffsstuff
Then just do: #/usr/src/mtd/util/mkfs.jffs -d /home/jffsstuff -o /tmp/jffs.image
This makes a jffs image file. Then do (if your flash chips are erased, else see below): #cp /tmp/jffs.image /dev/mtd0,1,2... (as the case may be, most likely /dev/mtd0).
You may also mount an erased mtdblock device directly without putting a file system on it. This will let you fill the device interactively under your shell control (you know- copy stuff to the mounted dir).
If your flash chips are not erased or you have been messing around with them earlier, your cannot just copy the new image on top of the older one. Bad things may happen. Use the program mtd/util/erase to erase your device.
#/usr/src/mtd/util/erase /dev/mtd0,1,2,3 <offset> <erase-size> where offset: try 0 if you don't know (start of mtd device), else must be in decimal bytes, but must start at an integral erase sector boundary.
erase-size: How many "erase sectors" worth do you want to erase. Your max erase size for your flash is: (total-size/your mtd device erase size- look under `cat /proc/mtd`)
Watch the messages on your console (assuming you have verbose turned on when you configured your kernel). You should not see any errors.
When your command prompt returns, do: #cp /tmp/jffs.image /dev/mtd0,1,2... (as the case may be, most likely /dev/mtd0).
Then load the jffs module in by: #modprobe jffs
Then mount the file system by: #mount -t jffs /dev/mtdblock0 /mnt/jffs (assuming /mnt/jffs exists, else make it).
Note: Note the use of /dev/mtdblock0 NOT /dev/mtd0. "mount" needs a block device interface and /dev/mtdblock0,1,2,3... are provided for that purpose. /dev/mtd0,1,2,3 are char devices are provided for things like copying the binary image onto the raw flash devices.
*** Making partitions with CFI flash and working with multiple banks of FLASH:
Unlike a "regular" block device, you cannot launch fdisk and create partitions on /dev/mtdblock0,1,2,3...
(As far as I know) CFI flash partitions have to be created and compiled in the physmap.c file.
The same goes for multiple banks of flash memory. (IS THIS CORRECT???? Check and correct.)
An example of creating partitions can be found in the file mtd/kernel/sbc_mediagx.c
An example of multiple banks of flash chips being mapped into separate /dev/mtdn devices can be found in the file mtd/kernel/octagon_5066.c (in particular pay attention to the multiple looping of the code while registering the mtd device in "init_oct5066()". You may also add partitions to each bank by looking at code in mtd/kernel/sbc_mediagx.c
*** Mounting a JFFS(1 or 2) F/S as root device. This is rather simple.
*Note: This assumes that you can some how boot your kernel. This section does NOT deal with booting your kernel from an mtd partition or device. You may be doing this by booting your kernel off an IDE flash disk/CF disk etc. using lilo. This procedure is the same even when you want to boot the kernel directly off flash. This time you will just burn the kernel into the raw flash device after the "rdev" step below.
1. Make sure that you can detect your flash devices and read and write them though the MTD device nodes (/dev/mtdn). 2. Make sure than you can mount the required JFFS(1 or 2) f/s on your flash devices and copy files to it, unmount, reboot, re-mount and still see your files there (also do a "diff" on a couple of files to make sure that the data did not get corrupted). 3. Compile all the required MTD/JFFS(1/2) support into the kernel (using modules to mount root is left as an exercise for the reader). 4. Tell the kernel what your root device is going to be. Do that by: # rdev <your flash image here> /dev/mtdblock<n> where mtdblock<n> is where you have constructed your root fs that you want to mount as root on reboot. 5. Run your boot loader init program (lilo for LILO bootloader). 6. Reboot. Your jffs mtdblock<n> partition should be mounted as root.
*** Mounting a *compressed* ext2 file system stored on an mtd partition or device as root. Ah! Ha! This is much more fun (and complicated). Prerequisites: a. You must have ramdisk support in your development system kernel at least as large as the final root f/s that will be mounted in your target. This is for compressing the root f/s only. If you already have a ready-to-go compressed root f/s then you can skip this stage.
Steps: 1. Make a "root" file system on your mtd enabled development system. (mtd "enabled" means that you are running a kernel that supports mtd and that you can write to your mtd flash devices from your development station). The creation of this "root" file system is left to the reader. There are numerous ready available root f/s out on the net. Use any one or create your own (this is not necessarily fun if you have never done this before).
2. Make an ext2 f/s in ramdisk as large as you want the final uncompressed root f/s to be. Do that as thus:
#mke2fs /dev/ram0 <you_root_fs_size_in_1k_blocks_here>
3. Mount this empty f/s on a free dir under /mnt as:
#mount -t ext2 /dev/ram0 /mnt/ramdisk
4. Copy your "root fs" dir that you have so carefully made over to this ramdisk.
#cp -af /tmp/my_final_root_fs_files/* /mnt/ramdisk
5. If you have done everything right till now you should be able to see the required "root" dir's (that's etc, root, bin, lib, sbin...) if you do a:
# ls -ld /mnt/ramdisk
6. Now unmount and compress the file system.
#umount /mnt/ramdisk
#dd if=/dev/ram0 bs=1k count=<your_root_fs_size_in_1k_blocks> | gzip \ -9 > /tmp/compressedRootFS.gz
7. Now we have to tell your kernel that will be mounting this compressed file system that this is a compressed f/s and where to find it on the mtd device. Make sure that your mtd stuff is all compiled into the kernel. Additionally you must make the following 2 changes to the kernel. This applies both to the 2.2.x and 2.4.x series.
A. In the file drivers/block/rd.c you must comment out the check made for ROOT_DEV to be a floppy device. This code usually looks like:
if (MAJOR(ROOT_DEV) != FLOPPY_MAJOR #ifdef CONFIG_BLK_DEV_INITRD && MAJOR(real_root_dev) != FLOPPY_MAJOR #endif ) return;
You must *NOT* return here, as your ROOT_DEV will *NOT* be a floppy device, it will be the mtd block device.
B. At this time, due to the link order the rd_load() call to load any compressed files systems into ramdisk are made before the mtd driver has a chance to register the mtd block device. This causes the rd_load() code to fail to find your root device to load your compressed f/s from. Till this issue is fixed in the kernel, you have to make another explicit call to rd_load() right before mount_root() in main.c So, just add a call to rd_load() immediately before mount_root() in init/main.c
C. Now compile the kernel with mtd and ext2 support in it (not as modules). 8. Now tell your target kernel (before installing it in the target) that you want it to load a compressed f/s and where this compressed image lies. There are two ways to do this. The easy way (using command line parameters) and the difficult way. We will do this the difficult way. Figuring out the easy way is left as an exercise for the reader. No, I don't usually like to do things the difficult way just for the fun of it, there is a reason behind this.
I'm moving towards booting a Linux kernel out of raw flash, without the help of a boot load. In that situation we will not have any means to pass any kernel command line parameters.
Tell the target kernel that you want to load a compressed f/s and where your image can be found as thus:
#rdev -r <your_target_kernel_image> <offset_number_in_dec>
where offset_number_in_dec is calculated as follows: This number is the decimal equivalent of a binary number which is made of various bits. Bits 0-9 specify in 1KB blocks the offset from the start of the root device. Bit 14 specifies if a (compressed in our case) ramdisk needs to be loaded- obviously a yes! Why else are you reading this! Other Bits: Set to zero.
Just as a sanity check, 17408 is the number that you plug in as the 2nd parameter to the rdev -r above for the following. This numbers tells the kernel that the offset is 1024 1kblocks (i.e. find and load the compressed image found at the 1 Megabyte offset from the start of the mtd device and mount it at the root device).
Note: If this bit pattern ever changes or you are doubtful of my sanity, please go to arch/i386/kernel/setup.c file and look at the various #define masks there. That's where all this bit magic comes from.
9. Now tell your target kernel what your root device is going to be:
#rdev <your_target_kernel> /dev/mtdblock<0,1,2....n>
10. Now of course you need to copy your compressed f/s image to the proper offset in your mtd device. Making sure that your target device is erased do:
#dd if=/tmp/compressedRootFS.gz bs=1k of=/dev/mtd<0,1,2....n> seek=<num of 1k blocks, in k, here that you told your kernel in above>
So for the 1Meg offset boundary you would put seek=1024
Note: "dd" is going to complain about "operation not permitted" or some such thing. Just ignore that. dd tries to truncate the o/p device, but mtd of course in not going to let somebody like "dd" truncate it. The copy should go on just find.
11. Sanity check (year's of experience has taught me to triple check every step twice ;) Let's make sure that you got the compressed image in ok.
12. We will look at the first few bytes of both images and make sure that they are ok. You can also "dd" the target image back to a file and do a diff on it (left as an exercise for the reader).
#dd if=/dev/mtd<0,1,2...n> bs=1k skip=1024 (or your 1k offset in k) \ od -Ax -tx1 |less Jot down the first few lines. (note the use of "skip" in above, NOT "seek").
Now let's look at your compressed root f/s file on your hard disk: #dd if=/tmp/compressedRootFS.gz | od -Ax -tx1 | less
Compare with the stuff that you jotted down above. They should match (did I need to say that?).
13. Install your kernel however way you are going to boot it (run lilo if you are going to boot using LILO) or place it where it will boot from any other boot loader (or directly from flash etc.).
14. Reboot. This time, you should see the ramdisk loading code run twice and find the compressed image the second time and VFS mount it as root.
Ship it and ask for a pay raise (and send me some of that too)!
*** Booting a Linux kernel without a BIOS off an mtd device and mounting a compressed root file system stored on that device.
This is the holy grail of embedded Linux computing :) I shall attempt to describe how to do this here. Note that at best this can only be a guide as one embedded system differs a *lot* for another, not only in terms of memory maps, but type of processors, type of flash, amount of RAM etc.
* Assumptions: This will (may) help you if your requirements meet the following: You want to:
1. Use the standard Linux kernel as found when you download the entire kernel from ftp.kernel.org
2. Know how to initialize your processor and chipset. This would include, memory map (and chip select decode registers etc.). You should be able to read/write the RAM and flash (if NOR type) from a "simple" init program that you or you hardware guy wrote to test the board. (Note: If you intend to use a BIOS, then this restriction goes away).
3. You are way ahead of the game if your target platform supports an IDE hard disk (note: This is just for the development phase. We will not end up with the hard disk in the final cut). This may not be an unreasonable requirement. You may be able to buy an "eval" or "development" board for the target processor that has a BIOS and supports an IDE disk and serial console at the very least.
4. Do not think that compiling the kernel about 100-200 times is too much effort to get this working ;)
* Overview: We will follow the following steps: 1. Setup and boot linux on the target platform using a hard disk.
2. Take a beer break, take our spouse/(girl/boy)friend out for dinner as they will not see you for a while.
3. Setup mtd drivers so that you can read/write the flash and mount a jffs on it. At this stage we will use modules.
4. Once we are happy and comfortable with #3 above, compile the mtd/jffs stuff into the kernel to prepare for booting. At this stage we will install the kernel on the hard disk and the compressed file system on the mtdblock device and boot that. Then we will either do 5a or 5b as you desire.
