vreg

NAME

vreg - Register configuration utility

SYNOPSIS

  vreg --help
  vreg ...

DESCRIPTION

Vreg has two major uses. The first vreg converts a HTML document (saved via Word, Framemaker, LyX, or Latex) to a vreg file. The second generates standard headers from the .html or from a .vregs file.

HTML CONVERSION

When the --html switch is used, vreg generates a .vregs file from a .html file. The file format is described in vregs_spec.doc or vregs_spec.htm.

When saving HTML, be sure to change both the filename to .htm and the file format to HTML. If inside Microsoft Word, exit.

HEADER CREATION

When the --header switch is used, vreg reads a .vregs file and creates definition and class headers in the --output directory. Vreg can also create LaTex tables based on the register layouts.

GENERAL ARGUMENTS

--change-diff program: With --change-error, use this program to determine if the error should be reported or not. The program should exit with non-zero status to raise an error.
--change-error language: Report error if file of the given language would change. Use ALL for all languages. This option may be given multiple times to specify multiple languages.
--dry-run: Don't write any output files, mearly report which files would change.
--help: Displays this message and program version and exits.
--headers: Creates the header files and other files after the hardware.vregs file has changed.
--html html_filename: Reads the specified filename and creates a .vregs file from the html.
--if-product product: Only include registers in output with a Product column matching that specified. See the vregs_spec document for more information.
--library package: Specifies a package to be used to resolve subclasses. The library package will only be read, not changed in any way.
--nocomments: Add minimal comment to the header files, to save disk space and time. Users of the file will have to then look at the .vregs file to determine what bits represent.
--output: Specifies the directory name to be used for all output files.
--package: Specifies the name of the package; used for creating all filenames.
--rebuild-comment: Specifies a comment to be placed into output files describing to users how to rebuild the file.
--rm: When used with the --html switch, remove a directory named html_name_files. (This generally contains images written by Microsoft Word that are not needed.) Also, clean up the HTML file to compress out useless style tags that make the file less humanly readable.
--rules: Specify the name of the rules file. (See SystemC::Vregs::Rules.) Defaults to the out_directory/package__rules.pl.
--v2k: Use Verilog-2001 constructs, such as localparam. Identical to the v2k package attribute.
--version: Displays program version and exits.
--vregs: Specify vregs format file to be read or written. Defaults to be in the directory specified by --output with the filename package.vregs.

OUTPUT FILE TYPE ARGUMENTS

--asm_h

Create an _asm.h file.

--class_cpp

Create a _class.cpp file.

--class_h

Create a _class.h C++ file.

--defs_h

Create a _defs.h file.

--defs_pm

Create a _defs.pl file.

--defs_v

Create a _defs.v file.

--filename-asm-h filename

Specify the output filename for the asm_h file. By default this is {--output}{package_name}_asm.h.

Similar options exist for all of the other output files.

--files

Create all files. Equivalent to: --class_h --class_cpp --defs_h --defs_pm --defs_v --info_cpp --hash_pm --params_v --struct_h

--hash_pm

Create a _hash.pm file.

--info_cpp

Create an _info.cpp file.

--latex

Creates latex tables from the vregs definition, suitable for formatting into printable documentation.

--nofiles

Suppresses creating all files. Equivalent to: --noclass_h --noclass_cpp --nodefs_h --nodefs_pm --nodefs_v --noinfo_cpp --nohash_pm --noparams_v --nostruct_h

You can then use specific enables after the --nofiles to turn on the desired files, for example: --nofiles --class_h --defs_h --hash_pm

--params_v

Create a _defs.pm file.

--struct_h

Create a _struct.h C file.

DISTRIBUTION

Vregs is part of the http://www.veripool.org/ free Verilog software tool suite. The latest version is available from CPAN and from http://www.veripool.org/vregs.

Copyright 2001-2010 by Wilson Snyder. This package is free software; you can redistribute it and/or modify it under the terms of either the GNU Lesser General Public License Version 3 or the Perl Artistic License Version 2.0.

AUTHORS

Wilson Snyder <wsnyder@wsnyder.org>

vreg_latex2html

NAME

vreg_latex2html - Register configuration utility

SYNOPSIS

  vreg_latex2html --help
  vreg_latex2html {filename}.tex

DESCRIPTION

Vreg_latex2html is a simple script to read LaTex documents that use the vregs Latex definitions and write out HTML code that can then be parsed by the Vreg program.

