Skip to contentSkip to conversation

Improve alloc_percpu: documentation

PATCH In review Rusty Russell 1 participant 1 message Nov 17, 2008

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 5/7 Improve alloc_percpu: documentation

Since we can now endorse this interface without wincing, we should
document it. Nothing has changed API-wise, but it's a nice cleanup.

Cc Christoph Lameter <[email protected]>
---
 include/asm-generic/percpu.h |    8 ++++++++
 include/linux/percpu.h       |   10 ++++++++++
 mm/allocpercpu.c             |   13 +++++++++++++
 3 files changed, 31 insertions(+)
include/asm-generic/percpu.h +8 -0
diff -r cf4fb53a413e include/asm-generic/percpu.h
@@ -61,6 +61,14 @@
 	(*SHIFT_PERCPU_PTR(&per_cpu_var(var), __my_cpu_offset))
 
 /* Use RELOC_HIDE: some arch's SHIFT_PERCPU_PTR really want an identifier. */
+/**
+ * per_cpu_ptr - get a pointer to a particular cpu's allocated memory
+ * @ptr: the pointer returned from alloc_percpu
+ * @cpu: the cpu whose memory you want to access
+ *
+ * Similar to per_cpu(), except for dynamic memory.
+ * cpu_possible(@cpu) must be true.
+ */
 #define per_cpu_ptr(ptr, cpu) \
 	RELOC_HIDE((ptr), (per_cpu_offset(cpu)))
 
include/linux/percpu.h +10 -0
diff -r cf4fb53a413e include/linux/percpu.h
@@ -72,6 +72,16 @@
 }
 #endif /* CONFIG_SMP */
 
+/**
+ * alloc_percpu - allocate memory on every possible cpu.
+ * @type: the type to allocate
+ *
+ * Allocates memory for use with per_cpu_ptr/get_cpu_ptr/__get_cpu_ptr.
+ * The memory is always zeroed.  Returns NULL on failure.
+ *
+ * Note that percpu memory is a limited resource; it's usually used for small
+ * allocations.
+ */
 #define alloc_percpu(type) \
 	(type *)__alloc_percpu(sizeof(type), __alignof__(type))
 
mm/allocpercpu.c +13 -0
diff -r cf4fb53a413e mm/allocpercpu.c
@@ -45,6 +45,13 @@
 	return val;
 }
 
+/**
+ * __alloc_percpu - allocate dynamic percpu memory
+ * @size: bytes to allocate
+ * @align: bytes to align (< PAGE_SIZE)
+ *
+ * See alloc_percpu().
+ */
 void *__alloc_percpu(unsigned long size, unsigned long align)
 {
 	unsigned long extra;
@@ -91,6 +98,12 @@
 }
 EXPORT_SYMBOL_GPL(__alloc_percpu);
 
+/**
+ * free_percpu - free memory allocated with alloc_percpu.
+ * @pcpuptr: the pointer returned from alloc_percpu.
+ *
+ * Like kfree(), the argument can be NULL.
+ */
 void free_percpu(void *freeme)
 {
 	unsigned int i;