Initial commit of OpenSPARC T2 architecture model.

[OpenSPARC-T2-SAM] / sam-t2 / sam / cpus / vonk / n2 / lib / ras / bin / xml2reg

use XML::Simple;
use FileHandle;
use Getopt::Std;
use Data::Dumper;
use Storable qw( dclone );
use strict;
use vars qw( $opt_n $opt_S $opt_I $opt_h $opt_d $opt_v $opt_r $opt_o $opt_t
            $opt_p);
use vars qw( @ORIG_ARGS );
use vars qw( $debug );

$debug = 0;
@ORIG_ARGS = @ARGV;
getopts('n:S:I:hdvropt');
# n - Additional namepaces separated by commas
# S - source file destination path
# I - include file destination path
# h - help 
# d - dump internal representation, then quit
# v - validate register, then quit
# p - include pretty print routines, e.g. toString()
# t - not to make the register a BL_ThinFieldObj-derived class

main();

####################################################################
####################################################################
####################################################################

sub print_debug
{
   if( $debug ){
       print @_;
   }
}

####################################################################
####################################################################
####################################################################

sub main
{
   if( defined $opt_h ){
       $0 =~ s#.*/##;
       print "usage: $0 [-h|d|v] [-I include path] [-S source path] [-n csv namespace list] <xml file names>\n";
       exit 0;
   }

   for my $xml_file ( @ARGV ){
       gen_regs( $xml_file );
   }
   
   return 0;
}

####################################################################
####################################################################
####################################################################

sub get_xml_hash
{
   my ( $xml_file, $leaf ) = @_;
   my $xs = XML::Simple->new();
   my $xml_hash = $xs->XMLin( $xml_file );

   # If the register has only one entry, fix it up.
   # This is a consequence of using the XML::Simple library. 
   if( defined $xml_hash->{register}->{field}->{name} ){
       # copy the single field to the single field's name.  Then remove
       # all of the other key's using fix_hash.
       $xml_hash->{register}->{field}->{$xml_hash->{register}->{field}->{name}} = dclone( $xml_hash->{register}->{field} );
       fix_hash( $xml_hash->{register} );
   }

   if ( defined $xml_hash->{register}->{inherits} ){
       my $parent_xml_hash;
       my $parent_file = $xml_hash->{register}->{inherits};
       #$parent_file = $opt_S . "/" . $parent_file if defined $opt_S;
       $parent_xml_hash = get_xml_hash( $parent_file, 0 );
       $xml_hash = merge_parent_child( $parent_xml_hash, $xml_hash, $leaf );
       $xml_hash->{register}->{inheritance_info}->{other_ancestor} = 1;
       $xml_hash->{register}->{inheritance_info}->{ancestor_xml} = $parent_file;
   } elsif ( $leaf ) {
       for my $field_name ( keys (%{$xml_hash->{register}->{field}}) ){
           $xml_hash->{register}->{field}->{$field_name}->{generate_data} = 1;
       }
   }

   if( $leaf && defined $xml_hash->{register}->{inheritance_info}->{other_ancestor} ){
       my $inh_xml_file = $xml_hash->{register}->{inheritance_info}->{ancestor_xml};
       my $inh_include_file = $inh_xml_file;

       #$inh_include_file =~ s/\.xml$/.h/;
       my $inh_class_name;
       if( $inh_xml_file =~ m#\b(\w[\w\d]*)\.xml$# ){
           $inh_class_name = $1;
           $inh_include_file = $1.".h";
       } else {
           die "$0: couldn't extract class name from \"$inh_xml_file\"\n";
       }

       $xml_hash->{register}->{inheritance_info}->{include_file} = $inh_include_file;
       $xml_hash->{register}->{inheritance_info}->{ancestor_class} = $inh_class_name;

   }

   return $xml_hash;
}

####################################################################
####################################################################
####################################################################

sub location_match
{
   my ( $p, $start_o, $end_o ) = @_;

   for my $field ( keys (%{$p->{field}}) ){
       return $field if ( $p->{field}->{$field}->{start_offset} == $start_o && 
                          $p->{field}->{$field}->{end_offset}   == $end_o );
   }
    
   return -1;
}

####################################################################
####################################################################
####################################################################

