Verilog::Readmem(3)

💖 Verilog::Readmem 💖

okay bestie, gather round, because this one is literally the module that reads your Verilog memory files, and it's about to be your new fave. The page you're reading is Verilog::Readmem(3) — a User Contributed Perl doc, and yes, she ate. 💅

---

✨ VERSION ✨

This doc is all about Verilog::Readmem version 0.05. That's the one, no cap.

---

🦋 SYNOPSIS 🦋

use Verilog::Readmem qw(parse_readmem);

# Read memory file into Array-Of-Arrays data structure:
my $mem_ref = parse_readmem({filename => 'memory.hex'});

my $num_blocks = scalar @{$mem_ref};
print "num_blocks = $num_blocks\n";

# It is typical to have only one data block.
# Sum up all data values.
if ($num_blocks == 1) {
    my ($addr, @data) = @{ $mem_ref->[0] };
    my $sum = 0;
    for (@data) { $sum += $_ }
    print "addr = $addr, data sum = $sum\n";
}

like, look at that. three lines of setup and you're parsing hex files. obsessed. 🫶

---

🌈 DESCRIPTION 🌈

So here's the vibe: the Verilog Hardware Description Language (HDL, for short) gives you a super convenient way to load a memory while you're doing logic simulation. The system tasks $readmemh() and $readmemb() get used in your HDL source code to import the contents of a text file straight into a memory variable. iconic behavior, honestly.

But wait — there's more. 👑 Besides letting the simulator software read in these memory files, it's also useful to analyze what's inside that file outside of the simulator. Like, maybe you wanna derive some simulation parameters from the memory file before you even run the simulation. Or maybe data stored at different addresses needs to be combined arithmetically to produce other meaningful values. Sometimes it's just simpler to do those calculations outside of the simulator. fr fr.

Verilog::Readmem emulates the Verilog $readmemh() and $readmemb() system tasks. The same memory file that the simulator reads in can also be read into a Perl program — which potentially eases the burden of making your HDL code do numeric calculations or string manipulations. perl said "I gotchu." 💜

🎀 Input File Syntax 🎀

The syntax of the text file is described in the documentation of the IEEE standard for Verilog. But briefly, bestie: the file contains two types of tokens — data and optional addresses. The tokens are separated by whitespace and comments. Comments can be single-line (//) or multi-line (/**/), similar to C++. Addresses are specified by a leading "at" character (@) and are always hexadecimal strings. Data values are either hexadecimal strings ($readmemh) or binary strings ($readmemb). Data and addresses may contain underscore (_) characters. And the syntax supports 4-state logic for data values (0, 1, x, z), where x represents an unknown value and z represents the high impedance value. 💀 (yes, your data can be a mystery and that's valid.)

If no address is specified, the data is assumed to start at address 0. Similarly, if data exists before the first specified address, then that data is assumed to start at address 0. consistent queen. ✨

There are many corner cases which are not explicitly mentioned in the Verilog document. In each instance, this module was designed to behave the same as two widely-known, commercially-available simulators. so it's not just making things up, it's matching the real ones. 🫡

---

🌸 SUBROUTINES 🌸

💅 parse_readmem

Read in a Verilog $readmem format text file and return the addresses and data as a reference to an array of arrays. All comments are stripped out. All options to the parse_readmem function must be passed as a single hash. one hash, one vibe. 🎀

💖 OPTIONS 💖

• filename — A filename must be provided. like, mandatory mandatory. ngl you can't skip this one.

my $mem_ref = parse_readmem({filename => 'memory.hex'});

• binary — By default, the input file format is hexadecimal, consistent with the Verilog $readmemh() system task. To read in a binary format, consistent with the Verilog $readmemb() system task, use binary=>1.

my $mem_ref = parse_readmem({filename=>$file, binary=>1});

• string — By default, all addresses and data values will be converted to numeric (decimal) values. If numeric conversion is not desired, use string=>1.

my $mem_ref = parse_readmem({filename=>$file, string=>1});

In numeric conversion mode, data must represent 2-state logic (0 and 1). If an application requires 4-state logic (0, 1, x, z), numeric conversion must be disabled using string=>1. no exceptions, bestie. 🚨

To parse a binary format file using string mode:

my $mem_ref = parse_readmem(
                {
                    string      => 1,
                    binary      => 1,
                    filename    => '/path/to/file.bin'
                }
);

⭐ EXAMPLE ⭐

The returned array-of-arrays has the following structure:

[a0, d01, d02, d03],
[a1, d11, d12, d13, d14, d15],
[a2, d21, d22]

Each array corresponds to a block of memory. The first item in each array is the start address of the block. All subsequent items are data values. In the example above, there are 3 memory blocks:

1. The 1st block starts at address a0 and has 3 data values.
2. The 2nd block starts at address a1 and has 5 data values.
3. The 3rd block starts at address a2 and has 2 data values.

see how tidy that is? main character data structure energy. 👑

---

💜 EXPORT 💜

None by default. she gives you nothing unless you ask nicely with qw(parse_readmem). boundaries. respect them. 🎀

---

🚨 DIAGNOSTICS 🚨

Error conditions cause the program to die using croak from the standard Carp module. so if something goes wrong, she's not subtle about it. 😭

---

😭 LIMITATIONS 😭

In the default numeric conversion mode, address and data values may not be larger than 32-bit. If an application requires larger values, numeric conversion must be disabled using string=>1. This allows for post-processing of strings in either hexadecimal or binary format. so big numbers? turn off the conversion, handle it yourself, iykyk. 💅

---

🦋 SEE ALSO 🦋

Refer to the following Verilog documentation:

IEEE Standard Verilog (c) Hardware Description Language
IEEE Std 1364-2001
Version C
Section 17.2.8, "Loading memory data from a file"

like, go read the source, bestie, it's giving ✨authoritative✨.

---

👑 AUTHOR 👑

Gene Sullivan (gsullivan@cpan.org)

---

🌈 COPYRIGHT AND LICENSE 🌈

Copyright (c) 2008 Gene Sullivan. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. 🫶

---

and that's the whole page, bestie!! 🎀 this was perl v5.42.0, dated 2025-07-25, and you just read Verilog::Readmem(3) in full. slay, periodt, go parse some memories. 💖✨🦋🌸💅