Module ring_buffer
This document contains technical documentation for the ring_buffer module.
To browse the source code, visit the repository on GitHub.
simple_ring_buffer_manager.vhd
Simple implementation of the logic for a ring buffer or circular buffer. It is simple in the sense address segments are always of the same length, which is defined at compile-time.
The entity is designed to be used with applications where the FPGA writes data to a memory buffer and a CPU progressively reads/consumes it. Even though the entity might have other use cases, the terminology and naming of things is based on this presumed use case.
The buffer_start_address, buffer_end_address and buffer_read_address must be set
by the user before enabling the entity with the enable signal.
Initially, the buffer_read_address should be set to the buffer_start_address.
All these addresses need to be byte-aligned with the segment length, i.e. they must be integer
multiples of segment_length_bytes.
Warning
Once the entity has been enabled, it does not support disabling, doing so would result in undefined behavior.
Once enabled, the entity will start providing segment addresses to the user on the
segment interface.
This is an AXI-Stream-like handshaking interface.
Once a segment has been written, the segment_written signal must be pulsed by the user.
The entity will then update the buffer_written_address accordingly.
Once the CPU has updated buffer_read_address accordingly, the address of this segment can
once again be provided on the segment interface.
Note
In order to distinguish between the full and empty states, this entity will never
utilize 100% of the provided buffer space.
There will always be one segment that is not used.
In other words, there will never be more than
(buffer_end_address - buffer_start_address) / segment_length_bytes - 1
segments outstanding.
Warning
This entity will fail if buffer_last_address is the very last address in the address space.
(e.g. 0xFFFFFFFF).
Resource utilization
This entity has netlist builds set up with automatic size checkers in module_ring_buffer.py. The following table lists the resource utilization for the entity, depending on generic configuration.
Generics |
Total LUTs |
FFs |
Maximum logic level |
|---|---|---|---|
address_width = 29 segment_length_bytes = 64 |
94 |
52 |
12 |
simple_ring_buffer_manager_pkg.vhd
Package with types and constants for simple_ring_buffer_manager.vhd.