enum-devices

Менеджер-перечислитель устройств

Примечание. Для запуска этого менеджера необходимо войти в систему под учетной записью root.

Синтаксис:

enum-devices опции

Поддерживаемые платформы:

Neutrino

Опции:

-c путь

Указать один или несколько конфигурационных файлов. В качестве значения переменной можно указать отдельный файл или каталог.
Для определения нескольких конфигурационных файлов и каталогов эту опцию можно указать повторно. Кроме того, для добавления других файлов и каталогов (см. ниже) можно использовать выражение config в конфигурационном файле.

Перед началом обработки утилита enum-devices выполняет конкатенацию содержимого всех конфигурационных файлов, указанных для считывания.

-D

Выгрузить таблицу поиска устройств.

-E перечислитель

Запустить программу-перечислитель второго прохода.

-e перечислитель

Выполнить данную команду программы перечислитель:

-i префикс

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

-I суффикс

Игнорировать любые конфигурационные файлы в каталогах, в конце имени которых находится суффикс.

-n

Записать команды для запуска драйверов в стандартный поток вывода вместо их выполнения.

-v[v...]


Вывести расширенную информацию. Большее количество символов v обеспечивает вывод более подробной информации.

Описание:

Разделы описания enum-devices:

Обзор

Менеджер enum-devices перечисляет устройства, имеющиеся на данном компьютере. Сначала менеджер считывает данные из конфигурационных файлов, указанных с помощью любой из опций командной строки -c.

После этого конфигурационный менеджер опрашивает различные перечислители с целью определения устройств, имеющихся в системе. Затем выполняется сопоставление этих устройств и идентификаторов устройств, указанных в конфигурационных файлах. При совпадении обнаруженного устройства с данными в конфигурационном файле enum-devices выполняет действия, указанные для этого устройства.

Примечание. Фактическое выполнение программ, указанных в любых выражениях start и requires, начинается после завершения обработки, т.е. после выполнения всех строк встроенных команд. При необходимости выполнения действия вне зависимости от наличия тех или иных устройств следует использовать идентификатор устройства all.

Правила сопоставления

Поведение сопоставления, реализуемое при использовании утилиты enum-devices, основано на "количестве совпадений" в операторе устройств конфигурационного файла утилиты enum-devices. Для создания вторичного оператора устройств можно указать точку (".") перед полем сопоставления.

Использование этого метода сопоставления устройств с записями в конфигурационном файле enum-devices иногда может приводить к возникновению "неоднозначности": если указанное устройство соответствует нескольким записям в конфигурационном файле утилиты enum-devices, выбор перечислителем предпочтительного драйвера для устройства становится невозможным.

Например, если устройство определено следующим образом:

ven=1922,dev=1234,busno=0,devno=1,

rev=100,msven=fe,mscomp=MTP,mssubcomp=0

и в конфигурационном файле утилиты enum-devices содержится следующее:

device(usb, ven=1922,dev=1234)

device(usb, class=08,proto=00)


то указанное устройство соответствует обеим записям в конфигурационном файле.

Возникновение неоднозначности можно предотвратить путем расширения критериев совпадения для предпочтительного драйвера:

device(usb, ven=1922,dev=1234,class=08)

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

device(usb, .class=08,proto=00)

Для поиска любых совпадений ("catch all") (поиска совпадений с любым устройством) следует просто указать тип шины устройства. Пример.

device(usb)

echo("No match found for device ven=$(ven),

dev=$(dev), class=$(class), busno=$(busno),

devno=$(devno), cfg=$(cfg), iface=$(iface),

msven=$(msven), mscomp=$(mscomp),

mssubcomp=$(mssubcomp)" )


Конфигурационные файлы

В каталоге etc/system/enum/ находятся следующие конфигурационные файлы:
etc/system/enum/devices/

В конфигурационных файлах, находящихся в каталоге etc/system/enum/devices/, содержатся определения устройств. В число этих файлов входят:

etc/system/enum/devices/usb/

В каталоге etc/system/enum/devices/usb/ находятся следующие конфигурационные файлы:

etc/system/enum/include/

В конфигурационных файлах, находящихся в каталоге etc/system/enum/include/, содержатся определения макросов. В число этих файлов входят:

Старшинство конфигурационных файлов

Порядок старшинства конфигурационных файлов утилиты enum-devices определяется одним или обоими следующими критериями:

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

Принимая во внимание сложность, связанную с добавлением и удалением файлов и каталогов во время обработки, при работе в среде QNX рекомендуется
Содержимое конфигурационных файлов

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

Для конфигурационного файла утилиты enum-devices обычно используется следующий формат:

/enum

common

/devices

default

net

mass

char

/include

usb-class

/overrides

mass


Любые данные, указанные после символа решетки (#) до конца строки, рассматриваются как комментарий.

Для всех операторов используется следующий формат:

идентификатор_устройства…

выражение_действия

…

Идентификатор_устройства может быть представлен ключевым словом all или любым количеством идентификаторов в следующем формате:

device(тип_шины[, параметры]...)


Типы шин могут быть представлены, по крайней мере, следующими значениями:
Каждое выражение представляет собой ключевое слово, за которым могут следовать любые необходимые аргументы. Предусмотрены следующие выражения:

start

Запустить команду.

requires

Запустить команду, если она еще не выполняется.

driver

Запустить команду в качестве отдельного драйвера, если устройство может быть отключено.

mount

Запустить утилиту mount с указанными аргументами.

enumerator

Запустить новый перечислитель шины.

set

Установить макрос.

append

Добавить к макроопределению.

uniq

Установить макрос в значение, зависящее от того, найдена строка во внутренней базе данных или нет.

waitfor

Ждать появления указанного путевого имени.

echo

Вывести строку в файл.

tag

Присвоить имя блоку выражений действия.

config

Загрузить дополнительные конфигурационные файлы или каталоги.

use


Объединить макроопределения.

Описание выражений приведено в следующих разделах.

Выражение start

Для выражения start используется следующий формат:

start[/wait] (системная_команда [, системные_аргументы] )


Это выражение выполняет команду системная_команда с использованием заданных аргументов. Если указана опция /wait, то работа перечислителя приостанавливается до завершения команды.

Если указаны системные_аргументы, то менеджер выполняет поиск выражения start с командой системная_команда, идентичной данной команде, и добавляет системные_аргументы в командную строку. Этот способ целесообразно использовать при необходимости запуска только одного экземпляра команды с определением аргументов, требующихся для всех обнаруженных устройств.

Например, выражение

start(spooler -d$(path), -P$(pnpstr))
запускает spooler -d$(path). При этом для утилиты enum-devices указывается, что если данная команда уже встречалась ранее, то к ней просто следует добавить аргумент -P$(pnpstr). (Формат $(...) используется для макрорасширения; см. приведенное ниже описание выражения set.)

Выражение requires

Для выражения requires предусмотрена возможность использования одного из двух форматов:

requires[/wait] (системная_команда [, системные_аргументы] )


Этот формат аналогичен формату выражения start, но в данном случае утилита enum-devices проверяет наличие в системе уже выполняемой команды.

Примечание. Если указаны системные_аргументы, разделителем между системная_команда и системные_аргументы является запятая. Если запятая не указана, утилита enum-devices не выполняет проверку наличия в системе уже выполняемой команды, что может привести к ее многократному выполнению.

Например, в файле перечислителя устройств /etc/system/enum/devices/net содержится следующая строка для сетевых устройств, для которых требуется io-pkt*:

requires($(IOPKT_CMD),)

requires[/wait] (@строка_тегов)


При использовании этого формата утилита enum-devices осуществляет поиск тегов с именами, указанными в переменной имя_тега, во всех рабочих строках, ожидающих обработки (см. описание выражения tag), и выполняет их. Использование этого метода может быть целесообразным при необходимости упорядочения различных компонентов.

Если в любом из форматов указана опция /wait, то работа перечислителя приостанавливается до завершения команды.

Выражение driver

Для выражения driver используется следующий формат:

driver[/wait] (системная_команда [, системные_аргументы] )


Формат аналогичен формату выражения start. Но в данном случае, если процесс перечислителя шины передает данные о том, что устройство может быть отключено, утилита enum-devices запускает для устройства отдельный процесс драйвера (вместо добавления аргументов системные_аргументы к драйверу, ранее указанному для этого устройства). Если процесс перечислителя шины передает данные о том, что устройство отключено, то в процесс драйвера передается сигнал SIGTERM.

Если указана опция /wait, то работа перечислителя приостанавливается до завершения команды.

Выражение mount

Для выражения mount используется следующий формат:

mount (аргументы_монтирования [, аргументы_демонтирования] )


Это выражение порождает команду mount с аргументами аргументы_монтирования. Если указаны какие-либо аргументы_демонтирования, то они передаются в команду umount в случае отключения устройства.

Выражение enumerator

Для выражения enumerator используется следующий формат:

enumerator (тип_перечислителя)


Это выражение запускает новый перечислитель, указанный в переменной тип_перечислителя.

Выражение set

Для выражения set используется следующий формат:

set (имя_макроса, макроопределение)

Это выражение определяет значение имя_макроса как макроопределение. Каждый раз, когда утилита enum-devices находит $(имя_макроса) в любом из конфигурационных файлов, подставляется макроопределение. Пример.

set(DEVB_OPTIONS, cam quiet blk auto=partition)


Предусмотрена возможность рекурсивного вложения макросов так же, как при работе с утилитой make.

Выражение append

Для выражения append используется следующий формат:

append (имя_макроса, макроопределение)


Это выражение добавляет макроопределение к определению имя_макроса.

Выражение uniq

Для выражения uniq используется следующий формат:

uniq (имя_макроса, уникальное_имя [, начальное_значение] )

Это выражение инициирует поиск утилитой enum-devices строки уникальное_имя во внутренней базе данных:
Например, выражение uniq можно использовать для отслеживания количества найденных экземпляров устройства и создания для него уникального пути:

uniq(sernum, devc-ser, 1)

driver(devc-ser8250 $(SER_OPTIONS), "-u$(sernum) $(ioport),$(irq)")


Выражение waitfor

Для выражения waitfor используется следующий формат:

waitfor (путевое_имя [, таймаут] )

Это выражение определяет таймаут, задаваемый в десятых долях секунды, ожидания появления пути путевое_имя. Значение параметра таймаут по-умолчанию - 10 секунд.

Выражение echo

Для выражения echo используется следующий формат:

echo (строка [, выходной_файл] )


строка выводится в указанный выходной_файл. Если это первое вхождение echo для этого вызова конфигурационного менеджера, утилита enum-devices стирает выходной_файл перед выводом данных. В дальнейшем утилита enum-devices дополняет файл данными. Если выходной_файл не указан, выходные данные передаются в стандартный поток вывода.

Выражение tag

Для выражения tag используется следующий формат:

tag (строка_тегов)


Это выражение присваивает имя (строка_тегов) последующему блоку выражений действия. Это выражение следует использовать для определения команд, подлежащих выполнению при использовании второго формата выражения requires.

Выражение config

Для выражения config используется следующий формат:

config (путь)


Это выражение инициирует загрузку дополнительного конфигурационного файла или каталога утилитой enum-devices в соответствии со значением параметра путь. Обработка этого выражения осуществляется аналогично опции командной строки -c, за исключением того, что указанное путевое имя относится к конфигурационному файлу, содержащему выражение.

Выражение use

Для выражения use используется следующий формат:

use (список_устройств)

При обнаружении этого выражения утилита enum-devices выполняет следующие действия:
Макросы

Доступны к использованию несколько специальных макросов. Значение этих макросов зависит от шины, на которой находится устройство.

Макросы для устройств PCI:

$(ven)

Идентификатор вендора PCI.

$(dev)

Идентификатор устройства PCI.

$(index)

PCI-индекс.

$(busnum)

Номер шины PCI.

$(function)


Номер функции PCI.

Протокол перечислителя шины

Для обработки аспектов распознавания устройств на шине утилита enum-devices порождает отдельные программы-перечислители шины. Стандартный поток вывода этих программ подключается к каналу данных, из которого утилита enum-devices считывает данные. Поскольку перечислитель шины выполняет сканирование соответствующей ему шины, строки с описанием обнаруженных параметров записываются в стандартный поток вывода. Запись каждой строки в канал должна осуществляться атомарно. В начале каждой строки указывается односимвольный код (определенный в файле в формате ENUMER_CODE_*), за которым сразу следует идентификатор процесса перечислителя шины.

Для каждого макроопределения на языке C допускается запись следующих строк:

ENUMER_CODE_DEV_PERM

Эта строка обеспечивает передачу информации о постоянно подключенном устройстве (т.е. устройстве, которое никогда не будет удалено во время работы системы):

Dpid { макрос=значение }

Последовательность имен макросов и значений, следующая за кодом D и идентификатором процесса pid. Если требуется задать несколько макросов, то в качестве разделителя следует использовать пробел. Эти макросы используются для расширения в выражениях действия, вызываемых утилитой enum-devices для устройства.

Для обеспечения возможности идентификации устройств утилитой enum-devices следует определить следующие специальные макросы:

#define ENUMER_SYM_BUSTYPE "bus"

#define ENUMER_SYM_VENDOR "ven"

#define ENUMER_SYM_SUBVENDOR "dev"

#define ENUMER_SYM_CLASS "class"

#define ENUMER_SYM_SUBCLASS "subclass"

ENUMER_CODE_DEV_TEMP

Эта строка аналогична строке ENUMER_CODE_DEV_PERM, за исключением того, что в данном случае можно удалить устройство во время работы системы:

dpid { макрос=определение }

В дополнение к обязательным определениям макросов, приведенным выше, также необходимо определить следующие:

#define ENUMER_SYM_REMOVAL_ID "removal_id"

Значение макроса должно быть простым целым числом.

ENUMER_CODE_DEV_ACTIVE

Эта строка аналогична строке ENUMER_CODE_DEV_PERM, за исключением того, что указанное устройство уже работает в системе:

apid { макрос=определение }

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

ENUMER_CODE_DEV_REMOVED

Эта строка передается в случае удаления устройства из работающей системы:

gpid { макрос=определение }

Требуется только одно макроопределение: для упомянутого выше макроса ENUMER_SYM_REMOVAL_ID. В качестве значения следует задать целое число равное значению, указанному при передаче информации об устройстве в первый раз. Программа enum-devices использует его для определения процессов драйверов, подлежащих уничтожению, или путевых имен, подлежащих демонтированию.

ENUMER_CODE_BUS

Эта строка используется для передачи информации о дополнительных шинах, для которых требуется запустить программы-перечислители:

Bpid { макрос=определение }

Для этой строки предусмотрен такой же синтаксис и требования, как и для строки ENUMER_CODE_DEV_PERM.

ENUMER_CODE_SCAN_DONE

Эта строка записывается после окончания сканирования соответствующей шины перечислителем шины:

Fpid

После записи этой строки всеми запущенными перечислителями шин утилита enum-devices вызывает требуемые выражения действия (следует отметить, что для строки ENUMER_CODE_BUS вызов действий производится незамедлительно). Если возможность добавления/удаления каких-либо устройств на шине отсутствует, перечислитель шины после записи этой строки должен завершить работу. При наличии временных устройств перечислитель шины должен продолжать работу и записать события ENUMER_CODE_DEV_TEMP и/или ENUMER_CODE_DEV_REMOVED, за которыми записывается еще одна строка ENUMER_CODE_SCAN_DONE при добавлении или удалении устройств.

ENUMER_CODE_ERROR

Эта строка записывается при обнаружении перечислителем шины какой-либо ошибки:

Epid текст_сообщения_об_ошибке

Менеджер enum-devices выводит текст_сообщения_об_ошибке, отображаемый для пользователя.

ENUMER_CODE_COMMENT

Строки данного типа игнорируются менеджером enum-devices. Их можно использовать для получения дополнительной информации в случае, когда перечислитель шины работает в автономном режиме:

#pid текст_комментария

Примеры:

Ниже приведен пример конфигурационного файла:

# установка префиксов для групповых команд

all

# для удобочитаемости можно указать "pci($(ATI), ....)

set( ATI, 0x1234 )

echo( "Начало конфигурирования" )

# запуск драйвера жесткого диска

device(pci,1234,5678)

start( devb-ncr8 ncr8 pci=$(index) )

# запуск сетевого драйвера (в настоящий момент)

device(pci,0x1234,0x5678)

start( io-pkt-v4, -d speedo pci=$(index) )

# запуск сетевого драйвера (с поддержкой монтирования)

device(cardbus,1234,5678)

requires( io-pkt-v4 )

start( mount, -T none -o pci=$(index) ne2000 /dev/if0 )

# запуск графического драйвера (например)

device(pci,1234,5678)

echo( $(ven) $(dev) $(bus) $(device) $(function), /etc/devg.$(hostname) )

# установка постфиксов для групповых команд

all

echo( "Конфигурирование завершено" )

Примечание.