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
81 * The name of the memzone. If it already exists, the function will
82 * fail and return NULL.
84 * The size of the memory to be reserved. If it
85 * is 0, the biggest contiguous zone will be reserved.
87 * The socket identifier in the case of
88 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
89 * constraint for the reserved zone.
91 * The flags parameter is used to request memzones to be
92 * taken from specifically sized hugepages.
93 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
94 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
95 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
96 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
97 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
98 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
99 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
100 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
101 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
102 * the requested page size is unavailable.
103 * If this flag is not set, the function
104 * will return error on an unavailable size
106 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
107 * This option should be used when allocating
108 * memory intended for hardware rings etc.
110 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
112 * On error case, rte_errno will be set appropriately:
113 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
114 * - E_RTE_SECONDARY - function was called from a secondary process instance
115 * - ENOSPC - the maximum number of memzones has already been allocated
116 * - EEXIST - a memzone with the same name already exists
117 * - ENOMEM - no appropriate memory area found in which to create memzone
118 * - EINVAL - invalid parameters
120 const struct rte_memzone *rte_memzone_reserve(const char *name,
121 size_t len, int socket_id,
125 * Reserve a portion of physical memory with alignment on a specified
128 * This function reserves some memory with alignment on a specified
129 * boundary, and returns a pointer to a correctly filled memzone
130 * descriptor. If the allocation cannot be done or if the alignment
131 * is not a power of 2, returns NULL.
134 * The name of the memzone. If it already exists, the function will
135 * fail and return NULL.
137 * The size of the memory to be reserved. If it
138 * is 0, the biggest contiguous zone will be reserved.
140 * The socket identifier in the case of
141 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
142 * constraint for the reserved zone.
144 * The flags parameter is used to request memzones to be
145 * taken from specifically sized hugepages.
146 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
147 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
148 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
149 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
150 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
151 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
152 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
153 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
154 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
155 * the requested page size is unavailable.
156 * If this flag is not set, the function
157 * will return error on an unavailable size
159 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
160 * This option should be used when allocating
161 * memory intended for hardware rings etc.
163 * Alignment for resulting memzone. Must be a power of 2.
165 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
167 * On error case, rte_errno will be set appropriately:
168 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
169 * - E_RTE_SECONDARY - function was called from a secondary process instance
170 * - ENOSPC - the maximum number of memzones has already been allocated
171 * - EEXIST - a memzone with the same name already exists
172 * - ENOMEM - no appropriate memory area found in which to create memzone
173 * - EINVAL - invalid parameters
175 const struct rte_memzone *rte_memzone_reserve_aligned(const char *name,
176 size_t len, int socket_id,
177 unsigned flags, unsigned align);
180 * Reserve a portion of physical memory with specified alignment and
183 * This function reserves some memory with specified alignment and
184 * boundary, and returns a pointer to a correctly filled memzone
185 * descriptor. If the allocation cannot be done or if the alignment
186 * or boundary are not a power of 2, returns NULL.
187 * Memory buffer is reserved in a way, that it wouldn't cross specified
188 * boundary. That implies that requested length should be less or equal
192 * The name of the memzone. If it already exists, the function will
193 * fail and return NULL.
195 * The size of the memory to be reserved. If it
196 * is 0, the biggest contiguous zone will be reserved.
198 * The socket identifier in the case of
199 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
200 * constraint for the reserved zone.
202 * The flags parameter is used to request memzones to be
203 * taken from specifically sized hugepages.
204 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
205 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
206 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
207 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
208 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
209 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
210 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
211 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
212 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
213 * the requested page size is unavailable.
214 * If this flag is not set, the function
215 * will return error on an unavailable size
217 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
218 * This option should be used when allocating
219 * memory intended for hardware rings etc.
221 * Alignment for resulting memzone. Must be a power of 2.
223 * Boundary for resulting memzone. Must be a power of 2 or zero.
224 * Zero value implies no boundary condition.
226 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
228 * On error case, rte_errno will be set appropriately:
229 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
230 * - E_RTE_SECONDARY - function was called from a secondary process instance
231 * - ENOSPC - the maximum number of memzones has already been allocated
232 * - EEXIST - a memzone with the same name already exists
233 * - ENOMEM - no appropriate memory area found in which to create memzone
234 * - EINVAL - invalid parameters
236 const struct rte_memzone *rte_memzone_reserve_bounded(const char *name,
237 size_t len, int socket_id,
238 unsigned flags, unsigned align, unsigned bound);
244 * A pointer to the memzone
246 * -EINVAL - invalid parameter.
249 int rte_memzone_free(const struct rte_memzone *mz);
252 * Lookup for a memzone.
254 * Get a pointer to a descriptor of an already reserved memory
255 * zone identified by the name given as an argument.
258 * The name of the memzone.
260 * A pointer to a read-only memzone descriptor.
262 const struct rte_memzone *rte_memzone_lookup(const char *name);
265 * Dump all reserved memzones to a file.
268 * A pointer to a file for output
270 void rte_memzone_dump(FILE *f);
273 * Walk list of all memzones
278 * Argument passed to iterator
280 void rte_memzone_walk(void (*func)(const struct rte_memzone *, void *arg),
287 #endif /* _RTE_MEMZONE_H_ */