rdunkley / vhdlcodegen

VHDL Code Generation Library - Allows consumer to easily generate simplified VHDL code.

VHDLCodeGen

VHDL Code Generation Library - C# library which allows consumer to easily generate simplified well-structured VHDL code. The classes represent different components of the VHDL language. An application can use the data structures to create components in a VHDL file and then rely on the library to organize and document the components and generate the actual files.

This library is not intended to represent all the possible code structures or implementation of VHDL. It is meant to provide a simplified view of creating VHDL modules so that a code generation tool can very quickly and easily generate well-structured, simplified code.

Well-structured referenced above means that the code is documented and organized according to strict guidelines. The software classes require minimum documentation text to be added when the objects are created and generates the documentation based on this text. It currently provides the following structured features:

1. Adds flower boxes around documentation. Adds flower box lines before and after all documentation. The flower box character can be specified using DefaultValues.FlowerBoxCharacter. It can be set to null, to omit the flower box lines.

2. Generates a file sub-header. Some coding standards require a sub-header at the top of the file that lists the components of the file for a quick reference. This can be turned on or off using DefaultValues.IncludeSubHeader.

3. File header template. The library allows you to specify a file header in template form so that it can populate it and add it to all the code files generated. You specify the template using DefaultValues.FileInfoTemplate. Note: the string lines provided will be added to the top of the file directly.

4. Copyright template. The library allows you to specify a copyright statement in template form so that it can populate it and add it to all the code files generated. This allows you to specify a simple copyright (Ex: "Copyright © <%developer%> <%year%>") or a much more complex one. The copyright template is specified using DefaultValues.CopyrightTemplate. Note: the string line is added to comment line(s) directly below the file header so no need to add the required comment characters at the first of it.

5. License template. The library allows you to specify a license statement in template form so that it can populate it and add it to all the code files generated. If you are planning on open-sourcing the code you generate you won't need to add the information later. The license template can be set using DefaultValues.LicenseTemplate. These lines are added after the appropriate comment characters so you can copy this strait out of your typical license file.

6. Can specify the number of spaces in the indentation for the files. This is set using DefaultValues.TabSize.

7. Can specify whether tabs or spaces should be used for indentation. This is set using DefaultValues.UseTabs.

8. Can specify the number of characters per line and will break code and comments to a new line if they exceed the number of characters. This is set using DefaultValues.NumCharactersPerLine.

9. Section Start Template. Allows you to specify the template that will be added to the code at the start of a section. Sections are defined by 'Functions', 'Constants & Types', 'Procedures', 'Components', 'Signals', 'Aliases', 'Attributes', 'Processes', 'Generates', and 'Sub-Modules'. The <%filename%> and <%description%> tags are not supported in this template. The <%param%> tag is the name of the section.

10. Section End Template. Allows you to specify the template that will be added to the code at the end of a section. Sections are defined by 'Functions', 'Constants & Types', 'Procedures', 'Components', 'Signals', 'Aliases', 'Attributes', 'Processes', 'Generates', and 'Sub-Modules'. The <%filename%> and <%description%> tags are not supported in this template. The <%param%> tag is the name of the section.

11. Can specify whether to add the optional type names to the end of entity, architecture, function, procedure, and package. This is set using DefaultValues.AddOptionalTypeNames.

12. Can specify whether to add the optional name/label to the end of entity, architecture, component, function, procedure, and generate. This is set using DefaultValues.AddOptionalNames.

13. Can specify whether to add a space after certain key words in the auto-generated code. For example, he space allows a preference between 'process (' and 'process('. This is set using DefaultValues.AddSpaceAfterKeyWords.

The templates above have defaults in them that you will definitely want to change before generating code. All templates can be left out by providing an empty or null value for the associated template. The templates have the following optional tags that are replaced when the code is generated:

Generic Tags: 1. <%year%> - Replaced with the current year.

2. <%date%> - Replaced with the current date.

3. <%time%> - Replaced with the current time.

4. <%datetime%> - Replaced with the current date and time.

