/src/libcoap/include/coap3/coap_mem.h

Source
/*
 * coap_mem.h -- CoAP memory handling
 *
 * Copyright (C) 2010-2011,2014-2015 Olaf Bergmann <bergmann@tzi.org>
 *
 * SPDX-License-Identifier: BSD-2-Clause
 *
 * This file is part of the CoAP library libcoap. Please see README for terms
 * of use.
 */

/**
 * @file coap_mem.h
 * @brief CoAP memory handling
 */

#ifndef COAP_MEM_H_
#define COAP_MEM_H_

#include "coap3/coap_oscore.h"
#include "coap3/coap_proxy.h"

#ifdef __cplusplus
extern "C" {
#endif

/**
 * Type specifiers for coap_malloc_type(). Memory objects can be typed to
 * facilitate arrays of type objects to be used instead of dynamic memory
 * management on constrained devices.
 */
typedef enum {
  COAP_STRING,
  COAP_ATTRIBUTE_NAME,
  COAP_ATTRIBUTE_VALUE,
  COAP_PACKET,
  COAP_NODE,
  COAP_CONTEXT,
  COAP_ENDPOINT,
  COAP_PDU,
  COAP_PDU_BUF,
  COAP_RESOURCE,
  COAP_RESOURCEATTR,
  COAP_DTLS_SESSION,
  COAP_SESSION,
  COAP_OPTLIST,
  COAP_CACHE_KEY,
  COAP_CACHE_ENTRY,
  COAP_LG_XMIT,
  COAP_LG_CRCV,
  COAP_LG_SRCV,
  COAP_DIGEST_CTX,
  COAP_SUBSCRIPTION,
  COAP_DTLS_CONTEXT,
  COAP_OSCORE_COM,
  COAP_OSCORE_SEN,
  COAP_OSCORE_REC,
  COAP_OSCORE_EX,
  COAP_OSCORE_EP,
  COAP_OSCORE_BUF,
  COAP_COSE,
  COAP_MEM_TAG_LAST
} coap_memory_tag_t;

/**
 * Dumps the current usage of malloc'd memory types.
 *
 * Requires COAP_MEMORY_TYPE_TRACK to be defined to 1.
 *
 * @param log_level The logging level to use.
 */
void coap_dump_memory_type_counts(coap_log_t log_level);

#if ! defined(WITH_LWIP) || (defined(WITH_LWIP) && ! MEMP_USE_CUSTOM_POOLS && ! MEM_USE_POOLS)

/**
 * Initializes libcoap's memory management.
 * This function must be called once before coap_malloc() can be used on
 * constrained devices.
 */
void coap_memory_init(void);

/**
 * Allocates a chunk of @p size bytes and returns a pointer to the newly
 * allocated memory. The @p type is used to select the appropriate storage
 * container on constrained devices. The storage allocated by coap_malloc_type()
 * must be released with coap_free_type().
 *
 * @param type The type of object to be stored.
 * @param size The number of bytes requested.
 * @return     A pointer to the allocated storage or @c NULL on error.
 */
void *coap_malloc_type(coap_memory_tag_t type, size_t size);

/**
 * Reallocates a chunk @p p of bytes created by coap_malloc_type() or
 * coap_realloc_type() and returns a pointer to the newly allocated memory of
 * @p size.
 * Only COAP_STRING type is supported.
 *
 * Note: If there is an error, @p p will separately need to be released by
 * coap_free_type().
 *
 * @param type The type of object to be stored.
 * @param p    A pointer to memory that was allocated by coap_malloc_type().
 * @param size The number of bytes requested.
 * @return     A pointer to the allocated storage or @c NULL on error.
 */
void *coap_realloc_type(coap_memory_tag_t type, void *p, size_t size);

/**
 * Releases the memory that was allocated by coap_malloc_type(). The type tag @p
 * type must be the same that was used for allocating the object pointed to by
 * @p .
 *
 * @param type The type of the object to release.
 * @param p    A pointer to memory that was allocated by coap_malloc_type().
 */
void coap_free_type(coap_memory_tag_t type, void *p);

/**
 * Wrapper function to coap_malloc_type() for backwards compatibility.
 */
COAP_STATIC_INLINE void *
coap_malloc(size_t size) {
  return coap_malloc_type(COAP_STRING, size);
}

/**
 * Wrapper function to coap_free_type() for backwards compatibility.
 */
COAP_STATIC_INLINE void
coap_free(void *object) {
  coap_free_type(COAP_STRING, object);
}

#else /* WITH_LWIP && (MEMP_USE_CUSTOM_POOLS || MEM_USE_POOLS) */

#include <lwip/memp.h>

/* no initialization needed with lwip (or, more precisely: lwip must be
 * completely initialized anyway by the time coap gets active)  */
COAP_STATIC_INLINE void
coap_memory_init(void) {}

#if MEMP_STATS
COAP_STATIC_INLINE void *
coap_malloc_error(uint16_t *err) {
  (*err)++;
  return NULL;
}
#endif /* MEMP_STATS */
/*
 * It would be nice to check that size equals the size given at the memp
 * declaration, but I currently don't see a standard way to check that without
 * sourcing the custom memp pools and becoming dependent of its syntax
 */
#if MEM_USE_POOLS

void *coap_malloc_type_string(size_t size);

void *coap_realloc_type_string(void *p, size_t size);

void coap_free_type_string(void *p);

#if MEMP_STATS

#define coap_malloc_type(type, asize) \
  (type == COAP_STRING) ? coap_malloc_type_string(asize) : \
  (((asize) <= memp_pools[MEMP_ ## type]->size) ? \
   memp_malloc(MEMP_ ## type) : coap_malloc_error(&memp_pools[MEMP_ ## type]->stats->err))

#else /* ! MEMP_STATS */

#define coap_malloc_type(type, asize) \
  (type == COAP_STRING) ? coap_malloc_type_string(asize) : \
  (((asize) <= memp_pools[MEMP_ ## type]->size) ? \
   memp_malloc(MEMP_ ## type) : NULL)
#endif /* ! MEMP_STATS */

#define coap_free_type(type, p) \
  (type == COAP_STRING) ? coap_free_type_string(p) : \
  memp_free(MEMP_ ## type, p)

/* As these are fixed size, return value if already defined */
#define coap_realloc_type(type, p, asize) \
  (type == COAP_STRING) ? coap_realloc_type_string(p, asize) : \
  ((p) ? ((asize) <= memp_pools[MEMP_ ## type]->size) ? (p) : NULL : coap_malloc_type(type, asize))

#else /* ! MEM_USE_POOLS */

#if MEMP_STATS

#define coap_malloc_type(type, asize) \
  (((asize) <= memp_pools[MEMP_ ## type]->size) ? \
   memp_malloc(MEMP_ ## type) : coap_malloc_error(&memp_pools[MEMP_ ## type]->stats->err))

#else /* ! MEMP_STATS */

#define coap_malloc_type(type, asize) \
  (((asize) <= memp_pools[MEMP_ ## type]->size) ? \
   memp_malloc(MEMP_ ## type) : NULL)
#endif /* ! MEMP_STATS */

#define coap_free_type(type, p) memp_free(MEMP_ ## type, p)

/* As these are fixed size, return value if already defined */
#define coap_realloc_type(type, p, asize) \
  ((p) ? ((asize) <= memp_pools[MEMP_ ## type]->size) ? (p) : NULL : coap_malloc_type(type, asize))
#endif /* MEM_USE_POOLS */

/* Those are just here to make uri.c happy where string allocation has not been
 * made conditional.
 */
COAP_STATIC_INLINE void *
coap_malloc(size_t size) {
  (void)size;
  LWIP_ASSERT("coap_malloc must not be used in lwIP", 0);
  return NULL;
}

COAP_STATIC_INLINE void
coap_free(void *pointer) {
  (void)pointer;
  LWIP_ASSERT("coap_free must not be used in lwIP", 0);
}

#endif /* WITH_LWIP && (MEMP_USE_CUSTOM_POOLS || MEM_USE_POOLS) */

#ifdef __cplusplus
}
#endif

#endif /* COAP_MEM_H_ */

Coverage Report

Created: 2026-06-10 06:32

Line	Count	Source
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 "coap3/coap_proxy.h"
22
23		#ifdef __cplusplus
24		extern "C" {
25		#endif
26
27		/**
28		* Type specifiers for coap_malloc_type(). Memory objects can be typed to
29		* facilitate arrays of type objects to be used instead of dynamic memory
30		* management on constrained devices.
31		*/
32		typedef enum {
33		COAP_STRING,
34		COAP_ATTRIBUTE_NAME,
35		COAP_ATTRIBUTE_VALUE,
36		COAP_PACKET,
37		COAP_NODE,
38		COAP_CONTEXT,
39		COAP_ENDPOINT,
40		COAP_PDU,
41		COAP_PDU_BUF,
42		COAP_RESOURCE,
43		COAP_RESOURCEATTR,
44		COAP_DTLS_SESSION,
45		COAP_SESSION,
46		COAP_OPTLIST,
47		COAP_CACHE_KEY,
48		COAP_CACHE_ENTRY,
49		COAP_LG_XMIT,
50		COAP_LG_CRCV,
51		COAP_LG_SRCV,
52		COAP_DIGEST_CTX,
53		COAP_SUBSCRIPTION,
54		COAP_DTLS_CONTEXT,
55		COAP_OSCORE_COM,
56		COAP_OSCORE_SEN,
57		COAP_OSCORE_REC,
58		COAP_OSCORE_EX,
59		COAP_OSCORE_EP,
60		COAP_OSCORE_BUF,
61		COAP_COSE,
62		COAP_MEM_TAG_LAST
63		} coap_memory_tag_t;
64
65		/**
66		* Dumps the current usage of malloc'd memory types.
67		*
68		* Requires COAP_MEMORY_TYPE_TRACK to be defined to 1.
69		*
70		* @param log_level The logging level to use.
71		*/
72		void coap_dump_memory_type_counts(coap_log_t log_level);
73
74		#if ! defined(WITH_LWIP) \|\| (defined(WITH_LWIP) && ! MEMP_USE_CUSTOM_POOLS && ! MEM_USE_POOLS)
75
76		/**
77		* Initializes libcoap's memory management.
78		* This function must be called once before coap_malloc() can be used on
79		* constrained devices.
80		*/
81		void coap_memory_init(void);
82
83		/**
84		* Allocates a chunk of @p size bytes and returns a pointer to the newly
85		* allocated memory. The @p type is used to select the appropriate storage
86		* container on constrained devices. The storage allocated by coap_malloc_type()
87		* must be released with coap_free_type().
88		*
89		* @param type The type of object to be stored.
90		* @param size The number of bytes requested.
91		* @return A pointer to the allocated storage or @c NULL on error.
92		*/
93		void *coap_malloc_type(coap_memory_tag_t type, size_t size);
94
95		/**
96		* Reallocates a chunk @p p of bytes created by coap_malloc_type() or
97		* coap_realloc_type() and returns a pointer to the newly allocated memory of
98		* @p size.
99		* Only COAP_STRING type is supported.
100		*
101		* Note: If there is an error, @p p will separately need to be released by
102		* coap_free_type().
103		*
104		* @param type The type of object to be stored.
105		* @param p A pointer to memory that was allocated by coap_malloc_type().
106		* @param size The number of bytes requested.
107		* @return A pointer to the allocated storage or @c NULL on error.
108		*/
109		void coap_realloc_type(coap_memory_tag_t type, void p, size_t size);
110
111		/**
112		* Releases the memory that was allocated by coap_malloc_type(). The type tag @p
113		* type must be the same that was used for allocating the object pointed to by
114		* @p .
115		*
116		* @param type The type of the object to release.
117		* @param p A pointer to memory that was allocated by coap_malloc_type().
118		*/
119		void coap_free_type(coap_memory_tag_t type, void *p);
120
121		/**
122		* Wrapper function to coap_malloc_type() for backwards compatibility.
123		*/
124		COAP_STATIC_INLINE void *
125	0	coap_malloc(size_t size) {
126	0	return coap_malloc_type(COAP_STRING, size);
127	0	} Unexecuted instantiation: observe_target.c:coap_malloc Unexecuted instantiation: coap_fuzz_helper.c:coap_malloc Unexecuted instantiation: coap_address.c:coap_malloc Unexecuted instantiation: coap_debug.c:coap_malloc Unexecuted instantiation: coap_encode.c:coap_malloc Unexecuted instantiation: coap_event.c:coap_malloc Unexecuted instantiation: coap_mem.c:coap_malloc Unexecuted instantiation: coap_net.c:coap_malloc Unexecuted instantiation: coap_netif.c:coap_malloc Unexecuted instantiation: coap_openssl.c:coap_malloc Unexecuted instantiation: coap_option.c:coap_malloc Unexecuted instantiation: coap_oscore.c:coap_malloc Unexecuted instantiation: coap_pdu.c:coap_malloc Unexecuted instantiation: coap_proxy.c:coap_malloc Unexecuted instantiation: coap_prng.c:coap_malloc Unexecuted instantiation: coap_resource.c:coap_malloc Unexecuted instantiation: coap_session.c:coap_malloc Unexecuted instantiation: coap_str.c:coap_malloc Unexecuted instantiation: coap_strm_posix.c:coap_malloc Unexecuted instantiation: coap_subscribe.c:coap_malloc Unexecuted instantiation: coap_time.c:coap_malloc Unexecuted instantiation: coap_uri.c:coap_malloc Unexecuted instantiation: coap_ws.c:coap_malloc Unexecuted instantiation: oscore.c:coap_malloc Unexecuted instantiation: oscore_cbor.c:coap_malloc Unexecuted instantiation: oscore_context.c:coap_malloc Unexecuted instantiation: oscore_cose.c:coap_malloc Unexecuted instantiation: oscore_crypto.c:coap_malloc Unexecuted instantiation: coap_async.c:coap_malloc Unexecuted instantiation: coap_block.c:coap_malloc Unexecuted instantiation: coap_cache.c:coap_malloc Unexecuted instantiation: coap_dgrm_posix.c:coap_malloc Unexecuted instantiation: coap_dtls.c:coap_malloc Unexecuted instantiation: coap_io.c:coap_malloc Unexecuted instantiation: coap_io_posix.c:coap_malloc Unexecuted instantiation: coap_layers.c:coap_malloc
128
129		/**
130		* Wrapper function to coap_free_type() for backwards compatibility.
131		*/
132		COAP_STATIC_INLINE void
133	0	coap_free(void *object) {
134	0	coap_free_type(COAP_STRING, object);
135	0	} Unexecuted instantiation: observe_target.c:coap_free Unexecuted instantiation: coap_fuzz_helper.c:coap_free Unexecuted instantiation: coap_address.c:coap_free Unexecuted instantiation: coap_debug.c:coap_free Unexecuted instantiation: coap_encode.c:coap_free Unexecuted instantiation: coap_event.c:coap_free Unexecuted instantiation: coap_mem.c:coap_free Unexecuted instantiation: coap_net.c:coap_free Unexecuted instantiation: coap_netif.c:coap_free Unexecuted instantiation: coap_openssl.c:coap_free Unexecuted instantiation: coap_option.c:coap_free Unexecuted instantiation: coap_oscore.c:coap_free Unexecuted instantiation: coap_pdu.c:coap_free Unexecuted instantiation: coap_proxy.c:coap_free Unexecuted instantiation: coap_prng.c:coap_free Unexecuted instantiation: coap_resource.c:coap_free Unexecuted instantiation: coap_session.c:coap_free Unexecuted instantiation: coap_str.c:coap_free Unexecuted instantiation: coap_strm_posix.c:coap_free Unexecuted instantiation: coap_subscribe.c:coap_free Unexecuted instantiation: coap_time.c:coap_free Unexecuted instantiation: coap_uri.c:coap_free Unexecuted instantiation: coap_ws.c:coap_free Unexecuted instantiation: oscore.c:coap_free Unexecuted instantiation: oscore_cbor.c:coap_free Unexecuted instantiation: oscore_context.c:coap_free Unexecuted instantiation: oscore_cose.c:coap_free Unexecuted instantiation: oscore_crypto.c:coap_free Unexecuted instantiation: coap_async.c:coap_free Unexecuted instantiation: coap_block.c:coap_free Unexecuted instantiation: coap_cache.c:coap_free Unexecuted instantiation: coap_dgrm_posix.c:coap_free Unexecuted instantiation: coap_dtls.c:coap_free Unexecuted instantiation: coap_io.c:coap_free Unexecuted instantiation: coap_io_posix.c:coap_free Unexecuted instantiation: coap_layers.c:coap_free
136
137		#else /* WITH_LWIP && (MEMP_USE_CUSTOM_POOLS \|\| MEM_USE_POOLS) */
138
139		#include <lwip/memp.h>
140
141		/* no initialization needed with lwip (or, more precisely: lwip must be
142		* completely initialized anyway by the time coap gets active) */
143		COAP_STATIC_INLINE void
144		coap_memory_init(void) {}
145
146		#if MEMP_STATS
147		COAP_STATIC_INLINE void *
148		coap_malloc_error(uint16_t *err) {
149		(*err)++;
150		return NULL;
151		}
152		#endif /* MEMP_STATS */
153		/*
154		* It would be nice to check that size equals the size given at the memp
155		* declaration, but I currently don't see a standard way to check that without
156		* sourcing the custom memp pools and becoming dependent of its syntax
157		*/
158		#if MEM_USE_POOLS
159
160		void *coap_malloc_type_string(size_t size);
161
162		void coap_realloc_type_string(void p, size_t size);
163
164		void coap_free_type_string(void *p);
165
166		#if MEMP_STATS
167
168		#define coap_malloc_type(type, asize) \
169		(type == COAP_STRING) ? coap_malloc_type_string(asize) : \
170		(((asize) <= memp_pools[MEMP_ ## type]->size) ? \
171		memp_malloc(MEMP_ ## type) : coap_malloc_error(&memp_pools[MEMP_ ## type]->stats->err))
172
173		#else /* ! MEMP_STATS */
174
175		#define coap_malloc_type(type, asize) \
176		(type == COAP_STRING) ? coap_malloc_type_string(asize) : \
177		(((asize) <= memp_pools[MEMP_ ## type]->size) ? \
178		memp_malloc(MEMP_ ## type) : NULL)
179		#endif /* ! MEMP_STATS */
180
181		#define coap_free_type(type, p) \
182		(type == COAP_STRING) ? coap_free_type_string(p) : \
183		memp_free(MEMP_ ## type, p)
184
185		/* As these are fixed size, return value if already defined */
186		#define coap_realloc_type(type, p, asize) \
187		(type == COAP_STRING) ? coap_realloc_type_string(p, asize) : \
188		((p) ? ((asize) <= memp_pools[MEMP_ ## type]->size) ? (p) : NULL : coap_malloc_type(type, asize))
189
190		#else /* ! MEM_USE_POOLS */
191
192		#if MEMP_STATS
193
194		#define coap_malloc_type(type, asize) \
195		(((asize) <= memp_pools[MEMP_ ## type]->size) ? \
196		memp_malloc(MEMP_ ## type) : coap_malloc_error(&memp_pools[MEMP_ ## type]->stats->err))
197
198		#else /* ! MEMP_STATS */
199
200		#define coap_malloc_type(type, asize) \
201		(((asize) <= memp_pools[MEMP_ ## type]->size) ? \
202		memp_malloc(MEMP_ ## type) : NULL)
203		#endif /* ! MEMP_STATS */
204
205		#define coap_free_type(type, p) memp_free(MEMP_ ## type, p)
206
207		/* As these are fixed size, return value if already defined */
208		#define coap_realloc_type(type, p, asize) \
209		((p) ? ((asize) <= memp_pools[MEMP_ ## type]->size) ? (p) : NULL : coap_malloc_type(type, asize))
210		#endif /* MEM_USE_POOLS */
211
212		/* Those are just here to make uri.c happy where string allocation has not been
213		* made conditional.
214		*/
215		COAP_STATIC_INLINE void *
216		coap_malloc(size_t size) {
217		(void)size;
218		LWIP_ASSERT("coap_malloc must not be used in lwIP", 0);
219		return NULL;
220		}
221
222		COAP_STATIC_INLINE void
223		coap_free(void *pointer) {
224		(void)pointer;
225		LWIP_ASSERT("coap_free must not be used in lwIP", 0);
226		}
227
228		#endif /* WITH_LWIP && (MEMP_USE_CUSTOM_POOLS \|\| MEM_USE_POOLS) */
229
230		#ifdef __cplusplus
231		}
232		#endif
233
234		#endif /* COAP_MEM_H_ */