Documentation/filesystems/exofs.txt

   1 ===============================================================================
   2 WHAT IS EXOFS?
   3 ===============================================================================
   4
   5 exofs is a file system that uses an OSD and exports the API of a normal Linux
   6 file system. Users access exofs like any other local file system, and exofs
   7 will in turn issue commands to the local OSD initiator.
   8
   9 OSD is a new T10 command set that views storage devices not as a large/flat
  10 array of sectors but as a container of objects, each having a length, quota,
  11 time attributes and more. Each object is addressed by a 64bit ID, and is
  12 contained in a 64bit ID partition. Each object has associated attributes
  13 attached to it, which are integral part of the object and provide metadata about
  14 the object. The standard defines some common obligatory attributes, but user
  15 attributes can be added as needed.
  16
  17 ===============================================================================
  18 ENVIRONMENT
  19 ===============================================================================
  20
  21 To use this file system, you need to have an object store to run it on.  You
  22 may download a target from:
  23 http://open-osd.org
  24
  25 See Documentation/scsi/osd.txt for how to setup a working osd environment.
  26
  27 ===============================================================================
  28 USAGE
  29 ===============================================================================
  30
  31 1. Download and compile exofs and open-osd initiator:
  32   You need an external Kernel source tree or kernel headers from your
  33   distribution. (anything based on 2.6.26 or later).
  34
  35   a. download open-osd including exofs source using:
  36      [parent-directory]$ git clone git://git.open-osd.org/open-osd.git
  37
  38   b. Build the library module like this:
  39      [parent-directory]$ make -C KSRC=$(KER_DIR) open-osd
  40
  41      This will build both the open-osd initiator as well as the exofs kernel
  42      module. Use whatever parameters you compiled your Kernel with and
  43      $(KER_DIR) above pointing to the Kernel you compile against. See the file
  44      open-osd/top-level-Makefile for an example.
  45
  46 2. Get the OSD initiator and target set up properly, and login to the target.
  47   See Documentation/scsi/osd.txt for farther instructions. Also see ./do-osd
  48   for example script that does all these steps.
  49
  50 3. Insmod the exofs.ko module:
  51    [exofs]$ insmod exofs.ko
  52
  53 4. Make sure the directory where you want to mount exists. If not, create it.
  54    (For example, mkdir /mnt/exofs)
  55
  56 5. At first run you will need to invoke the mkfs.exofs application
  57
  58    As an example, this will create the file system on:
  59    /dev/osd0 partition ID 65536
  60
  61    mkfs.exofs --pid=65536 --format /dev/osd0
  62
  63    The --format is optional. If not specified, no OSD_FORMAT will be
  64    performed and a clean file system will be created in the specified pid,
  65    in the available space of the target. (Use --format=size_in_meg to limit
  66    the total LUN space available)
  67
  68    If pid already exists, it will be deleted and a new one will be created in
  69    its place. Be careful.
  70
  71    An exofs lives inside a single OSD partition. You can create multiple exofs
  72    filesystems on the same device using multiple pids.
  73
  74    (run mkfs.exofs without any parameters for usage help message)
  75
  76 6. Mount the file system.
  77
  78    For example, to mount /dev/osd0, partition ID 0x10000 on /mnt/exofs:
  79
  80         mount -t exofs -o pid=65536 /dev/osd0 /mnt/exofs/
  81
  82 7. For reference (See do-exofs example script):
  83         do-exofs start - an example of how to perform the above steps.
  84         do-exofs stop - an example of how to unmount the file system.
  85         do-exofs format - an example of how to format and mkfs a new exofs.
  86
  87 8. Extra compilation flags (uncomment in fs/exofs/Kbuild):
  88         CONFIG_EXOFS_DEBUG - for debug messages and extra checks.
  89
  90 ===============================================================================
  91 exofs mount options
  92 ===============================================================================
  93 Similar to any mount command:
  94         mount -t exofs -o exofs_options /dev/osdX mount_exofs_directory
  95
  96 Where:
  97     -t exofs: specifies the exofs file system
  98
  99     /dev/osdX: X is a decimal number. /dev/osdX was created after a successful
 100                login into an OSD target.
 101
 102     mount_exofs_directory: The directory to mount the file system on
 103
 104     exofs specific options: Options are separated by commas (,)
 105                 pid=<integer> - The partition number to mount/create as
 106                                 container of the filesystem.
 107                                 This option is mandatory.
 108                 to=<integer>  - Timeout in ticks for a single command.
 109                                 default is (60 * HZ) [for debugging only]
 110
 111 ===============================================================================
 112 DESIGN
 113 ===============================================================================
 114
 115 * The file system control block (AKA on-disk superblock) resides in an object
 116   with a special ID (defined in common.h).
 117   Information included in the file system control block is used to fill the
 118   in-memory superblock structure at mount time. This object is created before
 119   the file system is used by mkexofs.c. It contains information such as:
 120         - The file system's magic number
 121         - The next inode number to be allocated
 122
 123 * Each file resides in its own object and contains the data (and it will be
 124   possible to extend the file over multiple objects, though this has not been
 125   implemented yet).
 126
 127 * A directory is treated as a file, and essentially contains a list of <file
 128   name, inode #> pairs for files that are found in that directory. The object
 129   IDs correspond to the files' inode numbers and will be allocated according to
 130   a bitmap (stored in a separate object). Now they are allocated using a
 131   counter.
 132
 133 * Each file's control block (AKA on-disk inode) is stored in its object's
 134   attributes. This applies to both regular files and other types (directories,
 135   device files, symlinks, etc.).
 136
 137 * Credentials are generated per object (inode and superblock) when they are
 138   created in memory (read from disk or created). The credential works for all
 139   operations and is used as long as the object remains in memory.
 140
 141 * Async OSD operations are used whenever possible, but the target may execute
 142   them out of order. The operations that concern us are create, delete,
 143   readpage, writepage, update_inode, and truncate. The following pairs of
 144   operations should execute in the order written, and we need to prevent them
 145   from executing in reverse order:
 146         - The following are handled with the OBJ_CREATED and OBJ_2BCREATED
 147           flags. OBJ_CREATED is set when we know the object exists on the OSD -
 148           in create's callback function, and when we successfully do a
 149           read_inode.
 150           OBJ_2BCREATED is set in the beginning of the create function, so we
 151           know that we should wait.
 152                 - create/delete: delete should wait until the object is created
 153                   on the OSD.
 154                 - create/readpage: readpage should be able to return a page
 155                   full of zeroes in this case. If there was a write already
 156                   en-route (i.e. create, writepage, readpage) then the page
 157                   would be locked, and so it would really be the same as
 158                   create/writepage.
 159                 - create/writepage: if writepage is called for a sync write, it
 160                   should wait until the object is created on the OSD.
 161                   Otherwise, it should just return.
 162                 - create/truncate: truncate should wait until the object is
 163                   created on the OSD.
 164                 - create/update_inode: update_inode should wait until the
 165                   object is created on the OSD.
 166         - Handled by VFS locks:
 167                 - readpage/delete: shouldn't happen because of page lock.
 168                 - writepage/delete: shouldn't happen because of page lock.
 169                 - readpage/writepage: shouldn't happen because of page lock.
 170
 171 ===============================================================================
 172 LICENSE/COPYRIGHT
 173 ===============================================================================
 174 The exofs file system is based on ext2 v0.5b (distributed with the Linux kernel
 175 version 2.6.10).  All files include the original copyrights, and the license
 176 is GPL version 2 (only version 2, as is true for the Linux kernel).  The
 177 Linux kernel can be downloaded from www.kernel.org.