1 files changed, 126 insertions, 0 deletions
diff --git a/filesystems/ntfs/files/README.FreeBSD b/filesystems/ntfs/files/README.FreeBSD
new file mode 100644
index 000000000000..ffaedb7707c3
--- /dev/null
+++ b/filesystems/ntfs/files/README.FreeBSD
@@ -0,0 +1,126 @@
+==============================================================================
+NTFS-3G README for the FreeBSD port
+==============================================================================
+
+1. Introduction
+2. Port specific notes
+3. Mounting at startup with /etc/fstab
+4. Ublio configuration
+5. Known issues
+
+==============================================================================
+1. Introduction
+==============================================================================
+
+The NTFS-3G project provides a read/write filesystem driver for NTFS. It uses
+the FUSE library (an OS-independent library to create filesystem drivers) and
+FreeBSD fusefs(5) kernel module (port of the kernel-dependent part of FUSE).
+For more information see:
+
+NTFS-3G site:	https://github.com/tuxera/ntfs-3g
+FUSE site:	https://github.com/libfuse/libfuse
+
+==============================================================================
+2. Port specific notes
+==============================================================================
+
+The port has a patch to align read/write operations to the media block size
+(required on FreeBSD).
+
+The port has 2 options: LOCK (to prevent access to the device by external
+programs than NTFS-3G once mounted, default on Linux), and UBLIO (use a user
+space cache library, see devel/libublio, not required on Linux).
+
+The reason for using UBLIO is that FreeBSD removed support for block devices,
+being them now character devices. The former ones had a cache, and NTFS-3G was
+optimized for it (Linux still uses them). The same happens on Mac OS X (based
+on FreeBSD 5). So using UBLIO both improves performance (~10 times faster),
+and reduces disk load.
+
+==============================================================================
+3. Mounting at startup with /etc/fstab
+==============================================================================
+
+To mount at startup you need to have the following line in /boot/loader.conf:
+
+  fusefs_load="YES"
+
+or have "fusefs" added to the "kld_list" in the /etc/rc.conf.
+
+Then create the following symlink:
+
+$ ln -s `which ntfs-3g` /usr/sbin/mount_ntfs-3g
+
+And add the appropriate line to /etc/fstab: the filesystem should be "ntfs-3g"
+instead of "ntfs", and the additional "late" parameter is required. Example:
+
+/dev/ad4s1		/wxp		ntfs-3g	rw,late		0	0
+
+==============================================================================
+4. Ublio configuration
+==============================================================================
+
+The UBLIO layer is configured through environment variables, which are read
+when mounting the filesystem. The following are available:
+
+NTFS_USE_UBLIO	- Enable the UBLIO cache.
+UBLIO_BLOCKSIZE	- Actual reads/writes will be multiples of this quantity.
+UBLIO_ITEMS	- Number of cache entries, each of UBLIO_BLOCKSIZE length.
+UBLIO_GRACE	- Number of times a cache entry will refuse being recycled.
+UBLIO_SYNC_IO	- If enabled, all writes will be immediately executed.
+
+To give an idea about tuning, here are the default values with some notes
+(they are only based on some simple benchmarks, and may be wrong):
+
+NTFS_USE_UBLIO	- 1. Disabling it drastically decreases performance.
+UBLIO_BLOCKSIZE	- 262144 (256KB). Larger improves reading/writing speed of
+		  large files, and smaller makes filesystem operations
+		  (creation, deletion, moving, find(1)) perform faster.
+		  Try 2/4MB and 512/256KB for the different approaches. Note
+		  that after that points performance decreases again.
+UBLIO_ITEMS	- 64. Higher increases speed of filesystem operations. Try 128.
+UBLIO_GRACE	- 32. Makes the cache items have more chances to be reused.
+UBLIO_SYNC_IO	- 0. If enabled, highly decreases writing speed, but the data
+		  is immediately written to the disk.
+
+For example (improves performance over large files, but read below):
+
+# env UBLIO_BLOCKSIZE=2097152 ntfs-3g /dev/ad0s1 /mnt
+
+Alternatively these variables could be set in the shell startup file. For
+example if you are using it in /etc/fstab add them to /etc/profile. If you use
+it as a user, instead, editing the shell startup in HOME is enough.
+
+Note that higher values for UBLIO_BLOCKSIZE and UBLIO_ITEMS increase the
+memory usage by their product in bytes. For example, if you set it to 1MB it
+would consume 64MB. To decrease it to 16MB you could set UBLIO_BLOCKSIZE to
+256KB (currently this is the default). Small values like 4096 can be used and
+also perform fine.
+
+It is also possible to enforce block aligned I/O on regular files by setting
+the FORCE_ALIGNED_IO variable (it will be set to 512 bytes), but this is only
+useful for testing purposes and in practice has no use.
+
+==============================================================================
+5. Known issues
+==============================================================================
+
+- For mkntfs(8) -F must be used to allow non-block device to be processed.
+
+- Current implementation does not properly work with partitions of size which
+is not a multiply of UBLIO_BLOCKSIZE (cannot read/write last cluster). For
+instance, you may not be able to create ntfs filesystem because of this with
+
+   Initializing device with zeroes:  99%Failed to complete writing to
+   /dev/ada0s1 after three retries.
+
+- When reading/writing the same file repeatedly while doing many simultaneous
+operations on different files sometimes the former one fails: read(2) returns
+-1 and sets errno to EAGAIN. This is because of a difference between the FUSE
+kernel implementation in Linux and FreeBSD, and is being worked on. An example
+scenario would be playing a song in XMMS, while building many ports, which
+could cause XMMS skip the song. Another observed problem is the current
+directory not being found, but entering again would work (Linux access is
+path-based while FreeBSD is vnode-based, which may be reused).
+
+==============================================================================