From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from mail-wm1-f53.google.com (mail-wm1-f53.google.com [209.85.128.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id C23FD253359 for ; Sun, 14 Jun 2026 20:41:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.53 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1781469717; cv=none; b=GGganpaxFaKnCoYull2MRCpbd/06va9ETUh9bQkplBao/7sRmoYYrshn+piqp/BueD/f1tRw2brGFeJxlmYEcjC1tzuXH3RHbLx2df3Zk6aRTydArvJaYCqIa3W9gpt0sCvEEtzt2QTsqItsJUlKOm/B/UJh39eYnS02I9yjM5A= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1781469717; c=relaxed/simple; bh=ZdLXPaYDUbRiLz7f3Uuasjnjn59d9kL8Sra6lK+U/8o=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version; b=K1L038fDCglb752Dh+pSkMJ/bnClwtI/mWtAJrWjjrMi2v/vIQvsatzf7I2vaPv0GCcrANnuoe7bz7LWiqKuyooX7f/SgEwOwDGqD50YM3cSDGkCRZT2IlWwOSAgr2MEWHIuZUYr66ku1YBDHhFOmsEWGCY4y8LriCVYO5DcTqE= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=nmkqJSva; arc=none smtp.client-ip=209.85.128.53 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="nmkqJSva" Received: by mail-wm1-f53.google.com with SMTP id 5b1f17b1804b1-490ace40f4bso25280895e9.3 for ; Sun, 14 Jun 2026 13:41:55 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1781469714; x=1782074514; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:from:to:cc:subject:date:message-id:reply-to; bh=1Y3gHg3wyfp/6WbXCdcDPUbsriBCTevnaBJPpFnTrJA=; b=nmkqJSvaea2I6vkav9BXySCnZ+FSpQ9CbtKLQT4qi1LOcy+yLePj7lTPsQCoDsasKw 35IeBrl+oRrU8gfNX+fcqoNBD2KKd354bYHg0LVirtHVx3YEvvOdHISYlMnqvwh+Mngh K1WJefl9qkN40v3luMtZ2kXJctTXVlCa/sD9k3p9XyNIyeW98P/DAywZ74dUiv6rCfSW WhMv7ZybjdqSPe4KZyFb2ORa6GdJ14/QGbuWGvOlq1+qQBRFI+l3LcCzqEQCpUDz1tgI 7mlIVXD/BMkitgI9GGzjhfvEr6iR1mDjP46bCx+j+nbULyrciq8nZdc5QICmpfyhduK7 GnFg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1781469714; x=1782074514; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to; bh=1Y3gHg3wyfp/6WbXCdcDPUbsriBCTevnaBJPpFnTrJA=; b=LGwOJ00n5Fa+ifJxQ82plO13Bt7YZrrJKrsg4TofkWs9yddu0b+jg1KnwFVXual1Ku N5maRdURCwHzWYa6cz/eBR+MNAQprmG0DZiEh4YEnkaErqZdFFgieoN9feK83swkNf+L ux7dq1GFsHskWAzivB1dGoIiTkOtanPPhGiM8FPvmLxpB60hGIB8z2bY4yyPhdfkQ1sa vG2hD6ZIptmhuAGI+su9n27TLY0MfS9SexOl/mmAu3TA8mtfxpT+j4y8iZMpvXjDqyMH 0k8LUm/dvolfJgc/2Y0E9kUjYNOuu8Wdb9e1z2bmoNUDi+OxHI86TYnwyTFSc4qVLFNN mDBQ== X-Forwarded-Encrypted: i=1; AFNElJ/7lzIO0O8mHG1OjBb2Q5OSVkqNHyK48dNPBC4RoVIGqY/MuanqefaTKBUJfpP/+T31bWEU3wp05oUm+UU=@vger.kernel.org X-Gm-Message-State: AOJu0YzYOarPiPBrUNSGpwzPB+bsrgpTErs0BpK17vZRmvKP1oMZjnP8 uiHmKgCc8q9woI6F4VntfWAlVof14Vy/sMxmsnrCtZ6L9xIPVuk/g/8j X-Gm-Gg: Acq92OHbLpw1kdYuEgQY9fFxEiRR9HGaqw0skerCLGZ8wXhjxezUISvZUp2vYP7kmqK Bv0Fb4hZLf9WW+HYcaxPXFIlYs5IuN01jz8QiHKDHJhVf0OoUIC72dF/prldwO7d/8UpneAVZ/s Qkrq2F2HavSUDa6IgZmgrl7z0XGdgCyI1f/BdR992gO7R7PnIU09wmSwxr0HBHflzrNu7knOpa6 3u3DesVGLPeXT4WmM/1NQlY5rMdrqgLVD6JDW+bXFjvX7oSm2RwwLPTkyDISZMpCNVg9HaC++Jh e+DrxriMQTcNn/7xgQziNEFUHbYL4QWvqymj6gRbj/Te992CU8zQhsgSGmoPokHb9Hn7+UMJVQU cNilSAAOnj/1ywfVLsztF6QsxUl3FxHqy661tBg1YQGLGga6C51aqCH9WDgD4PcF9Ij5v0Vg5Em H/OEzV5SktxHkS5lVDXHlRez0twY7LbWONd18H53/tCB98jT158ns92W/KmgZaGaXFyuhDuwR5Z A== X-Received: by 2002:a05:600c:474f:b0:490:d946:47cf with SMTP id 5b1f17b1804b1-4922005e1c4mr96033965e9.4.1781469714006; Sun, 14 Jun 2026 13:41:54 -0700 (PDT) Received: from DESKTOP-80V9C1H (89-93-105-162.hfc.dyn.abo.bbox.fr. [89.93.105.162]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-4606f2b0c35sm28247497f8f.22.2026.06.14.13.41.53 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sun, 14 Jun 2026 13:41:53 -0700 (PDT) From: Ronan Marchal To: rafael@kernel.org Cc: pavel@kernel.org, lenb@kernel.org, linux-pm@vger.kernel.org, linux-kernel@vger.kernel.org, Ronan Marchal Subject: [PATCH] kernel/power/snapshot: Add missing kernel-doc parameter descriptions Date: Sun, 14 Jun 2026 22:41:49 +0200 Message-ID: <20260614204149.41641-1-ronanmarchal29@gmail.com> X-Mailer: git-send-email 2.53.0 Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Add missing parameter descriptions in kernel-doc comments to fix warnings reported by scripts/kernel-doc -none. Signed-off-by: Ronan Marchal --- kernel/power/snapshot.c | 62 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 58 insertions(+), 4 deletions(-) diff --git a/kernel/power/snapshot.c b/kernel/power/snapshot.c index a564650734dc..65e5839f3921 100644 --- a/kernel/power/snapshot.c +++ b/kernel/power/snapshot.c @@ -460,6 +460,11 @@ static struct rtree_node *alloc_rtree_node(gfp_t gfp_mask, int safe_needed, /** * add_rtree_block - Add a new leave node to the radix tree. + * @gfp_mask: GFP mask for the allocation. + * @safe_needed: Get pages not used before hibernation (restore only) + * @ca: Pointer to a linked list of pages ("a chain") to allocate from + * @zone: The radix tree zone bitmap whose blocks counter tracks + * the position of the next leave node to allocate. * * The leave nodes need to be allocated in order to keep the leaves * linked list in order. This is guaranteed by the zone->blocks @@ -530,10 +535,15 @@ static void free_zone_bm_rtree(struct mem_zone_bm_rtree *zone, /** * create_zone_bm_rtree - Create a radix tree for one zone. + * @gfp_mask: GFP mask for the allocation. + * @safe_needed: Get pages not used before hibernation (restore only). + * @ca: Pointer to a linked list of pages ("a chain") to allocate from. + * @start: Start PFN of the zone. + * @end: End PFN of the zone. * - * Allocated the mem_zone_bm_rtree structure and initializes it. - * This function also allocated and builds the radix tree for the - * zone. + * Allocates and initializes the mem_zone_bm_rtree structure, including + * its nodes and leaves lists. Builds the radix tree by allocating the + * number of blocks required to cover all pages in the [@start, @end] range. */ static struct mem_zone_bm_rtree *create_zone_bm_rtree(gfp_t gfp_mask, int safe_needed, @@ -568,6 +578,8 @@ static struct mem_zone_bm_rtree *create_zone_bm_rtree(gfp_t gfp_mask, /** * free_zone_bm_rtree - Free the memory of the radix tree. + * @zone: The radix tree to free. + * @clear_nosave_free: If set, clear the PageNosaveFree bit for the page. * * Free all node pages of the radix tree. The mem_zone_bm_rtree * structure itself is not freed here nor are the rtree_node @@ -680,6 +692,11 @@ static int create_mem_extents(struct list_head *list, gfp_t gfp_mask) /** * memory_bm_create - Allocate memory for a memory bitmap. + * @bm: Memory bitmap. + * @gfp_mask: GFP mask for the allocation. + * @safe_needed: Get pages not used before hibernation (restore only). + * + * Allocate memory for a memory bitmap and initialize it. */ static int memory_bm_create(struct memory_bitmap *bm, gfp_t gfp_mask, int safe_needed) @@ -723,6 +740,8 @@ static int memory_bm_create(struct memory_bitmap *bm, gfp_t gfp_mask, /** * memory_bm_free - Free memory occupied by the memory bitmap. * @bm: Memory bitmap. + * @clear_nosave_free: If set, clear the PageNosaveFree bit for the page. + * */ static void memory_bm_free(struct memory_bitmap *bm, int clear_nosave_free) { @@ -738,6 +757,10 @@ static void memory_bm_free(struct memory_bitmap *bm, int clear_nosave_free) /** * memory_bm_find_bit - Find the bit for a given PFN in a memory bitmap. + * @bm: Memory bitmap. + * @pfn: The page frame number to find. + * @addr: The address of the memory page containing the bit for @pfn. + * @bit_nr: The bit index within the page for @pfn. * * Find the bit in memory bitmap @bm that corresponds to the given PFN. * The cur.zone, cur.block and cur.node_pfn members of @bm are updated. @@ -881,6 +904,7 @@ static bool memory_bm_pfn_present(struct memory_bitmap *bm, unsigned long pfn) /* * rtree_next_node - Jump to the next leaf node. + * @bm: Memory bitmap. * * Set the position to the beginning of the next node in the * memory bitmap. This is either the next node in the current @@ -990,6 +1014,8 @@ static void memory_bm_recycle(struct memory_bitmap *bm) /** * register_nosave_region - Register a region of unsaveable memory. + * @start_pfn: The starting page frame number. + * @end_pfn: The ending page frame number. * * Register a range of page frames the contents of which should not be saved * during hibernation (to be used in the early initialization code). @@ -1307,6 +1333,8 @@ static unsigned int count_free_highmem_pages(void) /** * saveable_highmem_page - Check if a highmem page is saveable. + * @zone: The zone to which the page belongs. + * @pfn: The page frame number of the page to check. * * Determine whether a highmem page should be included in a hibernation image. * @@ -1364,6 +1392,8 @@ static unsigned int count_highmem_pages(void) /** * saveable_page - Check if the given page is saveable. + * @zone: The zone to which the page belongs. + * @pfn: The page frame number of the page to check. * * Determine whether a non-highmem page should be included in a hibernation * image. @@ -1442,6 +1472,8 @@ static inline bool do_copy_page(long *dst, long *src) /** * safe_copy_page - Copy a page in a safe way. + * @dst: The destination address to copy to. + * @s_page: The source page to copy from. * * Check if the page we are going to copy is marked as present in the kernel * page tables. This always is the case if CONFIG_DEBUG_PAGEALLOC or @@ -1688,7 +1720,10 @@ static unsigned long preallocate_image_highmem(unsigned long nr_pages) } /** - * __fraction - Compute (an approximation of) x * (multiplier / base). + * __fraction - Compute (an approximation of) x * (multiplier / base). + * @x: The value to multiply. + * @multiplier: The numerator of the fraction. + * @base: The denominator of the fraction. */ static unsigned long __fraction(u64 x, u64 multiplier, u64 base) { @@ -1984,6 +2019,7 @@ int hibernate_preallocate_memory(void) #ifdef CONFIG_HIGHMEM /** * count_pages_for_highmem - Count non-highmem pages needed for copying highmem. + * @nr_highmem: Number of highmem pages to copy. * * Compute the number of non-highmem pages that will be necessary for creating * copies of highmem pages. @@ -2005,6 +2041,11 @@ static unsigned int count_pages_for_highmem(unsigned int nr_highmem) { return 0; /** * enough_free_mem - Check if there is enough free memory for the image. + * @nr_pages: Number of non-highmem pages to copy. + * @nr_highmem: Number of highmem pages to copy. + * + * Check if there are enough free non-highmem pages available to save + * the hibernation image. */ static int enough_free_mem(unsigned int nr_pages, unsigned int nr_highmem) { @@ -2025,6 +2066,7 @@ static int enough_free_mem(unsigned int nr_pages, unsigned int nr_highmem) #ifdef CONFIG_HIGHMEM /** * get_highmem_buffer - Allocate a buffer for highmem pages. + * @safe_needed: The type of pages to allocate for the buffer. * * If there are some highmem pages in the hibernation image, we may need a * buffer to copy them and/or load their data. @@ -2037,6 +2079,8 @@ static inline int get_highmem_buffer(int safe_needed) /** * alloc_highmem_pages - Allocate some highmem pages for the image. + * @bm: Memory bitmap. + * @nr_highmem: Number of highmem pages to allocate. * * Try to allocate as many pages as needed, but if the number of free highmem * pages is less than that, allocate them all. @@ -2067,6 +2111,9 @@ static inline unsigned int alloc_highmem_pages(struct memory_bitmap *bm, /** * swsusp_alloc - Allocate memory for hibernation image. + * @copy_bm: Memory bitmap. + * @nr_pages: Number of non-highmem pages to allocate. + * @nr_highmem: Number of highmem pages to allocate. * * We first try to allocate as many highmem pages as there are * saveable highmem pages in the system. If that fails, we allocate @@ -2294,6 +2341,7 @@ static void duplicate_memory_bitmap(struct memory_bitmap *dst, /** * mark_unsafe_pages - Mark pages that were used before hibernation. + * @bm: Memory bitmap. * * Mark the pages that cannot be used for storing the image during restoration, * because they conflict with the pages that had been used before hibernation. @@ -2332,6 +2380,7 @@ static int check_header(struct swsusp_info *info) /** * load_header - Check the image header and copy the data from it. + * @info: Structure containing the image header. */ static int load_header(struct swsusp_info *info) { @@ -2485,6 +2534,8 @@ static struct page *last_highmem_page; /** * get_highmem_page_buffer - Prepare a buffer to store a highmem image page. + * @page: Pointer to the highmem image page. + * @ca: Pointer to the chain allocator structure. * * For a given highmem image page get a buffer that suspend_write_next() should * return to its caller to write to. @@ -2708,6 +2759,8 @@ static int prepare_image(struct memory_bitmap *new_bm, struct memory_bitmap *bm, /** * get_buffer - Get the address to store the next image data page. + * @bm: Memory bitmap. + * @ca: Pointer to the chain allocator structure. * * Get the address that snapshot_write_next() should return to its caller to * write to. @@ -2845,6 +2898,7 @@ int snapshot_write_next(struct snapshot_handle *handle) /** * snapshot_write_finalize - Complete the loading of a hibernation image. + * @handle: Snapshot handle structure to guide the writing. * * Must be called after the last call to snapshot_write_next() in case the last * page in the image happens to be a highmem page and its contents should be -- 2.53.0