cpumask: documentation for cpumask_var_t

Impact: New kerneldoc comments Additional documentation added to all the alloc_cpumask and free_cpumask functions. Signed-off-by: Mike Travis <travis@sgi.com> Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> (minor additions)

cpumask: documentation for cpumask_var_t
Impact: New kerneldoc comments Additional documentation added to all the alloc_cpumask and free_cpumask functions. Signed-off-by: Mike Travis <travis@sgi.com> Signed-off-by: Rusty Russell <rusty@rustcorp.com.au> (minor additions)
Mike Travis · Rusty Russell
1 parent 7b4967c532
Showing 1 changed file with 43 additions and 0 deletions Side-by-side Diff
lib/cpumask.c
@@ -76,6 +76,20 @@
  
 /* These are not inline because of header tangles. */
 #ifdef CONFIG_CPUMASK_OFFSTACK
+/**
+ * alloc_cpumask_var_node - allocate a struct cpumask on a given node
+ * @mask: pointer to cpumask_var_t where the cpumask is returned
+ * @flags: GFP_ flags
+ *
+ * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
+ * a nop returning a constant 1 (in <linux/cpumask.h>)
+ * Returns TRUE if memory allocation succeeded, FALSE otherwise.
+ *
+ * In addition, mask will be NULL if this fails.  Note that gcc is
+ * usually smart enough to know that mask can never be NULL if
+ * CONFIG_CPUMASK_OFFSTACK=n, so does code elimination in that case
+ * too.
+ */
 bool alloc_cpumask_var_node(cpumask_var_t *mask, gfp_t flags, int node)
 {
 	if (likely(slab_is_available()))
  
  
  
@@ -97,23 +111,52 @@
 }
 EXPORT_SYMBOL(alloc_cpumask_var_node);
  
+/**
+ * alloc_cpumask_var - allocate a struct cpumask
+ * @mask: pointer to cpumask_var_t where the cpumask is returned
+ * @flags: GFP_ flags
+ *
+ * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
+ * a nop returning a constant 1 (in <linux/cpumask.h>).
+ *
+ * See alloc_cpumask_var_node.
+ */
 bool alloc_cpumask_var(cpumask_var_t *mask, gfp_t flags)
 {
 	return alloc_cpumask_var_node(mask, flags, numa_node_id());
 }
 EXPORT_SYMBOL(alloc_cpumask_var);
  
+/**
+ * alloc_bootmem_cpumask_var - allocate a struct cpumask from the bootmem arena.
+ * @mask: pointer to cpumask_var_t where the cpumask is returned
+ *
+ * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
+ * a nop returning a constant 1 (in <linux/cpumask.h>)
+ * Either returns an allocated (zero-filled) cpumask, or causes the
+ * system to panic.
+ */
 void __init alloc_bootmem_cpumask_var(cpumask_var_t *mask)
 {
 	*mask = alloc_bootmem(cpumask_size());
 }
  
+/**
+ * free_cpumask_var - frees memory allocated for a struct cpumask.
+ * @mask: cpumask to free
+ *
+ * This is safe on a NULL mask.
+ */
 void free_cpumask_var(cpumask_var_t mask)
 {
 	kfree(mask);
 }
 EXPORT_SYMBOL(free_cpumask_var);
  
+/**
+ * free_bootmem_cpumask_var - frees result of alloc_bootmem_cpumask_var
+ * @mask: cpumask to free
+ */
 void __init free_bootmem_cpumask_var(cpumask_var_t mask)
 {
 	free_bootmem((unsigned long)mask, cpumask_size());
...	...	@@ -76,6 +76,20 @@
76	76
77	77	/* These are not inline because of header tangles. */
78	78	#ifdef CONFIG_CPUMASK_OFFSTACK
	79	+/**
	80	+ * alloc_cpumask_var_node - allocate a struct cpumask on a given node
	81	+ * @mask: pointer to cpumask_var_t where the cpumask is returned
	82	+ * @flags: GFP_ flags
	83	+ *
	84	+ * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
	85	+ * a nop returning a constant 1 (in <linux/cpumask.h>)
	86	+ * Returns TRUE if memory allocation succeeded, FALSE otherwise.
	87	+ *
	88	+ * In addition, mask will be NULL if this fails. Note that gcc is
	89	+ * usually smart enough to know that mask can never be NULL if
	90	+ * CONFIG_CPUMASK_OFFSTACK=n, so does code elimination in that case
	91	+ * too.
	92	+ */
79	93	bool alloc_cpumask_var_node(cpumask_var_t *mask, gfp_t flags, int node)
80	94	{
81	95	if (likely(slab_is_available()))
82	96
83	97
84	98
...	...	@@ -97,23 +111,52 @@
97	111	}
98	112	EXPORT_SYMBOL(alloc_cpumask_var_node);
99	113
	114	+/**
	115	+ * alloc_cpumask_var - allocate a struct cpumask
	116	+ * @mask: pointer to cpumask_var_t where the cpumask is returned
	117	+ * @flags: GFP_ flags
	118	+ *
	119	+ * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
	120	+ * a nop returning a constant 1 (in <linux/cpumask.h>).
	121	+ *
	122	+ * See alloc_cpumask_var_node.
	123	+ */
100	124	bool alloc_cpumask_var(cpumask_var_t *mask, gfp_t flags)
101	125	{
102	126	return alloc_cpumask_var_node(mask, flags, numa_node_id());
103	127	}
104	128	EXPORT_SYMBOL(alloc_cpumask_var);
105	129
	130	+/**
	131	+ * alloc_bootmem_cpumask_var - allocate a struct cpumask from the bootmem arena.
	132	+ * @mask: pointer to cpumask_var_t where the cpumask is returned
	133	+ *
	134	+ * Only defined when CONFIG_CPUMASK_OFFSTACK=y, otherwise is
	135	+ * a nop returning a constant 1 (in <linux/cpumask.h>)
	136	+ * Either returns an allocated (zero-filled) cpumask, or causes the
	137	+ * system to panic.
	138	+ */
106	139	void __init alloc_bootmem_cpumask_var(cpumask_var_t *mask)
107	140	{
108	141	*mask = alloc_bootmem(cpumask_size());
109	142	}
110	143
	144	+/**
	145	+ * free_cpumask_var - frees memory allocated for a struct cpumask.
	146	+ * @mask: cpumask to free
	147	+ *
	148	+ * This is safe on a NULL mask.
	149	+ */
111	150	void free_cpumask_var(cpumask_var_t mask)
112	151	{
113	152	kfree(mask);
114	153	}
115	154	EXPORT_SYMBOL(free_cpumask_var);
116	155
	156	+/**
	157	+ * free_bootmem_cpumask_var - frees result of alloc_bootmem_cpumask_var
	158	+ * @mask: cpumask to free
	159	+ */
117	160	void __init free_bootmem_cpumask_var(cpumask_var_t mask)
118	161	{
119	162	free_bootmem((unsigned long)mask, cpumask_size());