1Verilog::Readmem(3) User Contributed Perl Documentation Verilog::Readmem(3)
2
6 Verilog::Readmem - Parse Verilog $readmemh or $readmemb text file
7
9 This document refers to Verilog::Readmem version 0.04.
10
12 use Verilog::Readmem qw(parse_readmem);
13 # Read memory file into Array-Of-Arrays data structure:
15 my $mem_ref = parse_readmem({filename => 'memory.hex'});
16 my $num_blocks = scalar @{$mem_ref};
18 print "num_blocks = $num_blocks\n";
19 # 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
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 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 "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 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 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 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
70 parse_readmem
71 Read in a Verilog $readmem format text file and return the addresses
73 and data as a reference to an array of arrays. All comments are
74 stripped out. All options to the "parse_readmem" function must be
75 passed as a single hash.
76 OPTIONS
78 filename
79 A filename must be provided.
80 my $mem_ref = parse_readmem({filename => 'memory.hex'});
82 binary
84 By default, the input file format is hexadecimal, consistent with
85 the Verilog "$readmemh()" system task. To read in a binary format,
86 consistent with the Verilog "$readmemb()" system task, use
87 "binary=>1".
88 my $mem_ref = parse_readmem({filename=>$file, binary=>1});
90 string
92 By default, all addresses and data values will be converted to
93 numeric (decimal) values. If numeric conversion is not desired,
94 use "string=>1".
95 my $mem_ref = parse_readmem({filename=>$file, string=>1});
97 In numeric conversion mode, data must represent 2-state logic (0
99 and 1). If an application requires 4-state logic (0, 1, x, z),
100 numeric conversion must be disabled using "string=>1".
101 To parse a binary format file using string mode:
103 my $mem_ref = parse_readmem(
105 {
106 string => 1,
107 binary => 1,
108 filename => '/path/to/file.bin'
109 }
110 );
111 EXAMPLE
113 The returned array-of-arrays has the following structure:
114 [a0, d01, d02, d03],
116 [a1, d11, d12, d13, d14, d15],
117 [a2, d21, d22]
118 Each array corresponds to a block of memory. The first item in each
120 array is the start address of the block. All subsequent items are data
121 values. In the example above, there are 3 memory blocks. The 1st
122 block starts at address a0 and has 3 data values. The 2nd block starts
123 at address a1 and has 5 data values. The 3rd block starts at address
124 a2 and has 2 data values.
125 EXPORT
127 None by default.
128
130 Error conditions cause the program to die using "croak" from the
131 standard "Carp.pm" module.
132
134 In the default numeric conversion mode, address and data values may not
135 be larger than 32-bit. If an application requires larger values,
136 numeric conversion must be disabled using "string=>1". This allows for
137 post-processing of strings in either hexadecimal or binary format.
138
140 Refer to the following Verilog documentation:
141 IEEE Standard Verilog (c) Hardware Description Language
143 IEEE Std 1364-2001
144 Version C
145 Section 17.2.8, "Loading memory data from a file"
146
148 Gene Sullivan (gsullivan@cpan.org)
149
151 Copyright (c) 2008 Gene Sullivan. All rights reserved.
152 This module is free software; you can redistribute it and/or modify it
154 under the same terms as Perl itself. See perlartistic.
155perl v5.12.0 2009-01-05 Verilog::Readmem(3)