# Руководство пользователя gEDA gnetlist

Автор: Ales Hvezda

Настоящий документ выпущен под лицензией GFDL

21 сентября, 2003 г.

## Введение

В настоящем документе описывается использование gnetlist. И настоящий документ, и вообще gnetlist находятся в состоянии альфа-версии, так что имейте это в виду при создании списков соединений с его помощью. Каждому инженеру известно, что ни в коем случае нельзя слепо доверять программным средствам и считать, что они всегда дают верный результат. gnetlist определённо не является исключением из этого правила. Очень важно проверять каждый из создаваемых вами списков соединений. Как и большинство программ (в том числе все программы gEDA), gnetlist поставляется БЕЗ КАКИХ БЫ ТО НИ БЫЛО ГАРАНТИЙ. Я ненавижу, что приходится это говорить, но, надеюсь, данное предупреждение удержит пользователя от мнения, что gnetlist создаёт идеальные списки соединений. Тем не менее, если вы найдёте ошибку, дайте мне знать по адресу ahvezda@geda.seul.org.
Настоящий документ очень сырой, так что посылайте все исправления на ahvezda@geda.seul.org или заполните отчёт об ошибке на домашней странице gEDA http://www.geda-project.org. Спасибо!

## Обзор

gnetlist — это генератор списка соединений gEDA. Он принимает на входе файлы схем и производит списки соединений. Список соединений является текстовым представлением схемы. Это текстовое представление полностью описывает все соединения между устройствами. Это означает, что все подключения, относящиеся к одному соединению группируются вместе. Генератор списка соединений обрабатывает также иерархически связанные схемы.
gnetlist имеет очень гибкую архитектуру. Основная программа, написанная на C, читает схему (используя подпрограммы из libgeda) и создаёт внутреннее представление данных схемы. Это внутреннее представление дальше обрабатывается низкоуровневыми модулями (драйверами), ответственными за вывод списков соединений в различных форматах. Драйверы для каждого формата написаны на языке Scheme (а конкретнее, на его разновидности Guile). Данная архитектура не только допускает бесчисленное количество форматов списков соединений, но и позволяет генератору списка соединений создавать другие документы (например, перечни элементов).
С версии 20001006 gnetlist имеет драйверы на Scheme для поддержки следующих форматов:

1. PCB & PCBboard - формат списка соединений UNIX PCB.
2. Формат списка соединений Allegro
3. Формат списка соединений BAE
4. BOM & BOM2 - генератор перечня элементов (BOM)
5. DRC - Запуск проверки на соответствие проектным нормам
6. gEDA - родной формат gEDA, используемый главным образом для тестирования
7. Формат списка соединений Gossip
8. Формат списка соединений PADS
9. Формат списка соединений ProtelII
10. SPICE-совместимый формат списка соединений
11. Формат списка соединений Tango
12. Код Verilog
13. Код VHDL
14. Формат списка соединений VIPEC
15. Формат списка соединений VAMS - VHDL-AMS

Этот список постоянно растёт. Несколько отсутствующих возможностей (на момент версии 20001006): отсутствует поддержка шин, определение ошибок и сообщения о них весьма ограничены,… и многое другое.

## Установка

Надеюсь, что программа gnetlist уже установлена на вашей машине. В данном документе установка не описывается. Свою установку можно проверить запуском:

    libgeda-config --version
    gesym-config --version
    which gnetlist
    ldd `which gnetlist`

Первые две команды должны показать версии установленных программ (libgeda и библиотеки символов), следующая команда должна выдать путь к двоичному файлу gnetlist. Последняя команда покажет, какие библиотеки подключаются к gnetlist (только на Unix-подобных операционных системах, в которых есть утилита ldd, предназначенная для вывода динамических зависимостей исполняемых файлов или совместно используемых объектов); чтобы программа gnetlist смогла запуститься, все запрашиваемые библиотеки должны быть найдены. Если эти команды не дают ожидаемых результатов, скорее всего, программы gEDA не установлены должным образом. Более подробную информацию по установке программ gEDA можно найти в соответствующих документах INSTALL (входящих в дистрибутив).

## Запуск gnetlist

Запуск gnetlist очень прост. У программы gnetlist простой интерфейс командной строки, так что нет никакого докучного GUI для работы с ней . Для получения списка аргументов командной строки запустите `gnetlist -h`.
Для запуска gnetlist нужно указать два параметра:

