# Руководство по созданию символов gEDA/gaf

Последняя версия оригинала настоящего документа находится по адресу http://www.geda-project.org/wiki/geda:gschem_symbol_creation.
Настоящий документ выпущен под лицензией GNU Free Documentation License (GFDL).

## Обзор

В настоящем документе описывается создание символов компонентов, в том числе соглашения по стилю, советы/подсказки и то, чего стоит остерегаться при вычерчивании символов для системы gEDA/gaf.

## Создание символа компонента

Символы компонентов (называемые далее просто “символами”) вычерчиваются в gschem. Можно начать с пустой страницы или с заведомо хорошего символа, похожего на создаваемый вами.

### Подготовка

Прежде, чем открыть gschem и начать чертить символ, задайте себе несколько вопросов, ответы на которые повлияют на то, как это делать:

1. Создаётся ли символ чисто из эстетических соображений (просто как рисунок)? Если так, несколько шагов упрощаются.
2. Нужно ли будет потом использовать этот компонент для моделирования, например в SPICE?
3. Нужно ли будет использовать этот символ в схеме, где производится разводка питания? Это будет важно при решении вопроса о том, какие выводы нужно чертить.
4. Представляет ли этот символ компонент, которых по несколько штук в одном корпусе? Это на языке gEDA называется назначением логических секций и на этот счёт имеются особые правила.

Когда вы сами для себя ответите на эти вопросы, дальнейшая часть руководства станет для вас гораздо полезней.

Итак, приступим к созданию символа:

1. Откройте gschem.
2. По умолчанию на новых пустых страницах выводятся рамки. Выберите инструмент выделения (в виде чёрной стрелки мыши на панели инструментов) и выделите всё на странице. Нажмите клавишу `Delete`, чтобы всё удалить.
3. Увеличьте хотя бы раз масштаб (Вид → Увеличить [View → Zoom In], или нажмите клавишу `Z`).
4. Удостоверьтесь, что привязка к сетке ВКЛЮЧЕНА (Настройки → Переключить сетку привязки [Options → Toggle Snap On/Off] или `O` `S`).
5. Убедитесь, что шаг сетки привязки установлен в 100 (Настройки → Шаг сетки привязки… [Options → Snap Grid Spacing…] или `O` `Shift`+`S`).

### Черчение символа

С помощью инструментов `Линия`, `Прямоугольник`, `Окружность`, `Дуга` (которые можно выбрать в меню Добавить [Add]) создайте условное графическое обозначение своего устройства. Убедитесь, что единственный цвет, который вы использовали, это 'Graphic' (зелёный). Не помещайте никаких выводов устройства до следующего шага.

Для проверки того, какой цвет используется для черчения, откройте меню Правка → Цвет… [Edit → Color…] (или нажмите `E` `O`).

### Размещение выводов

Если вы решили, что ваш символ будет графическим (т. е. не будет ни к чему подключаться, а будет просто картинкой), то этот шаг можно пропустить.

Добавьте свой первый вывод.

1. Выберите Добавить → Вывод [Add → Pin], или нажмите `A` `P`. После этого щёлкните в том месте, где должен быть конец вывода, и переместите мышь к краю своего символа. Около вашего нового вывода должны появиться '0' и слово 'unknown'. Обратите внимание, что направление вычерчивания выводов важно. Если их чертить от края символа наружу, то текст окажется снаружи символа!
2. Щёлкните по инструменту выделения и выделите им вывод, который вы только что нарисовали. Цвет самого вывода и относящегося к нему текста должен измениться, а на концах вывода должны появиться квадратики.
3. Выберите Правка → Правка… [Edit → Edit…] или нажмите `E` `E` (или щёлкните правой кнопкой и выберите Правка… [Edit…]). Тогда для вывода появится диалоговое окно редактирования.

В диалоговом окне редактирования своего нового вывода вы должны увидеть четыре атрибута (четыре пары `имя=значение`), уже прикреплённых к нему. Эти атрибуты можно отредактировать, щёлкая сначала по атрибуту в списке вверху окна редактирования, затем по полю, которое вы хотите изменить. Учтите, что когда что-то выделено, это не отражается в разделе диалогового окна Добавить атрибут, так как этот раздел предназначен только для добавления, а не для редактирования уже имеющихся атрибутов.

Давайте взглянем на каждый из атрибутов, уже прикреплённых к вашему выводу, и изменим некоторые значения. Я предлагаю увеличить размер окна редактирования так, чтобы было видно все атрибуты.

- У каждого вывода должен быть атрибут `pinseq`. Это число, определяющее порядок работы программы gnetlist с атрибутами. Для нашего первого вывода начнём эту последовательность с '1' и будем последовательно увеличивать этот номер по мере добавления выводов.
- У каждого вывода должен быть атрибут `pinnumber`. Это номер вывода на корпусе компонента, для которого создаётся этот символ. Номер вывода может быть буквенным или цифровым (то есть можно использовать, например, `E` или `C`).
- У каждого вывода должен быть также атрибут `pinlabel`. Данный атрибут является названием или меткой вывода (а не номером вывода).
- У каждого вывода должен быть также атрибут `pintype`. Данный атрибут определяет тип вывода.
- Атрибуты `pinseq` и `pinnumber` нескольких выводов сразу можно пронумеровать автоматически с помощью Атрибуты → Автонумерация… [Attributes → Autonumber Text…].

Допустимыми значениями `pintype` являются: `in`, `out`, `io`, `oc`, `oe`, `pas`, `tp`, `tri`, `clk`, `pwr`. Более подробную информацию о нём см. в Перечне основных атрибутов.

### Добавление атрибутов к символу

Чтобы использовать символ с пользой в gschem и других программах, он должен содержать несколько атрибутов (в виде пар `имя=значение`).

Сначала мы добавим все нужные нам атрибуты, а затем отключим видимость тех из них, которые должны быть невидимыми.

1. В символ нужно добавить атрибут `device=НАЗВАНИЕ_УСТРОЙСТВА`. Название устройства не должно содержать ничего, кроме прописных букв, дефисов, чисел и символов подчёркивания. Если символ определяет чисто графический объект, то значение атрибута `device=` должно быть `none` (`device=none`).
2. В чисто графический символ (такой как, например, рамка формата основной надписи или символ `decon`) следует добавить атрибут `graphical=1`. Этот атрибут показывает, что содержащий его символ не имеет электрического или схемотехнического назначения. Не забывайте согласно предыдущему требованию устанавливать вместе с данным атрибутом `device=none`.
3. В символе должен быть атрибут `description=ТЕКСТ`. `ТЕКСТ` должен представлять собой однострочное описание символа.
4. В символе должен быть атрибут `footprint=ИМЯ_КОРПУСА`, он может использоваться генератором списка соединений для pcb. `ИМЯ_КОРПУСА` представляет собой посадочное место для pcb или тип корпуса, такой как DIP14 или DIP40. Подробности см. в Соглашениях по именованию посадочных мест. Если вы используете gEDA в связке с pcb, то более подробную информацию по данному атрибуту и о том, как его использовать, вы найдёте в документации по pcb и в `gnetlist/docs/README.pcb`.
5. Атрибут `refdes=` должен помещаться во все символы, не являющиеся чисто графическими. Значение данного атрибута по умолчанию для микросхем должно быть `U?`, а для транзисторов `T?`. Видимым следует сделать только его значение и, когда символ будет помещён в схему, данный атрибут будет вынесен (прикреплён вне символа для обеспечения возможности его редактирования).
6. Атрибут `numslots=` нужно добавлять во все символы, чтобы предотвратить предупреждения, выдаваемые программой gsymcheck при их проверке. Вполне достаточно добавить `numslots=1`.

Теперь, когда все эти атрибуты добавлены, сделайте `numslots`, `footprint`, `description`, `graphical` и `device` невидимыми. Оставьте видимым только значение атрибута `refdes` и расположите его где-нибудь над символом.

