From 63925c8de8d3171e6b258796e4d167524691490a Mon Sep 17 00:00:00 2001
From: gingold <gingold@b72b5c32-5f01-0410-b925-b5c7b92870f7>
Date: Sun, 6 Aug 2006 06:45:40 +0000
Subject: bugs fixed
---
doc/ghdl.1 | 108 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
doc/ghdl.texi | 75 +++++++++++++++++++++++++++++-----------
2 files changed, 163 insertions(+), 20 deletions(-)
create mode 100644 doc/ghdl.1
(limited to 'doc')
diff --git a/doc/ghdl.1 b/doc/ghdl.1
new file mode 100644
index 000000000..d65bf68ad
--- /dev/null
+++ b/doc/ghdl.1
@@ -0,0 +1,108 @@
+.\" Hey, EMACS: -*- nroff -*-
+.\" First parameter, NAME, should be all caps
+.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
+.\" other parameters are allowed: see man(7), man(1)
+.\" Please adjust this date whenever revising the manpage.
+.\"
+.\" Some roff macros, for reference:
+.\" .nh disable hyphenation
+.\" .hy enable hyphenation
+.\" .ad l left justify
+.\" .ad b justify to both left and right margins
+.\" .nf disable filling
+.\" .fi enable filling
+.\" .br insert line break
+.\" .sp <n> insert n+1 empty lines
+.\" for manpage-specific macros, see man(7)
+.TH "GHDL" "1" "Jun 24, 2006" "" ""
+.SH "NAME"
+ghdl \- VHDL compiler/simulator
+.SH "SYNOPSIS"
+.B ghdl
+.RI [ command ] " " [ options ] " files" ...
+.br
+.SH "DESCRIPTION"
+This manual page documents briefly the
+.B ghdl
+command.
+This manual page was written for user of man, but is not as complete as the
+reference documentation.
+.PP
+Instead, users should read the GHDL texinfo manual
+.SH "OPTIONS"
+This program follows the usual GNU command line syntax, with long
+options starting with two dashes (`\-').
+A summary of the main modes and options is included below.
+For a complete description, refer to the GHDL texinfo manual.
+.PP
+Basic commands:
+.TP
+.B \-a
+Analysis, i.e. \fIghdl \-a file.vhdl\fP
+.TP
+.B \-e
+Elabortation, i.e. \fIghdl \-e unit_name\fP
+.TP
+.B \-r
+Run: run the simulation, i.e. \fIghdl \-r unit_name\fP
+.TP
+.B \-s
+Syntax\-check, i.e. \fIghdl \-s file.vhdl\fP
+.TP
+.B \-\-clean
+Clean: remove generated files, i.e. \fIghdl \-\-clean\fP
+.TP
+.B \-h, \-\-help
+Help, i.e. \fIghdl \-\-help\fP
+.TP
+.B \-\-version
+Version, i.e. \fIghdl \-\-version\fP
+.PP
+Basic options:
+.TP
+.B \-\-work=NAME
+Name of the WORK library, i.e. \fI ghdl \-a \-\-work=foo foo.vhdl\fP
+.TP
+.B \-\-std=STD
+Which VHDL standard (87|93|93c|00|02), i.e. \fIghdl \-a \-\-std=87 old.vhdl\fP
+.TP
+.B \-\-ieee=VER
+Which IEEE library (none|standard|synopsys|mentor), i.e. \fIghdl \-a \-\-ieee=synopsys broken.vhdl\fP
+.TP
+.B \-\-no\-vital\-checks
+Disable VITAL restriction checking, i.e. \fIghdl \-a \-\-no\-vital\-checks unsupported_vital.vhdl\fP
+.PP
+There are many more modes and options;
+please consult the documentation.
+.PP
+Executables created by GHDL have addition simulation options. The
+most important ones are listed below:
+.TP
+.B \-\-help
+Show options for simulation and execution.
+.TP
+.B \-\-assert\-level=LEVEL
+Assert level at which to stop simulation (none|note|warning|error|failure), i.e. \fI./touchy_design \-\-assert\-level=note\fB
+.TP
+.B \-\-stop\-time=TIME
+Stop simuation after TIME, i.e. \fI./design \-\-stop\-time=50ns
+.TP
+.B \-\-vcd=FILENAME
+Dump VCD to FILENAME (a waveform dump, viewable with\-\-for instance\-\-\fBgtkwave\fP), i.e. \fI./design \-\-vcd=design.vcd
+.TP
+.B \-\-sdf=[TYPE=]PATH=FILENAME
+Back annotate SDF onto design using TYPE (min|typ|max), instance PATH, and SDF file FILENAME, i.e. \fI./sdf_design \-\-sdf=typ=top/inst=inst.sdf\fP
+
+.SH "SEE ALSO"
+.TP
+.B gtkwave (1)
+.PP
+.br
+The texinfo manual fully documents GHDL. You may also browse it at
+\fB<http://ghdl.free.fr/ghdl/index.html>\fP.
+.SH "AUTHOR"
+This manual page was written by Wesley J. Landaker
+<wjl@icecavern.net>, for the Debian project (but may be used by
+others). It is released under the same terms as GHDL, i.e. the GNU
+General Public License. It was modified by Tristan Gingold to include
+it in the GHDL sources.
diff --git a/doc/ghdl.texi b/doc/ghdl.texi
index e704221c9..e83a0ac55 100644
--- a/doc/ghdl.texi
+++ b/doc/ghdl.texi
@@ -11,7 +11,7 @@
@titlepage
@title GHDL guide
@subtitle GHDL, a VHDL compiler
-@subtitle For GHDL version 0.22 (Sokcho edition)
+@subtitle For GHDL version 0.25 (Sokcho edition)
@author Tristan Gingold
@c The following two commands start the copyright page.
@page
@@ -163,10 +163,14 @@ or @code{C++}. Therefore, the compiled code should be faster and
the analysis time should be shorter than with a compiler using an
intermediary language.
+The Windows(TM) version of @code{GHDL} is not based on @code{GCC} but on
+an internal code generator.
+
The current version of @code{GHDL} does not contain any graphical
viewer: you cannot see signal waves. You can still check with a test
bench. The current version can produce a @code{VCD} file which can be
-viewed with a wave viewer.
+viewed with a wave viewer, as well as @code{ghw} files to be viewed by
+@samp{gtkwave}.
@code{GHDL} aims at implementing @code{VHDL} as defined by IEEE 1076.
It supports most of the 1987 standard and most features added by the
@@ -217,9 +221,10 @@ file in VHDL terms.
@smallexample
$ ghdl -a hello.vhdl
@end smallexample
-This command generates a file @file{hello.o}, which is the object file
-corresponding to your VHDL program. This command also creates or updates
-a file @file{work-obj93.cf}, which describes the library @samp{work}.
+This command creates or updates a file @file{work-obj93.cf}, which
+describes the library @samp{work}. On GNU/Linux, this command generates a
+file @file{hello.o}, which is the object file corresponding to your
+VHDL program. The object file is not created on Windows.
Then, you have to build an executable file.
@smallexample
@@ -229,7 +234,8 @@ The @samp{-e} option means @dfn{elaborate}. With this option, @code{GHDL}
creates code in order to elaborate a design, with the @samp{hello}
entity at the top of the hierarchy.
-The result is an executable program called @file{hello} which can be run:
+On GNU/Linux, the result is an executable program called @file{hello}
+which can be run:
@smallexample
$ ghdl -r hello_world
@end smallexample
@@ -238,7 +244,12 @@ or directly:
$ ./hello_world
@end smallexample
-and which should display:
+On Windows, no file is created. The simulation is launched using this command:
+@smallexample
+> ghdl -r hello_world
+@end smallexample
+
+The result of the simulation appears on the screen:
@smallexample
Hello world!
@end smallexample
@@ -558,10 +569,13 @@ $ ghdl -a -g my_design.vhdl
$ ghdl -e [@var{options}] @var{primary_unit} [@var{secondary_unit}]
@end smallexample
-The @dfn{elaboration} command creates an executable containing the
-code of the @code{VHDL} sources, the elaboration code and simulation
-code to execute a design hiearachy. The elaboration command is selected
-with @var{-e} switch, and must be followed by either:
+On GNU/Linux the @dfn{elaboration} command creates an executable
+containing the code of the @code{VHDL} sources, the elaboration code
+and simulation code to execute a design hiearachy. On Windows this
+command elaborates the design but does not generate anything.
+
+The elaboration command is selected with @var{-e} switch, and must be
+followed by either:
@itemize @bullet
@item a name of a configuration unit
@@ -576,9 +590,10 @@ option, as described in @ref{GHDL options}.
@xref{Top entity}, for the restrictions on the root design of a
hierarchy.
-The file name of the executable is the name of the primary unit, or for
-the later case, the concatenation of the name of the primary unit, a
-dash, and the name of the secondary unit (or architecture).
+On GNU/Linux the file name of the executable is the name of the
+primary unit, or for the later case, the concatenation of the name of
+the primary unit, a dash, and the name of the secondary unit (or
+architecture). On Windows there is no executable generated.
The @option{-o} followed by a file name can override the default
executable file name.
@@ -603,9 +618,10 @@ Run (or simulate) an elaborated design hierarchy.
$ ghdl -r @var{primary_unit} [@var{secondary_unit}] [@var{simulation_options}]
@end smallexample
-The arguments are the same as the @xref{Elaboration command}. This command
-simply build the filename of the executable and execute it. You may also
-directly execute the program.
+The arguments are the same as the @xref{Elaboration command}.
+
+On GNU/Linux this command simply build the filename of the executable
+and execute it. You may also directly execute the program.
This command exists for three reasons:
@itemize @bullet{}
@@ -614,10 +630,12 @@ You don't have to create the executable program name.
@item
It is coherent with the @samp{-a} and @samp{-e} commands.
@item
-It will work with future implementations, where the code is generated in
+It works with the Windows implementation, where the code is generated in
memory.
@end itemize
+On Windows this command elaborate and launch the simulation.
+
@xref{Simulation and run time}, for details on options.
@node Elaborate and run command, Bind command, Run command, Building commands
@@ -644,6 +662,8 @@ Bind a design unit and prepare the link step.
$ ghdl --bind [@var{options}] @var{primary_unit} [@var{secondary_unit}]
@end smallexample
+This command is only available on GNU/Linux.
+
This performs only the first stage of the elaboration command; the list
of objects files is created but the executable is not built. This
command should be used only when the main entry point is not ghdl.
@@ -672,6 +692,8 @@ Disp files which will be linked.
$ ghdl --list-link @var{primary_unit} [@var{secondary_unit}]
@end smallexample
+This command is only available on GNU/Linux.
+
This command may be used only after a bind command. GHDL displays all
the files which will be linked to create an executable. This command is
intended to add object files in a link of an foreign program.
@@ -683,7 +705,7 @@ intended to add object files in a link of an foreign program.
Analyze files but do not generate code.
@smallexample
-$ ghdl -a [@var{options}] @var{files}
+$ ghdl -s [@var{options}] @var{files}
@end smallexample
This command may be used to check the syntax of files. It does not update
@@ -695,13 +717,19 @@ the library.
@cindex @option{-c} command
Analyze files and elaborate in the same time.
+On GNU/Linux:
@smallexample
$ ghdl -c [@var{options}] @var{file}@dots{} -e @var{primary_unit} [@var{secondary_unit}]
@end smallexample
+On Windows:
+@smallexample
+$ ghdl -c [@var{options}] @var{file}@dots{} -r @var{primary_unit} [@var{secondary_unit}]
+@end smallexample
+
This command combines analyze and elaboration: @var{file}s are analyzed and
the unit is then elaborated. However, code is only generated during the
-elaboration.
+elaboration. On Windows the simulation is launched.
To be more precise, the files are first parsed, and then the elaboration
drives the analysis. Therefore, there is no analysis order, and you don't
@@ -878,6 +906,9 @@ displays the commands executed.
@node Passing options to other programs, GHDL warnings, GHDL options, Invoking GHDL
@comment node-name, next, previous, up
@section Passing options to other programs
+
+These options are only available on GNU/Linux.
+
For many commands, @code{GHDL} acts as a driver: it invokes programs to perform
the command. You can pass arbritrary options to these programs.
@@ -1671,6 +1702,8 @@ Display a short description of the options accepted by the run time library.
@section Debugging VHDL programs
@cindex debugging
@cindex @code{__ghdl_fatal}
+Debugging VHDL programs usign @code{GDB} is possible only on GNU/Linux systems.
+
@code{GDB} is a general purpose debugger for programs compiled by @code{GCC}.
Currently, there is no VHDL support for @code{GDB}. It may be difficult
to inspect variables or signals in @code{GDB}, however, @code{GDB} is
@@ -1949,6 +1982,8 @@ web, but they cannot be included in GHDL.
@cindex foreign
@cindex VHPI
@cindex VHPIDIRECT
+Interfacing with foreign languages is possible only on GNU/Linux systems.
+
You can define a subprogram in a foreign language (such as @code{C} or
@code{Ada}) and import it in a VHDL design.
--
cgit v1.2.3