Module byte_queue

FIFO queue with a byte-oriented interface

The ByteQueue operates on a shared memory region and keeps track of a write-pointer and a read-pointer. To access both pointers from both processors, the pointers are stored in the shared memory region itself so the capacity of the queue is 2*size_of::<u32>() smaller than the memory region size.

When initializing the ByteQueue from an array buffer, the buffer should be defined with the type u32 to ensure alignment regardless of its size, and then cast into an u8 pointer when passed into the ByteQueue constructor. Additionally, the size parameter for the constructor needs to be adjusted accordingly, i.e. it is 4 times larger than the array length.

The main contract for the ByteQueue is that only the writer may write to the write-pointer, only the reader may change the read-pointer. The memory region in front of the write-pointer and up to the read-pointer is owned by the writer (it may be changed by the writer), the memory region in front of the read-pointer and up to the write-pointer is owned by the reader (it may not be changed by the writer and can safely be read by the reader). For initialization, both pointers have to be set to 0 at the beginning. This is in contrast to the contract above because the initializing processor needs to write both pointers. Therefore, this has to be done by processor A while it is guaranteed that processor B does not access the queue yet to prevent race conditions.

Because processor A has to initialize the byte queue and processor B should not reset the write- and read-pointers, there are two methods for initialization: ByteQueue::create should be called by the first processor and sets both pointers to 0, ByteQueue::attach should be called by the second one.

The ByteQueue implements both the write- and the read-methods but each processor should have either the writing side or the reading side assigned to it and must not call the other methods. It would also be possible to have a SharedMemWriter and a SharedMemReader but this design was initially chosen so that the queue can also be used as a simple ring buffer on a single processor.

Structs

ByteQueue

The ByteQueue queue type. Read the crate and module documentation for further information and usage examples.