← Back to branch summary

~ubuntu-branches/ubuntu/precise/linux-lowlatency/precise

« back to all changes in this revision

Viewing changes to Documentation/filesystems/exofs.txt

  • Committer: Package Import Robot
  • Author(s): Alessio Igor Bogani
  • Date: 2011-10-26 11:13:05 UTC
  • Revision ID: package-import@ubuntu.com-20111026111305-tz023xykf0i6eosh
Tags: upstream-3.2.0
Import upstream version 3.2.0

Show diffs side-by-side

added added

removed removed

Lines of Context:
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. integer can be
 
108
                                Hex by pre-pending an 0x to the number.
 
109
                osdname=<id>  - Mount by a device's osdname.
 
110
                                osdname is usually a 36 character uuid of the
 
111
                                form "d2683732-c906-4ee1-9dbd-c10c27bb40df".
 
112
                                It is one of the device's uuid specified in the
 
113
                                mkfs.exofs format command.
 
114
                                If this option is specified then the /dev/osdX
 
115
                                above can be empty and is ignored.
 
116
                to=<integer>  - Timeout in ticks for a single command.
 
117
                                default is (60 * HZ) [for debugging only]
 
118
 
 
119
===============================================================================
 
120
DESIGN
 
121
===============================================================================
 
122
 
 
123
* The file system control block (AKA on-disk superblock) resides in an object
 
124
  with a special ID (defined in common.h).
 
125
  Information included in the file system control block is used to fill the
 
126
  in-memory superblock structure at mount time. This object is created before
 
127
  the file system is used by mkexofs.c. It contains information such as:
 
128
        - The file system's magic number
 
129
        - The next inode number to be allocated
 
130
 
 
131
* Each file resides in its own object and contains the data (and it will be
 
132
  possible to extend the file over multiple objects, though this has not been
 
133
  implemented yet).
 
134
 
 
135
* A directory is treated as a file, and essentially contains a list of <file
 
136
  name, inode #> pairs for files that are found in that directory. The object
 
137
  IDs correspond to the files' inode numbers and will be allocated according to
 
138
  a bitmap (stored in a separate object). Now they are allocated using a
 
139
  counter.
 
140
 
 
141
* Each file's control block (AKA on-disk inode) is stored in its object's
 
142
  attributes. This applies to both regular files and other types (directories,
 
143
  device files, symlinks, etc.).
 
144
 
 
145
* Credentials are generated per object (inode and superblock) when they are
 
146
  created in memory (read from disk or created). The credential works for all
 
147
  operations and is used as long as the object remains in memory.
 
148
 
 
149
* Async OSD operations are used whenever possible, but the target may execute
 
150
  them out of order. The operations that concern us are create, delete,
 
151
  readpage, writepage, update_inode, and truncate. The following pairs of
 
152
  operations should execute in the order written, and we need to prevent them
 
153
  from executing in reverse order:
 
154
        - The following are handled with the OBJ_CREATED and OBJ_2BCREATED
 
155
          flags. OBJ_CREATED is set when we know the object exists on the OSD -
 
156
          in create's callback function, and when we successfully do a
 
157
          read_inode.
 
158
          OBJ_2BCREATED is set in the beginning of the create function, so we
 
159
          know that we should wait.
 
160
                - create/delete: delete should wait until the object is created
 
161
                  on the OSD.
 
162
                - create/readpage: readpage should be able to return a page
 
163
                  full of zeroes in this case. If there was a write already
 
164
                  en-route (i.e. create, writepage, readpage) then the page
 
165
                  would be locked, and so it would really be the same as
 
166
                  create/writepage.
 
167
                - create/writepage: if writepage is called for a sync write, it
 
168
                  should wait until the object is created on the OSD.
 
169
                  Otherwise, it should just return.
 
170
                - create/truncate: truncate should wait until the object is
 
171
                  created on the OSD.
 
172
                - create/update_inode: update_inode should wait until the
 
173
                  object is created on the OSD.
 
174
        - Handled by VFS locks:
 
175
                - readpage/delete: shouldn't happen because of page lock.
 
176
                - writepage/delete: shouldn't happen because of page lock.
 
177
                - readpage/writepage: shouldn't happen because of page lock.
 
178
 
 
179
===============================================================================
 
180
LICENSE/COPYRIGHT
 
181
===============================================================================
 
182
The exofs file system is based on ext2 v0.5b (distributed with the Linux kernel
 
183
version 2.6.10).  All files include the original copyrights, and the license
 
184
is GPL version 2 (only version 2, as is true for the Linux kernel).  The
 
185
Linux kernel can be downloaded from www.kernel.org.