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 uint32_t memseg_id; /**< Memseg it belongs. */
72 } __attribute__((__packed__));
75 * Reserve a portion of physical memory.
77 * This function reserves some memory and returns a pointer to a
78 * correctly filled memzone descriptor. If the allocation cannot be
82 * The name of the memzone. If it already exists, the function will
83 * fail and return NULL.
85 * The size of the memory to be reserved. If it
86 * is 0, the biggest contiguous zone will be reserved.
88 * The socket identifier in the case of
89 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
90 * constraint for the reserved zone.
92 * The flags parameter is used to request memzones to be
93 * taken from specifically sized hugepages.
94 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
95 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
96 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
97 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
98 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
99 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
100 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
101 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
102 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
103 * the requested page size is unavailable.
104 * If this flag is not set, the function
105 * will return error on an unavailable size
107 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
108 * This option should be used when allocating
109 * memory intended for hardware rings etc.
111 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
113 * On error case, rte_errno will be set appropriately:
114 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
115 * - E_RTE_SECONDARY - function was called from a secondary process instance
116 * - ENOSPC - the maximum number of memzones has already been allocated
117 * - EEXIST - a memzone with the same name already exists
118 * - ENOMEM - no appropriate memory area found in which to create memzone
119 * - EINVAL - invalid parameters
121 const struct rte_memzone *rte_memzone_reserve(const char *name,
122 size_t len, int socket_id,
126 * Reserve a portion of physical memory with alignment on a specified
129 * This function reserves some memory with alignment on a specified
130 * boundary, and returns a pointer to a correctly filled memzone
131 * descriptor. If the allocation cannot be done or if the alignment
132 * is not a power of 2, returns NULL.
135 * The name of the memzone. If it already exists, the function will
136 * fail and return NULL.
138 * The size of the memory to be reserved. If it
139 * is 0, the biggest contiguous zone will be reserved.
141 * The socket identifier in the case of
142 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
143 * constraint for the reserved zone.
145 * The flags parameter is used to request memzones to be
146 * taken from specifically sized hugepages.
147 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
148 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
149 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
150 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
151 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
152 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
153 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
154 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
155 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
156 * the requested page size is unavailable.
157 * If this flag is not set, the function
158 * will return error on an unavailable size
160 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
161 * This option should be used when allocating
162 * memory intended for hardware rings etc.
164 * Alignment for resulting memzone. Must be a power of 2.
166 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
168 * On error case, rte_errno will be set appropriately:
169 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
170 * - E_RTE_SECONDARY - function was called from a secondary process instance
171 * - ENOSPC - the maximum number of memzones has already been allocated
172 * - EEXIST - a memzone with the same name already exists
173 * - ENOMEM - no appropriate memory area found in which to create memzone
174 * - EINVAL - invalid parameters
176 const struct rte_memzone *rte_memzone_reserve_aligned(const char *name,
177 size_t len, int socket_id,
178 unsigned flags, unsigned align);
181 * Reserve a portion of physical memory with specified alignment and
184 * This function reserves some memory with specified alignment and
185 * boundary, and returns a pointer to a correctly filled memzone
186 * descriptor. If the allocation cannot be done or if the alignment
187 * or boundary are not a power of 2, returns NULL.
188 * Memory buffer is reserved in a way, that it wouldn't cross specified
189 * boundary. That implies that requested length should be less or equal
193 * The name of the memzone. If it already exists, the function will
194 * fail and return NULL.
196 * The size of the memory to be reserved. If it
197 * is 0, the biggest contiguous zone will be reserved.
199 * The socket identifier in the case of
200 * NUMA. The value can be SOCKET_ID_ANY if there is no NUMA
201 * constraint for the reserved zone.
203 * The flags parameter is used to request memzones to be
204 * taken from specifically sized hugepages.
205 * - RTE_MEMZONE_2MB - Reserved from 2MB pages
206 * - RTE_MEMZONE_1GB - Reserved from 1GB pages
207 * - RTE_MEMZONE_16MB - Reserved from 16MB pages
208 * - RTE_MEMZONE_16GB - Reserved from 16GB pages
209 * - RTE_MEMZONE_256KB - Reserved from 256KB pages
210 * - RTE_MEMZONE_256MB - Reserved from 256MB pages
211 * - RTE_MEMZONE_512MB - Reserved from 512MB pages
212 * - RTE_MEMZONE_4GB - Reserved from 4GB pages
213 * - RTE_MEMZONE_SIZE_HINT_ONLY - Allow alternative page size to be used if
214 * the requested page size is unavailable.
215 * If this flag is not set, the function
216 * will return error on an unavailable size
218 * - RTE_MEMZONE_IOVA_CONTIG - Ensure reserved memzone is IOVA-contiguous.
219 * This option should be used when allocating
220 * memory intended for hardware rings etc.
222 * Alignment for resulting memzone. Must be a power of 2.
224 * Boundary for resulting memzone. Must be a power of 2 or zero.
225 * Zero value implies no boundary condition.
227 * A pointer to a correctly-filled read-only memzone descriptor, or NULL
229 * On error case, rte_errno will be set appropriately:
230 * - E_RTE_NO_CONFIG - function could not get pointer to rte_config structure
231 * - E_RTE_SECONDARY - function was called from a secondary process instance
232 * - ENOSPC - the maximum number of memzones has already been allocated
233 * - EEXIST - a memzone with the same name already exists
234 * - ENOMEM - no appropriate memory area found in which to create memzone
235 * - EINVAL - invalid parameters
237 const struct rte_memzone *rte_memzone_reserve_bounded(const char *name,
238 size_t len, int socket_id,
239 unsigned flags, unsigned align, unsigned bound);
245 * A pointer to the memzone
247 * -EINVAL - invalid parameter.
250 int rte_memzone_free(const struct rte_memzone *mz);
253 * Lookup for a memzone.
255 * Get a pointer to a descriptor of an already reserved memory
256 * zone identified by the name given as an argument.
259 * The name of the memzone.
261 * A pointer to a read-only memzone descriptor.
263 const struct rte_memzone *rte_memzone_lookup(const char *name);
266 * Dump all reserved memzones to a file.
269 * A pointer to a file for output
271 void rte_memzone_dump(FILE *f);
274 * Walk list of all memzones
279 * Argument passed to iterator
281 void rte_memzone_walk(void (*func)(const struct rte_memzone *, void *arg),
288 #endif /* _RTE_MEMZONE_H_ */