sub merge_parent_child
{
   my ( $parent_h, $child_h, $leaf ) = @_;
   my ( $p, $c ) = ( $parent_h->{register}, $child_h->{register} );

   print_debug "Merging $p->{class_name} into $c->{class_name}\n";
   my $old_class_name = $p->{class_name};
   my $new_class_name = $c->{class_name};
   # top-level informational tags
   $p->{class_name} = $c->{class_name};
   $p->{name} = $c->{name} if defined $c->{name};
   $p->{submodule} = $c->{submodule} if defined $c->{submodule};
   $p->{priv} = $c->{priv} if defined $c->{priv};
   $p->{comment} .= $c->{comment} if defined $c->{comment};
   $p->{base_address} .= $c->{base_address} if defined $c->{base_address};
   $p->{count} .= $c->{count} if defined $c->{count};
   $p->{stride} .= $c->{stride} if defined $c->{stride};
   delete $p->{public};
   $p->{public} .= $c->{public} if defined $c->{public};
   delete $p->{protected};
   $p->{protected} .= $c->{protected} if defined $c->{protected};
   delete $p->{private};
   $p->{private} .= $c->{private} if defined $c->{private};

   # copy any new aggregations that are in the child
   if( defined $c->{aggregate} ){
       for my $agg ( keys (%{$c->{aggregate}}) ){
           $p->{aggregate}->{$agg} = dclone( $c->{aggregate}->{$agg} );
       }
   }

   
   # don't generate any fields by default.
   for my $field ( keys (%{$p->{field}}) ){
       $p->{field}->{$field}->{generate_data} = 0;
   }


   for my $field ( keys (%{$c->{field}}) ){
       my $field_name = location_match( 
               $p, 
               $c->{field}->{$field}->{start_offset}, 
               $c->{field}->{$field}->{end_offset} );
       
       # there's a field in the parent that matches the child's location
       if( $field_name != -1 ){
           print_debug "Merging field '$field_name'\n"; 
           if( defined $c->{field}->{$field}->{comment} ){
               print_debug "     Merged comment from $old_class_name.$field_name to $new_class_name.$field\n";
               $p->{field}->{$field_name}->{comment} = $c->{field}->{$field}->{comment};
           }
           if( defined $c->{field}->{$field}->{base_address} ){
               print_debug "     Merged base_address from $old_class_name.$field_name to $new_class_name.$field\n";
               $p->{field}->{$field_name}->{base_address} = $c->{field}->{$field}->{base_address};
           }
           if( defined $c->{field}->{$field}->{count} ){
               print_debug "     Merged count from $old_class_name.$field_name to $new_class_name.$field\n";
               $p->{field}->{$field_name}->{count} = $c->{field}->{$field}->{count};
           }
           if( defined $c->{field}->{$field}->{stride} ){
               print_debug "     Merged stride from $old_class_name.$field_name to $new_class_name.$field\n";
               $p->{field}->{$field_name}->{stride} = $c->{field}->{$field}->{stride};
           }
           if( defined $c->{field}->{$field}->{protection} ){
               print_debug "     Merged protection from $old_class_name.$field_name to $new_class_name.$field ";
               print_debug "(old = $p->{field}->{$field_name}->{protection}, new = $c->{field}->{$field}->{protection})\n";
               $p->{field}->{$field_name}->{protection} = $c->{field}->{$field}->{protection};
           }
           if( defined $c->{field}->{$field}->{field_type} ){
               print_debug "     Merged field_type from $old_class_name.$field_name to $new_class_name.$field ";
               print_debug "(old=$p->{field}->{$field_name}->{field_type} new=$c->{field}->{$field}->{field_type})\n";
               $p->{field}->{$field_name}->{field_type} = $c->{field}->{$field}->{field_type} ;
           }
           if( defined $c->{field}->{$field}->{initial_value} ){
               print_debug "     Merged intial_value from $old_class_name.$field_name to $new_class_name.$field ";
               print_debug "(old=$p->{field}->{$field_name}->{initial_value} new=$c->{field}->{$field}->{initial_value})\n";
               $p->{field}->{$field_name}->{initial_value} = $c->{field}->{$field}->{initial_value} ;
           }
           if( defined $c->{field}->{$field}->{format} ){
               print_debug "Merged format from $old_class_name.$field_name to $new_class_name.$field\n";
               $p->{field}->{$field_name}->{format} = dclone( $c->{field}->{$field}->{format} );
           }

           # If this statement is true, then the field has been renamed in the child
           # Since we've merged everything into the parent, then we'll need clone the 
           # parent's field (containing the merged data) and assign it to the new name.  
           # Then we can remove copy under the old field name
           if( $field ne $field_name ){
               $p->{field}->{$field} = dclone( $p->{field}->{$field_name} );
               delete( $p->{field}->{$field_name} );
               $p->{field}->{$field}->{generate_data} = $leaf;
           }
       } else {
           print_debug "Adding new field '$field' from child\n"; 
           # no field matches child's location, so we add it.
           $p->{field}->{$field} = dclone( $c->{field}->{$field} );
           $p->{field}->{$field}->{generate_data} = $leaf;
       }
   }


   return $parent_h;
}

####################################################################
####################################################################
####################################################################

sub gen_regs
{
   my( $xml_file ) = @_;

   my $xml_hash = get_xml_hash( $xml_file, 1 );

   if( defined $opt_d ){
       print Dumper( $xml_hash );
       my $register_ref = $xml_hash->{register};
       print Dumper( $register_ref );
       exit 0;
   } 

   my $register_ref = $xml_hash->{register};
   if( defined $register_ref->{name} ){
       # single register 
       gen_cpp( $xml_file, $register_ref->{name}, $register_ref );

   } else {
       foreach my $reg_name ( keys (%{$register_ref}) ){
           $register_ref->{$reg_name}->{name} = $reg_name;
           gen_cpp( $xml_file, $reg_name, $register_ref->{$reg_name} );
       }
   }

}

####################################################################
####################################################################
####################################################################

sub gen_cpp
{
   my ( $xml_file, $name, $register_ref ) = @_;
   my( $h_file_name, $cc_file_name );

   calculate_sizes( $register_ref );
   
   if( !validate( $register_ref ) ){
       exit 1;
   }
   return if defined $opt_v;
   
   my $include_path = ".";
   my $source_path = ".";
   $include_path = $opt_I if defined $opt_I;
   $source_path = $opt_S if defined $opt_S;
   if( ! -d $include_path ){
       system( "mkdir -p $include_path" );
   }
   if( ! -d $source_path ){
       system( "mkdir -p $source_path" );
   }

   $h_file_name = xlate_path( $register_ref->{class_name}, $include_path, "h" );
   $cc_file_name = xlate_path( $register_ref->{class_name}, $source_path, "cc" );

   
   open DOT_H_FILE, ">$h_file_name" or die "couldn't create $h_file_name"; 
   open DOT_CC_FILE, ">$cc_file_name" or die "couldn't create $cc_file_name"
       if !$opt_t;

   print "$xml_file -> $h_file_name\n";
   write_include_file( *DOT_H_FILE, $xml_file, $register_ref, $register_ref->{name} );
   if( !$opt_t ) {
       print "$xml_file -> $cc_file_name\n";
       write_impl_file   ( *DOT_CC_FILE, $xml_file, $register_ref, $register_ref->{name} );
   }
}

####################################################################
####################################################################
####################################################################

sub calculate_sizes
{
   my ( $reg_ref ) = @_;

   for my $field_name ( keys (%{$reg_ref->{field}} ) ){
       $reg_ref->{field}->{$field_name}->{size} = $reg_ref->{field}->{$field_name}->{end_offset} -
           $reg_ref->{field}->{$field_name}->{start_offset} + 1;
   }
}

####################################################################
####################################################################
####################################################################

sub xlate_path
{
   my ( $file, $path, $suffix ) = @_;
   my $new_file = $file;

   if( $path ne "" ){
       $new_file = $path . "/" . $new_file;
   }

   return $new_file . "." . $suffix;
}

####################################################################
####################################################################
####################################################################

sub get_size
{
   my( $reg_hash ) = @_;
   my $bits;

   for my $field_name ( keys (%{$reg_hash->{field}} ) ){
       $bits += $reg_hash->{field}->{$field_name}->{size};
   }


   return $bits;
}

####################################################################
####################################################################
####################################################################

