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.05.
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
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 OPTIONS
77 filename
78 A filename must be provided.
79 my $mem_ref = parse_readmem({filename => 'memory.hex'});
81 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 my $mem_ref = parse_readmem({filename=>$file, binary=>1});
89 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 my $mem_ref = parse_readmem({filename=>$file, string=>1});
96 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 To parse a binary format file using string mode:
102 my $mem_ref = parse_readmem(
104 {
105 string => 1,
106 binary => 1,
107 filename => '/path/to/file.bin'
108 }
109 );
110 EXAMPLE
112 The returned array-of-arrays has the following structure:
113 [a0, d01, d02, d03],
115 [a1, d11, d12, d13, d14, d15],
116 [a2, d21, d22]
117 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
126 None by default.
127
129 Error conditions cause the program to die using "croak" from the
130 standard "Carp" module.
131
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
139 Refer to the following Verilog documentation:
140 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
147 Gene Sullivan (gsullivan@cpan.org)
148
150 Copyright (c) 2008 Gene Sullivan. All rights reserved.
151 This module is free software; you can redistribute it and/or modify it
153 under the same terms as Perl itself. See perlartistic.
154perl v5.34.0 2022-01-21 Verilog::Readmem(3)