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 */
29void 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 */
37typedef 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 */
81void *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 */
97void *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 */
107void coap_free_type(coap_memory_tag_t type, void *p);
108
109/**
110 * Wrapper function to coap_malloc_type() for backwards compatibility.
111 */
112COAP_STATIC_INLINE void *
113coap_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 */
120COAP_STATIC_INLINE void
121coap_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)  */
133COAP_STATIC_INLINE void
134coap_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 */
152COAP_STATIC_INLINE void *
153coap_malloc(size_t size) {
154  (void)size;
155  LWIP_ASSERT("coap_malloc must not be used in lwIP", 0);
156}
157
158COAP_STATIC_INLINE void
159coap_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