Updated all man page dates/versions
[geda-gaf.git] / gnetlist / docs / vams / vams_mode.txt
blob7065b5433e226850c2b685c597290582b47b49b1
1 date: 10 october 2000
2 gEDA: gnetlist vams mode
3 first unrevised vams mode documentation
6 Written by: Martin Lehmann
7 -------------------------------------------------------------------------
10 VHDL-AMS support for the gEDA gnetlist tool
11 -------------------------------------------
13 CONTENT:
15    1. functionality
16       1. ARCHITECTURE generation   
17       2. ENTITY generation
18       3. automatisate gnetlist calls
20    2. implementation
21       1. the vams mode of gEDA gnetlist
22          1. scheme
23             1. settings and new definition
24             2. gnet-vams.scm
25                1. routines main structure
26             3. helpfully setting in gEDA gschem environment
28          2. new c-code
29             1. routines
30             2. code-adaptation
31       
32       2. automatic generating gnetlist calls in gEDA gschem
33          1. generated gEDA gnetlist calls
34          2. scheme
35             1. generate_netlist.scm
36             2. settings
37          
38          3. new c-code
39             1. routines
40             2. code-adaptation
41    
43    The purpose of our endevour, is that gEDA gnelist completly
44    supportted VHDL-AMS (VHDL Analog and Mixed-Signal) netlist
45    generation. 
47    The VHDL-AMS netlist support mode is called vams.
50    1. FUNCTIONALITY
52    gEDA gnetlist in vams mode allow it to generate a VHDL-AMS
53    ARCHITECTURE or an ENTIY declaration. Which of both tasks is
54    performed, dependends on the generate-mode variable. This variable
55    is defined in the gnetlist command or will be set default.
57    If generate-mode=1 (default) gnetlist creates a netlist as an
58    VHDL-AMS ARCHITECTURE of the current schematic. Otherwise
59    (generate-mode=2), it creates an VHDL-AMS ENTITY declaration of the
60    selected component (this task needs information from gEDA gschem,
61    see below).
63    Now follows a stepwise discription of the program run in both
64    submodes.
66    We presuppose that you are familiar with the structure of gEDA
67    gnetlist usage (otherwise try gnetlist -help) and that you have
68    ever seen an VHDL-AMS ARCHITECTURE with its belonging ENTITY. If
69    you does not then the following distription will be seems very
70    strange to you. Maybe the syntax files (syntax_entity.txt,
71    syntax_architeture.txt) can helps you further.
72    
73    ==================================================================
74      
75    1.1. ARCHITECTURE GENERATION
77    
78    We suppose generate-mode is equal to 1, from this it follows that
79    vams creates a netlist as an ARCHITECTURE (saved to
80    <value-of-toplevel-attribute-entity>_arc.<output-fileextension>).
83      ARCHITECTURE <architecture-identifier> OF <entity-identifier> IS 
85    The architecture-identifier we are getting from the toplevel
86    attribute architecture, which we have introduced. If it is not
87    defined, we are setting architecture-identifier default
88    (default_architecture).  The same have we doing with the
89    entity-identifier (toplevel attribute entity, default_entity).
92      {<subnet-object> <subnet-name> : subnet-kind;}
93   
94    In the signal declaration part all subnets of the schematic will be
95    declarated. A subnet declaration consists of an net-object, a
96    net-name and a net-kind. All subnets are connected to various
97    components pins. If this pins have all the same port-object and the
98    same port-kind it is ok, but if one of them different, the net is
99    faulty, and will be not declarated. Moreover, if the subnet-object
100    a quantity, then it will be checked, whether the subnet consists
101    exactly one output pin (port-mode), else the subnet is faulty too.
102    The three net attributes (object, kind, mode) we are getting from
103    the pin attribs, port_kind, port_object and port_mode (which we
104    have introduced newly) of a component pin.
106      
107      BEGIN
108         
109    Ok. it's only marks the start of the architecture body.
112      {<label> : ENTITY <entity> [(<architecture>)]
113             [GENERIC MAP (<set generic> => <generic-value>
114                          {; <set-generic=> <generic-value>})]
115             PORT MAP ( <pin-name> => <subnet-name>{; <.. => ..>});}
117    We only support component instantiation statements, like this
118    above, because we generate simple VHDL-AMS netlists. The label of
119    an instance is defined from the uref of the instanciated
120    component. Watch out, this label must be unique,it is not checked
121    anywhere. The entity variable is not the same as the
122    entity-identifier, it is the value of the device attribute which on
123    its part identifies the precompiled ENTITY of this special
124    component. Similar is the architecture variable belonging to the
125    instanciated components ARCHITECTURE (note: one ENTITY can have more
126    ARCHITECTURES), hence we are getting it from the component
127    attribute ARCHITECTURE (newly introduced).
129    All generics of the generic-list are component parameters, which
130    are different from its default values (set in its ENTITY
131    declaration). How can we distinguish them?  All defined generics
132    are attached to the component and looks like :
134            <attribute-name>=?<default-value> <- default, not in
135                                                 generic-list 
136      
137    And if you want to change a parameter, you only must delete the
138    ?-character and replace the default-value with your wanted value,
139    like this :
141            <attribute-name>=<new-value> <- element of generic list 
142            
143    If you do it this way, the new assigned value and its attribute-name
144    will be appear in the GENERIC MAP (set-generic=attribute-name and
145    generic-value=new-value).
147    The PORT MAP consists of all pins of a component and which nets
148    them connected to. The pin-name is getting from the pin# attribute
149    of the pin and the subnet-name means the value of the label
150    attribute of a net (mostly default named), which the pin is
151    connected to. If the pin directly wired to a PORT component (=
152    component, which device attribute =PORT), then we assign the uref
153    of this component to subnet-name.
156      END ARCHITECTURE <architecture-identifier>;
158    I think, this line needs no more explanation. The
159    architecture-identifier is the same like in the first line of
160    ARCHITECTURE declaration. Hence, the ARCHITECTURE part ends here.
162    ==================================================================
163      
164    1.2. ENTITY GENERATION
167    Now, we suppose generate-mode is equal to 2, from this it follows
168    that vams creates an ENTITY declaration of a component (save to
169    <component-device>.vhdl). If there no component selected (empty
170    top-attribs list) then it will be created an toplevel ENTITY of the
171    current schematic (save to
172    <value-of-toplevel-attribute-entity>.vhdl).
175      LIBRARY <library-identifier>{,<library-identifier>};
176      USE     <package-identidier>{,<package-identifier>};
178    Well, the context clause part is not very ingenious. All libraries
179    and packages you needs for your simulation you must insert staticly
180    (a library contents precompiled ENTITIES, ARCHITECTURES and
181    PACKAGES, which are needed from base components [base of the
182    hierachical netlist] of your schematic. a package contents
183    predefined types, constants, ...).  We are searching for a better
184    usability of this part.
186      
187      ENTITY <entity-identifier> IS 
188          [genric_clause]
189          [port_clause]
190      END ENTITY;
192    If you want generate a toplevel ENTITY of your current schematic
193    then the entity-identifier is defined from the toplevel attribute
194    entity of the schematic-file. Moreover, there are no generic_clause
195    and no port_clause.
197    In case of an component based ENTITY declaration, the
198    entity-identifier is getting from the device attribute of the
199    selected component (this attribute is included in top-attribs list,
200    which is defined in the automatic generated gnetlist command .. more
201    about this, later).
204      generic_clause :=
205                GENERIC ( <generic-identifier> : REAL := <default-value>
206                         {;<generic-identifier> : REAL := <default-value>});
208    All needed generic-identifiers and it default-values are getting
209    from the top-attribs list. Note: all attached attributes of a
210    component appears in the generic_clause, only special attributes,
211    like uref, source and architecture, are taked out. The values of
212    this attributes are taked from the top-attribs list, too, but it
213    does not matter whether the value starts with a ?-character or not
214    (?-character always will be deleted, if it exist in front of a
215    value).
218      port_clause :=
219             PORT (<port-kind> <port-identifier> : [<port-mode>] <port-type>
220                   {;<port-kind> <port-identifier> : [<port-mode>] <port-type>});
222    All variables of this clause are grabbed from the symbol of the
223    selected component. Port-kind corresponds with the value of the
224    port_kind attribute of the pin, which pin# attribute value is equal
225    to port-identifier. Just as corresponds port-type with the the
226    value of the pin attribute port_type and port-mode with the value
227    of port_mode.
228         
229    ===================================================================
231    1.3. AUTOMATISATING gnetlist CALLS
233    Because it is very arduous to type the whole gnetlist command,
234    which all its parameters, per hand into the terminal, we are
235    implement an automatisation of this process in gEDA gschem. This
236    makes it possible to create a VHDL-AMS ARCHITECTURE or ENTITY
237    whitout any commandline actions. The only thing you must do, is to
238    use one of the following hotkeys:
239       
240             <g e> for generating an ENTITY 
241             <g n> for genarating an ARCHITECTURE.
242      
243         NOTE to <g e> - hotkey : If one component of the schematic
244                                  selected then the ENTITY generation 
245                                  will be applied to this component !!
247    ===================================================================                  
249    2. IMPLEMENTATION
250      
251    At this section it will be explained the basic concept of the
252    implementation, which is splited in two sections. The first one
253    aimed to the gnelist implementation and the second to the gschem
254    implementation. 
256      
257    2.1. THE VAMS MODE OF gEDA gnetlist
259    To realize gnetlist VHDL-AMS support, it was necessary to create
260    new scheme and c stuff.
263    2.1.1. SCHEME 
265    The scheme implementation contents two parts. On one hand the new
266    file gnet-vams.scm, which realize the VHDL-AMS-code generation, and
267    on the other hand some settings in rc-files.
269      
270    2.1.1.1. SETTINGS AND NEW DEFINITIONS
272    The following lines insert in your gschemrc, or wherever you want,
273    but it must be loaded at gnetlist startup.
274                         
275            - load two modules, which we needs in our new implementation.
277              (define-module (ice-9 ls) :use-module (ice-9 common-list)
278                                        :use-module (ice-9 string-fun))     
280            - load main file for VHDL-AMS support, which contents the 
281              startup procedure vams.
283              (load "<path_of_gnet-vams.scm>/gnet-vams.scm")
286    2.1.1.2. gnet-vams.scm
288    This file contents all necessary scheme-functions to generate
289    VHDL-AMS-code. Especially, the main procedure vams, which can be
290    execute from the gnetlist command.
291          
292          For example : 
293              
294                 gnetlist -g vams schematic_filename.sch
296       ...
298       
299    2.1.2.1. ROUTINES MAIN STRUCTURE
301    the mainly functions structure looks like:
303    - (vams output-filename)
305      ARCHITECTURE generation
307         - (vams:write-secondary-unit architecture entity  output-port)
309             - (vams:write-architecture-declarative-part output-port)
310                   - (vams:write-signal-declarations output-port)
312             - (vams:write-architecture-statement-part packages output-port)
313                   - (vams:write-generic-map output-port package)
314                   - (vams:write-port-map package output-port)
316      ENTITY declaraction
318          - (vams:write-primary-unit entity port-list generic-list output-port)     
319             
320              - (vams:write-context-clause output-port)
322              - (vams:write-generic-clause generic-list output-port)
323                   - (vams:write-generic-list generic-list output-port)
325              - (vams:write-port-clause port-list output-port)
326                   - (vams:write-port-list port-list output-port)
329    2.1.1.3 HELPFULLY SETTING IN THE gEDA gschem ENVIRONMENT   
331    This settings are not absolutly necessary, but they makes work
332    easier.
334         - set in .gEDA/gschemrc or wherever you want, but place it
335           right.
337                 (attribute-promotion "enable")     
338                 (promote-invisible "enable")
339                 (enforce-hierarchy "disabled")
340          
341                 (attribute-name "port_object")
342                 (attribute-name "port_type")
343                 (attribute-name "port_mode")
344                 (attribute-name "entity")
345                 (attribute-name "architecture")
348    2.1.2. NEW C - CODE 
349       
350    To got all informations, which we needed for currently netlist 
351    generation, we must implemented two new c - functions.
353    
354    2.1.2.1 NEW ROUTINES (saved in vams_misc.c)
357      SCM vams_get_package_attributes(SCM scm_uref)
359    The first function gets all attribute names (not its values) of a
360    component. This routine requires the name a component (package),
361    especially the uref of it, and returns a list of all attribute
362    names which are attached to this package. 
364    We needs this functionality to produce a currectly 
365    VHDL-AMS GENERIC MAP.
368      SCM vams_get_attribs_list(OBJECT *object)
370    It exists only for the support of the first function.
371            
373    2.1.2.2. CODE ADAPTATION
374          
375    To place this new functions at gnetlist scheme's disposal, you must
376    perform the following actions.
377          
378      (1) gnetlist/src/g_register.c
379          
380            gh_new_procedure1_0 
381                ("gnetlist:vams-get-package-attributes", 
382                  vams_get_package_attributes);
383          
385      (2) gnetlist/include/prototype.h
386              
387            SCM vams_get_package_attributes(SCM scm_uref);
388              
390      (3) edit gnetlist/src/Makefile.in or directly in Makefile
391              
392          (if you have edited Makefile.in you must run make config of
393          course)
394              
395           - add "vams_misc.c" to gnetlist_SOURCES - variable
396           - add "vams_misc.o" to gnetlist_OBJECTS - variable
397              
398      (4) copy vams_misc.c to gEDA/gnetlist/src/
400      (5) compile your code newly
402    ===================================================================  
404    2.2. AUTOMATIC GENERATING gnetlist CALLS IN gEDA gschem
406    To realize this new feature it was necessary to put more
407    information from the schematic to the scheme world of gEDA gschem.
408    Concretly, we needs the filename of the current schematic, because
409    gEDA gnetlist required it, and the attached attributes of a
410    selected component for creating an VHDL-AMS ENTITY.  Hence, the
411    gnetlist command is mutated to an unidirectional interface between
412    the world of gschem scheme and the world of gnetlist scheme.
413    
414    There are three important things, which transfer through this
415    interface:
416    
417         (1) the source-file, which contents the complett filename
418             (with path) of the current schematic.
420         (2) the top-attribs list, which contents all attached
421             attributes of the selected component.
423         (3) the generate-mode, which is defined by the users actions.
426    2.2.1. STRUCTURE OF gEDA gnetlist CALLS FROM COMMANDLINE OR FROM gEDA
427           gschem.
429      typical commandline call :
430      
431                 gnetlist [-o <output-filename>] 
432                          -g vams
433                          <schematic-file>
435    There are nothing to explain. The top-attribs list and the
436    generate-mode variable are default defined ('() and 1).
439    calls from gEDA gschem (3 possible variations) :
442    Note: vhdl-path is a predefined variable, which is set in
443          generate_netlist.scm first times. You can it simple redefine
444          in your local gschemrc file, which is loading everytimes you
445          starts gEDA gschem.
447      
448      (1) hot-key-stroke: - g n  (generate netlist)
449          
450          --> generates a netlist of the current schematic. 
451              
452          
453              gnetlist -o <vhdl-path>/<target-file>
454                       -g vams
455                       <source-file>
457           The source-file variable is equate to the complett
458           path+filename of the current schematic, which we get with
459           help of a self coded c function. If you cut out the filename
460           of the source-file variable (source-file without path) then
461           you are getting the target-file.generate-mode and
462           top-attribs are default again.
464       (2) hot-key-stroke: - g e (generate-entity) 
465           and no component is selected.  
466           
467           --> generates an toplevel ENTITY of the current
468               schematic.
471               gnetlist -c <scheme-comm>
472                        -o <vhdl-path>/<target-file>
473                        -g vams
474                        <source-file>
476                   scheme-comm="(define top-attribs '<top-attribs>)
477                                (define generate-mode '2)"
479            
480            Source-file needs no comment, because it is the same as in
481            (1). To get all attributes of a selected component, we are 
482            must write a new c function again. The values, which we get 
483            from this new function are saved in top-attribs. The sense
484            of the scheme-comm command is to put top-attribs and 
485            generate-mode from the gschem to the gnetlist environment.
486            At last, the target-file consists of the pure basefilename
487            of the source-file and an .vhdl extention.
489        (3) hot-key-stroke: - g e (generate-entity)
490            and only one component is selected.
492            --> generates an ENTITY of the selected schematic.
495                commandline is the same as in (2).
497            
498            Differences: The target-file is different, but it does not
499            matter, because gnetlist generate an new output-filename in
500            in this case (<device-name-of-selected-component>.vhdl,
501            normally).But one fact is very important: the top-attribs
502            variable includes all attached attributes of the selected
503            component now.
505    2.2.2. SCHEME
507    The gnetlist command is generating from two scheme functions, which
508    are saved in generate_netlist.scm. This functions starts if the
509    gschem user is typing one of the specified hot-keys ([g e] starts
510    generate-entity and [g n] starts generate-netlis). Both routines
511    puts the whole gnetlist command together and execute it. The syntax
512    you see above.
515    2.2.2.1. generate_netlist.scm
518    2.2.2.2. SETTINGS
520    If you want use the new feature then you must do some entries in one
521    of your gEDA gschem rc-files
523      necessary defines:
525          - in system-gschemrc 
526                    
527                     ("g" . gnetlist-keymap)
529            Edit your global-keymap and if "g" always defined then find
530            out an other free hot-key-stroke.
532            Note: the documentation supports the "g" - key only.
533          
535          - in one of the gschem startup files
536                     
537              (define gnetlist-keymap
538                '(("n" . generate-netlist)
539                  ("e" . generate-entity)))
542      loads :
544             (load "/home/fliser3/.gEDA/generate_netlist.scm")
545             
546             
547    2.2.3. NEW C-CODE
548    
549    The c-code makes it possible to get directly informations from the
550    gschem tool, which is necessary for the online execution of
551    gnetlist.
554    2.2.3.1. ROUTINES
556    It exists two new c-functions. Both are put down in
557    misc_for_gnetlist.c.
559    
560      SCM get_selected_filename(gpointer data,           
561                           guint callback_action,        
562                           GtkWidget *widget)
564    This function returns the whole filename of the current schematic,
565    which is picked from the w_current->page_current->page_filename
566    string.
569      SCM get_selected_component_attributes(gpointer data,               
570                                       guint callback_action,    
571                                       GtkWidget *widget)
573    How the name is saying, this functions returns all attributes of
574    the selected component. It is realized with a simple while loop
575    over all objects of the schematic, which picked out all elements
576    where the selected flag is set.
579    2.2.3.2. CODE-ADAPTATION
581    Here are some actions you must conclude to makes the software
582    runable.
584    (1) new lines in /gschem/src/g_register.c
586         gh_new_procedure0_0 ("get-selected-filename",g_get_selected_filename);
589    (2) new lines in /gschem/include/prototype.h
591         SCM g_get_selected_filename();
594    (3) copy the file misc_for_gnetlist.c to gschem/src 
596    (4) add in file /gschem/src/Makefile.in or directly in Makefile.
598        (if you have edited Makefile.in you must run make config of
599        course)
601         - add "misc_for_gnetlist.c" to gschem_SOURCES - variable
602         - add "misc_for_gnetlist.o" to gschem_OBJECTS - variable
604    (5) add new lines in /gschem/src/g_key.c
605         
606          SCM g_get_selected_filename(void)                      
607          {                                                      
608            return (get_selected_filename(window_current, 0, NULL));
609          }
612    (6) compile your changed c-code newly