It’s common for a simulation or firmware to need data loading into a memory array, ram, or rom. Fortunately, Verilog provides the
$readmemb functions for this very purpose. Unfortunately, there is a dearth of good Verilog documentation online, so using them can be harder than it should be. This how to explains the syntax and provides plenty of examples, including how to do this in Yosys and Xilinx Vivado.
If you want to learn more about FPGA memory itself, see FPGA Memory Types.
Verilog allows you to initialize memory from a text file with either hex or binary values:
$readmemh("hex_memory_file.mem", memory_array, [start_address], [end_address])
$readmemb("bin_memory_file.mem", memory_array, [start_address], [end_address])
hex_memory_file.mem- a text file containing hex values separated by whitespace
bin_memory_file.mem- a text file containing binary values separated by whitespace
memory_array- name of Verilog memory array of the form:
reg [n:0] memory_array [0:m]
start_address- where in the memory array to start loading data (optional)
end_address- where in the memory array to stop loading data (optional)
The following shows a very simple simulation module using
module readmemh_tb(); reg [7:0] test_memory [0:15]; initial begin $display("Loading rom."); $readmemh("rom_image.mem", test_memory); end endmodule
The test memory has 16 locations
[0:15] (depth) each of 8 bits
[7:0] (data width).
Memory File Syntax
bin_memory_file.mem file consists of text hex/binary values separated by whitespace: space, tab, and newline all work. You can mix the whitespace types in one file. Comments are the same as regular Verilog files:
// begins a comment.
The width of a data value in the file mustn’t be wider than the data width of the array; otherwise, that value will be truncated. In Vivado, you’ll see a warning in the log WARNING: Data truncated while reading Datafile.
The following examples show
$readmemb with a range of different initialization files. Some older tools are really picky; if you have issues, you may need to avoid comments and mixing whitespace.
1) Four 16-bit data values in hex
reg [15:0] ex1_memory [0:3]; $readmemh("ex1.mem", ex1_memory);
dead beef 0a0a 1234
2) Sixteen 8-bit data values in hex (mixing spaces and newlines)
reg [7:0] ex2_memory [0:15]; $readmemh("ex2.mem", ex2_memory);
ab cd ef 01 // this is a comment ef 22 1e 00 9f ff 13 e6 ce b7 28 8f
3) Six 3-bit values in binary
reg [2:0] ex3_memory [0:5]; $readmemb("ex3.mem", ex3_memory);
001 101 111 111 101 001
4) Six 16-bit values in hex starting at array position 4
reg [15:0] ex4_memory [0:255]; $readmemh("ex4.mem", ex4_memory, 4);
dead beef 0a0a 1234 abab 987e
NB. As demonstrated by this example, the memory array can have more entries than the data file.
Yosys automatically picks up
$readmemb files, but you need to include the path if the memory file isn’t in the same directory as the Verilog module. You can see examples of this in the iCEBreaker designs for Hardware Sprites.
The easy way to get memory files working with Vivado is to give them the
.mem extension then add them to your project. You do this as you would for a design or simulation source using “Add Sources” then selecting “Files of type: Memory Initialization Files”. Vivado will automatically identify them as memory files and place them in the current working directory during simulation etc.
If you reference a file but don’t add it to the project, you’ll get an error of the form:
WARNING: File rom_image.mem referenced on acme.v at line 42 cannot be opened for reading. Please ensure that this file is available in the current working directory.
Once you’ve added the files to your project, they will show up in the Sources view under Design or Simulation Sources.
Check out my FPGA demos and tutorials for more tasty FPGA goodness.
Have a question or suggestion? Contact @WillFlux or join me on Project F Discussions or 1BitSquared Discord. If you like what I do, consider sponsoring me on GitHub. Thank you.
The wonderful image of the Micron MT4C1024 DRAM used in the social media card for this post comes from Zeptobars and is licensed under a Creative Commons licence.