RngLib

rngLib - an implementation of vxWorks style ring buffers

What is this?

Ring buffers work like any first in first out buffers (FIFOs), except are implemented in software. They may be used to store data such as catching keypresses, serial or other data while the system is busy which may then be read out later in the exact order it was received into the buffer. They are interrupt safe so long as data is read out before the buffer 'fills'. In this way ring buffers are perfect for storing data of various lengths that is received faster than may be immediately processed.

The functions here are pretty self explanatory. thdslib provides for byte and/or 32bit word sized ring buffers. These may be used in addition to the FIFO or anyplace you need more code.

rngLib is based on the VxWorks implementation of the same name and are intended to be compatible. The functions may just as easily be used on any system as well as the NDS, with only slight modifications.

Where to get it

Currently the sources for this are part of LibThds. The source can be downloaded via SVN (see libthds page) or directly from the svn httpd:

• rngLib.c
• rngLib.h

32bit buffer versions:

• rng32Lib.c
• rng32Lib.h

Functions

Please note that function names and data type names are the same except prefixed with either 'rng32' for functions and 'RING32' for data types. They function in an identical manner except for using unsigned long int (u32) instead of char (u8) for data.

todo: Explain these in detail!

RING_ID rngCreate(int nbytes); //Create a ring buffer nbytes long
void rngDelete(RING_ID ringId); //Destory a ring buffer 
int rngNBytes(RING_ID ringId);	//rngNBytes( ) - determine the number of bytes available in a ring buffer
void rngFlush(RING_ID ringId);  //empty all buffer content,
int rngBufGet(RING_ID rngId, char *buffer, int maxbytes);  //get number of chars, retuns nbytes gotten
int rngBufPut(RING_ID rngId, char *buffer, int nbytes); //write a number of chars, returns nbytes put
bool rngIsEmpty(RING_ID ringId); //tst if buffer is empty
bool rngIsFull(RING_ID ringId);  //tst if full
int rngFreeBytes(RING_ID ringId); //how many free bytes remain?
int rngNBytes(RING_ID ringId);  
void rngPutAhead(RING_ID ringId, char byte, int offset); //put bytes in the read buffer without incrementing counter
void rngMoveAhead(RING_ID ringId, int n); //move inbuffer ahead n # of bytes (used after a PutAhead)

Macros

// RNG_ELEM_PUT - put one character into a ring buffer
 
//(register int) 't'.
// c is a char
 
// returns 1 if success 0 if not
#define RNG_ELEM_PUT(r, c, t)

// RNG_ELEM_GET - get one character from a ring buffer
// p should be a char *
 
// (register int) 'f'.
 
// returns 1 if success 0 if not
#define RNG_ELEM_GET(r,p,f)

Examples

Write the string into buffer and read it back out again.

char blahsrc[]="this is blah";
char blahdst[0x20];
int putcnt, getcnt;
 
//create 32 byte long rng buffer
RING_ID rid=rngCreate(0x20);
//write bytes into ring buffer
putcnt=rngBufPut(rid, blahsrc, strlen(blahsrc)+1);
//read bytes back out of ring buffer
getcnt=rngBufGet(rid, blahdst, sizeof(blahdst));
printf("put %d bytes into buffer, read %d bytes out: %s\n",putcnt,getcnt,blahdst);

ring buffers are very useful. ^^