1*5113495bSYour Name /*
2*5113495bSYour Name * Copyright (c) 2018 The Linux Foundation. All rights reserved.
3*5113495bSYour Name * Copyright (c) 2022-2024 Qualcomm Innovation Center, Inc. All rights reserved.
4*5113495bSYour Name *
5*5113495bSYour Name * Permission to use, copy, modify, and/or distribute this software for
6*5113495bSYour Name * any purpose with or without fee is hereby granted, provided that the
7*5113495bSYour Name * above copyright notice and this permission notice appear in all
8*5113495bSYour Name * copies.
9*5113495bSYour Name *
10*5113495bSYour Name * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL
11*5113495bSYour Name * WARRANTIES WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED
12*5113495bSYour Name * WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE
13*5113495bSYour Name * AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
14*5113495bSYour Name * DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR
15*5113495bSYour Name * PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
16*5113495bSYour Name * TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
17*5113495bSYour Name * PERFORMANCE OF THIS SOFTWARE.
18*5113495bSYour Name */
19*5113495bSYour Name
20*5113495bSYour Name /**
21*5113495bSYour Name * DOC: qdf_talloc.h - Public APIs for t(ree) alloc(ate) memory management
22*5113495bSYour Name *
23*5113495bSYour Name * These APIs allocate memory like malloc, but track those allocations via a
24*5113495bSYour Name * parent-child relationship, or tree. If the parent is freed while it still has
25*5113495bSYour Name * children, a panic will be triggered. This effectively gives you the ability
26*5113495bSYour Name * to limit the lifetime of an allocation by ensuring the child allocation
27*5113495bSYour Name * lifetime will be strictly less than the parent allocation lifetime.
28*5113495bSYour Name */
29*5113495bSYour Name
30*5113495bSYour Name #ifndef __QDF_TALLOC_H
31*5113495bSYour Name #define __QDF_TALLOC_H
32*5113495bSYour Name
33*5113495bSYour Name #include "i_qdf_talloc.h"
34*5113495bSYour Name #include "qdf_status.h"
35*5113495bSYour Name
36*5113495bSYour Name /**
37*5113495bSYour Name * qdf_talloc() - t(ree) alloc(ate) memory
38*5113495bSYour Name * @parent: the parent memory of the new allocation
39*5113495bSYour Name * @size: requested size of the newly allocated memory
40*5113495bSYour Name *
41*5113495bSYour Name * Return: pointer to the newly allocated memory
42*5113495bSYour Name */
43*5113495bSYour Name #define qdf_talloc(parent, size) \
44*5113495bSYour Name qdf_talloc_fl(parent, size, __func__, __LINE__)
45*5113495bSYour Name
46*5113495bSYour Name /**
47*5113495bSYour Name * qdf_talloc_type() - t(ree) alloc(ate) memory for a type
48*5113495bSYour Name * @parent: the parent memory of the new allocation
49*5113495bSYour Name * @cursor: pointer to the type of memory to allocate
50*5113495bSYour Name *
51*5113495bSYour Name * This API automatically determines the correct size needed or an allocation
52*5113495bSYour Name * based on the type of @cursor. If you need to allocate an arbitrary number
53*5113495bSYour Name * of bytes, use qdf_talloc() instead.
54*5113495bSYour Name *
55*5113495bSYour Name * Return: pointer to the newly allocated memory
56*5113495bSYour Name */
57*5113495bSYour Name #define qdf_talloc_type(parent, cursor) \
58*5113495bSYour Name qdf_talloc(parent, sizeof(*(cursor)))
59*5113495bSYour Name
60*5113495bSYour Name /**
61*5113495bSYour Name * qdf_talloc_fl() - t(ree) alloc(ate) memory with function and line info
62*5113495bSYour Name * @parent: the parent memory of the new allocation
63*5113495bSYour Name * @size: requested size of the newly allocated memory
64*5113495bSYour Name * @func: name of the function requesting the allocation
65*5113495bSYour Name * @line: line number of the call site in @func
66*5113495bSYour Name *
67*5113495bSYour Name * Return: pointer to the newly allocated memory
68*5113495bSYour Name */
69*5113495bSYour Name #define qdf_talloc_fl(parent, size, func, line) \
70*5113495bSYour Name __qdf_talloc_fl(parent, size, func, line)
71*5113495bSYour Name
72*5113495bSYour Name /**
73*5113495bSYour Name * qdf_tfree() - free memory allocated using the *_talloc() function family
74*5113495bSYour Name * @ptr: double point to memory to free, set to NULL
75*5113495bSYour Name *
76*5113495bSYour Name * Return: None
77*5113495bSYour Name */
78*5113495bSYour Name #define qdf_tfree(ptr) \
79*5113495bSYour Name qdf_tfree_fl(ptr, __func__, __LINE__)
80*5113495bSYour Name
81*5113495bSYour Name /**
82*5113495bSYour Name * qdf_tfree_fl() - free memory allocated using the *_talloc() function family
83*5113495bSYour Name * with function and line info
84*5113495bSYour Name * @ptr: pointer to memory to free
85*5113495bSYour Name * @func: name of the function requesting the free
86*5113495bSYour Name * @line: line number of the call site in @func
87*5113495bSYour Name *
88*5113495bSYour Name * Return: None
89*5113495bSYour Name */
90*5113495bSYour Name #define qdf_tfree_fl(ptr, func, line) \
91*5113495bSYour Name do { \
92*5113495bSYour Name __qdf_tfree_fl(ptr, func, line); \
93*5113495bSYour Name ptr = (void *)1; \
94*5113495bSYour Name } while (false)
95*5113495bSYour Name
96*5113495bSYour Name /**
97*5113495bSYour Name * qdf_talloc_assert_no_children() - assert @parent has not child allocations
98*5113495bSYour Name * @parent: the parent memory pointer to check
99*5113495bSYour Name *
100*5113495bSYour Name * Return: None
101*5113495bSYour Name */
102*5113495bSYour Name #define qdf_talloc_assert_no_children(parent) \
103*5113495bSYour Name qdf_talloc_assert_no_children_fl(parent, __func__, __LINE__)
104*5113495bSYour Name
105*5113495bSYour Name #ifdef WLAN_TALLOC_DEBUG
106*5113495bSYour Name
107*5113495bSYour Name /**
108*5113495bSYour Name * qdf_talloc_feature_init() - initialize the QDF talloc feature
109*5113495bSYour Name *
110*5113495bSYour Name * Must be called before allocating memory via a qdf_talloc API.
111*5113495bSYour Name *
112*5113495bSYour Name * Return: None
113*5113495bSYour Name */
114*5113495bSYour Name QDF_STATUS qdf_talloc_feature_init(void);
115*5113495bSYour Name
116*5113495bSYour Name /**
117*5113495bSYour Name * qdf_talloc_feature_deinit() - deinitialize the QDF talloc feature
118*5113495bSYour Name *
119*5113495bSYour Name * Memory must not be allocated via a qdf_talloc API after this is called. This
120*5113495bSYour Name * API asserts that the parent/child relationship table is empty in order to
121*5113495bSYour Name * catch memory leaks.
122*5113495bSYour Name *
123*5113495bSYour Name * Return: None
124*5113495bSYour Name */
125*5113495bSYour Name void qdf_talloc_feature_deinit(void);
126*5113495bSYour Name
127*5113495bSYour Name void *__qdf_talloc_fl(const void *parent, const size_t size,
128*5113495bSYour Name const char *func, const uint16_t line);
129*5113495bSYour Name
130*5113495bSYour Name void __qdf_tfree_fl(void *ptr, const char *func, const uint16_t line);
131*5113495bSYour Name
132*5113495bSYour Name /**
133*5113495bSYour Name * qdf_talloc_assert_no_children_fl() - assert @parent has not child allocations
134*5113495bSYour Name * @parent: the parent memory pointer to check
135*5113495bSYour Name * @func: name of the function requesting the assert
136*5113495bSYour Name * @line: line number of the call site in @func
137*5113495bSYour Name *
138*5113495bSYour Name * Return: None
139*5113495bSYour Name */
140*5113495bSYour Name void qdf_talloc_assert_no_children_fl(const void *parent,
141*5113495bSYour Name const char *func, const uint16_t line);
142*5113495bSYour Name
143*5113495bSYour Name #else /* WLAN_TALLOC_DEBUG */
144*5113495bSYour Name
qdf_talloc_feature_init(void)145*5113495bSYour Name static inline QDF_STATUS qdf_talloc_feature_init(void)
146*5113495bSYour Name {
147*5113495bSYour Name return QDF_STATUS_SUCCESS;
148*5113495bSYour Name }
149*5113495bSYour Name
qdf_talloc_feature_deinit(void)150*5113495bSYour Name static inline void qdf_talloc_feature_deinit(void) { }
151*5113495bSYour Name
__qdf_talloc_fl(const void * parent,const size_t size,const char * func,const uint16_t line)152*5113495bSYour Name static inline void *__qdf_talloc_fl(const void *parent, const size_t size,
153*5113495bSYour Name const char *func, const uint16_t line)
154*5113495bSYour Name {
155*5113495bSYour Name return __zalloc_auto(size);
156*5113495bSYour Name }
157*5113495bSYour Name
158*5113495bSYour Name static inline void
__qdf_tfree_fl(void * ptr,const char * func,const uint16_t line)159*5113495bSYour Name __qdf_tfree_fl(void *ptr, const char *func, const uint16_t line)
160*5113495bSYour Name {
161*5113495bSYour Name __k_free(ptr);
162*5113495bSYour Name }
163*5113495bSYour Name
164*5113495bSYour Name static inline void
qdf_talloc_assert_no_children_fl(const void * parent,const char * func,const uint16_t line)165*5113495bSYour Name qdf_talloc_assert_no_children_fl(const void *parent,
166*5113495bSYour Name const char *func, const uint16_t line) { }
167*5113495bSYour Name
168*5113495bSYour Name #endif /* WLAN_TALLOC_DEBUG */
169*5113495bSYour Name
170*5113495bSYour Name #endif /* __QDF_TALLOC_H */
171