First-in first-out queues
The amaranth.lib.fifo
module provides building blocks for first-in, first-out queues.
- class amaranth.lib.fifo.FIFOInterface(*, width, depth)
Data written to the input interface (
w_data
,w_rdy
,w_en
) is buffered and can be read at the output interface (r_data
,r_rdy
,r_en
). The data entry written first to the input also appears first on the output.- Parameters:
- Attributes:
w_data (Signal(width), in) – Input data.
w_rdy (Signal(1), out) – Asserted if there is space in the queue, i.e.
w_en
can be asserted to write a new entry.w_en (Signal(1), in) – Write strobe. Latches
w_data
into the queue. Does nothing ifw_rdy
is not asserted.w_level (Signal(range(depth + 1)), out) – Number of unread entries.
r_data (Signal(width), out) – Output data. The conditions in which
r_data
is valid depends on the type of the queue.r_rdy (Signal(1), out) – Asserted if there is an entry in the queue, i.e.
r_en
can be asserted to read an existing entry.r_en (Signal(1), in) – Read strobe. Makes the next entry (if any) available on
r_data
at the next cycle. Does nothing ifr_rdy
is not asserted.r_level (Signal(range(depth + 1)), out) – Number of unread entries.
Note
The
FIFOInterface
class can be used directly to substitute a FIFO in tests, or inherited from in a custom FIFO implementation.
- class amaranth.lib.fifo.SyncFIFO(*, width, depth)
Synchronous first in, first out queue.
Read and write interfaces are accessed from the same clock domain. If different clock domains are needed, use
AsyncFIFO
.- Parameters:
- Attributes:
level (Signal(range(depth + 1)), out) – Number of unread entries. This level is the same between read and write for synchronous FIFOs.
w_data (Signal(width), in) – Input data.
w_rdy (Signal(1), out) – Asserted if there is space in the queue, i.e.
w_en
can be asserted to write a new entry.w_en (Signal(1), in) – Write strobe. Latches
w_data
into the queue. Does nothing ifw_rdy
is not asserted.w_level (Signal(range(depth + 1)), out) – Number of unread entries.
r_data (Signal(width), out) – Output data. Valid if
r_rdy
is asserted.r_rdy (Signal(1), out) – Asserted if there is an entry in the queue, i.e.
r_en
can be asserted to read an existing entry.r_en (Signal(1), in) – Read strobe. Makes the next entry (if any) available on
r_data
at the next cycle. Does nothing ifr_rdy
is not asserted.r_level (Signal(range(depth + 1)), out) – Number of unread entries.
- class amaranth.lib.fifo.SyncFIFOBuffered(*, width, depth)
Buffered synchronous first in, first out queue.
This queue’s interface is identical to
SyncFIFO
, but it does not use asynchronous memory reads, which are incompatible with FPGA block RAMs.In exchange, the latency between an entry being written to an empty queue and that entry becoming available on the output is increased by one cycle compared to
SyncFIFO
.- Parameters:
- Attributes:
level (Signal(range(depth + 1)), out) – Number of unread entries. This level is the same between read and write for synchronous FIFOs.
w_data (Signal(width), in) – Input data.
w_rdy (Signal(1), out) – Asserted if there is space in the queue, i.e.
w_en
can be asserted to write a new entry.w_en (Signal(1), in) – Write strobe. Latches
w_data
into the queue. Does nothing ifw_rdy
is not asserted.w_level (Signal(range(depth + 1)), out) – Number of unread entries.
r_data (Signal(width), out) – Output data. Valid if
r_rdy
is asserted.r_rdy (Signal(1), out) – Asserted if there is an entry in the queue, i.e.
r_en
can be asserted to read an existing entry.r_en (Signal(1), in) – Read strobe. Makes the next entry (if any) available on
r_data
at the next cycle. Does nothing ifr_rdy
is not asserted.r_level (Signal(range(depth + 1)), out) – Number of unread entries.
- class amaranth.lib.fifo.AsyncFIFO(*, width, depth, r_domain='read', w_domain='write', exact_depth=False)
Asynchronous first in, first out queue.
Read and write interfaces are accessed from different clock domains, which can be set when constructing the FIFO.
AsyncFIFO
can be reset from the write clock domain. When the write domain reset is asserted, the FIFO becomes empty. When the read domain is reset, data remains in the FIFO - the read domain logic should correctly handle this case.AsyncFIFO
only supports power of 2 depths. Unlessexact_depth
is specified, thedepth
parameter is rounded up to the next power of 2.- Parameters:
- Attributes:
w_data (Signal(width), in) – Input data.
w_rdy (Signal(1), out) – Asserted if there is space in the queue, i.e.
w_en
can be asserted to write a new entry.w_en (Signal(1), in) – Write strobe. Latches
w_data
into the queue. Does nothing ifw_rdy
is not asserted.w_level (Signal(range(depth + 1)), out) – Number of unread entries.
r_data (Signal(width), out) – Output data. Valid if
r_rdy
is asserted.r_rdy (Signal(1), out) – Asserted if there is an entry in the queue, i.e.
r_en
can be asserted to read an existing entry.r_en (Signal(1), in) – Read strobe. Makes the next entry (if any) available on
r_data
at the next cycle. Does nothing ifr_rdy
is not asserted.r_level (Signal(range(depth + 1)), out) – Number of unread entries.
r_rst (Signal(1), out) – Asserted, for at least one read-domain clock cycle, after the FIFO has been reset by the write-domain reset.
- class amaranth.lib.fifo.AsyncFIFOBuffered(*, width, depth, r_domain='read', w_domain='write', exact_depth=False)
Buffered asynchronous first in, first out queue.
Read and write interfaces are accessed from different clock domains, which can be set when constructing the FIFO.
AsyncFIFOBuffered
only supports power of 2 plus one depths. Unlessexact_depth
is specified, thedepth
parameter is rounded up to the next power of 2 plus one. (The output buffer acts as an additional queue element.)This queue’s interface is identical to
AsyncFIFO
, but it has an additional register on the output, improving timing in case of block RAM that has large clock-to-output delay.In exchange, the latency between an entry being written to an empty queue and that entry becoming available on the output is increased by one cycle compared to
AsyncFIFO
.- Parameters:
- Attributes:
w_data (Signal(width), in) – Input data.
w_rdy (Signal(1), out) – Asserted if there is space in the queue, i.e.
w_en
can be asserted to write a new entry.w_en (Signal(1), in) – Write strobe. Latches
w_data
into the queue. Does nothing ifw_rdy
is not asserted.w_level (Signal(range(depth + 1)), out) – Number of unread entries.
r_data (Signal(width), out) – Output data. Valid if
r_rdy
is asserted.r_rdy (Signal(1), out) – Asserted if there is an entry in the queue, i.e.
r_en
can be asserted to read an existing entry.r_en (Signal(1), in) – Read strobe. Makes the next entry (if any) available on
r_data
at the next cycle. Does nothing ifr_rdy
is not asserted.r_level (Signal(range(depth + 1)), out) – Number of unread entries.
r_rst (Signal(1), out) – Asserted, for at least one read-domain clock cycle, after the FIFO has been reset by the write-domain reset.