Memory handling

memory - translate memories to basic cells

yosys> help memory

memory [-norom] [-nomap] [-nordff] [-nowiden] [-nosat] [-memx] [-no-rw-check] [-bram <bram_rules>] [selection]

This pass calls all the other memory_* passes in a useful order:

    opt_mem
    opt_mem_priority
    opt_mem_feedback
    memory_bmux2rom                     (skipped if called with -norom)
    memory_dff [-no-rw-check]           (skipped if called with -nordff or -memx)
    opt_clean
    memory_share [-nowiden] [-nosat]
    opt_mem_widen
    memory_memx                         (when called with -memx)
    opt_clean
    memory_collect
    memory_bram -rules <bram_rules>     (when called with -bram)
    memory_map                          (skipped if called with -nomap)

This converts memories to word-wide DFFs and address decoders
or multiport memory blocks if called with the -nomap option.

Note

Help text automatically generated from passes/memory/memory.cc:29

memory_bmux2rom - convert muxes to ROMs

yosys> help memory_bmux2rom

memory_bmux2rom [options] [selection]

This pass converts $bmux cells with constant A input to ROMs.

Note

Help text automatically generated from passes/memory/memory_bmux2rom.cc:28

memory_bram - map memories to block rams

yosys> help memory_bram

memory_bram -rules <rule_file> [selection]

This pass converts the multi-port $mem memory cells into block ram instances.
The given rules file describes the available resources and how they should be
used.

The rules file contains configuration options, a set of block ram description
and a sequence of match rules.

The option 'attr_icase' configures how attribute values are matched. The value 0
means case-sensitive, 1 means case-insensitive.

A block ram description looks like this:

    bram RAMB1024X32     # name of BRAM cell
      init 1             # set to '1' if BRAM can be initialized
      abits 10           # number of address bits
      dbits 32           # number of data bits
      groups 2           # number of port groups
      ports  1 1         # number of ports in each group
      wrmode 1 0         # set to '1' if this groups is write ports
      enable 4 1         # number of enable bits
      transp 0 2         # transparent (for read ports)
      clocks 1 2         # clock configuration
      clkpol 2 2         # clock polarity configuration
    endbram

For the option 'transp' the value 0 means non-transparent, 1 means transparent
and a value greater than 1 means configurable. All groups with the same
value greater than 1 share the same configuration bit.

For the option 'clocks' the value 0 means non-clocked, and a value greater
than 0 means clocked. All groups with the same value share the same clock
signal.

For the option 'clkpol' the value 0 means negative edge, 1 means positive edge
and a value greater than 1 means configurable. All groups with the same value
greater than 1 share the same configuration bit.

Using the same bram name in different bram blocks will create different variants
of the bram. Verilog configuration parameters for the bram are created as
needed.

It is also possible to create variants by repeating statements in the bram block
and appending '@<label>' to the individual statements.

A match rule looks like this:

    match RAMB1024X32
      max waste 16384    # only use this bram if <= 16k ram bits are unused
      min efficiency 80  # only use this bram if efficiency is at least 80%
    endmatch

It is possible to match against the following values with min/max rules:

    words  ........  number of words in memory in design
    abits  ........  number of address bits on memory in design
    dbits  ........  number of data bits on memory in design
    wports  .......  number of write ports on memory in design
    rports  .......  number of read ports on memory in design
    ports  ........  number of ports on memory in design
    bits  .........  number of bits in memory in design
    dups ..........  number of duplications for more read ports

    awaste  .......  number of unused address slots for this match
    dwaste  .......  number of unused data bits for this match
    bwaste  .......  number of unused bram bits for this match
    waste  ........  total number of unused bram bits (bwaste*dups)
    efficiency  ...  total percentage of used and non-duplicated bits

    acells  .......  number of cells in 'address-direction'
    dcells  .......  number of cells in 'data-direction'
    cells  ........  total number of cells (acells*dcells*dups)

A match containing the command 'attribute' followed by a list of space
separated 'name[=string_value]' values requires that the memory contains any
one of the given attribute name and string values (where specified), or name
and integer 1 value (if no string_value given, since Verilog will interpret
'(* attr *)' as '(* attr=1 *)').
A name prefixed with '!' indicates that the attribute must not exist.

The interface for the created bram instances is derived from the bram
description. Use 'techmap' to convert the created bram instances into
instances of the actual bram cells of your target architecture.

A match containing the command 'or_next_if_better' is only used if it
has a higher efficiency than the next match (and the one after that if
the next also has 'or_next_if_better' set, and so forth).

A match containing the command 'make_transp' will add external circuitry
to simulate 'transparent read', if necessary.

A match containing the command 'make_outreg' will add external flip-flops
to implement synchronous read ports, if necessary.

A match containing the command 'shuffle_enable A' will re-organize
the data bits to accommodate the enable pattern of port A.

