C MIP-SDK
Data Structures | Defines | Typedefs | Functions
ring_buffer.h File Reference
#include "mip_types.h"
#include <string.h>
#include <stdlib.h>

Go to the source code of this file.

Data Structures

struct  _ring_buffer

Defines

#define RING_BUFFER_UNINITIALIZED   0
#define RING_BUFFER_INITIALIZED   1
#define RING_BUFFER_OK   0
#define RING_BUFFER_ERROR   1
#define RING_BUFFER_MEMORY_ERROR   2
#define RING_BUFFER_SIZE_MISMATCH   3
#define RING_BUFFER_EMPTY   4
#define RING_BUFFER_FULL   5
#define RING_BUFFER_STATIC_TYPE   0
#define RING_BUFFER_MALLOC_TYPE   1

Typedefs

typedef struct _ring_buffer ring_buffer

Functions

u16 ring_buffer_init_static (ring_buffer *buffer, u8 *data_buffer_ptr, u32 max_entries, u32 entry_size)
u16 ring_buffer_init_malloc (ring_buffer *buffer, u32 max_entries, u32 entry_size)
u32 ring_buffer_count (ring_buffer *buffer)
u32 ring_buffer_remaining_entries (ring_buffer *buffer)
u16 ring_buffer_flush (ring_buffer *buffer)
u16 ring_buffer_write (ring_buffer *buffer, u8 *entry, u32 num_bytes)
u16 ring_buffer_write_multi (ring_buffer *buffer, u8 *entry_buff, u32 num_entries, u32 *num_written)
u16 ring_buffer_read (ring_buffer *buffer, u8 *entry, u32 max_bytes)
u16 ring_buffer_read_multi (ring_buffer *buffer, u8 *entry_buff, u32 entry_buff_size, u32 num_requested, u32 *num_read)
u16 ring_buffer_lookahead_read (ring_buffer *buffer, u32 offset, u8 *entry, u32 max_bytes)
u16 ring_buffer_lookahead_read_multi (ring_buffer *buffer, u32 offset, u8 *entry_buff, u32 entry_buff_size, u32 num_requested, u32 *num_read)
u32 ring_buffer_copy (ring_buffer *to, ring_buffer *from, u32 num_entries)
u32 ring_buffer_lookahead_copy (ring_buffer *to, u32 offset, ring_buffer *from, u32 num_entries)
u16 ring_buffer_consume_entries (ring_buffer *buffer, u32 num_entries)
u8 * ring_buffer_get_first_element_ptr (ring_buffer *buffer)
u16 ring_buffer_remove_first_element (ring_buffer *buffer)
u8 * ring_buffer_get_available_element_ptr (ring_buffer *buffer)
u16 ring_buffer_increment_count (ring_buffer *buffer)
u16 ring_buffer_malloc_free (ring_buffer *buffer)
void __ring_buffer_reset (ring_buffer *buffer)

Detailed Description

Author:
Nathan Miller
Version:
1.1

Function Documentation

void __ring_buffer_reset ( ring_buffer buffer)

DESCRIPTION

Reset the ring buffer state, stats, and buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.

NOTES

Internal Function.

u16 ring_buffer_consume_entries ( ring_buffer buffer,
u32  num_entries 
)

DESCRIPTION

Removes num_entries from the buffer if they exist.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
[in]num_entries- the number of entries to remove.
Returns:
Number of entries removed

NOTES

None.

u32 ring_buffer_copy ( ring_buffer to,
ring_buffer from,
u32  num_entries 
)

DESCRIPTION

Copy num_entries between two ring buffers.

DETAILS

Parameters:
[out]ring_buffer*to - pointer to a ring buffer structure to copy to.
[in]ring_buffer*from - pointer to a ring buffer structure to copy from.
[in]num_entries- the number of entries to copy.
Returns:
Number of entries copied

NOTES

None.

u32 ring_buffer_count ( ring_buffer buffer)

DESCRIPTION

Returns the number of entries in the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Returns:
Number of entries in the buffer, if initialized.
0 Otherwise.

NOTES

None

u16 ring_buffer_flush ( ring_buffer buffer)

DESCRIPTION

Flushes the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Return values:
RING_BUFFER_ERRORBuffer not initialized.
RING_BUFFER_OKBuffer flushed.

NOTES

None

u8* ring_buffer_get_available_element_ptr ( ring_buffer buffer)

