michaelh/zephyr
1
0
Fork 0
Code Releases Activity

Bluetooth: Add doxygen documentation for buf.h

Browse source 
Change-Id: Ia60227e9f960f9563c82cdc4a044a2f9a538331c
Signed-off-by: Johan Hedberg <johan.hedberg@intel.com>
This commit is contained in:
Johan Hedberg 2015-06-18 11:29:48 +03:00 • committed by Anas Nashif
commit 5a72e9aaaa
1 changed files with 126 additions and 35 deletions
Download patch file Download diff file Expand all files Collapse all files

161
include/bluetooth/buf.h
View file

@ -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);