diff options
Diffstat (limited to 'Documentation/DocBook')
| -rw-r--r-- | Documentation/DocBook/Makefile | 2 | ||||
| -rw-r--r-- | Documentation/DocBook/filesystems.tmpl | 300 | ||||
| -rw-r--r-- | Documentation/DocBook/journal-api.tmpl | 333 |
3 files changed, 301 insertions, 334 deletions
diff --git a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile index 3bf5086574bc..db9499adbed4 100644 --- a/Documentation/DocBook/Makefile +++ b/Documentation/DocBook/Makefile | |||
| @@ -9,7 +9,7 @@ | |||
| 9 | DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ | 9 | DOCBOOKS := wanbook.xml z8530book.xml mcabook.xml videobook.xml \ |
| 10 | kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ | 10 | kernel-hacking.xml kernel-locking.xml deviceiobook.xml \ |
| 11 | procfs-guide.xml writing_usb_driver.xml \ | 11 | procfs-guide.xml writing_usb_driver.xml \ |
| 12 | kernel-api.xml filesystems.xml journal-api.xml lsm.xml usb.xml \ | 12 | kernel-api.xml filesystems.xml lsm.xml usb.xml \ |
| 13 | gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ | 13 | gadget.xml libata.xml mtdnand.xml librs.xml rapidio.xml \ |
| 14 | genericirq.xml | 14 | genericirq.xml |
| 15 | 15 | ||
diff --git a/Documentation/DocBook/filesystems.tmpl b/Documentation/DocBook/filesystems.tmpl index 4785032fb6ea..39fa2aba7f9b 100644 --- a/Documentation/DocBook/filesystems.tmpl +++ b/Documentation/DocBook/filesystems.tmpl | |||
| @@ -98,4 +98,304 @@ | |||
| 98 | </sect1> | 98 | </sect1> |
| 99 | </chapter> | 99 | </chapter> |
| 100 | 100 | ||
| 101 | <chapter id="LinuxJDBAPI"> | ||
| 102 | <chapterinfo> | ||
| 103 | <title>The Linux Journalling API</title> | ||
| 104 | |||
| 105 | <authorgroup> | ||
| 106 | <author> | ||
| 107 | <firstname>Roger</firstname> | ||
| 108 | <surname>Gammans</surname> | ||
| 109 | <affiliation> | ||
| 110 | <address> | ||
| 111 | <email>rgammans@computer-surgery.co.uk</email> | ||
| 112 | </address> | ||
| 113 | </affiliation> | ||
| 114 | </author> | ||
| 115 | </authorgroup> | ||
| 116 | |||
| 117 | <authorgroup> | ||
| 118 | <author> | ||
| 119 | <firstname>Stephen</firstname> | ||
| 120 | <surname>Tweedie</surname> | ||
| 121 | <affiliation> | ||
| 122 | <address> | ||
| 123 | <email>sct@redhat.com</email> | ||
| 124 | </address> | ||
| 125 | </affiliation> | ||
| 126 | </author> | ||
| 127 | </authorgroup> | ||
| 128 | |||
| 129 | <copyright> | ||
| 130 | <year>2002</year> | ||
| 131 | <holder>Roger Gammans</holder> | ||
| 132 | </copyright> | ||
| 133 | </chapterinfo> | ||
| 134 | |||
| 135 | <title>The Linux Journalling API</title> | ||
| 136 | |||
| 137 | <sect1> | ||
| 138 | <title>Overview</title> | ||
| 139 | <sect2> | ||
| 140 | <title>Details</title> | ||
| 141 | <para> | ||
| 142 | The journalling layer is easy to use. You need to | ||
| 143 | first of all create a journal_t data structure. There are | ||
| 144 | two calls to do this dependent on how you decide to allocate the physical | ||
| 145 | media on which the journal resides. The journal_init_inode() call | ||
| 146 | is for journals stored in filesystem inodes, or the journal_init_dev() | ||
| 147 | call can be use for journal stored on a raw device (in a continuous range | ||
| 148 | of blocks). A journal_t is a typedef for a struct pointer, so when | ||
| 149 | you are finally finished make sure you call journal_destroy() on it | ||
| 150 | to free up any used kernel memory. | ||
| 151 | </para> | ||
| 152 | |||
| 153 | <para> | ||
| 154 | Once you have got your journal_t object you need to 'mount' or load the journal | ||
| 155 | file, unless of course you haven't initialised it yet - in which case you | ||
| 156 | need to call journal_create(). | ||
| 157 | </para> | ||
| 158 | |||
| 159 | <para> | ||
| 160 | Most of the time however your journal file will already have been created, but | ||
| 161 | before you load it you must call journal_wipe() to empty the journal file. | ||
| 162 | Hang on, you say , what if the filesystem wasn't cleanly umount()'d . Well, it is the | ||
| 163 | job of the client file system to detect this and skip the call to journal_wipe(). | ||
| 164 | </para> | ||
| 165 | |||
| 166 | <para> | ||
| 167 | In either case the next call should be to journal_load() which prepares the | ||
| 168 | journal file for use. Note that journal_wipe(..,0) calls journal_skip_recovery() | ||
| 169 | for you if it detects any outstanding transactions in the journal and similarly | ||
| 170 | journal_load() will call journal_recover() if necessary. | ||
| 171 | I would advise reading fs/ext3/super.c for examples on this stage. | ||
| 172 | [RGG: Why is the journal_wipe() call necessary - doesn't this needlessly | ||
| 173 | complicate the API. Or isn't a good idea for the journal layer to hide | ||
| 174 | dirty mounts from the client fs] | ||
| 175 | </para> | ||
| 176 | |||
| 177 | <para> | ||
| 178 | Now you can go ahead and start modifying the underlying | ||
| 179 | filesystem. Almost. | ||
| 180 | </para> | ||
| 181 | |||
| 182 | <para> | ||
| 183 | |||
| 184 | You still need to actually journal your filesystem changes, this | ||
| 185 | is done by wrapping them into transactions. Additionally you | ||
| 186 | also need to wrap the modification of each of the buffers | ||
| 187 | with calls to the journal layer, so it knows what the modifications | ||
| 188 | you are actually making are. To do this use journal_start() which | ||
| 189 | returns a transaction handle. | ||
| 190 | </para> | ||
| 191 | |||
| 192 | <para> | ||
| 193 | journal_start() | ||
| 194 | and its counterpart journal_stop(), which indicates the end of a transaction | ||
| 195 | are nestable calls, so you can reenter a transaction if necessary, | ||
| 196 | but remember you must call journal_stop() the same number of times as | ||
| 197 | journal_start() before the transaction is completed (or more accurately | ||
| 198 | leaves the update phase). Ext3/VFS makes use of this feature to simplify | ||
| 199 | quota support. | ||
| 200 | </para> | ||
| 201 | |||
| 202 | <para> | ||
| 203 | Inside each transaction you need to wrap the modifications to the | ||
| 204 | individual buffers (blocks). Before you start to modify a buffer you | ||
| 205 | need to call journal_get_{create,write,undo}_access() as appropriate, | ||
| 206 | this allows the journalling layer to copy the unmodified data if it | ||
| 207 | needs to. After all the buffer may be part of a previously uncommitted | ||
| 208 | transaction. | ||
| 209 | At this point you are at last ready to modify a buffer, and once | ||
| 210 | you are have done so you need to call journal_dirty_{meta,}data(). | ||
| 211 | Or if you've asked for access to a buffer you now know is now longer | ||
| 212 | required to be pushed back on the device you can call journal_forget() | ||
| 213 | in much the same way as you might have used bforget() in the past. | ||
| 214 | </para> | ||
| 215 | |||
| 216 | <para> | ||
| 217 | A journal_flush() may be called at any time to commit and checkpoint | ||
| 218 | all your transactions. | ||
| 219 | </para> | ||
| 220 | |||
| 221 | <para> | ||
| 222 | Then at umount time , in your put_super() (2.4) or write_super() (2.5) | ||
| 223 | you can then call journal_destroy() to clean up your in-core journal object. | ||
| 224 | </para> | ||
| 225 | |||
| 226 | <para> | ||
| 227 | Unfortunately there a couple of ways the journal layer can cause a deadlock. | ||
| 228 | The first thing to note is that each task can only have | ||
| 229 | a single outstanding transaction at any one time, remember nothing | ||
| 230 | commits until the outermost journal_stop(). This means | ||
| 231 | you must complete the transaction at the end of each file/inode/address | ||
| 232 | etc. operation you perform, so that the journalling system isn't re-entered | ||
| 233 | on another journal. Since transactions can't be nested/batched | ||
| 234 | across differing journals, and another filesystem other than | ||
| 235 | yours (say ext3) may be modified in a later syscall. | ||
| 236 | </para> | ||
| 237 | |||
| 238 | <para> | ||
| 239 | The second case to bear in mind is that journal_start() can | ||
| 240 | block if there isn't enough space in the journal for your transaction | ||
| 241 | (based on the passed nblocks param) - when it blocks it merely(!) needs to | ||
| 242 | wait for transactions to complete and be committed from other tasks, | ||
| 243 | so essentially we are waiting for journal_stop(). So to avoid | ||
| 244 | deadlocks you must treat journal_start/stop() as if they | ||
| 245 | were semaphores and include them in your semaphore ordering rules to prevent | ||
| 246 | deadlocks. Note that journal_extend() has similar blocking behaviour to | ||
| 247 | journal_start() so you can deadlock here just as easily as on journal_start(). | ||
| 248 | </para> | ||
| 249 | |||
| 250 | <para> | ||
| 251 | Try to reserve the right number of blocks the first time. ;-). This will | ||
| 252 | be the maximum number of blocks you are going to touch in this transaction. | ||
| 253 | I advise having a look at at least ext3_jbd.h to see the basis on which | ||
| 254 | ext3 uses to make these decisions. | ||
| 255 | </para> | ||
| 256 | |||
| 257 | <para> | ||
| 258 | Another wriggle to watch out for is your on-disk block allocation strategy. | ||
| 259 | why? Because, if you undo a delete, you need to ensure you haven't reused any | ||
| 260 | of the freed blocks in a later transaction. One simple way of doing this | ||
| 261 | is make sure any blocks you allocate only have checkpointed transactions | ||
| 262 | listed against them. Ext3 does this in ext3_test_allocatable(). | ||
| 263 | </para> | ||
| 264 | |||
| 265 | <para> | ||
| 266 | Lock is also providing through journal_{un,}lock_updates(), | ||
| 267 | ext3 uses this when it wants a window with a clean and stable fs for a moment. | ||
| 268 | eg. | ||
| 269 | </para> | ||
| 270 | |||
| 271 | <programlisting> | ||
| 272 | |||
| 273 | journal_lock_updates() //stop new stuff happening.. | ||
| 274 | journal_flush() // checkpoint everything. | ||
| 275 | ..do stuff on stable fs | ||
| 276 | journal_unlock_updates() // carry on with filesystem use. | ||
| 277 | </programlisting> | ||
| 278 | |||
| 279 | <para> | ||
| 280 | The opportunities for abuse and DOS attacks with this should be obvious, | ||
| 281 | if you allow unprivileged userspace to trigger codepaths containing these | ||
| 282 | calls. | ||
| 283 | </para> | ||
| 284 | |||
| 285 | <para> | ||
| 286 | A new feature of jbd since 2.5.25 is commit callbacks with the new | ||
| 287 | journal_callback_set() function you can now ask the journalling layer | ||
| 288 | to call you back when the transaction is finally committed to disk, so that | ||
| 289 | you can do some of your own management. The key to this is the journal_callback | ||
| 290 | struct, this maintains the internal callback information but you can | ||
| 291 | extend it like this:- | ||
| 292 | </para> | ||
| 293 | <programlisting> | ||
| 294 | struct myfs_callback_s { | ||
| 295 | //Data structure element required by jbd.. | ||
| 296 | struct journal_callback for_jbd; | ||
| 297 | // Stuff for myfs allocated together. | ||
| 298 | myfs_inode* i_commited; | ||
| 299 | |||
| 300 | } | ||
| 301 | </programlisting> | ||
| 302 | |||
| 303 | <para> | ||
| 304 | this would be useful if you needed to know when data was committed to a | ||
| 305 | particular inode. | ||
| 306 | </para> | ||
| 307 | |||
| 308 | </sect2> | ||
| 309 | |||
| 310 | <sect2> | ||
| 311 | <title>Summary</title> | ||
| 312 | <para> | ||
| 313 | Using the journal is a matter of wrapping the different context changes, | ||
| 314 | being each mount, each modification (transaction) and each changed buffer | ||
| 315 | to tell the journalling layer about them. | ||
| 316 | </para> | ||
| 317 | |||
| 318 | <para> | ||
| 319 | Here is a some pseudo code to give you an idea of how it works, as | ||
| 320 | an example. | ||
| 321 | </para> | ||
| 322 | |||
| 323 | <programlisting> | ||
| 324 | journal_t* my_jnrl = journal_create(); | ||
| 325 | journal_init_{dev,inode}(jnrl,...) | ||
| 326 | if (clean) journal_wipe(); | ||
| 327 | journal_load(); | ||
| 328 | |||
| 329 | foreach(transaction) { /*transactions must be | ||
| 330 | completed before | ||
| 331 | a syscall returns to | ||
| 332 | userspace*/ | ||
| 333 | |||
| 334 | handle_t * xct=journal_start(my_jnrl); | ||
| 335 | foreach(bh) { | ||
| 336 | journal_get_{create,write,undo}_access(xact,bh); | ||
| 337 | if ( myfs_modify(bh) ) { /* returns true | ||
| 338 | if makes changes */ | ||
| 339 | journal_dirty_{meta,}data(xact,bh); | ||
| 340 | } else { | ||
| 341 | journal_forget(bh); | ||
| 342 | } | ||
| 343 | } | ||
| 344 | journal_stop(xct); | ||
| 345 | } | ||
| 346 | journal_destroy(my_jrnl); | ||
| 347 | </programlisting> | ||
| 348 | </sect2> | ||
| 349 | |||
| 350 | </sect1> | ||
| 351 | |||
| 352 | <sect1> | ||
| 353 | <title>Data Types</title> | ||
| 354 | <para> | ||
| 355 | The journalling layer uses typedefs to 'hide' the concrete definitions | ||
| 356 | of the structures used. As a client of the JBD layer you can | ||
| 357 | just rely on the using the pointer as a magic cookie of some sort. | ||
| 358 | |||
| 359 | Obviously the hiding is not enforced as this is 'C'. | ||
| 360 | </para> | ||
| 361 | <sect2><title>Structures</title> | ||
| 362 | !Iinclude/linux/jbd.h | ||
| 363 | </sect2> | ||
| 364 | </sect1> | ||
| 365 | |||
| 366 | <sect1> | ||
| 367 | <title>Functions</title> | ||
| 368 | <para> | ||
| 369 | The functions here are split into two groups those that | ||
| 370 | affect a journal as a whole, and those which are used to | ||
| 371 | manage transactions | ||
| 372 | </para> | ||
| 373 | <sect2><title>Journal Level</title> | ||
| 374 | !Efs/jbd/journal.c | ||
| 375 | !Ifs/jbd/recovery.c | ||
| 376 | </sect2> | ||
| 377 | <sect2><title>Transasction Level</title> | ||
| 378 | !Efs/jbd/transaction.c | ||
| 379 | </sect2> | ||
| 380 | </sect1> | ||
| 381 | <sect1> | ||
| 382 | <title>See also</title> | ||
| 383 | <para> | ||
| 384 | <citation> | ||
| 385 | <ulink url="ftp://ftp.uk.linux.org/pub/linux/sct/fs/jfs/journal-design.ps.gz"> | ||
| 386 | Journaling the Linux ext2fs Filesystem, LinuxExpo 98, Stephen Tweedie | ||
| 387 | </ulink> | ||
| 388 | </citation> | ||
| 389 | </para> | ||
| 390 | <para> | ||
| 391 | <citation> | ||
| 392 | <ulink url="http://olstrans.sourceforge.net/release/OLS2000-ext3/OLS2000-ext3.html"> | ||
| 393 | Ext3 Journalling FileSystem, OLS 2000, Dr. Stephen Tweedie | ||
| 394 | </ulink> | ||
| 395 | </citation> | ||
| 396 | </para> | ||
| 397 | </sect1> | ||
| 398 | |||
| 399 | </chapter> | ||
| 400 | |||
| 101 | </book> | 401 | </book> |
diff --git a/Documentation/DocBook/journal-api.tmpl b/Documentation/DocBook/journal-api.tmpl deleted file mode 100644 index 2077f9a28c19..000000000000 --- a/Documentation/DocBook/journal-api.tmpl +++ /dev/null | |||
| @@ -1,333 +0,0 @@ | |||
| 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 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 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 | !Ifs/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> | ||