# Перечень основных атрибутов gEDA/gaf

Автор: Ales Hvezda, ahvezda@geda.seul.org

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

10 июля 2007 г.

Перевод: Владимир Жбанов, 2010-2011 гг.

## Обзор

В настоящем документе приводится описание всех атрибутов, используемых в gEDA/gaf (GPL'd Electronic Design Automation / gschem and friends)1). Документ разбит на несколько разделов: данная обзорная часть, атрибуты только для символов, атрибуты только для схем, атрибуты для символов и схем, описание устаревших атрибутов или атрибутов, использовать которые больше не рекомендуется.
Далее в настоящем документе имена атрибутов выделены жирным шрифтом, примеры — `машинописным`.

## Что такое атрибуты?

Атрибуты в gEDA/gaf — это не что иное, как текстовые элементы вида: имя_атрибута=значение. Имя может содержать что угодно, за исключением знака равенства. Значение может также содержать что угодно, но не может быть пустой строкой. имя_атрибута= (без значения) не является допустимым атрибутом. Также не должно быть пробелов непосредственно до или после знака равенства.
Атрибуты могут быть прикреплены к некоторой части символа. Если атрибут несёт информацию, специфическую для объекта, он должен быть прикреплён непосредственно к этому объекту, в противном случае он может быть свободным (плавающим, неприкреплённым). Свободные атрибуты просто находятся в файле символа как текстовые элементы вида имя_атрибута=значение.

## Атрибуты только для символов

### device

Атрибутом device= задаётся название устройства в символе. Его нужно расположить где-нибудь в символе и сделать невидимым. Данный атрибут является свободным. Если объект является графическим, то атрибут device= должен иметь значение `none` (device=none), и в символе должен быть атрибут graphical=. Не следует путать данный атрибут с простым текстовым обозначением устройства. Не следует в названии устройства использовать пробелы, некоторым программам это не нравится. Как правило, название устройства указывается полностью прописными буквами.
Примеры:
`device=7400
device=CONNECTOR_10
device=NPN_TRANSISTOR`

### graphical

Наличие атрибута graphical=1 обязательно для символов, не предназначенных для электрических или схемотехнических целей. Такие символы, как рамка основной надписи для чертежей, являются чисто графическими. Любой символ, имеющий graphical=1, игнорируется программой gnetlist.
Чисто графический символ должен содержать невидимый атрибут graphical=1. Данный атрибут является свободным. При его наличии не забудьте установить device=none.
Пример:
`graphical=1`

### description

Атрибут description= задаёт простое однострочное описание того, какой символ намеревался изобразить автор.
Примеры:
`description=4 NAND gates with 2 inputs`
`description=4×2И-НЕ`

### author

Атрибут author= определяет имя автора данного символа и его электронный адрес. Данный атрибут является необязательным, но порой просто приятно иметь представление о том, кто какой символ сделал. Ещё он служит для того, чтобы узнать, с кем можно связаться, если есть вопросы о назначении символа. Данный атрибут имеет свободную форму и поэтому может также содержать и имена изменявших символ людей, и множество электронных адресов. Ещё может быть было бы неплохо как-то изменить адрес, чтобы он не стал жертвой спама.
Пример:
`author=Ales Hvezda ahvezdaATgeda.seul.org`

### comment

Атрибут comment= может содержать всё что угодно. С его помощью может передаваться любая дополнительная информация, которую нельзя включить в другие атрибуты. В символе может быть несколько экземпляров данного атрибута.
Пример:
`comment=Это комментарий внутри символа`

### pinseq

Данный атрибут используется для задания каждому выводу уникального порядкового номера. Атрибуты pinseq=# должны быть прикреплены к каждому из выводов. Их следует сделать невидимыми. Данные атрибуты широко используются программами gschem и gnetlist.
При работе некоторых драйверов (особенно драйвера SPICE) gnetlist выдаёт выводы в порядке возрастания их порядковых номеров. Порядковые номера должны начинаться с 1 и последовательно увеличиваться, причём пропускать их не допускается. Данный атрибут не является номером вывода (т. е. номером вывода компонента, как, например, вывод GND имеет номер 7 для многих TTL-микросхем). Для нумерации выводов служит атрибут pinnumber=.
Примеры:
`pinseq=1
pinseq=2
pinseq=3`

Данный атрибут замещает устаревший pin#=#.

### pinnumber

Атрибут pinnumber=# определяет номер вывода компонента (как, например, вывод GND имеет номер 7 для TTL серии 74). Он должен быть прикреплён к каждому выводу.
Значения могут задаваться цифрами или буквами. Атрибут должен быть видимым, причём видимым должно быть только значение. Также необходим атрибут pinseq=.
Примеры:
`pinnumber=1
pinnumber=13
pinnumber=A0`

Данный атрибут замещает устаревший pin#=#.

### pintype

Атрибут pintype=значение должен быть прикреплён к каждому выводу. Его следует сделать невидимым. В таблице 1 приведены допустимые значения данного атрибута.
Атрибут pintype= не очень широко применяется в библиотеке символов, но он используется для проверки соответствия проектным нормам (DRC) и для создания списков соединений. Если никакой другой тип для вывода не подходит, используйте “пассивный” (“pas”).
Примеры:
`pintype=clk
pintype=in
pintype=pas`

in | Input | Вход
out | Output | Выход
io | Input/Output | Вход/выход
oc | Open collector | Открытый коллектор
oe | Open emitter | Открытый эмиттер
pas | Passive | Пассивный
tp | Totem pole | Идольский столб2)
tri | Tristate (high impedance) | Трёхстабильный, третье состояние — высокоимпедансное
clk | Clock | Тактовый
pwr | Power/Ground | Питание/общий
Таблица 1: Значения атрибута pintype

