1 /* SPDX-License-Identifier: BSD-3-Clause
2 *
3 * Copyright(c) 2016 Intel Corporation. All rights reserved.
4 *
5 * Author: Liam Girdwood <liam.r.girdwood@linux.intel.com>
6 * Keyon Jie <yang.jie@linux.intel.com>
7 */
8
9 /**
10 * \file include/sof/lib/alloc.h
11 * \brief Memory Allocation API definition
12 * \author Liam Girdwood <liam.r.girdwood@linux.intel.com>
13 * \author Keyon Jie <yang.jie@linux.intel.com>
14 */
15
16 #ifndef __SOF_LIB_ALLOC_H__
17 #define __SOF_LIB_ALLOC_H__
18
19 #include <sof/bit.h>
20 #include <sof/string.h>
21 #include <sof/trace/trace.h>
22 #include <user/trace.h>
23
24 #include <stddef.h>
25 #include <stdint.h>
26
27 /** \addtogroup alloc_api Memory Allocation API
28 * @{
29 */
30
31 /**
32 * \brief Heap Memory Zones
33 *
34 * The heap has three different zones from where memory can be allocated :-
35 *
36 * 1) System Zone. Fixed size heap where alloc always succeeds and is never
37 * freed. Used by any init code that will never give up the memory.
38 *
39 * 2) System Runtime Zone. Heap zone intended for runtime objects allocated
40 * by the kernel part of the code.
41 *
42 * 3) Runtime Zone. Main and larger heap zone where allocs are not guaranteed to
43 * succeed. Memory can be freed here.
44 *
45 * 4) Buffer Zone. Largest heap zone intended for audio buffers.
46 *
47 * 5) Runtime Shared Zone. Similar to Runtime Zone, but content may be used and
48 * fred from any enabled core.
49 *
50 * 6) System Shared Zone. Similar to System Zone, but content may be used from
51 * any enabled core.
52 *
53 * See platform/memory.h for heap size configuration and mappings.
54 */
55 enum mem_zone {
56 SOF_MEM_ZONE_SYS = 0, /**< System zone */
57 SOF_MEM_ZONE_SYS_RUNTIME, /**< System-runtime zone */
58 SOF_MEM_ZONE_RUNTIME, /**< Runtime zone */
59 SOF_MEM_ZONE_BUFFER, /**< Buffer zone */
60 SOF_MEM_ZONE_RUNTIME_SHARED, /**< Runtime shared zone */
61 SOF_MEM_ZONE_SYS_SHARED, /**< System shared zone */
62 };
63
64 /** \name Heap zone flags
65 * @{
66 */
67
68 /** \brief Indicates that original content should not be copied by realloc. */
69 #define SOF_MEM_FLAG_NO_COPY BIT(1)
70
71 /** @} */
72
73 /**
74 * Allocates memory block.
75 * @param zone Zone to allocate memory from, see enum mem_zone.
76 * @param flags Flags, see SOF_MEM_FLAG_...
77 * @param caps Capabilities, see SOF_MEM_CAPS_...
78 * @param bytes Size in bytes.
79 * @return Pointer to the allocated memory or NULL if failed.
80 *
81 * @note Do not use for buffers (SOF_MEM_ZONE_BUFFER zone).
82 * Use rballoc(), rballoc_align() to allocate memory for buffers.
83 */
84 void *rmalloc(enum mem_zone zone, uint32_t flags, uint32_t caps, size_t bytes);
85
86 /**
87 * Similar to rmalloc(), guarantees that returned block is zeroed.
88 *
89 * @note Do not use for buffers (SOF_MEM_ZONE_BUFFER zone).
90 * rballoc(), rballoc_align() to allocate memory for buffers.
91 */
92 void *rzalloc(enum mem_zone zone, uint32_t flags, uint32_t caps, size_t bytes);
93
94 /**
95 * Allocates memory block from SOF_MEM_ZONE_BUFFER.
96 * @param flags Flags, see SOF_MEM_FLAG_...
97 * @param caps Capabilities, see SOF_MEM_CAPS_...
98 * @param bytes Size in bytes.
99 * @param alignment Alignment in bytes.
100 * @return Pointer to the allocated memory or NULL if failed.
101 */
102 void *rballoc_align(uint32_t flags, uint32_t caps, size_t bytes,
103 uint32_t alignment);
104
105 /**
106 * Similar to rballoc_align(), returns buffer aligned to PLATFORM_DCACHE_ALIGN.
107 */
rballoc(uint32_t flags,uint32_t caps,size_t bytes)108 static inline void *rballoc(uint32_t flags, uint32_t caps, size_t bytes)
109 {
110 return rballoc_align(flags, caps, bytes, PLATFORM_DCACHE_ALIGN);
111 }
112
113 /**
114 * Changes size of the memory block allocated from SOF_MEM_ZONE_BUFFER.
115 * @param ptr Address of the block to resize.
116 * @param flags Flags, see SOF_MEM_FLAG_...
117 * @param caps Capabilities, see SOF_MEM_CAPS_...
118 * @param bytes New size in bytes.
119 * @param old_bytes Old size in bytes.
120 * @param alignment Alignment in bytes.
121 * @return Pointer to the resized memory of NULL if failed.
122 */
123 void *rbrealloc_align(void *ptr, uint32_t flags, uint32_t caps, size_t bytes,
124 size_t old_bytes, uint32_t alignment);
125
126 /**
127 * Similar to rballoc_align(), returns resized buffer aligned to
128 * PLATFORM_DCACHE_ALIGN.
129 */
rbrealloc(void * ptr,uint32_t flags,uint32_t caps,size_t bytes,size_t old_bytes)130 static inline void *rbrealloc(void *ptr, uint32_t flags, uint32_t caps,
131 size_t bytes, size_t old_bytes)
132 {
133 return rbrealloc_align(ptr, flags, caps, bytes, old_bytes,
134 PLATFORM_DCACHE_ALIGN);
135 }
136
137 /**
138 * Frees the memory block.
139 * @param ptr Pointer to the memory block.
140 *
141 * @note Blocks from SOF_MEM_ZONE_SYS cannot be freed, such a call causes
142 * panic.
143 */
144 void rfree(void *ptr);
145
146 /**
147 * Allocates memory block from the system heap reserved for the specified core.
148 * @param core Core id.
149 * @param bytes Size in bytes.
150 */
151 void *rzalloc_core_sys(int core, size_t bytes);
152
153 /** \brief Zeroes memory block.
154 * @param ptr Pointer to the memory block.
155 * @param size Size of the block in bytes.
156 */
157 #define bzero(ptr, size) \
158 arch_bzero(ptr, size)
159
160 /**
161 * Calculates length of the null-terminated string.
162 * @param s String.
163 * @return Length of the string in bytes.
164 */
165 int rstrlen(const char *s);
166
167 /**
168 * Compares two strings, see man strcmp.
169 * @param s1 First string to compare.
170 * @param s2 Second string to compare.
171 * @return See man strcmp.
172 */
173 int rstrcmp(const char *s1, const char *s2);
174
175 /** @}*/
176
177 #endif /* __SOF_LIB_ALLOC_H__ */
178