DESCRIPTION

Return a pointer to the next available element in the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Returns:
NULL (0) If the ring buffer pointer is invalid or there are no elements.
Otherwise, the pointer to first available element.

NOTES

This routine should only be used for single-element access!!!
Attempting to access multiple elements using this can cause access
outside of the array boundaries!

u8* ring_buffer_get_first_element_ptr ( ring_buffer buffer)

DESCRIPTION

Return a pointer to the first element in the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Returns:
NULL (0) If the ring buffer pointer is invalid or there are no elements.
Otherwise, the pointer to first element.

NOTES

This routine should only be used for single-element access!!!
Attempting to access multiple elements using this can cause access
outside of the array boundaries!

u16 ring_buffer_increment_count ( ring_buffer buffer)

DESCRIPTION

Increments the number of elements in the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Return values:
RING_BUFFER_ERRORRing buffer invalid.
RING_BUFFER_EMPTYRing buffer full.
RING_BUFFER_OKElement added.

NOTES

Used in conjunction with ring_buffer_get_available_element_ptr
for pointer write access to ring buffer elements.

u16 ring_buffer_init_malloc ( ring_buffer buffer,
u32  max_entries,
u32  entry_size 
)

DESCRIPTION

Initialize a ring buffer using malloc to allocate the buffer from the heap.

DETAILS

Parameters:
[out]ring_buffer*buffer - pointer to a ring buffer structure.
[in]u32max_entries - maximum entries the ring buffer may contain.
[in]u32entry_size - size of each entry (bytes).
Return values:
RING_BUFFER_ERRORBuffer not initialized.
RING_BUFFER_OKBuffer initialized.

NOTES

None

u16 ring_buffer_init_static ( ring_buffer buffer,
u8 *  data_buffer_ptr,
u32  max_entries,
u32  entry_size 
)

DESCRIPTION

Initialize a ring buffer with a static memory location.

DETAILS

Parameters:
[out]ring_buffer*buffer - pointer to a ring buffer structure.
[in]u8*data_buffer_ptr - data pointer (must be allocated and size = max_entries * entry_size).
[in]u32max_entries - maximum entries the ring buffer may contain.
[in]u32entry_size - size of each entry (bytes).
Return values:
RING_BUFFER_ERRORBuffer not initialized.
RING_BUFFER_OKBuffer initialized.

NOTES

None

u32 ring_buffer_lookahead_copy ( ring_buffer to,
u32  offset,
ring_buffer from,
u32  num_entries 
)

DESCRIPTION

Copy num_entries between two ring buffers without consuming the entries.

DETAILS

Parameters:
[out]ring_buffer*to - pointer to a ring buffer structure to copy to.
[in]u32offset - offset from the first element to start the copy.
[in]ring_buffer*from - pointer to a ring buffer structure to copy from.
[in]num_entries- the number of entries to copy.
Returns:
Number of entries copied

NOTES

None.

u16 ring_buffer_lookahead_read ( ring_buffer buffer,
u32  offset,
u8 *  entry,
u32  max_bytes 
)

DESCRIPTION

Read an entry from the ring buffer without consuming it.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
[in]u32offset - offset from the head of the ring buffer to read.
[out]u8*entry - pointer to data buffer where the entry will be stored.
[in]u32max_bytes - maximum size of the data buffer.
Return values:
RING_BUFFER_ERROREntry not read, buffer not initialized.
RING_BUFFER_FULLEntry not read, the buffer is empty.
RING_BUFFER_MEMORY_ERROREntry not read, max_bytes is smaller than the ring buffer entry size.
RING_BUFFER_OKEntries read.

NOTES

None.

u16 ring_buffer_lookahead_read_multi ( ring_buffer buffer,
u32  offset,
u8 *  entry_buff,
u32  entry_buff_size,
u32  num_requested,
u32 *  num_read 
)

DESCRIPTION

Read num_requested entries from the ring buffer without consuming them.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
[in]u32offset - offset from the head of the ring buffer to read.
[out]u8*entry_buff - pointer to data buffer where the entries will be stored.
[in]u32entry_buff_size - maximum size of the data buffer in bytes.
[in]u32num_requested - the number of entries requested.
[out]u32num_read - the number of entries actually read.
Return values:
RING_BUFFER_ERROREntry not read, buffer not initialized.
RING_BUFFER_EMPTYEntry not read, the buffer is empty.
RING_BUFFER_MEMORY_ERROREntry not read, max_bytes is smaller than the ring buffer entry size.
RING_BUFFER_OKEntries read.