- `-g guile_procedure` (определяет драйвер, который надо запустить для схем)
- `filename.sch` (определяет файлы схем)

В командной строке можно указать несколько схем. По умолчанию для вывода созданного списка соединений используется имя файла `output.net`. Можно изменить это умолчание указанием ключа `-o filename`.
Примеры запуска gnetlist:

    gnetlist -g geda -o stack.net stack_1.sch

(выводит список соединений для схемы `stack_1.sch` в `stack.net`, используя родной формат gEDA)

Есть также несколько ключей для отладки. Первый из них — это ключ `-v`, включающий режим вывода подробной информации. В этом режиме выводится большой объём информации о том, что делает gnetlist, а также дамп внутреннего представления данных. Ключ `-i`, переводящий gnetlist в интерактивный режим, очень полезен для отладки драйверов на Scheme, он обычно не используется конечными пользователями.
Аргументы командной строки подробно описаны в man-странице gnetlist.

## Требования к схемам/символам

В данном разделе рассматривается вопрос о том, что должно быть в схемах/символах, чтобы программа gnetlist могла с ними работать. Чтобы программа gnetlist работала корректно, и схема, и поддерживаемые символы должны быть правильны. В основном это требование относится к определению атрибутов. В системе gEDA атрибуты повсюду используются для представления информации. Атрибуты — это единственный способ добавления информации для компонентов, соединений, выводов и т. д. Для получения более подробной информации об атрибутах, упомянутых в данном документе, обратитесь к странице документации Перечень основных атрибутов.

### Требования к символам

- Каждый символ должен иметь атрибут `device=`.
- Каждый вывод должен иметь атрибут `pin#=#`. Этот атрибут со временем изменит форму, но сейчас он должен быть в виде `pin#=#`.
- Также каждый вывод должен иметь атрибут `pinlabel=`.
- Для символов, определяющих многосекционные компоненты, состоящие из нескольких секций, необходим атрибут `slot=`, атрибут `slot#=#` для каждого элемента и атрибут `numslots=#`. Назначение секций компонентов также изменится в ближайшем будущем, но сейчас оно должно описываться указанным способом.
- Для любых соединений питания и специальных соединений необходимо указать атрибуты `net=` внутри символа. Более подробную информацию об этом см. в Мини-HOWTO по атрибуту net=.
- Для различных параметров (в зависимости от того, какой драйвер вы используете) можно задать значения по умолчанию, воспользовавшись механизмом “выноса” атрибутов. Более подробная информация находится ниже, а также в документации по gschem.
- Если нужно, чтобы какие-то символы полностью игнорировались генератором списка соединений, задайте для них атрибут `graphical=1`.
- Больше советов по символам можно найти в Руководстве по созданию символов.

### Требования к схемам

- Самое важное, что каждый компонент, который должен отображаться в списке соединений, должен иметь атрибут `refdes=`. Это ОЧЕНЬ важно. Программа gnetlist должна предупредить вас, если вы используете компонент, в котором нет `refdes=`, но ранее уже бывали программные ошибки, из-за которых такое предупреждение могло не появиться.
- Для любого из соединений можно создать метку с помощью атрибута `label=`. Эту метку нужно прикрепить только к одному сегменту соединения, чтобы все сегменты данного соединения (электрически связанные с ним) унаследовали эту метку.
- В одном проекте может быть несколько принципиальных схем (на самом деле термин “проект” сбивает людей с толку, так как каждый понимает его по-своему). Чтобы использовать несколько схем для создания одного списка соединений, надо просто задать их в командной строке gnetlist.
- Если назвать соединения одинаково, они будут считаться электрически связанными. Одинаковые имена соединений распространяются на все заданные схемы.
- Есть кое-какие проблемы, относящиеся к иерархии. Обратитесь к приведённому ниже разделу по иерархии.

### Прочие примечания

- Атрибуты, находящиеся внутри символа, но ни к чему там не прикрепленные, “выносятся” вовне символа, когда он помещается в схему (в gschem). Эти “вынесенные” атрибуты всегда проверяются/ищутся до того, как перейти внутрь символа. То есть, иными словами, если к экземпляру компонента снаружи прикреплён атрибут, одноимённый с атрибутом внутри его символа, то приоритет отдаётся внешнему атрибуту.

## Поддержка иерархии

TBA

## Информация, специфичная для драйверов

