[PATCH] Update UBIFS mounting instructions

Sat Dec 19 18:53:05 PST 2015

On 12/19/2015 09:18 AM, Brian Norris wrote:
> Garbage collecting old patches...
>
> On Wed, Apr 01, 2015 at 01:55:58PM -0700, Matt Kline wrote:
>> I recently spent several days attempting to mount a UBIFS image.
>> Efforts were hampered by seemingly outdated documentation,
>> the fact that much of the documentation was for UBI images,
>> not UBIFS ones, and the fact that the image was for NOR memory and
>> all documentation I found only referenced nandsim.
>>
>> After some very kind help on IRC and from Artem Bityutskiy on the
>> mailing list, I was able to figure things out. I think it is only
>> fair that I contribute back and bring the web site up to date so
>> others don't face the same stumbling blocks.
>>
>> This patch includes the following changes:
>>
>> - Acknowledge that udev _does_ now create a block device
>>    automatically for MTD.
>>
>> - Provide instructions for mounting standalone UBIFS images as well
>>    as UBI images.
>>
>> - Mention mtdram and its usefulness in mounting UBIFS images made
>>    for NOR memory.
>>
>> Signed-off-by: Matt Kline <matthew.kline at flukenetworks.com>
>
> This looks pretty good to me (as in, it's a net positive). I know
> Dongsheng Yang (and Richard?) has been working on some kind of user
> space unpacker tools, so this might be out of date "soon". But when
> isn't documentation out of date? :)

Yes, agreed. BTW, Brian and Richard, I would like to pick patches from
Richard in my local tree, fixing some conflict maybe. And then send a
patchset out about unpacker and ubifs_dump tools. Is that okey?

Yang
>
> Anyway, pushed to mtd-www.git. Improvements are welcome from anyone
> doing updates to this though!
>
> Thanks,
> Brian
>
>> ---
>>   faq/ubifs.xml | 81 +++++++++++++++++++++++++++++++++++++++--------------------
>>   1 file changed, 54 insertions(+), 27 deletions(-)
>>
>> diff --git a/faq/ubifs.xml b/faq/ubifs.xml
>> index 8b61fc7..2b724f3 100644
>> --- a/faq/ubifs.xml
>> +++ b/faq/ubifs.xml
>> @@ -894,10 +894,9 @@ embedded systems.</p>
>>   modprobe nandsim first_id_byte=0x20 second_id_byte=0xaa \
>>                    third_id_byte=0x00 fourth_id_byte=0x15
>>
>> -# MTD is not LDM-enabled and udev does not create device
>> -# MTD device nodes automatically, so create /dev/mtd0
>> -# (we assume that you do not have other MTD devices)
>> -mknod /dev/mtd0 c 90 0
>> +# udev should create MTD device nodes automatically.
>> +# If it does not, we can create /dev/mtd0 manually with
>> +# mknod /dev/mtd0 c 90 0
>>
>>   # Load UBI module and attach mtd0
>>   modprobe ubi mtd=0
>> @@ -917,44 +916,65 @@ mount -t ubifs /dev/ubi0_0 /mnt/ubifs
>>   <h2><a name="L_ubifs_extract">How do I extract files from an UBI/UBIFS image?</a></h2>
>>
>>   <p>Unfortunately, at the moment there are no user-space tools which can
>> -unwrap UBI and UBIFS images. UBIFS cannot be loop-back mounted as well,
>> +unwrap UBI and UBIFS images. UBIFS cannot be loop-back mounted either,
>>   because it does not work with block devices.</p>
>>
>> -<p>However, there is a hacky way to unwrap UBI/UBIFS images. But you have
>> -to make sure you have UBIFS support in your host machine. UBIFS is a relatively
>> -new file system and is not supported by all Linux distributions. But at least
>> -Fedora 11 does include it.</p>
>> +<p>However, kernel modules exist that allow you to create a virtual MTD
>> +onto which UBIFS can be mounted. You have two options:
>> +<ol>
>> +	<li><code>nandsim</code>, which can simulate various NAND devices.
>> +	You can find an incomplete list of those devices
>> +	<a href="../nand-data/nanddata.html">here</a>.
>> +	To emulate a given device, pass its ID bytes via the module parameters
>> +	<code>first_id_byte</code>, <code>second_id_byte</code>,
>> +	<code>third_id_byte</code>, and <code>fourth_id_byte</code>.</li>
>> +
>> +	<li><code>mtdram</code>, which simulates a generic MTD.
>> +	Use the module parameter <code>total_size</code> to specify the device size
>> +	in KiB and <code>erase_size</code> to specify the erase block size in KiB.
>> +	This module is useful for mounting UBIFS images made for NOR memory,
>> +	which usually have a minimum I/O unit of 1 byte, as opposed to NAND
>> +	devices which have a minimum unit of at least 512 bytes.
>> +	See more information <a href="../doc/ubi.html#L_min_io_unit">here</a>.
>> +	</li>
>> +</ol>
>> +These modules should be provided on most distributions released in the past
>> +few years.</p>
>>
>> -<p>Let's consider a simple example. Suppose you have an <code>ubi.img</code>
>> -file. This is an UBI image, which contains a single UBI volume, which in turn
>> -contains UBIFS file-system. In other words, this is an image which was
>> -created using the <code>mkfs.ubifs</code> and <code>ubinize</code> tools,
>> -just like it is described in <a href="ubifs.html#L_mkfubifs">this</a>
>> -section (the image is created for a 256MiB NAND flash with 2KiB NAND page
>> -size and which supports sub-pages). Here is what you can do:</p>
>> +<p>Consider a simple example. Suppose you have some <code>ubifs.img</code>
>> +file which contains a single UBIFS filesystem.
>> +In other words, this is an image which was created using <code>mkfs.ubifs</code>,
>> +as described in <a href="ubifs.html#L_mkfubifs">this</a> section. To mount it:</p>
>>
>>   <pre>
>> -# Create an 256MiB emulated NAND flash with 2KiB NAND page size
>> -# (you should see the new MTD device in /proc/mtd)
>> +# Create a virtual MTD by bringing up one of the kernel modules mentioned above.
>>   modprobe nandsim first_id_byte=0x20 second_id_byte=0xaa \
>>                    third_id_byte=0x00 fourth_id_byte=0x15
>>
>> -# MTD is not LDM-enabled and udev does not create device
>> -# MTD device nodes automatically, so create /dev/mtd0
>> -# (we assume that you do not have other MTD devices)
>> -mknod /dev/mtd0 c 90 0
>> +# udev should create MTD device nodes automatically.
>> +# If it does not, we can create /dev/mtd0 manually with
>> +# mknod /dev/mtd0 c 90 0
>>
>> -# Copy the contents of your image to the emulated MTD device
>> -dd if=ubi.img of=/dev/mtd0 bs=2048
>> +# Format the device. IOSIZE should be the minimum I/O unit size passed
>> +# via -s to mkfs.ubifs when the image was created.
>> +ubiformat /dev/mtd0 -s $IOSIZE
>>
>>   # Load UBI module and attach mtd0
>>   modprobe ubi mtd=0
>>
>> -# Mount UBIFS
>> -mount -t ubifs /dev/ubi0_0 /mnt/ubifs
>> +# Create a volume.
>> +# -N names the volume and -s sets its size, in bytes, kilobytes (KiB),
>> +# or megabytes (MiB). Make sure it is at least as large as the image.
>> +ubimkvol /dev/ubi0 -N "My UBIFS volume name" -s $VOLSIZE
>> +
>> +# Apply our image to that volume
>> +ubiupdatevol /dev/ubi0_0 ubifs.img
>> +
>> +# Mount it to any desired mount point
>> +mount /dev/ubi0_0 /mnt/ubifs
>>   </pre>
>>
>> -<p>Now you have the file-system in <code>/mnt/ubifs</code>. Use
>> +<p>Now you have the filesystem in <code>/mnt/ubifs</code>. Use
>>   the following to get rid of it:</p>
>>
>>   <pre>
>> @@ -962,6 +982,13 @@ umount /mnt/ubifs
>>   rmmod ubifs ubi nandsim
>>   </pre>
>>
>> +If you have an entire UBI image made with <code>ubinize</code>,
>> +the process is simpler.
>> +Write the image to the MTD via <code>ubiformat -f ubi.img</code>
>> +(assuming that is the name of your image file).
>> +You should be able to skip the instructions above after
>> +<code>modprobe ubi mtd=0</code>, since
>> +the UBI image should take care of the volume(s) itself.
>>
>>
>>   <h2><a name="L_smaller_jrn">I need more space - should I make UBIFS journal smaller?</a></h2>
>> --
>> 2.3.4
>>
>> ______________________________________________________
>> Linux MTD discussion mailing list
>> http://lists.infradead.org/mailman/listinfo/linux-mtd/
>
>
> .
>