### pinlabel

Атрибут pinlabel= устанавливает метку вывода. Главным образом он нужен программе gnetlist для поддержки иерархических проектов.
Данный атрибут нужно прикрепить к выводу и сделать видимым. Он должен быть зелёного цвета (вместо жёлтого, стандартного цвета атрибутов).
Примеры:
`pinlabel=A0
pinlabel=DATA1
pinlabel=CLK`

### numslots

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

### slotdef

Если компонент служит для представления многосекционного прибора, содержащего несколько секций в одном физическом корпусе, то для каждой из этих секций необходимо задать атрибут slotdef=номер_секции:#,#,#… .
Число `номер_секции` соответствует номеру секции. Двоеточие после номера секции обязательно. Например, для устройства, содержащего 4 секции, в символ нужно было бы добавить атрибуты slotdef=1:…, slotdef=2:…, slotdef=3:… и slotdef=4:… и сделать их невидимыми. Данный атрибут является свободным.
Числа # однозначно соответствуют значениям атрибутов pinseq= и определяют номера выводов pinnumber=#, используемые для отображения на экране (в gschem) и для создания списка соединений (с помощью gnetlist).
Для всех символов, определяющих несколько секций, рекомендуется задавать атрибут slot=1, прикрепляемый таким же образом, как и device=.
См. символ 7400-1.sym как пример реального применения slotdef=.
Примеры:
`slotdef=1:1,2,3
slotdef=2:4,5,6
slotdef=3:7,8,9`
Данный атрибут замещает устаревший slot#=#.

### footprint

Атрибут footprint=название_корпуса нужно расположить где-нибудь в символе и сделать невидимым. Он используется программой gnetlist и главным образом для пакета pcb.
Атрибут прикрепляется таким же образом, как и device=. Он является свободным.
`название_корпуса` определяет посадочное место для pcb или типоразмер корпуса, как, например, DIP14 или DIP40. Хотя в принципе значения данного атрибута зависят от пакета pcb, в gEDA/gaf существуют соглашения о том, чтобы делать их как можно лучше переносимыми для предоставления пользователям возможностей удобного сотрудничества и совместного использования. См. Соглашения по именованию посадочных мест.
Если для символа посадочное место не нужно или если оно должно переопределяться в схеме, следует установить footprint=none. Если название посадочного места неизвестно, следует установить footprint=unknown.

### documentation

Атрибут documentation=ссылка_на_документацию можно расположить где-нибудь в символе и сделать невидимым. Данный атрибут используется программой gschemdoc для поиска подходящей документации по символу, или, вернее, по устройству или компоненту, определяемому данным символом.
Атрибут прикрепляется таким же образом, как и device=. Он является свободным.
`ссылка_на_документацию` определяет либо имя основного файла документации, либо полный интернет-адрес. Если в атрибуте задано имя файла, программа попытается найти его в локальном каталоге `documentation` пакета gEDA.

Пример имени файла:
`documentation=sn74ls00.pdf`
Пример интернет-адреса:
`documentation=http://www-s.ti.com/sc/ds/sn74ls00.pdf`

