Documentation: sharedsubtree: Don't repeat lists with explanation

Linux kernel mirror (for testing) git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git

kernel os linux

Don't repeat lists only mentioning the items when a corresponding list
with item's explanations suffices.

Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250819061254.31220-4-bagasdotme@gmail.com

authored by

Bagas Sanjaya and committed by

Jonathan Corbet 7 months ago 570924bf a8886b42

+44 -62

1 changed file

expand all

Documentation

filesystems

sharedsubtree.rst

+44 -62

Documentation/filesystems/sharedsubtree.rst

··· 31 31 ----------- 32 32 33 33 Shared subtree provides four different flavors of mounts; struct vfsmount to be 34 - precise 35 - 36 - a. shared mount 37 - b. slave mount 38 - c. private mount 39 - d. unbindable mount 34 + precise: 40 35 41 36 42 - a) A shared mount can be replicated to as many mountpoints and all the 37 + a) A **shared mount** can be replicated to as many mountpoints and all the 43 38 replicas continue to be exactly same. 44 39 45 40 Here is an example: ··· 78 83 contents will be visible under /tmp/a too. 79 84 80 85 81 - b) A slave mount is like a shared mount except that mount and umount events 86 + b) A **slave mount** is like a shared mount except that mount and umount events 82 87 only propagate towards it. 83 88 84 89 All slave mounts have a master mount which is a shared. ··· 126 131 /mnt 127 132 128 133 129 - c) A private mount does not forward or receive propagation. 134 + c) A **private mount** does not forward or receive propagation. 130 135 131 136 This is the mount we are familiar with. Its the default type. 132 137 133 138 134 - d) A unbindable mount is a unbindable private mount 139 + d) An **unbindable mount** is, as the name suggests, an unbindable private 140 + mount. 135 141 136 142 let's say we have a mount at /mnt and we make it unbindable:: 137 143 ··· 248 252 249 253 a) Mount states 250 254 251 - A given mount can be in one of the following states 252 - 253 - 1) shared 254 - 2) slave 255 - 3) shared and slave 256 - 4) private 257 - 5) unbindable 258 - 259 - A 'propagation event' is defined as event generated on a vfsmount 255 + A **propagation event** is defined as event generated on a vfsmount 260 256 that leads to mount or unmount actions in other vfsmounts. 261 257 262 - A 'peer group' is defined as a group of vfsmounts that propagate 258 + A **peer group** is defined as a group of vfsmounts that propagate 263 259 events to each other. 260 + 261 + A given mount can be in one of the following states: 264 262 265 263 (1) Shared mounts 266 264 267 - A 'shared mount' is defined as a vfsmount that belongs to a 268 - 'peer group'. 265 + A **shared mount** is defined as a vfsmount that belongs to a 266 + peer group. 269 267 270 268 For example:: 271 269 ··· 274 284 275 285 (2) Slave mounts 276 286 277 - A 'slave mount' is defined as a vfsmount that receives 287 + A **slave mount** is defined as a vfsmount that receives 278 288 propagation events and does not forward propagation events. 279 289 280 290 A slave mount as the name implies has a master mount from which ··· 289 299 290 300 (3) Shared and Slave 291 301 292 - A vfsmount can be both shared as well as slave. This state 302 + A vfsmount can be both **shared** as well as **slave**. This state 293 303 indicates that the mount is a slave of some vfsmount, and 294 304 has its own peer group too. This vfsmount receives propagation 295 305 events from its master vfsmount, and also forwards propagation ··· 308 318 309 319 (4) Private mount 310 320 311 - A 'private mount' is defined as vfsmount that does not 321 + A **private mount** is defined as vfsmount that does not 312 322 receive or forward any propagation events. 313 323 314 324 (5) Unbindable mount 315 325 316 - A 'unbindable mount' is defined as vfsmount that does not 326 + A **unbindable mount** is defined as vfsmount that does not 317 327 receive or forward any propagation events and cannot 318 328 be bind mounted. 319 329 ··· 844 854 845 855 A) Datastructure 846 856 847 - 4 new fields are introduced to struct vfsmount: 848 - 849 - * ->mnt_share 850 - * ->mnt_slave_list 851 - * ->mnt_slave 852 - * ->mnt_master 857 + Several new fields are introduced to struct vfsmount: 853 858 854 859 ->mnt_share 855 - links together all the mount to/from which this vfsmount 860 + Links together all the mount to/from which this vfsmount 856 861 send/receives propagation events. 857 862 858 863 ->mnt_slave_list 859 - links all the mounts to which this vfsmount propagates 864 + Links all the mounts to which this vfsmount propagates 860 865 to. 861 866 862 867 ->mnt_slave 863 - links together all the slaves that its master vfsmount 868 + Links together all the slaves that its master vfsmount 864 869 propagates to. 865 870 866 871 ->mnt_master 867 - points to the master vfsmount from which this vfsmount 872 + Points to the master vfsmount from which this vfsmount 868 873 receives propagation. 869 874 870 875 ->mnt_flags 871 - takes two more flags to indicate the propagation status of 876 + Takes two more flags to indicate the propagation status of 872 877 the vfsmount. MNT_SHARE indicates that the vfsmount is a shared 873 878 vfsmount. MNT_UNCLONABLE indicates that the vfsmount cannot be 874 879 replicated. ··· 945 960 The overall algorithm breaks the operation into 3 phases: (look at 946 961 attach_recursive_mnt() and propagate_mnt()) 947 962 948 - 1. prepare phase. 949 - 2. commit phases. 950 - 3. abort phases. 963 + 1. Prepare phase. 951 964 952 - Prepare phase: 965 + For each mount in the source tree: 953 966 954 - for each mount in the source tree: 967 + a) Create the necessary number of mount trees to 968 + be attached to each of the mounts that receive 969 + propagation from the destination mount. 970 + b) Do not attach any of the trees to its destination. 971 + However note down its ->mnt_parent and ->mnt_mountpoint 972 + c) Link all the new mounts to form a propagation tree that 973 + is identical to the propagation tree of the destination 974 + mount. 955 975 956 - a) Create the necessary number of mount trees to 957 - be attached to each of the mounts that receive 958 - propagation from the destination mount. 959 - b) Do not attach any of the trees to its destination. 960 - However note down its ->mnt_parent and ->mnt_mountpoint 961 - c) Link all the new mounts to form a propagation tree that 962 - is identical to the propagation tree of the destination 963 - mount. 976 + If this phase is successful, there should be 'n' new 977 + propagation trees; where 'n' is the number of mounts in the 978 + source tree. Go to the commit phase 964 979 965 - If this phase is successful, there should be 'n' new 966 - propagation trees; where 'n' is the number of mounts in the 967 - source tree. Go to the commit phase 980 + Also there should be 'm' new mount trees, where 'm' is 981 + the number of mounts to which the destination mount 982 + propagates to. 968 983 969 - Also there should be 'm' new mount trees, where 'm' is 970 - the number of mounts to which the destination mount 971 - propagates to. 984 + If any memory allocations fail, go to the abort phase. 972 985 973 - if any memory allocations fail, go to the abort phase. 986 + 2. Commit phase. 974 987 975 - Commit phase 976 - attach each of the mount trees to their corresponding 977 - destination mounts. 988 + Attach each of the mount trees to their corresponding 989 + destination mounts. 978 990 979 - Abort phase 980 - delete all the newly created trees. 991 + 3. Abort phase. 992 + Delete all the newly created trees. 981 993 982 994 .. Note:: 983 995 all the propagation related functionality resides in the file pnode.c