1 /*
2 * Copyright (c) 2020, Nordic Semiconductor ASA
3 * All rights reserved.
4 *
5 * SPDX-License-Identifier: BSD-3-Clause
6 *
7 * Redistribution and use in source and binary forms, with or without
8 * modification, are permitted provided that the following conditions are met:
9 *
10 * 1. Redistributions of source code must retain the above copyright notice, this
11 * list of conditions and the following disclaimer.
12 *
13 * 2. Redistributions in binary form must reproduce the above copyright
14 * notice, this list of conditions and the following disclaimer in the
15 * documentation and/or other materials provided with the distribution.
16 *
17 * 3. Neither the name of Nordic Semiconductor ASA nor the names of its
18 * contributors may be used to endorse or promote products derived from this
19 * software without specific prior written permission.
20 *
21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
22 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 * IMPLIED WARRANTIES OF MERCHANTABILITY, AND FITNESS FOR A PARTICULAR PURPOSE
24 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
25 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
26 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
27 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
28 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
29 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
30 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
31 * POSSIBILITY OF SUCH DAMAGE.
32 *
33 */
34
35 /**
36 * @file nrf_802154_buffer_allocator.h
37 * @brief Buffer allocation for 802.15.4 receptions and transmissions.
38 */
39
40 #ifndef NRF_802154_BUFFER_ALLOCATOR_H__
41 #define NRF_802154_BUFFER_ALLOCATOR_H__
42
43 #include <stdbool.h>
44 #include <stddef.h>
45 #include <stdint.h>
46
47 /**
48 * @brief Default length of a buffer allocated by the buffer allocation mechanism.
49 *
50 * The buffer should be able to store the longest possible 802.15.4 packet.
51 */
52 #define NRF_802154_BUFFER_ALLOCATOR_DEFAULT_BUFFER_LEN 128
53
54 /**@brief Calculates byte size of memory required to store a buffer allocator.
55 *
56 * Example:
57 * @code
58 * static uint8_t m_memory[NRF_802154_BUFFER_ALLOCATOR_MEMORY_SIZE(10)];
59 * static nrf_802154_buffer_allocator_t m_buffer_allocator;
60 *
61 * nrf_802154_buffer_allocator_init(&m_buffer_allocator, m_memory, sizeof(m_memory));
62 * @endcode
63 */
64 #define NRF_802154_BUFFER_ALLOCATOR_MEMORY_SIZE(capacity) \
65 ((capacity) * (sizeof(nrf_802154_buffer_t)))
66
67 /** @brief Structure representing a buffer. */
68 typedef struct
69 {
70 /** @brief Stored data. */
71 uint8_t data[NRF_802154_BUFFER_ALLOCATOR_DEFAULT_BUFFER_LEN];
72 /** @brief Flag indicating if a buffer is currently in use. */
73 volatile bool taken;
74 } nrf_802154_buffer_t;
75
76 /** @brief Structure representing a buffer allocator. */
77 typedef struct
78 {
79 /** @brief Pointer to a memory used to store buffers. */
80 void * p_memory;
81 /** @brief Maximum number of buffers the buffer allocator instance is able to store. */
82 size_t capacity;
83 } nrf_802154_buffer_allocator_t;
84
85 /**
86 * @brief Initializes a buffer allocator instance.
87 *
88 * @param[out] p_obj Pointer to an object to initialize.
89 * The pointed object should persist as long as the buffer allocator
90 * is in use. Cannot be NULL.
91 * @param[in] p_memory Pointer to a memory to be used as to store buffers.
92 * Memory pointed by this pointer should persist as long as
93 * the buffer allocator pointed by @p p_obj is in use.
94 * Cannot be NULL (with exception, when memsize is 0)
95 * @param[in] memsize Size of the memory pointed by @p p_memory. When defining
96 * storage you can use @ref NRF_802154_BUFFER_ALLOCATOR_MEMORY_SIZE
97 * helper macro.
98 */
99 void nrf_802154_buffer_allocator_init(nrf_802154_buffer_allocator_t * p_obj,
100 void * p_memory,
101 size_t memsize);
102
103 /**
104 * @brief Allocates buffer for 802.15.4 reception or transmission.
105 *
106 * @param[in] p_obj Pointer to a buffer allocator that stores the buffer pool to allocate from.
107 *
108 * @return Pointer to allocated buffer or NULL if no buffer could be allocated.
109 */
110 void * nrf_802154_buffer_allocator_alloc(const nrf_802154_buffer_allocator_t * p_obj);
111
112 /**
113 * @brief Frees buffer allocated for 802.15.4 reception or transmission.
114 *
115 * @param[in] p_obj Pointer to a buffer allocator that stores the buffer pool to free from.
116 * @param[in] p_buffer Pointer to a buffer to free.
117 *
118 * @note This function should be used complementary to @ref nrf_802154_buffer_allocator_alloc.
119 */
120 void nrf_802154_buffer_allocator_free(const nrf_802154_buffer_allocator_t * p_obj, void * p_buffer);
121
122 /**
123 * @brief Gets total number of buffers a buffer allocator can store.
124 *
125 * @param[in] p_obj Pointer to a buffer allocator to check.
126 *
127 * @return Number of buffers a buffer allocator can store.
128 */
nrf_802154_buffer_allocator_capacity(const nrf_802154_buffer_allocator_t * p_obj)129 static inline size_t nrf_802154_buffer_allocator_capacity(
130 const nrf_802154_buffer_allocator_t * p_obj)
131 {
132 return p_obj->capacity;
133 }
134
135 #endif // NRF_802154_BUFFER_ALLOCATOR_H__
136
