Bluetooth: Add doxygen documentation for buf.h
Change-Id: Ia60227e9f960f9563c82cdc4a044a2f9a538331c Signed-off-by: Johan Hedberg <johan.hedberg@intel.com>
This commit is contained in:
parent
f77d80121e
commit
5a72e9aaaa
1 changed files with 126 additions and 35 deletions
|
@ -1,4 +1,6 @@
|
|||
/* buf.h - Bluetooth buffer management */
|
||||
/*! @file
|
||||
* @brief Bluetooth buffer management.
|
||||
*/
|
||||
|
||||
/*
|
||||
* Copyright (c) 2015 Intel Corporation
|
||||
|
@ -35,41 +37,45 @@
|
|||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
/* The biggest foreseeable buffer size requirement right now comes from
|
||||
* the Bluetooth 4.2 SMP MTU which is 65. This then become 65 + 4 (L2CAP
|
||||
* header) + 4 (ACL header) + 1 (H4 header) = 74. This also covers the
|
||||
* biggest HCI commands and events which are a bit under the 70 byte
|
||||
* mark.
|
||||
/*! @def BT_BUF_MAX_DATA
|
||||
* @brief Maximum amount of data that can fit in a buffer.
|
||||
*
|
||||
* The biggest foreseeable buffer size requirement right now comes from
|
||||
* the Bluetooth 4.2 SMP MTU which is 65. This then become 65 + 4 (L2CAP
|
||||
* header) + 4 (ACL header) + 1 (H4 header) = 74. This also covers the
|
||||
* biggest HCI commands and events which are a bit under the 70 byte
|
||||
* mark.
|
||||
*/
|
||||
#define BT_BUF_MAX_DATA 74
|
||||
|
||||
/* Type of data contained in this buffer */
|
||||
/*! Type of data contained in a buffer */
|
||||
enum bt_buf_type {
|
||||
BT_CMD, /* HCI command */
|
||||
BT_EVT, /* HCI event */
|
||||
BT_ACL_OUT, /* Outgoing ACL data */
|
||||
BT_ACL_IN, /* Incoming ACL data */
|
||||
BT_DUMMY = BT_CMD, /* Only used for waking up fibers */
|
||||
BT_CMD, /*! HCI command */
|
||||
BT_EVT, /*! HCI event */
|
||||
BT_ACL_OUT, /*! Outgoing ACL data */
|
||||
BT_ACL_IN, /*! Incoming ACL data */
|
||||
BT_DUMMY = BT_CMD, /*! Only used for waking up fibers */
|
||||
};
|
||||
|
||||
/* HCI command specific info */
|
||||
/*! HCI command specific information */
|
||||
struct bt_buf_hci_data {
|
||||
/* Used by bt_hci_cmd_send_sync. Initially contains the waiting
|
||||
* semaphore, as the semaphore is given back contains the bt_buf
|
||||
* for the return parameters.
|
||||
/*! Used by bt_hci_cmd_send_sync. Initially contains the waiting
|
||||
* semaphore, as the semaphore is given back contains the bt_buf
|
||||
* for the return parameters.
|
||||
*/
|
||||
void *sync;
|
||||
|
||||
/* The command OpCode that the buffer contains */
|
||||
/*! The command OpCode that the buffer contains */
|
||||
uint16_t opcode;
|
||||
};
|
||||
|
||||
/*! ACL data buffer specific information */
|
||||
struct bt_buf_acl_data {
|
||||
uint16_t handle;
|
||||
};
|
||||
|
||||
struct bt_buf {
|
||||
/* FIFO uses first 4 bytes itself, reserve space */
|
||||
/*! FIFO uses first 4 bytes itself, reserve space */
|
||||
int __unused;
|
||||
|
||||
union {
|
||||
|
@ -77,51 +83,136 @@ struct bt_buf {
|
|||
struct bt_buf_acl_data acl;
|
||||
};
|
||||
|
||||
/* Buffer data variables */
|
||||
/*! Pointer to the start of data in the buffer. */
|
||||
uint8_t *data;
|
||||
|
||||
/*! Length of the data behind the data pointer. */
|
||||
uint8_t len;
|
||||
|
||||
uint8_t ref:5, /* Reference count */
|
||||
type:3; /* Type of data contained in the buffer */
|
||||
uint8_t ref:5, /*! Reference count */
|
||||
type:3; /*! Type of data contained in the buffer */
|
||||
|
||||
/*! The full available buffer. */
|
||||
uint8_t buf[BT_BUF_MAX_DATA];
|
||||
};
|
||||
|
||||
/* Get buffer from the available buffers pool with specified type and
|
||||
* reserved headroom.
|
||||
/*! @brief Get a new buffer from the pool.
|
||||
*
|
||||
* Get buffer from the available buffers pool with specified type and
|
||||
* reserved headroom.
|
||||
*
|
||||
* @param type Buffer type.
|
||||
* @param reserve_head How much headroom to reserve.
|
||||
*
|
||||
* @return New buffer or NULL if out of buffers.
|
||||
*
|
||||
* @warning If there are no available buffers and the function is
|
||||
* called from a task or fiber the call will block until a buffer
|
||||
* becomes available in the pool.
|
||||
*/
|
||||
struct bt_buf *bt_buf_get(enum bt_buf_type type, size_t reserve_head);
|
||||
|
||||
/* Place buffer back into the available buffers pool */
|
||||
/*! @brief Decrements the reference count of a buffer.
|
||||
*
|
||||
* Decrements the reference count of a buffer and puts it back into the
|
||||
* pool if the count reaches zero.
|
||||
*
|
||||
* @param buf Buffer.
|
||||
*/
|
||||
void bt_buf_put(struct bt_buf *buf);
|
||||
|
||||
/* Increment the reference count of a buffer */
|
||||
/*! Increment the reference count of a buffer.
|
||||
*
|
||||
* Increment the reference count of a buffer.
|
||||
*
|
||||
* @param buf Buffer.
|
||||
*/
|
||||
struct bt_buf *bt_buf_hold(struct bt_buf *buf);
|
||||
|
||||
/* Prepare data to be added at the end of the buffer */
|
||||
/*! @brief Prepare data to be added at the end of the buffer
|
||||
*
|
||||
* Increments the data length of a buffer to account for more data
|
||||
* at the end.
|
||||
*
|
||||
* @param buf Buffer to update.
|
||||
* @param len Number of bytes to increment the length with.
|
||||
*
|
||||
* @return The original tail of the buffer.
|
||||
*/
|
||||
void *bt_buf_add(struct bt_buf *buf, size_t len);
|
||||
|
||||
/* Push data to the beginning of the buffer */
|
||||
/*! @brief Push data to the beginning of the buffer.
|
||||
*
|
||||
* Modifies the data pointer and buffer length to account for more data
|
||||
* in the beginning of the buffer.
|
||||
*
|
||||
* @param buf Buffer to update.
|
||||
* @param len Number of bytes to add to the beginning.
|
||||
*
|
||||
* @return The new beginning of the buffer data.
|
||||
*/
|
||||
void *bt_buf_push(struct bt_buf *buf, size_t len);
|
||||
|
||||
/* Remove data from the beginning of the buffer */
|
||||
/*! @brief Remove data from the beginning of the buffer.
|
||||
*
|
||||
* Removes data from the beginnig of the buffer by modifying the data
|
||||
* pointer and buffer length.
|
||||
*
|
||||
* @param buf Buffer to update.
|
||||
* @param len Number of bytes to remove.
|
||||
*
|
||||
* @return New beginning of the buffer data.
|
||||
*/
|
||||
void *bt_buf_pull(struct bt_buf *buf, size_t len);
|
||||
|
||||
/* Remove and convert 16 bits from the beginning of the buffer */
|
||||
/*! @brief Remove and convert 16 bits from the beginning of the buffer.
|
||||
*
|
||||
* Same idea as with bt_buf_pull(), but a helper for operating on
|
||||
* 16-bit little endian data.
|
||||
*
|
||||
* @param buf Buffer.
|
||||
*
|
||||
* @return 16-bit value converted from little endian to host endian.
|
||||
*/
|
||||
uint16_t bt_buf_pull_le16(struct bt_buf *buf);
|
||||
|
||||
/* Returns how much free space there is at the end of the buffer */
|
||||
/*! @brief Check buffer tailroom.
|
||||
*
|
||||
* Check how much free space there is at the end of the buffer.
|
||||
*
|
||||
* @return Number of bytes available at the end of the buffer.
|
||||
*/
|
||||
size_t bt_buf_tailroom(struct bt_buf *buf);
|
||||
|
||||
/* Returns how much free space there is at the beginning of the buffer */
|
||||
/*! @brief Check buffer headroom.
|
||||
*
|
||||
* Check how much free space there is in the beginning of the buffer.
|
||||
*
|
||||
* @return Number of bytes available in the beginning of the buffer.
|
||||
*/
|
||||
size_t bt_buf_headroom(struct bt_buf *buf);
|
||||
|
||||
/* Return pointer to the end of the data in the buffer */
|
||||
/*! @def bt_buf_tail
|
||||
* @brief Get the tail pointer for a buffer.
|
||||
*
|
||||
* Get a pointer to the end of the data in a buffer.
|
||||
*
|
||||
* @param buf Buffer.
|
||||
*
|
||||
* @return Tail pointer for the buffer.
|
||||
*/
|
||||
#define bt_buf_tail(buf) ((buf)->data + (buf)->len)
|
||||
|
||||
/* Initialize the buffers with specified amount of incoming and outgoing
|
||||
* ACL buffers. The HCI command and event buffers will be allocated from
|
||||
* whatever is left over.
|
||||
/*! @brief Initialize buffer handling.
|
||||
*
|
||||
* Initialize the buffers with specified amount of incoming and outgoing
|
||||
* ACL buffers. The HCI command and event buffers will be allocated from
|
||||
* whatever is left over.
|
||||
*
|
||||
* @param acl_in Number of incoming ACL data buffers.
|
||||
* @param acl_out Number of outgoing ACL data buffers.
|
||||
*
|
||||
* @return Zero on success or (negative) error code on failure.
|
||||
*/
|
||||
int bt_buf_init(int acl_in, int acl_out);
|
||||
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue