Загальний довідник HAL

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

Всі об’єкти HAL доступні та можуть бути змінені за їхніми іменами, тому дуже важливо документувати імена контактів, сигналів, параметрів тощо. Імена в HAL мають максимальну довжину 41 символ (як визначено в HAL_NAME_LEN в hal.h). Багато імен будуть представлені в загальній формі, з форматованим текстом <like-this>, що представляє поля різних значень.

Коли контакти, сигнали або параметри описуються вперше, перед їхньою назвою в дужках вказується їхній тип (float), а після — короткий опис. Типові визначення контактів виглядають так, як у цих прикладах:

(bit) parport.<portnum>.pin-<pinnum>-in: Вивід HAL, пов’язаний з фізичним вхідним виводом <номер виводу> роз’єму db25.
(float) pid.<loopnum>.output: Вихід контуру PID

Іноді може використовуватися скорочена версія назви, наприклад, другий контакт вище можна просто викликати за допомогою .output, коли це можна зробити без плутанини.

2. Загальні правила іменування HAL

Послідовні правила іменування значно полегшили б використання HAL. Наприклад, якби кожен драйвер енкодера мав однаковий набір контактів і називався однаково, то було б легко перейти з одного типу драйвера енкодера на інший. На жаль, як і багато інших проектів з відкритим кодом, HAL є поєднанням елементів, які були розроблені, та елементів, які просто еволюціонували. В результаті існує багато невідповідностей. У цьому розділі ми спробуємо вирішити цю проблему, визначивши деякі правила, але, ймовірно, знадобиться деякий час, перш ніж усі модулі будуть перетворені відповідно до них.

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

Крапки (“.”) розділяють рівні ієрархії. Це аналогічно скісну риску (“/”) в імені файлу.
Дефіси («-») розділяють слова або поля на одному рівні ієрархії.
Компоненти HAL не повинні використовувати підкреслення або «MixedCase». Примітка: [Підкреслені символи були видалені, але все ще є кілька випадків неправильного поєднання, наприклад pid.0.Pgain замість pid.0.p-gain.]
Використовуйте в іменах лише малі літери та цифри.

3. Правила іменування драйверів обладнання

Note	Більшість драйверів у версії 2.0 не дотримуються цих умовних позначень. Цей розділ насправді є керівництвом для майбутніх розробок.

3.1. Назви контактів/параметрів

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

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

Окремі поля:

<device-name>: Пристрій, з яким призначений драйвер. Найчастіше це інтерфейсна плата певного типу, але є й інші можливості.
<device-num>: У комп’ютері можна встановити більше однієї плати сервоприводу, паралельного порту або іншого апаратного пристрою. Номер пристрою ідентифікує конкретний пристрій. Номери пристроїв починаються з 0 і збільшуються на нуль.

<io-type>: Більшість пристроїв забезпечують більше одного типу вводу-виводу. Навіть простий паралельний порт має як цифрові входи, так і цифрові виходи. Більш складні плати можуть мати цифрові входи і виходи, лічильники енкодера, генератори імпульсів pwm або step, аналого-цифрові перетворювачі, цифро-аналогові перетворювачі або інші унікальні можливості. Тип вводу-виводу використовується для ідентифікації виду вводу-виводу, з яким пов’язаний вивід або параметр. В ідеалі драйвери, що реалізують один і той самий тип вводу-виводу, навіть для дуже різних пристроїв, повинні забезпечувати однаковий набір контактів і параметрів та ідентичну поведінку. Наприклад, усі цифрові входи повинні поводитися однаково, якщо дивитися зсередини HAL, незалежно від пристрою.
<chan-num>: Практично кожен пристрій вводу-виводу має кілька каналів, і номер каналу ідентифікує один з них. Як і номери пристроїв, номери каналів починаються з нуля і збільшуються. Примітка: [Єдиним винятком із правила «номери каналів починаються з нуля» є паралельний порт. Його контакти HAL пронумеровані відповідно до номерів контактів на роз’ємі DB-25. Це зручно для підключення, але несумісно з іншими драйверами. Існують суперечки щодо того, чи є це помилкою, чи особливістю.] Якщо встановлено більше одного пристрою, номери каналів на додаткових пристроях починаються з нуля. Якщо можливий номер каналу, більший за 9, то номери каналів повинні бути двозначними, з нулем на початку для чисел менше 10, щоб зберегти порядок сортування. Деякі модулі мають контакти та/або параметри, які впливають на більше ніж один канал. Наприклад, генератор PWM може мати чотири канали з чотирма незалежними входами «робочого циклу», але один параметр «частоти», який контролює всі чотири канали (через обмеження апаратного забезпечення). Параметр частоти повинен використовувати «0-3» як номер каналу.
<specific-name>: Окремий канал вводу/виводу може мати тільки один контакт HAL, але більшість з них мають більше одного. Наприклад, цифровий вхід має два контакти: один відповідає стану фізичного контакту, а інший — його інвертованому стану. Це дозволяє конфігуратору вибирати між активними високими та активними низькими входами. Для більшості типів вводу-виводу існує стандартний набір контактів і параметрів (який називається «канонічним інтерфейсом»), який повинен реалізовувати драйвер. Канонічні інтерфейси описані в розділі Канонічні інтерфейси пристроїв.

Приклади

motenc.0.encoder.2.position: Вихід положення третього каналу енкодера на першій платі Motenc.
stg.0.din.03.in: Стан четвертого цифрового входу на першій платі Servo-to-Go.
ppmc.0.pwm.00-03.frequency: Несуча частота, що використовується для каналів PWM з 0 по 3 на першій платі ppmc від Pico Systems.

3.2. Назви функцій

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

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

<device-name>: Те саме, що використовується для контактів та параметрів.
<device-num>: Конкретний пристрій, до якого функція отримуватиме доступ.
<io-type>: Необов’язково. Функція може мати доступ до всіх входів/виходів на платі або тільки до певного типу. Наприклад, можуть існувати незалежні функції для зчитування лічильників енкодера та зчитування цифрових входів/виходів. Якщо такі незалежні функції існують, поле <io-type> визначає тип входів/виходів, до яких вони мають доступ. Якщо одна функція зчитує всі входи/виходи, що надаються платою, <io-type> не використовується. Примітка: [Примітка для програмістів драйверів: НЕ реалізуйте окремі функції для різних типів входів/виходів, якщо вони не є перериваними і не можуть працювати в незалежних потоках. Якщо переривання зчитування енкодера, зчитування цифрових входів, а потім відновлення зчитування енкодера спричинить проблеми, реалізуйте одну функцію, яка виконує всі ці дії.]
<chan-num-range>: Необов’язково. Використовується лише якщо введення-виведення <io-type> розділене на групи та доступ до нього здійснюється різними функціями.
читати|писати: Вказує, чи функція зчитує дані з обладнання, чи записує на нього.

Приклади

motenc.0.encoder.read: Зчитує всі енкодери на першій платі Motenc.
generic8255.0.din.09-15.read: Зчитує другий 8-бітний порт на першій універсальній платі цифрового вводу/виводу на базі 8255.
ppmc.0.write: Записує всі виходи (генератори кроків, PWM, DAC та цифрові) на першу плату ppmc Pico Systems.