DPDK  17.05.2
rte_mempool.h
Go to the documentation of this file.
1 /*-
2  * BSD LICENSE
3  *
4  * Copyright(c) 2010-2014 Intel Corporation. All rights reserved.
5  * Copyright(c) 2016 6WIND S.A.
6  * All rights reserved.
7  *
8  * Redistribution and use in source and binary forms, with or without
9  * modification, are permitted provided that the following conditions
10  * are met:
11  *
12  * * Redistributions of source code must retain the above copyright
13  * notice, this list of conditions and the following disclaimer.
14  * * Redistributions in binary form must reproduce the above copyright
15  * notice, this list of conditions and the following disclaimer in
16  * the documentation and/or other materials provided with the
17  * distribution.
18  * * Neither the name of Intel Corporation nor the names of its
19  * contributors may be used to endorse or promote products derived
20  * from this software without specific prior written permission.
21  *
22  * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
23  * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
24  * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
25  * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
26  * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
27  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
28  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29  * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
30  * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
32  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
33  */
34 
35 #ifndef _RTE_MEMPOOL_H_
36 #define _RTE_MEMPOOL_H_
37 
65 #include <stdio.h>
66 #include <stdlib.h>
67 #include <stdint.h>
68 #include <errno.h>
69 #include <inttypes.h>
70 #include <sys/queue.h>
71 
72 #include <rte_spinlock.h>
73 #include <rte_log.h>
74 #include <rte_debug.h>
75 #include <rte_lcore.h>
76 #include <rte_memory.h>
77 #include <rte_branch_prediction.h>
78 #include <rte_ring.h>
79 #include <rte_memcpy.h>
80 #include <rte_common.h>
81 
82 #ifdef __cplusplus
83 extern "C" {
84 #endif
85 
86 #define RTE_MEMPOOL_HEADER_COOKIE1 0xbadbadbadadd2e55ULL
87 #define RTE_MEMPOOL_HEADER_COOKIE2 0xf2eef2eedadd2e55ULL
88 #define RTE_MEMPOOL_TRAILER_COOKIE 0xadd2e55badbadbadULL
90 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
91 
94 struct rte_mempool_debug_stats {
95  uint64_t put_bulk;
96  uint64_t put_objs;
97  uint64_t get_success_bulk;
98  uint64_t get_success_objs;
99  uint64_t get_fail_bulk;
100  uint64_t get_fail_objs;
102 #endif
103 
108  uint32_t size;
109  uint32_t flushthresh;
110  uint32_t len;
111  /*
112  * Cache is allocated to this size to allow it to overflow in certain
113  * cases to avoid needless emptying of cache.
114  */
115  void *objs[RTE_MEMPOOL_CACHE_MAX_SIZE * 3];
117 
122  uint32_t elt_size;
123  uint32_t header_size;
124  uint32_t trailer_size;
125  uint32_t total_size;
127 };
128 
130 #define RTE_MEMPOOL_NAMESIZE (RTE_RING_NAMESIZE - \
131  sizeof(RTE_MEMPOOL_MZ_PREFIX) + 1)
132 #define RTE_MEMPOOL_MZ_PREFIX "MP_"
133 
134 /* "MP_<name>" */
135 #define RTE_MEMPOOL_MZ_FORMAT RTE_MEMPOOL_MZ_PREFIX "%s"
136 
137 #define MEMPOOL_PG_SHIFT_MAX (sizeof(uintptr_t) * CHAR_BIT - 1)
138 
140 #define MEMPOOL_PG_NUM_DEFAULT 1
141 
142 #ifndef RTE_MEMPOOL_ALIGN
143 #define RTE_MEMPOOL_ALIGN RTE_CACHE_LINE_SIZE
144 #endif
145 
146 #define RTE_MEMPOOL_ALIGN_MASK (RTE_MEMPOOL_ALIGN - 1)
147 
159  struct rte_mempool *mp;
161 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
162  uint64_t cookie;
163 #endif
164 };
165 
169 STAILQ_HEAD(rte_mempool_objhdr_list, rte_mempool_objhdr);
170 
171 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
172 
179 struct rte_mempool_objtlr {
180  uint64_t cookie;
181 };
182 
183 #endif
184 
188 STAILQ_HEAD(rte_mempool_memhdr_list, rte_mempool_memhdr);
189 
194  void *opaque);
195 
204  struct rte_mempool *mp;
205  void *addr;
207  size_t len;
209  void *opaque;
210 };
211 
215 struct rte_mempool {
216  /*
217  * Note: this field kept the RTE_MEMZONE_NAMESIZE size due to ABI
218  * compatibility requirements, it could be changed to
219  * RTE_MEMPOOL_NAMESIZE next time the ABI changes
220  */
223  union {
224  void *pool_data;
225  uint64_t pool_id;
226  };
227  void *pool_config;
228  const struct rte_memzone *mz;
229  int flags;
230  int socket_id;
231  uint32_t size;
232  uint32_t cache_size;
235  uint32_t elt_size;
236  uint32_t header_size;
237  uint32_t trailer_size;
239  unsigned private_data_size;
247  int32_t ops_index;
248 
251  uint32_t populated_size;
252  struct rte_mempool_objhdr_list elt_list;
253  uint32_t nb_mem_chunks;
254  struct rte_mempool_memhdr_list mem_list;
256 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
257 
258  struct rte_mempool_debug_stats stats[RTE_MAX_LCORE];
259 #endif
261 
262 #define MEMPOOL_F_NO_SPREAD 0x0001
263 #define MEMPOOL_F_NO_CACHE_ALIGN 0x0002
264 #define MEMPOOL_F_SP_PUT 0x0004
265 #define MEMPOOL_F_SC_GET 0x0008
266 #define MEMPOOL_F_POOL_CREATED 0x0010
267 #define MEMPOOL_F_NO_PHYS_CONTIG 0x0020
279 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
280 #define __MEMPOOL_STAT_ADD(mp, name, n) do { \
281  unsigned __lcore_id = rte_lcore_id(); \
282  if (__lcore_id < RTE_MAX_LCORE) { \
283  mp->stats[__lcore_id].name##_objs += n; \
284  mp->stats[__lcore_id].name##_bulk += 1; \
285  } \
286  } while(0)
287 #else
288 #define __MEMPOOL_STAT_ADD(mp, name, n) do {} while(0)
289 #endif
290 
299 #define MEMPOOL_HEADER_SIZE(mp, cs) \
300  (sizeof(*(mp)) + (((cs) == 0) ? 0 : \
301  (sizeof(struct rte_mempool_cache) * RTE_MAX_LCORE)))
302 
303 /* return the header of a mempool object (internal) */
304 static inline struct rte_mempool_objhdr *__mempool_get_header(void *obj)
305 {
306  return (struct rte_mempool_objhdr *)RTE_PTR_SUB(obj,
307  sizeof(struct rte_mempool_objhdr));
308 }
309 
319 static inline struct rte_mempool *rte_mempool_from_obj(void *obj)
320 {
321  struct rte_mempool_objhdr *hdr = __mempool_get_header(obj);
322  return hdr->mp;
323 }
324 
325 /* return the trailer of a mempool object (internal) */
326 static inline struct rte_mempool_objtlr *__mempool_get_trailer(void *obj)
327 {
328  struct rte_mempool *mp = rte_mempool_from_obj(obj);
329  return (struct rte_mempool_objtlr *)RTE_PTR_ADD(obj, mp->elt_size);
330 }
331 
346 void rte_mempool_check_cookies(const struct rte_mempool *mp,
347  void * const *obj_table_const, unsigned n, int free);
348 
349 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
350 #define __mempool_check_cookies(mp, obj_table_const, n, free) \
351  rte_mempool_check_cookies(mp, obj_table_const, n, free)
352 #else
353 #define __mempool_check_cookies(mp, obj_table_const, n, free) do {} while(0)
354 #endif /* RTE_LIBRTE_MEMPOOL_DEBUG */
355 
356 #define RTE_MEMPOOL_OPS_NAMESIZE 32
368 typedef int (*rte_mempool_alloc_t)(struct rte_mempool *mp);
369 
373 typedef void (*rte_mempool_free_t)(struct rte_mempool *mp);
374 
378 typedef int (*rte_mempool_enqueue_t)(struct rte_mempool *mp,
379  void * const *obj_table, unsigned int n);
380 
384 typedef int (*rte_mempool_dequeue_t)(struct rte_mempool *mp,
385  void **obj_table, unsigned int n);
386 
390 typedef unsigned (*rte_mempool_get_count)(const struct rte_mempool *mp);
391 
401 
402 #define RTE_MEMPOOL_MAX_OPS_IDX 16
413 struct rte_mempool_ops_table {
415  uint32_t num_ops;
421 
424 
434 static inline struct rte_mempool_ops *
435 rte_mempool_get_ops(int ops_index)
436 {
437  RTE_VERIFY((ops_index >= 0) && (ops_index < RTE_MEMPOOL_MAX_OPS_IDX));
438 
439  return &rte_mempool_ops_table.ops[ops_index];
440 }
441 
451 int
452 rte_mempool_ops_alloc(struct rte_mempool *mp);
453 
467 static inline int
468 rte_mempool_ops_dequeue_bulk(struct rte_mempool *mp,
469  void **obj_table, unsigned n)
470 {
471  struct rte_mempool_ops *ops;
472 
473  ops = rte_mempool_get_ops(mp->ops_index);
474  return ops->dequeue(mp, obj_table, n);
475 }
476 
490 static inline int
491 rte_mempool_ops_enqueue_bulk(struct rte_mempool *mp, void * const *obj_table,
492  unsigned n)
493 {
494  struct rte_mempool_ops *ops;
495 
496  ops = rte_mempool_get_ops(mp->ops_index);
497  return ops->enqueue(mp, obj_table, n);
498 }
499 
508 unsigned
509 rte_mempool_ops_get_count(const struct rte_mempool *mp);
510 
517 void
518 rte_mempool_ops_free(struct rte_mempool *mp);
519 
537 int
538 rte_mempool_set_ops_byname(struct rte_mempool *mp, const char *name,
539  void *pool_config);
540 
551 int rte_mempool_register_ops(const struct rte_mempool_ops *ops);
552 
558 #define MEMPOOL_REGISTER_OPS(ops) \
559  void mp_hdlr_init_##ops(void); \
560  void __attribute__((constructor, used)) mp_hdlr_init_##ops(void)\
561  { \
562  rte_mempool_register_ops(&ops); \
563  }
564 
570 typedef void (rte_mempool_obj_cb_t)(struct rte_mempool *mp,
571  void *opaque, void *obj, unsigned obj_idx);
572 typedef rte_mempool_obj_cb_t rte_mempool_obj_ctor_t; /* compat */
573 
579 typedef void (rte_mempool_mem_cb_t)(struct rte_mempool *mp,
580  void *opaque, struct rte_mempool_memhdr *memhdr,
581  unsigned mem_idx);
582 
589 typedef void (rte_mempool_ctor_t)(struct rte_mempool *, void *);
590 
670 struct rte_mempool *
671 rte_mempool_create(const char *name, unsigned n, unsigned elt_size,
672  unsigned cache_size, unsigned private_data_size,
673  rte_mempool_ctor_t *mp_init, void *mp_init_arg,
674  rte_mempool_obj_cb_t *obj_init, void *obj_init_arg,
675  int socket_id, unsigned flags);
676 
736 struct rte_mempool *
737 rte_mempool_xmem_create(const char *name, unsigned n, unsigned elt_size,
738  unsigned cache_size, unsigned private_data_size,
739  rte_mempool_ctor_t *mp_init, void *mp_init_arg,
740  rte_mempool_obj_cb_t *obj_init, void *obj_init_arg,
741  int socket_id, unsigned flags, void *vaddr,
742  const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift);
743 
778 struct rte_mempool *
779 rte_mempool_create_empty(const char *name, unsigned n, unsigned elt_size,
780  unsigned cache_size, unsigned private_data_size,
781  int socket_id, unsigned flags);
792 void
793 rte_mempool_free(struct rte_mempool *mp);
794 
822 int rte_mempool_populate_phys(struct rte_mempool *mp, char *vaddr,
823  phys_addr_t paddr, size_t len, rte_mempool_memchunk_free_cb_t *free_cb,
824  void *opaque);
825 
853 int rte_mempool_populate_phys_tab(struct rte_mempool *mp, char *vaddr,
854  const phys_addr_t paddr[], uint32_t pg_num, uint32_t pg_shift,
855  rte_mempool_memchunk_free_cb_t *free_cb, void *opaque);
856 
881 int
882 rte_mempool_populate_virt(struct rte_mempool *mp, char *addr,
883  size_t len, size_t pg_sz, rte_mempool_memchunk_free_cb_t *free_cb,
884  void *opaque);
885 
900 
914 int rte_mempool_populate_anon(struct rte_mempool *mp);
915 
931 uint32_t rte_mempool_obj_iter(struct rte_mempool *mp,
932  rte_mempool_obj_cb_t *obj_cb, void *obj_cb_arg);
933 
949 uint32_t rte_mempool_mem_iter(struct rte_mempool *mp,
950  rte_mempool_mem_cb_t *mem_cb, void *mem_cb_arg);
951 
960 void rte_mempool_dump(FILE *f, struct rte_mempool *mp);
961 
976 struct rte_mempool_cache *
977 rte_mempool_cache_create(uint32_t size, int socket_id);
978 
985 void
987 
996 static inline void __attribute__((always_inline))
998  struct rte_mempool *mp)
999 {
1000  rte_mempool_ops_enqueue_bulk(mp, cache->objs, cache->len);
1001  cache->len = 0;
1002 }
1003 
1014 static inline struct rte_mempool_cache *__attribute__((always_inline))
1015 rte_mempool_default_cache(struct rte_mempool *mp, unsigned lcore_id)
1016 {
1017  if (mp->cache_size == 0)
1018  return NULL;
1019 
1020  if (lcore_id >= RTE_MAX_LCORE)
1021  return NULL;
1022 
1023  return &mp->local_cache[lcore_id];
1024 }
1025 
1041 static inline void __attribute__((always_inline))
1042 __mempool_generic_put(struct rte_mempool *mp, void * const *obj_table,
1043  unsigned n, struct rte_mempool_cache *cache)
1044 {
1045  void **cache_objs;
1046 
1047  /* increment stat now, adding in mempool always success */
1048  __MEMPOOL_STAT_ADD(mp, put, n);
1049 
1050  /* No cache provided or if put would overflow mem allocated for cache */
1051  if (unlikely(cache == NULL || n > RTE_MEMPOOL_CACHE_MAX_SIZE))
1052  goto ring_enqueue;
1053 
1054  cache_objs = &cache->objs[cache->len];
1055 
1056  /*
1057  * The cache follows the following algorithm
1058  * 1. Add the objects to the cache
1059  * 2. Anything greater than the cache min value (if it crosses the
1060  * cache flush threshold) is flushed to the ring.
1061  */
1062 
1063  /* Add elements back into the cache */
1064  rte_memcpy(&cache_objs[0], obj_table, sizeof(void *) * n);
1065 
1066  cache->len += n;
1067 
1068  if (cache->len >= cache->flushthresh) {
1069  rte_mempool_ops_enqueue_bulk(mp, &cache->objs[cache->size],
1070  cache->len - cache->size);
1071  cache->len = cache->size;
1072  }
1073 
1074  return;
1075 
1076 ring_enqueue:
1077 
1078  /* push remaining objects in ring */
1079 #ifdef RTE_LIBRTE_MEMPOOL_DEBUG
1080  if (rte_mempool_ops_enqueue_bulk(mp, obj_table, n) < 0)
1081  rte_panic("cannot put objects in mempool\n");
1082 #else
1083  rte_mempool_ops_enqueue_bulk(mp, obj_table, n);
1084 #endif
1085 }
1086 
1087 
1103 static inline void __attribute__((always_inline))
1104 rte_mempool_generic_put(struct rte_mempool *mp, void * const *obj_table,
1105  unsigned n, struct rte_mempool_cache *cache,
1106  __rte_unused int flags)
1107 {
1108  __mempool_check_cookies(mp, obj_table, n, 0);
1109  __mempool_generic_put(mp, obj_table, n, cache);
1110 }
1111 
1126 static inline void __attribute__((always_inline))
1127 rte_mempool_put_bulk(struct rte_mempool *mp, void * const *obj_table,
1128  unsigned n)
1129 {
1130  struct rte_mempool_cache *cache;
1131  cache = rte_mempool_default_cache(mp, rte_lcore_id());
1132  rte_mempool_generic_put(mp, obj_table, n, cache, mp->flags);
1133 }
1134 
1147 static inline void __attribute__((always_inline))
1148 rte_mempool_put(struct rte_mempool *mp, void *obj)
1149 {
1150  rte_mempool_put_bulk(mp, &obj, 1);
1151 }
1152 
1170 static inline int __attribute__((always_inline))
1171 __mempool_generic_get(struct rte_mempool *mp, void **obj_table,
1172  unsigned n, struct rte_mempool_cache *cache)
1173 {
1174  int ret;
1175  uint32_t index, len;
1176  void **cache_objs;
1177 
1178  /* No cache provided or cannot be satisfied from cache */
1179  if (unlikely(cache == NULL || n >= cache->size))
1180  goto ring_dequeue;
1181 
1182  cache_objs = cache->objs;
1183 
1184  /* Can this be satisfied from the cache? */
1185  if (cache->len < n) {
1186  /* No. Backfill the cache first, and then fill from it */
1187  uint32_t req = n + (cache->size - cache->len);
1188 
1189  /* How many do we require i.e. number to fill the cache + the request */
1190  ret = rte_mempool_ops_dequeue_bulk(mp,
1191  &cache->objs[cache->len], req);
1192  if (unlikely(ret < 0)) {
1193  /*
1194  * In the offchance that we are buffer constrained,
1195  * where we are not able to allocate cache + n, go to
1196  * the ring directly. If that fails, we are truly out of
1197  * buffers.
1198  */
1199  goto ring_dequeue;
1200  }
1201 
1202  cache->len += req;
1203  }
1204 
1205  /* Now fill in the response ... */
1206  for (index = 0, len = cache->len - 1; index < n; ++index, len--, obj_table++)
1207  *obj_table = cache_objs[len];
1208 
1209  cache->len -= n;
1210 
1211  __MEMPOOL_STAT_ADD(mp, get_success, n);
1212 
1213  return 0;
1214 
1215 ring_dequeue:
1216 
1217  /* get remaining objects from ring */
1218  ret = rte_mempool_ops_dequeue_bulk(mp, obj_table, n);
1219 
1220  if (ret < 0)
1221  __MEMPOOL_STAT_ADD(mp, get_fail, n);
1222  else
1223  __MEMPOOL_STAT_ADD(mp, get_success, n);
1224 
1225  return ret;
1226 }
1227 
1251 static inline int __attribute__((always_inline))
1252 rte_mempool_generic_get(struct rte_mempool *mp, void **obj_table, unsigned n,
1253  struct rte_mempool_cache *cache, __rte_unused int flags)
1254 {
1255  int ret;
1256  ret = __mempool_generic_get(mp, obj_table, n, cache);
1257  if (ret == 0)
1258  __mempool_check_cookies(mp, obj_table, n, 1);
1259  return ret;
1260 }
1261 
1284 static inline int __attribute__((always_inline))
1285 rte_mempool_get_bulk(struct rte_mempool *mp, void **obj_table, unsigned n)
1286 {
1287  struct rte_mempool_cache *cache;
1288  cache = rte_mempool_default_cache(mp, rte_lcore_id());
1289  return rte_mempool_generic_get(mp, obj_table, n, cache, mp->flags);
1290 }
1291 
1312 static inline int __attribute__((always_inline))
1313 rte_mempool_get(struct rte_mempool *mp, void **obj_p)
1314 {
1315  return rte_mempool_get_bulk(mp, obj_p, 1);
1316 }
1317 
1330 unsigned int rte_mempool_avail_count(const struct rte_mempool *mp);
1331 
1344 unsigned int
1345 rte_mempool_in_use_count(const struct rte_mempool *mp);
1346 
1360 static inline int
1362 {
1363  return !!(rte_mempool_avail_count(mp) == mp->size);
1364 }
1365 
1379 static inline int
1381 {
1382  return !!(rte_mempool_avail_count(mp) == 0);
1383 }
1384 
1397 static inline phys_addr_t
1398 rte_mempool_virt2phy(__rte_unused const struct rte_mempool *mp, const void *elt)
1399 {
1400  const struct rte_mempool_objhdr *hdr;
1401  hdr = (const struct rte_mempool_objhdr *)RTE_PTR_SUB(elt,
1402  sizeof(*hdr));
1403  return hdr->physaddr;
1404 }
1405 
1416 void rte_mempool_audit(struct rte_mempool *mp);
1417 
1426 static inline void *rte_mempool_get_priv(struct rte_mempool *mp)
1427 {
1428  return (char *)mp +
1430 }
1431 
1438 void rte_mempool_list_dump(FILE *f);
1439 
1452 struct rte_mempool *rte_mempool_lookup(const char *name);
1453 
1471 uint32_t rte_mempool_calc_obj_size(uint32_t elt_size, uint32_t flags,
1472  struct rte_mempool_objsz *sz);
1473 
1495 size_t rte_mempool_xmem_size(uint32_t elt_num, size_t total_elt_sz,
1496  uint32_t pg_shift);
1497 
1525 ssize_t rte_mempool_xmem_usage(void *vaddr, uint32_t elt_num,
1526  size_t total_elt_sz, const phys_addr_t paddr[], uint32_t pg_num,
1527  uint32_t pg_shift);
1528 
1537 void rte_mempool_walk(void (*func)(struct rte_mempool *, void *arg),
1538  void *arg);
1539 
1540 #ifdef __cplusplus
1541 }
1542 #endif
1543 
1544 #endif /* _RTE_MEMPOOL_H_ */