1 /* 2 * Copyright (c) 2020 - 2023, 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_mgr_src.h 37 * @brief Buffer management on source side of a buffer of a nRF 802.15.4 serialization. 38 * 39 * Sending a buffer to a remote peer and then receiving asynchronous 40 * notification about that buffer from the remote peer is a common scenario in 41 * serialization. This module is intended for a local peer who needs to send 42 * a buffer to a remote peer. The existence of the buffer is out of scope of 43 * this module. Function @ref nrf_802154_buffer_mgr_src_add allows creation of 44 * a @c buffer_handle which can be sent with a buffer content to a remote peer. 45 * The remote peer can then reference the buffer in the local peer by providing 46 * the @c buffer_handle. The local peer can map a received @c buffer_handle to 47 * the original buffer pointer by a call to 48 * @ref nrf_802154_buffer_mgr_src_search_by_buffer_handle. 49 * When the local peer is done with given buffer it should call 50 * @ref nrf_802154_buffer_mgr_src_remove_by_buffer_handle. 51 * 52 * The source peer manages buffer existence by its own discretion. The buffer 53 * shall exist as long as @c buffer_handle to pointer mapping exists. 54 */ 55 56 #ifndef NRF_802154_BUFFER_MGR_SRC_H__ 57 #define NRF_802154_BUFFER_MGR_SRC_H__ 58 59 #include <stdbool.h> 60 #include <stdint.h> 61 62 #include "nrf_802154_kvmap.h" 63 64 /**@brief Type of a buffer manager object for a source peer. */ 65 typedef struct 66 { 67 /**@brief Map for holding source peer local buffer pointers. */ 68 nrf_802154_kvmap_t map; 69 } nrf_802154_buffer_mgr_src_t; 70 71 /**@brief Calculates number of bytes needed to store map. 72 * @param buffers_count Number of buffers to be tracked. 73 */ 74 #define NRF_802154_BUFFER_MGR_SRC_MAP_MEMSIZE(buffers_count) \ 75 NRF_802154_KVMAP_MEMORY_SIZE((buffers_count), sizeof(uint32_t), 0U) 76 77 /**@brief Defines instance of @ref nrf_802154_buffer_mgr_src_t with all necessary accompanying 78 * variables. 79 * 80 * Instance defined by this macro still needs 81 * to be initialized. See an example below: 82 * @code 83 * NRF_802154_BUFFER_MGR_SRC_INST_DECL(m_buffer_mgr_src, 10U); 84 * 85 * void foo(void) 86 * { 87 * NRF_802154_BUFFER_MGR_SRC_INIT(m_buffer_mgr_src) 88 * } 89 * @endcode 90 * 91 * @param name Identifier of an object of type @ref nrf_802154_buffer_mgr_src_t 92 * @param buffers_count Number of buffers the @c name object will be able to track. 93 */ 94 #define NRF_802154_BUFFER_MGR_SRC_INST_DECL(name, buffers_count) \ 95 nrf_802154_buffer_mgr_src_t name; \ 96 uint8_t name ## _map_mem[ \ 97 NRF_802154_BUFFER_MGR_SRC_MAP_MEMSIZE(buffers_count)] \ 98 __attribute__((aligned(4))); \ 99 const size_t name ## _buffers_count = (buffers_count); 100 101 /**@brief Provides extern complementary to @ref NRF_802154_BUFFER_MGR_SRC_INST_DECL. 102 * 103 * @param name Identifier of an object of type @ref nrf_802154_buffer_mgr_src_t 104 */ 105 #define NRF_802154_BUFFER_MGR_SRC_INST_DECL_EXTERN(name) \ 106 extern nrf_802154_buffer_mgr_src_t name 107 108 /**@brief @ref NRF_802154_BUFFER_MGR_SRC_INST_DECL but with static storage */ 109 #define NRF_802154_BUFFER_MGR_SRC_INST_DECL_STATIC(name, buffers_count) \ 110 static nrf_802154_buffer_mgr_src_t name; \ 111 static uint8_t name ## _map_mem[ \ 112 NRF_802154_BUFFER_MGR_SRC_MAP_MEMSIZE(buffers_count)] \ 113 __attribute__((aligned(4))); \ 114 static const size_t name ## _buffers_count = (buffers_count); 115 116 /**@brief Calls @ref nrf_802154_buffer_mgr_src_init for an object instantiated by 117 * @ref NRF_802154_BUFFER_MGR_SRC_INST_DECL. 118 * @param name Name of object instance introduced by a NRF_802154_BUFFER_MGR_SRC_INST_DECL 119 * (note: not a pointer) 120 */ 121 #define NRF_802154_BUFFER_MGR_SRC_INIT(name) \ 122 nrf_802154_buffer_mgr_src_init( \ 123 &name, \ 124 name ## _map_mem, \ 125 name ## _buffers_count) 126 127 /**@brief Initializes a source peer buffer manager. 128 * 129 * @param[out] p_obj Pointer to an object instance to initialize 130 * @param[in] p_map_memory Pointer to a memory buffer of size equal to 131 * @ref NRF_802154_BUFFER_MGR_SRC_MAP_MEMSIZE(@c buffers_count) 132 * @param[in] buffers_count Number of buffers the object @p p_obj will be able to track 133 * 134 * @sa @ref NRF_802154_BUFFER_MGR_SRC_INSTANCE_DECL, @ref NRF_802154_BUFFER_MGR_SRC_INIT 135 */ 136 void nrf_802154_buffer_mgr_src_init( 137 nrf_802154_buffer_mgr_src_t * p_obj, 138 void * p_map_memory, 139 size_t buffers_count); 140 141 /**@brief Adds a local memory buffer pointer to a buffer manager. 142 * 143 * @param[in,out] p_obj Pointer to a buffer manager object. 144 * @param[in] p_buffer Pointer to a buffer to track 145 * @param[out] p_buffer_handle A handle that can be used to reference the buffer pointed by 146 * @ref p_buffer in a remote side. 147 * 148 * @retval true Buffer added to tracking 149 * @retval false Out of memory 150 */ 151 bool nrf_802154_buffer_mgr_src_add( 152 nrf_802154_buffer_mgr_src_t * p_obj, 153 const void * p_buffer, 154 uint32_t * p_buffer_handle); 155 156 /**@brief Searches a local memory buffer pointer by a buffer handle. 157 * 158 * @param[in,out] p_obj Pointer to a buffer manager object. 159 * @param[in] buffer_handle Buffer handle obtained from @ref nrf_802154_buffer_mgr_src_add 160 * @param[out] pp_buffer Pointer to a local buffer pointer associated with buffer_handle 161 * 162 * @retval true Given @p buffer_handle has been found. The pointer to an associated buffer 163 * is available behind @p pp_buffer 164 * @retval false Given @p buffer_handle has not been found. 165 */ 166 bool nrf_802154_buffer_mgr_src_search_by_buffer_handle( 167 nrf_802154_buffer_mgr_src_t * p_obj, 168 uint32_t buffer_handle, 169 void ** pp_buffer); 170 171 /**@brief Removes a local memory buffer pointer from a buffer manager. 172 * 173 * @param[in,out] p_obj Pointer to a buffer manager object. 174 * @param[in] buffer_handle Buffer handle obtained from @ref nrf_802154_buffer_mgr_src_add 175 * 176 * @retval true Pointer has been removed. 177 * @retval false Pointer has not been found (but it does not exist in the 178 * buffer manager anyway). 179 */ 180 bool nrf_802154_buffer_mgr_src_remove_by_buffer_handle( 181 nrf_802154_buffer_mgr_src_t * p_obj, 182 uint32_t buffer_handle); 183 184 #endif // NRF_802154_BUFFER_MGR_SRC_H__ 185
