^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2) JFFS2 LOCKING DOCUMENTATION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) This document attempts to describe the existing locking rules for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6) JFFS2. It is not expected to remain perfectly up to date, but ought to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) be fairly close.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) alloc_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) ---------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) The alloc_sem is a per-filesystem mutex, used primarily to ensure
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) contiguous allocation of space on the medium. It is automatically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) obtained during space allocations (jffs2_reserve_space()) and freed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) upon write completion (jffs2_complete_reservation()). Note that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) the garbage collector will obtain this right at the beginning of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) jffs2_garbage_collect_pass() and release it at the end, thereby
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) preventing any other write activity on the file system during a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) garbage collect pass.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22) When writing new nodes, the alloc_sem must be held until the new nodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) have been properly linked into the data structures for the inode to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) which they belong. This is for the benefit of NAND flash - adding new
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) nodes to an inode may obsolete old ones, and by holding the alloc_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) until this happens we ensure that any data in the write-buffer at the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) time this happens are part of the new node, not just something that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) was written afterwards. Hence, we can ensure the newly-obsoleted nodes
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29) don't actually get erased until the write-buffer has been flushed to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) the medium.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) With the introduction of NAND flash support and the write-buffer,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) the alloc_sem is also used to protect the wbuf-related members of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) jffs2_sb_info structure. Atomically reading the wbuf_len member to see
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) if the wbuf is currently holding any data is permitted, though.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) Ordering constraints: See f->sem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40) File Mutex f->sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) ---------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) This is the JFFS2-internal equivalent of the inode mutex i->i_sem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) It protects the contents of the jffs2_inode_info private inode data,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45) including the linked list of node fragments (but see the notes below on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) erase_completion_lock), etc.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) The reason that the i_sem itself isn't used for this purpose is to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49) avoid deadlocks with garbage collection -- the VFS will lock the i_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) before calling a function which may need to allocate space. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) allocation may trigger garbage-collection, which may need to move a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) node belonging to the inode which was locked in the first place by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53) VFS. If the garbage collection code were to attempt to lock the i_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) of the inode from which it's garbage-collecting a physical node, this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55) lead to deadlock, unless we played games with unlocking the i_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) before calling the space allocation functions.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) Instead of playing such games, we just have an extra internal
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59) mutex, which is obtained by the garbage collection code and also
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) by the normal file system code _after_ allocation of space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) Ordering constraints:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64) 1. Never attempt to allocate space or lock alloc_sem with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) any f->sem held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) 2. Never attempt to lock two file mutexes in one thread.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) No ordering rules have been made for doing so.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) 3. Never lock a page cache page with f->sem held.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) erase_completion_lock spinlock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) This is used to serialise access to the eraseblock lists, to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75) per-eraseblock lists of physical jffs2_raw_node_ref structures, and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) (NB) the per-inode list of physical nodes. The latter is a special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) case - see below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) As the MTD API no longer permits erase-completion callback functions
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) to be called from bottom-half (timer) context (on the basis that nobody
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) ever actually implemented such a thing), it's now sufficient to use
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82) a simple spin_lock() rather than spin_lock_bh().
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84) Note that the per-inode list of physical nodes (f->nodes) is a special
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) case. Any changes to _valid_ nodes (i.e. ->flash_offset & 1 == 0) in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) the list are protected by the file mutex f->sem. But the erase code
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) may remove _obsolete_ nodes from the list while holding only the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) erase_completion_lock. So you can walk the list only while holding the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) erase_completion_lock, and can drop the lock temporarily mid-walk as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) long as the pointer you're holding is to a _valid_ node, not an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91) obsolete one.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) The erase_completion_lock is also used to protect the c->gc_task
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) pointer when the garbage collection thread exits. The code to kill the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) GC thread locks it, sends the signal, then unlocks it - while the GC
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) thread itself locks it, zeroes c->gc_task, then unlocks on the exit path.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99) inocache_lock spinlock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) ----------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) This spinlock protects the hashed list (c->inocache_list) of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) in-core jffs2_inode_cache objects (each inode in JFFS2 has the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) correspondent jffs2_inode_cache object). So, the inocache_lock
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) has to be locked while walking the c->inocache_list hash buckets.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) This spinlock also covers allocation of new inode numbers, which is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) currently just '++->highest_ino++', but might one day get more complicated
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) if we need to deal with wrapping after 4 milliard inode numbers are used.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) Note, the f->sem guarantees that the correspondent jffs2_inode_cache
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) will not be removed. So, it is allowed to access it without locking
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113) the inocache_lock spinlock.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) Ordering constraints:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117) If both erase_completion_lock and inocache_lock are needed, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) c->erase_completion has to be acquired first.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) erase_free_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) --------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124) This mutex is only used by the erase code which frees obsolete node
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) references and the jffs2_garbage_collect_deletion_dirent() function.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) The latter function on NAND flash must read _obsolete_ nodes to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) determine whether the 'deletion dirent' under consideration can be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) discarded or whether it is still required to show that an inode has
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) been unlinked. Because reading from the flash may sleep, the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130) erase_completion_lock cannot be held, so an alternative, more
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) heavyweight lock was required to prevent the erase code from freeing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) the jffs2_raw_node_ref structures in question while the garbage
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) collection code is looking at them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) Suggestions for alternative solutions to this problem would be welcomed.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) wbuf_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) --------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) This read/write semaphore protects against concurrent access to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) write-behind buffer ('wbuf') used for flash chips where we must write
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143) in blocks. It protects both the contents of the wbuf and the metadata
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) which indicates which flash region (if any) is currently covered by
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) the buffer.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) Ordering constraints:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) Lock wbuf_sem last, after the alloc_sem or and f->sem.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) c->xattr_sem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) ------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) This read/write semaphore protects against concurrent access to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) xattr related objects which include stuff in superblock and ic->xref.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) In read-only path, write-semaphore is too much exclusion. It's enough
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) by read-semaphore. But you must hold write-semaphore when updating,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) creating or deleting any xattr related object.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) Once xattr_sem released, there would be no assurance for the existence
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) of those objects. Thus, a series of processes is often required to retry,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) when updating such a object is necessary under holding read semaphore.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) For example, do_jffs2_getxattr() holds read-semaphore to scan xref and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) xdatum at first. But it retries this process with holding write-semaphore
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) after release read-semaphore, if it's necessary to load name/value pair
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) from medium.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168) Ordering constraints:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) Lock xattr_sem last, after the alloc_sem.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags