gEDA Project Wiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Руководство пользователя gEDA gnetlist ======
Автор: Ales Hvezda

Настоящий документ выпущен под лицензией
[[http://www.gnu.org/copyleft/fdl.html|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**). Данная архитектура не только допускает бесчисленное
количество форматов списков соединений, но и позволяет генератору списка
соединений создавать другие документы (например,
[[geda:glossary.ru#Перечень элементов|перечни элементов]]).\\
С версии 20001006 **gnetlist** имеет драйверы на **Scheme** для поддержки
следующих форматов:
  - **PCB** & **PCBboard** - формат списка соединений UNIX **PCB**.
  - Формат списка соединений  **Allegro**
  - Формат списка соединений  **BAE**
  - **BOM** & **BOM2** - генератор перечня элементов (BOM)
  - **DRC** - Запуск [[geda:glossary.ru#Проверка соответствия проектным нормам|проверки на соответствие проектным нормам]]
  - **gEDA** - родной формат gEDA, используемый главным образом для тестирования
  - Формат списка соединений  **Gossip**
  - Формат списка соединений  **PADS**
  - Формат списка соединений  **ProtelII**
  - [[geda:glossary.ru#SPICE]]-совместимый формат списка соединений
  - Формат списка соединений  **Tango**
  - Код **Verilog**
  - Код **VHDL**
  - Формат списка соединений  **VIPEC**
  - Формат списка соединений  **VAMS** - **VHDL-AMS**

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

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

<code>libgeda-config --version
gesym-config --version
which gnetlist
ldd `which gnetlist`</code>

Первые две команды должны показать версии установленных программ (**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**:
<code>gnetlist -g geda -o stack.net stack_1.sch</code>

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

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

===== Требования к схемам/символам =====
В данном разделе рассматривается вопрос о том, что должно быть в схемах/символах, чтобы
программа **gnetlist** могла с ними работать. Чтобы программа **gnetlist** работала корректно, и
схема, и поддерживаемые символы должны быть правильны. В основном это
требование относится к определению атрибутов. В системе gEDA атрибуты
повсюду используются для представления информации. Атрибуты --- это
единственный способ добавления информации для компонентов, соединений, выводов
и т. д. Для получения более подробной информации об атрибутах, упомянутых в
данном документе, обратитесь к странице документации
[[gEDA:master_attributes_list.ru|Перечень основных атрибутов]].


==== Требования к символам ====
  * Каждый символ должен иметь атрибут ''device=''.
  * Каждый вывод должен иметь атрибут ''pin#=#''. Этот атрибут со временем изменит форму, но сейчас он должен быть в виде ''pin#=#''.
  * Также каждый вывод должен иметь атрибут ''pinlabel=''.
  * Для символов, определяющих [[geda:glossary.ru#Многосекционный компонент|многосекционные компоненты]], состоящие из нескольких [[geda:glossary.ru#Секция компонента|секций]], необходим атрибут ''slot='', атрибут ''slot#=#'' для каждого элемента и атрибут ''numslots=#''. Разбивка на элементы также изменится в ближайшем будущем, но сейчас она должна описываться указанным способом.
  * Для любых соединений питания и специальных соединений необходимо указать атрибуты ''net='' внутри символа. Более подробную информацию об этом см. в [[geda:na_howto.ru|Мини-HOWTO по атрибуту net=]].
  * Для различных параметров (в зависимости от того, какой драйвер вы используете) можно задать значения по умолчанию, воспользовавшись механизмом "выноса" атрибутов. Более подробная информация находится ниже, а также в документации по **gschem**.
  * Если нужно, чтобы какие-то символы полностью игнорировались генератором списка соединений, задайте для них атрибут ''graphical=1''.
  * Больше советов по символам можно найти в [[gEDA:gschem_symbol_creation.ru|Руководстве по созданию символов]].

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

  * Самое важное, что каждый компонент, который должен отображаться в списке соединений, должен иметь атрибут ''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** показано начало входной функции,
где открывается выходной файл, и её конец, где этот файл закрывается.
<code>;; ---------------------------------------
;; 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))))</code>

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

<code>;; 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)</code>

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

<code>(switcap:write-top-header port)</code>

Учтите, что существует соглашение о том, что имена любых специфических функций
драйвера  должны содержать префикс в виде имени этого драйвера. Например, все
специфические для **switcap** функции начинаются со ''switcap:''. Функции,
пригодные для всех драйверов и предоставляемые программой
**gnetlist**, имеют префикс ''gnetlist:''.\\
''switcap:write-top-header'' определяется следующим образом:
<code>;;
;; 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)
    )
  )</code>

Далее входная функция вызывает функции для каждого раздела выходного списка
соединений. В **gnetlist** зарезервированы некоторые имена переменных: переменная ''packages''
представляет собой список всех компонентов, а ''all-unique-nets'' ---
список всех соединений в проекте. Эти переменные будут использоваться в
различных функциях, используемых драйвером для каждого раздела списка
соединений.
Например, основная часть списка соединений **switcap**, содержащая компоненты
и их соединения, записывается в выходной файл так:
<code>(switcap:write-netlist port packages)</code>

==== Псевдонимы имён соединений и позиционных обозначений ====
Обычно в драйверах для целевых типов списков соединений к именам соединений предъявляются
более строгие требования, чем в **gschem**. Могут быть, например, ограничения на
длину, разрешённые символы или их регистр. Для решения данной проблемы
**gnetlist** предоставляет возможность использования псевдонимов имён
соединений. Для использования этой возможности в разделе инициализации
входной функции вызывается функция ''gnetlist:build-netaliases''.\\
Например, в драйвере **switcap**:
<code>;; initialize the net-name aliasing
(gnetlist:build-net-aliases switcap:map-net-names
    all-unique-nets)</code>

Функция ''switcap:map-net-names'' является функцией, специфической для
драйвера (в данном случае ''switcap''), которая принимает в качестве аргумента
имя соединения **gschem** и возвращает изменённое имя,
удовлетворяющее требованиям формата выходного списка соединений. В случае **switcap**
требования следующие: "земля" называется "0", имена соединений имеют не больше 7
знаков и код списка соединений регистронезависим.
<code>;; 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)

  )
 )
)</code>

Функцией ''gnetlist:build-net-aliases'' создаётся база данных, в которой позже
можно будет производить поиск имени выходного соединения по имени соединения в
**gschem** или имени соединения в **gschem** по имени выходного
соединения. Кроме того, эта функция выполняет очень важную задачу обеспечения
отсутствия коротких замыканий при изменении имён соединений. В качестве
примера предположим, что у вас в схеме есть соединение с именем "MyNet", и
ещё одно --- с именем "mynet". Они уникальны, но после преобразования обоих
в верхний регистр, они станут одним соединением.
''gnetlist:build-net-aliases'' определит это условие, выдаст ошибку и
остановит создание списка соединений.\\
Теперь, когда база данных инициализирована, для нахождения имени
в списке соединений по имени соединения в **gschem**, генератор списка соединений
просто использует:
<code>(gnetlist:alias-net somenet)</code>

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

==== Советы по отладке ====
Полезным средством для отладки является запуск **gnetlist** в интерактивном
режиме. Для **gnetlist** этот режим запускается с помощью ключа ''-i''. При
этом появится оболочка, где можно будет вводить команды **Scheme**. Это
простой способ проверки различных переменных и тестирования разных функций.\\
Пример запуска **gnetlist** в интерактивном режиме приведён ниже.
<code>% 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)
  %</code>
gEDA Project Wiki

User Tools

Site Tools

Page Tools
