1 /*
2 * mem.h -- CoAP memory handling
3 *
4 * Copyright (C) 2010-2011,2014-2015 Olaf Bergmann <bergmann@tzi.org>
5 *
6 * SPDX-License-Identifier: BSD-2-Clause
7 *
8 * This file is part of the CoAP library libcoap. Please see README for terms
9 * of use.
10 */
11
12 #ifndef COAP_MEM_H_
13 #define COAP_MEM_H_
14
15 #include <stdlib.h>
16
17 #ifndef WITH_LWIP
18 /**
19 * Initializes libcoap's memory management.
20 * This function must be called once before coap_malloc() can be used on
21 * constrained devices.
22 */
23 void coap_memory_init(void);
24 #endif /* WITH_LWIP */
25
26 /**
27 * Type specifiers for coap_malloc_type(). Memory objects can be typed to
28 * facilitate arrays of type objects to be used instead of dynamic memory
29 * management on constrained devices.
30 */
31 typedef enum {
32 COAP_STRING,
33 COAP_ATTRIBUTE_NAME,
34 COAP_ATTRIBUTE_VALUE,
35 COAP_PACKET,
36 COAP_NODE,
37 COAP_CONTEXT,
38 COAP_ENDPOINT,
39 COAP_PDU,
40 COAP_PDU_BUF,
41 COAP_RESOURCE,
42 COAP_RESOURCEATTR,
43 #ifdef HAVE_LIBTINYDTLS
44 COAP_DTLS_SESSION,
45 #endif
46 COAP_SESSION,
47 COAP_OPTLIST,
48 COAP_CACHE_KEY,
49 COAP_CACHE_ENTRY,
50 COAP_LG_XMIT,
51 COAP_LG_CRCV,
52 COAP_LG_SRCV,
53 } coap_memory_tag_t;
54
55 #ifndef WITH_LWIP
56
57 /**
58 * Allocates a chunk of @p size bytes and returns a pointer to the newly
59 * allocated memory. The @p type is used to select the appropriate storage
60 * container on constrained devices. The storage allocated by coap_malloc_type()
61 * must be released with coap_free_type().
62 *
63 * @param type The type of object to be stored.
64 * @param size The number of bytes requested.
65 * @return A pointer to the allocated storage or @c NULL on error.
66 */
67 void *coap_malloc_type(coap_memory_tag_t type, size_t size);
68
69 /**
70 * Reallocates a chunk @p p of bytes created by coap_malloc_type() or
71 * coap_realloc_type() and returns a pointer to the newly allocated memory of
72 * @p size.
73 * Only COAP_STRING type is supported.
74 *
75 * Note: If there is an error, @p p will separately need to be released by
76 * coap_free_type().
77 *
78 * @param type The type of object to be stored.
79 * @param p A pointer to memory that was allocated by coap_malloc_type().
80 * @param size The number of bytes requested.
81 * @return A pointer to the allocated storage or @c NULL on error.
82 */
83 void *coap_realloc_type(coap_memory_tag_t type, void *p, size_t size);
84
85 /**
86 * Releases the memory that was allocated by coap_malloc_type(). The type tag @p
87 * type must be the same that was used for allocating the object pointed to by
88 * @p .
89 *
90 * @param type The type of the object to release.
91 * @param p A pointer to memory that was allocated by coap_malloc_type().
92 */
93 void coap_free_type(coap_memory_tag_t type, void *p);
94
95 /**
96 * Wrapper function to coap_malloc_type() for backwards compatibility.
97 */
coap_malloc(size_t size)98 COAP_STATIC_INLINE void *coap_malloc(size_t size) {
99 return coap_malloc_type(COAP_STRING, size);
100 }
101
102 /**
103 * Wrapper function to coap_free_type() for backwards compatibility.
104 */
coap_free(void * object)105 COAP_STATIC_INLINE void coap_free(void *object) {
106 coap_free_type(COAP_STRING, object);
107 }
108
109 #endif /* not WITH_LWIP */
110
111 #ifdef WITH_LWIP
112
113 #include <lwip/memp.h>
114
115 /* no initialization needed with lwip (or, more precisely: lwip must be
116 * completely initialized anyway by the time coap gets active) */
coap_memory_init(void)117 COAP_STATIC_INLINE void coap_memory_init(void) {}
118
119 /* It would be nice to check that size equals the size given at the memp
120 * declaration, but i currently don't see a standard way to check that without
121 * sourcing the custom memp pools and becoming dependent of its syntax
122 */
123 #define coap_malloc_type(type, size) memp_malloc(MEMP_ ## type)
124 #define coap_free_type(type, p) memp_free(MEMP_ ## type, p)
125
126 /* Those are just here to make uri.c happy where string allocation has not been
127 * made conditional.
128 */
coap_malloc(size_t size)129 COAP_STATIC_INLINE void *coap_malloc(size_t size) {
130 LWIP_ASSERT("coap_malloc must not be used in lwIP", 0);
131 }
132
coap_free(void * pointer)133 COAP_STATIC_INLINE void coap_free(void *pointer) {
134 LWIP_ASSERT("coap_free must not be used in lwIP", 0);
135 }
136
137 #endif /* WITH_LWIP */
138
139 #endif /* COAP_MEM_H_ */
140