sub get_native_type
{
   my ( $nr_bits ) = @_;
   my %sz_hash = ( 8  => "uint8_t",
                   16 => "uint16_t",
                   32 => "uint32_t",
                   64 => "uint64_t" );

   for my $k ( sort { $a <=> $b } keys %sz_hash ){
       return ( $sz_hash{$k}, $k ) if $nr_bits <= $k;
   }

   print "ERROR: size $nr_bits cannot be represented in an integral type\n";
   return ("ERROR", "ERROR");
}

####################################################################
####################################################################
####################################################################

sub build_aggregate_include_string
{
   my ( $reg_ref ) = @_;
   my $agg_ref = $reg_ref->{aggregate};
   my $field_ref = $reg_ref->{field};
   my $str;

   for my $agg ( keys (%{$agg_ref} ) ){
       my $size = 0;
       for my $field ( keys (%{$agg_ref->{$agg}->{field}}) ){
           $size += $field_ref->{$field}->{end_offset} - $field_ref->{$field}->{start_offset} + 1; 
       }
       my ( $native_type, $bits ) = get_native_type( $size );
$str .= <<EOTEXT
       $native_type get${agg}();
       void set${agg}( $native_type );
EOTEXT
;
   }
   return $str;
}

####################################################################
####################################################################
####################################################################

sub build_aggregate_impl_string
{
   my ( $reg_ref, $class_name ) = @_;
   my $agg_ref = $reg_ref->{aggregate};
   my $field_ref = $reg_ref->{field};
   my $str;

   for my $agg ( keys (%{$agg_ref} ) ){
       my $size = 0;
       my %field_data;
       for my $field ( keys (%{$agg_ref->{$agg}->{field}}) ){
           my $sz = $field_ref->{$field}->{end_offset} - $field_ref->{$field}->{start_offset} + 1; 
           $size += $sz;
           $field_data{$agg_ref->{$agg}->{field}->{$field}->{'pos'}}->{name} = $field;
           $field_data{$agg_ref->{$agg}->{field}->{$field}->{'pos'}}->{size} = $sz;
       }
       my ( $native_type, $bits ) = get_native_type( $size );
       
       my ( $get_str, $set_str ) = ( "", "" );

       my $offset = 0;

       for my $pos ( sort { $a <=> $b } keys %field_data ){
           my $var_name = uc $field_data{$pos}->{name};
           my $mask = (2 ** $field_data{$pos}->{size}) - 1;
           $mask = sprintf "0x0%lx", $mask;
           $get_str .= "(get$var_name() << $offset) |\n         ";
           $set_str .= "  set$var_name((____d >> $offset) & $mask);\n";
           $offset += $field_data{$pos}->{size};
       }
       $get_str .= "0";

$str .= <<EOTEXT
$native_type ${class_name}::get${agg}()
{
 return $get_str;
}

void ${class_name}::set${agg}( $native_type ____d )
{
$set_str
}
EOTEXT
;

   }
   return $str;
}

####################################################################
####################################################################
####################################################################

sub calc_constructors
{
   my( $reg_ref ) = @_;

   my ( $constructor_mask, $constructor_init, $constructor_bits,
       $constructor_rw1c ) = ( "0\n",  "0\n",  "0\n",  "0\n" );

   my $register_size = 0;
   my @tmpList;
   my $fn;
   my %fields;
   for my $field_name ( keys (%{$reg_ref->{field}} ) ){
       $register_size += $reg_ref->{field}->{$field_name}->{size};
       if( $reg_ref->{field}->{$field_name}->{field_type} eq "NORMAL" ){
           push @tmpList, $field_name;
       }
       $fields{ $reg_ref->{field}->{$field_name}->{start_offset}} =
           $field_name;
   }
   while( ($fn = pop @tmpList) ){
       my $ha_field_mask = "(~uint64_t(0) >> (64 - $reg_ref->{field}->{$fn}->{size}))";
       my $ha_field_shft = "$reg_ref->{field}->{$fn}->{start_offset}";

       if( defined $reg_ref->{field}->{$fn}->{initial_value} ){
           $constructor_init .= "       | (($reg_ref->{field}->{$fn}->{initial_value} & $ha_field_mask) << $ha_field_shft)\n"; 
       }
       if( $reg_ref->{field}->{$fn}->{field_type} eq "NORMAL" ){
         if( $reg_ref->{field}->{$fn}->{protection} eq "RW" ){
           $constructor_mask .= "       | ($ha_field_mask << $ha_field_shft)\n";
         }
         if( $reg_ref->{field}->{$fn}->{protection} eq "RW1C" ){
           $constructor_rw1c .= "       | ($ha_field_mask << $ha_field_shft)\n";
         }
         $constructor_bits .= "       | ($ha_field_mask << $ha_field_shft)\n";
       }
  }

   return ( $constructor_mask, $constructor_init, $constructor_bits,
           $constructor_rw1c );
}

####################################################################
####################################################################
####################################################################

