nfsd: add some comments to the nfsd4 object definitions

Add some comments that describe what each of these objects is, and how they related to one another. Signed-off-by: Jeff Layton <jlayton@primarydata.com> Signed-off-by: J. Bruce Fields <bfields@redhat.com>

nfsd: add some comments to the nfsd4 object definitions
Add some comments that describe what each of these objects is, and how they related to one another. Signed-off-by: Jeff Layton <jlayton@primarydata.com> Signed-off-by: J. Bruce Fields <bfields@redhat.com>
Jeff Layton · J. Bruce Fields
1 parent b687f6863e
Showing 2 changed files with 101 additions and 7 deletions Side-by-side Diff
fs/nfsd/netns.h
fs/nfsd/state.h
@@ -34,6 +34,14 @@
 struct cld_net;
 struct nfsd4_client_tracking_ops;
  
+/*
+ * Represents a nfsd "container". With respect to nfsv4 state tracking, the
+ * fields of interest are the *_id_hashtbls and the *_name_tree. These track
+ * the nfs4_client objects by either short or long form clientid.
+ *
+ * Each nfsd_net runs a nfs4_laundromat workqueue job when necessary to clean
+ * up expired clients and delegations within the container.
+ */
 struct nfsd_net {
 	struct cld_net *cld_net;
  
@@ -72,6 +72,11 @@
 	bool cb_done;
 };
  
+/*
+ * A core object that represents a "common" stateid. These are generally
+ * embedded within the different (more specific) stateid objects and contain
+ * fields that are of general use to any stateid.
+ */
 struct nfs4_stid {
 	atomic_t sc_count;
 #define NFS4_OPEN_STID 1
@@ -89,6 +94,27 @@
 	void (*sc_free)(struct nfs4_stid *);
 };
  
+/*
+ * Represents a delegation stateid. The nfs4_client holds references to these
+ * and they are put when it is being destroyed or when the delegation is
+ * returned by the client:
+ *
+ * o 1 reference as long as a delegation is still in force (taken when it's
+ *   alloc'd, put when it's returned or revoked)
+ *
+ * o 1 reference as long as a recall rpc is in progress (taken when the lease
+ *   is broken, put when the rpc exits)
+ *
+ * o 1 more ephemeral reference for each nfsd thread currently doing something
+ *   with that delegation without holding the cl_lock
+ *
+ * If the server attempts to recall a delegation and the client doesn't do so
+ * before a timeout, the server may also revoke the delegation. In that case,
+ * the object will either be destroyed (v4.0) or moved to a per-client list of
+ * revoked delegations (v4.1+).
+ *
+ * This object is a superset of the nfs4_stid.
+ */
 struct nfs4_delegation {
 	struct nfs4_stid	dl_stid; /* must be first field */
 	struct list_head	dl_perfile;
@@ -195,6 +221,11 @@
 	unsigned char cn_flags;
 };
  