Note

Help text automatically generated from passes/memory/memory_bram.cc:1203

memory_collect - creating multi-port memory cells

yosys> help memory_collect

memory_collect [selection]

This pass collects memories and memory ports and creates generic multiport
memory cells.

Note

Help text automatically generated from passes/memory/memory_collect.cc:27

memory_dff - merge input/output DFFs into memory read ports

yosys> help memory_dff

memory_dff [-no-rw-check] [selection]

This pass detects DFFs at memory read ports and merges them into the memory
port. I.e. it consumes an asynchronous memory port and the flip-flops at its
interface and yields a synchronous memory port.

-no-rw-check

marks all recognized read ports as "return don't-care value on
read/write collision" (same result as setting the no_rw_check
attribute on all memories).

Note

Help text automatically generated from passes/memory/memory_dff.cc:627

memory_libmap - map memories to cells

yosys> help memory_libmap

memory_libmap -lib <library_file> [-D <condition>] [selection]

This pass takes a description of available RAM cell types and maps
all selected memories to one of them, or leaves them to be mapped to FFs.

-lib <library_file>

Selects a library file containing RAM cell definitions. This option
can be passed more than once to select multiple libraries.
See passes/memory/memlib.md for description of the library format.

-D <condition>

Enables a condition that can be checked within the library file
to eg. select between slightly different hardware variants.
This option can be passed any number of times.

-logic-cost-rom <num>

-logic-cost-ram <num>

Sets the cost of a single bit for memory lowered to soft logic.

-no-auto-distributed

-no-auto-block

-no-auto-huge

Disables automatic mapping of given kind of RAMs.  Manual mapping
(using ram_style or other attributes) is still supported.

Note

Help text automatically generated from passes/memory/memory_libmap.cc:2152

memory_map - translate multiport memories to basic cells

yosys> help memory_map

memory_map [options] [selection]

This pass converts multiport memory cells as generated by the memory_collect
pass to word-wide DFFs and address decoders.

-attr !<name>

do not map memories that have attribute <name> set.

-attr <name>[=<value>]

for memories that have attribute <name> set, only map them if its value
is a string <value> (if specified), or an integer 1 (otherwise). if this
option is specified multiple times, map the memory if the attribute is
to any of the values.

-iattr

for -attr, suppress case sensitivity in matching of <value>.

-rom-only

only perform conversion for ROMs (memories with no write ports).

-keepdc

when mapping ROMs, keep x-bits shared across read ports.

-formal

map memories for a global clock based formal verification flow.
This implies -keepdc, uses $ff cells for ROMs and sets hdlname
attributes. It also has limited support for async write ports
as generated by clk2fflogic.

Note

Help text automatically generated from passes/memory/memory_map.cc:398

memory_memx - emulate vlog sim behavior for mem ports

yosys> help memory_memx

memory_memx [selection]

This pass adds additional circuitry that emulates the Verilog simulation
behavior for out-of-bounds memory reads and writes.

Note

Help text automatically generated from passes/memory/memory_memx.cc:27

memory_narrow - split up wide memory ports

yosys> help memory_narrow

memory_narrow [options] [selection]

This pass splits up wide memory ports into several narrow ports.

Note

Help text automatically generated from passes/memory/memory_narrow.cc:28

memory_nordff - extract read port FFs from memories

yosys> help memory_nordff

memory_nordff [options] [selection]

This pass extracts FFs from memory read ports. This results in a netlist
similar to what one would get from not calling memory_dff.

Note

Help text automatically generated from passes/memory/memory_nordff.cc:28

memory_share - consolidate memory ports

yosys> help memory_share

memory_share [-nosat] [-nowiden] [selection]

This pass merges share-able memory ports into single memory ports.

The following methods are used to consolidate the number of memory ports:

  - When multiple write ports access the same address then this is converted
    to a single write port with a more complex data and/or enable logic path.

  - When multiple read or write ports access adjacent aligned addresses, they
    are merged to a single wide read or write port.  This transformation can be
    disabled with the "-nowiden" option.

  - When multiple write ports are never accessed at the same time (a SAT
    solver is used to determine this), then the ports are merged into a single
    write port.  This transformation can be disabled with the "-nosat" option.

Note that in addition to the algorithms implemented in this pass, the $memrd
and $memwr cells are also subject to generic resource sharing passes (and other
optimizations) such as "share" and "opt_merge".

Note

Help text automatically generated from passes/memory/memory_share.cc:512

memory_unpack - unpack multi-port memory cells

yosys> help memory_unpack

memory_unpack [selection]

This pass converts the multi-port $mem memory cells into individual $memrd and
$memwr cells. It is the counterpart to the memory_collect pass.

Note

Help text automatically generated from passes/memory/memory_unpack.cc:27