From 46439007cf417cbd9ac8049bb4122c890097a0fa Mon Sep 17 00:00:00 2001 From: "Charles.Forsyth" Date: Fri, 22 Dec 2006 20:52:35 +0000 Subject: 20060303-partial --- man/3/logfs | 260 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 260 insertions(+) create mode 100644 man/3/logfs (limited to 'man/3/logfs') diff --git a/man/3/logfs b/man/3/logfs new file mode 100644 index 00000000..5e60b308 --- /dev/null +++ b/man/3/logfs @@ -0,0 +1,260 @@ +.TH LOGFS 3 +.SH NAME +logfs \- log-structured file system for flash devices +.SH SYNOPSIS +.B bind -b '#ʟ' /dev +.PP +.B /dev/logfsctl +.br +.B /dev/logfsusers +.br +.BI /dev/logfs name +.br +.BI /dev/logfs name boot +.PP +.B echo fsys +.I name +.B config +.I flash-device +.B "> /dev/logfsctl" +.br +.B echo fsys +.I name +.B format +.I boot-area-size +.B "> /dev/logfsctl" +.br +.B echo fsys +.I name +.B open +.B "> /dev/logfsctl" +.br +.BI "mount -Ac /dev/logfs" name +.I dir +.SH DESCRIPTION +.I Logfs +is a driver level implementation of the Inferno log structured +filesystem, a file system designed with modern flash devices +(such as NAND flash) in mind. +.I Logfs +is itself hardware independent, requiring other +devices to provide the physical medium. Currently only +.IR flash (3) +devices are supported. +.PP +The file system maintains two storage regions on the same medium: +a log-structured hierarchical file system that implements all the +functionality communicable by the Styx protocol +(see +.IR intro (5)), +and a boot +partition that offers a fixed amount of flat storage suitable for +holding such things as a kernel boot image, boot parameters etc. The +boot partition can be accessed and updated without understanding all +but the simplest facts about the hierarchical file system, making it +easy to implement boot loaders with small footprints. +.PP +The physical layout of the file system varies from medium to medium, +so that the specialised features of the medium can be accounted for. +.PP +The user table is maintained in memory; there is one table, shared between +all file systems supported by this driver. There is no distinction between +users and groups: a user is a group with one member. +The user table records a mapping +between uids +and +unames, +as well as recording the leader and members of each group. A +.I uid +is a string naming a user or group that is stored in the file system. A +.I uname +is the string naming a user or group that is used in +file system protocol messages (see +.IR intro (5)). +There is a distinction so that +unames +can be safely reused, even though +uids +cannot. +.PP +Configuration and control of the file systems is by writing commands to +.BR /dev/logfsctl : +.TP +.BI fsys " name" +.br +Sets the current file system to +.IR name , +which must be configured. Subsequent commands, not prefixed with +.BI fsys name\fR, +will by applied to the name file system. +.TP +.BI [fsys " name\f5] config\fI flash-device" +.br +Configures file system +.I name +to be written to +.BI flash (3) +device +.IR flash-device . +This does not initialise or format the filesystem, but simply bind +.I name +to +.IR flash-device . +For each configured +.IR name , +two files appear in the device name space, +.BI /dev/logfs name +and +.BI /dev/logfs name\f5boot\fI. +The former serves the Styx protocol giving access to the hierarchical file system; +the latter is a fixed size file that represents the boot partition. +.TP +.BI [fsys " name\f5] format \fIbootsize" +.br +Formats the underlying medium as a +.I logfs +format file system. Sufficent storage is set aside to create a boot partition of at +least +.I bootsize +bytes. Some medium implementations (eg, for NAND flash) store file system +parameters (eg, location, size and boot partition size) to enable automatic +location of file systems and improve bad block detection. These must +be part of the boot partition so that they are easily accessible to boot loaders, +so such medium implementations may also enforce a minimum size for the +boot partition. +.TP +.BI [fsys " name\f5] open [-P] [-W]" +.br +Initialises the specified file system, and makes it available for use. The file +system structure is verified, bad blocks are repaired and, in the case of the +log structured file system, and the log replayed to regenerate the directory structure. +The +.B -W +option reduces the permission control on +.IR wstat (5) +requests. Specifically it allows the +.BR uid , +.BR gid , +.BR mtime , +and +.B perm +to be changed by anyone. +The +.B -P +option removes all file access controls, allowing anyone to open any file in +any mode. +.TP +.BI [fsys " name\f5] sweep" +.br +Forces the log to be swept, if it has been written to since last being swept. +The log is normally swept automatically when space is low. +.TP +.BI [fsys " name\f5] sync" +.br +Flush any buffered log or data to the underlying device. +Use before shutting down the system if the device is not unmounted. +(See notes below.) +.TP +.BI [fsys " name\f5] trace [\fIlevel\f5]" +.br +If +.I +level +is non-zero, internal diagnostics for the log file system are enabled at the +given level. If +.I level +is zero, or missing, tracing is disabled. +.TP +.BI [fsys " name\f5] unconfig" +.br +removes the configuration. The file system must not be mounted, or the +boot partition open, before doing this. +.TP +.BI uname " uname uid" +.TP +.BI uname " uname \f5:\fPuid" +.br +adds the user with uname +.I uname +and uid +.I uid +to the in-memory table +.TP +.BI uname " uname \f5%\fPnewname" +.br +renames +.I uname +to +.IR newname , +throughout the user table +.TP +.BI uname " uname \f5=\fPleader" +.br +sets the group leader to the uname +.I leader +.TP +.BI uname " uname \f5=" +.br +removes the group leader; then all members are leaders +.TP +.BI uname " uname \f5+\fPmember" +.br +add the uname +.I +member +to the group +.TP +.BI uname " uname \f5-\fPmember" +.br +removes the uname +.I +member +from the group +.SS Notes +The file system log may be subject to a small amount of buffering for efficiency +purposes; therefore, it is necessary to unmount the file system before disconnecting +the power to avoid losing recent updates. Failure to do this does not result in +inconsistencies in the file system, but some recent changes will be lost. +Equivalently, a +.IR wstat (5) +of any file or directory, with all fields set to +.I no change +(also known as a +.I wstat +.IR flush) +will cause the log to be written to disk. Note that during a dismount, and also a +.I wstat +.IR flush , +a +.I wstat +flush +is also applied to the underlying +.IR flash (3) +device. Furthermore, since some buffering is used on the log, +needless use of +.I wstat flush +will consume log space more rapidly than normal, although it will be recovered during +the next sweep. +.PP +The log is automatically swept when space is low, so there is not normally any +need to use the +.B sweep +command. +.SH SOURCE +.B /liblogfs +.br +.B /libnandfs +.br +.B /emu/port/devlogfs.c +.br +.B /os/port/devlogfs.c +.SH SEE ALSO +.IR flash (3), +.IR ftl (3), +.IR kfs (4) +.SH BUGS +The only medium currently supported is NAND flash. This is detected by +recognising the manufacturer and device ids supplied by the status file of +the +.IR flash (3) +device. -- cgit v1.2.3