xref: /wlan-driver/qca-wifi-host-cmn/qdf/inc/qdf_flex_mem.h (revision 5113495b16420b49004c444715d2daae2066e7dc)
1 /*
2  * Copyright (c) 2018-2019 The Linux Foundation. All rights reserved.
3  * Copyright (c) 2022-2023 Qualcomm Innovation Center, Inc. All rights reserved.
4  *
5  * Permission to use, copy, modify, and/or distribute this software for
6  * any purpose with or without fee is hereby granted, provided that the
7  * above copyright notice and this permission notice appear in all
8  * copies.
9  *
10  * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11  * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12  * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13  * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14  * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15  * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16  * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17  * PERFORMANCE OF THIS SOFTWARE.
18  */
19 
20 /**
21  * DOC: qdf_flex_mem (flexibly sized memory allocator)
22  * QCA driver framework (QDF) flex mem APIs
23  *
24  * A flex memory allocator is a memory pool which not only dynamically expands,
25  * but also dynamically reduces as well. Benefits over full dynamic memory
26  * allocation are amoritized allocation cost, and reduced memory fragmentation.
27  *
28  * The allocator consists of 3 parts: the pool, segments, and items. Items are
29  * the smallest chunks of memory that are handed out via the alloc call, and
30  * are all of a uniform size. Segments are groups of items, representing the
31  * smallest amount of memory that can be dynamically allocated or freed. A pool
32  * is simply a collection of segments.
33  */
34 
35 #ifndef __QDF_FLEX_MEM_H
36 #define __QDF_FLEX_MEM_H
37 
38 #include "qdf_list.h"
39 #include "qdf_lock.h"
40 
41 #define QDF_FM_BITMAP uint32_t
42 #define QDF_FM_BITMAP_BITS (sizeof(QDF_FM_BITMAP) * 8)
43 
44 /**
45  * struct qdf_flex_mem_pool - a pool of memory segments
46  * @seg_list: the list containing the memory segments
47  * @lock: spinlock for protecting internal data structures
48  * @reduction_limit: the minimum number of segments to keep during reduction
49  * @item_size: the size of the items the pool will allocate
50  */
51 struct qdf_flex_mem_pool {
52 	qdf_list_t seg_list;
53 	struct qdf_spinlock lock;
54 	uint16_t reduction_limit;
55 	uint16_t item_size;
56 };
57 
58 /**
59  * struct qdf_flex_mem_segment - a memory pool segment
60  * @node: the list node for membership in the memory pool
61  * @dynamic: true if this segment was dynamically allocated
62  * @used_bitmap: bitmap for tracking which items in the segment are in use
63  * @bytes: raw memory for allocating items from
64  */
65 struct qdf_flex_mem_segment {
66 	qdf_list_node_t node;
67 	bool dynamic;
68 	QDF_FM_BITMAP used_bitmap;
69 	uint8_t *bytes;
70 };
71 
72 /**
73  * DEFINE_QDF_FLEX_MEM_POOL() - define a new flex mem pool with one segment
74  * @name: the name of the pool variable
75  * @size_of_item: size of the items the pool will allocate
76  * @rm_limit: min number of segments to keep during reduction
77  */
78 #define DEFINE_QDF_FLEX_MEM_POOL(name, size_of_item, rm_limit) \
79 	struct qdf_flex_mem_pool name; \
80 	uint8_t __ ## name ## _head_bytes[QDF_FM_BITMAP_BITS * (size_of_item)];\
81 	struct qdf_flex_mem_segment __ ## name ## _head = { \
82 		.node = QDF_LIST_NODE_INIT_SINGLE( \
83 			QDF_LIST_ANCHOR(name.seg_list)), \
84 		.bytes = __ ## name ## _head_bytes, \
85 	}; \
86 	struct qdf_flex_mem_pool name = { \
87 		.seg_list = QDF_LIST_INIT_SINGLE(__ ## name ## _head.node), \
88 		.reduction_limit = (rm_limit), \
89 		.item_size = (size_of_item), \
90 	}
91 
92 /**
93  * qdf_flex_mem_init() - initialize a qdf_flex_mem_pool
94  * @pool: the pool to initialize
95  *
96  * Return: None
97  */
98 void qdf_flex_mem_init(struct qdf_flex_mem_pool *pool);
99 
100 /**
101  * qdf_flex_mem_deinit() - deinitialize a qdf_flex_mem_pool
102  * @pool: the pool to deinitialize
103  *
104  * Return: None
105  */
106 void qdf_flex_mem_deinit(struct qdf_flex_mem_pool *pool);
107 
108 /**
109  * qdf_flex_mem_alloc() - logically allocate memory from the pool
110  * @pool: the pool to allocate from
111  *
112  * This function returns any unused item from any existing segment in the pool.
113  * If there are no unused items in the pool, a new segment is dynamically
114  * allocated to service the request. The size of the allocated memory is the
115  * size originally used to create the pool.
116  *
117  * Return: Point to newly allocated memory, NULL on failure
118  */
119 void *qdf_flex_mem_alloc(struct qdf_flex_mem_pool *pool);
120 
121 /**
122  * qdf_flex_mem_free() - logically frees @ptr from the pool
123  * @pool: the pool to return the memory to
124  * @ptr: a pointer received via a call to qdf_flex_mem_alloc()
125  *
126  * This function marks the item corresponding to @ptr as unused. If that item
127  * was the last used item in the segment it belongs to, and the segment was
128  * dynamically allocated, the segment will be freed.
129  *
130  * Return: None
131  */
132 void qdf_flex_mem_free(struct qdf_flex_mem_pool *pool, void *ptr);
133 
134 #endif /* __QDF_FLEX_MEM_H */
135