diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..3f0ed21 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +docs/_build/ diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..71226ec --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,225 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help +help: + @echo "Please use \`make ' where is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " applehelp to make an Apple Help Book" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " epub3 to make an epub3" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " xml to make Docutils-native XML files" + @echo " pseudoxml to make pseudoxml-XML files for display purposes" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + @echo " coverage to run coverage check of the documentation (if enabled)" + @echo " dummy to check syntax errors of document sources" + +.PHONY: clean +clean: + rm -rf $(BUILDDIR)/* + +.PHONY: html +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +.PHONY: dirhtml +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +.PHONY: singlehtml +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +.PHONY: pickle +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +.PHONY: json +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +.PHONY: htmlhelp +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +.PHONY: qthelp +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/VHDL-2008SupportLibrary.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/VHDL-2008SupportLibrary.qhc" + +.PHONY: applehelp +applehelp: + $(SPHINXBUILD) -b applehelp $(ALLSPHINXOPTS) $(BUILDDIR)/applehelp + @echo + @echo "Build finished. The help book is in $(BUILDDIR)/applehelp." + @echo "N.B. You won't be able to view it unless you put it in" \ + "~/Library/Documentation/Help or install it in your application" \ + "bundle." + +.PHONY: devhelp +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/VHDL-2008SupportLibrary" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/VHDL-2008SupportLibrary" + @echo "# devhelp" + +.PHONY: epub +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +.PHONY: epub3 +epub3: + $(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3 + @echo + @echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3." + +.PHONY: latex +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +.PHONY: latexpdf +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: latexpdfja +latexpdfja: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through platex and dvipdfmx..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf-ja + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +.PHONY: text +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +.PHONY: man +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +.PHONY: texinfo +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +.PHONY: info +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +.PHONY: gettext +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +.PHONY: changes +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +.PHONY: linkcheck +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +.PHONY: doctest +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." + +.PHONY: coverage +coverage: + $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage + @echo "Testing of coverage in the sources finished, look at the " \ + "results in $(BUILDDIR)/coverage/python.txt." + +.PHONY: xml +xml: + $(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml + @echo + @echo "Build finished. The XML files are in $(BUILDDIR)/xml." + +.PHONY: pseudoxml +pseudoxml: + $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml + @echo + @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." + +.PHONY: dummy +dummy: + $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy + @echo + @echo "Build finished. Dummy builder generates no files." diff --git a/docs/additions.rst b/docs/additions.rst new file mode 100644 index 0000000..61c4fb2 --- /dev/null +++ b/docs/additions.rst @@ -0,0 +1,17 @@ +Additions to... +############### + + * :doc:`std.standard ` + * :doc:`std.env ` + * :doc:`std.textio ` + * :doc:`ieee.std_logic_1164 ` + * :doc:`ieee.numeric_std ` + +.. toctree:: + :hidden: + + std.standard + std.env + std.textio + ieee.std_logic_1164 + ieee.numeric_std diff --git a/docs/altera.rst b/docs/altera.rst new file mode 100644 index 0000000..e045f5b --- /dev/null +++ b/docs/altera.rst @@ -0,0 +1,14 @@ +Altera Quartus +############## + +**Tested with Altera Quartus 2 version 9.2** + +First, enter Quartus, and create a project. +Next, add the files ``fixed_float_types_c.vhdl``, ``fixed_pkg_c.vhdl`` and +``float_pkg_c.vhdl`` to the project. +Quartus seems to simply ignore library names, so you can just run from there. + +When loaded, hit the "run" arrow. This will take some time to run, but it +seems to give a functional result. + +I needed to modify no files for this version of Quartus. diff --git a/docs/cadence_ncvhdl.rst b/docs/cadence_ncvhdl.rst new file mode 100644 index 0000000..fd45470 --- /dev/null +++ b/docs/cadence_ncvhdl.rst @@ -0,0 +1,15 @@ +Cadence ncvhdl +############## + +Tested with ncvhdl 08.20-s004.

+ +To compile: You will need to setup your ``cds.lib`` and ``hdl.var`` files, then +create an ``ieee_proposed`` and ``worklib`` directory. Then you can just run +``compile.ncvhdl``. + +See the README for an explination of the new functions in these packages. + +.. NOTE:: + ncvhdl is stricter on syntax then Modeltech. It actually found a few minor + things that I missed. The only error I found was in the ``env_c.vhdl`` file. + It didn't like the 10 hr and 100 hr time resolutions. diff --git a/docs/cadence_rc.rst b/docs/cadence_rc.rst new file mode 100644 index 0000000..46581b3 --- /dev/null +++ b/docs/cadence_rc.rst @@ -0,0 +1,25 @@ +Cadence RC +########## + +Checked with RC version 11.20 + +To Compile: +just run "compile.rc" + +Notes: +Had to remove the "match_table". This gave me the error: +Error : Incompatible bitwidths in assignment. [CDFG-283] [elaborate] + : Width of target 'match_logic_table' (1) doesn't match the width of the assigned value (81) in file 'fixed_pkg_c.vhdl' on line 1595. + : Use 'set_attribute hdl_vhdl_assign_width_mismatch true /' to allow such assignments with mismatching widths of lhs and rhs. + +So, I set the variable, and still had the error.... +Replaced it with an "rtl" version of the match table. In synthsis it will behave +the same way as rtl, but not in simulaiton. + +Version 11.20 hung on the floating point package. I reported this to Cadence, +and they said to change the synthesis effort to "medium" and use verion 12.10. + +To run these testcases: + +rc -f fixed_synth.tcl +rc -f float_synth.tcl diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..71ea9cc --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,348 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# VHDL-2008 Support Library documentation build configuration file, created by +# sphinx-quickstart on Tue Oct 11 10:25:39 2016. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.intersphinx', + 'sphinx.ext.todo', + 'sphinx.ext.mathjax', + 'sphinx.ext.ifconfig', +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The encoding of source files. +# +# source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'VHDL-2008 Support Library' +copyright = '2016, David W. Bishop' +author = 'David W. Bishop' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.0' +# The full version, including alpha/beta/rc tags. +release = '1.0.0' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +# +# today = '' +# +# Else, today_fmt is used as the format for a strftime call. +# +# today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = [] + +# The reST default role (used for this markup: `text`) to use for all +# documents. +# +# default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +# +# add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +# +# add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +# +# show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +# modindex_common_prefix = [] + +# If true, keep warnings as "system message" paragraphs in the built documents. +# keep_warnings = False + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- +import sphinx_rtd_theme +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +html_theme_path = [sphinx_rtd_theme.get_html_theme_path()] + +# The name for this set of Sphinx documents. +# " v documentation" by default. +# +# html_title = 'VHDL-2008 Support Library v1.0.0' + +# A shorter title for the navigation bar. Default is the same as html_title. +# +# html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +# +# html_logo = None + +# The name of an image file (relative to this directory) to use as a favicon of +# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +# +# html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Add any extra paths that contain custom files (such as robots.txt or +# .htaccess) here, relative to this directory. These files are copied +# directly to the root of the documentation. +# +# html_extra_path = [] + +# If not None, a 'Last updated on:' timestamp is inserted at every page +# bottom, using the given strftime format. +# The empty string is equivalent to '%b %d, %Y'. +# +# html_last_updated_fmt = None + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +# +# html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +# +# html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +# +# html_additional_pages = {} + +# If false, no module index is generated. +# +# html_domain_indices = True + +# If false, no index is generated. +# +# html_use_index = True + +# If true, the index is split into individual pages for each letter. +# +# html_split_index = False + +# If true, links to the reST sources are added to the pages. +# +# html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +# +# html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +# +# html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +# +# html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +# html_file_suffix = None + +# Language to be used for generating the HTML full-text search index. +# Sphinx supports the following languages: +# 'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja' +# 'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr', 'zh' +# +# html_search_language = 'en' + +# A dictionary with options for the search language support, empty by default. +# 'ja' uses this config value. +# 'zh' user can custom change `jieba` dictionary path. +# +# html_search_options = {'type': 'default'} + +# The name of a javascript file (relative to the configuration directory) that +# implements a search results scorer. If empty, the default will be used. +# +# html_search_scorer = 'scorer.js' + +# Output file base name for HTML help builder. +htmlhelp_basename = 'VHDL-2008SupportLibrarydoc' + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'VHDL-2008SupportLibrary.tex', 'VHDL-2008 Support Library Documentation', + 'David W. Bishop', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +# +# latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +# +# latex_use_parts = False + +# If true, show page references after internal links. +# +# latex_show_pagerefs = False + +# If true, show URL addresses after external links. +# +# latex_show_urls = False + +# Documents to append as an appendix to all manuals. +# +# latex_appendices = [] + +# It false, will not define \strong, \code, itleref, \crossref ... but only +# \sphinxstrong, ..., \sphinxtitleref, ... To help avoid clash with user added +# packages. +# +# latex_keep_old_macro_names = True + +# If false, no module index is generated. +# +# latex_domain_indices = True + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'vhdl-2008supportlibrary', 'VHDL-2008 Support Library Documentation', + [author], 1) +] + +# If true, show URL addresses after external links. +# +# man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'VHDL-2008SupportLibrary', 'VHDL-2008 Support Library Documentation', + author, 'VHDL-2008SupportLibrary', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +# +# texinfo_appendices = [] + +# If false, no module index is generated. +# +# texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +# +# texinfo_show_urls = 'footnote' + +# If true, do not generate a @detailmenu in the "Top" node's menu. +# +# texinfo_no_detailmenu = False + + +# Example configuration for intersphinx: refer to the Python standard library. +intersphinx_mapping = {'https://docs.python.org/': None} diff --git a/docs/fixed_float_types.rst b/docs/fixed_float_types.rst new file mode 100644 index 0000000..32b3471 --- /dev/null +++ b/docs/fixed_float_types.rst @@ -0,0 +1,4 @@ +fixed_float_types +################# + + diff --git a/docs/fixed_pkg.rst b/docs/fixed_pkg.rst new file mode 100644 index 0000000..a0ca5b4 --- /dev/null +++ b/docs/fixed_pkg.rst @@ -0,0 +1,4 @@ +fixed_pkg +######### + + diff --git a/docs/float_pkg.rst b/docs/float_pkg.rst new file mode 100644 index 0000000..d86fb5c --- /dev/null +++ b/docs/float_pkg.rst @@ -0,0 +1,4 @@ +float_pkg +######### + + diff --git a/docs/fpfaq.rst b/docs/fpfaq.rst new file mode 100644 index 0000000..559e529 --- /dev/null +++ b/docs/fpfaq.rst @@ -0,0 +1,172 @@ + +Fixed and Floating point VHDL FAQ + + + + + + + + + + + + + + + +

+Fixed and Floating point VHDL FAQ

+ +

+What follows are frequently asked questions about the fixed and floating +point VHDL packages.   VHDL-93 source code can be found on the +VHDL-2008 support library page. +  +You will find these packages built into several implimentations of VHDL.   +

+

+What synthesis results can I expect? +

+

+Under the hood, all of the fixed and floating point functions call functions +from the "numeric_std" package.   Much work was done to make sure that +these algorithms would be as fast as possible.   You can expect a fixed +point multiply to be just as fast as an UNSIGNED multiply.   Floating +point gives you about 3X overhead.   However you get much more accurate +results.   My best results have been gotten by mixing the two. +

+

+Where are the shift operators?

+

+You don't need them. Use the "scalb" function. This function works as +follows: +

+variable uf1 : ufixed (5 downto 0);
+variable uf2 : ufixed (4 downto -1);
+...
+uf2 := scalb (uf1, -1);  -- shift right by 1
+
+The nice thing about this function is that you don't loose any data.   +Note that under the hood, for some synthesis tools, this function is +implimented with shift operators. Standard shift operators are built into +VHDL-2008, but some vendors have not implemented them. +

+

+Why can't I say "X <= '0' & Y;" to tack a '0' in front of +(or behind) a vector? +

+

+The problem here is that the vector returned will be +"ufixed (integer'low to integer'low+Y'high)" or essentially 2**-32,000 +(a VERY small number).   +Instead, use the resize function: +

+X <= resize (Y, X'high, X'low);
+
+The resize function is used to all of the rouding in the fixed point package. +

+

+These sizing rules are a pain.   Why can't these packages work more +like numeric_std?

+

+The sizing was done so that you never need to round, thus removing one addition +stage, and making the results run faster.   +For the applications where this is just a pain, I've created +fixed_noresize.vhdl.   +This package creates the types "fixedu" and "fixeds" (which are similar to +"ufixed" and "sfixed"). However these new types have the same sizing rules +as numeric_std UNSIGNED and SIGNED. +

+

Note that there is also an "add_carry" procedure in the +fixed point package for fixed point +accumulators, which can be used like this: +

+variable uf3: ufixed (3 downto -2);
+constant one : ufixed (0 downto 0) := "1";
+...
+add_carry (
+  L => uf3,
+  R => one,
+  result => uf3,
+  c_in => '0',
+  c_out => open);
+
+This procedure will return a result which is the "widest" of the inputs.   +Overflow will show up in the "c_out" output. +

+

+My floating point divider (or other function) is slow, what can I do about it? +

+

+Yes, it will be, a floating point divider is lots of logic.   +You will need to pipeline these functions.   +Some synthsis tools will do this for you automatically.   +Others will make you pipline them manually.   +I have already created pipelined versions of many of them. +

+

+How do you convert unsigned fixed point (ufixed) +into signed fixed point (sfixed)? +

+

+There is a function "to_sfixed(ufixed)" which increases the size of the output +by 1 (the sign bit).   +The "to_ufixed(sfixed)" function returns a vector of the same size as the +input.   + +

+

+What happened to the "math_utility_pkg" package?

+It got replaced with the +fixed_float_types package +during the final edits of the VHDL-2008 LRM.   +Some older implimentations of these packages (like the ones built into the +floatfixlib library in version 6.* of Modeltech) still use it.   +The types in these two packages are identical. +

+

+Why does the "break_number" return an incorrect result?

+This has to do with how the floating point number is encoded. The exponent is +biased by -1. Thus if you take every result and multiply it by 2 you will get +the correct answer. The "break_number" routine was designed to be a synthesis pass +through, creating no logic. It is up to the next function to fix the bias. +

+What bugs have been found?

+

+So far: +

    +
  • The add_carry for both the "sfixed" and "ufixed" types has a bug in +the "c_out" output. "c_out" will be incorrect because of this bug. +This function is fixed in the latest version +
    • +
  • The to_float (sfixed) function will return the wrong result if the +"sfixed" value is the largest possible negative number ("100000").   +That function is fixed in the latest version. +
    • +
  • The to_float (ufixed) funciton will return the wrong result if the +decimal width of the number is larger than can be held in the exponent of the +result.   This is only a problem with denormal numbers.   +That function is fixed in the latest version. +
    • +
  • The documented sizing rules for the fixed point reciprocal + function in +the VHDL-2008 LRM is wrong.   It is corrected in +Fixed point users guide +
    • +
+

+Need some help with this code? +Drop me an e-mail, maybe I can help.
+My company will also allow me to consult for you.
+

+

+This web page is brought to you by the +EDA Industry Working Groups and +Accellera. +

+ + + \ No newline at end of file diff --git a/docs/ieee.numeric_std.rst b/docs/ieee.numeric_std.rst new file mode 100644 index 0000000..6c1e323 --- /dev/null +++ b/docs/ieee.numeric_std.rst @@ -0,0 +1,4 @@ +ieee.numeric_std +################ + + diff --git a/docs/ieee.std_logic_1164.rst b/docs/ieee.std_logic_1164.rst new file mode 100644 index 0000000..0aa4f1f --- /dev/null +++ b/docs/ieee.std_logic_1164.rst @@ -0,0 +1,4 @@ +ieee.std_logic_1164 +################### + + diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..06a3acf --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,116 @@ +VHDL-2008 Support Library +######################### + +These packages were designed as a bridge between VHDL-93 and VHDL-2008. I +replicated as many of the new functions as possible. Note that all of these +packages are design to be synthesizable in VHDL-93. So, as long as you stick +to the subsets defined in the "README" files for the various vendors you should +be able to take your code through the entire flow. + +VHDL-2008 is finally getting some traction. What started out as just a fixed +and floating point package got merged into the VHDL LRM. On this page you will +find definitions of the functions available in the VHDL-2008 libraries. You will +also find VHDL-93 compatible code for those that do not yet have access to +VHDL-2008 compilers. + +There is a Fixed Point user's guide and a Floating Point user's guide. Please +check the Fixed and floating point FAQ (NEW!) if you have any quesiton. + +The VHDL-2008 packages will eventually be included in your vendor's environment. +In some cases I have found that they may be encrypted due to IEEE rules. The +packages available on this page are NOT the released packages, but VHDL-93 +versions of those packages, which I published BEFORE the release of the LRM. +They are free of copyright restrictions, and may be used for whatever purpose is +needed. + +VHDL-93 versions of the VHDL-2008 packages +****************************************** + ++----------------------------------+----------------------------------+-------------------------------+ +| Description | File | User Guide | ++==================================+==================================+===============================+ +| Additions to std.standard | standard_additions_c.vhdl | user's guide | ++----------------------------------+----------------------------------+-------------------------------+ +| New package std.env | env_c.vhdl | | ++----------------------------------+----------------------------------+-------------------------------+ +| Additions to std.textio | standard_textio_additions_c.vhdl | (user's guide) | ++----------------------------------+----------------------------------+-------------------------------+ +| Additions to ieee.std_logic_1164 | std_logic_1164_additions.vhdl | (user's guide) | ++----------------------------------+----------------------------------+-------------------------------+ +| Additions to ieee.numeric_std | numeric_std_additions.vhdl | (user's guide) | ++----------------------------------+----------------------------------+-------------------------------+ +| New package numeric_std_unsigned | numeric_std_unsigned_c.vhdl | (user's guide) | ++----------------------------------+----------------------------------+-------------------------------+ +| New package fixed_float_types | fixed_float_types_c.vhdl | | ++----------------------------------+----------------------------------+-------------------------------+ +| New package fixed_pkg | fixed_pkg_c.vhdl | (Fixed Point user's guide) | ++----------------------------------+----------------------------------+-------------------------------+ +| New package float_pkg | float_pkg_c.vhdl | (Floating Point user's guide) | ++----------------------------------+----------------------------------+-------------------------------+ + +.. ZIP file of all the packages (updated 09/2010) + +I use this code in most of my designs. Many times I find that I have to modify +the code slightly in some tools, so I made this list. Included in the "source +code" section for each tool is source code specifically debugged for that +particluar tool. Click on the "documentation" link to see what changes I had to +make, and how to use this code in the specific tool. + +Tool specifc modifications +************************** + ++--------------------------------+----------+-------+ +| Vendor / Tool | ZIP File | Notes | ++================================+==========+=======+ +| :doc:`Altera Quartus ` | | | ++--------------------------------+----------+-------+ + +.. + Altera Source code Documentation + Cadence ncvhdl Source code Documentation + Cadence RC (new) Source code Documentation + Modeltech Source code Documentation + Synopsys Source code Documentation + Synplicity Source code Documentation + Xilinx 11.1 Source code Documentation + Xilinx 9.1 Source code (old) Documentation + VCS Source code Documentation + Spectrum 2009a Source code Documentation + +.. TODO:. + Aldec + +Some helpful code to go with these packages +******************************************* + + * fixed_noresize.vhdl + Similar to ``fixed_pkg``, however this version uses the same rules that + ``numeric_std`` does for the size of the result. This is done by calling + the function in ``fixed_pkg`` and resizing the result. + * float_noround_pkg.vhdl + Similar to ``float_pkg``, however this version turns off all of the IEEE + rounding and overflow, and defaults to a 26 bit floating point number. + This package saves off 1/3 of the logic needed for full 32 bit floating + point. + * fixed_synth.vhdl + Synthesis testcase for the fixed point package. + * test_fixed_synth.vhdl + Testbench for the fixed point synthesis testcase. + * float_synth.vhdl + Synthesis testcase for the floating point package. + * test_float_synth.vhdl + Testbench for the floating point synthesis package + * Matrix Math package + for type REAL which has a user guide (Done in conjunction with IEEE 1076.1 VHDL-AMS) + * Testbenches to verify an implimentation of VHDL-2008. + + + + + +.. toctree:: + :hidden: + + new + additions + tools diff --git a/docs/leonardo.rst b/docs/leonardo.rst new file mode 100644 index 0000000..a6eb401 --- /dev/null +++ b/docs/leonardo.rst @@ -0,0 +1,18 @@ +Leonardo Spectrum +################# + +Leonardo Spectrum (2009a) + +Spectrum doesn't like the fixed point "divide" functions, so they are +commented out in this release. In order to get a divide to work you +will have to write your own divider. +I've also had to comment out the "alias" statement. + +To run this code: +``spectrum -f fixed_synth.tcl`` + +For some reason Spectrum picks slow multipliers. You may need to use the +Modgen multipliers to meet timing. + +Floating point functions, but the synthesis is very slow. I would recommand +that you use smaller accumulators with this tool. diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..d8aa9d6 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,281 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. epub3 to make an epub3 + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + echo. dummy to check syntax errors of document sources + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel 9009 goto sphinx_python +goto sphinx_ok + +:sphinx_python + +set SPHINXBUILD=python -m sphinx.__init__ +%SPHINXBUILD% 2> nul +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\VHDL-2008SupportLibrary.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\VHDL-2008SupportLibrary.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "epub3" ( + %SPHINXBUILD% -b epub3 %ALLSPHINXOPTS% %BUILDDIR%/epub3 + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub3 file is in %BUILDDIR%/epub3. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +if "%1" == "dummy" ( + %SPHINXBUILD% -b dummy %ALLSPHINXOPTS% %BUILDDIR%/dummy + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. Dummy builder generates no files. + goto end +) + +:end diff --git a/docs/modelsim.rst b/docs/modelsim.rst new file mode 100644 index 0000000..a9e94eb --- /dev/null +++ b/docs/modelsim.rst @@ -0,0 +1,28 @@ +Modeltech / ModelSim +#################### + +Tested with Modeltech 6.2e + +To compile: source the "compile.mti" script. This will create the +IEEE_PROPOSED VHDL library. The ZIP file contains VHDL-93 compatable versions +of several of the new packages. Included in this ZIP file are the following packages: +
    library ieee_proposed; +
  • use ieee_proposed.standard_additions.all; -- Additions to packages standard.std +
  • use ieee_proposed.standard_textio.all; -- Additions to packages standard.textio +
  • use ieee_proposed.env.all; -- New "env" package +
  • use ieee_proposed.std_logic_1164_additions.all; -- Additions to std_logic_1164 +
  • use ieee_proposed.numeric_std_additions.all; -- Additions to numeric_std +
  • use ieee_proposed.numeric_std_unsigned.all; -- Package to do unsigned math with std_logic_vectors, similar to the (sic) ieee.std_logic_unsigned package. +
  • use ieee_proposed.math_utiliti_pkg.all; -- Types for the fixed and float packages +
  • use ieee_proposed.fixed_pkg.all; -- Fixed point package +
  • use ieee_proposed.float_pkg.all; -- Floating point package +
+ +See the README for an explination of the new functions in these packages. +You will also want to look at the +Fixed point docuementation and the +Floating point docuementation. + +.. NOTE:: + When you simulation, you may need to use the ``-novopt`` option. Otherwise + some of the alias won't get seen correctly. diff --git a/docs/modeltech.rst b/docs/modeltech.rst new file mode 100644 index 0000000..af33fa6 --- /dev/null +++ b/docs/modeltech.rst @@ -0,0 +1,16 @@ +Modeltech / QuestaSim +##################### + +Tested with Modeltech/Questasim 6.5b + +When you compile you will get a warning: +(vcom-1246) Range 0 downto 1 is null. +To suppress this warning compile with "-suppress 1236" +In the MTI install you will find a premapped library called +"floatfixlib". This contains an old version of "fixed_pkg" and "float_pkg". +The versions in this release are newer. + +To compile: source the "compile.mti" script. This will create the +IEEE_PROPOSED VHDL library. + +See the README for an explination of the new functions in these packages. diff --git a/docs/new.rst b/docs/new.rst new file mode 100644 index 0000000..ecec158 --- /dev/null +++ b/docs/new.rst @@ -0,0 +1,15 @@ +New Packages +############ + + * :doc:`numeric_std_unsigned ` + * :doc:`fixed_float_types ` + * :doc:`fixed_pkg ` + * :doc:`float_pkg ` + +.. toctree:: + :hidden: + + numeric_std_unsigned + fixed_float_types + fixed_pkg + float_pkg diff --git a/docs/numeric_std_additions.rst b/docs/numeric_std_additions.rst new file mode 100644 index 0000000..dff9ac0 --- /dev/null +++ b/docs/numeric_std_additions.rst @@ -0,0 +1,74 @@ + +Additions to package numeric_std + + + + + + + + + + + + + + + +

+ numeric_std_additions.vhdl -- Additions to the package "ieee.numeric_std" +

+

+ Use model:
+ use ieee.std_logic_1164.all;
+ use ieee.numeric_std.all;
+ use ieee_proposed.numeric_std_additions.all; +

+ Dependencies: ieee.std_logic_1164, ieee.numeric_std +

+
    +
  • SIGNED or UNSIGNED + std_ulogic operators +
  • SIGNED or UNSIGNED - std_ulogic operators +
  • type UNRESOLVED_UNSIGNED (aliased to U_UNSIGNED) is an unresolved + verion of UNSIGNED. It is aliased to "UNSIGNED" for compatability. +
  • type UNRESOLVED_SIGNED (aliased to U_SIGNED) is an unresolved + verion of SIGNED. It is aliased to "SIGNED" for compatability. +
  • \?=\, \?/=\ - similar to "std_match", but return std_ulogic values. + \?<\, \?<=\, \?>\, \?>=\ - compare functions which retrun std_ulogic. + (these will be "?="... operators in the release) +
  • To_X01, To_X01Z, To_U01X, Is_X - same as std_logic_1164 functions, + but overloaded for SIGNED and UNSIGNED. +
  • "sla" and "sra" - Mathmetically correct versions of these functions. +
  • minimum and maximum - smaller or larger of two SIGNED or UNSIGNED values. +
  • find_leftmost and find_rightmost - finds the first bit in a string.
    + Example:
    + find_leftmost (c12, '1'); -- returns the Log2 of "c12". + returns -1 if not found. +
  • _reduce functions (and_reduce, nand_reduce, or_reduce ...) are defined + These functions reduce a SIGNED or an UNSIGNED to a single bit. + (will overload the "or" and "and", ... operators in the release) +
  • SIGNED or UNSIGNED and "std_ulogic" operations are defined. + These will perform a boolean operation of a vector.
    Example:
    + "1" xor "1010" = "0101"; +
  • READ and WRITE procedures for "SIGNED", and "UNSIGNED" are defined. +
  • HREAD and HWRITE (Hex read and write) for SIGNED and UNSIGNED. + These are more "forgiving" than the ones + originally from "std_logic_textio" +
  • OREAD and OWRITE (octal read and write) for "SIGNED" and "UNSIGNED. + These are more "forgiving" than the ones + originally from "std_logic_textio" +
  • BREAD and BWRITE (binary read and write, same as "READ" and "WRITE" for + SIGNED and UNSIGNED. +
  • to_string function - Converts a "SIGNED" or "UNSIGNED" types into a + string. Example:
    + assert (UNS = "101") report "result was " & to_string(UNS) severity note; +
  • to_hstring and to_ostring function (SIGNED or UNSIGNED to hex or octal + string) + +
+Please send feedback to David W. Bishop +dbishop@vhdl.org.   + + + + \ No newline at end of file diff --git a/docs/numeric_std_addtions.rst b/docs/numeric_std_addtions.rst new file mode 100644 index 0000000..60243dc --- /dev/null +++ b/docs/numeric_std_addtions.rst @@ -0,0 +1,74 @@ + +Additions to package numeric_std + + + + + + + + + + + + + + + +

+ numeric_std_additions -- Additions to the package "ieee.numeric_std" +

+

+ Use model:
+ use ieee.std_logic_1164.all;
+ use ieee.numeric_std.all;
+ use ieee_proposed.numeric_std_additions.all; +

+ Dependencies: ieee.std_logic_1164, ieee.numeric_std +

+
    +
  • SIGNED or UNSIGNED + std_ulogic operators +
  • SIGNED or UNSIGNED - std_ulogic operators +
  • type UNRESOLVED_UNSIGNED (aliased to U_UNSIGNED) is an unresolved + verion of UNSIGNED. It is aliased to "UNSIGNED" for compatability. +
  • type UNRESOLVED_SIGNED (aliased to U_SIGNED) is an unresolved + verion of SIGNED. It is aliased to "SIGNED" for compatability. +
  • \?=\, \?/=\ - similar to "std_match", but return std_ulogic values. + \?<\, \?<=\, \?>\, \?>=\ - compare functions which retrun std_ulogic. + (these will be "?="... operators in the release) +
  • To_X01, To_X01Z, To_U01X, Is_X - same as std_logic_1164 functions, + but overloaded for SIGNED and UNSIGNED. +
  • "sla" and "sra" - Mathmetically correct versions of these functions. +
  • minimum and maximum - smaller or larger of two SIGNED or UNSIGNED values. +
  • find_leftmost and find_rightmost - finds the first bit in a string.
    + Example:
    + find_leftmost (c12, '1'); -- returns the Log2 of "c12". + returns -1 if not found. +
  • _reduce functions (and_reduce, nand_reduce, or_reduce ...) are defined + These functions reduce a SIGNED or an UNSIGNED to a single bit. + (will overload the "or" and "and", ... operators in the release) +
  • SIGNED or UNSIGNED and "std_ulogic" operations are defined. + These will perform a boolean operation of a vector. Example: + "1" xor "1010" = "0101"; +
  • READ and WRITE procedures for "SIGNED", and "UNSIGNED" are defined. +
  • HREAD and HWRITE (Hex read and write) for SIGNED and UNSIGNED. + These are more "forgiving" than the ones + originally from "std_logic_textio" +
  • OREAD and OWRITE (octal read and write) for "SIGNED" and "UNSIGNED. + These are more "forgiving" than the ones + originally from "std_logic_textio" +
  • BREAD and BWRITE (binary read and write, same as "READ" and "WRITE" for + SIGNED and UNSIGNED. +
  • to_string function - Converts a "SIGNED" or "UNSIGNED" types into a + string. Example:
    + assert (UNS = "101") report "result was " & to_string(UNS) severity note; +
  • to_hstring and to_ostring function (SIGNED or UNSIGNED to hex or octal + string) + +
+Please send feedback to David W. Bishop +dbishop@vhdl.org.   + + + + \ No newline at end of file diff --git a/docs/numeric_std_unsigned.rst b/docs/numeric_std_unsigned.rst new file mode 100644 index 0000000..2b956d3 --- /dev/null +++ b/docs/numeric_std_unsigned.rst @@ -0,0 +1,47 @@ + +Package numeric_std_unsigned + + + + + + + + + + + + + + + +

+

+ numeric_std_unsigned.vhdl This package +is a "standardized" verion of "std_logic_unsigned" which appears in many +vendor tools. +

+

+ Use model:
+ use ieee.std_logic_1164.all;
+ use ieee.numeric_std.all;
+ use ieee_proposed.numeric_std_additions.all; + use ieee_proposed.numeric_std_unsigned.all; +

+

VHDL-2008 use model:
+use ieee.numeric_std_unsigned.all; +

+

+ Dependencies: ieee.std_logic_1164, ieee.numeric_std +

+

+This package treats "std_logic_vector" and "std_ulogic_vector" just like the +"unsigned" type in ieee.numeric_std. It has all of the funcitionality of the +old "std_logic_unsigned" package with the ability to use "std_ulogic_vector". +

+Please send feedback to David W. Bishop +dbishop@vhdl.org.   + + + + \ No newline at end of file diff --git a/docs/standard_additions.rst b/docs/standard_additions.rst new file mode 100644 index 0000000..c87085d --- /dev/null +++ b/docs/standard_additions.rst @@ -0,0 +1,65 @@ + +Additions to package standard + + + + + + + + + + + + + + + +

+ standard_additions -- Additions to the package "std.standard" +

+

+ Use model:
+ use ieee_proposed.standard_additions.all;
+ Dependancies: None. +

+ Notes: The functions "rising_edge" and "falling_edge" are defined in + this package. If you use "numeric_bit" they are ALSO defined in that + package, causing a conflict. The VHDL-200X-FT version of numeric_bit + has these functions commented out, as well as the "sll", "srl", "ror" + and "rol" functions which are implicit. +

+
    New types defined in this package: +
  • REAL_VECTOR - A vector of type real +
  • TIME_VECTOR - A vector of type time +
  • INTEGER_VECTOR - A vector of type integer +
  • BOOLEAN_VECTOR - a vector of type boolean +
+
    + New constants defined in this package: +
  • SIM_RESOLUTION : TIME - returns the simulator's resolution (1 ns default) +
+
    New funcitons defined in this package: +
  • "maximum" and "minimum" are defined for all default datatypes +
  • _reduce functions (and_reduce, nand_reduce, or_reduce ...) are defined + These functions reduce a bit_vector to a single bit.
    Example:
    + or_reduce ("0101") = '1' +
    In VHDL-2008 syntax these will be "or". +
  • "vector" and "bit" operations are defined. These will perform a + boolean operation of a vector.
    Example:
    + "1" xor "1010" = "0101"; +
  • /??/ function is defined for "bit" ("??" operator is release) + if (/??/('1')) then -- will return a "true". +
  • rising_edge and falling_edge functions are defined (see Notes). +
  • to_string function - Converts any of the base types into a string.
    + Example:
    + assert (bv = "101") report "result was " & to_string(bv) severity note; +
  • to_hstring and to_ostring function (bit_vector to hex or octal string) +
+ +Please send feedback to David W. Bishop +dbishop@vhdl.org.   + + + + \ No newline at end of file diff --git a/docs/std.env.rst b/docs/std.env.rst new file mode 100644 index 0000000..5aabd19 --- /dev/null +++ b/docs/std.env.rst @@ -0,0 +1,4 @@ +std.env +####### + + diff --git a/docs/std.standard.rst b/docs/std.standard.rst new file mode 100644 index 0000000..39ec1d9 --- /dev/null +++ b/docs/std.standard.rst @@ -0,0 +1,4 @@ +std.standard +############ + + diff --git a/docs/std.textio.rst b/docs/std.textio.rst new file mode 100644 index 0000000..472c2d2 --- /dev/null +++ b/docs/std.textio.rst @@ -0,0 +1,4 @@ +std.textio +########## + + diff --git a/docs/std_logic_1164_additions.rst b/docs/std_logic_1164_additions.rst new file mode 100644 index 0000000..bea8713 --- /dev/null +++ b/docs/std_logic_1164_additions.rst @@ -0,0 +1,77 @@ + +Additions to package ieee.std_logic_1164 + + + + + + + + + + + + + + + +

+ std_logic_1164_additions.vhdl -- Additions to the package "ieee.std_logic_1164". This package now includes what used to be in "std_logic_textio", so it must be commented out. Otherwise it will +conflict with the new functions (which are much more forgiving). +

+

+ Usage model:
+ use ieee.std_logic_1164.all;
+ -- use ieee.std_logic_textio.all; -- Comment out, included in "_additions".
+ use ieee_proposed.std_logic_1164_additions.all; +

+ Dependencies: ieee.std_logic_1164; +

+

+ Note: The contents of the "std_logic_textio" package have now been + included in the "std_logic_1164" package, and an EMPTY "std_logic_textio" + package is provided in the new release. +

+
    New funcitons defined in this package: +
  • Short had aliases:
      +
    • to_bv - calls "to_BitVector" +
    • to_slv - calls "to_StdLogicVector" +
    • to_sulv - calls "to_stdULogicVector" +
    +
  • Long hand aliases:
      +
    • to_bit_vector - calls "to_BitVector" +
    • to_std_logic_vector - calls "to_StdLogicVector" +
    • to_std_ulogic_vector - calls "to_StdULogicVector" +
    +
  • _reduce functions (and_reduce, nand_reduce, or_reduce ...) are defined + These functions reduce a std_logic_vector (or ulogic) to a single bit. + In vhdl-2008 these will be unary "or", example "or "11011" = '1'" +
  • "vector" and "std_ulogic" operations are defined. These will perform a + boolean operation of a vector.
    Example:
    + "1" xor "1010" = "0101"; +
  • "\??\" function is defined for "std_ulogic" ("??" operator is release) + if (\??\('1')) then -- will return a "true" +
  • READ and WRITE procedures for "std_logic_vector", "std_ulogic_vector" + and "std_ulogic" are defined. +
  • HREAD and HWRITE (Hex read and write) for std_logic_vector + and std_ulogic_vector. These are more "forgiving" than the ones + originally from "std_logic_textio" +
  • OREAD and OWRITE (octal read and write) for std_logic_vector + and std_ulogic_vector. These are more "forgiving" than the ones + originally from "std_logic_textio" +
  • BREAD and BWRITE (binary read and write, same as "READ" and "WRITE" for + std_logic_vector and std_ulogic_vector. +
  • to_string function - Converts a "std_ulogic", "std_logic_vector" or + "std_ulogic_vector" types into a string.
    + Example:
    + assert (slv = "101") report "result was " & to_string(slv) severity note; +
  • to_hstring and to_ostring function (std_(u)logic_vector to hex or octal + string) +
+ +Please send feedback to David W. Bishop +dbishop@vhdl.org.   + + + + diff --git a/docs/std_textio_additions.rst b/docs/std_textio_additions.rst new file mode 100644 index 0000000..b106bf7 --- /dev/null +++ b/docs/std_textio_additions.rst @@ -0,0 +1,44 @@ + +Additions to package textio + + + + + + + + + + + + + + + +

+ standard_textio_additions.vhdl -- Additions to the package "std.textio" +

+

+ Use model:
+ use ieee_proposed.standard_textio_additions.all; +

+ Dependencies:
+ use std.textio;
use ieee_proposed.standard_additions; +

+
    +
  • tee - Echos the string to BOTH the file and the screen +
  • SREAD and SWRITE - String read and write routines
    (so you no longer + need to do write (L, string'("ABCEDFG")); +
  • HREAD and HWRITE (Hex read and write) for bit_vector +
  • OREAD and OWRITE (octal read and write) for bit_vector +
  • BREAD and BWRITE (binary read and write, same as "READ" and "WRITE" for + bit_vector +
  • justify - Justify a string left or right with a width.
    Example:
    + justify ("ABCD", left, 6); will result in "ABCD  " +
+Please send feedback to David W. Bishop +dbishop@vhdl.org.   + + + + \ No newline at end of file diff --git a/docs/synopsys.rst b/docs/synopsys.rst new file mode 100644 index 0000000..34ab670 --- /dev/null +++ b/docs/synopsys.rst @@ -0,0 +1,46 @@ +Synopsys +######## + +Tested with Synopsys 2006.06 sp4, you may be able to use earlier versions, +but if you do make sure that you are using the "Presto" compiler. + +To load, The easiest way is to add the following lines into your compile script +(You need only load the packages you need): + +.. code-block:: tcl + + define_design_lib ieee_proposed -path ./ieee_proposed + analyze -w ieee_proposed -f vhdl standard_additions_c.vhdl + analyze -w ieee_proposed -f vhdl std_logic_1164_additions.vhdl + analyze -w ieee_proposed -f vhdl numeric_std_additions.vhdl + analyze -w ieee_proposed -f vhdl numeric_std_unsigned_c.vhdl + analyze -w ieee_proposed -f vhdl math_utility_pkg.vhdl + analyze -w ieee_proposed -f vhdl fixed_pkg_c.vhdl + analyze -w ieee_proposed -f vhdl float_pkg_c.vhdl + # analyze -w work -f vhdl float_synth.vhdl + +Included in this ZIP file are the following packages (only include the ones you need): +
    library ieee_proposed; +
  • use ieee_proposed.standard_additions.all; -- Additions to packages standard.std +
  • use ieee_proposed.std_logic_1164_additions.all; -- Additions to std_logic_1164 +
  • use ieee_proposed.numeric_std_additions.all; -- Additions to numeric_std +
  • use ieee_proposed.numeric_std_unsigned.all; -- Package to do unsigned math with std_logic_vectors, similar to the (sic) ieee.std_logic_unsigned package. +
  • use ieee_proposed.math_utiliti_pkg.all; -- Types for the fixed and float packages +
  • use ieee_proposed.fixed_pkg.all; -- Fixed point package +
  • use ieee_proposed.float_pkg.all; -- Floating point package +
+The "README" file in the ZIP file will give you a list of the new functions. + +See the README for an explination of the new functions in these packages. +You will also want to look at the +Fixed point docuementation and the +Floating point docuementation. + + +.. NOTE:: + + * Synopsys doesn't accept the 1076.6 "-- rtl_synthesis off" metacomment. I placed "-- pragma synthesis_off" metacomments around these.   + * When Synopsys sees fixed_pkg'instance_name it dies on elaboration. + Replaced with "fixed_pkg" (and "float_pkg") where necessary. + * Same problem with "integer'image" and "real'image" - commented out. + * I had to replace the "match_logic_table" and "no_match_logic_table" with a logical equivilent. This was done in "std_logic_1164_additions" and in "fixed_pkg_c". diff --git a/docs/synplicity.rst b/docs/synplicity.rst new file mode 100644 index 0000000..74f724c --- /dev/null +++ b/docs/synplicity.rst @@ -0,0 +1,29 @@ +Synplify +######## + +Tested with Synplify 2009.06 + +I tried the new "VHDL 2008 (beta)" VHDL option in this tool. There were +major issues with function overloading, so don't use it. Instead, include +the VHDL-93 package versions. They all work find in this tool (no +modification needed). + +To load, The easiest way is to add the following lines into your project file +(You need only load the packages you need): + +.. code-block:: tcl + + add_file -vhdl -lib ieee_proposed "standard_additions_c.vhdl" + add_file -vhdl -lib ieee_proposed "std_logic_1164_additions.vhdl" + add_file -vhdl -lib ieee_proposed "numeric_std_additions.vhdl" + add_file -vhdl -lib ieee_proposed "numeric_std_unsigned_c.vhdl" + add_file -vhdl -lib ieee_proposed "math_utility_pkg.vhdl" + add_file -vhdl -lib ieee_proposed "fixed_pkg_c.vhdl" + add_file -vhdl -lib ieee_proposed "float_pkg_c.vhdl" + +The "README" file in the ZIP file will give you a list of the new functions. + +See the README for an explination of the new functions in these packages. +You will also want to look at the +Fixed point docuementation and the +Floating point docuementation. diff --git a/docs/tools.rst b/docs/tools.rst new file mode 100644 index 0000000..3d9e853 --- /dev/null +++ b/docs/tools.rst @@ -0,0 +1,30 @@ +Tool Specific Patches +##################### + + * :doc:`altera ` + * :doc:`cadence_ncvhdl ` + * :doc:`cadence_rc ` + * :doc:`leonardo ` + * :doc:`modelsim ` + * :doc:`modeltech ` + * :doc:`synopsys ` + * :doc:`synplicity ` + * :doc:`vcs ` + * :doc:`xilinx ` + * :doc:`xilinx_11 ` + + +.. toctree:: + :hidden: + + altera + cadence_ncvhdl + cadence_rc + leonardo + modelsim + modeltech + synopsys + synplicity + vcs + xilinx + xilinx_11 diff --git a/docs/vcs.rst b/docs/vcs.rst new file mode 100644 index 0000000..ec44898 --- /dev/null +++ b/docs/vcs.rst @@ -0,0 +1,14 @@ +VCS +### + +Tested with VCS C-2009.06 + +Textio issues: +VCS reports time with capital letters. So instead of "5 ns" you will get +"5 NS". It also doesn't know what an NBSP is (it's in the spec, but not in +VCS). 'instance_name works, but you don't get a seperator at the end. +(not reported). +The Textio "NBSP" does not appear to be recognized by VCS. (not reported) + +This version does not seem to like the floating point packages, however +previous versions did. diff --git a/docs/vhdl.rst b/docs/vhdl.rst new file mode 100644 index 0000000..c390cfe --- /dev/null +++ b/docs/vhdl.rst @@ -0,0 +1,58 @@ + +Fixed and Floating point support page + + + + + + + + + + + + + + + + +

+Fixed and Floating point support page

+ + + +

+The floating point packages were designed to be 100% +IEEE 754 compatible.   +For synthesis, this just isn't practical.   +I recommend that you that you go into the top of "float_pkg" and change the constants as follows:

+    constant float_exponent_width : NATURAL    := 8;
+    constant float_fraction_width : NATURAL    := 15;  -- 16 bits of precision
+    constant float_round_style    : round_type := round_zero; -- disable rounding
+    constant float_denormalize    : BOOLEAN    := false; -- no denormal numbers
+    constant float_check_error    : BOOLEAN    := false; -- NO NAN and overflow checks
+    constant float_guard_bits     : NATURAL    := 0; -- no guard bits
+In your source code, you should use this type:
+  begin
+    signal float1 : float (float_exponent_width downto -float_fraction_width);
+
+ + +

+

+If you are an EDA vendor, and would like to test your tool against these packages, please download the "modeltech.zip" +(which has the fewest changes in it) and try it aginst your syntheis/simulation +tool. If you have any issues please drop me an e-mail. +

+

+The NEXT step is a Verilog package. Interested? +

+

+Questions or comments? Please e-mail me. +dbishop"at"vhdl.org + + + + diff --git a/docs/xilinx.rst b/docs/xilinx.rst new file mode 100644 index 0000000..642cead --- /dev/null +++ b/docs/xilinx.rst @@ -0,0 +1,33 @@ +Xilinx ISE +########## + +Tested with Xilinx M9.1i sp1 + +Go through "new project" and add the files to the project. +Go to the "Source Libraries" tab under "Sources" +Click on a blank area of that window, Select "New Source" +Select "VHDL Library", enter the name "ieee_proposed" and hit "Finish". +Select "math_utility_pkg.vhdl", "fixed_pkg_c.vhdl", and "float_pkg_c.vhdl" +one at a time and move them into "ieee_proposed" library. + +Click on "Synthesis" and select "Run". + + +Things Xilinx m9.1i didn't like about these packages: +1) Didn't like the "alias" statements on functions and type. Had to comment +these out or replace them with subtypes. +2) 'instance_name - Doesn't like this attribute, replace with package name. +3) "to_stdlogicvector(to_suv(arg))" shows as a type conversion error, replace +with casting "std_logic_vector()" +4) "to_stdulogicvector(arg)" shows as a type conversion error, replace with +casting "std_ulogic_vector()" + +After fixing everything, it gave me the error: +INTERNAL_ERROR:Xst:cmain.c:3111:1.8.6.1 - To resolve this error, please +consult the Answers Database and other online resources at +http://support.xilinx.com + +Which according to Xilinx has to do with the loops in my synthesis testcase, +and not the packages. This is a "use at your own risk" one I guess. I would +recommend Synplicity, which seems to work much better. Xilinx has said that +they plan to fix this problem in version 9.2. diff --git a/docs/xilinx_11.rst b/docs/xilinx_11.rst new file mode 100644 index 0000000..e16d16d --- /dev/null +++ b/docs/xilinx_11.rst @@ -0,0 +1,25 @@ +Xilinx ISE +########## + +Tested with Xilinx M11.2i + +Go through "new project" and add the files to the project. +When the "Adding Source files..." windows comes up, change the library +for "fixed_float_types.vhdl", "fixed_pkg_c.vhdl" and "float_pkg_c.vhdl" to +"ieee_porposed" + +Click on "Synthesis" and select "Run". + +I had to really fight to get these packages to synthesize in this tool. I +could not check everything, so "use at your own risk". For a real Xilinx +project I would use still Synplicity or Leonardo. However, I was able to +get both my fixed and floating point testcases (with some modification) +to place and route. This is a major improvement over M9.1i + +Things Xilinx m11.1i didn't like about these packages: +1) 'instance_name showed as a syntax error, replace with package name +2) "to_stdlogicvector(to_suv(arg))" shows as a type conversion error, replace +with casting "std_logic_vector()" +3) Did not like any of the fixed point division routines, +had to comment them out. +4) Had to comment out the "?=" routines, XST could not deal with that syntax. diff --git a/readthedocs.yml b/readthedocs.yml new file mode 100644 index 0000000..e8d6ad6 --- /dev/null +++ b/readthedocs.yml @@ -0,0 +1,5 @@ +formats: + - pdf +requirements_file: requirements.txt +python: + version: 3 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..ef3f026 --- /dev/null +++ b/requirements.txt @@ -0,0 +1 @@ +# Requirements file for Python used by PIP