[GitHub/mt8127/android_kernel_alcatel_ttab.git] / Documentation / filesystems / automount-support.txt

Support is available for filesystems that wish to do automounting support (such
as kAFS which can be found in fs/afs/). This facility includes allowing
in-kernel mounts to be performed and mountpoint degradation to be
requested. The latter can also be requested by userspace.


======================
IN-KERNEL AUTOMOUNTING
======================

A filesystem can now mount another filesystem on one of its directories by the
following procedure:

 (1) Give the directory a follow_link() operation.

     When the directory is accessed, the follow_link op will be called, and
     it will be provided with the location of the mountpoint in the nameidata
     structure (vfsmount and dentry).

 (2) Have the follow_link() op do the following steps:

     (a) Call vfs_kern_mount() to call the appropriate filesystem to set up a
         superblock and gain a vfsmount structure representing it.

     (b) Copy the nameidata provided as an argument and substitute the dentry
	 argument into it the copy.

     (c) Call do_add_mount() to install the new vfsmount into the namespace's
	 mountpoint tree, thus making it accessible to userspace. Use the
	 nameidata set up in (b) as the destination.

	 If the mountpoint will be automatically expired, then do_add_mount()
	 should also be given the location of an expiration list (see further
	 down).

     (d) Release the path in the nameidata argument and substitute in the new
	 vfsmount and its root dentry. The ref counts on these will need
	 incrementing.

Then from userspace, you can just do something like:

	[root@andromeda root]# mount -t afs \#root.afs. /afs
	[root@andromeda root]# ls /afs
	asd  cambridge  cambridge.redhat.com  grand.central.org
	[root@andromeda root]# ls /afs/cambridge
	afsdoc
	[root@andromeda root]# ls /afs/cambridge/afsdoc/
	ChangeLog  html  LICENSE  pdf  RELNOTES-1.2.2

And then if you look in the mountpoint catalogue, you'll see something like:

	[root@andromeda root]# cat /proc/mounts
	...
	#root.afs. /afs afs rw 0 0
	#root.cell. /afs/cambridge.redhat.com afs rw 0 0
	#afsdoc. /afs/cambridge.redhat.com/afsdoc afs rw 0 0


===========================
AUTOMATIC MOUNTPOINT EXPIRY
===========================

Automatic expiration of mountpoints is easy, provided you've mounted the
mountpoint to be expired in the automounting procedure outlined above.

