Общий справочник HAL

1. Имена сущностей HAL

All HAL entities are accessible and manipulable by their names, so documenting the names of pins, signals, parameters, etc., is very important. Names in HAL have a maximum length of 41 characters (as defined by HAL_NAME_LEN in hal.h). Many names will be presented in the general form, with formatted text <like-this> representing fields of various values.

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

(bit) parport.<portnum>.pin-<pinnum>-in: Контакт HAL, связанный с физическим входным контактом <pinnum> разъема db25.
(float) pid.<loopnum>.output: Выходной сигнал ПИД-регулятора

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

2. HAL Общие соглашения об именах

Consistent naming conventions would make HAL much easier to use. For example, if every encoder driver provided the same set of pins and named them the same way, then it would be easy to change from one type of encoder driver to another. Unfortunately, like many open-source projects, HAL is a combination of things that were designed, and things that simply evolved. As a result, there are many inconsistencies. This section attempts to address that problem by defining some conventions, but it will probably be a while before all the modules are converted to follow them.

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

Точки (“.”) разделяют уровни иерархии. Это аналог косой черты (“/”) в имени файла.
Дефисы (“-”) разделяют слова или поля на одном уровне иерархии.
Компоненты HAL не должны использовать символы подчеркивания или “MixedCase”. footnote: [Подчеркнутые символы были удалены, но все еще есть несколько случаев неправильного сочетания, например pid.0.Pgain вместо pid.0.p-gain.]
Используйте в именах только строчные буквы и цифры.

3. Соглашения об именовании драйверов оборудования

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

3.1. Имена контактов/параметров

Hardware drivers should use five fields (on three levels) to make up a pin or parameter name, as follows:

<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. Имена функций

Hardware drivers usually only have two kinds of HAL functions, ones that read the hardware and update HAL pins, and ones that write to the hardware using data from HAL pins. They should be named as follows:

<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.