An alternative path is to use the regular latex2html program to convert the entire document to HTML format, then run vregs on that. Using this package is much more restricted in how you write the definitions, but doesn't cause latex2html errors with unknown packages and such as they are simply ignored.

ARGUMENTS

--output: Specifies the output filename.
-I: Specifies path to include files.
--version: Displays program version and exits.

ENVIRONMENT

TEXINPUTS: If set, colon separated directory names are used as -I include paths.

SystemC::Vregs

NAME

SystemC::Vregs - Utility routines used by vregs

SYNOPSIS

  use SystemC::Vregs;

DESCRIPTION

A Vregs object contains a documentation "package" containing enumerations, definitions, classes, and registers.

METHODS

See also SystemC::Vregs::Output::* for details on functions that write out various header files.

new: Creates a new Vregs package object and returns a reference to it. The name of the package should be passed as a "name" named parameter, likewise the number of address bits should be passed as address_bits.
check: Checks the object for errors, and parses the object to create some derived fields.
defines_sorted: Returns list of SystemC::Vregs::Define objects.
enums_sorted: Returns list of SystemC::Vregs::Enum objects.
exit_if_error: Exits if any errors were detected by check().
find_define: Returns SystemC::Vregs::Define object with a name matching the passed parameter, or undef if not found.
find_enum: Returns SystemC::Vregs::Enum object with a name matching the passed parameter, or undef if not found.
find_type: Returns SystemC::Vregs::Type object with a name matching the passed parameter, or undef if not found.
find_type_regexp: Returns list of SystemC::Vregs::Type objects with a name matching the passed wildcard, or undef if not found.
html_read: Reads the specified HTML filename, and creates internal objects.
regs_read: Reads the specified .vregs filename, and creates internal objects.
regs_read_check: Calls the normal sequence of commands to read a known-good vregs file; regs_read, check, and exit_if_error.
regs_sorted: Returns list of SystemC::Vregs::Register objects.
regs_write: Creates the specified .vregs filename.
types_sorted: Returns list of SystemC::Vregs::Type objects.

SystemC::Vregs::Bit

NAME

SystemC::Vregs::Bit - Bit object

SYNOPSIS

    use SystemC::Vregs;

DESCRIPTION

This package contains a blessed hash object for each bit field in a SystemC::Vregs::Type.

FIELDS

These fields may be specified with the new() function, and accessed via the self hash: $self->{field}.

access: RW/R/W/H/S access for the field, from the access column of the field definition.
bits: The bits the field occupies, from the bit column in the field definition.
desc: Description comment for the object.
name: Name of the object.
overlaps: A string indicating what bitfields may be overlapped by this field. From parsing the description column of the field for "overlaps allowed" strings.
pack: Reference to the package (SystemC::Vregs) object self is a member of.
rst: Reset value from the reset column of the field definition.
type: Type of the field, from the type column of the field definition.

DERIVED FIELDS

These fields are valid only after check() is called.

bitarray: A array, with one entry for each bit number (0..31). Each entry contains a hash with the bit field reference and status on that bit.

METHODS

new: Creates a new bit object.
check: Checks the object for errors, and parses to create derived Fields.

SystemC::Vregs::Define

NAME

SystemC::Vregs::Define - Definition object

SYNOPSIS

    use SystemC::Vregs;

DESCRIPTION

This package contains a blessed hash object for each definition.

FIELDS

These fields may be specified with the new() function, and accessed via the self hash: $self->{field}.

bits: Number of bits in the define. If not specified, it is assumed to be a unsized object that is less than 32 bits.
desc: Description comment for the object.
name: Name of the object.
pack: Reference to the package (SystemC::Vregs) object self is a member of.
rst: Reset value for the object.

DERIVED FIELDS

These fields are valid only after check() is called.

rst: The reset value, expressed as a text string.
rst_val: The reset value, expressed as a hex string.

METHODS

new: Creates a new definition object.
new_push: Creates a new definition object, at the head of the list of definitions.
check: Checks the object for errors, and parses to create derived Fields.

SystemC::Vregs::Enum

NAME

SystemC::Vregs::Enum - Definition object

SYNOPSIS

    use SystemC::Vregs;

DESCRIPTION

This package contains a blessed hash object for each enumeration.

FIELDS

These fields may be specified with the new() function, and accessed via the self hash: $self->{field}.

