UP

# TUTORIAL: Use symgen.awk to create symbols from 'djboxsym' compatible text files

The `symgen.awk` utility (installed in `(install_root)/share/xschem`) generates xschem symbol files from a textual description that is backward compatible to DJ Delorie's perl djboxsym symbol generator for the geda schematic editor (gschem, lepton-schematic). A sample `sample.symdef` file is the following:

    # This is a sample symbol definition for documenting djboxsym.  Some
    # of the pins have been intentionally mistyped in order to demonstrate
    # all combinations of flags.  DO NOT USE AS A CP2201 REFERENCE!

    [labels]

    SAMPLE
    refdes=U?
    DEMO ONLY
    ! copryright=2006 DJ Delorie
    ! author=DJ Delorie
    ! uselicense=unlimited
    ! distlicense=GPL
    ! device=sample device
    ! description=ethernet controller
    ! footprint=QFN-28

    [left]
    24 ! CS
    .bus
    11  AD0
    12  AD1
    13  AD2
    14  AD3
    15  AD4
    16  AD4
    17  AD6
    18  AD7

    21 > ALE
    22 ! RD/(DS)
    23 !> WR/(R/!W)

    25 ! INT
    29  \_RESET\_

    [right]
    10 ! RST
    26 > MOTEN
    1 !> LA

    6 TX+
    7 TX-

    5 RX+
    4 RX-

    28 XTAL1
    27 XTAL2
    [top]
    3 AV+
    8 VDD1
    30 !> \_CLK\_
    19 VDD2

    [bottom]
    2 AGND
    9 DGND1
    20 DGND2

Creating the symbol is simple:
`<install_path>/share/xschem/symgen.awk sample.symdef > sample.sym`
The resulting symbol is shown here under, side-compared with the same symbol generated by djboxsym for gschem:

Another `sample2.symdef` file specifically created to generate a perfectly valid xschem symbol (including attributes for spice netlisting) is the following:

    #  <pinnumber>  <direction>[<circle><edge_trigger>] <name>
    # circle: !
    # edge_trigger: >
    # direction is mandatory: i=input, o=output, b=bidirectional (inout)

    [labels]
    FAKE IC TO TEST XSCHEM SYMGEN
    STEFAN FREDERIK SCHIPPERS
    @symname
    @name
    ! type=subcircuit
    ! format="@name @pinlist @symname"
    ! template="name=x1"
    --vmode
    [left]
    24   i!   CHIP_SELECT
    .bus
    11   i    AD0
    12   i    AD1
    13   i    AD2
    14   i    AD3
    15   i    AD4
    16   i    AD5
    17   i    AD6
    18   i    AD7

    21   i>   ALE

    22   i!   \_RD\_
    23   i!>  \_WR\_
    25   i!   INTERRUPT_REQUEST
    [right]
    10   i!   RST
    26   i>   MOTEN
    1    i!>  LA
    6    o    TXP
    7    o    TXM

    5    i    RXP
    4    i    RXM
    28   i    XTAL1
    27   i    XTAL2
    [top]
    3    io    AVP
    .bus
    29  o!    DATA0
    30  o!    DATA1
    31  o!    DATA2
    32  o     DATA3
    33  o     DATA4
    34  o!    DATA5
    35  o!    DATA6
    36  o!    DATA7
    37  o!    DATA8
    38  o     DATA9
    39  o>    DATA10
    40  o>    DATA11
    41  o>    DATA12
    42  o     DATA13
    43  o     DATA14
    44  o     DATA15

    8    io    VDD1
    19   io    VDD2
    45   io    VDD_ANALOG
    46   io    VDD_DIGITAL
    [bottom]
    2    io!   GND_ANALOG
    47   io!   GND_DIGITAL
    9    io>   DGND1
    20   io>   GND2

some extensions of xschem's symdef text file format with respect to original djboxsym format:

- In addition to optional `!` (inversion bubble) and `>` (edge trigger) specifiers XSCHEM's `symgen.awk` accepts a pin direction specifier, `i`, `o`, `io` and `p` (latter one for power pins, treated by xschem as inout) for 'input', 'output', 'inout' (bidirectional) direction and 'power'. These attributes are fundamental for digital simulations (Verilog, Vhdl). If this specifier is missing (as it is in djboxsym .symdef files) then the direction is assumed as `b` (inout). XSCHEM does not have any specific direction for power pins so they are treated as 'inout'
  Port direction specifiers are indeed supported also by 'djboxsym' but not documented.
- Option `--vmode` given before any pin declaration like in djboxsym sets vertical orientation for top / bottom pins.
- `.bus` specifier can be used for all pin orientations, left, top, right, bottom if `--vmode` is enabled, otherwise it will affect only spacing of left/right pins.
- Option `--auto_pinnumber` given before any pin declaration lets `symgen.awk` automatically add pin numbers, so the first field may be omitted
- Edge trigger (>) and inversion bubble (!) specifiers are drawn on all sides, not only left/right.
- Option `--hide_pinnumber` given before any pin declaration avoids pin numbers in generated symbol. If this option is used it is mostly done together with `--auto_pinnumber` to get rid of pin numbers completely.