1 /* SPDX-License-Identifier: BSD-3-Clause
2 * Copyright(c) 2010-2014 Intel Corporation
5 #ifndef _RTE_MEMZONE_H_
6 #define _RTE_MEMZONE_H_
12 * The goal of the memzone allocator is to reserve contiguous
13 * portions of physical memory. These zones are identified by a name.
15 * The memzone descriptors are shared by all partitions and are
16 * located in a known place of physical memory. This zone is accessed
17 * using rte_eal_get_configuration(). The lookup (by name) of a
18 * memory zone can be done in any partition and returns the same
21 * A reserved memory zone cannot be unreserved. The reservation shall
22 * be done at initialization time only.
26 #include <rte_compat.h>
27 #include <rte_memory.h>
28 #include <rte_common.h>
34 #define RTE_MEMZONE_2MB 0x00000001 /**< Use 2MB pages. */
35 #define RTE_MEMZONE_1GB 0x00000002 /**< Use 1GB pages. */
36 #define RTE_MEMZONE_16MB 0x00000100 /**< Use 16MB pages. */
37 #define RTE_MEMZONE_16GB 0x00000200 /**< Use 16GB pages. */
38 #define RTE_MEMZONE_256KB 0x00010000 /**< Use 256KB pages. */
39 #define RTE_MEMZONE_256MB 0x00020000 /**< Use 256MB pages. */
40 #define RTE_MEMZONE_512MB 0x00040000 /**< Use 512MB pages. */
41 #define RTE_MEMZONE_4GB 0x00080000 /**< Use 4GB pages. */
42 #define RTE_MEMZONE_SIZE_HINT_ONLY 0x00000004 /**< Use available page size */
43 #define RTE_MEMZONE_IOVA_CONTIG 0x00100000 /**< Ask for IOVA-contiguous memzone. */
46 * A structure describing a memzone, which is a contiguous portion of
47 * physical memory identified by a name.
51 #define RTE_MEMZONE_NAMESIZE 32 /**< Maximum length of memory zone name.*/
52 char name[RTE_MEMZONE_NAMESIZE]; /**< Name of the memory zone. */
54 rte_iova_t iova; /**< Start IO address. */
57 void *addr; /**< Start virtual address. */
58 uint64_t addr_64; /**< Makes sure addr is always 64-bits */
60 size_t len; /**< Length of the memzone. */
62 uint64_t hugepage_sz; /**< The page size of underlying memory */
64 int32_t socket_id; /**< NUMA socket ID. */
66 uint32_t flags; /**< Characteristics of this memzone. */
70 * Reserve a portion of physical memory.
72 * This function reserves some memory and returns a pointer to a
73 * correctly filled memzone descriptor. If the allocation cannot be
76 * @note Reserving memzones with len set to 0 will only attempt to allocate
77 * memzones from memory that is already available. It will not trigger any
80 * @note: When reserving memzones with len set to 0, it is preferable to also
81 * set a valid socket_id. Setting socket_id to SOCKET_ID_ANY is supported, but
82 * will likely not yield expected results. Specifically, the resulting memzone
83 * may not necessarily be the biggest memzone available, but rather biggest
84 * memzone available on socket id corresponding to an lcore from which
85 * reservation was called.
88 * The name of the memzone. If it already exists, the function will
89 * fail and return NULL.
91 * The size of the memory to be reserved. If it
92 * is 0, the biggest contiguous zone will be reserved.
94 * The socket identifier in the case of
95 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
96 * constraint for the reserved zone.
98 * The flags parameter is used to request memzones to be
99 * taken from specifically sized hugepages.
100 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
101 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
102 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
103 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
104 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
105 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
106 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
107 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
108 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
109 * the requested page size is unavailable.
110 * If this flag is not set, the function
111 * will return error on an unavailable size
113 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
114 * This option should be used when allocating
115 * memory intended for hardware rings etc.
117 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
119 * On error case, rte_errno will be set appropriately:
120 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
121 * - E_RTE_SECONDARY - function was called from a secondary process instance
122 * - ENOSPC - the maximum number of memzones has already been allocated
123 * - EEXIST - a memzone with the same name already exists
124 * - ENOMEM - no appropriate memory area found in which to create memzone
125 * - EINVAL - invalid parameters
127 const struct rte_memzone *rte_memzone_reserve(const char *name,
128 size_t len, int socket_id,
132 * Reserve a portion of physical memory with alignment on a specified
135 * This function reserves some memory with alignment on a specified
136 * boundary, and returns a pointer to a correctly filled memzone
137 * descriptor. If the allocation cannot be done or if the alignment
138 * is not a power of 2, returns NULL.
140 * @note Reserving memzones with len set to 0 will only attempt to allocate
141 * memzones from memory that is already available. It will not trigger any
144 * @note: When reserving memzones with len set to 0, it is preferable to also
145 * set a valid socket_id. Setting socket_id to SOCKET_ID_ANY is supported, but
146 * will likely not yield expected results. Specifically, the resulting memzone
147 * may not necessarily be the biggest memzone available, but rather biggest
148 * memzone available on socket id corresponding to an lcore from which
149 * reservation was called.
152 * The name of the memzone. If it already exists, the function will
153 * fail and return NULL.
155 * The size of the memory to be reserved. If it
156 * is 0, the biggest contiguous zone will be reserved.
158 * The socket identifier in the case of
159 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
160 * constraint for the reserved zone.
162 * The flags parameter is used to request memzones to be
163 * taken from specifically sized hugepages.
164 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
165 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
166 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
167 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
168 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
169 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
170 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
171 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
172 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
173 * the requested page size is unavailable.
174 * If this flag is not set, the function
175 * will return error on an unavailable size
177 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
178 * This option should be used when allocating
179 * memory intended for hardware rings etc.
181 * Alignment for resulting memzone. Must be a power of 2.
183 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
185 * On error case, rte_errno will be set appropriately:
186 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
187 * - E_RTE_SECONDARY - function was called from a secondary process instance
188 * - ENOSPC - the maximum number of memzones has already been allocated
189 * - EEXIST - a memzone with the same name already exists
190 * - ENOMEM - no appropriate memory area found in which to create memzone
191 * - EINVAL - invalid parameters
193 const struct rte_memzone *rte_memzone_reserve_aligned(const char *name,
194 size_t len, int socket_id,
195 unsigned flags, unsigned align);
198 * Reserve a portion of physical memory with specified alignment and
201 * This function reserves some memory with specified alignment and
202 * boundary, and returns a pointer to a correctly filled memzone
203 * descriptor. If the allocation cannot be done or if the alignment
204 * or boundary are not a power of 2, returns NULL.
205 * Memory buffer is reserved in a way, that it wouldn't cross specified
206 * boundary. That implies that requested length should be less or equal
209 * @note Reserving memzones with len set to 0 will only attempt to allocate
210 * memzones from memory that is already available. It will not trigger any
213 * @note: When reserving memzones with len set to 0, it is preferable to also
214 * set a valid socket_id. Setting socket_id to SOCKET_ID_ANY is supported, but
215 * will likely not yield expected results. Specifically, the resulting memzone
216 * may not necessarily be the biggest memzone available, but rather biggest
217 * memzone available on socket id corresponding to an lcore from which
218 * reservation was called.
221 * The name of the memzone. If it already exists, the function will
222 * fail and return NULL.
224 * The size of the memory to be reserved. If it
225 * is 0, the biggest contiguous zone will be reserved.
227 * The socket identifier in the case of
228 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
229 * constraint for the reserved zone.
231 * The flags parameter is used to request memzones to be
232 * taken from specifically sized hugepages.
233 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
234 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
235 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
236 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
237 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
238 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
239 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
240 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
241 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
242 * the requested page size is unavailable.
243 * If this flag is not set, the function
244 * will return error on an unavailable size
246 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
247 * This option should be used when allocating
248 * memory intended for hardware rings etc.
250 * Alignment for resulting memzone. Must be a power of 2.
252 * Boundary for resulting memzone. Must be a power of 2 or zero.
253 * Zero value implies no boundary condition.
255 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
257 * On error case, rte_errno will be set appropriately:
258 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
259 * - E_RTE_SECONDARY - function was called from a secondary process instance
260 * - ENOSPC - the maximum number of memzones has already been allocated
261 * - EEXIST - a memzone with the same name already exists
262 * - ENOMEM - no appropriate memory area found in which to create memzone
263 * - EINVAL - invalid parameters
265 const struct rte_memzone *rte_memzone_reserve_bounded(const char *name,
266 size_t len, int socket_id,
267 unsigned flags, unsigned align, unsigned bound);
273 * A pointer to the memzone
275 * -EINVAL - invalid parameter.
278 int rte_memzone_free(const struct rte_memzone *mz);
281 * Lookup for a memzone.
283 * Get a pointer to a descriptor of an already reserved memory
284 * zone identified by the name given as an argument.
287 * The name of the memzone.
289 * A pointer to a read-only memzone descriptor.
291 const struct rte_memzone *rte_memzone_lookup(const char *name);
294 * Dump all reserved memzones to a file.
297 * A pointer to a file for output
299 void rte_memzone_dump(FILE *f);
302 * Walk list of all memzones
307 * Argument passed to iterator
309 void rte_memzone_walk(void (*func)(const struct rte_memzone *, void *arg),
316 #endif /* _RTE_MEMZONE_H_ */