sub write_include_file
{
   my( @save_args ) = @_;
   my( $file_handle, $xml_file, $reg_ref, $reg_name ) = @_;
   my $sz = 0;
   my $reg_name_uc = uc $reg_name;
   my $nr_fields = 0;
   my $class_name = $reg_ref->{class_name};
   my $class_name_ref = "${class_name}&";
   my $class_name_const_ref = "const ${class_name}&";
   my ( $get_string, $set_string );
   my $field_type_struct; 
   my ( $extra_namespace_header, $extra_namespace_footer );

   my $field_type_enum = "enum { ";
   my $field_string_array = "static const FieldObject::FieldInfo fieldData[] = {";
   my %fields;
   my $agg_string;

   my $base_address;
   my $count;
   my $stride;
   my $public;
   my $protected;
   my $private;
   my $pretty_print_includes;

   my ( $constructor_mask, $constructor_init, $constructor_bits,
       $constructor_rw1c ) = &calc_constructors($reg_ref);
   my $constructor_list =
       "$constructor_mask, $constructor_init, $constructor_bits, $constructor_rw1c";
   if (defined $reg_ref->{base_address}) {
       $base_address = "static const uint64_t BaseAddress = $reg_ref->{base_address};";
   }
   if (defined $reg_ref->{count}) {
       $count = "static const uint64_t Count = $reg_ref->{count};";
   }
   if (defined $reg_ref->{stride}) {
       $stride = "static const uint64_t Stride = $reg_ref->{stride};";
   }
   if (defined $reg_ref->{public}) {
       $public = "$reg_ref->{public}";
   }
   if (defined $reg_ref->{protected}) {
       $protected = "$reg_ref->{protected}";
   }
   if (defined $reg_ref->{private}) {
       $private = "$reg_ref->{private}";
   }

   $agg_string = build_aggregate_include_string( $reg_ref ) if defined $reg_ref->{aggregate};

   # Get count of total register size and field count
   for my $field_name ( keys (%{$reg_ref->{field}} ) ){
       # maps field start_offset to field name
       $fields{$reg_ref->{field}->{$field_name}->{start_offset}} = $field_name;
       $sz += $reg_ref->{field}->{$field_name}->{size};
       ++$nr_fields;
   }


   my $field_count = $nr_fields;
   for my $o ( reverse sort { $a <=> $b } keys %fields ){
       $field_count--;
       my $field_name = $fields{$o};
       $field_type_enum .=  uc $field_name;
       $field_type_enum .= ",";

       if($reg_ref->{field}->{$field_name}->{field_type} eq "NORMAL" ){
           my ($data_type, $foo) = get_native_type( $reg_ref->{field}->{$field_name}->{size} );
#           $field_type_struct .= "     $data_type ". lc $field_name . ";\n" if $reg_ref->{field}->{$field_name}->{generate_data};
           $get_string .= create_get_fn_decl( $reg_name, $field_name, $reg_ref->{field}->{$field_name}->{size}, $reg_ref->{field}->{$field_name}->{start_offset} );
           $set_string .= create_set_fn_decl( $reg_name, $field_name, $reg_ref->{field}->{$field_name}->{size}, $reg_ref->{field}->{$field_name}->{start_offset}, $reg_ref->{field}->{$field_name}->{protection});
   }
   $set_string .= create_bitsize_decl( $reg_name, $field_name, $reg_ref->{field}->{$field_name}->{size}, $reg_ref->{field}->{$field_name}->{start_offset}, $reg_ref->{field}->{$field_name}->{protection});    }

   $field_type_enum =~ s/,\s*$//; # chop off the comma from the last entry
   $field_type_enum .= " }";
  
   my $include_guard = "RIESLING_" . uc $class_name . "_H";
   my $comment_str = get_comment_string( $0, $xml_file );

   foreach my $ns ( split /,/, $opt_n ){
       $extra_namespace_header .= "namespace $ns {\n"; 
       $extra_namespace_footer .= "} /* namespace $ns */\n";
   }

   ##
   ## Frontend registration handling
   ##
   my $extra_ancestors;
   my $reg_declarations;
   my $to_string_fn = "std::string toString() const;";
   my $set_native_fn =   "void setNative( uint64_t value )    { FieldObject::setNative(value); }";
   $set_native_fn =   "void setNative( uint64_t value )    { BL_ThinFieldObj<$constructor_list>::setNative(value); }" if $opt_t;
   my $set_nativeHW_fn = "void setNativeHW( uint64_t value )  { FieldObject::setNativeHW(value); }";
   $set_nativeHW_fn = "void setNativeHW( uint64_t value )  { BL_ThinFieldObj<$constructor_list>::setNativeHW(value); }" if $opt_t;
   my $get_native_fn =   "uint64_t getNative() const          { return FieldObject::getNative(); }";
   $get_native_fn =   "uint64_t getNative() const          { return BL_ThinFieldObj<$constructor_list>::getNative(); }" if $opt_t;
   my $default_ctor = "$class_name();";

   my $ancestor_include = $opt_t ? '#include "BL_ThinFieldObj.h"' :
       '#include "FieldObject.h"';
   my $ancestor_class   = "FieldObject";
   $ancestor_class   = "BL_ThinFieldObj<$constructor_list>" if $opt_t;
   if( defined  $reg_ref->{inheritance_info}->{other_ancestor} ){
       $ancestor_include = '#include "' . $reg_ref->{inheritance_info}->{include_file} . '"';
       $ancestor_class = $reg_ref->{inheritance_info}->{ancestor_class};
       # TODO This should really find out of RegisteredObject was already inherited by its        # ancestor
       $extra_ancestors = "";
       # base class aready has these so no need to duplicate/confuse people
       $set_native_fn = "";
       $set_nativeHW_fn = "";
       $get_native_fn = "";
   } 

$pretty_print_includes = "#include <iostream>\n#include <string>\n" if $ opt_p;

if ($opt_t) {
print $file_handle <<EOHFILE0
#ifndef $include_guard
#define $include_guard
$comment_str

$pretty_print_includes

#include "BL_ThinFieldObj.h"
$ancestor_include

$extra_namespace_header
EOHFILE0
;
   }
   else {
print $file_handle <<EOHFILE1
#ifndef $include_guard
#define $include_guard
$comment_str

#include "DataTypes.h"
$ancestor_include
#include "StdMacros.h"
#include "Interface/RegisteredObject.h"
#include <iostream>
#include <string>

$extra_namespace_header
EOHFILE1
;
   }

#################################
## Produce html for doxygen
#################################
print $file_handle "/**\n<pre>\n";
print_field_table_doc( $file_handle, $reg_name_uc, \%fields, $reg_ref ); 
print $file_handle "\n</pre>\n*/\n";

print $file_handle <<EOHFILE1
class $class_name : public $ancestor_class $extra_ancestors {
EOHFILE1
;

print $file_handle <<EOHFILE4

   public:

       $base_address
       $count
       $stride
       $public

EOHFILE4
;

if (! $opt_t) {
print $file_handle <<EOHFILE5

       /**
         * An enumeration that represent each accessable field.  Use these types
         * as inputs for accessors and mutators for fields.
         */
       typedef $field_type_enum FieldT; 
EOHFILE5
;
}

print $file_handle <<EOHFILE6

       $default_ctor
       $class_name( $class_name_const_ref obj );
       ~$class_name();
EOHFILE6
if ! $opt_t;

print $file_handle <<EOHFILE60
       $class_name_const_ref operator=( $class_name_const_ref obj ) { return ($class_name_const_ref)$ancestor_class ::operator=(obj); }
       bool operator==( $class_name_const_ref obj ) const      { return $ancestor_class ::operator==(obj); }

       /**
         * Get a copy of the register's native representation
         *
         * \@param data A pointer to a chunk of memory large enough
         * to hold the register's native representaion 
         * \@see getSize()
         */
       $get_native_fn

       $set_native_fn

       $set_nativeHW_fn
EOHFILE60
;

if (! $opt_t) {
print $file_handle <<EOHFILE7
       /**
         * Return the register's size in bits
         *
         * \@return The register size in bits
         * \@see ${class_name}::FieldT
         */
       uint32_t getSize() const; 
       
       /**
         * Return the field's size in bits
         *
         * \@param field The number of this field
         * \@return The field's size in bits
         * \@see ${class_name}::FieldT
         */
       virtual uint32_t getSize( uint_t field ) const;  

       /**
         * Return the field's offset in the register
         *
         * \@param field The number of this field
         * \@return The field's offset
         * \@see ${class_name}::FieldT
         */
       virtual uint32_t getOffset( uint_t field ) const; 

       /**
         * Return the field's protection.  That is, can the field be 
         * read, written, or both.
         *
         * \@param field The number of this field
         * \@return The field's protection
         * \@see FieldObject::ProtectionT
         * \@see ${class_name}::FieldT
         */
       FieldObject::Protection getProtection(  uint_t field ) const; 

       /**
         * Return a string representation of the field name
         *
         * \@param field The number of this field
         * \@return The name of the field
         * \@see ${class_name}::FieldT
         */
       virtual const char* getName() const;  

       /**
         * Return a string representation of the field name
         *
         * \@param field The number of this field
         * \@return The name of the field
         * \@see ${class_name}::FieldT
         */
       virtual const char* getName( uint_t field ) const; 

EOHFILE7
;
}

print $file_handle <<EOHFILE80
       $reg_declarations

$get_string
$set_string 
$agg_string

EOHFILE80
;

if ( $opt_t ) {
   my( $file_handle, $xml_file, $reg_ref, $reg_name ) = @save_args;
   write_impl_file( $file_handle, $xml_file, $reg_ref, $reg_name );
}
else {
   print $file_handle <<EOHFILE8

       /**
         * Return the string representaton of this register.
         * 
         */
       $to_string_fn

       /**
         * Print this Register to an output stream
         * 
         * \@param os The output stream to which the register should be
         * printed.  Omitting this parameter will print the std::cout 
         */
       virtual void print( std::ostream& os = std::cout ) const; 
EOHFILE8
;
}

print $file_handle <<EOHFILE85

   protected:

       $protected
EOHFILE85
;

if (! $opt_t) {
print $file_handle <<EOHFILE9
       //! How many fields the register has.
       static const int NR_FIELDS = $nr_fields; 
       static const FieldObject::FieldInfo fieldData[];
EOHFILE9
;
}

print $file_handle <<EOHFILE10
   private:
       
};

$extra_namespace_footer


#endif /* $include_guard */

EOHFILE10
;

print $file_handle "\n";
}

