summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/register/reg_list.pl
blob: 16c40cb554b3a44cbbc5867e478f6d34e90da8b5 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
#!/usr/bin/env perl
###############################################################################
#
# File:         reg_list.pl
# RCS:          $Header: /doc_tools/register/reg_list.pl 1.2 2004/08/16 23:37:07 lovell Exp $
# Description:  Output a table (per function) of CSR's in offset order
# Author:       Matthew Lovell
# Created:      Mon Mar 31 16:50:05 2003
# Modified:     Mon Aug 16 17:36:19 2004
# Language:     CPerl
#
# (C) Copyright 2003, Matthew Lovell, all rights reserved.
#
###############################################################################

use lib("$ENV{WJ_HOME}/docs/common",
	"$ENV{WJ_HOME}/docs/common");

use Getopt::Long;
use FileHandle;
use Reg_macro;


# Parameters controlling execution
my $params = 
  {
   file  => "",       # LaTeX file to parse
   list  => 0,        # just list files
   table => 0,        # produce table files
   Make  => 0,        # dependency extraction
  };


$DEBUG = 0;

###############################################################################
#                               M A I N                                       #
###############################################################################

# read options and get files from command-line
get_input_opts($params);
$REG_DEBUG = 1 if ($DEBUG);

my @files = get_tex_files($params->{file}, $params->{Make});

if ($DEBUG or $params->{list}) {
  print "\nFile tree\n";
  print "----------------------------\n";
  print join("\n",@files) . "\n\n";
  exit if ($params->{list});
}


#
# Just output Makefile dependencies and exit
#
if ($params->{Make}) {
  print_depends_list($params->{file},
		     @files);
  exit(0);
}


#
# ...otherwise, go on to extract some register information
#

my @reg_data = ();

for (@files) {
  get_regs($_,\@reg_data)
}

my $reg_hash = build_reg_hash(\@reg_data);

if (!$params->{table}) {
  print_reg_list($reg_hash);
} else {
  make_reg_files($params->{file}, $reg_hash);
}


exit($REG_ERRORS);

###############################################################################
#                         S U B R O U T I N E S                               #
###############################################################################


# Print out file dependencies in a format suitable for use by
# GNU make.  Makefile rules should be setup to update this
# information as necessary.
#
# Arguments: .tex filename
#            array of dependencies
#
sub print_depends_list {
  my ($file, @depends) = @_;

  my @setup_files = qw[preamble.sty];

  # separate all .error files
  my @error_files = grep { $_ =~ /\.error$/ } @depends;

  # separate all .func files
  my @func_files = grep  { $_ =~ /\.func$/ } @depends;

  # ensure output is on STDOUT
  select STDOUT;

  my $aux_file, $dvi_file, $d_file, $ps_file;
  ($aux_file = $file) =~ s/\.tex$/.aux/;
  ($dvi_file = $file) =~ s/\.tex$/.dvi/;
  ($ps_file = $file) =~ s/\.tex$/.ps/;
  ($d_file = $file) =~ s/\.tex$/.d/;


  print "#\n";
  print "# Generated dependency file.  Do NOT check into HMS !!\n";
  print "#\n\n";

  # Print out dependency list for the .aux file itself
  print "$aux_file $dvi_file : \\\n";
  map { print "\t$_ \\\n" } @setup_files;
  map { print "\t$_ \\\n" } @error_files;
  map { print "\t$_ \\\n" } @func_files;

  foreach my $file (@depends) {
    next if ($file =~ m/\.(?:error|func)$/);
    next if ($file =~ m/logo\.eps/);
    print "\t$file \\\n";
  }
  print "\n";


  # Repeat for the .d file, leaving out unneeded files
  print "$d_file : \\\n";

  foreach my $file (@depends) {
    next if ($file =~ m/\.(?:error|func)$/);
    next if ($file =~ m/\.eps$/);
    print "\t$file \\\n";
  }
  print "\n\n";


} # print_depends_list