bits: Number of bits wide the enumeration values are.
desc: Description comment for the object.
name: Name of the object.
pack: Reference to the package (SystemC::Vregs) object self is a member of.
fields: Hash containing SystemC::Vregs::Enum::Value objects. Each value object contains a name, desc, and rst field, just like the SystemC::Vregs::Define objects.

METHODS

new: Creates a new enumeration object.
check: Checks the object for errors, and parses to create derived Fields.

SystemC::Vregs::File

NAME

SystemC::Vregs::File - Output Vregs Code

SYNOPSIS

    use SystemC::Vregs::File;

DESCRIPTION

This package contains an extension of the SystemC::Vregs::Language class, used for writing files.

METHODS

open

Create a new file handle object. Named parameters include:

  filename - passed  to SystemC::Vregs::Language.

  verbose - print comment on opening of file on the screen.

  noheader - suppress Automatically Generated comments.

  And all parameters supported by SystemC::Vregs::Language.

close

Print the closing comment and close the file.

private_not_public

Unless previously printed, if true, print "private:" else print "public".

fn

Print a function declaration in C or C++ format.

call_str

Return a function call string in C or C++ format.

print_tabify

Print the line with spaces that land on tab stops as tabs.

SystemC::Vregs::Language

NAME

SystemC::Vregs::Language - File processing for various Languages

SYNOPSIS

    use SystemC::Vregs::Language;

    my $fh = SystemC::Vregs::Language->new (filename=>"foo.c",
                                            language=>'C',);
    $fh->comment ("This file is generated automatically\n");
    $fh->define ("TRUE",1, "Set true");
    $fh->print ("void main();\n");

DESCRIPTION

This package creates a file handle with language specific semantics. This allows similar operators to be called, such as comment, for many different file formats.

The output data is stored in an array and dumped when the file is complete. This allows the file to only be written if the data changes, to reduce makefile rebuilding.

FIELDS

These fields may be specified with the new() function.

filename: The filename to write the data to.
keep_timestamp: If true, the file will only be written if the data being written differs from the present file contents.
language: The language for the file. May be C, Perl, Assembler, TCL, or Verilog. A new language Foo may be defined by making a SystemC::Vregs::Language::Foo class which is an @ISA of SystemC::Vregs::Language.

ACCESSORS

language: Returns the type of file, for example 'C'.

OUTPUT FUNCTIONS

comment: Output a string with the appropriate comment delimiters.
comment_pre: Output a comment and Doxygen document before-the-fact.
comment_post: Output a comment and Doxygen document after-the-fact.
include_guard: Output a standard #ifndef around the file to prevent multiple inclusion. Closing the file will automatically add the #endif
sprint_hex_value: Return a string representing the value as a hex number. Second argument is number of bits.
preproc: Output a preprocessor directive.
print: Output plain text. This function is called by all other functions. You will probably want to make a inherited class and override this method.
printf: Output printf text.

SystemC::Vregs::Number

NAME

SystemC::Vregs::Number - Number parsing used by Vregs

SYNOPSIS

  use SystemC::Vregs::Number;

DESCRIPTION

This package is used to extract numbers in C++ or Verilog format into a Bit::Vector.

SystemC::Vregs::Output::CBitFields

NAME

SystemC::Vregs::Output::CBitFields - Outputting Vregs Code

SYNOPSIS

