Contents of /alx-src/trunk/kernel26-alx/linux/Documentation/DocBook/journal-api.tmpl
Parent Directory | Revision Log
Revision 628 -
(show annotations)
(download)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 11090 byte(s)
Wed Mar 4 10:48:58 2009 UTC (15 years, 2 months ago) by niro
File size: 11090 byte(s)
import linux sources based on 2.6.12-alx-r9: -using linux-2.6.12.6 -using 2.6.12-ck6 patch set -using fbsplash-0.9.2-r3 -using vesafb-tng-0.9-rc7 -using squashfs-2.2 -added cddvd-cmdfilter-drop.patch as ck dropped it -added via-epia-dri (cle266) patch -added zd1211-svn-32 wlan driver (http://zd1211.ath.cx/download/) -added debian patches to zd1211 for wep256 etc
1 | <?xml version="1.0" encoding="UTF-8"?> |
2 | <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" |
3 | "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" []> |
4 | |
5 | <book id="LinuxJBDAPI"> |
6 | <bookinfo> |
7 | <title>The Linux Journalling API</title> |
8 | <authorgroup> |
9 | <author> |
10 | <firstname>Roger</firstname> |
11 | <surname>Gammans</surname> |
12 | <affiliation> |
13 | <address> |
14 | <email>rgammans@computer-surgery.co.uk</email> |
15 | </address> |
16 | </affiliation> |
17 | </author> |
18 | </authorgroup> |
19 | |
20 | <authorgroup> |
21 | <author> |
22 | <firstname>Stephen</firstname> |
23 | <surname>Tweedie</surname> |
24 | <affiliation> |
25 | <address> |
26 | <email>sct@redhat.com</email> |
27 | </address> |
28 | </affiliation> |
29 | </author> |
30 | </authorgroup> |
31 | |
32 | <copyright> |
33 | <year>2002</year> |
34 | <holder>Roger Gammans</holder> |
35 | </copyright> |
36 | |
37 | <legalnotice> |
38 | <para> |
39 | This documentation is free software; you can redistribute |
40 | it and/or modify it under the terms of the GNU General Public |
41 | License as published by the Free Software Foundation; either |
42 | version 2 of the License, or (at your option) any later |
43 | version. |
44 | </para> |
45 | |
46 | <para> |
47 | This program is distributed in the hope that it will be |
48 | useful, but WITHOUT ANY WARRANTY; without even the implied |
49 | warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
50 | See the GNU General Public License for more details. |
51 | </para> |
52 | |
53 | <para> |
54 | You should have received a copy of the GNU General Public |
55 | License along with this program; if not, write to the Free |
56 | Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, |
57 | MA 02111-1307 USA |
58 | </para> |
59 | |
60 | <para> |
61 | For more details see the file COPYING in the source |
62 | distribution of Linux. |
63 | </para> |
64 | </legalnotice> |
65 | </bookinfo> |
66 | |
67 | <toc></toc> |
68 | |
69 | <chapter id="Overview"> |
70 | <title>Overview</title> |
71 | <sect1> |
72 | <title>Details</title> |
73 | <para> |
74 | The journalling layer is easy to use. You need to |
75 | first of all create a journal_t data structure. There are |
76 | two calls to do this dependent on how you decide to allocate the physical |
77 | media on which the journal resides. The journal_init_inode() call |
78 | is for journals stored in filesystem inodes, or the journal_init_dev() |
79 | call can be use for journal stored on a raw device (in a continuous range |
80 | of blocks). A journal_t is a typedef for a struct pointer, so when |
81 | you are finally finished make sure you call journal_destroy() on it |
82 | to free up any used kernel memory. |
83 | </para> |
84 | |
85 | <para> |
86 | Once you have got your journal_t object you need to 'mount' or load the journal |
87 | file, unless of course you haven't initialised it yet - in which case you |
88 | need to call journal_create(). |
89 | </para> |
90 | |
91 | <para> |
92 | Most of the time however your journal file will already have been created, but |
93 | before you load it you must call journal_wipe() to empty the journal file. |
94 | Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the |
95 | job of the client file system to detect this and skip the call to journal_wipe(). |
96 | </para> |
97 | |
98 | <para> |
99 | In either case the next call should be to journal_load() which prepares the |
100 | journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery() |
101 | for you if it detects any outstanding transactions in the journal and similarly |
102 | journal_load() will call journal_recover() if necessary. |
103 | I would advise reading fs/ext3/super.c for examples on this stage. |
104 | [RGG: Why is the journal_wipe() call necessary - doesn't this needlessly |
105 | complicate the API. Or isn't a good idea for the journal layer to hide |
106 | dirty mounts from the client fs] |
107 | </para> |
108 | |
109 | <para> |
110 | Now you can go ahead and start modifying the underlying |
111 | filesystem. Almost. |
112 | </para> |
113 | |
114 | |
115 | <para> |
116 | |
117 | You still need to actually journal your filesystem changes, this |
118 | is done by wrapping them into transactions. Additionally you |
119 | also need to wrap the modification of each of the the buffers |
120 | with calls to the journal layer, so it knows what the modifications |
121 | you are actually making are. To do this use journal_start() which |
122 | returns a transaction handle. |
123 | </para> |
124 | |
125 | <para> |
126 | journal_start() |
127 | and its counterpart journal_stop(), which indicates the end of a transaction |
128 | are nestable calls, so you can reenter a transaction if necessary, |
129 | but remember you must call journal_stop() the same number of times as |
130 | journal_start() before the transaction is completed (or more accurately |
131 | leaves the the update phase). Ext3/VFS makes use of this feature to simplify |
132 | quota support. |
133 | </para> |
134 | |
135 | <para> |
136 | Inside each transaction you need to wrap the modifications to the |
137 | individual buffers (blocks). Before you start to modify a buffer you |
138 | need to call journal_get_{create,write,undo}_access() as appropriate, |
139 | this allows the journalling layer to copy the unmodified data if it |
140 | needs to. After all the buffer may be part of a previously uncommitted |
141 | transaction. |
142 | At this point you are at last ready to modify a buffer, and once |
143 | you are have done so you need to call journal_dirty_{meta,}data(). |
144 | Or if you've asked for access to a buffer you now know is now longer |
145 | required to be pushed back on the device you can call journal_forget() |
146 | in much the same way as you might have used bforget() in the past. |
147 | </para> |
148 | |
149 | <para> |
150 | A journal_flush() may be called at any time to commit and checkpoint |
151 | all your transactions. |
152 | </para> |
153 | |
154 | <para> |
155 | Then at umount time , in your put_super() (2.4) or write_super() (2.5) |
156 | you can then call journal_destroy() to clean up your in-core journal object. |
157 | </para> |
158 | |
159 | |
160 | <para> |
161 | Unfortunately there a couple of ways the journal layer can cause a deadlock. |
162 | The first thing to note is that each task can only have |
163 | a single outstanding transaction at any one time, remember nothing |
164 | commits until the outermost journal_stop(). This means |
165 | you must complete the transaction at the end of each file/inode/address |
166 | etc. operation you perform, so that the journalling system isn't re-entered |
167 | on another journal. Since transactions can't be nested/batched |
168 | across differing journals, and another filesystem other than |
169 | yours (say ext3) may be modified in a later syscall. |
170 | </para> |
171 | |
172 | <para> |
173 | The second case to bear in mind is that journal_start() can |
174 | block if there isn't enough space in the journal for your transaction |
175 | (based on the passed nblocks param) - when it blocks it merely(!) needs to |
176 | wait for transactions to complete and be committed from other tasks, |
177 | so essentially we are waiting for journal_stop(). So to avoid |
178 | deadlocks you must treat journal_start/stop() as if they |
179 | were semaphores and include them in your semaphore ordering rules to prevent |
180 | deadlocks. Note that journal_extend() has similar blocking behaviour to |
181 | journal_start() so you can deadlock here just as easily as on journal_start(). |
182 | </para> |
183 | |
184 | <para> |
185 | Try to reserve the right number of blocks the first time. ;-). This will |
186 | be the maximum number of blocks you are going to touch in this transaction. |
187 | I advise having a look at at least ext3_jbd.h to see the basis on which |
188 | ext3 uses to make these decisions. |
189 | </para> |
190 | |
191 | <para> |
192 | Another wriggle to watch out for is your on-disk block allocation strategy. |
193 | why? Because, if you undo a delete, you need to ensure you haven't reused any |
194 | of the freed blocks in a later transaction. One simple way of doing this |
195 | is make sure any blocks you allocate only have checkpointed transactions |
196 | listed against them. Ext3 does this in ext3_test_allocatable(). |
197 | </para> |
198 | |
199 | <para> |
200 | Lock is also providing through journal_{un,}lock_updates(), |
201 | ext3 uses this when it wants a window with a clean and stable fs for a moment. |
202 | eg. |
203 | </para> |
204 | |
205 | <programlisting> |
206 | |
207 | journal_lock_updates() //stop new stuff happening.. |
208 | journal_flush() // checkpoint everything. |
209 | ..do stuff on stable fs |
210 | journal_unlock_updates() // carry on with filesystem use. |
211 | </programlisting> |
212 | |
213 | <para> |
214 | The opportunities for abuse and DOS attacks with this should be obvious, |
215 | if you allow unprivileged userspace to trigger codepaths containing these |
216 | calls. |
217 | </para> |
218 | |
219 | <para> |
220 | A new feature of jbd since 2.5.25 is commit callbacks with the new |
221 | journal_callback_set() function you can now ask the journalling layer |
222 | to call you back when the transaction is finally committed to disk, so that |
223 | you can do some of your own management. The key to this is the journal_callback |
224 | struct, this maintains the internal callback information but you can |
225 | extend it like this:- |
226 | </para> |
227 | <programlisting> |
228 | struct myfs_callback_s { |
229 | //Data structure element required by jbd.. |
230 | struct journal_callback for_jbd; |
231 | // Stuff for myfs allocated together. |
232 | myfs_inode* i_commited; |
233 | |
234 | } |
235 | </programlisting> |
236 | |
237 | <para> |
238 | this would be useful if you needed to know when data was committed to a |
239 | particular inode. |
240 | </para> |
241 | |
242 | </sect1> |
243 | |
244 | <sect1> |
245 | <title>Summary</title> |
246 | <para> |
247 | Using the journal is a matter of wrapping the different context changes, |
248 | being each mount, each modification (transaction) and each changed buffer |
249 | to tell the journalling layer about them. |
250 | </para> |
251 | |
252 | <para> |
253 | Here is a some pseudo code to give you an idea of how it works, as |
254 | an example. |
255 | </para> |
256 | |
257 | <programlisting> |
258 | journal_t* my_jnrl = journal_create(); |
259 | journal_init_{dev,inode}(jnrl,...) |
260 | if (clean) journal_wipe(); |
261 | journal_load(); |
262 | |
263 | foreach(transaction) { /*transactions must be |
264 | completed before |
265 | a syscall returns to |
266 | userspace*/ |
267 | |
268 | handle_t * xct=journal_start(my_jnrl); |
269 | foreach(bh) { |
270 | journal_get_{create,write,undo}_access(xact,bh); |
271 | if ( myfs_modify(bh) ) { /* returns true |
272 | if makes changes */ |
273 | journal_dirty_{meta,}data(xact,bh); |
274 | } else { |
275 | journal_forget(bh); |
276 | } |
277 | } |
278 | journal_stop(xct); |
279 | } |
280 | journal_destroy(my_jrnl); |
281 | </programlisting> |
282 | </sect1> |
283 | |
284 | </chapter> |
285 | |
286 | <chapter id="adt"> |
287 | <title>Data Types</title> |
288 | <para> |
289 | The journalling layer uses typedefs to 'hide' the concrete definitions |
290 | of the structures used. As a client of the JBD layer you can |
291 | just rely on the using the pointer as a magic cookie of some sort. |
292 | |
293 | Obviously the hiding is not enforced as this is 'C'. |
294 | </para> |
295 | <sect1><title>Structures</title> |
296 | !Iinclude/linux/jbd.h |
297 | </sect1> |
298 | </chapter> |
299 | |
300 | <chapter id="calls"> |
301 | <title>Functions</title> |
302 | <para> |
303 | The functions here are split into two groups those that |
304 | affect a journal as a whole, and those which are used to |
305 | manage transactions |
306 | </para> |
307 | <sect1><title>Journal Level</title> |
308 | !Efs/jbd/journal.c |
309 | !Efs/jbd/recovery.c |
310 | </sect1> |
311 | <sect1><title>Transasction Level</title> |
312 | !Efs/jbd/transaction.c |
313 | </sect1> |
314 | </chapter> |
315 | <chapter> |
316 | <title>See also</title> |
317 | <para> |
318 | <citation> |
319 | <ulink url="ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz"> |
320 | Journaling the Linux ext2fs Filesystem,LinuxExpo 98, Stephen Tweedie |
321 | </ulink> |
322 | </citation> |
323 | </para> |
324 | <para> |
325 | <citation> |
326 | <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html"> |
327 | Ext3 Journalling FileSystem , OLS 2000, Dr. Stephen Tweedie |
328 | </ulink> |
329 | </citation> |
330 | </para> |
331 | </chapter> |
332 | |
333 | </book> |