Commit b6da9401 authored by Vlastimil Babka's avatar Vlastimil Babka
Browse files

mm, slab: add kerneldocs for common SLAB_ flags 



We have many SLAB_ flags but many are used only internally, by kunit
tests or debugging subsystems cooperating with slab, or are set
according to slab_debug boot parameter.

Create kerneldocs for the commonly used flags that may be passed to
kmem_cache_create(). SLAB_TYPESAFE_BY_RCU already had a detailed
description, so turn it to a kerneldoc. Add some details for
SLAB_ACCOUNT, SLAB_RECLAIM_ACCOUNT and SLAB_HWCACHE_ALIGN. Reference
them from the __kmem_cache_create_args() kerneldoc.

Signed-off-by: default avatarVlastimil Babka <vbabka@suse.cz>
parent b4b797d8

include/linux/slab.h

+41 −19
Original line number Diff line number Diff line
@@ -77,7 +77,17 @@ enum _slab_flag_bits { 
#define SLAB_POISON		__SLAB_FLAG_BIT(_SLAB_POISON)

/* Indicate a kmalloc slab */

#define SLAB_KMALLOC		__SLAB_FLAG_BIT(_SLAB_KMALLOC)

/* Align objs on cache lines */

/**

 * define SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries.

 *

 * Sufficiently large objects are aligned on cache line boundary. For object

 * size smaller than a half of cache line size, the alignment is on the half of

 * cache line size. In general, if object size is smaller than 1/2^n of cache

 * line size, the alignment is adjusted to 1/2^n.

 *

 * If explicit alignment is also requested by the respective

 * &struct kmem_cache_args field, the greater of both is alignments is applied.

 */

#define SLAB_HWCACHE_ALIGN	__SLAB_FLAG_BIT(_SLAB_HWCACHE_ALIGN)

/* Use GFP_DMA memory */

#define SLAB_CACHE_DMA		__SLAB_FLAG_BIT(_SLAB_CACHE_DMA)
@@ -87,8 +97,8 @@ enum _slab_flag_bits { 
#define SLAB_STORE_USER		__SLAB_FLAG_BIT(_SLAB_STORE_USER)

/* Panic if kmem_cache_create() fails */

#define SLAB_PANIC		__SLAB_FLAG_BIT(_SLAB_PANIC)

/*

 * SLAB_TYPESAFE_BY_RCU - **WARNING** READ THIS!

/**

 * define SLAB_TYPESAFE_BY_RCU - **WARNING** READ THIS!

 *

 * This delays freeing the SLAB page by a grace period, it does _NOT_

 * delay object freeing. This means that if you do kmem_cache_free()
@@ -99,6 +109,8 @@ enum _slab_flag_bits { 
 * stays valid, the trick to using this is relying on an independent

 * object validation pass. Something like:

 *

 * ::

 *

 *  begin:

 *   rcu_read_lock();

 *   obj = lockless_lookup(key);
@@ -137,7 +149,6 @@ enum _slab_flag_bits { 
 *

 * Note that SLAB_TYPESAFE_BY_RCU was originally named SLAB_DESTROY_BY_RCU.

 */

/* Defer freeing slabs to RCU */

#define SLAB_TYPESAFE_BY_RCU	__SLAB_FLAG_BIT(_SLAB_TYPESAFE_BY_RCU)

/* Trace allocations and frees */

#define SLAB_TRACE		__SLAB_FLAG_BIT(_SLAB_TRACE)
@@ -170,7 +181,12 @@ enum _slab_flag_bits { 
#else

# define SLAB_FAILSLAB		__SLAB_FLAG_UNUSED

#endif

/* Account to memcg */

/**

 * define SLAB_ACCOUNT - Account allocations to memcg.

 *

 * All object allocations from this cache will be memcg accounted, regardless of

 * __GFP_ACCOUNT being or not being passed to individual allocations.

 */

#ifdef CONFIG_MEMCG

# define SLAB_ACCOUNT		__SLAB_FLAG_BIT(_SLAB_ACCOUNT)

#else
@@ -197,7 +213,13 @@ enum _slab_flag_bits { 
#endif



/* The following flags affect the page allocator grouping pages by mobility */

/* Objects are reclaimable */

/**

 * define SLAB_RECLAIM_ACCOUNT - Objects are reclaimable.

 *

 * Use this flag for caches that have an associated shrinker. As a result, slab

 * pages are allocated with __GFP_RECLAIMABLE, which affects grouping pages by

 * mobility, and are accounted in SReclaimable counter in /proc/meminfo

 */

#ifndef CONFIG_SLUB_TINY

#define SLAB_RECLAIM_ACCOUNT	__SLAB_FLAG_BIT(_SLAB_RECLAIM_ACCOUNT)

#else

mm/slab_common.c

+13 −1
Original line number Diff line number Diff line
@@ -254,11 +254,23 @@ static struct kmem_cache *create_cache(const char *name, 
 * @object_size: The size of objects to be created in this cache.

 * @args: Additional arguments for the cache creation (see

 *        &struct kmem_cache_args).

 * @flags: See %SLAB_* flags for an explanation of individual @flags.

 * @flags: See the desriptions of individual flags. The common ones are listed

 *         in the description below.

 *

 * Not to be called directly, use the kmem_cache_create() wrapper with the same

 * parameters.

 *

 * Commonly used @flags:

 *

 * &SLAB_ACCOUNT - Account allocations to memcg.

 *

 * &SLAB_HWCACHE_ALIGN - Align objects on cache line boundaries.

 *

 * &SLAB_RECLAIM_ACCOUNT - Objects are reclaimable.

 *

 * &SLAB_TYPESAFE_BY_RCU - Slab page (not individual objects) freeing delayed

 * by a grace period - see the full description before using.

 *

 * Context: Cannot be called within a interrupt, but can be interrupted.

 *

 * Return: a pointer to the cache on success, NULL on failure.