| /* | |
| * Copyright 2017, Data61 | |
| * Commonwealth Scientific and Industrial Research Organisation (CSIRO) | |
| * ABN 41 687 119 230. | |
| * | |
| * This software may be distributed and modified according to the terms of | |
| * the BSD 2-Clause license. Note that NO WARRANTY is provided. | |
| * See "LICENSE_BSD2.txt" for details. | |
| * | |
| * @TAG(DATA61_BSD) | |
| */ | |
| /* This interface allows a user to treat a region of memory as a ring buffer, | |
| * to which they read or write. It is intended for unidirectional communication | |
| * only. | |
| * | |
| * Note that, although it is not obvious from this interface, there is no flow | |
| * control provided. The effect of this is that a sender transmitting | |
| * characters at a rapid rate can have an entire buffer's worth of their data | |
| * missed by the receiver. This is semi-deliberate because any mechanism to | |
| * prevent this would introduce a back channel from the receiver to the sender. | |
| */ | |
| #ifndef _RINGBUFFER_RINGBUFFER_H_ | |
| #define _RINGBUFFER_RINGBUFFER_H_ | |
| #include <sys/types.h> | |
| /* Opaque type. Callers should be agnostic to the contents of this struct. */ | |
| typedef struct ringbuffer ringbuffer_t; | |
| /* Create a new ring buffer. | |
| * base - A pointer to the start of the region to use as the buffer. | |
| * size - The size of the buffer in bytes. | |
| * Returns NULL on failure. | |
| */ | |
| ringbuffer_t *rb_new(void *base, size_t size); | |
| /* Send a byte. | |
| * r - Buffer to send via. | |
| * c - Byte to send. | |
| */ | |
| void rb_transmit_byte(ringbuffer_t *r, unsigned char c); | |
| /* Receive a byte. | |
| * r - Buffer to read from. | |
| * Returns the character received. Does not return until it has received some | |
| * data. | |
| */ | |
| unsigned char rb_receive_byte(ringbuffer_t *r); | |
| /* Poll for new data. Identical to rb_receive_byte, except it is non-blocking | |
| * and returns 0 to indicate no data available. | |
| */ | |
| unsigned char rb_poll_byte(ringbuffer_t *r); | |
| /* Destroy a ring buffer and deallocate associated resources. */ | |
| void rb_destroy(ringbuffer_t *r); | |
| /* Higher-level wrappers. */ | |
| /* Send a null-terminated string. | |
| * r - Buffer to send via. | |
| * s - String to send. | |
| & Returns the number of characters sent. | |
| */ | |
| size_t rb_transmit_string(ringbuffer_t *r, const char *s); | |
| /* Receive a string. Note, this function does not null-terminate the resulting | |
| * string. | |
| * r - Buffer to read from. | |
| * s - Location to receive into. | |
| * len - Maximum characters to write into the destination location. | |
| * Returns the number of characters written into the destination location. | |
| */ | |
| size_t rb_receive_string(ringbuffer_t *r, char *s, size_t len); | |
| /* Send an arbitrary block of data. The block cannot contain any 0 bytes. | |
| * r - Buffer to send via. | |
| * src - Location to read from. | |
| * len - Number of bytes to send. | |
| * Returns the number of bytes sent. | |
| */ | |
| size_t rb_transmit(ringbuffer_t *r, const void *src, size_t len); | |
| /* Receive an arbitrary block of data. | |
| * r - Buffer to read from. | |
| * dest - Location to write bytes received into. | |
| * len - Maximum number of bytes to write to destination location. | |
| * Returns the number of bytes received. | |
| */ | |
| size_t rb_receive(ringbuffer_t *r, void *dest, size_t len); | |
| #endif |