## Атрибуты только для схем

### netname

Атрибут netname= должен прикрепляться к объекту «соединение» для установки его имени. Крайне не рекомендуется использовать разные имена для связанных сегментов соединений. Одинаково названные соединения считаются электрически замкнутыми между собой. Недопустимо использовать данный атрибут внутри символов (так как внутри символов соединения использовать нельзя).
Примеры:
`netname=DATA0 H
netname=CLK L`

### source

Атрибут source= указывает, что символ является представлением подсхемы. Он прикрепляется непосредственно к символу компонента.
Данный атрибут должен прикрепляться только к экземплярам символов компонентов в схеме. Атрибут следует прикрепить к символу и задать значение в виде имени файла подсхемы (например, `block.sch`), но не полного пути доступа. Указанный файл подсхемы должен находиться в одном из каталогов, перечисленных среди путей доступа к библиотекам источников данных. Можно прикреплять несколько таких атрибутов с различными значениями, что, по существу, означает, что подсхема представляет собой набор из нескольких связанных между собой схем.
Примеры:
`source=underlying.sch
source=memory.sch`

## Атрибуты для символов и схем

### refdes

Атрибут refdes= определяет позиционное обозначение конкретного экземпляра компонента в схеме. Данный атрибут должен быть у КАЖДОГО компонента, имеющего какой-либо электрический смысл. Для установки позиционного обозначения, используемого для компонента по умолчанию (такого как 'U?', например), данный атрибут может задаваться непосредственно в символе (и если он видим, то при помещении символа в схему будет вынесен, то есть прикреплён вне символа).
Примеры:
`refdes=U1
refdes=R10
refdes=CONN1`

#### Ограничения для позиционных обозначений

В качестве значения атрибута refdes= gschem принимает любые строки. Но некоторые драйверы gnetlist накладывают ограничения на допустимый синтаксис.

В частности gsch2pcb требует:

- Не должно быть пробелов.
- Не должно быть дефисов. Это может привести к сбою интерпретатора макроязыка M4, потенциально используемого для генерирования посадочных мест. Символ подчёркивания “_” допустим.
- Любой суффикс из строчных букв игнорируется. Таким образом в схему можно добавить 4 дискретных элемента И-НЕ с обозначениями `U1a`, `U1b`, `U1c` и `U1d`. При создании списка соединений они будут относиться к одному посадочному месту с названием `U1`.
- Символы, не входящие в ASCII, такие как, например, üöäß, не выводятся в pcb.

#### Соглашения по позиционным обозначениям

Существует соглашение о применяемых позиционных обозначениях для разных типов компонентов. Здесь приведены некоторые из них3) (`?` заменяется числом):

Обозначение | Тип компонента
--- | ---
R? | Резистор
RN? | Набор резисторов
FB? | Ферритовый фильтр
L? | Катушка индуктивности, дроссель
C? | Конденсатор
B? | Батарея
F? | Предохранитель
J? | Соединитель, разъём
P? | Соединитель, разъём (обычно сопрягаемый с обозначенным как J?)
K? | Реле
S? | Выключатель, переключатель
T? | Трансформатор
TP? | Контрольная точка
M? | Двигатель
D? | Диод
Q? | Транзистор
U? | ИС (интегральная схема)
X? | Кварцевый осциллятор

### slot

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

### net

Атрибут net= используется для создания соединений питания и специальных целей. Подробности см. в Мини-HOWTO по атрибуту net=. Если данный атрибут находится в символе, он используется для создания соединений. Если же он прикрепляется к экземпляру компонента в схеме, то может использоваться также для создания новых соединений и переопределения уже существующих.

### value

Атрибут value= в основном используется в драйвере генератора списка соединений для SPICE с целью определения значений различных элементов. Он не переводится и помещается в список соединений как есть.
Примеры:
`value=1K
value=10V`

### symversion

Атрибут symversion= используется для определения версии содержимого символа. Так как по умолчанию символы в схему не внедряются, а приводится лишь ссылка на них, то в схеме, использующей какой-либо конкретный символ, при изменении файла этого символа могут возникнуть проблемы. Например, изменение расположения выводов в символе приведёт к тому, что линии соединений в схеме уже не будут подключены к надлежащим выводам. Атрибут symversion= позволяет отслеживать такие разрушительные изменения в символах и уведомлять пользователя о потенциальных проблемах при загрузке схемы. Данный атрибут необязателен, но при наличии в символе он должен принимать следующую форму:
старший_номер.младший_номер,
где `старший_номер` и `младший_номер` — целые числа. Старший номер при вводе новой версии инкрементируется4) в случае таких изменений в символе, которые могут привести к порче существующих схем, использующих предыдущие версии символа. Младший номер инкрементируется только в случае небольших изменений (изменений, не приводящих к порче существующих схем, таких как косметические изменения при сохранении структуры, то есть положения выводов).