# Print out register names in offset order to STDOUT.  Used to 
# ensure script is acting correctly.
#
# Arguments: reference to hash constructed by build_reg_hash
#
sub print_reg_list {
  my ($reg_hash) = @_;

  my @functions = keys %$reg_hash;
  
  print "\n";
  for my $func (sort @functions) {

    print "Function $func Registers\n";
    print "-" x 80 . "\n";

    for my $offset (sort { hex($a) <=> hex($b) } keys %{$reg_hash->{$func}}) {
      my $output = "";
      if ($offset =~ /^unk/) {
	$output = sprintf(" ?   %-50s  %-20s", 
			   $reg_hash->{$func}{$offset}{long_name},
			   $reg_hash->{$func}{$offset}{short_name}
			  );
      } else {
	$output = sprintf("%03x  %-50s  %-20s", 
			  hex($offset),
			  $reg_hash->{$func}{$offset}{long_name},
			  $reg_hash->{$func}{$offset}{short_name}
			 );
      }

      print "$output\n";
    }

    print "\n\n";
  }

} # print_reg_list



# Output a LaTeX longtable listing registers in each function. 
#
# Arguments: name of latex file parsed, used as the root for 
#            the table files names
#
#            reference to hash created by build_reg_hash
#
sub make_reg_files {
  my ($orig_file, $reg_hash) = @_;

  my @functions = keys %$reg_hash;
  for my $func (sort @functions) {

    my $filename = $orig_file =~ s/\.tex$//;
    $filename = $orig_file . ".func$func";

    my $file = new FileHandle ">$filename";  
    if (!defined $file) {
      print STDERR "#ERROR reg_list.pl  Unable to open $filename for writing!";
      die;
    }

    for my $offset (sort { hex($a) <=> hex($b) } keys %{$reg_hash->{$func}}) {

      my $name = $reg_hash->{$func}{$offset}{long_name};
      if (defined $reg_hash->{$func}{$offset}{short_name}) {
	$name .= " ($reg_hash->{$func}{$offset}{short_name})";
      }

      my $pageref = "";
      if (exists $reg_hash->{$func}{$offset}{label}) {
	$pageref = '\pageref{' . $reg_hash->{$func}{$offset}{label} . '}';
      }

      if ($offset =~ /^unk/) {
	printf $file "\\texttt{?} & %s & %s \\\\\n",
	  $name, $pageref;	
      } else {
	printf $file "\\texttt{0x%03x} & %s & %s \\\\\n",
	  hex($offset), $name, $pageref;	
      }

    }

    close $file;

  }  


} # make_reg_files


# Retrieve the input parms passed to this script and set the proper
# options.  Some global variables may be set by this subroutine.
#
# Arguments: reference to parameters hash
#
sub get_input_opts {  
  my ($params) = @_;
  my $help     = 0;
  
  # Setup for GetOptions
  $Getopt::Long::autoabbrev = 1;
  $Getopt::Long::ignorecase = 0;
  $Getopt::Long::order = $PERMUTE;

  my @optl = ();
  push(@optl, 
       "help",        \$help,	          # show usage information
       "debug",       \$DEBUG,            # show debug information
       "file=s",      \$params->{file},    # LaTeX file to parse

       "list",        \$params->{list},
       "table",       \$params->{table},
       "Make",        \$params->{Make},
       );

  GetOptions(@optl);

  if ($help) {
    print_usage_and_die();
  }

  if ($params->{file} eq "") {
    print "Must specify a LaTeX file.  Use --help for usage info.\n";
    exit(1);
  }


  return;
} # get_input_opts


sub print_usage_and_die {
   $usage = <<"@@USAGE_INFO";
Register (CSR) Lister

This script parses all register/CSR diagrams found in a LaTeX document.
The document can include or import sub-documents; the script will follow
the tree.

By default, a human-readable list of registers, ordered by offset
within each function, is printed to STDOUT.  If the -table option is
given, files are written with a similar table formatted for inclusion
in a LaTeX document.  The filenames will have the same root as the
file specified on the command-line, but with an extension of 

  .func<function>

for each non-empty function encountered during parsing.

Usage:

  reg_list.pl -file <.tex file> 
               ( [-table] | [-list] | [-Make] )
               [-debug] [-help]


    <.tex file>  LaTeX file to parse

    Mutually exclusive
    ------------------
    -table       Produce LaTeX table output, no STDOUT output
    -list        Show the file tree of <.tex file>, then quit
    -Make        Produce makefile dependencies for specified LaTeX file


    Other options
    -------------
    -debug       Show parsing debug information
    -help        Print this stuff


@@USAGE_INFO

   print $usage;
   exit(1);
} # print_usage_and_die