From 5b6d31183099b5402e4ca9a50203b9442dcf0c3a Mon Sep 17 00:00:00 2001 From: Joe Kroesche Date: Sat, 28 Oct 2017 13:44:02 -0500 Subject: [PATCH 1/2] core/include/ringbuffer.h: add doc ref to tsrb. Updated file comment header to comply with coding standard; added brief module description and reference to tsrb to guide reader who might be looking for thread-safe implementation --- core/include/ringbuffer.h | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/core/include/ringbuffer.h b/core/include/ringbuffer.h index 44385d4193..3bdd5bab7c 100644 --- a/core/include/ringbuffer.h +++ b/core/include/ringbuffer.h @@ -1,18 +1,24 @@ -/** - * Ringbuffer header - * +/* * Copyright (C) 2013 Freie Universität Berlin * Copyright (C) 2013 INRIA * * This file is subject to the terms and conditions of the GNU Lesser * General Public License v2.1. See the file LICENSE in the top level * directory for more details. - * + */ + +/** * @ingroup core_util * @{ * @file * @author Kaspar Schleiser * @author René Kijewski + * + * @brief A utility for storing and retrieving byte data using a ring buffer. + * + * @details The ringbuffer is useful for buffering data in the same + * thread context but it is not thread-safe. For a thread-safe ring + * buffer, see @ref sys_tsrb in the System library. * @} */ From abb6913480d9eaccfdacbc2423ac35fd5a8498f8 Mon Sep 17 00:00:00 2001 From: Joe Kroesche Date: Sat, 28 Oct 2017 14:26:16 -0500 Subject: [PATCH 2/2] sys/include/tsrb.h: move usage doc to main API page. Modified file doc header so that important info about usage and buffer size show up on main API doc page instead of file doc page; added comment in a couple of places to remind reader that buffer size must be powewr of 2. --- sys/include/tsrb.h | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sys/include/tsrb.h b/sys/include/tsrb.h index e73fbdce4e..f0d7f698aa 100644 --- a/sys/include/tsrb.h +++ b/sys/include/tsrb.h @@ -12,14 +12,14 @@ * @brief Thread-safe ringbuffer implementation * @{ * - * @file - * @brief Thread-safe ringbuffer interface definition - * * @note This ringbuffer implementation can be used without locking if * there's only one producer and one consumer. * * @attention Buffer size must be a power of two! * + * @file + * @brief Thread-safe ringbuffer interface definition + * * @author Kaspar Schleiser */ @@ -38,7 +38,7 @@ extern "C" { */ typedef struct tsrb { char *buf; /**< Buffer to operate on. */ - unsigned int size; /**< Size of buf. */ + unsigned int size; /**< Size of buffer, must be power of 2. */ volatile unsigned reads; /**< total number of reads */ volatile unsigned writes; /**< total number of writes */ } tsrb_t; @@ -52,7 +52,7 @@ typedef struct tsrb { * @brief Initialize a tsrb. * @param[out] rb Datum to initialize. * @param[in] buffer Buffer to use by tsrb. - * @param[in] bufsize `sizeof (buffer)` + * @param[in] bufsize `sizeof (buffer)`, must be power of 2. */ static inline void tsrb_init(tsrb_t *rb, char *buffer, unsigned bufsize) {