TBA

## API драйвера в Scheme

Обратите внимание, что данный раздел всё ещё находится в стадии развития. Приведённая здесь информация должна быть верной, но не является полной.

### Обзор

gnetlist выполняет загрузку базы данных схемы из файлов `.sch`, строит внутреннее представление, а затем вызывает функцию, специфичную для указанного типа выходного списка соединений, которая и создаёт фактический список соединений. Каждый драйвер gnetlist содержится в файле, называемом `gnet-<backend>.scm`. Где <backend> – это имя отдельного драйвера. Например, `gnet-switcap.scm` содержит код, используемый командой `gnetlist -g switcap`, а `gnet-drc.scm` содержит код, используемый командой `gnetlist -g drc`. Драйверы написаны на языке программирования Scheme. Частная реализация Scheme — это Guile, что означает “GNU's Ubiquitous Intelligent Language for Extensions” (“вездесущий интеллектуальный язык GNU для расширений”). Больше информации по Guile можно найти на http://www.gnu.org/software/guile/guile.html.

### Входная функция

Каждый из драйверов списков соединений обязан предоставлять функцию, имя которой соответствует типу его списка соединений. Например, драйвер switcap, содержащийся в gnet-switcap.scm должен иметь функцию, называемую `switcap`. Это та функция, которую вызовет gnetlist, чтобы инициировать создание списка соединений. Входной функции задаётся один аргумент, представляющий собой имя файла выходного списка соединений. Обычно первое, что генератор списка соединений делает, это открывает данный файл на запись.
В следующем отрывке из драйвера switcap показано начало входной функции, где открывается выходной файл, и её конец, где этот файл закрывается.

    ;; ---------------------------------------
    ;; Switcap netlist generation -- top level
    ;; ---------------------------------------
    (define switcap
      (lambda (output-filename)
        (let ((port (open-output-file output-filename)))

    ;; rest of netlisting goes here

    ;; close the output file and return
          (close-output-port port))))

### Инициализация драйвера

После открытия выходного списка соединений производятся все необходимые действия по специфической инициализации, которые должны выполняться для списков соединений данного конкретного типа. В примере со switcap мы должны инициализировать имя соединения и базу данных псевдонимов позиционных обозначений (`refdes`). Это нужно потому, что switcap предъявляет более строгие требования к именам соединений, чем gschem. Кроме того, switcap предъявляет особые требования к позиционным обозначениям списка соединений. Для таких ситуаций gnetlist предоставляет некоторые функции общего назначения, переименовывающие соединения и позиционные обозначения так, чтобы они соответствовали требованиям целевого списка соединений. Подробнее об этом позже. А пока просто отметьте, что в драйвере switcap используется следующий код:

    ;; initialize the net-name aliasing
    (gnetlist:build-net-aliases switcap:map-net-names
        all-unique-nets)

    ;; initialize the refdes aliasing
    (gnetlist:build-refdes-aliases switcap:map-refdes
        packages)

Другая инициализация, которая хотя и не требуется для всех типов списков соединений, но обычно производится, состоит в выводе некоторого рода заголовка. Этот заголовок может либо явно содержаться во входной функции, либо, для ясности кода, может быть вынесен в свою собственную функцию. В драйвере switcap вызов такой:

    (switcap:write-top-header port)

Учтите, что существует соглашение о том, что имена любых специфических функций драйвера должны содержать префикс в виде имени этого драйвера. Например, все специфические для switcap функции начинаются со `switcap:`. Функции, пригодные для всех драйверов и предоставляемые программой gnetlist, имеют префикс `gnetlist:`.
`switcap:write-top-header` определяется следующим образом:

    ;;
    ;; Switcap netlist header
    ;;
    (define switcap:write-top-header
      (lambda (port)
        (display
          "/* Switcap netlist produced by gnetlist (part of gEDA) */\n"
          port)
        (display
          "/* See http://www.geda.seul.org for more information. */\n"
          port)
        (display
          "/* Switcap backend written by Dan McMahill            */\n"
          port)
        (display "\n\n" port)
        )
      )

Далее входная функция вызывает функции для каждого раздела выходного списка соединений. В gnetlist зарезервированы некоторые имена переменных: переменная `packages` представляет собой список всех компонентов, а `all-unique-nets` — список всех соединений в проекте. Эти переменные будут использоваться в различных функциях, используемых драйвером для каждого раздела списка соединений. Например, основная часть списка соединений switcap, содержащая компоненты и их соединения, записывается в выходной файл так:

    (switcap:write-netlist port packages)

