====== VAMS netlister README ======
===== VAMS netlister =====
date: 10 october 2000
gEDA: gnetlist vams mode
first unrevised vams mode documentation
Written by: Martin Lehmann
-------------------------------------------------------------------------
VHDL-AMS support for the gEDA gnetlist tool
-------------------------------------------
CONTENT:
1. functionality
1. ARCHITECTURE generation
2. ENTITY generation
3. automatisate gnetlist calls
2. implementation
1. the vams mode of gEDA gnetlist
1. scheme
1. settings and new definition
2. gnet-vams.scm
1. routines main structure
3. helpfully setting in gEDA gschem environment
2. new c-code
1. routines
2. code-adaptation
2. automatic generating gnetlist calls in gEDA gschem
1. generated gEDA gnetlist calls
2. scheme
1. generate_netlist.scm
2. settings
3. new c-code
1. routines
2. code-adaptation
The purpose of our endevour, is that gEDA gnelist completly
supportted VHDL-AMS (VHDL Analog and Mixed-Signal) netlist
generation.
The VHDL-AMS netlist support mode is called vams.
1. FUNCTIONALITY
gEDA gnetlist in vams mode allow it to generate a VHDL-AMS
ARCHITECTURE or an ENTIY declaration. Which of both tasks is
performed, dependends on the generate-mode variable. This variable
is defined in the gnetlist command or will be set default.
If generate-mode=1 (default) gnetlist creates a netlist as an
VHDL-AMS ARCHITECTURE of the current schematic. Otherwise
(generate-mode=2), it creates an VHDL-AMS ENTITY declaration of the
selected component (this task needs information from gEDA gschem,
see below).
Now follows a stepwise discription of the program run in both
submodes.
We presuppose that you are familiar with the structure of gEDA
gnetlist usage (otherwise try gnetlist -help) and that you have
ever seen an VHDL-AMS ARCHITECTURE with its belonging ENTITY. If
you does not then the following distription will be seems very
strange to you. Maybe the syntax files (syntax_entity.txt,
syntax_architeture.txt) can helps you further.
==================================================================
1.1. ARCHITECTURE GENERATION
We suppose generate-mode is equal to 1, from this it follows that
vams creates a netlist as an ARCHITECTURE (saved to
_arc.).
ARCHITECTURE OF IS
The architecture-identifier we are getting from the toplevel
attribute architecture, which we have introduced. If it is not
defined, we are setting architecture-identifier default
(default_architecture). The same have we doing with the
entity-identifier (toplevel attribute entity, default_entity).
{ : subnet-kind;}
In the signal declaration part all subnets of the schematic will be
declarated. A subnet declaration consists of an net-object, a
net-name and a net-kind. All subnets are connected to various
components pins. If this pins have all the same port-object and the
same port-kind it is ok, but if one of them different, the net is
faulty, and will be not declarated. Moreover, if the subnet-object
a quantity, then it will be checked, whether the subnet consists
exactly one output pin (port-mode), else the subnet is faulty too.
The three net attributes (object, kind, mode) we are getting from
the pin attribs, port_kind, port_object and port_mode (which we
have introduced newly) of a component pin.
BEGIN
Ok. it's only marks the start of the architecture body.
{ : ENTITY [()]
[GENERIC MAP ( =>
{; })]
PORT MAP ( => {; <.. => ..>});}
We only support component instantiation statements, like this
above, because we generate simple VHDL-AMS netlists. The label of
an instance is defined from the uref of the instanciated
component. Watch out, this label must be unique,it is not checked
anywhere. The entity variable is not the same as the
entity-identifier, it is the value of the device attribute which on
its part identifies the precompiled ENTITY of this special
component. Similar is the architecture variable belonging to the
instanciated components ARCHITECTURE (note: one ENTITY can have more
ARCHITECTURES), hence we are getting it from the component
attribute ARCHITECTURE (newly introduced).
All generics of the generic-list are component parameters, which
are different from its default values (set in its ENTITY
declaration). How can we distinguish them? All defined generics
are attached to the component and looks like :
=? <- default, not in
generic-list
And if you want to change a parameter, you only must delete the
?-character and replace the default-value with your wanted value,
like this :
= <- element of generic list
If you do it this way, the new assigned value and its attribute-name
will be appear in the GENERIC MAP (set-generic=attribute-name and
generic-value=new-value).
The PORT MAP consists of all pins of a component and which nets
them connected to. The pin-name is getting from the pin# attribute
of the pin and the subnet-name means the value of the label
attribute of a net (mostly default named), which the pin is
connected to. If the pin directly wired to a PORT component (=
component, which device attribute =PORT), then we assign the uref
of this component to subnet-name.
END ARCHITECTURE ;
I think, this line needs no more explanation. The
architecture-identifier is the same like in the first line of
ARCHITECTURE declaration. Hence, the ARCHITECTURE part ends here.
==================================================================
1.2. ENTITY GENERATION
Now, we suppose generate-mode is equal to 2, from this it follows
that vams creates an ENTITY declaration of a component (save to
.vhdl). If there no component selected (empty
top-attribs list) then it will be created an toplevel ENTITY of the
current schematic (save to
.vhdl).
LIBRARY {,};
USE {,};
Well, the context clause part is not very ingenious. All libraries
and packages you needs for your simulation you must insert staticly
(a library contents precompiled ENTITIES, ARCHITECTURES and
PACKAGES, which are needed from base components [base of the
hierachical netlist] of your schematic. a package contents
predefined types, constants, ...). We are searching for a better
usability of this part.
ENTITY IS
[genric_clause]
[port_clause]
END ENTITY;
If you want generate a toplevel ENTITY of your current schematic
then the entity-identifier is defined from the toplevel attribute
entity of the schematic-file. Moreover, there are no generic_clause
and no port_clause.
In case of an component based ENTITY declaration, the
entity-identifier is getting from the device attribute of the
selected component (this attribute is included in top-attribs list,
which is defined in the automatic generated gnetlist command .. more
about this, later).
generic_clause :=
GENERIC ( : REAL :=
{; : REAL := });
All needed generic-identifiers and it default-values are getting
from the top-attribs list. Note: all attached attributes of a
component appears in the generic_clause, only special attributes,
like uref, source and architecture, are taked out. The values of
this attributes are taked from the top-attribs list, too, but it
does not matter whether the value starts with a ?-character or not
(?-character always will be deleted, if it exist in front of a
value).
port_clause :=
PORT ( : []
{; : [] });
All variables of this clause are grabbed from the symbol of the
selected component. Port-kind corresponds with the value of the
port_kind attribute of the pin, which pin# attribute value is equal
to port-identifier. Just as corresponds port-type with the the
value of the pin attribute port_type and port-mode with the value
of port_mode.
===================================================================
1.3. AUTOMATISATING gnetlist CALLS
Because it is very arduous to type the whole gnetlist command,
which all its parameters, per hand into the terminal, we are
implement an automatisation of this process in gEDA gschem. This
makes it possible to create a VHDL-AMS ARCHITECTURE or ENTITY
whitout any commandline actions. The only thing you must do, is to
use one of the following hotkeys:
for generating an ENTITY
for genarating an ARCHITECTURE.
NOTE to - hotkey : If one component of the schematic
selected then the ENTITY generation
will be applied to this component !!
===================================================================
2. IMPLEMENTATION
At this section it will be explained the basic concept of the
implementation, which is splited in two sections. The first one
aimed to the gnelist implementation and the second to the gschem
implementation.
2.1. THE VAMS MODE OF gEDA gnetlist
To realize gnetlist VHDL-AMS support, it was necessary to create
new scheme and c stuff.
2.1.1. SCHEME
The scheme implementation contents two parts. On one hand the new
file gnet-vams.scm, which realize the VHDL-AMS-code generation, and
on the other hand some settings in rc-files.
2.1.1.1. SETTINGS AND NEW DEFINITIONS
The following lines insert in your gschemrc, or wherever you want,
but it must be loaded at gnetlist startup.
- load two modules, which we needs in our new implementation.
(define-module (ice-9 ls) :use-module (ice-9 common-list)
:use-module (ice-9 string-fun))
- load main file for VHDL-AMS support, which contents the
startup procedure vams.
(load "/gnet-vams.scm")
2.1.1.2. gnet-vams.scm
This file contents all necessary scheme-functions to generate
VHDL-AMS-code. Especially, the main procedure vams, which can be
execute from the gnetlist command.
For example :
gnetlist -g vams schematic_filename.sch
...
2.1.2.1. ROUTINES MAIN STRUCTURE
the mainly functions structure looks like:
- (vams output-filename)
ARCHITECTURE generation
- (vams:write-secondary-unit architecture entity output-port)
- (vams:write-architecture-declarative-part output-port)
- (vams:write-signal-declarations output-port)
- (vams:write-architecture-statement-part packages output-port)
- (vams:write-generic-map output-port package)
- (vams:write-port-map package output-port)
ENTITY declaraction
- (vams:write-primary-unit entity port-list generic-list output-port)
- (vams:write-context-clause output-port)
- (vams:write-generic-clause generic-list output-port)
- (vams:write-generic-list generic-list output-port)
- (vams:write-port-clause port-list output-port)
- (vams:write-port-list port-list output-port)
2.1.1.3 HELPFULLY SETTING IN THE gEDA gschem ENVIRONMENT
This settings are not absolutly necessary, but they makes work
easier.
- set in .gEDA/gschemrc or wherever you want, but place it
right.
(attribute-promotion "enable")
(promote-invisible "enable")
(enforce-hierarchy "disabled")
(attribute-name "port_object")
(attribute-name "port_type")
(attribute-name "port_mode")
(attribute-name "entity")
(attribute-name "architecture")
2.1.2. NEW C - CODE
To got all informations, which we needed for currently netlist
generation, we must implemented two new c - functions.
2.1.2.1 NEW ROUTINES (saved in vams_misc.c)
SCM vams_get_package_attributes(SCM scm_uref)
The first function gets all attribute names (not its values) of a
component. This routine requires the name a component (package),
especially the uref of it, and returns a list of all attribute
names which are attached to this package.
We needs this functionality to produce a currectly
VHDL-AMS GENERIC MAP.
char* vams_get_attribs_list
(OBJECT *object, SCM *list, OBJECT **return_found)
It exists only for the support of the first function.
2.1.2.2. CODE ADAPTATION
To place this new functions at gnetlist scheme's disposal, you must
perform the following actions.
(1) gnetlist/src/g_register.c
gh_new_procedure1_0
("gnetlist:vams-get-package-attributes",
vams_get_package_attributes);
(2) gnetlist/include/prototype.h
SCM vams_get_package_attributes(SCM scm_uref);
(3) edit gnetlist/src/Makefile.in or directly in Makefile
(if you have edited Makefile.in you must run make config of
course)
- add "vams_misc.c" to gnetlist_SOURCES - variable
- add "vams_misc.o" to gnetlist_OBJECTS - variable
(4) copy vams_misc.c to gEDA/gnetlist/src/
(5) compile your code newly
===================================================================
2.2. AUTOMATIC GENERATING gnetlist CALLS IN gEDA gschem
To realize this new feature it was necessary to put more
information from the schematic to the scheme world of gEDA gschem.
Concretly, we needs the filename of the current schematic, because
gEDA gnetlist required it, and the attached attributes of a
selected component for creating an VHDL-AMS ENTITY. Hence, the
gnetlist command is mutated to an unidirectional interface between
the world of gschem scheme and the world of gnetlist scheme.
There are three important things, which transfer through this
interface:
(1) the source-file, which contents the complett filename
(with path) of the current schematic.
(2) the top-attribs list, which contents all attached
attributes of the selected component.
(3) the generate-mode, which is defined by the users actions.
2.2.1. STRUCTURE OF gEDA gnetlist CALLS FROM COMMANDLINE OR FROM gEDA
gschem.
typical commandline call :
gnetlist [-o ]
-g vams
There are nothing to explain. The top-attribs list and the
generate-mode variable are default defined ('() and 1).
calls from gEDA gschem (3 possible variations) :
Note: vhdl-path is a predefined variable, which is set in
generate_netlist.scm first times. You can it simple redefine
in your local gschemrc file, which is loading everytimes you
starts gEDA gschem.
(1) hot-key-stroke: - g n (generate netlist)
--> generates a netlist of the current schematic.
gnetlist -o /
-g vams
The source-file variable is equate to the complett
path+filename of the current schematic, which we get with
help of a self coded c function. If you cut out the filename
of the source-file variable (source-file without path) then
you are getting the target-file.generate-mode and
top-attribs are default again.
(2) hot-key-stroke: - g e (generate-entity)
and no component is selected.
--> generates an toplevel ENTITY of the current
schematic.
gnetlist -c
-o /
-g vams
scheme-comm="(define top-attribs ')
(define generate-mode '2)"
Source-file needs no comment, because it is the same as in
(1). To get all attributes of a selected component, we are
must write a new c function again. The values, which we get
from this new function are saved in top-attribs. The sense
of the scheme-comm command is to put top-attribs and
generate-mode from the gschem to the gnetlist environment.
At last, the target-file consists of the pure basefilename
of the source-file and an .vhdl extention.
(3) hot-key-stroke: - g e (generate-entity)
and only one component is selected.
--> generates an ENTITY of the selected schematic.
commandline is the same as in (2).
Differences: The target-file is different, but it does not
matter, because gnetlist generate an new output-filename in
in this case (.vhdl,
normally).But one fact is very important: the top-attribs
variable includes all attached attributes of the selected
component now.
2.2.2. SCHEME
The gnetlist command is generating from two scheme functions, which
are saved in generate_netlist.scm. This functions starts if the
gschem user is typing one of the specified hot-keys ([g e] starts
generate-entity and [g n] starts generate-netlis). Both routines
puts the whole gnetlist command together and execute it. The syntax
you see above.
2.2.2.1. generate_netlist.scm
2.2.2.2. SETTINGS
If you want use the new feature then you must do some entries in one
of your gEDA gschem rc-files
necessary defines:
- in system-gschemrc
("g" . gnetlist-keymap)
Edit your global-keymap and if "g" always defined then find
out an other free hot-key-stroke.
Note: the documentation supports the "g" - key only.
- in one of the gschem startup files
(define gnetlist-keymap
'(("n" . generate-netlist)
("e" . generate-entity)))
loads :
(load "/home/fliser3/.gEDA/generate_netlist.scm")
2.2.3. NEW C-CODE
The c-code makes it possible to get directly informations from the
gschem tool, which is necessary for the online execution of
gnetlist.
2.2.3.1. ROUTINES
It exists two new c-functions. Both are put down in
misc_for_gnetlist.c.
SCM get_selected_filename(gpointer data,
guint callback_action,
GtkWidget *widget)
This function returns the whole filename of the current schematic,
which is picked from the w_current->page_current->page_filename
string.
SCM get_selected_component_attributes(gpointer data,
guint callback_action,
GtkWidget *widget)
How the name is saying, this functions returns all attributes of
the selected component. It is realized with a simple while loop
over all objects of the schematic, which picked out all elements
where the selected flag is set.
2.2.3.2. CODE-ADAPTATION
Here are some actions you must conclude to makes the software
runable.
(1) new lines in /gschem/src/g_register.c
gh_new_procedure0_0 ("get-selected-filename",g_get_selected_filename);
(2) new lines in /gschem/include/prototype.h
SCM g_get_selected_filename();
(3) copy the file misc_for_gnetlist.c to gschem/src
(4) add in file /gschem/src/Makefile.in or directly in Makefile.
(if you have edited Makefile.in you must run make config of
course)
- add "misc_for_gnetlist.c" to gschem_SOURCES - variable
- add "misc_for_gnetlist.o" to gschem_OBJECTS - variable
(5) add new lines in /gschem/src/g_key.c
SCM g_get_selected_filename(void)
{
return (get_selected_filename(window_current, 0, NULL));
}
(6) compile your changed c-code newly
===== VAMS netlister syntax architecture =====
ARCHITECTURE OF IS
{ : subnet-kind;}
BEGIN
{ : ENTITY [()]
[GENERIC MAP ( =>
{; })]
PORT MAP ( => {; <.. => ..>});}
END ARCHITECTURE ;
===== VAMS netlister syntax entity =====
LIBRARY {,};
USE {,};
ENTITY IS
[GENERIC ( : REAL :=
{; : REAL := }); ]
[PORT ( : []
{; : [] });]
END ENTITY;