### Завершение

1. Добавьте к своему символу обозначение, выбрав Добавить → Текст… [Add → Text…] или нажав `A` `T`. Наберите своё обозначение и переместите его в верхнюю часть символа.
2. Сместите символ в начало координат из меню Правка → Смещение символа…
   [Edit → Symbol Translate…] или нажмите `E` `T`.
3. Введите `0` в поле ввода и нажмите OK.
4. Сохраните символ с помощью Файл → Сохранить [File → Save] или Файл → Сохранить как… [File → Save As…].
5. Поместите символ в один из каталогов, определённых ключевым словом `component-library` в файле `system-gafrc`. Как только это сделано, символ должен немедленно стать видимым и может быть выбран и помещён в схему из меню Добавить → Компонент… [Add → Select Component…]. В Debian помещение файлов в `/usr/share/gEDA/sym/local/` работать будет, но потребует настройки привилегий.

#### Примечание

Смещение символа в начало координат — шаг необходимый. Для смещения символа в другое место введите величину смещения (в милах), кратную 100. Убедитесь, что все выводы привязаны к точкам сетки.

## Общие соглашения об именовании символов

1. Символы именуются следующим образом: `symbolname-#.sym`
2. Имена символов имеют расширение `.sym`.
3. Названия символов содержат число, обозначенное выше знаком `#`. Обычно оно равно 1, но если для устройства имеется несколько символов, данное число просто увеличивается.
4. Обычно имена символов задаются в нижнем регистре, но буквы, составляющие часть типа прибора, указываются в верхнем регистре.
5. Последнее правило может быть нарушено, если имя файла выглядит некорректно или ошибочно.

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

В данном разделе описываются различные требования, которые необходимо соблюдать для создания правильного символа в плане отображения его на экране и создания для него списков соединений в системе gEDA/gaf.

### Выводы

1. К каждому выводу должен быть прикреплён атрибут `pinseq`. Это число, определяющее порядок работы программы gnetlist с атрибутами. Это просто порядковый номер, последовательно увеличивающийся, начиная с 1.
2. К каждому выводу должен быть прикреплён атрибут `pinnumber`. Это номер вывода на корпусе компонента, для которого создаётся этот символ. Номер вывода может быть буквенным или цифровым (то есть можно использовать, например, `E` или `C`).
3. К каждому выводу должен быть также прикреплён атрибут `pinlabel`. Данный атрибут является названием или меткой вывода (а не номером вывода). Данный атрибут применяется также при использовании символа в иерархической схеме.
4. К каждому выводу должен быть также прикреплён атрибут `pintype`. Данный атрибут определяет тип вывода. Допустимыми значениями являются: `in`, `out`, `io`, `oc`, `oe`, `pas`, `tp`, `tri`, `clk`, `pwr`. Более подробную информацию о нём см. в Перечне основных атрибутов.

### Атрибуты

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

1. В символе должен находиться невидимый атрибут `device=НАЗВАНИЕ_УСТРОЙСТВА`. Обычно название устройства задаётся в верхнем регистре (прописными буквами). Данный атрибут не должен использоваться в качестве обозначения. Для этого следует использовать отдельный текстовый объект. Если символ определяет чисто графический объект, то `device=` должен иметь значение `none` (`device=none`).
2. Если символ является полностью графическим (как, например, рамка формата основной надписи или символ `decon`) в нём должен быть атрибут `graphical=1`. Символы с данным атрибутом не имеют электрического или схемотехнического назначения. Не забывайте согласно предыдущему требованию устанавливать вместе с данным атрибутом `device=none`.
3. В символе должен быть атрибут `description=ТЕКСТ`. `ТЕКСТ` должен представлять собой однострочное описание символа.
4. В символе должен быть атрибут `footprint=ИМЯ_КОРПУСА`, он может использоваться генератором списка соединений для pcb. `ИМЯ_КОРПУСА` представляет собой посадочное место для pcb или тип корпуса, такой как DIP14 или DIP40. Подробности см. в Соглашениях по именованию посадочных мест. Если вы используете gEDA в связке с pcb, то более подробную информацию по данному атрибуту и о том, как его использовать, вы найдёте в документации по pcb и в `gnetlist/docs/README.pcb`.
5. Атрибут `refdes=U?` должен помещаться во все символы, не являющиеся чисто графическими. Видимым следует сделать только его значение и, когда символ будет помещён в схему, данный атрибут будет вынесен (прикреплён вне символа для обеспечения возможности его редактирования).
6. Атрибуты `label=` и `name=` не должны использоваться в символах, так как это устаревшие атрибуты.
7. Атрибут `netname=` не должен использоваться в символах. Он используется только в схемах.