To do expiration, you need to follow these steps:

 (3) Create at least one list off which the vfsmounts to be expired can be
     hung. Access to this list will be governed by the vfsmount_lock.

 (4) In step (2c) above, the call to do_add_mount() should be provided with a
     pointer to this list. It will hang the vfsmount off of it if it succeeds.

 (5) When you want mountpoints to be expired, call mark_mounts_for_expiry()
     with a pointer to this list. This will process the list, marking every
     vfsmount thereon for potential expiry on the next call.

     If a vfsmount was already flagged for expiry, and if its usage count is 1
     (it's only referenced by its parent vfsmount), then it will be deleted
     from the namespace and thrown away (effectively unmounted).

     It may prove simplest to simply call this at regular intervals, using
     some sort of timed event to drive it.

The expiration flag is cleared by calls to mntput. This means that expiration
will only happen on the second expiration request after the last time the
mountpoint was accessed.

If a mountpoint is moved, it gets removed from the expiration list. If a bind
mount is made on an expirable mount, the new vfsmount will not be on the
expiration list and will not expire.

If a namespace is copied, all mountpoints contained therein will be copied,
and the copies of those that are on an expiration list will be added to the
same expiration list.


=======================
USERSPACE DRIVEN EXPIRY
=======================

As an alternative, it is possible for userspace to request expiry of any
mountpoint (though some will be rejected - the current process's idea of the
rootfs for example). It does this by passing the MNT_EXPIRE flag to
umount(). This flag is considered incompatible with MNT_FORCE and MNT_DETACH.

If the mountpoint in question is in referenced by something other than
umount() or its parent mountpoint, an EBUSY error will be returned and the
mountpoint will not be marked for expiration or unmounted.

If the mountpoint was not already marked for expiry at that time, an EAGAIN
error will be given and it won't be unmounted.

Otherwise if it was already marked and it wasn't referenced, unmounting will
take place as usual.

Again, the expiration flag is cleared every time anything other than umount()
looks at a mountpoint.
Commit	Line	Data
1da177e4 LT	1	Support is available for filesystems that wish to do automounting support (such
	2	as kAFS which can be found in fs/afs/). This facility includes allowing
	3	in-kernel mounts to be performed and mountpoint degradation to be
	4	requested. The latter can also be requested by userspace.
	5
	6
	7	======================
	8	IN-KERNEL AUTOMOUNTING
	9	======================
	10
	11	A filesystem can now mount another filesystem on one of its directories by the
	12	following procedure:
	13
	14	(1) Give the directory a follow_link() operation.
	15
	16	When the directory is accessed, the follow_link op will be called, and
	17	it will be provided with the location of the mountpoint in the nameidata
	18	structure (vfsmount and dentry).
	19
	20	(2) Have the follow_link() op do the following steps:
	21
1f5ce9e9	22	(a) Call vfs_kern_mount() to call the appropriate filesystem to set up a
1da177e4 LT	23	superblock and gain a vfsmount structure representing it.
	24
	25	(b) Copy the nameidata provided as an argument and substitute the dentry
	26	argument into it the copy.
	27
	28	(c) Call do_add_mount() to install the new vfsmount into the namespace's
	29	mountpoint tree, thus making it accessible to userspace. Use the
	30	nameidata set up in (b) as the destination.
	31
	32	If the mountpoint will be automatically expired, then do_add_mount()
	33	should also be given the location of an expiration list (see further
	34	down).
	35
	36	(d) Release the path in the nameidata argument and substitute in the new
	37	vfsmount and its root dentry. The ref counts on these will need
	38	incrementing.
	39
	40	Then from userspace, you can just do something like:
	41
	42	[root@andromeda root]# mount -t afs \#root.afs. /afs
	43	[root@andromeda root]# ls /afs
	44	asd cambridge cambridge.redhat.com grand.central.org
	45	[root@andromeda root]# ls /afs/cambridge
	46	afsdoc
	47	[root@andromeda root]# ls /afs/cambridge/afsdoc/
	48	ChangeLog html LICENSE pdf RELNOTES-1.2.2
	49
	50	And then if you look in the mountpoint catalogue, you'll see something like:
	51
	52	[root@andromeda root]# cat /proc/mounts
	53	...
	54	#root.afs. /afs afs rw 0 0
	55	#root.cell. /afs/cambridge.redhat.com afs rw 0 0
	56	#afsdoc. /afs/cambridge.redhat.com/afsdoc afs rw 0 0
	57
	58
	59	===========================
	60	AUTOMATIC MOUNTPOINT EXPIRY
	61	===========================
	62
	63	Automatic expiration of mountpoints is easy, provided you've mounted the
	64	mountpoint to be expired in the automounting procedure outlined above.
	65
	66	To do expiration, you need to follow these steps:
	67
	68	(3) Create at least one list off which the vfsmounts to be expired can be
	69	hung. Access to this list will be governed by the vfsmount_lock.
	70
	71	(4) In step (2c) above, the call to do_add_mount() should be provided with a
	72	pointer to this list. It will hang the vfsmount off of it if it succeeds.
	73
	74	(5) When you want mountpoints to be expired, call mark_mounts_for_expiry()
	75	with a pointer to this list. This will process the list, marking every
	76	vfsmount thereon for potential expiry on the next call.
	77
	78	If a vfsmount was already flagged for expiry, and if its usage count is 1
	79	(it's only referenced by its parent vfsmount), then it will be deleted
	80	from the namespace and thrown away (effectively unmounted).
	81
	82	It may prove simplest to simply call this at regular intervals, using
	83	some sort of timed event to drive it.
	84
	85	The expiration flag is cleared by calls to mntput. This means that expiration
	86	will only happen on the second expiration request after the last time the
87	mountpoint was accessed.
88
89	If a mountpoint is moved, it gets removed from the expiration list. If a bind
90	mount is made on an expirable mount, the new vfsmount will not be on the
91	expiration list and will not expire.
92
93	If a namespace is copied, all mountpoints contained therein will be copied,
94	and the copies of those that are on an expiration list will be added to the
95	same expiration list.
96
97
98	=======================
99	USERSPACE DRIVEN EXPIRY
100	=======================
101
102	As an alternative, it is possible for userspace to request expiry of any
103	mountpoint (though some will be rejected - the current process's idea of the
104	rootfs for example). It does this by passing the MNT_EXPIRE flag to
105	umount(). This flag is considered incompatible with MNT_FORCE and MNT_DETACH.
106
107	If the mountpoint in question is in referenced by something other than
108	umount() or its parent mountpoint, an EBUSY error will be returned and the
109	mountpoint will not be marked for expiration or unmounted.
110
111	If the mountpoint was not already marked for expiry at that time, an EAGAIN
112	error will be given and it won't be unmounted.
113
114	Otherwise if it was already marked and it wasn't referenced, unmounting will
115	take place as usual.
116
117	Again, the expiration flag is cleared every time anything other than umount()
118	looks at a mountpoint.