Если символ, содержащий данный атрибут, помещается в схему, атрибут symversion= автоматически “выносится”, то есть для данного экземпляра символа копия атрибута symversion=M.N сохраняется непосредственно в файле схемы. При загрузке символа с диска значение атрибута symversion= в файле символа (при его наличии) сравнивается со значением атрибута, прикреплённого к экземпляру символа в схеме. Если эти значения различаются, то libgeda выдаст предупреждение (при изменении младшего номера версии) или ошибку (при изменении старшего номера версии).

Обычно при помещении данного атрибута в файл символа его лучше сделать невидимым. Если при добавлении символа в схему в нём найден этот атрибут, то он всегда выносится. Не следует прикреплять данный атрибут к имеющимся в схеме экземплярам символов вручную.

Примеры:
`symversion=1.1
symversion=2.0`

### dist-license

Атрибут dist-license= используется для указания лицензии, под которой распространяется символ или схема. В нём должна задаваться известная лицензия. Вот несколько примеров его возможных значений: `GPL`, `GPL version 2 only`, `GPL version 3 only`, `public domain`, `Apache version 2`, `Modified BSD`, `X11` и т. д.
Перечни существующих лицензий можно найти по следующим адресам: Перечень лицензий FSF и Перечень лицензий OSI.

### use-license

Атрибут use-license= используется для указания лицензии, определяющей, как другие пользователи могут использовать данный символ или данную схему в своих схемах и платах. Вот примеры его значений: `unlimited` (неограниченная), `personal use only` (только для личного пользования), `not for sale` (не для продажи) и т. д.

: добавить сюда набор примеров получше.

## Устаревшие атрибуты

### uref

Атрибут uref= устарел и использоваться не должен. Он применялся для тех же целей, что и refdes=.

### name

Атрибут name= не должен ни использоваться в символе, ни прикрепляться в схеме. Считается, что такое название атрибута неоднозначно. Данный атрибут никогда не использовался в gEDA/gaf.

### label

Атрибут label= устарел и использоваться не должен. Он применялся для определения названий/меток соединений и меток выводов. Теперь эти функции выполняют соответственно атрибуты netname= и pinlabel=.

### pin#

Атрибут pin#=# устарел и использоваться не должен. Он применялся для определения порядковых номеров выводов в символе и номеров выводов для компонента. Теперь эти функции выполняют соответственно pinseq= и pinnumber=.

### slot#

Атрибут slot#=# устарел и использоваться не должен. Ранее в нём предоставлялась информация о назначении секций компонентов. Теперь эту функцию выполняет атрибут slotdef=.

### type

Атрибут type= устарел и использоваться не должен. Он применялся для установки типа выводов. Теперь эту функцию выполняет атрибут pintype=.

### email

Информация из данного атрибута вынесена в атрибут author=.

## История изменений документа

14 июля 2002 г. | Создан attributes.tex из attributes.txt.
14 июля 2002 г. | Документ обновлён для синхронизации с post-20020527.
25 августа 2002 г. | Добавлен устаревший атрибут type=.
14 сентября 2002 г. | Добавлен атрибут description=. Небольшие исправления
7 октября 2002 г. | Добавлен атрибут doc=; Egil Kvaleberg.
11 февраля 2003 г. | Добавлена ссылка на соглашения по посадочным местам.
23 февраля 2003 г. | Добавлены атрибуты author=, email=, и comment=.
6 июля 2004 г. | Добавлен атрибут symversion=.
10 июля 2007 г. | Добавлены атрибуты dist-license= и use-license=.

1) САПР электроники под лицензией GPL / gschem и друзья. — Прим. перев.
2) Шуточная расшифровка. На самом деле расшифровывается как “test pin/point” (контрольная точка/контрольный вывод). — Прим. перев.
3) Данные соглашения в ряде случаев не соответствуют отечественным стандартам, см. ГОСТ 2.710-81. — Прим. перев.
4) Увеличивается на 1. — Прим. перев.