Дерево устройств OrangePi Zero2

Flattened Device Tree (FDT) - плоское дерево устройств представляет собой древовидную структуру, содержащую именованные узлы с набором свойств в виде пар имя-значение. Дерево устройств используется загрузчиком U-Boot и ядром системы.

В командном интерфейсе U-Boot имеется группа команд поддержки дерева устройств FDT .

Исходный бинарный файл FDT находится в образе прошивки Андроид, его имя: sunxi.fex

В файловой системе Android бинарный файл FDT читается по пути: sys/firmware/devicetree/base/fdt

В файловой системе Linux бинарный файл FDT читается по пути: sys/firmware/fdt
Примечание. fdt - имя файла без расширения.

Признаком бинарного формата FDT является magic-слово 0xD00DFEED в начале файла.

Примечания.

1. Файлы sunxi.fex (файл из прошивки) и sys/firmware/devicetree/base/fdt отличаюся, размер sunxi.fex - 129536 байт, размер /base/fdt - 129152 байта (после загрузки дерево модифицируется).

2. Для бинарного файла используется расширение .dtb (DTB -Device Tree Blob)

В файловой системе дерево устройств отображается по пути: sys/firmware/devicetree/base, а также по пути: proc/device-tree.

В FS-формате дерево устройств имеет вид: папка - это узел, а файл - это свойство.

Формат "читабельного" текстового исходного файла DTS (Device Tree Source), из которого компилируется бинарный файл при сборке системы, имеет C-образную структуру с фигурными скобками.

Текстовый DTS-файл можно восстановить двумя способами:

1. Конвертировать из бинарного файла утилитой fdtdump (под Linux).

2. Непосредственно на устройстве через UART вывести текстовый лог командой U-Boot fdt print и сохранить в файл.

Примечание. Вторым способом был восстановлен DTS-формат дерева устройств Orange Pi Zero 2, на основе которого создана представленная здесь справочная БД дерева устройств. При этом на устройстве Orange Pi Zero 2 была установлена SD-карта с записанной ОС Android 10 (файл прошивки загружен с сайта производителя).

Дополнительно

Иерархия дерева устройств - отображение дерева устройств из справочной БД

Деревья двух устройств - сравнение OrangePi Zero2 и TV-бокса

Деревья U-Boot и Base - как изменяется дерево после загрузки ОС

Базовые адреса регистров H616 - адрес устройства в имени узла или значении свойства reg

Структура бинарного файла FDT - формальное описание blob дерева устройств

Инструменты Linux для работы с деревом устройств - справочник по командам (вывод --help)

Оверлеи (наложения) дерева устройств - зачем они нужны

Документы

Как использовать дерево устройств - перевод статьи на eLinux.org

Devicetree Specification v0.2 - спецификация дерева устройств Devicetree.org

Power_ePAPR_APPROVED_v1.1 - спецификация дерева устройств ePAPR

Файлы

Бинарный FDT прошивки - из распакованного образа Android

Бинарный FDT устройства - из папки base на устройстве

Исходный текст DTS-формата - восстановлен командой U-Boot fdt print

Примечание. В кратком описании узлов и свойств дерева устройств (разделы 2 и 3) использованы переводы отдельных пунктов спецификации Devicetree.org .

1. Как пользоваться справочником

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

Вторая проблема - "человекочитабельный" исходный текст дерева представляет собой довольно длинную ленту, чтение и поиск в которой не очень удобен (особенно, на мобильном устройстве). Этот текст больше ориентирован на программный парсинг для конвертации в бинарный формат. Поэтому на его основе сделана БД с соответствуюим веб-интерфейсом для доступа.

Дерево устройств OpiZero2 содержит 500 узлов (с подузлами), включающих 4576 свойств

Корневой узел FDT (/) имеет следующие свойства:

interrupt-parent = <0x00000001>; #address-cells = <0x00000002>; #size-cells = <0x00000002>; model = "sun50iw9"; compatible = "allwinner,h616", "arm,sun50iw9p1";

Узлы первого уровня (базовые) показаны в виде списка из 32-х имен узлов, являющихся ссылками на страницы, раскрывающие их внутреннюю структуру (дочерние подузлы и свойства).

При выводе списка многоуровневых узлов (а также полного дерева) иерархия узлов отображается отступами с символами »

Для каждого узла выводится заголовок, содержащий полный путь, например: Путь узла: / soc@03000000 / pinctrl@0300b000 / uart2@0

Свойство - это пара: имя свойства - значение свойства.
Значения могут иметь следующий тип (формат):

"строка" - строка с нулевым байтом на конце, в dts-файле выделено кавычками

