86 lines
2.7 KiB
C
86 lines
2.7 KiB
C
/** @file
|
|
* @brief Bluetooth "view" buffer abstraction
|
|
*/
|
|
|
|
/*
|
|
* Copyright (c) 2024 Nordic Semiconductor ASA
|
|
*
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*/
|
|
|
|
#ifndef ZEPHYR_SUBSYS_BLUETOOTH_HOST_BUF_VIEW_H_
|
|
#define ZEPHYR_SUBSYS_BLUETOOTH_HOST_BUF_VIEW_H_
|
|
|
|
#include <zephyr/net_buf.h>
|
|
|
|
|
|
struct bt_buf_view_meta {
|
|
struct net_buf *parent;
|
|
/* saves the data pointers while the parent buffer is locked. */
|
|
struct net_buf_simple backup;
|
|
};
|
|
|
|
/** @internal
|
|
*
|
|
* @brief Create a "view" or "window" into an existing buffer.
|
|
* - enforces one active view at a time per-buffer
|
|
* -> this restriction enables prepending data (ie. for headers)
|
|
* - forbids appending data to the view
|
|
* - pulls the size of the view from said buffer.
|
|
*
|
|
* The "virtual buffer" that is generated has to be allocated from a buffer
|
|
* pool. This is to allow refcounting and attaching a destroy callback. The
|
|
* configured size of the buffers in that pool should be zero-length.
|
|
*
|
|
* The user-data size is application-dependent, but should be minimized to save
|
|
* memory. user_data is not used by the view API.
|
|
*
|
|
* The view mechanism needs to store extra metadata in order to unlock the
|
|
* original buffer when the view is destroyed.
|
|
*
|
|
* The storage and allocation of the view buf pool and the view metadata is the
|
|
* application's responsibility.
|
|
*
|
|
* @note The `headroom` param is only used for __ASSERT(). The idea is that
|
|
* it's easier to debug a headroom assert failure at allocation time, rather
|
|
* than later down the line when a lower layer tries to add its headers and
|
|
* fails.
|
|
*
|
|
* @param view Uninitialized "View" buffer
|
|
* @param parent Buffer data is pulled from into `view`
|
|
* @param len Amount to pull
|
|
* @param meta Uninitialized metadata storage
|
|
*
|
|
* @return view if the operation was successful. NULL on error.
|
|
*/
|
|
struct net_buf *bt_buf_make_view(struct net_buf *view,
|
|
struct net_buf *parent,
|
|
size_t len,
|
|
struct bt_buf_view_meta *meta);
|
|
|
|
/** @internal
|
|
*
|
|
* @brief Check if `parent` has view.
|
|
*
|
|
* If `parent` has been passed to @ref bt_buf_make_view() and the resulting
|
|
* view buffer has not been destroyed.
|
|
*/
|
|
bool bt_buf_has_view(const struct net_buf *parent);
|
|
|
|
/** @internal
|
|
*
|
|
* @brief Destroy the view buffer
|
|
*
|
|
* Equivalent of @ref net_buf_destroy.
|
|
* It is mandatory to call this from the view pool's `destroy` callback.
|
|
*
|
|
* This frees the parent buffer, and allows calling @ref bt_buf_make_view again.
|
|
* The metadata is also freed for re-use.
|
|
*
|
|
* @param view View to destroy
|
|
* @param meta Meta that was given to @ref bt_buf_make_view
|
|
*/
|
|
void bt_buf_destroy_view(struct net_buf *view, struct bt_buf_view_meta *meta);
|
|
|
|
#endif /* ZEPHYR_SUBSYS_BLUETOOTH_HOST_BUF_VIEW_H_ */
|