####################################################################
####################################################################
####################################################################

sub write_impl_file
{
   my( $file_handle, $xml_file, $reg_ref, $reg_name ) = @_;
   my $ifile_name =  $reg_ref->{class_name} . ".h";
   if( defined  $reg_ref->{submodule} ){
       $ifile_name =  $reg_ref->{submodule} . "/" . $ifile_name;
   }
   my $class_name = $reg_ref->{class_name};
   my $class_name_ref = "${class_name}&";
   my $class_name_const_ref = "const ${class_name}&";
   my $class_scope = $class_name . '::';

   my $equal_string;  
   my ( $get_string, $set_string );
   my $printing_string;  
   my $str_string;  
   my @tmpList;
   my $fn;
   my ( $copy_constructor_string, $constructor_string );
   my ( $constructor_mask, $constructor_init, $constructor_bits,
       $constructor_rw1c ) = &calc_constructors($reg_ref);
   my ( $get_native_string, $set_native_string, $set_nativeHW_string );
   my $register_size = 0;
   my %fields;
   my $agg_string;
   $agg_string = build_aggregate_impl_string( $reg_ref, $class_name ) if defined $reg_ref->{aggregate};

   my $field_string_array = "const FieldObject::FieldInfo ${class_scope}fieldData[] = {";

   for my $field_name ( keys (%{$reg_ref->{field}} ) ){
       $register_size += $reg_ref->{field}->{$field_name}->{size};
       if( $reg_ref->{field}->{$field_name}->{field_type} eq "NORMAL" ){
           push @tmpList, $field_name;
       }
       $fields{ $reg_ref->{field}->{$field_name}->{start_offset}} = $field_name;
   }
   for my $o ( reverse sort { $a <=> $b } keys %fields ){
       my $field_name = $fields{$o};
       if ( $reg_ref->{field}->{$field_name}->{protection} eq "RWH") {
         $field_string_array .= "\n            { FieldObject::RO, ";
       }

       else {
         $field_string_array .= "\n            { FieldObject::$reg_ref->{field}->{$field_name}->{protection}, ";
       }
       $field_string_array .= " $reg_ref->{field}->{$field_name}->{start_offset},";
       $field_string_array .= " $reg_ref->{field}->{$field_name}->{size},";
       $field_string_array .= " FieldObject::$reg_ref->{field}->{$field_name}->{field_type},";
       $field_string_array .= " \"$field_name\" }";
       $field_string_array .= ",";

       if( $reg_ref->{field}->{$field_name}->{field_type} eq "NORMAL" ){
           # build impl for getNative method
           $get_native_string .= " |\n" if $get_native_string ne "";
           $get_native_string .= "     ( (0ULL |" . lc $field_name . ") << " . 
               $reg_ref->{field}->{$field_name}->{start_offset} . ")";

           # build impl for setNative method
           if( $reg_ref->{field}->{$field_name}->{protection} eq "RW" ){
               my $mask = "(~0ULL >> (64 - $reg_ref->{field}->{$field_name}->{size}))";
               $set_native_string .= " " . lc $field_name . 
                   " = (____d >> $reg_ref->{field}->{$field_name}->{start_offset}) & $mask;\n";
           }
           elsif($reg_ref->{field}->{$field_name}->{protection} eq "RW1C"){
               my $mask = "(~0ULL >> (64 - $reg_ref->{field}->{$field_name}->{size}))";
               $set_native_string .= " " . lc $field_name . 
                   " &= ~((____d >> $reg_ref->{field}->{$field_name}->{start_offset}) & $mask);\n";
           }


           # build impl for setNativeHW method
           if( $reg_ref->{field}->{$field_name}->{protection} ne "RO" ){
               my $mask = "(~0ULL >> (64 - $reg_ref->{field}->{$field_name}->{size}))";
               $set_nativeHW_string .= "       " . lc $field_name . 
                 " = (____d >> $reg_ref->{field}->{$field_name}->{start_offset}) & $mask;\n";
           }
       }

   }

   $field_string_array =~ s/,\s*$//; # chop off the comma from the last entry
   $field_string_array .= " }";
  
   my ( $get_case_body, $set_case_body );
   while( ($fn = pop @tmpList) ){
       my $lc_fn = lc $fn;
       my $uc_fn = uc $fn;
       $equal_string .= "    $lc_fn == rhs.$lc_fn";
       $equal_string .= " &&\n" if @tmpList;

       $printing_string .= "    \"" . uc( $fn ) . "=\" << get$uc_fn() << \" \"";
       $printing_string .= " <<\n" if @tmpList;
       
       $get_case_body .= 
<<EO_GET_CASE
       case $uc_fn:
           return get$uc_fn();
           break;
EO_GET_CASE
;
       $set_case_body .= 
<<EO_SET_CASE
       case $uc_fn:
           set$uc_fn( value );
           break;
EO_SET_CASE
;

   }

   my $comment_str = get_comment_string( $0, $xml_file );

   # construct using declarations for each additional namespace
   my $using_ns;
   my $extra_ns_accum = "Riesling";
   foreach my $ns ( split /,/, $opt_n ){
       $extra_ns_accum .= "::$ns";
       $using_ns .= "using namespace $extra_ns_accum;\n";
   }


print $file_handle <<EO_CCFILE
$comment_str
#include "$ifile_name"
#include <sstream>

using namespace std;
using namespace Riesling;
$using_ns
EO_CCFILE
if ! $opt_t;

if (! $opt_t) {
print $file_handle <<EO_CCFILE1

const int ${class_scope}NR_FIELDS;
$field_string_array;
EO_CCFILE1
;
}

if ($opt_t) {
print $file_handle <<EO_CCFILE6

$class_name()
{
 data = get_init();
}

~$class_name()
{}

$class_name( const $class_name& obj )
{
 data = obj.data;
}
EO_CCFILE6
}
else {
print $file_handle <<EO_CCFILE6

${class_scope}$class_name()
{
 mask = $constructor_mask       ;
 init = $constructor_init       ;
 bits = $constructor_bits       ;
 rw1c = $constructor_rw1c       ;
 data = init;
}

${class_scope}~$class_name()
{}

${class_scope}$class_name( const $class_name& obj )
{
 data = obj.data;
 mask = obj.mask;
 rw1c = obj.rw1c;
 init = obj.init;
 bits = obj.bits;
}
EO_CCFILE6
;
}

if (! $opt_t) {

print $file_handle <<EO_CCFILE7

$get_string

$set_string

uint32_t ${class_scope}getSize() const
{
 return $register_size;
}

uint32_t ${class_scope}getSize( uint_t field ) const
{
   if( field >= NR_FIELDS ){
       RIESLING_THROW_INVALID_ARGUMENT( "Invalid field specifier." );
   }
   return ${class_scope}fieldData[ field ].size;
}

uint32_t ${class_scope}getOffset( uint_t field ) const
{
   if( field >= NR_FIELDS ){
       RIESLING_THROW_INVALID_ARGUMENT( "Invalid field specifier." );
   }
   return ${class_scope}fieldData[ field ].offset;
}

FieldObject::Protection ${class_scope}getProtection( uint_t field ) const
{
   if( field >= NR_FIELDS ){
       RIESLING_THROW_INVALID_ARGUMENT( "Invalid field specifier." );
   }
   return ${class_scope}fieldData[ field ].prot;
}

const char* ${class_scope}getName() const
{
   return "$reg_ref->{name}"; 
}

const char* ${class_scope}getName( uint_t field ) const
{
   if( field >= NR_FIELDS ){
       RIESLING_THROW_INVALID_ARGUMENT( "Invalid field specifier." );
   }
   return ${class_scope}fieldData[ field ].name;
}

EO_CCFILE7
;
}

print $file_handle <<EO_CCFILE8

std::string ${class_scope}toString() const
{
   std::ostringstream os;
   os << std::hex << $printing_string;
   return os.str();
}

void ${class_scope}print( std::ostream& os ) const
{
   os << toString();
}
EO_CCFILE8
if $opt_p;


print $file_handle "$agg_string\n;";
}

