mm: clarify mm_struct.mm_{users,count} documentation

Clarify documentation relating to mm_users and mm_count, and switch to
kernel-doc syntax.

Link: http://lkml.kernel.org/r/20161218123229.22952-4-vegard.nossum@oracle.com
Signed-off-by: Vegard Nossum <vegard.nossum@oracle.com>
Acked-by: Michal Hocko <mhocko@suse.com>
Acked-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Acked-by: David Rientjes <rientjes@google.com>
Signed-off-by: Andrew Morton <akpm@linux-foundation.org>
Signed-off-by: Linus Torvalds <torvalds@linux-foundation.org>

diff --git a/include/linux/mm_types.h b/include/linux/mm_types.h
index 808751d7b737e28cd0b933d19b6544cae85bab79..4f6d440ad78551e919cf3988d436de1b9b2a80c2 100644 (file)
--- a/include/linux/mm_types.h
+++ b/include/linux/mm_types.h
@@ -407,8 +407,27 @@ struct mm_struct {
        unsigned long task_size;                /* size of task vm space */
        unsigned long highest_vm_end;           /* highest vma end address */
        pgd_t * pgd;
-       atomic_t mm_users;                      /* How many users with user space? */
-       atomic_t mm_count;                      /* How many references to "struct mm_struct" (users count as 1) */
+
+       /**
+        * @mm_users: The number of users including userspace.
+        *
+        * Use mmget()/mmget_not_zero()/mmput() to modify. When this drops
+        * to 0 (i.e. when the task exits and there are no other temporary
+        * reference holders), we also release a reference on @mm_count
+        * (which may then free the &struct mm_struct if @mm_count also
+        * drops to 0).
+        */
+       atomic_t mm_users;
+
+       /**
+        * @mm_count: The number of references to &struct mm_struct
+        * (@mm_users count as 1).
+        *
+        * Use mmgrab()/mmdrop() to modify. When this drops to 0, the
+        * &struct mm_struct is freed.
+        */
+       atomic_t mm_count;
+
        atomic_long_t nr_ptes;                  /* PTE page table pages */
 #if CONFIG_PGTABLE_LEVELS > 2
        atomic_long_t nr_pmds;                  /* PMD page table pages */