#### Многосекционные компоненты

1. Если компонент содержит несколько элементов (секций) в одном физическом корпусе (как, например, 7400, имеющий 4 элемента 2И-НЕ в одном корпусе), то необходим атрибут `numslots=#`. Число `#` задаёт количество элементов в физическом устройстве. В этом случае в символе должен быть атрибут `numslots=` и его следует сделать невидимым. Другие обязательные атрибуты, относящиеся к многосекционным компонентам, описываются ниже.
2. Если компонент содержит несколько элементов (секций) в одном физическом корпусе, то для каждой секции необходимо также задать атрибут `slotdef=#:#,#,#…` Первое число `#` соответствует номеру секции. Если устройство содержит 4 элемента, то в символе должны быть атрибуты `slotdef=1:…`, `slotdef=2:…`, `slotdef=3:…` и `slotdef=4:…`, их следует сделать невидимыми. Последующие числа `#` один к одному соответствуют атрибутам `pinseq=#` и определяют номер вывода `pinnumber=#`, который должен устанавливаться при назначении данной секции. В качестве примера того, как всё это должно работать, см. приведённый ниже символ 7400-1.sym.
3. В символы многосекционных компонентов рекомендуется добавлять атрибут `slot=1`.

## Проверка символа

Соответствие всем указанным требованиям проверяется запуском gsymcheck. gsymcheck выдаст фатальные ошибки, довольно серьёзные и требующие исправления. gsymcheck также выдаст предупреждения о требующих исправления, но не фатальных ошибках.

## Стиль

В данном разделе описывается стиль, используемый в стандартной библиотеке символов gEDA/gaf.

### Текст

- Все текстовые обозначения должны быть размером 10 пунктов.
- Текст (текстовые обозначения, но не атрибуты) должен иметь цветовой индекс 9 (text | зелёный).
- Для указания инверсных логических уровней используйте специальное кодирование черты над текстом (например, `pinlabel=\_Reset\_`).

### Атрибуты

- В качестве номеров выводов должны отображаться атрибуты `pinnumber` (не `pinseq`), и их размер должен составлять 8 пунктов.
- Цветовой индекс прикреплённых атрибутов должен быть равен 5 (attributes | жёлтый). Цвет автоматически устанавливается в жёлтый при прикреплении текстового элемента.
- Единственным исключением из данного правила являются атрибуты `pinlabel=`, цветовой индекс которых должен быть равен 9 (text | зелёный). Если каждый текстовый элемент внутри символа будет жёлтым, символ выглядит чересчур жёлтым.
- Атрибуты могут прикрепляться к некоторой части символа. Раньше, для того чтобы атрибуты верхнего уровня (такие как `device=` или `net=`) считались атрибутами, их требовалось к чему-либо прикреплять, но сейчас достаточно, чтобы они находились в файле символа в виде `имя_атрибута=значение`.
- Раскрывая немного последнее предложение, добавим, что атрибутом считается любой текстовый элемент вида `имя_атрибута=значение`. Атрибуты внутри символа не обязательно прикреплять к чему-либо. Чтобы увидеть скрытые атрибуты в gschem, выберите Правка → Показать/Скрыть невидимый текст [Edit → Show/Hide Inv Text].
- В библиотеке libgeda есть система работы с версиями содержимого символа на основе оценки атрибута `symversion=`. Подробности использования этой схемы работы с версиями см. в Перечне основных атрибутов.

