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. */
56 phys_addr_t phys_addr; /**< deprecated - Start physical address. */
57 rte_iova_t iova; /**< Start IO address. */
61 void *addr; /**< Start virtual address. */
62 uint64_t addr_64; /**< Makes sure addr is always 64-bits */
64 size_t len; /**< Length of the memzone. */
66 uint64_t hugepage_sz; /**< The page size of underlying memory */
68 int32_t socket_id; /**< NUMA socket ID. */
70 uint32_t flags; /**< Characteristics of this memzone. */
71 } __attribute__((__packed__));
74 * Reserve a portion of physical memory.
76 * This function reserves some memory and returns a pointer to a
77 * correctly filled memzone descriptor. If the allocation cannot be
80 * @note Reserving memzones with len set to 0 will only attempt to allocate
81 * memzones from memory that is already available. It will not trigger any
84 * @note Reserving IOVA-contiguous memzones with len set to 0 is not currently
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 Reserving IOVA-contiguous memzones with len set to 0 is not currently
148 * The name of the memzone. If it already exists, the function will
149 * fail and return NULL.
151 * The size of the memory to be reserved. If it
152 * is 0, the biggest contiguous zone will be reserved.
154 * The socket identifier in the case of
155 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
156 * constraint for the reserved zone.
158 * The flags parameter is used to request memzones to be
159 * taken from specifically sized hugepages.
160 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
161 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
162 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
163 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
164 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
165 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
166 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
167 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
168 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
169 * the requested page size is unavailable.
170 * If this flag is not set, the function
171 * will return error on an unavailable size
173 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
174 * This option should be used when allocating
175 * memory intended for hardware rings etc.
177 * Alignment for resulting memzone. Must be a power of 2.
179 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
181 * On error case, rte_errno will be set appropriately:
182 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
183 * - E_RTE_SECONDARY - function was called from a secondary process instance
184 * - ENOSPC - the maximum number of memzones has already been allocated
185 * - EEXIST - a memzone with the same name already exists
186 * - ENOMEM - no appropriate memory area found in which to create memzone
187 * - EINVAL - invalid parameters
189 const struct rte_memzone *rte_memzone_reserve_aligned(const char *name,
190 size_t len, int socket_id,
191 unsigned flags, unsigned align);
194 * Reserve a portion of physical memory with specified alignment and
197 * This function reserves some memory with specified alignment and
198 * boundary, and returns a pointer to a correctly filled memzone
199 * descriptor. If the allocation cannot be done or if the alignment
200 * or boundary are not a power of 2, returns NULL.
201 * Memory buffer is reserved in a way, that it wouldn't cross specified
202 * boundary. That implies that requested length should be less or equal
205 * @note Reserving memzones with len set to 0 will only attempt to allocate
206 * memzones from memory that is already available. It will not trigger any
209 * @note Reserving IOVA-contiguous memzones with len set to 0 is not currently
213 * The name of the memzone. If it already exists, the function will
214 * fail and return NULL.
216 * The size of the memory to be reserved. If it
217 * is 0, the biggest contiguous zone will be reserved.
219 * The socket identifier in the case of
220 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
221 * constraint for the reserved zone.
223 * The flags parameter is used to request memzones to be
224 * taken from specifically sized hugepages.
225 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
226 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
227 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
228 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
229 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
230 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
231 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
232 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
233 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
234 * the requested page size is unavailable.
235 * If this flag is not set, the function
236 * will return error on an unavailable size
238 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
239 * This option should be used when allocating
240 * memory intended for hardware rings etc.
242 * Alignment for resulting memzone. Must be a power of 2.
244 * Boundary for resulting memzone. Must be a power of 2 or zero.
245 * Zero value implies no boundary condition.
247 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
249 * On error case, rte_errno will be set appropriately:
250 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
251 * - E_RTE_SECONDARY - function was called from a secondary process instance
252 * - ENOSPC - the maximum number of memzones has already been allocated
253 * - EEXIST - a memzone with the same name already exists
254 * - ENOMEM - no appropriate memory area found in which to create memzone
255 * - EINVAL - invalid parameters
257 const struct rte_memzone *rte_memzone_reserve_bounded(const char *name,
258 size_t len, int socket_id,
259 unsigned flags, unsigned align, unsigned bound);
265 * A pointer to the memzone
267 * -EINVAL - invalid parameter.
270 int rte_memzone_free(const struct rte_memzone *mz);
273 * Lookup for a memzone.
275 * Get a pointer to a descriptor of an already reserved memory
276 * zone identified by the name given as an argument.
279 * The name of the memzone.
281 * A pointer to a read-only memzone descriptor.
283 const struct rte_memzone *rte_memzone_lookup(const char *name);
286 * Dump all reserved memzones to a file.
289 * A pointer to a file for output
291 void rte_memzone_dump(FILE *f);
294 * Walk list of all memzones
299 * Argument passed to iterator
301 void rte_memzone_walk(void (*func)(const struct rte_memzone *, void *arg),
308 #endif /* _RTE_MEMZONE_H_ */