####################################################################
####################################################################
####################################################################

sub create_set_fn_decl
{
   my ( $class_name, $field_name, $field_size, $field_start, $prot) = @_;
   my ( $sz_type, $sz ) = get_native_type( $field_size );
   my $field_name_uc = uc $field_name;
   my $field_name_lc = lc $field_name;
   
   my $rvalue = "(value << $field_start)";
   my $mask = "uint64_t field_mask = (~uint64_t(0) >> (64 - $field_size)) << $field_start;";
   $rvalue = "(data & ~field_mask) | ((value << $field_start) & field_mask)";
  
   ## This is a little painful. Long time ago Riesling decided to make itself public, very public
   ## and that means that all registers are visible and accessable, including the set field methods. 
   ## This is a grieving mistake. It should have been hidden, awell, now we have a problem ... 
   ## If someone sets a field of a register and internally there is some side effect associated with that 
   ## then we need to call a function or method that handles the side effect ... thank god for pointers 
   ##  to functions or methods ha style. All because the rshell allows for statements like 
   ## $hpstate.HPRIV=1 ... and that needs a call ... and I don't know what the jshell does.

   my $decl_string = "void set$field_name_uc( uint64_t value )  { $mask data=$rvalue; }\n";
   $decl_string .= "void set${field_name_uc}_Notify( uint64_t value )  { $mask call->call(this,$rvalue); }" if ! $opt_t;

   if( $opt_o ){
     $decl_string = "virtual $decl_string";
   }

<<EODECL    
       //! set the value of $class_name.$field_name_uc
       $decl_string
EODECL
;
}

####################################################################
####################################################################
####################################################################