+/*
+ * Representation of a v4.1+ session. These are refcounted in a similar fashion
+ * to the nfs4_client. References are only taken when the server is actively
+ * working on the object (primarily during the processing of compounds).
+ */
 struct nfsd4_session {
 	atomic_t		se_ref;
 	struct list_head	se_hash;	/* hash by sessionid */
  
  
@@ -224,13 +255,30 @@
  
 /*
  * struct nfs4_client - one per client.  Clientids live here.
- * 	o Each nfs4_client is hashed by clientid.
  *
- * 	o Each nfs4_clients is also hashed by name 
- * 	  (the opaque quantity initially sent by the client to identify itself).
+ * The initial object created by an NFS client using SETCLIENTID (for NFSv4.0)
+ * or EXCHANGE_ID (for NFSv4.1+). These objects are refcounted and timestamped.
+ * Each nfsd_net_ns object contains a set of these and they are tracked via
+ * short and long form clientid. They are hashed and searched for under the
+ * per-nfsd_net client_lock spinlock.
+ *
+ * References to it are only held during the processing of compounds, and in
+ * certain other operations. In their "resting state" they have a refcount of
+ * 0. If they are not renewed within a lease period, they become eligible for
+ * destruction by the laundromat.
+ *
+ * These objects can also be destroyed prematurely by the fault injection code,
+ * or if the client sends certain forms of SETCLIENTID or EXCHANGE_ID updates.
+ * Care is taken *not* to do this however when the objects have an elevated
+ * refcount.
+ *
+ * o Each nfs4_client is hashed by clientid
+ *
+ * o Each nfs4_clients is also hashed by name (the opaque quantity initially
+ *   sent by the client to identify itself).
  * 	  
- *	o cl_perclient list is used to ensure no dangling stateowner references
- *	  when we expire the nfs4_client
+ * o cl_perclient list is used to ensure no dangling stateowner references
+ *   when we expire the nfs4_client
  */
 struct nfs4_client {
 	struct list_head	cl_idhash; 	/* hash by cl_clientid.id */
@@ -340,6 +388,12 @@
 	void (*so_free)(struct nfs4_stateowner *);
 };
  
+/*
+ * A core object that represents either an open or lock owner. The object and
+ * lock owner objects have one of these embedded within them. Refcounts and
+ * other fields common to both owner types are contained within these
+ * structures.
+ */
 struct nfs4_stateowner {
 	struct list_head			so_strhash;
 	struct list_head			so_stateids;
@@ -354,6 +408,12 @@
 	bool					so_is_open_owner;
 };
  
+/*
+ * When a file is opened, the client provides an open state owner opaque string
+ * that indicates the "owner" of that open. These objects are refcounted.
+ * References to it are held by each open state associated with it. This object
+ * is a superset of the nfs4_stateowner struct.
+ */
 struct nfs4_openowner {
 	struct nfs4_stateowner	oo_owner; /* must be first field */
 	struct list_head        oo_perclient;
@@ -371,6 +431,12 @@
 	unsigned char		oo_flags;
 };
  
+/*
+ * Represents a generic "lockowner". Similar to an openowner. References to it
+ * are held by the lock stateids that are created on its behalf. This object is
+ * a superset of the nfs4_stateowner struct (or would be if it needed any extra
+ * fields).
+ */
 struct nfs4_lockowner {
 	struct nfs4_stateowner	lo_owner; /* must be first element */
 };
@@ -385,7 +451,14 @@
 	return container_of(so, struct nfs4_lockowner, lo_owner);
 }
  
-/* nfs4_file: a file opened by some number of (open) nfs4_stateowners. */
+/*
+ * nfs4_file: a file opened by some number of (open) nfs4_stateowners.
+ *
+ * These objects are global. nfsd only keeps one instance of a nfs4_file per
+ * inode (though it may keep multiple file descriptors open per inode). These
+ * are tracked in the file_hashtbl which is protected by the state_lock
+ * spinlock.
+ */
 struct nfs4_file {
 	atomic_t		fi_ref;
 	spinlock_t		fi_lock;
@@ -410,7 +483,20 @@
 	bool			fi_had_conflict;
 };
  