Global Tags: 1. <%developer%> - Replaced with the Developer's Name (as specified in the DefaultValues properties).

2. <%company%> - Replaced with the Company Name (as specified in the DefaultValues properties).

3. <%appversion%> - Replaced with the calling application's version.

4. <%appname%> - Replaced with the calling application's name.

5. <%libraryversion%> - Replaced with the VHDLCodeGen library version.

6. <%libraryname%> - Replaced with the VHDLCodeGen library name.

7. <%flowerfill%> - Fills the rest of the line with the flower character.

Other Template Tags: 1. <%copyright%> - Replaced with the copyright statement (cannot be cyclic).

2. <%license%> - Replaced with the license statement (cannot be cyclic).

Item Specific Tags: 1. <%filename%> - Replaced with the file name being generated.

2. <%description%> - Replaced with a description of the file being generated.

3. <%param%> - Replaced with a parameter based on context. See individual template for details.

vhdlcodegen's Issues

Add support for records

The library currently doesn't have support for records. Add support.

Need ability to convert signals on sub-module inputs

If a component takes in a std_logic_vector you can pass in an unsigned by casting it. The current SubModule class does not provide the ability to do this.

It would be nice to reference components by their name

Objects containing child list objects would be nice to have a way to reference those objects using the object name instead of index. This would reduce the logic a consumer would have to have to find the right object.

SignalInfo places order of preclock signal and type incorrectly

Line 92 in SignalInfo.cs should re-arrange the nextValueString and Type to something like:

"signal {0}{1} : {2}{3};", Name, nextValueString, Type, ...

Header info should be alphabetized

Starting with line 153 in FileInfo (method GenerateModuleSubInfo), the lists should be sorted prior to listing.

Add setting to determine whether closing name is added or not

At the end of certain declarations you can either specify a name or not (Ex: "end entityname;" vs "end;"). Recommend making it a setting on whether to include these or not. Note: some are required.

Components aren't currently added for sub-modules in generates.

Line 209 of ModuleInfo takes all the unique components from the sub-modules of the module. It then creates the Components region with their declarations. This doesn't account for Sub-Modules contained in child GenerateInfo objects. Recommend concatenating all the sub-modules in the generate with the module's sub-modules and then write out the unique ones.

Make SimplifiedGenericInfo and SimplifiedPortInfo support IComparable

Right now a consumer can sort lists of object that inherit from BaseTypeInfo. Should make the simplified classes support the interface so they can be sorted and compared as well by their name.

Easier way to set up Port and Generic maps

Need an easier way to setup Port and Generic maps in Submodule objects. It's painful right now.

Add ability to choose between vhd and vhdl file extensions

Right now the generated code has a vhdl extension on the files. Recommend adding the option to allow vhd file extension as well.

Create a setting to specify whether spaces should be placed after keywords

Recommend making a setting that will specify whether to include a space after a key word or not (Ex: "process (" vs "process(". This will allow users to dial it in to their individual coding standards.

Type and Subtypes are generated incorrectly

DeclarationInfo.Write method should use "is" instead of ":" for type and Subtypes. Only constants use ":". Suggest replacing WriteLine string format to one that passes in a typeAssigner string for this portion. The typeAssigner could then be generated above based on the type.

Descriptions should wrap to their beginning mark.

Right now when the documentation is generated the descriptions are wrapped to the beginning of the item's name. Suggest wrapping to the end of the item's name (beginning of description). This will make the documentation look cleaner. Also suggest adding blank lines in between sections.

SignalInfo generates incorrect code

Line 88 in SignalInfo.cs creates the pre clock signal but it passes DefaultValue as the name instead of Name.

Add the ability to specify section header formatting.

Currently a line is created with the flower box characters for the different sections. Recommend adding the ability to specify an opening and closing template for the sections.

Add support for packages.

The library currently doesn't have support to generate packages. Add the support.

Add "Structure" to ArchitecturalType

The architecture types supported currently are rtl and behavioral. I recommend also adding structural for modules that are wrappers for other modules.