Руководство пользователя 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. gEDA - родной формат gEDA, используемый главным образом для тестирования
  6. Формат списка соединений Gossip
  7. Формат списка соединений PADS
  8. Формат списка соединений ProtelII
  9. SPICE-совместимый формат списка соединений
  10. Формат списка соединений Tango
  11. Код Verilog
  12. Код VHDL
  13. Формат списка соединений VIPEC
  14. Формат списка соединений 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 нужно указать два параметра:

В командной строке можно указать несколько схем. По умолчанию для вывода созданного списка соединений используется имя файла 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 атрибуты повсюду используются для представления информации. Атрибуты — это единственный способ добавления информации для компонентов, соединений, выводов и т. д. Для получения более подробной информации об атрибутах, упомянутых в данном документе, обратитесь к странице документации Перечень основных атрибутов.

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

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

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

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

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)
  %