Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757097AbYFCB65 (ORCPT ); Mon, 2 Jun 2008 21:58:57 -0400 Received: (majordomo@vger.kernel.org) by vger.kernel.org id S1753944AbYFCB6T (ORCPT ); Mon, 2 Jun 2008 21:58:19 -0400 Received: from saeurebad.de ([85.214.36.134]:39469 "EHLO saeurebad.de" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1753714AbYFCB6R (ORCPT ); Mon, 2 Jun 2008 21:58:17 -0400 X-Mailbox-Line: From hannes@saeurebad.de Tue Jun 3 02:53:03 2008 Message-Id: <20080603005302.897705574@saeurebad.de> References: <20080603005017.593345596@saeurebad.de> User-Agent: quilt/0.46-1 Date: Tue, 03 Jun 2008 02:50:20 +0200 From: Johannes Weiner To: Andrew Morton Cc: Ingo Molnar , Yinghai Lu , Andi Kleen , Yasunori Goto , linux-kernel@vger.kernel.org Subject: [PATCH -mm 03/14] bootmem: add documentation to API functions Content-Disposition: inline; filename=bootmem-document-api.patch X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.1.3 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 8237 Lines: 268 Signed-off-by: Johannes Weiner --- mm/bootmem.c | 150 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 149 insertions(+), 1 deletion(-) --- a/mm/bootmem.c +++ b/mm/bootmem.c @@ -47,7 +47,10 @@ static unsigned long __init get_mapsize( return ALIGN(mapsize, sizeof(long)); } -/* return the number of _pages_ that will be allocated for the boot bitmap */ +/** + * bootmem_bootmap_pages - calculate bitmap size in pages + * @pages: number of pages the bitmap has to represent + */ unsigned long __init bootmem_bootmap_pages(unsigned long pages) { unsigned long mapsize; @@ -104,12 +107,28 @@ static unsigned long __init init_bootmem return mapsize; } +/** + * init_bootmem_node - register a node as boot memory + * @pgdat: node to register + * @freepfn: pfn where the bitmap for this node is to be placed + * @startpfn: first pfn on the node + * @endpfn: first pfn after the node + * + * Returns the number of bytes needed to hold the bitmap for this node. + */ unsigned long __init init_bootmem_node(pg_data_t *pgdat, unsigned long freepfn, unsigned long startpfn, unsigned long endpfn) { return init_bootmem_core(pgdat->bdata, freepfn, startpfn, endpfn); } +/** + * init_bootmem - register boot memory + * @start: pfn where the bitmap is to be placed + * @pages: number of available physical pages + * + * Returns the number of bytes needed to hold the bitmap. + */ unsigned long __init init_bootmem(unsigned long start, unsigned long pages) { max_low_pfn = pages; @@ -182,12 +201,23 @@ static unsigned long __init free_all_boo return count; } +/** + * free_all_bootmem_node - release a node's free pages to the buddy allocator + * @pgdat: node to be released + * + * Returns the number of pages actually released. + */ unsigned long __init free_all_bootmem_node(pg_data_t *pgdat) { register_page_bootmem_info_node(pgdat); return free_all_bootmem_core(pgdat->bdata); } +/** + * free_all_bootmem - release free pages to the buddy allocator + * + * Returns the number of pages actually released. + */ unsigned long __init free_all_bootmem(void) { return free_all_bootmem_core(NODE_DATA(0)->bdata); @@ -231,12 +261,32 @@ static void __init free_bootmem_core(boo } } +/** + * free_bootmem_node - mark a page range as usable + * @pgdat: node the range resides on + * @physaddr: starting address of the range + * @size: size of the range in bytes + * + * Partial pages will be considered reserved and left as they are. + * + * Only physical pages that actually reside on @pgdat are marked. + */ void __init free_bootmem_node(pg_data_t *pgdat, unsigned long physaddr, unsigned long size) { free_bootmem_core(pgdat->bdata, physaddr, size); } +/** + * free_bootmem - mark a page range as usable + * @addr: starting address of the range + * @size: size of the range in bytes + * + * Partial pages will be considered reserved and left as they are. + * + * All physical pages within the range are marked, no matter what + * node they reside on. + */ void __init free_bootmem(unsigned long addr, unsigned long size) { bootmem_data_t *bdata; @@ -319,6 +369,17 @@ static void __init reserve_bootmem_core( } } +/** + * reserve_bootmem_node - mark a page range as reserved + * @pgdat: node the range resides on + * @physaddr: starting address of the range + * @size: size of the range in bytes + * @flags: reservation flags (see linux/bootmem.h) + * + * Partial pages will be reserved. + * + * Only physical pages that actually reside on @pgdat are marked. + */ void __init reserve_bootmem_node(pg_data_t *pgdat, unsigned long physaddr, unsigned long size, int flags) { @@ -331,6 +392,17 @@ void __init reserve_bootmem_node(pg_data } #ifndef CONFIG_HAVE_ARCH_BOOTMEM_NODE +/** + * reserve_bootmem - mark a page range as usable + * @addr: starting address of the range + * @size: size of the range in bytes + * @flags: reservation flags (see linux/bootmem.h) + * + * Partial pages will be reserved. + * + * All physical pages within the range are marked, no matter what + * node they reside on. + */ int __init reserve_bootmem(unsigned long addr, unsigned long size, int flags) { @@ -499,6 +571,19 @@ found: return ret; } +/** + * __alloc_bootmem_nopanic - allocate boot memory without panicking + * @size: size of the request in bytes + * @align: alignment of the region + * @goal: preferred starting address of the region + * + * The goal is dropped if it can not be satisfied and the allocation will + * fall back to memory below @goal. + * + * Allocation may happen on any node in the system. + * + * Returns NULL on failure. + */ void * __init __alloc_bootmem_nopanic(unsigned long size, unsigned long align, unsigned long goal) { @@ -513,6 +598,19 @@ void * __init __alloc_bootmem_nopanic(un return NULL; } +/** + * __alloc_bootmem - allocate boot memory + * @size: size of the request in bytes + * @align: alignment of the region + * @goal: preferred starting address of the region + * + * The goal is dropped if it can not be satisfied and the allocation will + * fall back to memory below @goal. + * + * Allocation may happen on any node in the system. + * + * The function panics if the request can not be satisfied. + */ void * __init __alloc_bootmem(unsigned long size, unsigned long align, unsigned long goal) { @@ -532,6 +630,19 @@ void * __init __alloc_bootmem(unsigned l #define ARCH_LOW_ADDRESS_LIMIT 0xffffffffUL #endif +/** + * __alloc_bootmem_low - allocate low boot memory + * @size: size of the request in bytes + * @align: alignment of the region + * @goal: preferred starting address of the region + * + * The goal is dropped if it can not be satisfied and the allocation will + * fall back to memory below @goal. + * + * Allocation may happen on any node in the system. + * + * The function panics if the request can not be satisfied. + */ void * __init __alloc_bootmem_low(unsigned long size, unsigned long align, unsigned long goal) { @@ -553,6 +664,21 @@ void * __init __alloc_bootmem_low(unsign return NULL; } +/** + * __alloc_bootmem_node - allocate boot memory from a specific node + * @pgdat: node to allocate from + * @size: size of the request in bytes + * @align: alignment of the region + * @goal: preferred starting address of the region + * + * The goal is dropped if it can not be satisfied and the allocation will + * fall back to memory below @goal. + * + * Allocation may fall back to any node in the system if the specified node + * can not hold the requested memory. + * + * The function panics if the request can not be satisfied. + */ void * __init __alloc_bootmem_node(pg_data_t *pgdat, unsigned long size, unsigned long align, unsigned long goal) { @@ -565,6 +691,21 @@ void * __init __alloc_bootmem_node(pg_da return __alloc_bootmem(size, align, goal); } +/** + * __alloc_bootmem_low_node - allocate low boot memory from a specific node + * @pgdat: node to allocate from + * @size: size of the request in bytes + * @align: alignment of the region + * @goal: preferred starting address of the region + * + * The goal is dropped if it can not be satisfied and the allocation will + * fall back to memory below @goal. + * + * Allocation may fall back to any node in the system if the specified node + * can not hold the requested memory. + * + * The function panics if the request can not be satisfied. + */ void * __init __alloc_bootmem_low_node(pg_data_t *pgdat, unsigned long size, unsigned long align, unsigned long goal) { @@ -573,6 +714,13 @@ void * __init __alloc_bootmem_low_node(p } #ifdef CONFIG_SPARSEMEM +/** + * alloc_bootmem_section - allocate boot memory from a specific section + * @size: size of the request in bytes + * @section_nr: sparse map section to allocate from + * + * Return NULL on failure. + */ void * __init alloc_bootmem_section(unsigned long size, unsigned long section_nr) { -- -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/