### Псевдонимы имён соединений и позиционных обозначений

Обычно в драйверах для целевых типов списков соединений к именам соединений предъявляются более строгие требования, чем в gschem. Могут быть, например, ограничения на длину, разрешённые символы или их регистр. Для решения данной проблемы gnetlist предоставляет возможность использования псевдонимов имён соединений. Для использования этой возможности в разделе инициализации входной функции вызывается функция `gnetlist:build-netaliases`.
Например, в драйвере switcap:

    ;; initialize the net-name aliasing
    (gnetlist:build-net-aliases switcap:map-net-names
        all-unique-nets)

Функция `switcap:map-net-names` является функцией, специфической для драйвера (в данном случае `switcap`), которая принимает в качестве аргумента имя соединения gschem и возвращает изменённое имя, удовлетворяющее требованиям формата выходного списка соединений. В случае switcap требования следующие: “земля” называется “0”, имена соединений имеют не больше 7 знаков и код списка соединений регистронезависим.

    ;; This procedure takes a net name as determined by
    ;; gnetlist and modifies it to be a valid SWITCAP net name.
    ;;
    (define switcap:map-net-names
      (lambda (net-name)
        (let ((rx (make-regexp "^unnamed_net"))
              (net-alias net-name)
              )
          ;; XXX we should use a dynamic regexp based on the
          ;; current value for the unnamed net base string.

          (cond
           ;; Change "GND" to "0"
           ((string=? net-name "GND") (set! net-alias "0"))
           ;; remove the 'unnamed_net' part
           ((regexp-exec rx net-name)
               (set! net-alias (substring net-name 11)))
           (else net-name)
           )

          ;; Truncate to 7 characters
          (if (> (string-length net-alias) 7)
              (set! net-alias (substring net-alias 0 7))
              )

      ;; Convert to all upper case
      (string-upcase net-alias)

      )
     )
    )

Функцией `gnetlist:build-net-aliases` создаётся база данных, в которой позже можно будет производить поиск имени выходного соединения по имени соединения в gschem или имени соединения в gschem по имени выходного соединения. Кроме того, эта функция выполняет очень важную задачу обеспечения отсутствия коротких замыканий при изменении имён соединений. В качестве примера предположим, что у вас в схеме есть соединение с именем “MyNet”, и ещё одно — с именем “mynet”. Они уникальны, но после преобразования обоих в верхний регистр, они станут одним соединением. `gnetlist:build-net-aliases` определит это условие, выдаст ошибку и остановит создание списка соединений.
Теперь, когда база данных инициализирована, для нахождения имени в списке соединений по имени соединения в gschem, генератор списка соединений просто использует:

    (gnetlist:alias-net somenet)

Подобный набор функций предоставляется и для псевдонимов позиционных обозначений.

### Советы по отладке

Полезным средством для отладки является запуск gnetlist в интерактивном режиме. Для gnetlist этот режим запускается с помощью ключа `-i`. При этом появится оболочка, где можно будет вводить команды Scheme. Это простой способ проверки различных переменных и тестирования разных функций.
Пример запуска gnetlist в интерактивном режиме приведён ниже.

    % gnetlist -i ../../gnetlist/examples/switcap/*.sch
    gEDA/gnetlist version 20041228
    gEDA/gnetlist comes with ABSOLUTELY NO WARRANTY; see COPYING for more details.
    This is free software, and you are welcome to redistribute it under certain
    conditions; please see the COPYING file for more details.

    Loading schematic [../../gnetlist/examples/switcap/analysis.sch]
    Loading schematic [../../gnetlist/examples/switcap/ckt.sch]
    Loading schematic [../../gnetlist/examples/switcap/clocks.sch]
    gnetlist> all-unique-nets
      ("unnamed_net6" "unnamed_net5" "unnamed_net4" "OUT" "unnamed_net3"
       "unnamed_net2" "unnamed_net1" "GND")
      gnetlist> packages
      ("TIMING" "CLK1" "S7" "S8" "S6" "S5" "C3" "S4" "C2" "C1" "E1" "S3"
       "S1" "V1" "S2" "OPTIONS" "TITLE" "ANA1")
      gnetlist> (quit)
      %