### Графика

- Цветовой индекс линий, прямоугольников, дуг и других графических объектов должен быть равен 3 (graphic | зелёный).
- Цветовой индекс знаков логической инверсии в виде окружностей должен быть равен 6 (logic bubble | голубой).
- Если вы не уверены в том, как должен выглядеть новый символ или какой он должен быть величины, то, чтобы получить представление о подходящем виде и размере, взгляните на существующие символы.

### Выводы

- Длина выводов должна составлять 300 милов (3 интервала сетки).
- Длина выводов, располагаемых рядом со знаком логической инверсии, должна составлять 200 милов (2 интервала сетки), окружность знака логической инверсии должна иметь диаметр 100 милов. Чтобы начертить окружность диаметром 100 милов, нужно изменить размер сетки на 50.
- Вывод имеет два конца: один помечен красной точкой, другой — нет. Красная точка означает место подключения соединений. Для правильного размещения активного конца можно либо поворачивать сам вывод, либо вручную отредактировать файл символа, изменив параметр “whichend” нужного вывода. Подробности см. в документации по Формату файлов.
- Все концы выводов, предназначенные для соединений, должны размещаться по сетке размером 100 милов. Другие, неактивные концы могут быть при необходимости расположены не по сетке.
- Цветовой индекс для выводов должен быть равен 1 (pins | белый).
- Выводы (по вертикали) следует размещать на расстоянии 400 милов (4 интервала сетки) за исключением вычерчивания специальных символов, в таких случаях просто старайтесь, чтобы символ хорошо выглядел.
- Номера выводов должны располагаться на 50 милов выше вывода, к которому они прикреплены (или ниже; то есть более подходящим по смыслу образом).
- Входные выводы размещаются с левой стороны символа, выходные — с правой.
- Пожалуйста, не помещайте входы и выходы на одну и ту же сторону символа, если в этом нет абсолютной необходимости.
- Можно располагать выводы сверху или снизу символа.
- Порядок последовательности выводов (для шин) должен быть от младшего значащего разряда (МЗР) к старшему (СЗР). При вычерчивании выводов, являющихся частью шины, обеспечьте, чтобы МЗР на шине был расположен наверху (или для выводов, которые располагаются вверху или внизу символа, слева от других выводов). Пример правильного порядка вы найдёте в символе `74/74181-1.sym` (сверху вниз от A0 до A3 и от B0 до B3). Нарушение данного правила сильно затруднит подключение к шинам.
- При размещении выводов логических элементов обязательно располагайте выводы начиная с наименьших порядковых номеров сверху вниз (или слева направо) в порядке их увеличения.

### Схемотехника

- Не чертите выводы питания. Такая информация обычно передаётся посредством атрибутов (смотрите Мини-HOWTO по атрибуту net=).
- Вышеуказанное правило при необходимости может быть нарушено, но имейте в виду, что в большинстве символов стандартной библиотеки выводы питания не показаны.
- Имейте в виду, что символы должны быть символическими, они не изображают физический корпус устройства.
- По вышеуказанным вопросам есть некоторые разногласия, поэтому следующее тоже будет нормально: располагайте выводы символа логически, так, чтобы они способствовали созданию понятных, незапутанных схем. Заметьте, что часто это не тождественно физическому расположению выводов устройства.

## Советы и подсказки

В данном разделе приводится несколько советов и подсказок, чтобы облегчить вам труд по созданию символов.