SystemC::Vregs::Output::CBitFields->new->write(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package dumps C structures with bit fields. It is called by the Vregs package.

Note that the order of packing bits into integers is compiler-specific and thus unportable. You are better off using the C++ classes.

METHODS

new(): Create and return a new output class.
write: Creates a C header file with structs for class definitions.

SystemC::Vregs::Output::Class

NAME

SystemC::Vregs::Output::Class - Outputting Vregs Code

SYNOPSIS

SystemC::Vregs::Output::Class->new->write_class_h(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package contains additional SystemC::Vregs methods. These methods are used to output various types of files.

METHODS

write_class_h: Creates a C++ header file with class definitions.
write_class_cpp: Creates a C++ implementation file to correspond with write_class_h.
write_struct_h: Creates a C header file with structs for class definitions.

SystemC::Vregs::Output::Defines

NAME

SystemC::Vregs::Output::Defines - Dump Vregs into Defines header format

SYNOPSIS

SystemC::Vregs::Output::Defines->new->write(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package dumps vregs format into a header file for various languages. It is called by the Vregs package.

METHODS

new(): Create and return a new output class.
$self->write(pack=>vregsPackage, filename=>filename): Creates a C++, Verilog, or Perl header file with defines. The language parameter is used along with SystemC::Vregs::Language to produce the definitions in a language appropriate way.

SystemC::Vregs::Output::Hash

NAME

SystemC::Vregs::Output::Hash - Dump Vregs into Hash format

SYNOPSIS

SystemC::Vregs::Output::Hash->new->write(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package dumps vregs format into a perl Hash file. It is called by the Vregs package.

METHODS

new(): Create and return a new output class.
$self->write(pack=>vregsPackage, filename=>filename): Creates the output file.

SystemC::Vregs::Output::Info

NAME

SystemC::Vregs::Output::Info - Outputting Vregs _dump Code

SYNOPSIS

SystemC::Vregs::Output::Info->new->write_h(pack=>$VregsPackageObject, filename=>$fn); SystemC::Vregs::Output::Info->new->write_cpp(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package dumps vregs format into a file. It is called by the Vregs package.

METHODS

new(): Create and return a new output class.
write_h: Creates a header file for use with write_cpp.
write_cpp: Creates a C++ file with information on each register. The information is then added to a map which may be used during runtime to decode register addresses into names.

SystemC::Vregs::Output::Latex

NAME

SystemC::Vregs::Output::Latex - Outputting .tex files

SYNOPSIS

SystemC::Vregs::Output::Latex->new->write(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package dumps registers in Latex table format, suitable for printing. It is called by the Vregs package.

METHODS

new(): Create and return a new output class.
write: Creates the latex file.

SystemC::Vregs::Output::Layout

NAME

SystemC::Vregs::Output::Layout - Outputting .vregs files

SYNOPSIS

SystemC::Vregs::Output::Layout->new->write(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package dumps .vregs format into a file. It is called by the Vregs package.

METHODS

new(): Create and return a new output class.
write: Creates a file for use with vregs_read.

SystemC::Vregs::Output::Param

NAME

SystemC::Vregs::Output::Param - Dump Vregs into Perl Parameters format

SYNOPSIS

SystemC::Vregs::Output::Param->new->write(pack=>$VregsPackageObject, filename=>$fn);

DESCRIPTION

This package dumps vregs format into a perl parameters file. It is called by the Vregs package.

METHODS

new(): Create and return a new output class.
$self->write(pack=>vregsPackage, filename=>filename): Creates the output file.

SystemC::Vregs::Register

NAME

SystemC::Vregs::Register - Register object

SYNOPSIS

    use SystemC::Vregs;

DESCRIPTION

This package contains a blessed hash object for each register definition.

FIELDS

These fields may be specified with the new() function, and accessed via the self hash: $self->{field}.

addrtext: Textual form of the address of the register.
spacing: Spacing of each register in a range, normally 4 bytes.
range: Entry range a ram covers, for example [7:0].
name: Name of the object.
pack: Reference to the package (SystemC::Vregs) object self is a member of.

DERIVED FIELDS

These fields are valid only after check() is called.

addr: Address of the register.
addr_end: Ending address of the register.

METHODS

new: Creates a new register object.
check: Checks the object for errors, and parses to create derived fields.

SystemC::Vregs::Rules

NAME

SystemC::Vregs::Rules - Rules for outputting class headers

SYNOPSIS

    In a I<package>__rules.pl file:

    before_file_body    (replace => 1,
                         text => "#include \"myinclude.h\"\n",);
    before_enum_begin (  name => qr/_mine$/,
                         text => "    static const bool  MINE = true\n", );
    after_enum_end (     name => 'Foo',
                         prog => sub { fprint "   // enum foo\n"; }, );

DESCRIPTION

This package is used to execute Vregs rule files. These files describe exceptions and additional text to be included in Vregs outputs.

RULE DECLARATIONS

These functions are used to describe a rule. A rule has a number of rule parameters, generally a name which must match, and a text or prog parameter.

after_any_file: Specifies a rule to be invoked at the bottom of any type of file.
before_any_file: Specifies a rule to be invoked at the top of any type of file.
after_file_body: Specifies a rule to be invoked at the bottom of the class.h file.
before_file_body: Specifies a rule to be invoked to produce the #include and other text at the top of the class.h file.
after_class_begin: Specifies a rule to be invoked right after the 'class foo {' line.
before_class_end: Specifies a rule to be invoked right before the '}' ending a class declaration.
after_class_end: Specifies a rule to be invoked right after the '}' ending a class declaration.
after_defines_body: Specifies a rule to be invoked at the bottom of the defs.h file.
before_defines_body: Specifies a rule to be invoked at the top of the defs.h file.
after_enum_begin: Specifies a rule to be invoked right after the 'enum foo {' line.
before_enum_end: Specifies a rule to be invoked right before the '}' ending a enum declaration.
after_enum_end: Specifies a rule to be invoked right after the '}' ending a enum declaration.

RULE PARAMETERS

name => 'string' =item name => qr/regexp/: Must be either a string which must match for the rule to be invoked, or a regexp reference (qr/regexp/) which if matches will invoke the rule.
replace => 1: Generally rules are cumulative, in that defining additional rules will place additional cases to be tested. With the replace flag, the rule will replace all existing rules, including default rules. This is generally useful for replacing the default #include section with the before_file_body rule.
text => 'text': A text string to output to the file.
prog => sub { subroutine }: A reference to a subroutine that generates the code for the file.

RULE SUBROUTINES

These functions and variables are useful when writing prog=> subroutines.

$self: Reference to a SystemC::Vregs::Enum or SystemC::Vregs::Type, as appropriate. This can be used to get information about the thing to be printed, for example $self->{name} is the name of the object, and $self->{attributes}{foo} checks for a specific attribute.
fprint: Print to the file.
fprintf: Formatted print to the file.

SystemC::Vregs::Subclass

NAME

SystemC::Vregs::Subclass - Common base class

SYNOPSIS

    use SystemC::Vregs;

METHODS

new: Creates a new blessed object.
warn: Prints a warning message, using the name field if it exists. Errors are held until exit_if_error is called.
exit_if_error: Exits if any warnings have been found.
clean_sentence.: Finds the first sentence in a paragraph. Used to extract description lines from the description columns.

SystemC::Vregs::TableExtract

NAME

SystemC::Vregs::TableExtract - Superclass of HTML::TableExtract for vregs usage

SYNOPSIS

DESCRIPTION

SystemC::Vregs::TableExtract is a superclass of HTML::TableExtract which understands how to extract text and tables from HTML documents, and invoke callbacks as Vregs sections are encountered.

It is designed to be used by SystemC::Vregs only.

SystemC::Vregs::Type

NAME

SystemC::Vregs::Type - Type object

SYNOPSIS

    use SystemC::Vregs;

DESCRIPTION

This package contains a blessed hash object for each class and register definition.

FIELDS

These fields may be specified with the new() function, and accessed via the self hash: $self->{field}.

inherits: String with whatever base classes this class should inherit from.
fields: Hash with references to SystemC::Vregs::Bit objects, for the fields inside this class.
name: Name of the object.
pack: Reference to the package (SystemC::Vregs) object self is a member of.

DERIVED FIELDS

These fields are valid only after check() is called.

inherits_typeref: Reference to a SystemC::Vregs::Type object for the base class of this object (if any.)

METHODS

new: Creates a new type object.
check: Checks the object for errors, and parses to create derived fields.

Vregs

Wiki

vreg

NAME

SYNOPSIS

DESCRIPTION

HTML CONVERSION

HEADER CREATION

GENERAL ARGUMENTS

OUTPUT FILE TYPE ARGUMENTS

DISTRIBUTION

AUTHORS

SEE ALSO

vreg_latex2html

NAME

SYNOPSIS

DESCRIPTION

ARGUMENTS

ENVIRONMENT

SEE ALSO

SystemC::Vregs

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO

SystemC::Vregs::Bit

NAME

SYNOPSIS

DESCRIPTION

FIELDS

DERIVED FIELDS

METHODS

SEE ALSO

SystemC::Vregs::Define

NAME

SYNOPSIS

DESCRIPTION

FIELDS

DERIVED FIELDS

METHODS

SEE ALSO

SystemC::Vregs::Enum

NAME

SYNOPSIS

DESCRIPTION

FIELDS

METHODS

SEE ALSO

SystemC::Vregs::File

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO

SystemC::Vregs::Language

NAME

SYNOPSIS

DESCRIPTION

FIELDS

ACCESSORS

OUTPUT FUNCTIONS

SEE ALSO

SystemC::Vregs::Number

NAME

SYNOPSIS

DESCRIPTION

SEE ALSO

SystemC::Vregs::Output::CBitFields

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO

SystemC::Vregs::Output::Class

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO