text: /* ring_buffer.h: Simple ring buffer API */
  
  /*
   * Copyright (c) 2015 Intel Corporation
   *
   * Licensed under the Apache License, Version 2.0 (the "License");
   * you may not use this file except in compliance with the License.
   * You may obtain a copy of the License at
   *
   *     http://www.apache.org/licenses/LICENSE-2.0
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS,
   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   * See the License for the specific language governing permissions and
   * limitations under the License.
   */
  /** @file */
  
  #ifndef __RING_BUFFER_H__
  #define __RING_BUFFER_H__
  
  #include <nanokernel.h>
  #include <misc/debug/object_tracing_common.h>
  #include <misc/util.h>
  #include <errno.h>
  
  #ifdef __cplusplus
  extern "C" {
  #endif
  
  /**
   * @brief Ring Buffer APIs
   * @defgroup nanokernel_ringbuffer Ring Bufer
   * @ingroup nanokernel_services
   * @{
   */
  
  #define SIZE32_OF(x) (sizeof((x))/sizeof(uint32_t))
  
  /**
   * @brief A structure to represent a ring buffer
   */
  struct ring_buf {
  	uint32_t head;	 /**< Index in buf for the head element */
  	uint32_t tail;	 /**< Index in buf for the tail element */
  	uint32_t dropped_put_count; /**< Running tally of the number of failed
  				     * put attempts
  				     */
  	uint32_t size;   /**< Size of buf in 32-bit chunks */
  	uint32_t *buf;	 /**< Memory region for stored entries */
  	uint32_t mask;   /**< Modulo mask if size is a power of 2 */
  #ifdef CONFIG_DEBUG_TRACING_KERNEL_OBJECTS
  	struct ring_buf *__next;
  #endif
  };
  
  /**
   * @brief Declare a power-of-two sized ring buffer
   *
   * Use of this macro is preferred over SYS_RING_BUF_DECLARE_SIZE() as it
   * will not need to use expensive modulo operations.
   *
   * @param name File-scoped name of the ring buffer to declare
   * @param pow Create a buffer of 2^pow 32-bit elements
   */
  #define SYS_RING_BUF_DECLARE_POW2(name, pow) \
  	static uint32_t _ring_buffer_data_##name[1 << (pow)]; \
  	struct ring_buf name = { \
  		.size = (1 << (pow)), \
  		.mask = (1 << (pow)) - 1, \
  		.buf = _ring_buffer_data_##name \
  	};
  
  /**
   * @brief Declare an arbitrary sized ring buffer
   *
   * A ring buffer declared in this way has more flexibility on buffer size
   * but will use more expensive modulo operations to maintain itself.
   *
   * @param name File-scoped name of the ring buffer to declare
   * @param size32 Size of buffer in 32-bit elements
   */
  #define SYS_RING_BUF_DECLARE_SIZE(name, size32) \
  	static uint32_t _ring_buffer_data_##name[size32]; \
  	struct ring_buf name = { \
  		.size = size32, \
  		.buf = _ring_buffer_data_##name \
  	};
  
  /**
   * @brief Initialize a ring buffer, in cases where DECLARE_RING_BUF_STATIC
   * isn't used.
   *
   * For optimal performance, use size values that are a power of 2 as they
   * don't require expensive modulo operations when maintaining the buffer.
   *
   * @param buf Ring buffer to initialize
   * @param size Size of the provided buffer in 32-bit chunks
   * @param data Data area for the ring buffer, typically
   *	  uint32_t data[size]
   */
  static inline void sys_ring_buf_init(struct ring_buf *buf, uint32_t size,
  				     uint32_t *data)
  {
  	buf->head = 0;
  	buf->tail = 0;
  	buf->dropped_put_count = 0;
  	buf->size = size;
  	buf->buf = data;
  	if (is_power_of_two(size)) {
  		buf->mask = size - 1;
  	} else {
  		buf->mask = 0;
  	}
  
  	SYS_TRACING_OBJ_INIT(sys_ring_buf, buf);
  }
  
  /**
   * @brief Determine if a ring buffer is empty
   *
   * @return nonzero if the buffer is empty
   */
  static inline int sys_ring_buf_is_empty(struct ring_buf *buf)
  {
  	return (buf->head == buf->tail);
  }
  
  /**
   * @brief Obtain available space in a ring buffer
   *
   * @param buf Ring buffer to examine
   * @return Available space in the buffer in 32-bit chunks
   */
  static inline int sys_ring_buf_space_get(struct ring_buf *buf)
  {
  	if (sys_ring_buf_is_empty(buf)) {
  		return buf->size - 1;
  	}
  
  	if (buf->tail < buf->head) {
  		return buf->head - buf->tail - 1;
  	}
  
  	/* buf->tail > buf->head */
  	return (buf->size - buf->tail) + buf->head - 1;
  }
  
  /**
   * @brief Place an entry into the ring buffer
   *
   * Concurrency control is not implemented, however no synchronization is needed
   * between put() and get() operations as they independently work on the
   * tail and head values, respectively.
   * Any use-cases involving multiple producers will need to synchronize use
   * of this function, by either disabling preemption or using a mutex.
   *
   * @param buf Ring buffer to insert data to
   * @param type Application-specific type identifier
   * @param value Integral data to include, application specific
   * @param data Pointer to a buffer containing data to enqueue
   * @param size32 Size of data buffer, in 32-bit chunks (not bytes)
   * @return 0 on success, -ENOSPC if there isn't sufficient space
   */
  int sys_ring_buf_put(struct ring_buf *buf, uint16_t type, uint8_t value,
  		     uint32_t *data, uint8_t size32);
  
  /**
   * @brief Fetch data from the ring buffer
   *
   * @param buf Ring buffer to extract data from
   * @param type Return storage of the retrieved event type
   * @param value Return storage of the data value
   * @param data Buffer to copy data into
   * @param size32 Indicates the size of the data buffer. On return,
   *	updated with the actual amount of 32-bit chunks written to the buffer
   * @return 0 on success, -EAGAIN if the ring buffer is empty, -EMSGSIZE
   *	if the supplied buffer is too small (size32 will be updated with
   *	the actual size needed)
   */
  int sys_ring_buf_get(struct ring_buf *buf, uint16_t *type, uint8_t *value,
  		     uint32_t *data, uint8_t *size32);
  
  /**
   * @}
   */
  
  #ifdef __cplusplus
  }
  #endif
  
  #endif /* __RING_BUFFER_H__ */
  