sub create_get_fn_decl
{
   my ( $class_name, $field_name, $field_size, $field_start ) = @_;
   my ( $sz_type, $sz ) = get_native_type( $field_size );
   my $field_name_uc = uc $field_name;
   my $field_name_lc = lc $field_name;
     
   my $decl_string = "uint64_t get$field_name_uc( ) const   { return (data >> $field_start) & (~uint64_t(0) >> (64 - $field_size));}";
   
   if( $opt_o ){
     $decl_string = "virtual $decl_string";
   }

<<EODECL    
       //! return the value of $class_name.$field_name_uc
       $decl_string
EODECL
;
}

####################################################################
####################################################################
####################################################################

sub create_bitsize_decl
{
   my ( $class_name, $field_name, $field_size, $field_start ) = @_;
   my ( $sz_type, $sz ) = get_native_type( $field_size );
   my $field_name_uc = uc $field_name;
   my $field_name_lc = lc $field_name;
     
   my $decl_string = "static const bitSize$field_name_uc = $field_size;";

<<EODECL    
       //! return the value of $class_name.$field_name_uc
       $decl_string
EODECL
;
}

####################################################################
####################################################################
####################################################################

sub get_comment_string
{
   my ( $generator, $source_file ) = @_;
   my $today = `date`;
   chomp $today;
   my $id_str = `id`;
   $id_str =~ /uid=(\d+)/;
   my( $user_login_name,$passwd,$uid,$gid,$quota,$comment,$user_full_name, @foo ) = getpwuid( $1 );
   my $short_gen = $generator;
   $short_gen =~ s#.*/##;
   my $pwd = `pwd`;
   chomp $pwd;
   $source_file = resolve_path( $pwd, $source_file );
   
<<EOCOMMENT
/************************************************************************
**
**   
**      ****** MACHINE-GENERATED FILE ******
**      ******  DO NOT EDIT BY HAND   ******
**
**  Generated from $source_file 
**  using $generator
**  File created on $today by $user_full_name ($user_login_name)
**
**  Command Line Used to Generate File:
**  $short_gen @ORIG_ARGS
**  
**  Copyright (C) 2002, Sun Microsystems, Inc.
**
**  Sun considers its source code as an unpublished, proprietary
**  trade secret and it is available only under strict license provisions.
**  This copyright notice is placed here only to protect Sun in the event 
**  the source is deemed a published work. Disassembly, decompilation,
**  or other means of reducing the object code to human readable form
**  is prohibited by the license agreement under which this code is
**  provided to the user or company in possession of this copy.
*************************************************************************/
EOCOMMENT
;
}

####################################################################
####################################################################
####################################################################

sub resolve_path
{
   my ( $pwd, $path ) = @_;
   my $result; 
   while( $path =~ s#\.\./## ){
       $pwd =~ s#/[^/]+$##;
   }

   if( $path !~ m#^/# && $pwd !~ m#/$# ){
       $pwd .= '/';
   }

   return $pwd . $path;
}


####################################################################
####################################################################
####################################################################

sub get_register_documentation_string
{
   #my() = @_;


<<EOCOMMENT
EOCOMMENT
;
}

####################################################################
####################################################################
####################################################################


sub print_field_table_doc 
{
   my ( $file_handle, $reg_name, $field_ref, $reg_ref ) = @_; 
   #################################
   ## Produce the table of register fields.
   #################################
   my @comments;
   my $orig_name = $~;
print $file_handle <<EOHEAD
$reg_name Field Specification

Offset  Size  Name   Description
------------------------------------------------------------------------------------------------
EOHEAD
;
   for my $o ( sort { $a <=> $b } keys %{$field_ref} ){
       my ($FMT_offset,$FMT_size,$FMT_name, $FMT_description);
       my $field_name = $field_ref->{$o};

format COMMENT_INIT =
@>>     @>>   @<<<<<<<< ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<< 
$FMT_offset,$FMT_size,$FMT_name, $FMT_description
                       ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~ 
$FMT_description
.

       ( $FMT_description, @comments ) = split /\\n/, $reg_ref->{field}->{$field_name}->{comment};
       $FMT_offset = $reg_ref->{field}->{$field_name}->{start_offset};
       $FMT_size = $reg_ref->{field}->{$field_name}->{size};
       $FMT_name = $field_name;
       $file_handle->format_name( "COMMENT_INIT" );

       write $file_handle;

       while( @comments ){
           my $FMT_cont = shift @comments;
format COMMENT_CONT =
                       ^<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<~~ 
$FMT_cont
.
           $file_handle->format_name( "COMMENT_CONT" );
           write $file_handle;
       }
           
   }
   $~ = $orig_name;
}

####################################################################
####################################################################
####################################################################

sub fix_hash
{
   my ( $reg_ref ) = @_;

   delete( $reg_ref->{field}->{field_type});
   delete(  $reg_ref->{field}->{name} );   
   delete(  $reg_ref->{field}->{format} );   
   delete(  $reg_ref->{field}->{comment} );   
   delete(  $reg_ref->{field}->{start_offset} );   
   delete(  $reg_ref->{field}->{end_offset} );   
   delete(  $reg_ref->{field}->{protection} );   
   delete(  $reg_ref->{field}->{size} );   
   delete(  $reg_ref->{field}->{initial_value} );   
}

####################################################################
####################################################################
####################################################################

