1/**
2 * @file
3 * Memory pool API
4 */
5
6/*
7 * Copyright (c) 2001-2004 Swedish Institute of Computer Science.
8 * All rights reserved.
9 *
10 * Redistribution and use in source and binary forms, with or without modification,
11 * are permitted provided that the following conditions are met:
12 *
13 * 1. Redistributions of source code must retain the above copyright notice,
14 *    this list of conditions and the following disclaimer.
15 * 2. Redistributions in binary form must reproduce the above copyright notice,
16 *    this list of conditions and the following disclaimer in the documentation
17 *    and/or other materials provided with the distribution.
18 * 3. The name of the author may not be used to endorse or promote products
19 *    derived from this software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR IMPLIED
22 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
23 * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT
24 * SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
26 * OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
27 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
28 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29 * IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
30 * OF SUCH DAMAGE.
31 *
32 * This file is part of the lwIP TCP/IP stack.
33 *
34 * Author: Adam Dunkels <adam@sics.se>
35 *
36 */
37
38#ifndef LWIP_HDR_MEMP_H
39#define LWIP_HDR_MEMP_H
40
41#ifdef __cplusplus
42extern "C" {
43#endif
44
45/* run once with empty definition to handle all custom includes in lwippools.h */
46#define LWIP_MEMPOOL(name,num,size,desc)
47#include "lwip/priv/memp_std.h"
48
49/** Create the list of all memory pools managed by memp. MEMP_MAX represents a NULL pool at the end */
50typedef enum {
51#define LWIP_MEMPOOL(name,num,size,desc)  MEMP_##name,
52#include "lwip/priv/memp_std.h"
53  MEMP_MAX
54} memp_t;
55
56#include "lwip/priv/memp_priv.h"
57#include "lwip/stats.h"
58
59extern const struct memp_desc* const memp_pools[MEMP_MAX];
60
61/**
62 * @ingroup mempool
63 * Declare prototype for private memory pool if it is used in multiple files
64 */
65#define LWIP_MEMPOOL_PROTOTYPE(name) extern const struct memp_desc memp_ ## name
66
67#if MEMP_MEM_MALLOC
68
69#define LWIP_MEMPOOL_DECLARE(name,num,size,desc) \
70  LWIP_MEMPOOL_DECLARE_STATS_INSTANCE(memp_stats_ ## name) \
71  const struct memp_desc memp_ ## name = { \
72    DECLARE_LWIP_MEMPOOL_DESC(desc) \
73    LWIP_MEMPOOL_DECLARE_STATS_REFERENCE(memp_stats_ ## name) \
74    LWIP_MEM_ALIGN_SIZE(size) \
75  };
76
77#else /* MEMP_MEM_MALLOC */
78
79/**
80 * @ingroup mempool
81 * Declare a private memory pool
82 * Private mempools example:
83 * .h: only when pool is used in multiple .c files: LWIP_MEMPOOL_PROTOTYPE(my_private_pool);
84 * .c:
85 *   - in global variables section: LWIP_MEMPOOL_DECLARE(my_private_pool, 10, sizeof(foo), "Some description")
86 *   - call ONCE before using pool (e.g. in some init() function): LWIP_MEMPOOL_INIT(my_private_pool);
87 *   - allocate: void* my_new_mem = LWIP_MEMPOOL_ALLOC(my_private_pool);
88 *   - free: LWIP_MEMPOOL_FREE(my_private_pool, my_new_mem);
89 *
90 * To relocate a pool, declare it as extern in cc.h. Example for GCC:
91 *   extern u8_t __attribute__((section(".onchip_mem"))) memp_memory_my_private_pool[];
92 */
93#define LWIP_MEMPOOL_DECLARE(name,num,size,desc) \
94  LWIP_DECLARE_MEMORY_ALIGNED(memp_memory_ ## name ## _base, ((num) * (MEMP_SIZE + MEMP_ALIGN_SIZE(size)))); \
95    \
96  LWIP_MEMPOOL_DECLARE_STATS_INSTANCE(memp_stats_ ## name) \
97    \
98  static struct memp *memp_tab_ ## name; \
99    \
100  const struct memp_desc memp_ ## name = { \
101    DECLARE_LWIP_MEMPOOL_DESC(desc) \
102    LWIP_MEMPOOL_DECLARE_STATS_REFERENCE(memp_stats_ ## name) \
103    LWIP_MEM_ALIGN_SIZE(size), \
104    (num), \
105    memp_memory_ ## name ## _base, \
106    &memp_tab_ ## name \
107  };
108
109#endif /* MEMP_MEM_MALLOC */
110
111/**
112 * @ingroup mempool
113 * Initialize a private memory pool
114 */
115#define LWIP_MEMPOOL_INIT(name)    memp_init_pool(&memp_ ## name)
116/**
117 * @ingroup mempool
118 * Allocate from a private memory pool
119 */
120#define LWIP_MEMPOOL_ALLOC(name)   memp_malloc_pool(&memp_ ## name)
121/**
122 * @ingroup mempool
123 * Free element from a private memory pool
124 */
125#define LWIP_MEMPOOL_FREE(name, x) memp_free_pool(&memp_ ## name, (x))
126
127#if MEM_USE_POOLS
128/** This structure is used to save the pool one element came from.
129 * This has to be defined here as it is required for pool size calculation. */
130struct memp_malloc_helper
131{
132   memp_t poolnr;
133#if MEMP_OVERFLOW_CHECK || (LWIP_STATS && MEM_STATS)
134   u16_t size;
135#endif /* MEMP_OVERFLOW_CHECK || (LWIP_STATS && MEM_STATS) */
136};
137#endif /* MEM_USE_POOLS */
138
139void  memp_init(void);
140
141#if MEMP_OVERFLOW_CHECK
142void *memp_malloc_fn(memp_t type, const char* file, const int line);
143#define memp_malloc(t) memp_malloc_fn((t), __FILE__, __LINE__)
144#else
145void *memp_malloc(memp_t type);
146#endif
147void  memp_free(memp_t type, void *mem);
148
149#ifdef __cplusplus
150}
151#endif
152
153#endif /* LWIP_HDR_MEMP_H */
154