From: Marco Stornelli <marco.stornelli@xxxxxxxxx> Documentation. Signed-off-by: Marco Stornelli <marco.stornelli@xxxxxxxxx> --- diff -uprN linux-2.6.30-orig/Documentation/filesystems/pramfs.txt linux-2.6.30/Documentation/filesystems/pramfs.txt --- linux-2.6.30-orig/Documentation/filesystems/pramfs.txt 1970-01-01 01:00:00.000000000 +0100 +++ linux-2.6.30/Documentation/filesystems/pramfs.txt 2009-06-13 12:57:32.000000000 +0200 @@ -0,0 +1,227 @@ + +PRAMFS Overview +=============== + +Many embedded systems have a block of non-volatile RAM separate from +normal system memory, i.e. of which the kernel maintains no memory page +descriptors. For such systems it would be beneficial to mount a +fast read/write filesystem over this "I/O memory", for storing frequently +accessed data that must survive system reboots and power cycles. An +example usage might be system logs under /var/log, or a user address +book in a cell phone or PDA. + +Linux traditionally had no support for a persistent, non-volatile RAM-based +filesystem, persistent meaning the filesystem survives a system reboot +or power cycle intact. The RAM-based filesystems such as tmpfs and ramfs +have no actual backing store but exist entirely in the page and buffer +caches, hence the filesystem disappears after a system reboot or +power cycle. + +A relatively straight-forward solution is to write a simple block driver +for the non-volatile RAM, and mount over it any disk-based filesystem such +as ext2/ext3, reiserfs, etc. + +But the disk-based fs over non-volatile RAM block driver approach has +some drawbacks: + +1. Disk-based filesystems such as ext2/ext3 were designed for optimum + performance on spinning disk media, so they implement features such + as block groups, which attempts to group inode data into a contiguous + set of data blocks to minimize disk seeking when accessing files. For + RAM there is no such concern; a file's data blocks can be scattered + throughout the media with no access speed penalty at all. So block + groups in a filesystem mounted over RAM just adds unnecessary + complexity. A better approach is to use a filesystem specifically + tailored to RAM media which does away with these disk-based features. + This 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. + +2. If the backing-store RAM is comparable in access speed to system memory, + there's really no point in caching the file I/O data in the page + cache. Better to move file data directly between the user buffers + and the backing store RAM, i.e. use direct I/O. This prevents the + unnecessary populating of the page cache with dirty pages. However + direct I/O has to be enabled at every file open. To enable direct + I/O at all times for all regular files requires either that + applications be modified to include the O_DIRECT flag on all file + opens, or that a new filesystem be used that always performs direct + I/O by default. + +The Persistent/Protected RAM Special Filesystem (PRAMFS) is a +full-featured read/write filesystem that has been designed to address +these issues. PRAMFS is targeted to fast I/O memory, and if the memory +is non-volatile, the filesystem will be persistent. + +In PRAMFS, direct I/O is enabled across all files in the filesystem, in +other words the O_DIRECT flag is forced on every open of a PRAMFS file. +Also, file I/O in the PRAMFS is always synchronous. 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. So file I/O in PRAMFS is always direct, +synchronous, and never blocks. + +The data organization in PRAMFS can be thought of as an extremely +simplified version of ext2, such that the ratio of data to meta-data is +very high. + +PRAMFS is also write protected. The page table entries 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. This feature provides some protection against +filesystem corruption caused by errant writes into the RAM due to +kernel bugs for instance. In case there are systems where the write +protection 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. + + +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 in kilo/mega/giga 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=1M,bs=1k none /mnt/pram + +This example locates the filesystem at physical address 0x20000000, and +also requests an empty filesystem be initialized, of total size of one +megabytes and blocksize of one kilobytes. 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. + +Further Documentation +===================== + +If you are interested in the internal design of PRAMFS, there is +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@xxxxxxxxxxxxxxxxxxxxxx + + +ChangeLog +========= + +1.1.3: + - kernel 2.6.30 + - replaced DQUOT macros with vfs_dq_* functions in inode.c + +1.1.2: + - kernel 2.6.29 + - replaced current->fsuid and current->fsgid in inode.c with + current_fsuid() and current_fsgid() macro + - replaced pram_fsync with simple_file_sync (deleted fsync.c) + - removed ioctl.c + - fix the minus inside pram_sync_super and pram_sync_inode + inline functions + - now flags must be explicit in pram_lock/unlock_inode, + pram_lock/unlock_super and in pram_lock/unlock_block + - fix compiler warning about unused flags variable + - now multiple instances of pramfs are allowed + - added management of mode, uid and gid mount options + - renamed find_pramfs_super() in pram_get_super() and changed its + behaviour to remove the dependecy from a kernel symbol not exported + - added superblock operation pram_show_options + - added pram_parse_options function + - added checks for some mount parameters to avoid kernel crashes + - now a physical address of zero is allowed + - added the use of request_mem_region_exclusive + - now phys_addr in the struct pram_sb_info is phys_addr_t type + +1.1.1: + - kernel 2.6.28.1 + - now the code is compliant to kernel coding style + - replaced typedef pram_off_t with the standard off_t + +1.1.0 + - kernel 2.6.27 + - added xip feature. + +1.0.4: + - kernel 2.6.10 + - include <asm/tlbflush.h> in wprotect.c for + flush_tlb_kernel_range(). + - fixed a bug in pram_mknod(). The pramfs inode needs + updating after calling init_special_inode() to update + the rdev. +1.0.3: + - kernel 2.6.9. + - __ioremap() definition not consistent across archs, use + ioremap() instead. + - flush_tlb_kernel_page() is only available on some archs. + - fixed bug in pram_fill_super(): root inode pointer needs + to be recalculated after remapping whole fs. +1.0.2: + - kernel 2.6.4. + - use pram_truncate() in pram_delete_inode(). + - dangling pram_lock_inode() removed in pram_truncate_blocks(). + - edits to this README + +1.0.1: + - port to kernel 2.6.3. + - implement direct_IO() method instead of custom file read/write + methods. + - do away with __ioremap_readonly() requirement. + - implement inode truncate() method. + +1.0.0: + - Started ChangeLog (kernel 2.4.22). + + -- To unsubscribe from this list: send the line "unsubscribe linux-embedded" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
