Guidelines for the Development of a
VHDL-AMS Model Library
Version 2.0
Date:
June 11, 2008
VHDL-AMS Modeling Guidelines
Summary
The available proposal summarizes rules that should be considered in order to establish
consistent VHDL-AMS models for modeling and simulation of automotive systems. It is intended to assure that the models are running inside different VHDL-AMS simulators and
models of different origin can be combined. The draft proposal outlines the results of discussions of the Working Group “Simulation of Mixed Systems with VHDL-AMS” (VDA/FAT AK
30).
In the following, rules are specified that shall help to fulfill these expectations. It is distinguished between requirements and recommendations. A rule that is specified as a requirement has to be kept without restrictions. This is necessary to assure that the documentation can be generated automatically. A recommendation should be mentioned in order to
unify the layout of the models. This helps to make the models better readable. An example
of a VHDL-AMS model that considers rules is given in appendix G.
Furthermore, a proposal is represented how to administrate the model library in section 4.
Modification History
Version
Date
Comment
0.1
0.2
April 15, 2004
April 30, 2004
1.0
June 3, 2004
1.1
August 25, 2004
1.2
2.0
September 1, 2004
June 11, 2008
First German version
Revised version after discussion in the group
„Modeling Guidelines“ of VDA/FAT-AK 30
on April 20, 2004
Revised version after discussion in the Working Group
VDA/FAT AK30 on May 24, 2004
English translation and some revisions with respect to
experiences concerning model generation
Revision of version 1.1
Update with respect to new documentation guidelines
Comments to
Joachim Haase
E-Mail:
Version 2.0
joachim.haase@eas.iis.fraunhofer.de
-2-
June 11, 2008
VHDL-AMS Modeling Guidelines
1 Objectives
It is intended to establish a library of VHDL-AMS models that describe aspects of automotive
systems. To guarantee a unified layout of the library some guidelines that should be considered are summarized in the following.
These guidelines were influenced by
•
•
•
•
•
commitments that were worked out by the working group AK 30 “Modeling and simulation with VHDL-AMS” (ref. to appendices A, B, and C),
documents that settle VHDL modeling [1-3],
the SAE standard „Model Specification Process Standard“ [4],
IEEE standards or standard proposals [5-6],
special problems concerning the design of models discussed in the working group
AK 30 (current limitations of tools etc.)
The aim of this document is to support the development of VHDL-AMS models that can be
combined and correspond to each other easier.
2 Fundamentals of the Model Development
2.1 Structure of the Model Library
R2.1-1 (Requirement): The models are compiled into logical libraries. The characteristics of
the libraries are explained in table 2.1-1.
Table 2.1-1: Identifiers of the logical libraries
Logical library
FUNDAMENTALS_VDA
SPICE2VHD
SPICE2VHD_DEVICES
AUTOMOTIVE_VDA
MEGMA
MODELICA_TRANSLATIONAL
MODELICA_ROTATIONAL
Comments
Basic models
Spice-like models
Parameterized Spice-like models
Special models for automotive applications
Models of the MSR group [11]
Modelica equivalent VHDL-AMS models [12]
Modelica equivalent VHDL-AMS models [12]
The source code of the models, test benches and other appropriate files are stored in a special structure of the file system that is given in appendix A. A subdivision of the libraries for
administration purposes is introduced in this way.
2.2 Modeling Principles
R2.2-1 (Requirement): The values of branch through and across quantites of conservative
systems are measured in SI units with respect to the corresponding nature declaration given
in [6].
Version 2.0
-3-
June 11, 2008
VHDL-AMS Modeling Guidelines
In the case of nonconservative systems, a used unit has to be added as a comment after the
port quantity declaration if it makes sense (see section 3.2). To avoid inconsistencies the
rules summarized in table 2.2-1 must be considered.
Table 2.2-1: Modeling principles to avoid inconsistencies
Nature/Port
THERMAL
Comments
An external heat flow source is directed to the corresponding node. The across quantity (temperature) is measured
in Kelvin.
An external force is modeled as a through source directed
to the corresponding node.
Optical networks for data transmission are modeled by
nonconservative systems. The quantity port represents the
optical power that is measured in W.
Digital signal ports belong to the type STD_LOGIC of the
IEEE package STD_LOGIC_1164. The index range of
array should be descending (… downto …).
TRANSLATIONAL
TRANSLATIONAL_VELOCITY
Optical net
Digital signals
Example
y
F
x
F
x
x
z
Figure 1: Translational system and network model (FFeder = k.x)
Note
It should be mentioned that inconsistencies can occur if models of different provenience shall
be combined [8]. This especially concerns the common usage of MAST models and VHDLAMS models that are established with respect to rule 2.2-1.
2.3 Temporary Regulation
When the library development started the IEEE_ENV package MATERIAL_CONSTANTS [6]
that provides the constant AMBIENT_TEMPERATURE was not standardized and available
in all commercial simulators. That is why special constants were defined to characterize the
global temperatures. This concerns in the package SPICE_FUNDAMENTAL_CONSTANTS
of the SPICE2VHD library the default value of instance temperatures
(SPICE_TEMPERATURE) and the global nominal temperature (SPICE_TNOM) and the constants AUTOMOTIVE_VDA_TEMP and AUTOMOTIVE_VDA_TNOM resp. of the package
AUTOMOTIVE_VDA_FUNDAMENTALS_CONSTANTS.
Version 2.0
-4-
June 11, 2008
VHDL-AMS Modeling Guidelines
3 Rules for the Development of VHDL-AMS Models
3.1 Organization of Models and Naming of Identifiers
R3.1-1 (Requirement): The entity declaration should be organized in the following way:
entity ....
generic (
…
port (
…
begin
-- assert statements to check the scope of application of parameters
end entity entity_name;
Each declaration of a generic parameter or a port has to be done in a separate line. It should
be checked using assert statements whether the current values of parameters are in the
scope of application or not. Default values should be assigned to parameters.
Example
entity RESISTOR is
generic (
R : REAL := 1.0 -- resistance [Ohm], MIN: 0.0, MAX: INF
);
port (
terminal P : ELECTRICAL; -- plus terminal
terminal N : ELECTRICAL -- minus terminal
);
begin
assert R > 0.0
report “ERROR: Value R > 0.0 required.”
severity error;
end entity RESISTOR;
R3.1-2 (Recommendation): The declarational part of each architecture should be organized
in the following way:
•
•
•
•
•
•
•
•
At first: Declaration of local functions and procedures (Requirement)
Declaration of types
Declaration of constants
Declaration of signals
Declaration of internal nodes (terminal declaration)
Declaration of branches (branch quantity declaration)
Declaration of free quantities (free quantity declaration)
Declaration of AC sources (spectrum quantity declaration)
The real-valued signals have to be initialized in their declaration (Requirement). The statements of an architecture should observe the following order:
•
•
•
concurrent statements (without concurrent BREAK statement)
simultaneous statements
break statements
Version 2.0
-5-
June 11, 2008
VHDL-AMS Modeling Guidelines
Example
library IEEE;
use IEEE.MATH_REAL.all;
architecture BASIC of DIODE is
function LIM_EXP (ARG: REAL) return REAL is
variable RESULT : REAL;
-- result of function
…
begin
if ARG >
…
return RESULT;
end function LIM_EXP;
quantity V across I through ANODE to CATHODE;
begin
I == IS*(LIM_EXP(V/VT)-1.0);
end architecture BASIC;
R3.1-3 (Recommendation): All reserved words in VHDL-AMS shall be written lower case.
User-defined identifiers shall be written upper case. Also identifiers of predefined packages
shall be written upper case.
Example
library IEEE;
use IEEE.MATH_REAL.all;
entity BENCH is end entity BENCH;
R3.1-4 (Recommendation): User-defined designations shall be meaningful. Constituent
parts of names shall be separated by underscores. Identifiers are chosen with respect to
their English meaning.
Example
PROGRAM_COUNTER
LEFT_DATA_BUS
R3.1-5 (Recommendation): Identifiers should be named in accordance with table 3.1-1 (see
appendix A). It should be avoided to use names that are reserved words in Verilog (see appendix D).
Version 2.0
-6-
June 11, 2008
VHDL-AMS Modeling Guidelines
Tabelle 3.1-1: Recommendation for naming conventions of identifiers
Object
entity
architecture
Rule for identifier
Example
If it makes sense, the name should end with QTRPF_VDA
_VDA
The following identifiers are recommended
BASIC
EXTENDED
PRECISION
SPECIAL
type, subtype
package
signal
quantity
terminal
plainest basic model
e. g. models that switch
between different parts
consideration of secondary
effects
other models that consider
special effects
User-defined types and subtypes should end DATA_TYP
with _TYP
INT_64_BIT_PKG
Identifiers of user-defined packages should package
…
end with _PKG
S_1
Identifiers should start in the case of
internal signals with S_ ,
input signals with S_IN_ ,
output signals with S_OUT_ .
Identifiers of free quantities should start in
the case of
General continuous waveforms with Q_ ,
nonconservative input ports with Q_IN_ ,
nonconservative output ports with Q_OUT_
Nature ELECTRICAL:
Identifiers should start with EL_
nature TRANSLATIONAL:
Identifiers should start with MT_
nature ROTATIONAL:
Identifiers should start with MR_
nature TRANSLATIONAL_VELOCITY:
Identifiers should start with MTV_
nature ROTATIONAL_VELOCITY:
Identifiers should start with MRV_
nature MAGNETIC:
Identifiers should start with MA_
nature THERMAL:
Identifiers should start with TH_
nature RADIANT (optisch):
Identifiers should start with OP_
is
Q_IN_1, Q_IN_2, ...
EL_1
MT_BEAM
MR_78
MTV_IN
MRV_VEHICLE
TH_1
Further recommendations
- hydraulic terminals: HY_
- pneumatic terminals: PN_
- acoustic terminals: AC_
Version 2.0
-7-
June 11, 2008
VHDL-AMS Modeling Guidelines
R3.1-6 (Recommendation): Design units should be stored in separate files. The file names
should be chosen in accordance with the following table [1].
Design unit
entity
and possibly associated architectures
architecture
package header
package body
Naming convention for file name
entityName.vhd
entityName-architectureName.vhd
packageName.vhd
packageName-body.vhd
3.2 Annotation
R3.2-1 (Requirement): The comments have to be in English. The code has to start and stop
with the disclaimers (see R3.2-2). The start disclaimer has to be followed by the introductionary comment. Other comments have to be placed ahead the concerning statement.
3.2.1 Disclaimer
R3.2-2 (Requirement): At the beginning of a VHDL-AMS model the first disclaimers given in
appendix B has to be included. It must be followed by the comment for the file header (see
Appendix C). The model description must end with the second disclaimer shown in Appendix
B.
Note
After the comment for the file header the introductionary comment must follow.
3.2.2 Introductionary Comment
R3.2-3 (Requirement): The introductionary comment starts with --/** end ends with --*/
Between start and end string the comments should follow the rules from Table 3.2-1.
Note
The comments are used to generate the model documentation automatically. Thus, the rules
should be applied carefully to avoid problems during the generation of the documentation.
Explanations are given in table 3.2-1.
Keywords to structure the comments start with a @ sign.
Each line must start with --that characterize a comment.
There are currently some known limitations of the generation tool. To avoid problems the
hints in Table 3.2-1 should be considered.
Version 2.0
-8-
June 11, 2008
VHDL-AMS Modeling Guidelines
Table 3.2-1: Introductionary Comment between --/** and --*/
Purpose
Title
Description
The first line of the comment is interpreted as title. It must
end with a point (.)
Example
-- SPICE-like Model of a Resistor.
Description
Note:
Avoid double quotes and points in the title.
After the title the description follows. It ends at the next
keyword that starts with an @.
The readability of the documentation can be improved by
using HTML tags;
<p> tag to describe a section:
<p> text </p>
<pre> tag to describe a code section
<pre> code </pre>
<table> tag to describe a table with
• <thead> tag to describe the header
o <tr> tag to describe a row
o <th> tag to describe a column in a row
• <tbody> tag to describe the body
- <tr> tag to describe a row
- <td> tag to describe a column in a row
Example
-- <p>The following context clause should
-- be included:</p>
@generic
-- <pre>
-- library IEEE;
-- use IEEE.MATH_REAL.all;
-- </pre>
After this keyword the description the identifier of generic
parameter and its description may follow. The unit of the
parameter must be included in brackets [ ]. For the abbreviation of units see Table 3.2-3.
Example
-- @generic
FBRAKE
Braking force [N]
Note
• The identifier has to be written in the same way as it is
written in the VHDL-AMS code.
• Restrictions of parameters should be explained using
passive concurrent assert statements in the entity
declaration.
Version 2.0
-9-
June 11, 2008
VHDL-AMS Modeling Guidelines
@port
After this keyword the description the identifier of a port
may follow.
Example
-- @port
EL_VCC
Electrical terminal
Notes
• The identifier has to be written in the same way as it is
written in the VHDL-AMS code of the model.
• Directions in and out should be added using lower
letters to describe signal and quantity ports.
• Avoid squared brackets [ ] in the description.
@test
The name of the file with the test.bench in the subdirectory
tb may follow (without .vhd extension).
Note
The structure of a model subdirectory is shown in Table
4.2-1.
Example
The model is saved in the file res.vhd in the subdirectory
src. The test-bench is saved in the corresponding subdirectory in bench_res.vhd. Thus include in res.vhd
@reference
-- @test bench_res
.The reference description should follow.
@author
Example
-- @reference Isermann, R.:
-Fahrdynamik-Regelung.
-Vieweg-Verlag, 2006.
The name(s) of the authors may follow.
Notes:
• The order of the keyword comments is arbitrary.
• There are special rules to comment package headers (see section 3.6).
• The units of parameters should be used in accordance with the tables 3.2-2 to 3.2-4. Units
that are derived from basic units should be composed using the multiplication sign “*“ or
the power sign “^” (compare [6]).
Examples
Usual notation:
Notation in the comments:
Version 2.0
Nm,
N*m,
m2
m^2
-10-
June 11, 2008
VHDL-AMS Modeling Guidelines
Table 3.2-2: Abbreviation of Units
Unit
Joule
Watt
Volt
Coulomb
Ohm
Weber
Tesla
Henry
radian
Newton
second
kilogram
candela
lumen
Kelvin
Pascal
Abbreviation (see [5])
J
W
V
C
Ohm
Wb
T
H
rad
N
s
kg
cd
lm
K
P
Table 3.2-3: Operators to Compose Units
Operator
Multiplication
Division
Exponentiation
Operator sign
*
/
^
3.2.3 Entity declararion
R3.2-4 (Requirement): Generic parameters should be declared in separate lines.
R3.2-5 (Requirement): Ports should be declared in separate lines.
Example
library EXAMPLE_ECAR;
library IEEE;
use IEEE.ELECTRICAL_SYSTEMS.all;
entity BATTERY is
generic (
SOC_0
: REAL := 0.71
);
port (
terminal EL
: ELECTRICAL;
quantity SOC : out REAL
);
begin
assert (SOC_0 > 0.0);
assert (SOC_0 <= 1.0);
end entity BATTERY;
Version 2.0
-11-
June 11, 2008
VHDL-AMS Modeling Guidelines
3.2.4 Annotation of Model Descriptions
R3.2-6 (Recommendation): Data objects should be described after their declaration.
Example
constant
VT : REAL := PHYS_K*AMBIENT_TEMPERATURE/PHYS_Q; -- temperature voltage
R3.2-7 (Recommendation): Comments shall immediately be followed by the concurrent,
sequential, and/or simultaneous statements they describe. Single concurrent, sequential,
and simultaneous statements (and their descriptive comments) shall be separated by two
blank lines. Groups of statements and declarations that belong together shall be separated
by one blank line
Example
-- Clock generator
CLOCK <= not CLOCK after 5 ns;
-- State Transition
process (CLOCK) is
begin
STATE <= NEW_STATE;
end process;
-- Decode the instruction
STATEMENT;
STATEMENT;
3.3 Error Messages
R3.3-1 (Requirement):The hints concerning the usage and design of error messages given
in table 3.3-1 have to be taken into account.
Table 3.3-1: Design of error messages (see also [2], p. 8)
Severity level
ERROR
WARNING
NOTE
Version 2.0
Comment
Serious error that allows the continuation of the simulation only in exceptional cases. Examples:
- Violation of time conditions
- Violation of the range of parameters
Error that can implicate an erroneous behavior of the
model. The simulation can be continued in general.
Examples:
- Exceed or undershoot of recommended limits
Important hint
-12-
June 11, 2008
VHDL-AMS Modeling Guidelines
Error messages can be arranged using the assert or report statement. The messages should
be constructed in the following way:
•
•
•
The message starts with the severity level in upper cases followed by a colon, e. g.
ERROR:
A short description of the problem follows. This should not exceed one line.
The full path name to the model using the attribute ´INSTANCE_NAME should be included in the error message if possible.
The severity levels FAILURE and ERROR cause in general the termination of the simulation.
Warnings and hints should be applied economically.
Error numbers are not used.
3.4 Hints to Layout Design of Models
R3.4-1 (Recommendation): VHDL-AMS source layout should consider the following rules:
•
•
•
•
•
•
•
Declarative regions and blocks of statements shall be intended by 2 spaces.
Lines shall not exceed 80 characters in length.
The TAB character shall not be used to indent. Only use the SPC character.
Named association shall be used preferable to positional association.
process statements and loop statements shall be labeled.
Arrays of digital signals shall be preferable declared in descending direction (range
downto).
Variable-width ports shall be constrainted using generics.
Example
entity EXAMPLE is
generic (N: NATURAL
-- number of elements in the array MIN: 0
);
port (S : out BIT_VECTOR (N downto 1) -- output of signal generator
);
end entity EXAMPLE;
•
No space shall preceed the signs “(“, “)“, “;“ and “,“. No space shall surround a single
quote or dot.
3.5 Limitations
R3.5-1 (Requirement): In accordance with the current coverage of the VHDL-AMS language
by the implementation of different EDA vendors the language constructs given in table 3.5-1
should be avoided.
Version 2.0
-13-
June 11, 2008
VHDL-AMS Modeling Guidelines
Table 3.5-1: Language constructs that should be avoided
VHDL-AMS Language constructs
configuration
two and multi-dimensional arrays
data objects of type access
data objects of type record
noise source
nature arrays
nature records
simultaneous case statement
simultaneous procedural statement
tolerance aspect
generate
wait for real_time_expression
Comment
see [5], section 3.3
The usage of the type COMPLEX declared in
the package MATH_COMPLEX of the IEEE
library is possible.
see [5], section 4.3.1.16
see [5], section 3.6.2.1
see [5], section 3.6.2.2
see [5], section 15.3
see [5], section 15.4
In many simulators the tolerance aspect is not
supported. From the language point of view in
some cases tolerance aspects may be required in simultaneous statements by the standard ([5], section 15.1). If a problem occurs
because of missing tolerance aspects VHDLAMS compiler directives should be modified.
Real expressions are allowed but not supported by all simulation engines.
Note:
A real number can be converted to a number
of type TIME by multiplication with (1 sec):
wait for real_expression*(1 sec);
The usage of the following language construct is subject to restrictions:
•
break:
The definition of initial conditions using the break statement should be avoided.
The requirements concerning tool dependent restrictions will be updated from time to time.
3.6 Documentation
A HTML documentation will be generated. This is possible if the requirements from section 3
are taken into account. The HTML document contains a link to the associated source code.
3.6.1 Entity Declaration
The following information will be documented if possible and necessary:
•
•
•
entity-Name
Symbol
Generic parameters with
Version 2.0
-14-
June 11, 2008
VHDL-AMS Modeling Guidelines
o
o
o
o
o
o
•
Ports
o
o
o
o
o
Identifier
Typ
Default-Wert
Unit
Description
Assertions (if report is available)
Kind of (signal | terminal | quantity)
Identifier
Nature or type
Mode (only for signal and quantity ports: in| out | inout)
Description
•
Description (see Table 3.2-1)
o Short description of functionality and limitations of the model
•
•
References
Libraries and design units/design entities that support the model
3.6.2 Architecture
The following information will be documented if possible and necessary
•
•
•
•
•
Name of the architecture
Title of the description
Description (see Table 3.2-1)
o Short description of functionality and limitations of the model.
References
Libraries and design units/design entities that support the model
If entity and architectures are stored in the same file the descriptions (sections 3.6.1 and
3.6.2) are combined in one document. This is usually applied.
3.6.3 Package
The following information will be documented if possible and necessary
•
•
•
•
•
Name of the package and title
Title of the description
Description (see Table 3.2-1)
o Short description of functionality
References
Libraries and design units/design entities that support the model
There special facilities to comment
• constants
• functions
that are declared in a package header (see Table 3.6-1).
Version 2.0
-15-
June 11, 2008
VHDL-AMS Modeling Guidelines
Table 3.6-1 Declaration of constants and functions in a package header declaration
Purpose
constant
Description
In front of a constant declaration add:
--/**
-- Headline that ends with.
-- Description
---*/
Example
--/**
-- Air density.
-- The value describes the air density.
--*/
constant AIR_DENSITY : REAL := 1.2;
function
In front of a function declaration should be included:
--/**
-- Headline that ends
-- Description
--- @arg Identifier1
-- @arg Identifier2
-- @return
---*/
with.
Description
Description
Description of return value
Example
--/**
-- MIN Function.
-- The function determines the minimum
-- of two INTEGER numbers.
--- @arg VALUE_1
First argument
-- @arg VALUE_2
Second argument
-- @return
Minimum of both values
--*/
function MIN (VALUE_1, VALUE_2 : INTEGER)
return INTEGER;
Version 2.0
-16-
June 11, 2008
VHDL-AMS Modeling Guidelines
4 Administration of the Model Library
4.1 Installation of the Library
The files that constitute the model libraries are stored in a SubVersion-Repository [9]. The
access to the files is password protected.
Table 4.1-1: WWW addresses of the library for development purposes
WWW address
http://projects.eas.iis.fraunhofer.de/vdalibs
http://svn.eas.iis.fraunhofer.de/view/vdalibs
http://svn.eas.iis.fraunhofer.de/vdalibs
http://projects.eas.iis.fraunhofer.de/vdalibs/
nightly/vdalibs/doc
Comment
Central access (Documentation, Subversion
Repository, Downloads)
Subversion Repository
with WWW Version Control
Subversion Repository
Documentation
The repository contains
•
•
•
Separate directories for each logical (FUNDAMENTALS_VDA, SPICE2VHD,
AUTOMOTIVE_VDA, … )
Each of these directories is structured again (see Appendix A)
At the lowest level the models are saved in accordance with Table 4.2-1
The administration of the accounts is done by the SVN repository administrator. The responsibility is appointed by the working group.
At the root level of the SVN repository there exists
•
a subdirectory libs that contains scripts and information concerning the compilation
of the libraries
4.2 Transfer of Models
For each model, a subdirectory named by the entity or package identifier has to be created.
All of these model subdirectories have the same structure. They consist of
•
•
•
•
src subdirectory that contains the source code of the model
symbol subdirectory that contains symbol information
doc subdirectory that contains the generated model documentation
tb subdirectory that contains testbenches
The model developer shall deliver
•
•
file <model>.vhd that contains the VHDL-AMS source code and follows the rules
given in this document
file <model>.png that contains the symbol information
Note
A proposal for a general symbol format [13] that will replace the png files if supported by the
EDA vendors.
Version 2.0
-17-
June 11, 2008
VHDL-AMS Modeling Guidelines
For verification, the following files have to be delivered
•
•
•
<bench>.vhd with a (simple) testbench that demonstrates the usage of the model
<bench>.jpg with results of testbench simulation
README file that contains
- summary files that have to be compiled to run the testbench (i. e. a list of logical
target library identifiers and appropriate files)
- Spice commands that specify simulation parameters (HMIN, HMAX, EPS, …)
- description of output nets
These files have to be integrated in the SVN respository as shown in table 4.2-1. This integration can be done by the SubVersion repository administrator or the model developer.
Table 4.2-1: Structure of a model subdirectory
Subdirectory
src
File
<model>.vhd
symbol
<model>.png
doc
doc
tb
<model>.xml
<model>.html
<bench>.vhd
tb/subdirectory
tb/doc
README
tb/doc
<bench>.jpg
Comment
VHDL-AMS source code. This file should follow
the rules of this document.
File with model symbol.
Preferable size: 100x100 Pixel
Generated XML file with model description
Generated HTML file with model description
Testbench for the model <model>.vhd. This file
should follow the rules of this document.
Tool-dependent testbenches. Subdirectory name
in accordance with appendix E
Hints how to run the testbench <bench>.vhd
(optional).
Simulation results (plot)
Tool-dependent versions of the source code and the testbench or additional material can be
stored in subdirectories of src and tb. The names of the subdirectories are chosen w.r.t. the
tools in accordance to appendix E.
At the root level there exists
•
a subdirectory libs
with a file vhdlfilelist_ordered
4.3 Organization of the Model Development Process
After verification of a model by the developer and a second person it will be made available
to the members of the working group AK 30. Afterwards, the following steps are carried out:
•
•
•
•
Modification proposals are sent to the model author.
The model author or the SubVersion repository administrator carry out modifications.
After request of the author, the working group decides whether the model can be
made available for general use.
General available versions of the model libraries will be updated from time to time.
Tool developers will be asked to make tool-dependent modifications.
Version 2.0
-18-
June 11, 2008
VHDL-AMS Modeling Guidelines
4.4 Corrections of Models of the General Library
Modification proposals of the general available library are collected by the working group. A
special mail address will be created for this purpose.
The working group decides about updates of the model libraries.
References
[1]
Bergeron, J.: Guidelines for Writing VHDL Models in a Team Environment.
Available: http://www.eda.org/misc/ModelingGuidelines.paper.ps
[2]
Creasey, R.; Coirault, R.: VHDL Modelling Guidelines. estec European Space Research and Technology Centre, Issue 1, September 1994.
Available: http://www.eda.org/misc/esa.model.guidelines/ModelGuide.ps
[3]
VHDL Modelling Guidelines. Simulation and Documentation Aspects.
Second Draft, 23 February 1997.
[4]
Model Specification Process Standard. Surface Vehicle Standard SAE J 2546.
February 2002. Informationen verfügbar über (Suchwort J2546):
Available: http://www.sae.org
[5]
IEEE Std. 1076.1: IEEE Standard VHDL Analog and Mixed-Signal Extensions.
Approved 15 November 2007.
Available (1999 version): http://www.designers-guide.com/Modeling/1076.1-1999.pdf
[6]
IEEE Std. 1076.1.1: Standard VHDL Analog and Mixed-Signal Extensions –
Packages for Multiple Energy Domain Support. Approved 5 April 2005.
[7]
Verilog-AMS Language Reference Manual: Analog & Mixed-Signal Extensions
to VerilogHDL, Version 2.2, November 2004. Accellera.
Available: http://www.designers-guide.com/VerilogAMS/VlogAMS-2.2-pub.pdf
[8]
Fedder, G.: Issues in MEMS Macromodeling. Proc. 2003 Int. Workshop on Behavioral
Modeling and Simulation BMAS, October 7-8, 2003, San Jose, pp. 64-89.
Available: http://www.bmas-conf.org/2003/papers/bmas03-fedder.pdf
[9]
Version Control System SubVersion
Available: http://subversion.tigris.org
[10]
SubVersion client TortoiseSVN
Available : http://tortoisesvn.tigris.org
[11]
Standardizaition of library blocks for graphical model exchange. Version 1.12.
Manufacturer Supplier Relationship (MSR) Working group.
Available: http://www.msr-wg.de/megma/downlo.html
[12]
Modelica Libraries.
Available : http://www.modelica.org/libraries
[13]
Symbol Exchange with SVG (Version 10, January 24, 2008)
URL: http://fat-ak30.eas.iis.fraunhofer.de/exchange/index_de.html
Version 2.0
-19-
June 11, 2008
VHDL-AMS Modeling Guidelines
Appendix A
Definition of the Library Structure
-- library:
-- structure:
-- name:
FUNDAMENTALS_VDA
Library name
domains/electrics/capacitor Path to the model (here: domains/electrics)
Capacitor
Short name of the model
Structure of the Model Library FUNDAMENTALS_VDA
fundamentals_vda
domains
electrics
magnetics
mechanics
position_force
translational
rotational
transducer
energy transducer (translational↔rotational)
velocity_force
translational_v
rotational_v
transducer_v
energy transducer (translational↔rotational)
thermal
hydraulics
pneumatics
acoustics
optics
transducer
Energy transducer for physical domains
(simple models of heterogeneous systems like motor, ...)
control_systems
time-continous transfer blocks
discrete_systems
time-discrete transfer blocks
digital_systems
digital blocks (gates, flip flops etc.)
data_conversion
conversion between different waveform representations
a2s_vda
converter (analog quantities to signals)
s2a_vda
converter (signals to analog quantities)
s2s_vda
converter (conversion between different signal
representations)
time_sources
time continous waveform generators (non-conservative)
functions
characteristics, sets of characteristic curves
table_look_up
algorithm
e. g. mathematical functions
preliminary
non standard packages
Version 2.0
-20-
June 11, 2008
VHDL-AMS Modeling Guidelines
Structure of the Model Library SPICE2VHD
general
general models (R, L, C, sources, ...)
semiconductor
semiconductor models
Structure of the Model Library AUTOMOTIVE_VDA
general
sources
loads
general models
independent signal sources
general loads
electrical_system
energy_supply
fuses
lines
relais
lamps
energy_loads
models for powernet simulation
energy supply
automotive fuses
automotive lines
relays
automotive lamps
loads for powernet simulation
transducer
sensors
actuators
electrical-nonelectrical transducers
sensors
actors
Recommendation for Naming of Ports and Internal Objects
Conservative terminals:
In general, an identifier consists of the first two letters of the corresponding domain followed
by an underscore and a number if it makes sense. An exception should be made in the case
of mechanical terminals. The first letter is an “M”. The second letter is either a “T” (translational) or an “R” (rotational). The third letter is a “V” if the velocity-force-analogy is used.
EL_1, EL_2, . . .
MT_1, MT_2, . . .
MR_1, MR_2, . . .
MTV_1, MTV_2, . . .
MRV_1, MRV_2, . . .
MA_1, MA_2, . . .
TH_1, TH_2, . . .
HY_1, HY_2, . . .
PN_1, PN_2, . . .
AC_1, AC_2, . . .
Version 2.0
elektrical terminal
mechanical translational terminal (position-force representation)
mechanical rotational terminal (angle-torque representation)
mechanical translational terminal (velocity-force representation)
mechanical rotational terminal (angular velocity-torque represent.)
magnetic terminal
thermal terminal
hydraulic terminal
pneumatic terminal
acoustic terminal
-21-
June 11, 2008
VHDL-AMS Modeling Guidelines
signals (time-discrete)
S_1, s_2, . . .
no special direction, internal signals (in, out)
S_IN_1, S_IN_2, . . .
inputs
S_OUT_1, S_OUT_2, . . . outputs
quantities / nonconservative connection points (time-continuous):
Q_1, Q_2, . . .
no special direction, internal signals (in, out)
Q_IN_1, Q_IN_2, . . .
inputs (in)
Q_OUT_1, Q_OUT_2, . . . outputs (out)
OP_1, OP_2, . . .
optical port (optical power)
Recommendations for Naming of Architectures
BASIC
EXTENDED
PRECISION
SPECIAL
Version 2.0
very simple basic model
e. g. models that switch between different parts
consideration of secondary effects
further models with some special effects
-22-
June 11, 2008
VHDL-AMS Modeling Guidelines
Appendix B
Disclaimer for File Header
-------------------------------------------------------------------------------- Copyright (c) 2004 VDA / FAT
--- This model is a component of the open source library created by the VDA / FAT
-- working group number 30 and is covered by this license agreement .
-- This model including any updates, modifications, revisions, copies, and
-- documentation are copyrighted works of the VDA / FAT.
-- USE OF THIS MODEL INDICATES YOUR COMPLETE AND
-- UNCONDITIONAL ACCEPTANCE OF THE TERMS AND CONDITIONS
-- SET FORTH IN THIS LICENSE AGREEMENT.
-- The VDA / FAT grants a non-exclusive license to use, reproduce,
-- modify and distribute this model under the condition, that:
-- (a) no fee or other consideration is charged for any distribution except
-- compilations distributed in accordance with Section (d) of this license
-- agreement
-- (b) the comment text embedded in this model is included verbatim
-- in each copy of this model made or distributed by you, whether or not such
-- version is modified
-- (c) any modified version must include a conspicuous
-- notice that this model has been modified and the date of modification; and
-- (d) any compilations sold by you that include this model must include a
-- conspicuous notice that this model is available from the VDA / FAT in its
-- original form at no charge.
--- THIS MODEL IS LICENSED TO YOU "AS IT IS" AND WITH NO WARRANTIES,
-- EXPRESSED OR IMPLIED. THE VDA / FAT AND ALL COMPANIES CONTRIBUTING
-- TO THIS LIBRARY SPECIFICALLY DISCLAIM ALL IMPLIED WARRANTIES OF
-- MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
-- THE VDA / FAT AND ALL COMPANIES ORGANIZED WITHIN MUST NOT
-- HAVE ANY RESPONSIBILITY FOR ANY DAMAGES, FINANCIAL OR LEGAL CLAIMS
-- WHATEVER.
-------------------------------------------------------------------------------
Disclaimer for File End
-------------------------------------------------------------------------------- Copyright (c) 2004 VDA / FAT
-------------------------------------------------------------------------------
Version 2.0
-23-
June 11, 2008
VHDL-AMS Modeling Guidelines
Appendix C
Comment for File Header
-----------------------------
---------------------------------------------------------------Source:
<File name>
Development simulator:
<Simulator and version>
Tested on:
-----------------------------------------------------------------Model Vers.
Simulator
Version
OS
Validator
Date
-----------------------------------------------------------------1.0
…
Modification History:
-----------------------------------------------------------------Version
Author
Date
Description
-----------------------------------------------------------------1.0
N.N.
......
Original version
-----------------------------------------------------------------$Version$
$Revision$
$Date$
$Author$
------------------------------------------------------------------
Notes
Marker
Description
Name of the file with the model.
Simulator name follows in the next line.
The description of the validation of the model has to be
done in accordance with appendix C. The comment starts
in the next line:
- Version of the model
- Simulator
- Simulator Version
- Operating system (version, release)
- Validator
- Date in the form YYYY/MM/DD
-- Modification History:
The description of the modification history of the model
-- ----------------------- has to be done in accordance with appendix C. The com-- Logical Library ....
-- ----------------------- ment starts in the next line:
- Version of the model
- Author of the model
- Date in the form YYYY/MM/DD
- Comment
-- ----------------------- Variables for version control
-------
Source:
Development simulator:
Tested on:
---------------------Model Version … ....
----------------------
-- $Id$
-- -----------------------
Version 2.0
-24-
June 11, 2008
VHDL-AMS Modeling Guidelines
Appendix D
Reserved Words in VHDL-AMS [5]
Version 2.0
-25-
June 11, 2008
VHDL-AMS Modeling Guidelines
Reserved Words in Verilog [7]
Version 2.0
-26-
June 11, 2008
VHDL-AMS Modeling Guidelines
Appendix E
Subdirectory Names
Tool
ADVance MS
AMS Designer
FTL Systems Tools
Simplorer
SystemVision
SaberHDL
SMASH
Version 2.0
Current Version
EDA Vendor
Mentor Graphics
Cadence
FTL Systems
ANSOFT
Mentor Graphics
Synopsys
Dolphin
-27-
Identifier for
subdirectory
ADMS
AMSDesigner, dfII
FTL
SIMPL
SV
SaberHDL
Smash
June 11, 2008
VHDL-AMS Modeling Guidelines
Appendix F
Administration of Models
Generation of tool-dependent
libraries by the EDA vendors
AK 30
Feedback
To author
Feedback to
one AK address
At the instigation of
the author
SVN-Server
Version 2.0
At the instigation of
the author
WWW-Account
for
AK30 Members
-28-
WWW-Account
(general)
June 11, 2008
VHDL-AMS Modeling Guidelines
Appendix G
VHDL-AMS Model Example
----------------------------------------------------------
---------------------------------------------------------------------------Copyright (C) 2004-2006 VDA/FAT
This model is a component of the open source library created by the VDA/FAT
working group number 30 and is covered by this license agreement. This model
including any updates, modifications, revisions, copies, and documentation
are copyrighted works of the VDA/FAT. Use of this model indicates your
complete and unconditional acceptance of the terms and conditions set forth
in this license agreement.
The VDA/FAT grants a non-exclusive license to use, reproduce, modify and
distribute this model under the condition, that:
(a) no fee or other consideration is charged for any distribution except
compilations distributed in accordance with Section (d) of this license
agreement;
(b) the comment text embedded in this model is included verbatim in each
copy of this model made or distributed by you, whether or not such
version is modified;
(c) any modified version must include a conspicuous notice that this model
has been modified and the date of modification; and
(d) any compilations sold by you that include this model must include a
conspicuous notice that this model is available from the VDA/FAT in
its original form at no charge.
THIS MODEL IS LICENSED TO YOU "AS IT IS" AND WITH NO WARRANTIES, EXPRESSED
OR IMPLIED. THE VDA/FAT AND ALL COMPANIES CONTRIBUTING TO THIS LIBRARY
SPECIFICALLY DISCLAIM ALL IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS
FOR A PARTICULAR PURPOSE. THE VDA/FAT AND ALL COMPANIES ORGANIZED WITHIN
MUST NOT HAVE ANY RESPONSIBILITY FOR ANY DAMAGES, FINANCIAL OR LEGAL CLAIMS
WHATEVER.
-----------------------------------------------------------------------Source:
capacitor.vhd
Development simulator:
SimulatorA
Tested on:
-----------------------------------------------------------------Version Simulator
Version
OS
Validator
Date
-----------------------------------------------------------------1.1
SimulatorA
1.0
W2000 Mustermann_1
2004/07/05
1.1
SimulatorB
4.1
W2000 Mustermann_2
2005/01/10
Modification History:
-----------------------------------------------------------------Version Author
Date
Description
-----------------------------------------------------------------1.1
Mustermann_3
2004/07/05
Original Version
---------------------------------------------------------------------------$Version: 2.0.0 $
$Revision: 2135 $
$Date: 2007-05-14 16:35:43 +0200 (Mo, 14 Mai 2007) $
$Author: andre $
----------------------------------------------------------------------------
--/**
--- Spice Capacitor Model.
-- The model describes an ideal capacitor in the same way as in Spice
-- (SPICE3 Version 3f3 User's Manual 3.1.5).
--- @generic
C
capacitance [F]
-- @generic
IC
(optional) initial condition [V]
--- @port
P
plus terminal
-- @port
N
minus terminal
--- @library
SPICE2VHD
-- @structure general/basic
-- @test
basic_test
Version 2.0
-29-
June 11, 2008
VHDL-AMS Modeling Guidelines
-- @reference
--- @reference
-----*/
T. Quarles et al: SPICE3 Version 3f3 User's Manual.
University of California, May 1993.
Verilog-AMS Language Reference Manual.
Analog & Mixed-Signal Extensions to VerilogHDL.
Version 2.1, January 20, 2003.
library IEEE;
use IEEE.ELECTRICAL_SYSTEMS.all;
entity CAPACITOR is
generic (
C : REAL;
IC : REAL := REAL'LOW
);
port
(
terminal P : ELECTRICAL;
terminal N : ELECTRICAL
);
end entity CAPACITOR;
architecture SPICE of CAPACITOR is
quantity V across I through P to N;
begin
if DOMAIN = QUIESCENT_DOMAIN and IC /= REAL'LOW use
V == IC;
else
I == C*V'DOT;
end use;
end architecture SPICE;
-- ------------------------------------------------------------------------- Copyright (C) 2004-2006 VDA/FAT
-- ------------------------------------------------------------------------
Version 2.0
-30-
June 11, 2008