1. HAL Entity Names

Все объекты HAL доступны и ими можно манипулировать по их именам, поэтому очень важно документировать имена контактов, сигналов, параметров и т. д. Имена в HAL имеют максимальную длину 41 символ (как определено HAL_NAME_LEN в hal.h). Многие имена будут представлены в общем виде с форматированным текстом <так>, представляющим поля с различными значениями.

Когда контакты, сигналы или параметры описываются впервые, перед их именем в круглых скобках указывается их тип (float), а за ним следует краткое описание. Типичные определения выводов выглядят так:

(bit) parport.<portnum>.pin-<pinnum>-in

Контакт HAL, связанный с физическим входным контактом <pinnum> разъема db25.

(float) pid.<loopnum>.output

Выходной сигнал ПИД-регулятора

Иногда можно использовать сокращенную версию имени, например, второй контакт выше можно просто вызвать с помощью .output, когда это можно сделать, не вызывая путаницы.

2. HAL General Naming Conventions

Согласованные соглашения об именах значительно упростят использование HAL. Например, если бы каждый драйвер энкодерапредоставлял один и тот же набор контактов и называл их одинаково, то было бы легко перейти от одного типа драйвера энкодера к другому. К сожалению, как и многие проекты с открытым исходным кодом, HAL представляет собой комбинацию вещей, которые были разработаны, и вещей, которые просто развивались. В результате возникает множество несоответствий. В этом разделе делается попытка решить эту проблему путем определения некоторых соглашений, но, вероятно, пройдет некоторое время, прежде чем все модули будут преобразованы в соответствии с ними.

Halcmd и другие утилиты HAL низкого уровня рассматривают имена HAL как отдельные объекты без внутренней структуры. Однако большинство модулей имеют некоторую неявную структуру. Например, плата содержит несколько функциональных блоков, каждый блок может иметь несколько каналов, и каждый канал имеет один или несколько контактов. В результате получается структура, напоминающая дерево каталогов. Несмотря на то, что halcmd не распознает древовидную структуру, правильный выбор соглашений об именах позволит ему группировать связанные элементы вместе (поскольку он сортирует имена). Кроме того, инструменты более высокого уровня могут быть разработаны для распознавания такой структуры, если имена предоставляют необходимую информацию. Для этого все компоненты HAL должны следовать следующим правилам:

  • Точки (“.”) разделяют уровни иерархии. Это аналог косой черты (“/”) в имени файла.

  • Дефисы (“-”) разделяют слова или поля на одном уровне иерархии.

  • Компоненты HAL не должны использовать символы подчеркивания или “MixedCase”. footnote: [Подчеркнутые символы были удалены, но все еще есть несколько случаев неправильного сочетания, например pid.0.Pgain вместо pid.0.p-gain.]

  • Используйте в именах только строчные буквы и цифры.

3. Hardware Driver Naming Conventions

Note

Большинство драйверов не следуют этим соглашениям в версии 2.0. Эта глава на самом деле является руководством для будущих разработок.

3.1. Pins/Parameters names

Драйверы оборудования должны использовать пять полей (на трех уровнях) для создания имени контакта или параметра, а именно:

<device-name>.<device-num>.<io-type>.<chan-num>.<specific-name>

Отдельные поля:

<device-name>

Устройство, для которого предназначен драйвер. Чаще всего это интерфейсная плата какого-либо типа, но есть и другие возможности.

<device-num>

В компьютер можно установить более одной сервоплаты, параллельного порта или другого аппаратного устройства. Номер устройства идентифицирует конкретное устройство. Номера устройств начинаются с 0 и увеличиваются.

<io-type>

Большинство устройств предоставляют более одного типа ввода-вывода. Даже простой параллельный порт имеет как цифровые входы, так и цифровые выходы. Более сложные платы могут иметь цифровые входы и выходы, счетчики энкодеров, генераторы ШИМ или шаговых импульсов, аналого-цифровые преобразователи, цифро-аналоговые преобразователи или другие уникальные возможности. Тип ввода-вывода используется для идентификации типа ввода-вывода, с которым связан вывод или параметр. В идеале драйверы, реализующие один и тот же тип ввода-вывода, даже если для очень разных устройств, должны обеспечивать согласованный набор выводов и параметров и идентичное поведение. Например, все цифровые входы должны вести себя одинаково, если смотреть изнутри HAL, независимо от устройства.

