Patches
-------

This directory contains 3 patches which can be applied to the
fatfs-2.6 kernel tree to provide a patent workaround for the VFAT
patents.

The 3 patches are:

  1) FAT-Added-FAT_NO_83NAME.patch

  2) FAT-Add-CONFIG_VFAT_FS_NO_DUALNAMES-option.patch

  3) FAT-Add-CONFIG_VFAT_NO_CREATE_WITH_LONGNAMES-option.patch

The first patch should be applied to all systems, regardless of
whether you want to work around the VFAT patents. It adds support for
a new flag in FAT directory entries which mark the entries as not
having a 8.3 short name.

The second patch implements a patent workaround by avoiding the
creation of 'dual' names. This is the workaround that provides the
most convenience and minimal disruption for most users. Please see the
'Compatibility' section below for a discussion of the technical
limitations of this workaround.

The third patch implements a simpler workaround that may be suitable
for some embedded devices. It disables the creation of files with long
filenames, returning -1/ENAMETOOLONG when creation of a long filename
is attempted. Reading of long filenames is unaffected. This patch
should not be combined with the 2nd patch.


Discussion
----------

The reasoning behind these patches is contained in a FAQ posted to the
Linux Kernel Mailing List, which can be viewed here:

  http://article.gmane.org/gmane.linux.file-systems/33530

For an in-depth discussion of the pros and cons of this patch, please
see the July 2009 Linux Kernel Mailing List archives. A search on
subjects containing VFAT might be a good starting point.

I will be continuing my interoperability testing of this patch, to
gather more data on whether there are any other FAT implementations in
widespread use which may have interoperability problems with this
patch. 


Compatibility
-------------

The known interoperability concerns with the NO_DUALNAMES patch are:

 - There is a very small probability of WindowsXP crashing with a
   bluescreen when using a filesystem with files created by a patched
   kernel. While nobody has actually been able to make this happen
   with the patch as posted (as the probability is extremely small), the
   large number of WindowsXP boxes in the world makes some people
   nervous about accepting the patch.

 - There is a small probability that the Windows chkdsk.exe utility
   will rename a file created with a patched kernel. While no data is
   lost, the rename could be a inconvenience to some users. The
   probability of a rename varies with the number of files in the
   directory. With 100 files in a directory the probability of a
   rename happening is approximately 0.0000048%. For 32767 files in a
   directory (the maximum possible for VFAT) the probability of one
   file being renamed is approximately 0.5%.

 - The Linux mtools package needs a small patch to avoid a cosmetic
   problem with displaying garbage in the 8.3 name column in mdir. The
   patch for mtools is included in this directory.

 - The dosfstools package needs a small patch to make it understand
   the FAT_NO_83NAME flag. The patch to for dosfstools is included in
   this directory.

 - A patched kernel will no longer add 8.3 shortname aliases for files
   with long names, or files with names that are mixed case within the
   prefix or extension. So for example the file "Example.DAT" would
   have previously had a short name alias "EXAMPLE.DAT", but will only
   have the long name "Example.DAT" with this patch enabled.

Testing
-------

To facilitate testing of this patch, this directory includes a binary
image of a VFAT filesystem that contains files created with both an
unpatched kernel and a patched kernel. The image is called
'testvfat.bin'. This image allows you to test compatibility with
devices that use FAT filesystems without having to recompile your
kernel or load new modules.

To test a device, first put the image onto a partition on the device
using dd:

  dd if=testvfat.bin of=/dev/sdg1

note that this will wipe anything on the partition, so please be
careful to choose the right device. You may wish to look in
/proc/partitions to confirm the device name.

Once the files are on the device, you should use the devices user
interface to view the JPG images and/or listen to the MP3 files. There
should be a total of 10 JPG files and 6 MP3 files in each of the
PATCHED and ORIG directories. 

The FATTEST/ORIG directory contains files created with an unpatched kernel. if
these files do not show up correctly then your device is not
compatible with an unpatched Linux kernel.

The FATTEST/PATCHED directory contains files created with the
VFAT_FS_NO_DUALNAMES patch enabled. If the files in FATTEST/ORIG show
up on your device but the files in FATTEST/PATCHED do not show up then
the patch is not compatible with your device. If your device normally
supports long filenames then please notify Andrew Tridgell
(tridge@samba.org) giving details of the device and it's behaviour.

The script which created this test image is testdev.sh in this directory.

The MP3 files contain text spoken with a speech synthesiser, giving
the name of the directory and information on where the file is in the
directory tree. The JPG files contain similar information encoded as
an image. This allows you to test devices which do not display
filenames on their user interface.


Git trees
---------

A git tree containing this patch is available here:

  git://git.kernel.org/pub/scm/linux/kernel/git/tridge/fatfs-dualnames.git

The master branch of that tree contains the VFAT_FS_NO_DUALNAMES
patch.

The no_create_longname branch contains the
FAT-Add-CONFIG_VFAT_NO_CREATE_WITH_LONGNAMES patch.

Both branches contain the FAT-Added-FAT_NO_83NAME patch
