From 843389c2227465e860193fba7f23dfbfc167e747 Mon Sep 17 00:00:00 2001 From: Brad Gilbert Date: Sun, 19 Apr 2009 14:23:33 -0500 Subject: [PATCH] Improved POD documentation of perl modules --- perl/lib/Nasm/Regs.pm | 61 +++++++++++- perl/lib/Nasm/Regs/Format.pm | 9 +- perl/lib/Nasm/Regs/Format/YAML.pm | 8 +- perl/lib/Nasm/Regs/Register.pm | 19 +++- perl/lib/Nasm/Utils.pm | 19 +++- perl/lib/Nasm/insns.pm | 20 +++- perl/old/regs.pl | 194 ++++++++++++++++++++++++++++++++++++++ perl/t/regs/basic.t | 84 ++++++++--------- perl/t/regs/list.t | 32 +++---- perl/t/version/input.pm | 11 ++- 10 files changed, 383 insertions(+), 74 deletions(-) create mode 100755 perl/old/regs.pl diff --git a/perl/lib/Nasm/Regs.pm b/perl/lib/Nasm/Regs.pm index dd830a3f..b2cb9fb3 100644 --- a/perl/lib/Nasm/Regs.pm +++ b/perl/lib/Nasm/Regs.pm @@ -2,6 +2,10 @@ Nasm::Regs +=head1 DESCRIPTION + +=head1 Subroutines + =cut package Nasm::Regs; @@ -11,6 +15,11 @@ use warnings; require Nasm::Regs::Register; require Nasm::Regs::Format; +=head2 new + +Creates Nasm::Regs object + +=cut sub new{ my($class,$filename) = @_; my $self = bless {}, $class; @@ -23,8 +32,11 @@ sub new{ } +=head2 ProcessFile +Loads the file +=cut sub ProcessFile{ my($self,$filename) = @_; my $file; @@ -45,7 +57,7 @@ sub ProcessFile{ next unless length $line; $current{line} = $line; - $self->ProcessLine(\%current); + $self->_ProcessLine(\%current); } close $file; @@ -54,8 +66,7 @@ sub ProcessFile{ - -sub ProcessLine{ +sub _ProcessLine{ my($self,$current) = @_; unless( $current->{line} =~ /^\s*(\S+)\s*(\S+)\s*(\S+)\s*([0-9]+)$/ ){ @@ -100,11 +111,22 @@ sub ProcessLine{ +=head2 names + +Returns a sorted list of RegisterNames + +=cut sub names{ my($self) = @_; # deprecated return $self->RegisterNames; } + +=head2 RegisterNames + +Returns a sorted list of RegisterNames + +=cut sub RegisterNames{ my($self) = @_; my @keys = sort grep { length $_ } keys %{$self->{register}}; @@ -115,16 +137,34 @@ sub RegisterNames{ +=head2 Register( $register_name ) + +Returns a Register object + +=cut sub Register{ - my($self,$key) = @_; - return $self->{register}{$key}; + my($self,$register_name) = @_; + return $self->{register}{$register_name}; } + +=head2 DisassemblerClasses + +Returns a sorted list of DisassemblerClasses + +=cut sub DisassemblerClasses{ my($self) = @_; my @return = sort keys %{$self->{disassembler}}; + return @return if wantarray; return \@return; } + +=head2 DisassemblerClass( $class ) + + + +=cut sub DisassemblerClass{ my($self,$class) = @_; my $return = $self->{disassembler}{$class}; @@ -133,12 +173,23 @@ sub DisassemblerClass{ } +=head2 format( $format_type ) + +Returns regs info in a given format + +=cut sub format{ my($self,$fmt) = @_; + require Nasm::Regs::Format; Nasm::Regs::Format::format($self,$fmt); } +=head2 filename + +Returns the name of the file the data was loaded from + +=cut sub filename{ my($self) = @_; return $self->{filename}; diff --git a/perl/lib/Nasm/Regs/Format.pm b/perl/lib/Nasm/Regs/Format.pm index 978821ce..7d0610bc 100644 --- a/perl/lib/Nasm/Regs/Format.pm +++ b/perl/lib/Nasm/Regs/Format.pm @@ -2,6 +2,12 @@ Nasm::Regs::Format +=head1 DESCRIPTION + + + +=head1 Subroutines + =cut package Nasm::Regs::Format; @@ -12,8 +18,9 @@ use warnings; =head2 format -=cut +Returns regs info in a given format +=cut sub format{ my($regs,$fmt) = @_; ## no critic diff --git a/perl/lib/Nasm/Regs/Format/YAML.pm b/perl/lib/Nasm/Regs/Format/YAML.pm index afdc1006..30d0e639 100644 --- a/perl/lib/Nasm/Regs/Format/YAML.pm +++ b/perl/lib/Nasm/Regs/Format/YAML.pm @@ -20,10 +20,10 @@ sub _format{ for my $name (@names){ my $reg = $regs->Register($name); $data{$name} = { - AssemblerClass => $reg->AssemblerClass, - DisassemberClasses => [$reg->DisassemberClasses], - x86RegisterNumber => $reg->x86RegisterNumber, - Index => $count++ + AssemblerClass => $reg->AssemblerClass, + DisassemblerClasses => [$reg->DisassemblerClasses], + x86RegisterNumber => $reg->x86RegisterNumber, + Index => $count++ } } diff --git a/perl/lib/Nasm/Regs/Register.pm b/perl/lib/Nasm/Regs/Register.pm index 24a73c26..19140433 100644 --- a/perl/lib/Nasm/Regs/Register.pm +++ b/perl/lib/Nasm/Regs/Register.pm @@ -2,12 +2,19 @@ Nasm::Regs::Register +=head1 DESCRIPTION + +=head1 Subroutines + =cut package Nasm::Regs::Register; use strict; use warnings; +=head2 new + +=cut sub new{ my($class,@v) = @_; $v[0] =~ s/^\s+|\s+$//g; @@ -17,6 +24,13 @@ sub new{ return $self; } +=head2 RegisterName + +=head2 AssemblerClass + +=head2 x86RegisterNumber + +=cut BEGIN{ ## no critic my $i = -1; @@ -33,7 +47,10 @@ BEGIN{ ## use critic } -sub DisassemberClasses{ +=head2 DisassemblerClasses + +=cut +sub DisassemblerClasses{ my($self) = @_; my @classes; if( ref $self->[2] ){ diff --git a/perl/lib/Nasm/Utils.pm b/perl/lib/Nasm/Utils.pm index a7900e53..8363e915 100644 --- a/perl/lib/Nasm/Utils.pm +++ b/perl/lib/Nasm/Utils.pm @@ -1,6 +1,12 @@ =head1 NAME -Nasm::Regs::Register +Nasm::Utils + +=head1 DESCRIPTION + +Several utilities used in other modules + +=head1 Subroutines =cut @@ -15,8 +21,11 @@ our @EXPORT_OK = qw{ addprefix }; +=head2 str2hex + +Turn a numeric list into a hex string -# Turn a numeric list into a hex string +=cut sub str2hex{ my @return = map {sprintf("%02X", $_)} @_; @@ -24,6 +33,12 @@ sub str2hex{ return join '', @return; } +=head2 addprefix( $prefix, @list ) + +Takes a prefix, and a list of strings, and +adds the prefix to each element in the list + +=cut sub addprefix{ my ($prefix, @list) = @_; my @return = map { diff --git a/perl/lib/Nasm/insns.pm b/perl/lib/Nasm/insns.pm index 3d0fe652..7a2f242b 100644 --- a/perl/lib/Nasm/insns.pm +++ b/perl/lib/Nasm/insns.pm @@ -2,6 +2,12 @@ Nasm::insns +=head1 DESCRIPTION + +Loads info from insns.dat + +=head1 Subroutines + =cut package Nasm::insns; @@ -31,6 +37,11 @@ for( my $m = 0; $m < 32; $m++ ){ our @bytecode_count = (0) x 256; +=head2 new + +creates a new insns object + +=cut sub new{ my($class,$filename) = @_; @@ -43,6 +54,11 @@ sub new{ return $self; } +=head2 ProcessFile + +Reads the file + +=cut sub ProcessFile{ my( $self, $filename ) = @_; open( my $file, '<', $filename ) || die "unable to open $filename"; @@ -57,11 +73,11 @@ sub ProcessFile{ # /^\s*(?:;\#)(.*)$/ # special lines next if $line =~ /^\s*(?:;|$)/ ; # comments or blank lines - $self->ProcessLine($line,$line_number); + $self->_ProcessLine($line,$line_number); } } -sub ProcessLine{ +sub _ProcessLine{ my( $self, $line, $line_number ) = @_; unless( $line =~ m{ diff --git a/perl/old/regs.pl b/perl/old/regs.pl new file mode 100755 index 00000000..4fc30df1 --- /dev/null +++ b/perl/old/regs.pl @@ -0,0 +1,194 @@ +#!/usr/bin/env perl +# +# Read regs.dat and output regs.h and regs.c (included in names.c) +# + +use lib 'perllib'; + +$nline = 0; + +sub toint($) { + my($v) = @_; + + return ($v =~ /^0/) ? oct $v : $v+0; +} + +sub process_line($) { + my($line) = @_; + my @v; + + if ( $line !~ /^\s*(\S+)\s*(\S+)\s*(\S+)\s*([0-9]+)$/i ) { + die "regs.dat:$nline: invalid input\n"; + } + $reg = $1; + $aclass = $2; + $dclasses = $3; + $x86regno = toint($4); + + if ($reg =~ /^(.*[^0-9])([0-9]+)\-([0-9]+)(|[^0-9].*)$/) { + $nregs = $3-$2+1; + $reg = $1.$2.$4; + $reg_nr = $2; + $reg_prefix = $1; + $reg_suffix = $4; + } else { + $nregs = 1; + undef $reg_prefix, $reg_suffix; + } + + while ($nregs--) { + $regs{$reg} = $aclass; + $regvals{$reg} = $x86regno; + + foreach $dclass (split(/,/, $dclasses)) { + if ( !defined($disclass{$dclass}) ) { + $disclass{$dclass} = []; + } + + $disclass{$dclass}->[$x86regno] = $reg; + push @{$drclass{$reg}}, $dclass; + } + + # Compute the next register, if any + if (defined($reg_prefix)) { + $x86regno++; + $reg_nr++; + $reg = sprintf("%s%u%s", $reg_prefix, $reg_nr, $reg_suffix); + } else { + # Not a dashed sequence + die if ($nregs); + } + } +} + +($fmt, $file) = @ARGV; + +%regs = (); +%regvals = (); +%disclass = (); +open(REGS, "< ${file}") or die "$0: Cannot open $file\n"; +while ( defined($line = ) ) { + $nline++; + + chomp $line; + $line =~ s/\s*(\#.*|)$//; + + next if ( $line eq '' ); + + process_line($line); +} +close(REGS); + +if ( $fmt eq 'h' ) { + # Output regs.h + print "/* automatically generated from $file - do not edit */\n\n"; + print "#ifndef NASM_REGS_H\n"; + print "#define NASM_REGS_H\n\n"; + + $expr_regs = 1; + printf "#define EXPR_REG_START %d\n\n", $expr_regs; + print "enum reg_enum {\n"; + # Unfortunately the code uses both 0 and -1 as "no register" in + # different places... + print " R_zero = 0,\n"; + print " R_none = -1,\n"; + $attach = ' = EXPR_REG_START'; # EXPR_REG_START == 1 + foreach $reg ( sort(keys(%regs)) ) { + print " R_\U${reg}\E${attach},\n"; + $attach = ''; + $expr_regs++; + } + print " REG_ENUM_LIMIT\n"; + print "};\n\n"; + printf "#define EXPR_REG_END %d\n\n", $expr_regs-1; + foreach $reg ( sort(keys(%regs)) ) { + printf "#define %-15s %2d\n", "REG_NUM_\U${reg}", $regvals{$reg}; + } + print "\n\n#endif /* NASM_REGS_H */\n"; +} elsif ( $fmt eq 'c' ) { + # Output regs.c + print "/* automatically generated from $file - do not edit */\n\n"; + print "#include \"tables.h\"\n\n"; + print "const char * const nasm_reg_names[] = "; $ch = '{'; + # This one has no dummy entry for 0 + foreach $reg ( sort(keys(%regs)) ) { + print "$ch\n \"${reg}\""; + $ch = ','; + } + print "\n};\n"; +} elsif ( $fmt eq 'fc' ) { + # Output regflags.c + print "/* automatically generated from $file - do not edit */\n\n"; + print "#include \"tables.h\"\n"; + print "#include \"nasm.h\"\n\n"; + print "const int32_t nasm_reg_flags[] = {\n"; + printf " 0,\n"; # Dummy entry for 0 + foreach $reg ( sort(keys(%regs)) ) { + # Print the class of the register + printf " %-15s /* %-5s */\n", + $regs{$reg}.',', $reg; + } + print "};\n"; +} elsif ( $fmt eq 'vc' ) { + # Output regvals.c + print "/* automatically generated from $file - do not edit */\n\n"; + print "#include \"tables.h\"\n\n"; + print "const int nasm_regvals[] = {\n"; + print " -1,\n"; # Dummy entry for 0 + foreach $reg ( sort(keys(%regs)) ) { + # Print the x86 value of the register + printf " %2d, /* %-5s */\n", $regvals{$reg}, $reg; + } + print "};\n"; +} elsif ( $fmt eq 'dc' ) { + # Output regdis.c + print "/* automatically generated from $file - do not edit */\n\n"; + print "#include \"regdis.h\"\n\n"; + foreach $class ( sort(keys(%disclass)) ) { + printf "const enum reg_enum nasm_rd_%-8s[%2d] = {", + $class, scalar @{$disclass{$class}}; + @foo = @{$disclass{$class}}; + @bar = (); + for ( $i = 0 ; $i < scalar(@foo) ; $i++ ) { + if (defined($foo[$i])) { + push(@bar, "R_\U$foo[$i]\E"); + } else { + die "$0: No register name for class $class, value $i\n"; + } + } + print join(',', @bar), "};\n"; + } +} elsif ( $fmt eq 'dh' ) { + # Output regdis.h + print "/* automatically generated from $file - do not edit */\n\n"; + print "#ifndef NASM_REGDIS_H\n"; + print "#define NASM_REGDIS_H\n\n"; + print "#include \"regs.h\"\n\n"; + foreach $class ( sort(keys(%disclass)) ) { + printf "extern const enum reg_enum nasm_rd_%-8s[%2d];\n", + $class, scalar @{$disclass{$class}}; + } + print "\n#endif /* NASM_REGDIS_H */\n"; +} elsif ( $fmt eq 'yaml' ) { + require YAML::XS; + + my @names = sort keys %regs; + my %data; + + my $count = 1; + for my $name (@names){ + $data{$name} = { + AssemblerClass => $regs{$name}, + DisassemblerClasses => $drclass{$name}, + x86RegisterNumber => $regvals{$name}, + Index => $count++ + } + } + + print YAML::XS::Dump(\%data), "\n"; +} elsif ( $fmt eq 'order' ) { + use 5.010; + say for sort keys %regs; +} else { + die "$0: Unknown output format\n"; +} diff --git a/perl/t/regs/basic.t b/perl/t/regs/basic.t index ef10cf05..66fdb899 100644 --- a/perl/t/regs/basic.t +++ b/perl/t/regs/basic.t @@ -73,216 +73,216 @@ gs REG_FSGS sreg 5 --- ah: AssemblerClass: REG_HIGH - DisassemberClasses: + DisassemblerClasses: - reg8 x86RegisterNumber: 4 al: AssemblerClass: REG_AL - DisassemberClasses: + DisassemblerClasses: - reg8 - reg8_rex x86RegisterNumber: 0 ax: AssemblerClass: REG_AX - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 0 bh: AssemblerClass: REG_HIGH - DisassemberClasses: + DisassemblerClasses: - reg8 x86RegisterNumber: 7 bl: AssemblerClass: REG8NA - DisassemberClasses: + DisassemblerClasses: - reg8 - reg8_rex x86RegisterNumber: 3 bp: AssemblerClass: REG16NA - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 5 bpl: AssemblerClass: REG8NA - DisassemberClasses: + DisassemblerClasses: - reg8_rex x86RegisterNumber: 5 bx: AssemblerClass: REG16NA - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 3 ch: AssemblerClass: REG_HIGH - DisassemberClasses: + DisassemblerClasses: - reg8 x86RegisterNumber: 5 cl: AssemblerClass: REG_CL - DisassemberClasses: + DisassemblerClasses: - reg8 - reg8_rex x86RegisterNumber: 1 cs: AssemblerClass: REG_CS - DisassemberClasses: + DisassemblerClasses: - sreg x86RegisterNumber: 1 cx: AssemblerClass: REG_CX - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 1 dh: AssemblerClass: REG_HIGH - DisassemberClasses: + DisassemblerClasses: - reg8 x86RegisterNumber: 6 di: AssemblerClass: REG16NA - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 7 dil: AssemblerClass: REG8NA - DisassemberClasses: + DisassemblerClasses: - reg8_rex x86RegisterNumber: 7 dl: AssemblerClass: REG_DL - DisassemberClasses: + DisassemblerClasses: - reg8 - reg8_rex x86RegisterNumber: 2 ds: AssemblerClass: REG_DESS - DisassemberClasses: + DisassemblerClasses: - sreg x86RegisterNumber: 3 dx: AssemblerClass: REG_DX - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 2 eax: AssemblerClass: REG_EAX - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 0 ebp: AssemblerClass: REG32NA - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 5 ebx: AssemblerClass: REG32NA - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 3 ecx: AssemblerClass: REG_ECX - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 1 edi: AssemblerClass: REG32NA - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 7 edx: AssemblerClass: REG_EDX - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 2 es: AssemblerClass: REG_DESS - DisassemberClasses: + DisassemblerClasses: - sreg x86RegisterNumber: 0 esi: AssemblerClass: REG32NA - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 6 esp: AssemblerClass: REG32NA - DisassemberClasses: + DisassemblerClasses: - reg32 x86RegisterNumber: 4 fs: AssemblerClass: REG_FSGS - DisassemberClasses: + DisassemblerClasses: - sreg x86RegisterNumber: 4 gs: AssemblerClass: REG_FSGS - DisassemberClasses: + DisassemblerClasses: - sreg x86RegisterNumber: 5 rax: AssemblerClass: REG_RAX - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 0 rbp: AssemblerClass: REG64NA - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 5 rbx: AssemblerClass: REG64NA - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 3 rcx: AssemblerClass: REG_RCX - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 1 rdi: AssemblerClass: REG64NA - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 7 rdx: AssemblerClass: REG_RDX - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 2 rsi: AssemblerClass: REG64NA - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 6 rsp: AssemblerClass: REG64NA - DisassemberClasses: + DisassemblerClasses: - reg64 x86RegisterNumber: 4 si: AssemblerClass: REG16NA - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 6 sil: AssemblerClass: REG8NA - DisassemberClasses: + DisassemblerClasses: - reg8_rex x86RegisterNumber: 6 sp: AssemblerClass: REG16NA - DisassemberClasses: + DisassemblerClasses: - reg16 x86RegisterNumber: 4 spl: AssemblerClass: REG8NA - DisassemberClasses: + DisassemblerClasses: - reg8_rex x86RegisterNumber: 4 ss: AssemblerClass: REG_DESS - DisassemberClasses: + DisassemblerClasses: - sreg x86RegisterNumber: 2 ... diff --git a/perl/t/regs/list.t b/perl/t/regs/list.t index 3f4dc92a..296d273f 100644 --- a/perl/t/regs/list.t +++ b/perl/t/regs/list.t @@ -30,82 +30,82 @@ __DATA__ --- xmm0: AssemblerClass: XMM0 - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 0 xmm1: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 1 xmm10: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 10 xmm11: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 11 xmm12: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 12 xmm13: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 13 xmm14: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 14 xmm15: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 15 xmm2: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 2 xmm3: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 3 xmm4: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 4 xmm5: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 5 xmm6: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 6 xmm7: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 7 xmm8: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 8 xmm9: AssemblerClass: XMMREG - DisassemberClasses: + DisassemblerClasses: - xmmreg x86RegisterNumber: 9 ... diff --git a/perl/t/version/input.pm b/perl/t/version/input.pm index 32d6d0b3..bfa88aed 100644 --- a/perl/t/version/input.pm +++ b/perl/t/version/input.pm @@ -118,7 +118,7 @@ sub load{ 1; __DATA__ --- -# currently must only have what would be output with version.pl dump +# currently must only have what would be output with version.pl perl 0.98.09b: major: 0 mangled: 0.98.09b @@ -264,6 +264,15 @@ __DATA__ patchlevel: 98 rc: 8 subminor: 99 +2.06rc10: + major: 2 + minor: 5 + id: 33907556 + mangled: 2.05.99.100 + patchlevel: 100 + rc: 10 + subminor: 99 + xid: 0x02056364 ... -- 2.11.4.GIT