RngLib
rngLib - an implementation of vxWorks style ring buffers
Contents |
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, thread, and interprocessor safe meaning they are perfect for transfer of data between arm7 and arm9. So long as data is read out before the buffer 'fills' no data loss should result. 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 conjunction with 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. For further information beyond what is provided here see the vxWorks reference page linked above.
The functions may just as easily be used on any system as well as the NDS, with only slight modifications (mostly change the bool data type to what the system expects).
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:
32bit buffer versions:
An example of rng32Lib usage that caches keypresses during vblank handler may be found here:
kfD3So <a href="http://louvydfrqpxy.com/">louvydfrqpxy</a>, [url=http://ahxmwwavqcwx.com/]ahxmwwavqcwx[/url], [link=http://mttoxooogowq.com/]mttoxooogowq[/link], http://wlkzzqvgkxxm.com/
Macros
RNG_ELEM_PUT
Puts a single character (or 32bit word for thFifo32) into the ring buffer and increments the element count, faster than rngPutBytes and should be used when single character or word is to be placed into buffer.
- r - object of type RING_ID
- c - character to be placed into the ring buffer
- t - an integer to be used internally by the macro for calculations
returns 1 if successfull, otherwise 0
// returns 1 if success 0 if not #define RNG_ELEM_PUT(r, c, t)
For example:
register int myregint; RNG_ELEM_PUT(myringid, 'c', myregint); //Is equivalent to: ringPutBytes(myringid, "c", 1);
RNG_ELEM_GET
Gets a single character (or 32bit word for thFifo32) from the ring buffer and decrements the element count, faster than rngGetBytes and should be used when single character or word is to be retrieved into buffer.
- r - object of type RING_ID
- c - character to be placed into the ring buffer
- t - an integer to be used internally by the macro for calculations
returns 1 if successfull, otherwise 0
#define RNG_ELEM_GET(r,p,f)For example:
register int myregint; char blah[]="c"; RNG_ELEM_GET(myringid, blah, myregint); //Is equivalent to: char blah[]="c"; ringPutBytes(myringid, blah, 1);
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. ^^
