gnetlist/docs/vams/vams_mode.txt

   1 date: 10 october 2000
   2 gEDA: gnetlist vams mode
   3 first unrevised vams mode documentation
   4
   5
   6 Written by: Martin Lehmann
   7 -------------------------------------------------------------------------
   8
   9
  10 VHDL-AMS support for the gEDA gnetlist tool
  11 -------------------------------------------
  12
  13 CONTENT:
  14
  15    1. functionality
  16       1. ARCHITECTURE generation
  17       2. ENTITY generation
  18       3. automatisate gnetlist calls
  19
  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
  27
  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
  42
  43    The purpose of our endevour, is that gEDA gnelist completly
  44    supportted VHDL-AMS (VHDL Analog and Mixed-Signal) netlist
  45    generation.
  46
  47    The VHDL-AMS netlist support mode is called vams.
  48
  49
  50    1. FUNCTIONALITY
  51
  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.
  56
  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).
  62
  63    Now follows a stepwise discription of the program run in both
  64    submodes.
  65
  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
  76
  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>).
  81
  82
  83      ARCHITECTURE <architecture-identifier> OF <entity-identifier> IS
  84
  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).
  90
  91
  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.
 105
 106
 107      BEGIN
 108
 109    Ok. it's only marks the start of the architecture body.
 110
 111
 112      {<label> : ENTITY <entity> [(<architecture>)]
 113             [GENERIC MAP (<set generic> => <generic-value>
 114                          {; <set-generic=> <generic-value>})]
 115             PORT MAP ( <pin-name> => <subnet-name>{; <.. => ..>});}
 116
 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).
 128
 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 :
 133
 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 :
 140
 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).
 146
 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.
 154
 155
 156      END ARCHITECTURE <architecture-identifier>;
 157
 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.
 161
 162    ==================================================================
 163
 164    1.2. ENTITY GENERATION
 165
 166
 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).
 173
 174
 175      LIBRARY <library-identifier>{,<library-identifier>};
 176      USE     <package-identidier>{,<package-identifier>};
 177
 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.
 185
 186
 187      ENTITY <entity-identifier> IS
 188          [genric_clause]
 189          [port_clause]
 190      END ENTITY;
 191
 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.
 196
 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).
 202
 203
 204      generic_clause :=
 205                GENERIC ( <generic-identifier> : REAL := <default-value>
 206                         {;<generic-identifier> : REAL := <default-value>});
 207
 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).
 216
 217
 218      port_clause :=
 219             PORT (<port-kind> <port-identifier> : [<port-mode>] <port-type>
 220                   {;<port-kind> <port-identifier> : [<port-mode>] <port-type>});
 221
 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    ===================================================================
 230
 231    1.3. AUTOMATISATING gnetlist CALLS
 232
 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 !!
 246
 247    ===================================================================
 248
 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.
 255
 256
 257    2.1. THE VAMS MODE OF gEDA gnetlist
 258
 259    To realize gnetlist VHDL-AMS support, it was necessary to create
 260    new scheme and c stuff.
 261
 262
 263    2.1.1. SCHEME
 264
 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.
 268
 269
 270    2.1.1.1. SETTINGS AND NEW DEFINITIONS
 271
 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.
 276
 277              (define-module (ice-9 ls) :use-module (ice-9 common-list)
 278                                        :use-module (ice-9 string-fun))
 279
 280            - load main file for VHDL-AMS support, which contents the
 281              startup procedure vams.
 282
 283              (load "<path_of_gnet-vams.scm>/gnet-vams.scm")
 284
 285
 286    2.1.1.2. gnet-vams.scm
 287
 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
 295
 296       ...
 297
 298
 299    2.1.2.1. ROUTINES MAIN STRUCTURE
 300
 301    the mainly functions structure looks like:
 302
 303    - (vams output-filename)
 304
 305      ARCHITECTURE generation
 306
 307         - (vams:write-secondary-unit architecture entity  output-port)
 308
 309             - (vams:write-architecture-declarative-part output-port)
 310                   - (vams:write-signal-declarations output-port)
 311
 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)
 315
 316      ENTITY declaraction
 317
 318          - (vams:write-primary-unit entity port-list generic-list output-port)
 319
 320              - (vams:write-context-clause output-port)
 321
 322              - (vams:write-generic-clause generic-list output-port)
 323                   - (vams:write-generic-list generic-list output-port)
 324
 325              - (vams:write-port-clause port-list output-port)
 326                   - (vams:write-port-list port-list output-port)
 327
 328
 329    2.1.1.3 HELPFULLY SETTING IN THE gEDA gschem ENVIRONMENT
 330
 331    This settings are not absolutly necessary, but they makes work
 332    easier.
 333
 334         - set in .gEDA/gschemrc or wherever you want, but place it
 335           right.
 336
 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")
 346
 347
 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.
 352
 353
 354    2.1.2.1 NEW ROUTINES (saved in vams_misc.c)
 355
 356
 357      SCM vams_get_package_attributes(SCM scm_uref)
 358
 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.
 363
 364    We needs this functionality to produce a currectly
 365    VHDL-AMS GENERIC MAP.
 366
 367
 368      SCM vams_get_attribs_list(OBJECT *object)
 369
 370    It exists only for the support of the first function.
 371
 372
 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
 384
 385      (2) gnetlist/include/prototype.h
 386
 387            SCM vams_get_package_attributes(SCM scm_uref);
 388
 389
 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/
 399
 400      (5) compile your code newly
 401
 402    ===================================================================
 403
 404    2.2. AUTOMATIC GENERATING gnetlist CALLS IN gEDA gschem
 405
 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.
 419
 420         (2) the top-attribs list, which contents all attached
 421             attributes of the selected component.
 422
 423         (3) the generate-mode, which is defined by the users actions.
 424
 425
 426    2.2.1. STRUCTURE OF gEDA gnetlist CALLS FROM COMMANDLINE OR FROM gEDA
 427           gschem.
 428
 429      typical commandline call :
 430
 431                 gnetlist [-o <output-filename>]
 432                          -g vams
 433                          <schematic-file>
 434
 435    There are nothing to explain. The top-attribs list and the
 436    generate-mode variable are default defined ('() and 1).
 437
 438
 439    calls from gEDA gschem (3 possible variations) :
 440
 441
 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.
 446
 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>
 456
 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.
 463
 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.
 469
 470
 471               gnetlist -c <scheme-comm>
 472                        -o <vhdl-path>/<target-file>
 473                        -g vams
 474                        <source-file>
 475
 476                   scheme-comm="(define top-attribs '<top-attribs>)
 477                                (define generate-mode '2)"
 478
 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.
 488
 489        (3) hot-key-stroke: - g e (generate-entity)
 490            and only one component is selected.
 491
 492            --> generates an ENTITY of the selected schematic.
 493
 494
 495                commandline is the same as in (2).
 496
 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.
 504
 505    2.2.2. SCHEME
 506
 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.
 513
 514
 515    2.2.2.1. generate_netlist.scm
 516
 517
 518    2.2.2.2. SETTINGS
 519
 520    If you want use the new feature then you must do some entries in one
 521    of your gEDA gschem rc-files
 522
 523      necessary defines:
 524
 525          - in system-gschemrc
 526
 527                     ("g" . gnetlist-keymap)
 528
 529            Edit your global-keymap and if "g" always defined then find
 530            out an other free hot-key-stroke.
 531
 532            Note: the documentation supports the "g" - key only.
 533
 534
 535          - in one of the gschem startup files
 536
 537              (define gnetlist-keymap
 538                '(("n" . generate-netlist)
 539                  ("e" . generate-entity)))
 540
 541
 542      loads :
 543
 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.
 552
 553
 554    2.2.3.1. ROUTINES
 555
 556    It exists two new c-functions. Both are put down in
 557    misc_for_gnetlist.c.
 558
 559
 560      SCM get_selected_filename(gpointer data,
 561                           guint callback_action,
 562                           GtkWidget *widget)
 563
 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.
 567
 568
 569      SCM get_selected_component_attributes(gpointer data,
 570                                       guint callback_action,
 571                                       GtkWidget *widget)
 572
 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.
 577
 578
 579    2.2.3.2. CODE-ADAPTATION
 580
 581    Here are some actions you must conclude to makes the software
 582    runable.
 583
 584    (1) new lines in /gschem/src/g_register.c
 585
 586         gh_new_procedure0_0 ("get-selected-filename",g_get_selected_filename);
 587
 588
 589    (2) new lines in /gschem/include/prototype.h
 590
 591         SCM g_get_selected_filename();
 592
 593
 594    (3) copy the file misc_for_gnetlist.c to gschem/src
 595
 596    (4) add in file /gschem/src/Makefile.in or directly in Makefile.
 597
 598        (if you have edited Makefile.in you must run make config of
 599        course)
 600
 601         - add "misc_for_gnetlist.c" to gschem_SOURCES - variable
 602         - add "misc_for_gnetlist.o" to gschem_OBJECTS - variable
 603
 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          }
 610
 611
 612    (6) compile your changed c-code newly
 613
 614