NOTES

None.

u16 ring_buffer_malloc_free ( ring_buffer buffer)

DESCRIPTION

Return the allocated memory to the heap.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Return values:
RING_BUFFER_ERRORBuffer not initialized or not malloc'd.
RING_BUFFER_OKBuffer freed.

NOTES

None.

u16 ring_buffer_read ( ring_buffer buffer,
u8 *  entry,
u32  max_bytes 
)

DESCRIPTION

Read a single entry from the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
[out]u8*entry - pointer to data buffer where the entry will be stored.
[in]u32max_bytes - maximum size of the data buffer.
Return values:
RING_BUFFER_ERROREntry not read, buffer not initialized.
RING_BUFFER_FULLEntry not read, the buffer is empty.
RING_BUFFER_MEMORY_ERROREntry not read, max_bytes is smaller than the ring buffer entry size.
RING_BUFFER_OKEntry read.

NOTES

None.

u16 ring_buffer_read_multi ( ring_buffer buffer,
u8 *  entry_buff,
u32  entry_buff_size,
u32  num_requested,
u32 *  num_read 
)

DESCRIPTION

Read num_requested entries from the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
[out]u8*entry - pointer to data buffer where the entries will be stored.
[in]u32entry_buff_size - maximum size of the data buffer in bytes.
[in]u32num_requested - the number of entries requested.
[out]u32num_read - the number of entries actually read.
Return values:
RING_BUFFER_ERROREntry not read, buffer not initialized.
RING_BUFFER_EMPTYEntry not read, the buffer is empty.
RING_BUFFER_MEMORY_ERROREntry not read, max_bytes is smaller than the ring buffer entry size.
RING_BUFFER_OKEntries read.

NOTES

None.

u32 ring_buffer_remaining_entries ( ring_buffer buffer)

DESCRIPTION

Returns the number of empty entries in the ring buffer.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Returns:
Number of empty entries in the buffer, if initialized.
0 Otherwise.

NOTES

None

u16 ring_buffer_remove_first_element ( ring_buffer buffer)

DESCRIPTION

Removes the first element of the ring buffer if it exists.

DETAILS

Parameters:
[in]ring_buffer*buffer - pointer to a ring buffer structure.
Return values:
RING_BUFFER_ERRORRing buffer invalid.
RING_BUFFER_EMPTYRing buffer empty.
RING_BUFFER_OKElement removed.

NOTES

Used in conjunction with ring_buffer_get_first_element_ptr
for pointer read access to ring buffer elements.

u16 ring_buffer_write ( ring_buffer buffer,
u8 *  entry,
u32  num_bytes 
)

DESCRIPTION

Write num_bytes of a single entry to the ring buffer.

DETAILS

Parameters:
[out]ring_buffer*buffer - pointer to a ring buffer structure.
[in]u8*entry - pointer to memory buffer holding the entry.
[in]u32num_bytes - number of bytes to write.
Return values:
RING_BUFFER_ERROREntry not written, buffer not initialized.
RING_BUFFER_FULLEntry not written, the buffer is full.
RING_BUFFER_MEMORY_ERROREntry not written, num_bytes is larger than the ring buffer entry size.
RING_BUFFER_OKEntry written.

NOTES

num_bytes included for ring buffers with variable entry sizes (e.g. strings). num_bytes must be less than the max entry size.

u16 ring_buffer_write_multi ( ring_buffer buffer,
u8 *  entry_buff,
u32  num_entries,
u32 *  num_written 
)

DESCRIPTION

Write num_entries to the ring buffer.

DETAILS

Parameters:
[out]ring_buffer*buffer - pointer to a ring buffer structure.
[in]u8*entry_buff - pointer to memory buffer holding the entries.
[in]u32num_entries - number of entries to write.
Return values:
RING_BUFFER_ERROREntries not written, buffer not initialized.
RING_BUFFER_FULLEntries not written, the buffer is full.
RING_BUFFER_MEMORY_ERROREntries not written, num_bytes is larger than the ring buffer entry size.
RING_BUFFER_OKEntries written.

NOTES

All entries are assumed to be of size entry_size, which is set by the ring_buffer_init_xxxxxx call.

 All Data Structures Files Functions Defines