<1234abcd> - 32-битное слово - шестнадцатеричное число u32, в dts-файле выделено угловыми скобками

<12345678 12345678 deadbeef - список 32-битных слов u32, разделенных пробелами, в dts-файле выделено угловыми скобками

[0a 0b 0c 0d de ea ad be ef] - последовательность (произвольный массив) байтов, в dts-файле выделено квадратными скобками

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

имя строки

имя числа , имя списка чисел

имя массива байтов

хештег - имя свойства с символом решетки (#)

имя пустого свойства (свойству не присвоено значение)

Распределение свойств по типам:

"Строка" - 1477

"Число" - 2775

"Байты" - 19

"Хештег" - 197

"Пусто" - 108

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

Примечание. Символом # в исходном файле помечены свойства:

#address-cells

#size-cells

#clock-cells

#gpio-cells

#interrupt-cells

#dma-cells

#mbus-cells

#clocks

#thermal-sensor-cells

#cooling-cells

#iommu-cells

При выводе значений свойств использованы дополнительные форматы:

Обрамляющие символы (кавычки и скобки), указывающие на тип, в значениях удалены

Числовые шестнадцатеричные значения отображаются дополнительно в десятичном и двоичном виде, например:
hex=0x2f706d75
dec=795897205 (777243 K, 759 M)
bin=101111011100000 110110101110101

Цепочки байтов дополнительно отображаются символами в виде текстовой строки, например: reg_cldo3 2f 73 6f 63 40 30 33 30 30 30 30 30 30 2f 74 77 69 40 30 78 30 37 30 38 31 34 30 30 2f 70 6d 75 2f 72 65 67 75 6c 61 74 6f 72 73 2f 63 6c 64 6f 33 00 00
Строка: /soc@03000000 /twi@0x07081400 /pmu /regulators /cldo3

Массивы шестнадцатеричных значений, не содержащие нулей, преобразуются в байты и отображаются в виде текстовой строки, например: reg_sw 0x2f736f63 0x40303330 0x30303030 0x302f7477 0x69403078 0x30373038 0x31343030 0x2f706d75 0x2f726567 0x756c6174 0x6f72732f 0x73770000
Строка: [/so@03000000 /twi@0x07081400 /pmu /regulators /sw]

Некоторые значения конвертированы их hex-формата в числа с учетом единиц измерения физических величин (вольт, герц, секунда и пр.)

2. Стандартные свойства

Cписки узлов, содержащих стандартные свойства

1. compatible - значение состоит из одной или нескольких строк "производитель, модель" (от самых конкретных до самых общих), которые используется для выбора драйвера устройства. Показывают совместимость с семейством аналогичных устройств, потенциально позволяя одному драйверу устройства соответствовать нескольким устройствам.

2. phandle - числовой идентификатор узла, который уникален в пределах дерева устройств, используется другими узлами, которым необходимо ссылаться на узел, связанный со свойством. Примечания. 1. Имя "linux" является устаревшим и используется для совместимости.
2. В исходном файле phandle может отсутствовать и добавляться в бинарный файл при компиляции. В дереве устройств OpiZero2 имеется 406 уникальных идентификаторов phandle.

Список идентификаторов узлов

3. status - указывает на рабочее состояние устройства, возможные значения:

okay - работает

disabled - не работает (не подключено или выключено)

fail - не работает, серьезная ошибка

fail-sss - не работает, серьезная ошибка (с указанием подробностей)

Примечание. Последние два значения статуса в исходном файле отстуствуют, видимо они могут устанавливаться в бинарном FDT при стартовом тестировании.

Узлы cо свойством status

4. address-cells, size-cells - параметры для свойства reg дочернего узла.

# address-cells - количество (32-битовых ячеек) , используемых для кодирования поля адреса в свойстве reg дочернего узла.

# size-cells - количество ячеек , используемых для кодирования поля размера в свойстве reg дочернего узла.

# address-cells и # size-cells могут использоваться в любом узле устройства, который имеет дочерние элементы в иерархии дерева устройств и описывают,как следует обращаться к дочерним узлам устройства.
По умолчанию (если свойство отсутствует или имеет пустое значение) #address-cells = 2, #size-cells = 1

Узлы cо свойством address-cells, size-cells

5. reg - описывает адреса ресурсов устройства в адресном пространстве, определяемом его родительской шиной. Обычно это смещение и длина отображаемых в память блоков регистров ввода-вывода.

Адреса в адресном пространстве, определяемом корневым узлом, являются реальными адресами ЦП.
Значение reg - массив из произвольного числа пар "адрес, длина". Количество ячеек , необходимых для указания адреса и длины, зависит от шины и задаются свойствами # address-cells и # size-cells в родительском узле устройства.

Если родительский узел имеет # size-cells = 0, то поле длины в значении reg должно быть опущено.

Свойство reg представляет физический адрес в адресном пространстве его родительского узла устройства, связанного с узлом, а также объем физического адресного пространства, потребляемого этим устройством.

Узлы с адресами устройств reg

6. ranges - определяет физический адрес устройства.

Значение свойства range описывает соответствие между физическим адресным пространством, определенным шинным узлом (дочерним адресным пространством), и физическим адресным пространством родительского шинного узла (родительским адресным пространством).

Формат значения свойства ranges - произвольное количество троек: (адрес дочерней шины, адрес родительской шины, длина).

Адрес дочерней шины - это физический адрес в адресном пространстве дочерней шины. Количество ячеек для представления адреса зависит от шины и может быть определено из # address-cells узла, в котором появляется свойство ranges.

Адрес родительской шины - это физический адрес в адресном пространстве родительской шины. Количество ячеек для представления родительского адреса зависит от шины и может быть определено из свойства #address-cells узла, определяющего адресное пространство родителя.

Длина определяет размер диапазона в адресном пространстве дочернего элемента. Число ячеек, представляющих размер, можно определить по #size-cells узла, в котором появляется свойство ranges.

Пустое значение свойства ranges указывает, что родительское и дочернее адресное пространство идентично, и преобразование адресов не требуется.

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

Примечание. Свойство ranges присутствует в 4-х узлах дерева устройств Opi Zero2: clocks, soc@03000000, pcie@0x05400000, vind@0
При этом оно имеет пустые значения (кроме узла pcie@0x05400000).

7. device_type - устаревшее свойство

Свойство device_type использовалось в IEEE 1275 ( IEEE Standard for Boot Firmware ) для описания модели программирования устройства FCode.

Поскольку DTSpec не имеет FCode, новое использование этого свойства считается устаревшим, и его следует включать только в узлы ЦП и памяти для совместимости с деревьями устройств, производными от IEEE 1275

Примечание. FCode - язык программирования, который семантически подобен языку программирования Forth, но закодирован как последовательность двоичных байтовых кодов.

В дереве устройств OpiZero2 имеется 115 таких узлов

Узлы со свойством device_type

8. interrupts - определяет прерывания, которые генерируются устройством.

Значение свойства прерывания состоит из произвольного числа спецификаторов прерывания. Формат спецификатора прерывания определяется привязкой корня домена прерывания.

Значения свойства - массив троек 32-разрядных чисел.

Кроме свойства interrupts прерывания описываются также свойствами:

interrupt-controller - наличие свойства контроллера прерывания определяет узел как узел контроллера прерывания.

interrupt-map - это свойство на Nexus-узла, которое связывает один домен прерывания с набором родительских доменов прерывания и указывает, как спецификаторы прерывания в дочернем домене сопоставляются с их соответствующим родителем.

interrupt-parent - имеет одно значение идентификатора phandle, указывающее на родителя прерывания, к которому относится дочерний домен.

interrupt-map-mask - битовая маска, которая применяется к спецификатору прерывания входящего модуля, который ищется в таблице, указанной в свойстве interrupt-map.

interrupt-names - имена прерываний (в стандарте это свойство отсутствует).

#interrupt-cells - определяет количество ячеек, необходимых для кодирования спецификатора прерывания для домена прерывания.

Узлы со свойством interrupt

3. Базовые узлы дерева устройств

1. Root node - единственный корневой узел, потомками которого являются все остальные узлы устройств. Полный путь к корневому узлу /.

Свойства корневого узла

#address-cells - количество ячеек для представления адреса в свойстве reg в дочерних элементах root.

#size-cells - количество ячеек для представления размера в свойстве reg в дочерних элементах root.

model - строка, которая однозначно идентифицирует модель системной платы ("производитель, номер модели")

compatible - список строк ("производитель, модель") архитектуры платформ, с которой совместима данная платформа . Это свойство может использоваться операционными системами при выборе кода для конкретной платформы.

Корневой узел OpiZero2

interrupt-parent = <0x00000001>; #address-cells = <0x00000002>; #size-cells = <0x00000002>; model = "sun50iw9"; compatible = "allwinner,h616", "arm,sun50iw9p1";

2. aliases

3. memory

4. chosen

5. cpus

Для некоторых базовых узлов дерева в справочнике даны ссылки на соответствующие места в описании Soc Alwinner H616, на расшифровку регистров устройств, а также приведена дополниельная информация в виде комментариев (обычно это переводы цитат из сторонних источников), которые могут дать общее и приблизительное представление о смысле и назначении конкретного узла дерева устройств.