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
85 * The name of the memzone. If it already exists, the function will
86 * fail and return NULL.
88 * The size of the memory to be reserved. If it
89 * is 0, the biggest contiguous zone will be reserved.
91 * The socket identifier in the case of
92 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
93 * constraint for the reserved zone.
95 * The flags parameter is used to request memzones to be
96 * taken from specifically sized hugepages.
97 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
98 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
99 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
100 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
101 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
102 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
103 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
104 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
105 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
106 * the requested page size is unavailable.
107 * If this flag is not set, the function
108 * will return error on an unavailable size
110 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
111 * This option should be used when allocating
112 * memory intended for hardware rings etc.
114 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
116 * On error case, rte_errno will be set appropriately:
117 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
118 * - E_RTE_SECONDARY - function was called from a secondary process instance
119 * - ENOSPC - the maximum number of memzones has already been allocated
120 * - EEXIST - a memzone with the same name already exists
121 * - ENOMEM - no appropriate memory area found in which to create memzone
122 * - EINVAL - invalid parameters
124 const struct rte_memzone *rte_memzone_reserve(const char *name,
125 size_t len, int socket_id,
129 * Reserve a portion of physical memory with alignment on a specified
132 * This function reserves some memory with alignment on a specified
133 * boundary, and returns a pointer to a correctly filled memzone
134 * descriptor. If the allocation cannot be done or if the alignment
135 * is not a power of 2, returns NULL.
137 * @note Reserving memzones with len set to 0 will only attempt to allocate
138 * memzones from memory that is already available. It will not trigger any
142 * The name of the memzone. If it already exists, the function will
143 * fail and return NULL.
145 * The size of the memory to be reserved. If it
146 * is 0, the biggest contiguous zone will be reserved.
148 * The socket identifier in the case of
149 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
150 * constraint for the reserved zone.
152 * The flags parameter is used to request memzones to be
153 * taken from specifically sized hugepages.
154 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
155 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
156 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
157 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
158 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
159 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
160 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
161 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
162 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
163 * the requested page size is unavailable.
164 * If this flag is not set, the function
165 * will return error on an unavailable size
167 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
168 * This option should be used when allocating
169 * memory intended for hardware rings etc.
171 * Alignment for resulting memzone. Must be a power of 2.
173 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
175 * On error case, rte_errno will be set appropriately:
176 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
177 * - E_RTE_SECONDARY - function was called from a secondary process instance
178 * - ENOSPC - the maximum number of memzones has already been allocated
179 * - EEXIST - a memzone with the same name already exists
180 * - ENOMEM - no appropriate memory area found in which to create memzone
181 * - EINVAL - invalid parameters
183 const struct rte_memzone *rte_memzone_reserve_aligned(const char *name,
184 size_t len, int socket_id,
185 unsigned flags, unsigned align);
188 * Reserve a portion of physical memory with specified alignment and
191 * This function reserves some memory with specified alignment and
192 * boundary, and returns a pointer to a correctly filled memzone
193 * descriptor. If the allocation cannot be done or if the alignment
194 * or boundary are not a power of 2, returns NULL.
195 * Memory buffer is reserved in a way, that it wouldn't cross specified
196 * boundary. That implies that requested length should be less or equal
199 * @note Reserving memzones with len set to 0 will only attempt to allocate
200 * memzones from memory that is already available. It will not trigger any
204 * The name of the memzone. If it already exists, the function will
205 * fail and return NULL.
207 * The size of the memory to be reserved. If it
208 * is 0, the biggest contiguous zone will be reserved.
210 * The socket identifier in the case of
211 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
212 * constraint for the reserved zone.
214 * The flags parameter is used to request memzones to be
215 * taken from specifically sized hugepages.
216 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
217 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
218 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
219 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
220 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
221 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
222 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
223 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
224 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
225 * the requested page size is unavailable.
226 * If this flag is not set, the function
227 * will return error on an unavailable size
229 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
230 * This option should be used when allocating
231 * memory intended for hardware rings etc.
233 * Alignment for resulting memzone. Must be a power of 2.
235 * Boundary for resulting memzone. Must be a power of 2 or zero.
236 * Zero value implies no boundary condition.
238 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
240 * On error case, rte_errno will be set appropriately:
241 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
242 * - E_RTE_SECONDARY - function was called from a secondary process instance
243 * - ENOSPC - the maximum number of memzones has already been allocated
244 * - EEXIST - a memzone with the same name already exists
245 * - ENOMEM - no appropriate memory area found in which to create memzone
246 * - EINVAL - invalid parameters
248 const struct rte_memzone *rte_memzone_reserve_bounded(const char *name,
249 size_t len, int socket_id,
250 unsigned flags, unsigned align, unsigned bound);
256 * A pointer to the memzone
258 * -EINVAL - invalid parameter.
261 int rte_memzone_free(const struct rte_memzone *mz);
264 * Lookup for a memzone.
266 * Get a pointer to a descriptor of an already reserved memory
267 * zone identified by the name given as an argument.
270 * The name of the memzone.
272 * A pointer to a read-only memzone descriptor.
274 const struct rte_memzone *rte_memzone_lookup(const char *name);
277 * Dump all reserved memzones to a file.
280 * A pointer to a file for output
282 void rte_memzone_dump(FILE *f);
285 * Walk list of all memzones
290 * Argument passed to iterator
292 void rte_memzone_walk(void (*func)(const struct rte_memzone *, void *arg),
299 #endif /* _RTE_MEMZONE_H_ */