1
2 JFFS2 LOCKING DOCUMENTATION
3 ---------------------------
4
5 This document attempts to describe the existin
6 JFFS2. It is not expected to remain perfectly
7 be fairly close.
8
9
10 alloc_sem
11 ---------
12
13 The alloc_sem is a per-filesystem mutex, used
14 contiguous allocation of space on the medium.
15 obtained during space allocations (jffs2_reser
16 upon write completion (jffs2_complete_reservat
17 the garbage collector will obtain this right a
18 jffs2_garbage_collect_pass() and release it at
19 preventing any other write activity on the fil
20 garbage collect pass.
21
22 When writing new nodes, the alloc_sem must be
23 have been properly linked into the data struct
24 which they belong. This is for the benefit of
25 nodes to an inode may obsolete old ones, and b
26 until this happens we ensure that any data in
27 time this happens are part of the new node, no
28 was written afterwards. Hence, we can ensure t
29 don't actually get erased until the write-buff
30 the medium.
31
32 With the introduction of NAND flash support an
33 the alloc_sem is also used to protect the wbuf
34 jffs2_sb_info structure. Atomically reading th
35 if the wbuf is currently holding any data is p
36
37 Ordering constraints: See f->sem.
38
39
40 File Mutex f->sem
41 ---------------------
42
43 This is the JFFS2-internal equivalent of the i
44 It protects the contents of the jffs2_inode_in
45 including the linked list of node fragments (b
46 erase_completion_lock), etc.
47
48 The reason that the i_sem itself isn't used fo
49 avoid deadlocks with garbage collection -- the
50 before calling a function which may need to al
51 allocation may trigger garbage-collection, whi
52 node belonging to the inode which was locked i
53 VFS. If the garbage collection code were to at
54 of the inode from which it's garbage-collectin
55 lead to deadlock, unless we played games with
56 before calling the space allocation functions.
57
58 Instead of playing such games, we just have an
59 mutex, which is obtained by the garbage collec
60 by the normal file system code _after_ allocat
61
62 Ordering constraints:
63
64 1. Never attempt to allocate space or
65 any f->sem held.
66 2. Never attempt to lock two file mute
67 No ordering rules have been made fo
68 3. Never lock a page cache page with f
69
70
71 erase_completion_lock spinlock
72 ------------------------------
73
74 This is used to serialise access to the eraseb
75 per-eraseblock lists of physical jffs2_raw_nod
76 (NB) the per-inode list of physical nodes. The
77 case - see below.
78
79 As the MTD API no longer permits erase-complet
80 to be called from bottom-half (timer) context
81 ever actually implemented such a thing), it's
82 a simple spin_lock() rather than spin_lock_bh(
83
84 Note that the per-inode list of physical nodes
85 case. Any changes to _valid_ nodes (i.e. ->fla
86 the list are protected by the file mutex f->se
87 may remove _obsolete_ nodes from the list whil
88 erase_completion_lock. So you can walk the lis
89 erase_completion_lock, and can drop the lock t
90 long as the pointer you're holding is to a _va
91 obsolete one.
92
93 The erase_completion_lock is also used to prot
94 pointer when the garbage collection thread exi
95 GC thread locks it, sends the signal, then unl
96 thread itself locks it, zeroes c->gc_task, the
97
98
99 inocache_lock spinlock
100 ----------------------
101
102 This spinlock protects the hashed list (c->ino
103 in-core jffs2_inode_cache objects (each inode
104 correspondent jffs2_inode_cache object). So, t
105 has to be locked while walking the c->inocache
106
107 This spinlock also covers allocation of new in
108 currently just '++->highest_ino++', but might
109 if we need to deal with wrapping after 4 milli
110
111 Note, the f->sem guarantees that the correspon
112 will not be removed. So, it is allowed to acce
113 the inocache_lock spinlock.
114
115 Ordering constraints:
116
117 If both erase_completion_lock and inoc
118 c->erase_completion has to be acquired
119
120
121 erase_free_sem
122 --------------
123
124 This mutex is only used by the erase code whic
125 references and the jffs2_garbage_collect_delet
126 The latter function on NAND flash must read _o
127 determine whether the 'deletion dirent' under
128 discarded or whether it is still required to s
129 been unlinked. Because reading from the flash
130 erase_completion_lock cannot be held, so an al
131 heavyweight lock was required to prevent the e
132 the jffs2_raw_node_ref structures in question
133 collection code is looking at them.
134
135 Suggestions for alternative solutions to this
136
137
138 wbuf_sem
139 --------
140
141 This read/write semaphore protects against con
142 write-behind buffer ('wbuf') used for flash ch
143 in blocks. It protects both the contents of th
144 which indicates which flash region (if any) is
145 the buffer.
146
147 Ordering constraints:
148 Lock wbuf_sem last, after the alloc_se
149
150
151 c->xattr_sem
152 ------------
153
154 This read/write semaphore protects against con
155 xattr related objects which include stuff in s
156 In read-only path, write-semaphore is too much
157 by read-semaphore. But you must hold write-sem
158 creating or deleting any xattr related object.
159
160 Once xattr_sem released, there would be no ass
161 of those objects. Thus, a series of processes
162 when updating such a object is necessary under
163 For example, do_jffs2_getxattr() holds read-se
164 xdatum at first. But it retries this process w
165 after release read-semaphore, if it's necessar
166 from medium.
167
168 Ordering constraints:
169 Lock xattr_sem last, after the alloc_s
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.