PRAMFS Overview
===============

The Persistent, Protected RAM special filesystem (PRAMFS) is designed
for systems that have a chunk of fast, non-volatile RAM to be used as
a RAM-based non-volatile read/write filesystem.

One approach for a persistent RAM-based filesystem is to implement a
non-volatile RAM disk block driver, and mount over it any disk-based
filesystem (ext2/ext3, reiserfs, etc.). For RAM that has considerably
slower access times than system memory, this approach makes sense,
because it caches data from the slow RAM in the page cache.

However, for systems that have a chunk of non-volatile RAM that is
comparable in speed to system memory, it would be desirable to use a
filesystem for this memory that bypasses the page cache during file I/O.
There's no point in caching this data when the backing store is as fast
or faster than the cache memory itself! This also frees up the page
cache for use by other parts of the system that really need it (disk-
based filesystem data, memory-mapped files, pages from swapped-out
processes, IPC pages, etc.).

PRAMFS is designed to meet this need. PRAMFS data never uses the page
cache for caching file data. PRAMFS file I/O reads and writes directly
to/from the fast RAM backing store. The only use of the page cache in
PRAMFS is for memory mapping files.

This is similar to the current direct I/O support in Linux. However in
PRAMFS direct I/O is always enabled implicitly, as if the O_DIRECT flag
were passed on every open of a PRAMFS file. But unlike direct I/O, file
I/O in the PRAMFS occurs synchronously. There is no need to block the
current process while the transfer to/from the PRAMFS is in progress,
since one of the requirements of the PRAMFS is that the filesystem exist
in fast RAM. Hence, "direct access buffers" that are needed by
asynchronous direct I/O, are not used in PRAMFS.

Another advantage of PRAMFS: existing filesystems such as ext2/ext3 were
designed for optimum performance on disk-based media, and so implement
features such as block groups, which attempts to group inode data into a
contiguous set of data blocks to minimize disk seeks when accessing
files. Since there is no such performance penalty for random access on
RAM-based media, such features as block groups are not implemented in
PRAMFS, which reduces filesystem complexity and in turn increases the
efficient use of space on the media (i.e. More space is dedicated to
actual file data storage and less to meta-data needed to maintain that
file data).

PRAMFS is also write protected. The page tables that map the
backing-store RAM are normally marked read-only. Write operations into
the filesystem temporarily mark the affected pages as writeable, the
write operation is carried out with locks held, and then the pte is
marked read-only again. In case there are systems where the write
protect feature is not possible (for instance the RAM cannot be mapped
with page tables), this feature can be disabled with the
CONFIG_PRAMFS_NOWP config option.

In summary, PRAMFS is a light-weight, full-featured, and space-efficient
special filesystem that is ideal for systems with a block of fast
non-volatile RAM that need to access data on it using a standard
filesytem interface. An example application of PRAMFS might be a PDA
that needs to store frequently modified non-volatile information, such
as system logs. Storing this kind of information in a flash filesystem
would quickly wear down the flash device.


Supported mount options
=======================

The PRAMFS currently requires one mount option, and there are several
optional mount options:

physaddr=	Required. It tells PRAMFS the physical address of the
		start of the RAM that makes up the filesystem. The
		physical address must be located on a page boundary.

init=		Optional. It is used to initialize the memory to an
		empty filesystem. Any data in an existing filesystem
		will be lost if this option is given. The parameter to
		"init=" is the RAM size in bytes.

bs=		Optional. It is used to specify a block size. It is
		ignored if the "init=" option is not specified, since
		otherwise the block size is read from the PRAMFS
		super-block. The default blocksize is 2048 bytes,
		and the allowed block sizes are 512, 1024, 2048, and
		4096.

bpi=		Optional. It is used to specify the bytes per inode
		ratio, i.e. For every N bytes in the filesystem, an
		inode will be created. This behaves the same as the "-i"
		option to mke2fs. It is ignored if the "init=" option is
		not specified.

N=		Optional. It is used to specify the number of inodes to
		allocate in the inode table. If the option is not
		specified, the bytes-per-inode ratio is used the
		calculate the number of inodes. If neither the "N=" or
		"bpi=" options are specified, the default behavior is to
		reserve 5% of the total space in the filesystem for the
		inode table. This option behaves the same as the "-N"
		option to mke2fs. It is ignored if the "init=" option is
		not specified.

Examples:

mount -t pramfs -o physaddr=0x20000000,init=0x2F000,bs=1024 none /mnt/pram

This example locates the filesystem at physical address 0x20000000, and
also requests an empty filesystem be initialized, of total size 0x2f000
bytes and blocksize 1024. The mount point is /mnt/pram.

mount -t pramfs -o physaddr=0x20000000 none /mnt/pram

This example locates the filesystem at physical address 0x20000000 as in
the first example, but uses the intact filesystem that already exists.


Current Limitations
===================

- The RAM used for PRAMFS must be directly addressable.

- PRAMFS does not support hard links.

- PRAMFS supports only private memory mappings. This allows most
  executables to run, but programs that attempt shared memory
  mappings, such as X apps that use X shared memory, will fail.

- The write protect feature of PRAMFS requires some architecture
  dependent support that currently only exists in ARMV, MIPS32,
  and i386 UP. For other architectures, PRAMFS can still be used
  but write protection should be disabled with the CONFIG_PRAMFS_NOWP
  option. If you wish to provide write protect support for other
  architectures, please read the PRAMFS technical specification
  pdf at the Sourceforge project site (see below).
  

Further Documentation
=====================

If you are interested in the internal design of PRAMFS, there is a pdf
and other documentation available at the Sourceforge PRAMFS home page at
http://pramfs.sourceforge.net.

Please send bug reports/comments/feed back to the pramfs development
list at sourceforge: pramfs-devel@lists.sourceforge.net.


ChangeLog
=========

Kernel 2.4.22:

	- Started ChangeLog.