sub validate
{
   my( $reg_ref ) = @_;
   my (%names, @bits);
   my $size = 0;
   my $max_offset = 0;
   for my $field_name ( keys (%{$reg_ref->{field}} ) ){
       $size += $reg_ref->{field}->{$field_name}->{size};
       $max_offset = $reg_ref->{field}->{$field_name}->{end_offset} 
           if $max_offset <  $reg_ref->{field}->{$field_name}->{end_offset};
   }

   if( $size != $max_offset + 1 ){
       print STDERR "VALIDATION ERROR: Max end_offset is $max_offset but is size is $size\n.";
       return 0;
   }

   for( my $i = 0; $i < $size; $i++ ){
       $bits[$i] = 0; 
   }

   for my $field_name ( keys (%{$reg_ref->{field}} ) ){
       # Duplicated name check
       if( defined $names{ $field_name } ){
           print STDERR "VALIDATION ERROR: duplicate field: $field_name\n";
           return 0;
       } else {
           $names{$field_name} = 1;
       }

       if( $field_name =~ /^\W/ ){
           print STDERR "VALIDATION ERROR: $field_name must start with a letter or and underscore.\n";
           return 0;
       }

       if( $field_name =~ /([^\w\d])/ ){
           print STDERR "VALIDATION ERROR: $field_name cannot contain the character $1.\n";
           return 0;
       }

       # Check for offsets that are negative or too large.
       my $offset = $reg_ref->{field}->{$field_name}->{start_offset};
       if( $offset < 0 ){
           print STDERR "VALIDATION ERROR:  $field_name.offset is negative\n";
           return 0;
       }
       if( $offset >= $size ){
           print STDERR "VALIDATION ERROR: $field_name.offset = $offset is greater than size = $size\n";
           return 0;
       }

       my $field_size = $reg_ref->{field}->{$field_name}->{size};
       # Check for correct size
       if( $field_size < 1 ){
           print STDERR "VALIDATION ERROR: $field_name.size is less than one.\n";
           return 0;
       } 
       if( $offset + $field_size - 1 >= $size ){
           print STDERR "VALIDATION ERROR: $field_name.offset ($offset) + $field_name.size ($field_size) is \
               greater than size ($size)\n";
           return 0;
       }

       # Check for overlapping bits
       for( my $i = $offset; $i < ($offset + $field_size); $i++ ){
           if( $bits[$i] != 0 ){
               print STDERR "VALIDATION ERROR: $field_name overlaps with $bits[$i] at bit $i\n";
               return 0;
           } else {
               $bits[$i] = $field_name;
           }
       }
       
       # Initial value check.
       my $initial_value = $reg_ref->{field}->{$field_name}->{initial_value};
       my $max_size = ( 2 ** $size ) - 1;
       if( $initial_value > $max_size ){
           print STDERR "WARNING: $field_name.intial_value is greater than maximum representable value for\n";
           print STDERR "         $field_name. This value will be truncated.\n";
           $reg_ref->{field}->{$field_name}->{initial_value} &= $max_size;
       }

       my $prot = $reg_ref->{field}->{$field_name}->{protection};
       if( $prot ne "RO" && $prot ne "RW" && $prot ne "WO" && $prot ne "RWH" && $prot ne "RW1C"){
           # RWH is used to indicate a field that is read-only by software,
           # but is writable by hardware, we need this to create setNativeHW,
           # to be used by (N2) testbench to force a value into an otherwise
           # read-only field.
           print STDERR "VALIDATION ERROR: $field_name.protection is not RO, RW, or WO [$prot]\n";
           return 0;
       }
       if ($prot eq "RWH"){
         print STDERR "IMPLEMENTATION CHANGE: RWH behaviour is available through setNativeHW which treats RO fields as RW\n";
       }

       my $type = $reg_ref->{field}->{$field_name}->{field_type};
       if( $type ne "NORMAL" && $type ne "DONT_CARE" && $type ne "ZERO" ){
           print STDERR "VALIDATION ERROR: $field_name.field_type is not NORMAL, DONT_CARE, or ZERO.\n";
           return 0;
       }

       my $comment = $reg_ref->{field}->{$field_name}->{comment};
       if( $type ne "NORMAL" && $comment != /\w/ ){
           print STDERR "VALIDATION WARNING: $field_name.comment appears to be blank\n";
       }

   }

   my @uncounted_bits;
   for( my $i = 0; $i < $size; $i++ ){
       if( $bits[$i] eq "0" ){
           push @uncounted_bits, $i;
       }
   }

   if( @uncounted_bits > 0 ){
       print STDERR "VALIDATION ERROR: Bits @uncounted_bits are not part of any field.\n";
       return 0;
   }

   return 1;
}





__END__

####################################################################
####################################################################
####################################################################


# POD documentation

=head1 NAME

xml2reg - Build a C++ implementation of a register from an XML specification.

=head1 SYNOPSYS

xml2reg [-hdrv] [ -n namespaces] [ -I path] [ -S path ] xml file ...

=head1 DESCRIPTION

xml2reg takes an XML file containing a specification for a register as input and generates the 
corresponding C++ implemenation of that specification.  All xml2reg-generated registers
implement the FieldObject interface.  xml2reg documents the C++ files with appropriate 
doxygen-compatible comments.

=head1 OPTIONS

=item B<-h> 

Print a usage summary.

=item B<-d> 

Dump out the internal represenation (parse tree) of the XML file.  This option is useful
for developers who wish to modify xml2reg.

=item B<-v> 

Validate the XML file and then exit without generating any C++ output.  This option is used
to ensure the correctness of the your XML register file specification.  xml2reg performs a
number of sanity checks on your XML file.  When an error in your XML file is discovered, 
xml2reg will report the error to stderr an then exit with a nonzero status.  Some problems with your
XML will generate warnings.  A warning will be reported to stderr, but will not cause xml2reg to
exit.  xml2reg will exit with zero status if your file has no errors but does generate warnings.

=item B<-n> I<namespace list>

Enclose the C++ implemenation in additional namespaces.  By default, the C++ code generated by
xml2reg is placed in the Riesling namespace.  This option is used to specify additional enclosing 
namespaces.  The namespaces are specified as a comma-separated list of namespaces with no intervening
whitespace.  The the namespaces should be specified from in outermost to innermost order.  

=item B<-r> 

Generate code to make this register accessble from the object registry.  Classes generated with this 
can be instantiated and their instances manipulated Riesling's frontend.


=item B<-I> I<path>

Specify the directory to which the generated header file (.h file) should be written.  

=item B<-S> I<path>

Specify the directory to which the generated implemenation file (.cc file) should be written.

=head1 EXAMPLES

    xml2reg myreg.xml

Generate C++ code for a single xml file.  The resulting C++ files will be names myreg.h and myreg.cc.
The files will be written to the current working directory.

    xml2reg *.xml

Process all the XML files in the current directory.  A .h and .cc file will be generated for each
XML file processed.

   xml2reg -n Mmu -I /src/Riesling/include/mmu -S /src/Riesling/src/mmu MmuConfigReg.xml

Generates C++ code for the XML file MmuConfigReg.xml.  The the class is enclosed in the Mmu namespace.
The .h file is written to /src/Riesling/include/mmu/MmuConfigReg.h.  The .cc file is written to
/src/Riesling/include/mmu/MmuConfigReg.cc.


=head1 SEE ALSO

XML::Simple, FileHandle, process_xml(1)

=head1 BUGS

Errors parsing the XML file will be reported by XML::Simple, and these errors can be cryptic.


=head1 NOTES

See the document I<Riesling Register Specification> for a complete discussion 
of the XML specification.