[PATCH] cred: clarify usage of get_cred_rcu()

[Alice Ryhl <aliceryhl@google.com>]

After being confused by looking at get_cred() and get_cred_rcu(), I
figured out what's going on. Thus, add some comments to clarify how
get_cred_rcu() works for the benefit of others looking in the future.

Note that in principle we could add an assertion that non_rcu is zero in
the failure path of atomic_long_inc_not_zero().

Signed-off-by: Alice Ryhl <aliceryhl@google.com>
---
 include/linux/cred.h | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/include/linux/cred.h b/include/linux/cred.h
index ed1609d78cd7..95dcf5e967c7 100644
--- a/include/linux/cred.h
+++ b/include/linux/cred.h
@@ -213,32 +213,50 @@ * get_cred_many - Get references on a set of credentials
 static inline const struct cred *get_cred_many(const struct cred *cred, int nr)
 {
 	struct cred *nonconst_cred = (struct cred *) cred;
 	if (!cred)
 		return cred;
 	nonconst_cred->non_rcu = 0;
 	atomic_long_add(nr, &nonconst_cred->usage);
 	return cred;
 }
 
 /*
  * get_cred - Get a reference on a set of credentials
  * @cred: The credentials to reference
  *
  * Get a reference on the specified set of credentials.  The caller must
  * release the reference.  If %NULL is passed, it is returned with no action.
  *
  * This is used to deal with a committed set of credentials.
  */
 static inline const struct cred *get_cred(const struct cred *cred)
 {
 	return get_cred_many(cred, 1);
 }
 
+/*
+ * get_cred_rcu - Get a reference on a set of credentials under rcu
+ * @cred: The credentials to reference
+ *
+ * Get a reference on the specified set of credentials, or %NULL if the last
+ * refcount has already been put.
+ *
+ * This is used to obtain a reference under an rcu read lock.
+ */
 static inline const struct cred *get_cred_rcu(const struct cred *cred)
 {
 	struct cred *nonconst_cred = (struct cred *) cred;
 	if (!cred)
 		return NULL;
 	if (!atomic_long_inc_not_zero(&nonconst_cred->usage))
 		return NULL;
+	/*
+	 * If non_rcu is not already zero, then this call to get_cred_rcu() is
+	 * probably wrong because if 'usage' goes to zero prior to this call,
+	 * then get_cred_rcu() assumes it is freed with rcu.
+	 *
+	 * However, an exception to this is using get_cred_rcu() in cases where
+	 * get_cred() would have been okay. To support that case, we do not
+	 * check non_rcu and set it to zero regardless.
+	 */
 	nonconst_cred->non_rcu = 0;
 	return cred;
 }
-- 
2.53.0.345.g96ddfc5eaa-goog