1Verilog::Readmem(3)   User Contributed Perl Documentation  Verilog::Readmem(3)
2
3
4

NAME

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

VERSION

9       This document refers to Verilog::Readmem version 0.05.
10

SYNOPSIS

12           use Verilog::Readmem qw(parse_readmem);
13
14           # Read memory file into Array-Of-Arrays data structure:
15           my $mem_ref = parse_readmem({filename => 'memory.hex'});
16
17           my $num_blocks = scalar @{$mem_ref};
18           print "num_blocks = $num_blocks\n";
19
20           # It is typical to have only one data block.
21           # Sum up all data values.
22           if ($num_blocks == 1) {
23               my ($addr, @data) = @{ $mem_ref->[0] };
24               my $sum = 0;
25               for (@data) { $sum += $_ }
26               print "addr = $addr, data sum = $sum\n";
27           }
28

DESCRIPTION

30       The Verilog Hardware Description Language (HDL) provides a convenient
31       way to load a memory during logic simulation.  The "$readmemh()" and
32       "$readmemb()" system tasks are used in the HDL source code to import
33       the contents of a text file into a memory variable.
34
35       In addition to having the simulator software read in these memory
36       files, it is also useful to analyze the contents of the file outside of
37       the simulator.  For example, it may be useful to derive some simulation
38       parameters from the memory file prior to running the simulation.  Data
39       stored at different addresses may be combined arithmetically to produce
40       other meaningful values.  In some cases, it is simpler to perform these
41       calculations outside of the simulator.
42
43       "Verilog::Readmem" emulates the Verilog "$readmemh()" and "$readmemb()"
44       system tasks.  The same memory file which is read in by the simulator
45       can also be read into a Perl program, potentially easing the burden of
46       having the HDL code perform numeric calculations or string
47       manipulations.
48
49   Input File Syntax
50       The syntax of the text file is described in the documentation of the
51       IEEE standard for Verilog.  Briefly, the file contains two types of
52       tokens: data and optional addresses.  The tokens are separated by
53       whitespace and comments.  Comments may be single-line (//) or multi-
54       line (/**/), similar to C++.  Addresses are specified by a leading "at"
55       character (@) and are always hexadecimal strings.  Data values are
56       either hexadecimal strings ($readmemh) or binary strings ($readmemb).
57       Data and addresses may contain underscore (_) characters.  The syntax
58       supports 4-state logic for data values (0, 1, x, z), where x represents
59       an unknown value and z represents the high impedance value.
60
61       If no address is specified, the data is assumed to start at address 0.
62       Similarly, if data exists before the first specified address, then that
63       data is assumed to start at address 0.
64
65       There are many corner cases which are not explicitly mentioned in the
66       Verilog document.  In each instance, this module was designed to behave
67       the same as two widely-known, commercially-available simulators.
68

SUBROUTINES

70       parse_readmem
71           Read in a Verilog $readmem format text file and return the
72           addresses and data as a reference to an array of arrays.  All
73           comments are stripped out.  All options to the "parse_readmem"
74           function must be passed as a single hash.
75
76   OPTIONS
77       filename
78           A filename must be provided.
79
80               my $mem_ref = parse_readmem({filename => 'memory.hex'});
81
82       binary
83           By default, the input file format is hexadecimal, consistent with
84           the Verilog "$readmemh()" system task.  To read in a binary format,
85           consistent with the Verilog "$readmemb()" system task, use
86           "binary=>1".
87
88               my $mem_ref = parse_readmem({filename=>$file, binary=>1});
89
90       string
91           By default, all addresses and data values will be converted to
92           numeric (decimal) values.  If numeric conversion is not desired,
93           use "string=>1".
94
95               my $mem_ref = parse_readmem({filename=>$file, string=>1});
96
97           In numeric conversion mode, data must represent 2-state logic (0
98           and 1).  If an application requires 4-state logic (0, 1, x, z),
99           numeric conversion must be disabled using "string=>1".
100
101           To parse a binary format file using string mode:
102
103               my $mem_ref = parse_readmem(
104                               {
105                                   string      => 1,
106                                   binary      => 1,
107                                   filename    => '/path/to/file.bin'
108                               }
109               );
110
111   EXAMPLE
112       The returned array-of-arrays has the following structure:
113
114           [a0, d01, d02, d03],
115           [a1, d11, d12, d13, d14, d15],
116           [a2, d21, d22]
117
118       Each array corresponds to a block of memory.  The first item in each
119       array is the start address of the block.  All subsequent items are data
120       values.  In the example above, there are 3 memory blocks.  The 1st
121       block starts at address a0 and has 3 data values.  The 2nd block starts
122       at address a1 and has 5 data values.  The 3rd block starts at address
123       a2 and has 2 data values.
124

EXPORT

126       None by default.
127

DIAGNOSTICS

129       Error conditions cause the program to die using "croak" from the
130       standard "Carp" module.
131

LIMITATIONS

133       In the default numeric conversion mode, address and data values may not
134       be larger than 32-bit. If an application requires larger values,
135       numeric conversion must be disabled using "string=>1".  This allows for
136       post-processing of strings in either hexadecimal or binary format.
137

SEE ALSO

139       Refer to the following Verilog documentation:
140
141           IEEE Standard Verilog (c) Hardware Description Language
142           IEEE Std 1364-2001
143           Version C
144           Section 17.2.8, "Loading memory data from a file"
145

AUTHOR

147       Gene Sullivan (gsullivan@cpan.org)
148
150       Copyright (c) 2008 Gene Sullivan.  All rights reserved.
151
152       This module is free software; you can redistribute it and/or modify it
153       under the same terms as Perl itself.  See perlartistic.
154
155
156
157perl v5.28.0                      2015-07-09               Verilog::Readmem(3)
Impressum