- Выводы ДОЛЖНЫ быть выровнены по сетке размером 100.
- Избегайте черчения объектов вне сетки. В противном случае вы не сможете перемещать их командой перемещения (если сетка включена), так как объекты будут прилипать к сетке. [Это старая программная ошибка, которая, думаю, уже исправлена, но всё равно остерегайтесь так делать.] Вместо этого используйте команду смещения символа (или перемещайте объект, отключив сетку).
- При создании символов нормально устанавливать размер сетки меньше 100 (скажем, 10 или 25), только надо помнить, что его надо вернуть обратно в 100, когда вы будете готовы к смещению символа в начало координат.
- Если вы хотите сместить символ куда-то из начала координат, используйте команду Правка → Смещение символа… [Edit→Symbol Translate…] и введите число, не равное нулю. Это число должно быть кратным 100 (например, 1000 или 1100).
- Помните, что выводы являются специальными объектами; если вы хотите добавить вывод, убедитесь, что вводите именно вывод, а не линию или соединение. Используйте команду Добавить → Вывод [Add → Pin] для черчения вывода.
- Не используйте внутри символа соединений и шин. Это не поддерживается и не имеет особого смысла.
- Для выводов должен быть видимым атрибут `pinnumber`, может быть вместе с `pinlabel`, если таковой имеется.

## Пример

В данном разделе приведён простой пример, в котором мы стараемся следовать всем вышеуказанным правилам. Это символ 7400 (И-НЕ).

7400-1.sym

      v 20031231 1
      L 300 200 300 800 3 0 0 0 -1 -1
      T 300 0 9 8 1 0 0 0 1
      7400
      L 300 800 700 800 3 0 0 0 -1 -1
      T 500 900 5 10 0 0 0 0 1
      device=7400
      T 500 1100 5 10 0 0 0 0 1
      slot=1
      T 500 1300 5 10 0 0 0 0 1
      numslots=4
      T 500 1500 5 10 0 0 0 0 1
      slotdef=1:1,2,3
      T 500 1700 5 10 0 0 0 0 1
      slotdef=2:4,5,6
      T 500 1900 5 10 0 0 0 0 1
      slotdef=3:9,10,8
      T 500 2100 5 10 0 0 0 0 1
      slotdef=4:12,13,11
      L 300 200 700 200 3 0 0 0 -1 -1
      A 700 500 300 270 180 3 0 0 0 -1 -1
      V 1050 500 50 6 0 0 0 -1 -1 0 -1 -1 -1 -1 -1
      P 1100 500 1300 500 1 0 1
      {
      T 1100 550 5 8 1 1 0 0 1
      pinnumber=3
      T 1100 450 5 8 0 1 0 2 1
      pinseq=3
      T 950 500 9 8 0 1 0 6 1
      pinlabel=Y
      T 950 500 5 8 0 1 0 8 1
      pintype=out
      }
      P 300 300 0 300 1 0 1
      {
      T 200 350 5 8 1 1 0 6 1
      pinnumber=2
      T 200 250 5 8 0 1 0 8 1
      pinseq=2
      T 350 300 9 8 0 1 0 0 1
      pinlabel=B
      T 350 300 5 8 0 1 0 2 1
      pintype=in
      }
      P 300 700 0 700 1 0 1
      {
      T 200 750 5 8 1 1 0 6 1
      pinnumber=1
      T 200 650 5 8 0 1 0 8 1
      pinseq=1
      T 350 700 9 8 0 1 0 0 1
      pinlabel=A
      T 350 700 5 8 0 1 0 2 1
      pintype=in
      }
      T 300 900 8 10 1 1 0 0 1
      refdes=U?
      T 500 2250 5 10 0 0 0 0 1
      footprint=DIP14
      T 500 2450 5 10 0 0 0 0 1
      description=4 NAND gates with 2 inputs
      T 500 2850 5 10 0 0 0 0 1
      net=Vcc:14
      T 500 3050 5 10 0 0 0 0 1
      net=GND:7
      T 500 2650 5 10 0 0 0 0 1
      documentation=http://www-s.ti.com/sc/ds/sn74hc00.pdf

Результат, полученный в данном примере, выглядит в gschem следующим образом:

Вот тот же самый символ, весь скрытый текст которого видим (меню Правка → Показать/Скрыть невидимый текст [Edit → Show/Hide Inv Text]):