forked from torvalds/linux
-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
lib/stackdepot: move documentation comments to stackdepot.h
Move all interface- and usage-related documentation comments to include/linux/stackdepot.h. It makes sense to have them in the header where they are available to the interface users. [[email protected]: grammar fix, per Alexander] Link: https://lkml.kernel.org/r/fbfee41495b306dd8881f9b1c1b80999c885e82f.1676063693.git.andreyknvl@google.com Signed-off-by: Andrey Konovalov <[email protected]> Reviewed-by: Alexander Potapenko <[email protected]> Signed-off-by: Andrew Morton <[email protected]>
- Loading branch information
Showing
2 changed files
with
87 additions
and
87 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,6 +2,17 @@ | |
| /* | ||
| * Stack depot - a stack trace storage that avoids duplication. | ||
| * | ||
| * Stack depot is intended to be used by subsystems that need to store and | ||
| * later retrieve many potentially duplicated stack traces without wasting | ||
| * memory. | ||
| * | ||
| * For example, KASAN needs to save allocation and free stack traces for each | ||
| * object. Storing two stack traces per object requires a lot of memory (e.g. | ||
| * SLUB_DEBUG needs 256 bytes per object for that). Since allocation and free | ||
| * stack traces often repeat, using stack depot allows to save about 100x space. | ||
| * | ||
| * Stack traces are never removed from the stack depot. | ||
| * | ||
| * Author: Alexander Potapenko <[email protected]> | ||
| * Copyright (C) 2016 Google, Inc. | ||
| * | ||
|
|
@@ -57,24 +68,100 @@ static inline void stack_depot_request_early_init(void) { } | |
| static inline int stack_depot_early_init(void) { return 0; } | ||
| #endif | ||
|
|
||
| /** | ||
| * __stack_depot_save - Save a stack trace to stack depot | ||
| * | ||
| * @entries: Pointer to the stack trace | ||
| * @nr_entries: Number of frames in the stack | ||
| * @alloc_flags: Allocation GFP flags | ||
| * @can_alloc: Allocate stack pools (increased chance of failure if false) | ||
| * | ||
| * Saves a stack trace from @entries array of size @nr_entries. If @can_alloc is | ||
| * %true, stack depot can replenish the stack pools in case no space is left | ||
| * (allocates using GFP flags of @alloc_flags). If @can_alloc is %false, avoids | ||
| * any allocations and fails if no space is left to store the stack trace. | ||
| * | ||
| * If the provided stack trace comes from the interrupt context, only the part | ||
| * up to the interrupt entry is saved. | ||
| * | ||
| * Context: Any context, but setting @can_alloc to %false is required if | ||
| * alloc_pages() cannot be used from the current context. Currently | ||
| * this is the case for contexts where neither %GFP_ATOMIC nor | ||
| * %GFP_NOWAIT can be used (NMI, raw_spin_lock). | ||
| * | ||
| * Return: Handle of the stack struct stored in depot, 0 on failure | ||
| */ | ||
| depot_stack_handle_t __stack_depot_save(unsigned long *entries, | ||
| unsigned int nr_entries, | ||
| gfp_t gfp_flags, bool can_alloc); | ||
|
|
||
| /** | ||
| * stack_depot_save - Save a stack trace to stack depot | ||
| * | ||
| * @entries: Pointer to the stack trace | ||
| * @nr_entries: Number of frames in the stack | ||
| * @alloc_flags: Allocation GFP flags | ||
| * | ||
| * Context: Contexts where allocations via alloc_pages() are allowed. | ||
| * See __stack_depot_save() for more details. | ||
| * | ||
| * Return: Handle of the stack trace stored in depot, 0 on failure | ||
| */ | ||
| depot_stack_handle_t stack_depot_save(unsigned long *entries, | ||
| unsigned int nr_entries, gfp_t gfp_flags); | ||
|
|
||
| /** | ||
| * stack_depot_fetch - Fetch a stack trace from stack depot | ||
| * | ||
| * @handle: Stack depot handle returned from stack_depot_save() | ||
| * @entries: Pointer to store the address of the stack trace | ||
| * | ||
| * Return: Number of frames for the fetched stack | ||
| */ | ||
| unsigned int stack_depot_fetch(depot_stack_handle_t handle, | ||
| unsigned long **entries); | ||
|
|
||
| /** | ||
| * stack_depot_print - Print a stack trace from stack depot | ||
| * | ||
| * @stack: Stack depot handle returned from stack_depot_save() | ||
| */ | ||
| void stack_depot_print(depot_stack_handle_t stack); | ||
|
|
||
| /** | ||
| * stack_depot_snprint - Print a stack trace from stack depot into a buffer | ||
| * | ||
| * @handle: Stack depot handle returned from stack_depot_save() | ||
| * @buf: Pointer to the print buffer | ||
| * @size: Size of the print buffer | ||
| * @spaces: Number of leading spaces to print | ||
| * | ||
| * Return: Number of bytes printed | ||
| */ | ||
| int stack_depot_snprint(depot_stack_handle_t handle, char *buf, size_t size, | ||
| int spaces); | ||
|
|
||
| /** | ||
| * stack_depot_set_extra_bits - Set extra bits in a stack depot handle | ||
| * | ||
| * @handle: Stack depot handle returned from stack_depot_save() | ||
| * @extra_bits: Value to set the extra bits | ||
| * | ||
| * Return: Stack depot handle with extra bits set | ||
| * | ||
| * Stack depot handles have a few unused bits, which can be used for storing | ||
| * user-specific information. These bits are transparent to the stack depot. | ||
| */ | ||
| depot_stack_handle_t __must_check stack_depot_set_extra_bits( | ||
| depot_stack_handle_t handle, unsigned int extra_bits); | ||
|
|
||
| /** | ||
| * stack_depot_get_extra_bits - Retrieve extra bits from a stack depot handle | ||
| * | ||
| * @handle: Stack depot handle with extra bits saved | ||
| * | ||
| * Return: Extra bits retrieved from the stack depot handle | ||
| */ | ||
| unsigned int stack_depot_get_extra_bits(depot_stack_handle_t handle); | ||
|
|
||
| #endif | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,21 +2,10 @@ | |
| /* | ||
| * Stack depot - a stack trace storage that avoids duplication. | ||
| * | ||
| * Stack depot is intended to be used by subsystems that need to store and | ||
| * later retrieve many potentially duplicated stack traces without wasting | ||
| * memory. | ||
| * | ||
| * For example, KASAN needs to save allocation and free stack traces for each | ||
| * object. Storing two stack traces per object requires a lot of memory (e.g. | ||
| * SLUB_DEBUG needs 256 bytes per object for that). Since allocation and free | ||
| * stack traces often repeat, using stack depot allows to save about 100x space. | ||
| * | ||
| * Internally, stack depot maintains a hash table of unique stacktraces. The | ||
| * stack traces themselves are stored contiguously one after another in a set | ||
| * of separate page allocations. | ||
| * | ||
| * Stack traces are never removed from stack depot. | ||
| * | ||
| * Author: Alexander Potapenko <[email protected]> | ||
| * Copyright (C) 2016 Google, Inc. | ||
| * | ||
|
|
@@ -360,29 +349,6 @@ static inline struct stack_record *find_stack(struct stack_record *bucket, | |
| return NULL; | ||
| } | ||
|
|
||
| /** | ||
| * __stack_depot_save - Save a stack trace to stack depot | ||
| * | ||
| * @entries: Pointer to the stack trace | ||
| * @nr_entries: Number of frames in the stack | ||
| * @alloc_flags: Allocation GFP flags | ||
| * @can_alloc: Allocate stack pools (increased chance of failure if false) | ||
| * | ||
| * Saves a stack trace from @entries array of size @nr_entries. If @can_alloc is | ||
| * %true, stack depot can replenish the stack pools in case no space is left | ||
| * (allocates using GFP flags of @alloc_flags). If @can_alloc is %false, avoids | ||
| * any allocations and fails if no space is left to store the stack trace. | ||
| * | ||
| * If the provided stack trace comes from the interrupt context, only the part | ||
| * up to the interrupt entry is saved. | ||
| * | ||
| * Context: Any context, but setting @can_alloc to %false is required if | ||
| * alloc_pages() cannot be used from the current context. Currently | ||
| * this is the case for contexts where neither %GFP_ATOMIC nor | ||
| * %GFP_NOWAIT can be used (NMI, raw_spin_lock). | ||
| * | ||
| * Return: Handle of the stack struct stored in depot, 0 on failure | ||
| */ | ||
| depot_stack_handle_t __stack_depot_save(unsigned long *entries, | ||
| unsigned int nr_entries, | ||
| gfp_t alloc_flags, bool can_alloc) | ||
|
|
@@ -477,18 +443,6 @@ depot_stack_handle_t __stack_depot_save(unsigned long *entries, | |
| } | ||
| EXPORT_SYMBOL_GPL(__stack_depot_save); | ||
|
|
||
| /** | ||
| * stack_depot_save - Save a stack trace to stack depot | ||
| * | ||
| * @entries: Pointer to the stack trace | ||
| * @nr_entries: Number of frames in the stack | ||
| * @alloc_flags: Allocation GFP flags | ||
| * | ||
| * Context: Contexts where allocations via alloc_pages() are allowed. | ||
| * See __stack_depot_save() for more details. | ||
| * | ||
| * Return: Handle of the stack trace stored in depot, 0 on failure | ||
| */ | ||
| depot_stack_handle_t stack_depot_save(unsigned long *entries, | ||
| unsigned int nr_entries, | ||
| gfp_t alloc_flags) | ||
|
|
@@ -497,14 +451,6 @@ depot_stack_handle_t stack_depot_save(unsigned long *entries, | |
| } | ||
| EXPORT_SYMBOL_GPL(stack_depot_save); | ||
|
|
||
| /** | ||
| * stack_depot_fetch - Fetch a stack trace from stack depot | ||
| * | ||
| * @handle: Stack depot handle returned from stack_depot_save() | ||
| * @entries: Pointer to store the address of the stack trace | ||
| * | ||
| * Return: Number of frames for the fetched stack | ||
| */ | ||
| unsigned int stack_depot_fetch(depot_stack_handle_t handle, | ||
| unsigned long **entries) | ||
| { | ||
|
|
@@ -537,11 +483,6 @@ unsigned int stack_depot_fetch(depot_stack_handle_t handle, | |
| } | ||
| EXPORT_SYMBOL_GPL(stack_depot_fetch); | ||
|
|
||
| /** | ||
| * stack_depot_print - Print a stack trace from stack depot | ||
| * | ||
| * @stack: Stack depot handle returned from stack_depot_save() | ||
| */ | ||
| void stack_depot_print(depot_stack_handle_t stack) | ||
| { | ||
| unsigned long *entries; | ||
|
|
@@ -553,16 +494,6 @@ void stack_depot_print(depot_stack_handle_t stack) | |
| } | ||
| EXPORT_SYMBOL_GPL(stack_depot_print); | ||
|
|
||
| /** | ||
| * stack_depot_snprint - Print a stack trace from stack depot into a buffer | ||
| * | ||
| * @handle: Stack depot handle returned from stack_depot_save() | ||
| * @buf: Pointer to the print buffer | ||
| * @size: Size of the print buffer | ||
| * @spaces: Number of leading spaces to print | ||
| * | ||
| * Return: Number of bytes printed | ||
| */ | ||
| int stack_depot_snprint(depot_stack_handle_t handle, char *buf, size_t size, | ||
| int spaces) | ||
| { | ||
|
|
@@ -575,17 +506,6 @@ int stack_depot_snprint(depot_stack_handle_t handle, char *buf, size_t size, | |
| } | ||
| EXPORT_SYMBOL_GPL(stack_depot_snprint); | ||
|
|
||
| /** | ||
| * stack_depot_set_extra_bits - Set extra bits in a stack depot handle | ||
| * | ||
| * @handle: Stack depot handle returned from stack_depot_save() | ||
| * @extra_bits: Value to set the extra bits | ||
| * | ||
| * Return: Stack depot handle with extra bits set | ||
| * | ||
| * Stack depot handles have a few unused bits, which can be used for storing | ||
| * user-specific information. These bits are transparent to the stack depot. | ||
| */ | ||
| depot_stack_handle_t __must_check stack_depot_set_extra_bits( | ||
| depot_stack_handle_t handle, unsigned int extra_bits) | ||
| { | ||
|
|
@@ -600,13 +520,6 @@ depot_stack_handle_t __must_check stack_depot_set_extra_bits( | |
| } | ||
| EXPORT_SYMBOL(stack_depot_set_extra_bits); | ||
|
|
||
| /** | ||
| * stack_depot_get_extra_bits - Retrieve extra bits from a stack depot handle | ||
| * | ||
| * @handle: Stack depot handle with extra bits saved | ||
| * | ||
| * Return: Extra bits retrieved from the stack depot handle | ||
| */ | ||
| unsigned int stack_depot_get_extra_bits(depot_stack_handle_t handle) | ||
| { | ||
| union handle_parts parts = { .handle = handle }; | ||
|
|
||