<chan-num>

Практически каждое устройство ввода-вывода имеет несколько каналов, и номер канала идентифицирует один из них. Как и номера устройств, номера каналов начинаются с нуля и увеличиваются. footnote: [Одним исключением из правила "номера каналов начинаются с нуля" является параллельный порт. Его контакты HAL пронумерованы соответствующим номером контакта на разъеме DB-25. Это удобно для разводки, но несовместимо с другими драйверами. Есть некоторые споры о том, является ли это ошибкой или особенностью.] Если установлено более одного устройства, номера каналов на дополнительных устройствах начинаются с нуля. Если возможно иметь номер канала больше 9, то номера каналов должны состоять из двух цифр, с ведущим нулем в числах меньше 10, чтобы сохранить порядок сортировки. Некоторые модули имеют контакты и/или параметры, которые влияют более чем на один канал. Например, генератор ШИМ может иметь четыре канала с четырьмя независимыми входами "скважность", но одним параметром "частота", который управляет всеми четырьмя каналами (из-за аппаратных ограничений). Параметр частота должен использовать "0-3" в качестве номера канала.

<specific-name>

Отдельный канал ввода-вывода может иметь только один связанный с ним контакт HAL, но большинство из них имеют более одного. Например, цифровой вход имеет два контакта: один — состояние физического контакта, другой — то же самое, но в инвертированном виде. Это позволяет конфигуратору выбирать между входами с активным высоким и активным низким уровнем. Для большинства типов io существует стандартный набор контактов и параметров (называемый "стандартным интерфейсом"), который должен реализовать драйвер. Стандартные интерфейсы описаны в главе Интерфейсы стандартных устройств.

Examples
motenc.0.encoder.2.position

Выход положения третьего канала энкодера на первой плате Motenc.

stg.0.din.03.in

Состояние четвертого цифрового входа на первой плате Servo-to-Go.

ppmc.0.pwm.00-03.frequency

Несущая частота, используемая для каналов ШИМ с 0 по 3 на первой плате ppmc Pico Systems.

3.2. Function Names

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

<device-name>-<device-num>.<io-type>-<chan-num-range>.read|write
<device-name>

То же, что используется для контактов и параметров.

<device-num>

Конкретное устройство, к которому будет обращаться функция.

<io-type>

Опционально. Функция может иметь доступ ко всем вводам/выводам на плате или только к определенному типу. Например, могут существовать независимые функции для чтения счетчиков энкодера и чтения цифровых входов/выходов. Если такие независимые функции существуют, поле <io-type> идентифицирует тип ввода-вывода, к которому они обращаются. Если одна функция считывает все входы/выходы, предоставляемые платой, <io-type> не используется. footnote: [Примечание для программистов драйверов: НЕ реализуйте отдельные функции для разных типов ввода-вывода, если только они не являются прерываемыми и не могут работать в независимых потоках. Если прерывание чтения энкодера, чтение цифровых входов и последующее возобновление чтения энкодера вызовут проблемы, реализуйте одну функцию, которая сделает все.]

<chan-num-range>

Опционально. Используется только в том случае, если ввод-вывод <io-type> разбит на группы и доступен различным функциям.

read|write

Указывает, считывает ли функция с оборудования или записывает в него.

Examples
motenc.0.encoder.read

Считывает все энкодеры на первой плате motenc.

generic8255.0.din.09-15.read

Считывает второй 8-битный порт на первой универсальной плате цифрового ввода-вывода на базе 8255.

ppmc.0.write

Записывает все выходные данные (шаговые генераторы, ШИМ, ЦАП и цифровые данные) на первую плату ppmc Pico Systems.