1 /** @file 2 * @brief Bluetooth "view" buffer abstraction 3 */ 4 5 /* 6 * Copyright (c) 2024 Nordic Semiconductor ASA 7 * 8 * SPDX-License-Identifier: Apache-2.0 9 */ 10 11 #ifndef ZEPHYR_SUBSYS_BLUETOOTH_HOST_BUF_VIEW_H_ 12 #define ZEPHYR_SUBSYS_BLUETOOTH_HOST_BUF_VIEW_H_ 13 14 #include <zephyr/net/buf.h> 15 16 17 struct bt_buf_view_meta { 18 struct net_buf *parent; 19 /* saves the data pointers while the parent buffer is locked. */ 20 struct net_buf_simple backup; 21 }; 22 23 /** @internal 24 * 25 * @brief Create a "view" or "window" into an existing buffer. 26 * - enforces one active view at a time per-buffer 27 * -> this restriction enables prepending data (ie. for headers) 28 * - forbids appending data to the view 29 * - pulls the size of the view from said buffer. 30 * 31 * The "virtual buffer" that is generated has to be allocated from a buffer 32 * pool. This is to allow refcounting and attaching a destroy callback. The 33 * configured size of the buffers in that pool should be zero-length. 34 * 35 * The user-data size is application-dependent, but should be minimized to save 36 * memory. user_data is not used by the view API. 37 * 38 * The view mechanism needs to store extra metadata in order to unlock the 39 * original buffer when the view is destroyed. 40 * 41 * The storage and allocation of the view buf pool and the view metadata is the 42 * application's responsibility. 43 * 44 * @note The `headroom` param is only used for __ASSERT(). The idea is that 45 * it's easier to debug a headroom assert failure at allocation time, rather 46 * than later down the line when a lower layer tries to add its headers and 47 * fails. 48 * 49 * @param view Uninitialized "View" buffer 50 * @param parent Buffer data is pulled from into `view` 51 * @param len Amount to pull 52 * @param meta Uninitialized metadata storage 53 * 54 * @return view if the operation was successful. NULL on error. 55 */ 56 struct net_buf *bt_buf_make_view(struct net_buf *view, 57 struct net_buf *parent, 58 size_t len, 59 struct bt_buf_view_meta *meta); 60 61 /** @internal 62 * 63 * @brief Check if `parent` has view. 64 * 65 * If `parent` has been passed to @ref bt_buf_make_view() and the resulting 66 * view buffer has not been destroyed. 67 */ 68 bool bt_buf_has_view(const struct net_buf *parent); 69 70 /** @internal 71 * 72 * @brief Destroy the view buffer 73 * 74 * Equivalent of @ref net_buf_destroy. 75 * It is mandatory to call this from the view pool's `destroy` callback. 76 * 77 * This frees the parent buffer, and allows calling @ref bt_buf_make_view again. 78 * The metadata is also freed for re-use. 79 * 80 * @param view View to destroy 81 * @param meta Meta that was given to @ref bt_buf_make_view 82 */ 83 void bt_buf_destroy_view(struct net_buf *view, struct bt_buf_view_meta *meta); 84 85 #endif /* ZEPHYR_SUBSYS_BLUETOOTH_HOST_BUF_VIEW_H_ */ 86
