1 /*
2 * coap_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 /**
13 * @file coap_mem.h
14 * @brief CoAP memory handling
15 */
16
17 #ifndef COAP_MEM_H_
18 #define COAP_MEM_H_
19
20 #include "coap3/coap_oscore.h"
21 #include <stdlib.h>
22
23 #ifndef WITH_LWIP
24 /**
25 * Initializes libcoap's memory management.
26 * This function must be called once before coap_malloc() can be used on
27 * constrained devices.
28 */
29 void coap_memory_init(void);
30 #endif /* WITH_LWIP */
31
32 /**
33 * Type specifiers for coap_malloc_type(). Memory objects can be typed to
34 * facilitate arrays of type objects to be used instead of dynamic memory
35 * management on constrained devices.
36 */
37 typedef enum {
38 COAP_STRING,
39 COAP_ATTRIBUTE_NAME,
40 COAP_ATTRIBUTE_VALUE,
41 COAP_PACKET,
42 COAP_NODE,
43 COAP_CONTEXT,
44 COAP_ENDPOINT,
45 COAP_PDU,
46 COAP_PDU_BUF,
47 COAP_RESOURCE,
48 COAP_RESOURCEATTR,
49 COAP_DTLS_SESSION,
50 COAP_SESSION,
51 COAP_OPTLIST,
52 COAP_CACHE_KEY,
53 COAP_CACHE_ENTRY,
54 COAP_LG_XMIT,
55 COAP_LG_CRCV,
56 COAP_LG_SRCV,
57 COAP_DIGEST_CTX,
58 COAP_SUBSCRIPTION,
59 COAP_DTLS_CONTEXT,
60 COAP_OSCORE_COM,
61 COAP_OSCORE_SEN,
62 COAP_OSCORE_REC,
63 COAP_OSCORE_EX,
64 COAP_OSCORE_EP,
65 COAP_OSCORE_BUF,
66 COAP_COSE,
67 } coap_memory_tag_t;
68
69 #ifndef WITH_LWIP
70
71 /**
72 * Allocates a chunk of @p size bytes and returns a pointer to the newly
73 * allocated memory. The @p type is used to select the appropriate storage
74 * container on constrained devices. The storage allocated by coap_malloc_type()
75 * must be released with coap_free_type().
76 *
77 * @param type The type of object to be stored.
78 * @param size The number of bytes requested.
79 * @return A pointer to the allocated storage or @c NULL on error.
80 */
81 void *coap_malloc_type(coap_memory_tag_t type, size_t size);
82
83 /**
84 * Reallocates a chunk @p p of bytes created by coap_malloc_type() or
85 * coap_realloc_type() and returns a pointer to the newly allocated memory of
86 * @p size.
87 * Only COAP_STRING type is supported.
88 *
89 * Note: If there is an error, @p p will separately need to be released by
90 * coap_free_type().
91 *
92 * @param type The type of object to be stored.
93 * @param p A pointer to memory that was allocated by coap_malloc_type().
94 * @param size The number of bytes requested.
95 * @return A pointer to the allocated storage or @c NULL on error.
96 */
97 void *coap_realloc_type(coap_memory_tag_t type, void *p, size_t size);
98
99 /**
100 * Releases the memory that was allocated by coap_malloc_type(). The type tag @p
101 * type must be the same that was used for allocating the object pointed to by
102 * @p .
103 *
104 * @param type The type of the object to release.
105 * @param p A pointer to memory that was allocated by coap_malloc_type().
106 */
107 void coap_free_type(coap_memory_tag_t type, void *p);
108
109 /**
110 * Wrapper function to coap_malloc_type() for backwards compatibility.
111 */
112 COAP_STATIC_INLINE void *
coap_malloc(size_t size)113 coap_malloc(size_t size) {
114 return coap_malloc_type(COAP_STRING, size);
115 }
116
117 /**
118 * Wrapper function to coap_free_type() for backwards compatibility.
119 */
120 COAP_STATIC_INLINE void
coap_free(void * object)121 coap_free(void *object) {
122 coap_free_type(COAP_STRING, object);
123 }
124
125 #endif /* not WITH_LWIP */
126
127 #ifdef WITH_LWIP
128
129 #include <lwip/memp.h>
130
131 /* no initialization needed with lwip (or, more precisely: lwip must be
132 * completely initialized anyway by the time coap gets active) */
133 COAP_STATIC_INLINE void
coap_memory_init(void)134 coap_memory_init(void) {}
135
136 /* It would be nice to check that size equals the size given at the memp
137 * declaration, but i currently don't see a standard way to check that without
138 * sourcing the custom memp pools and becoming dependent of its syntax
139 */
140 #define coap_malloc_type(type, asize) \
141 (((asize) <= memp_pools[MEMP_ ## type]->size) ? \
142 memp_malloc(MEMP_ ## type) : NULL)
143 #define coap_free_type(type, p) memp_free(MEMP_ ## type, p)
144
145 /* As these are fixed size, return value if already defined */
146 #define coap_realloc_type(type, p, asize) \
147 ((p) ? ((asize) <= memp_pools[MEMP_ ## type]->size) ? (p) : NULL : coap_malloc_type(type, asize))
148
149 /* Those are just here to make uri.c happy where string allocation has not been
150 * made conditional.
151 */
152 COAP_STATIC_INLINE void *
coap_malloc(size_t size)153 coap_malloc(size_t size) {
154 (void)size;
155 LWIP_ASSERT("coap_malloc must not be used in lwIP", 0);
156 }
157
158 COAP_STATIC_INLINE void
coap_free(void * pointer)159 coap_free(void *pointer) {
160 (void)pointer;
161 LWIP_ASSERT("coap_free must not be used in lwIP", 0);
162 }
163
164 #endif /* WITH_LWIP */
165
166 #endif /* COAP_MEM_H_ */
167