-/* "ol" stands for "Open or Lock".  Better suggestions welcome. */
+/*
+ * A generic struct representing either a open or lock stateid. The nfs4_client
+ * holds a reference to each of these objects, and they in turn hold a
+ * reference to their respective stateowners. The client's reference is
+ * released in response to a close or unlock (depending on whether it's an open
+ * or lock stateid) or when the client is being destroyed.
+ *
+ * In the case of v4.0 open stateids, these objects are preserved for a little
+ * while after close in order to handle CLOSE replays. Those are eventually
+ * reclaimed via a LRU scheme by the laundromat.
+ *
+ * This object is a superset of the nfs4_stid. "ol" stands for "Open or Lock".
+ * Better suggestions welcome.
+ */
 struct nfs4_ol_stateid {
 	struct nfs4_stid    st_stid; /* must be first field */
 	struct list_head              st_perfile;
...	...	@@ -34,6 +34,14 @@
34	34	struct cld_net;
35	35	struct nfsd4_client_tracking_ops;
36	36
	37	+/*
	38	+ * Represents a nfsd "container". With respect to nfsv4 state tracking, the
	39	+ * fields of interest are the _id_hashtbls and the _name_tree. These track
	40	+ * the nfs4_client objects by either short or long form clientid.
	41	+ *
	42	+ * Each nfsd_net runs a nfs4_laundromat workqueue job when necessary to clean
	43	+ * up expired clients and delegations within the container.
	44	+ */
37	45	struct nfsd_net {
38	46	struct cld_net *cld_net;
39	47
...	...	@@ -72,6 +72,11 @@
72	72	bool cb_done;
73	73	};
74	74
	75	+/*
	76	+ * A core object that represents a "common" stateid. These are generally
	77	+ * embedded within the different (more specific) stateid objects and contain
	78	+ * fields that are of general use to any stateid.
	79	+ */
75	80	struct nfs4_stid {
76	81	atomic_t sc_count;
77	82	#define NFS4_OPEN_STID 1
...	...	@@ -89,6 +94,27 @@
89	94	void (sc_free)(struct nfs4_stid );
90	95	};
91	96
	97	+/*
	98	+ * Represents a delegation stateid. The nfs4_client holds references to these
	99	+ * and they are put when it is being destroyed or when the delegation is
	100	+ * returned by the client:
	101	+ *
	102	+ * o 1 reference as long as a delegation is still in force (taken when it's
	103	+ * alloc'd, put when it's returned or revoked)
	104	+ *
	105	+ * o 1 reference as long as a recall rpc is in progress (taken when the lease
	106	+ * is broken, put when the rpc exits)
	107	+ *
	108	+ * o 1 more ephemeral reference for each nfsd thread currently doing something
	109	+ * with that delegation without holding the cl_lock
	110	+ *
	111	+ * If the server attempts to recall a delegation and the client doesn't do so
	112	+ * before a timeout, the server may also revoke the delegation. In that case,
	113	+ * the object will either be destroyed (v4.0) or moved to a per-client list of
	114	+ * revoked delegations (v4.1+).
	115	+ *
	116	+ * This object is a superset of the nfs4_stid.
	117	+ */
92	118	struct nfs4_delegation {
93	119	struct nfs4_stid dl_stid; /* must be first field */
94	120	struct list_head dl_perfile;
...	...	@@ -195,6 +221,11 @@
195	221	unsigned char cn_flags;
196	222	};
197	223
	224	+/*
	225	+ * Representation of a v4.1+ session. These are refcounted in a similar fashion
	226	+ * to the nfs4_client. References are only taken when the server is actively
	227	+ * working on the object (primarily during the processing of compounds).
	228	+ */
198	229	struct nfsd4_session {
199	230	atomic_t se_ref;
200	231	struct list_head se_hash; /* hash by sessionid */
201	232
202	233
...	...	@@ -224,13 +255,30 @@
224	255
225	256	/*
226	257	* struct nfs4_client - one per client. Clientids live here.
227		- * o Each nfs4_client is hashed by clientid.
228	258	*
229		- * o Each nfs4_clients is also hashed by name
230		- * (the opaque quantity initially sent by the client to identify itself).
	259	+ * The initial object created by an NFS client using SETCLIENTID (for NFSv4.0)
	260	+ * or EXCHANGE_ID (for NFSv4.1+). These objects are refcounted and timestamped.
	261	+ * Each nfsd_net_ns object contains a set of these and they are tracked via
	262	+ * short and long form clientid. They are hashed and searched for under the
	263	+ * per-nfsd_net client_lock spinlock.
	264	+ *
	265	+ * References to it are only held during the processing of compounds, and in
	266	+ * certain other operations. In their "resting state" they have a refcount of
	267	+ * 0. If they are not renewed within a lease period, they become eligible for
	268	+ * destruction by the laundromat.
	269	+ *
	270	+ * These objects can also be destroyed prematurely by the fault injection code,
	271	+ * or if the client sends certain forms of SETCLIENTID or EXCHANGE_ID updates.
	272	+ * Care is taken not to do this however when the objects have an elevated
	273	+ * refcount.
	274	+ *
	275	+ * o Each nfs4_client is hashed by clientid
	276	+ *
	277	+ * o Each nfs4_clients is also hashed by name (the opaque quantity initially
	278	+ * sent by the client to identify itself).
231	279	*
232		- * o cl_perclient list is used to ensure no dangling stateowner references
233		- * when we expire the nfs4_client
	280	+ * o cl_perclient list is used to ensure no dangling stateowner references
	281	+ * when we expire the nfs4_client
234	282	*/
235	283	struct nfs4_client {
236	284	struct list_head cl_idhash; /* hash by cl_clientid.id */
...	...	@@ -340,6 +388,12 @@
340	388	void (so_free)(struct nfs4_stateowner );
341	389	};
342	390
	391	+/*
	392	+ * A core object that represents either an open or lock owner. The object and
	393	+ * lock owner objects have one of these embedded within them. Refcounts and
	394	+ * other fields common to both owner types are contained within these
	395	+ * structures.
	396	+ */
343	397	struct nfs4_stateowner {
344	398	struct list_head so_strhash;
345	399	struct list_head so_stateids;
...	...	@@ -354,6 +408,12 @@
354	408	bool so_is_open_owner;
355	409	};
356	410
	411	+/*
	412	+ * When a file is opened, the client provides an open state owner opaque string
	413	+ * that indicates the "owner" of that open. These objects are refcounted.
	414	+ * References to it are held by each open state associated with it. This object
	415	+ * is a superset of the nfs4_stateowner struct.
	416	+ */
357	417	struct nfs4_openowner {
358	418	struct nfs4_stateowner oo_owner; /* must be first field */
359	419	struct list_head oo_perclient;
...	...	@@ -371,6 +431,12 @@
371	431	unsigned char oo_flags;
372	432	};
373	433
	434	+/*
	435	+ * Represents a generic "lockowner". Similar to an openowner. References to it
	436	+ * are held by the lock stateids that are created on its behalf. This object is
	437	+ * a superset of the nfs4_stateowner struct (or would be if it needed any extra
	438	+ * fields).
	439	+ */
374	440	struct nfs4_lockowner {
375	441	struct nfs4_stateowner lo_owner; /* must be first element */
376	442	};
...	...	@@ -385,7 +451,14 @@
385	451	return container_of(so, struct nfs4_lockowner, lo_owner);
386	452	}
387	453
388		-/* nfs4_file: a file opened by some number of (open) nfs4_stateowners. */
	454	+/*
	455	+ * nfs4_file: a file opened by some number of (open) nfs4_stateowners.
	456	+ *
	457	+ * These objects are global. nfsd only keeps one instance of a nfs4_file per
	458	+ * inode (though it may keep multiple file descriptors open per inode). These
	459	+ * are tracked in the file_hashtbl which is protected by the state_lock
	460	+ * spinlock.
	461	+ */
389	462	struct nfs4_file {
390	463	atomic_t fi_ref;
391	464	spinlock_t fi_lock;
...	...	@@ -410,7 +483,20 @@
410	483	bool fi_had_conflict;
411	484	};
412	485
413		-/* "ol" stands for "Open or Lock". Better suggestions welcome. */
	486	+/*
	487	+ * A generic struct representing either a open or lock stateid. The nfs4_client
	488	+ * holds a reference to each of these objects, and they in turn hold a
	489	+ * reference to their respective stateowners. The client's reference is
	490	+ * released in response to a close or unlock (depending on whether it's an open
	491	+ * or lock stateid) or when the client is being destroyed.
	492	+ *
	493	+ * In the case of v4.0 open stateids, these objects are preserved for a little
	494	+ * while after close in order to handle CLOSE replays. Those are eventually
	495	+ * reclaimed via a LRU scheme by the laundromat.
	496	+ *
	497	+ * This object is a superset of the nfs4_stid. "ol" stands for "Open or Lock".
	498	+ * Better suggestions welcome.
	499	+ */
414	500	struct nfs4_ol_stateid {
415	501	struct nfs4_stid st_stid; /* must be first field */
416	502	struct list_head st_perfile;