NAME

Verilog::Readmem - Parse Verilog $readmemh or $readmemb text file

VERSION

This document refers to Verilog::Readmem version 0.05.

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";
    }

DESCRIPTION

The Verilog Hardware Description Language (HDL) provides a convenient way to load a memory during logic simulation. The $readmemh() and $readmemb() system tasks are used in the HDL source code to import the contents of a text file into a memory variable.

In addition to having the simulator software read in these memory files, it is also useful to analyze the contents of the file outside of the simulator. For example, it may be useful to derive some simulation parameters from the memory file prior to running the simulation. Data stored at different addresses may be combined arithmetically to produce other meaningful values. In some cases, it is simpler to perform these calculations outside of the simulator.

Verilog::Readmem emulates the Verilog $readmemh() and $readmemb() system tasks. The same memory file which is read in by the simulator can also be read into a Perl program, potentially easing the burden of having the HDL code perform numeric calculations or string manipulations.

Input File Syntax

The syntax of the text file is described in the documentation of the IEEE standard for Verilog. Briefly, the file contains two types of tokens: data and optional addresses. The tokens are separated by whitespace and comments. Comments may 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. 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.

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.

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.

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.

OPTIONS

filename

A filename must be provided.

    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.

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. The 1st block starts at address a0 and has 3 data values. The 2nd block starts at address a1 and has 5 data values. The 3rd block starts at address a2 and has 2 data values.

EXPORT

None by default.

DIAGNOSTICS

Error conditions cause the program to die using croak from the standard Carp module.

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.

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"

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.

cpanm Verilog::Readmem

perl -MCPAN -e shell
install Verilog::Readmem