Практически все встречающиеся примеры работы с GPIO используют ориентированные на это платы и библиотеки.
Эта статья призвана наглядно показать что суть GPIO вовсе не в специализированности: аппаратной частью выступает обычный чипсет Intel 2022 года, ядро и библиотеки дают возможность доступа по адресу физического адресного пространства, а код определяющий работу с GPIO локализован в программе на 200 строк. Основной упор сделан на концепцию, а не на описание конкретной реализации в коде.
Предупреждение: в статье рассматривается управление устройствами установленными на материнской плате, а не внешним тестовым оборудованием. При неудачном стечении обстоятельств ошибка в логике управления может вызвать НЕРЕМОНТОПРИГОДНОЕ ПОВРЕЖДЕНИЕ ИЛИ ВОЗГОРАНИЕ МАТЕРИНСКОЙ ПЛАТЫ. Не пытайтесь проводить эксперименты с GPIO-выходами, если не уверены в назначении конкретного сигнала
Постановка задачи и концепция решения
Когда необходимость GPIO приходит в контексте конкретной задачи - чем управлять ясно сразу. В моей ситуации это была распаянная производителем на материнскую плату микросхема XR34350 физического уровня последовательного порта. Она является конвертером между сигналом UART, реализованным в мультиконтроллере IT87xx и выведенным на коннектор разъёмом сигналов RS-232/RS-485 для подключения внешних устройств. При старте Linux ядро получает в ACPI информацию о UART мультиконтроллера, но никакой информации об этой микросхеме. Возможность переключения между RS-232 и RS-485 производитель платы заложил лишь в настройках EFI при загрузке, не предусмотрев управления этим после загрузки ОС. А задача появилась именно такая.
Документация, как на управляемую микросхему, так и на хабы Intel находится в свободном доступе. Исходя из неё появилась гипотеза о том, что на материнской плате один из GPIO хаба настроен на режим «выход» и подключен ко входу микросхемы. Но вот к какому из десятков GPIO хаба идёт это подключение, выяснить ни по документации, ни по визуальному осмотру дорожек на плате не удалось.
Для того чтоб это узнать, на основе документации хаба был написан код, который проходится по всем линиям GPIO, определяет какие из них настроены как «выход» и печатает их текущее состояние. Сопоставление изменений напечатанного при разных установленных в BIOS настройках позволило понять какие именно GPIO хаба управляют этой микросхемой. После выявления нужных линий в код была добавлена возможность записи значений, которая позволила не только читать, но и управлять их уровнем из userspace.
Авторское тестирование с успешным переключением вывода для управления микросхемой XR34350 было успешно проведено на чипсетах Q370 и Q670. Полный код программы с примерами вывода, использования и идентификатором лицензии MIT приведён в конце текста.
Детали реализации
Наибольшей сложностью при реализации стало то, что документация на хаб по большей части ориентирована на разработчиков прошивок и не всё, представленное в ней, доступно для ОС.
Конкретно управление GPIO осуществляется через PCIe-фунцию Sideband Bridge. Данная PCIe-функция имеет два доступных процессору региона: PCI Configuration Space и Memory Mapping BAR. Поскольку её использование операционной системой не предпоалагается – к моменту старта ОС UEFI выключает Configuration Space, таким образом исключая данную PCIe-функцию из перечисляемых устройств.
Согласно экспериментам 2017 года Configuration Space можно просто временно включить назад, но по совокупности причин ниже предлагается другое решение.
Дело в том, что обращение к Configuration Space нужно только для того, чтоб узнать одно число: адрес Memory Mapping BAR. И если узнать его другим способом, то доступ к Configuration Space становится неактуален.
Оказалось, что после загрузки этот адрес доступен как значение ACPI-региона с именем SBRG. Если ядро собрано с опцией CONFIG_ACPI_DEBUGGER, то из пространства пользователя это значение можно считать; так собраны, например, ядра Ubuntu. Во многих других дистрибутивах оно собрано без этой опции, и в случае такого ядра считать значение ACPI без написания/досборки модуля ядра затруднительно. Доступность этого механизма проверяется командой, которая в случае успеха выведет значение адреса.
# (timeout 1 cat& echo Evaluate SBRG >&0; wait) 0<>/sys/kernel/debug/acpi/acpidbg
- Evaluating \SBRG
Evaluation of \SBRG returned object 0000000026bb761f, external buffer length 18
[Integer] = 00000000FD000000
При недоступности acpidbg желаемый адрес можно просто подобрать благодаря тому, что эта часть адресного пространства не меняется при перезагрузке и имеет не очень большую вариативность между разными системами. На небольшом количестве моих тестовых систем встретилось всего 2 варианта - SBREG_BAR=0xFD000000 на чипсетах поколений 3x0-5x0 и SBREG_BAR=0xE0000000 на более новых.
Зная этот адрес уже в полном соответствии с разделами Configuration Space
Target Port ID и GPIO документации Intel можно найти биты, отвечающие за состояние GPIO, учитывая при этом отличающееся на разных поколениях смещение в региcтре PADBAR. Механизмы тонкой настройки и перечисления заметно отличаются даже между соседними поколениями, но бит включенности режима «выход» и бит задающий его уровень, к счастью, совпадают. Это позволило решить задачу перечисления GPIO, находящихся в режиме «выход», и управления ими кодом общим между поколениями - достаточно создать отображение /dev/mem по смещению SBREG_BAR в адресное пространство приложения и работать с этим Memory Mapping в соответствии с документацией на регистры Sideband Bridge.
Приложенный в конце код и является отлаженным вариантом реализации этого алгоритма. Поскольку эта статья концентрируется на концепциях, детального разбора каждой операции в коде здесь не будет – он просто соотвествует ссылкам на документацию, и приведён как демонстрация работоспобности подхода. Более детальная информация о статусе оказалась слишком разной между поколениями, и попытки её интерпретировать закомментированы.
Другим различием между поколениями является указанная в документации нумерация GPIO. Она очень разная и сложно формализуемая, поэтому наиболее удачным методом для указания конкретного GPIO, совместимым между поколениями, оказалось не штатное именование, а пара индексов, основанных на адресации памяти.
GPIO-линии чипсета объединены в 5-6 групп, называемых GPIO Community. Каждая группа отображает свои регистры в область размера 0x10000 в Memory Mapping обсуждаемого Sideband Bridge, такая область называется Port. Соответствие индексов группы и индекса Port на который она отображена одинаково для широкого диапазона поколений: GPIO Community0 занимает Port с индексом 0x6E, следующие группы занимают последовательно меньшие индексы.
Однозначным методом указания конкретной линии GPIO, по сути просто задающей адрес конкретного регистра, является пара индексов:
(индекс группы – он соответствует номеру GPIO Community в документации; индекс регистра в этой группе – он НЕ соответствует номерам линий GPIO в документации группы, потому что она менялась между поколениями).
Для избежания путаницы с другими индексами в выводе и аргументах эта пара записывается в hex c разделителем ~x. Например, 4~x1A это GPIO по смещению 26 в GPIO Community4.
Собрав всё это вместе, я получил код, который умеет перечислять GPIO, настроенные на выход, отображая их текущий уровень. А при запуске с аргументом – менять состояние такого выхода. На Ubuntu и других системах с включенным в ядре CONFIG_ACPI_DEBUGGER программа не требует дополнительных опций; там же где его нет – надо вручную задавать адрес SBREG установкой переменной окружения вида SBREG_BAR=0xE0000000.
Также, целевая система не должна иметь лимитов для root-пользователя, в том числе давать полный доступ к /dev/mem. Подобное требование естественно для систем, суть работы которых – прозрачный транспортный уровень взаимодействия с оборудованием, а все вопросы угроз перенесены на внешний узел.
Примеры использования
Вывести список регистров, настроенных как выходы, и их текущие значения (число после TX) можно так:
sudo python3 intel_pch_gpio.py
Это относительно безопасная операция: она показывает регистры, которые, вероятно, можно менять для конкретного BIOS. Скрипт может завершиться ошибкой из-за отсутствия /sys/kernel/debug/acpi/acpidbg; в этом случае нужно узнать адрес SBREG_BAR из другого источника и запустить, указав его через переменную окружения:
sudo SBREG_BAR=0xADDRADDR python3 intel_pch_gpio.py
На некоторых PCH 3x0–5x0 адрес SBREG_BAR равен 0xFD000000, на некоторых 6x0 — 0xE0000000.
Пример работы:
- Evaluating \SBRG
Evaluation of \SBRG returned object 00000000eaafa37e, external buffer length 18
[Integer] = 00000000E0000000
SBREG_BAR=0xE0000000 based GPIOS, only TX pads filtered:
GPIOCommunity@6E0000: PADBAR 0x700
PadCfgDw_Array_96@6E0700:
0~x08 TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x21
GPIOCommunity@6D0000: PADBAR 0x700
PadCfgDw_Array_96@6D0700:
1~x17 TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x67
1~x19 TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x69
1~x1B TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x6B
1~x1C TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x6C
GPIOCommunity@6C0000: PADBAR 0x700
PadCfgDw_Array_96@6C0700:
GPIOCommunity@6B0000: PADBAR 0x700
PadCfgDw_Array_96@6B0700:
GPIOCommunity@6A0000: PADBAR 0x700
PadCfgDw_Array_96@6A0700:
4~x0A TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x3A
4~x15 TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x45
4~x19 TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x49
4~x1A TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x4A
Asked setting 4~x1A to target_value='1'
setting done, new value:
4~x1A TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x4A
4~x1B TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x4B
4~x1C TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x4C
4~x1D TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x4D
4~x39 TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x67
4~x3A TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x68
4~x3B TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x69
4~x3D TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x6B
4~x3E TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x6C
4~x3F TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x6D
4~x40 TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x6E
4~x41 TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x6F
4~x42 TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x70
4~x43 TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x71
4~x44 TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x72
4~x45 TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x73
GPIOCommunity@690000: PADBAR 0x700
PadCfgDw_Array_96@690700:
А вот запись (пример ниже) совсем небезопасна: можно повредить ПК так, что его не получится починить, или даже вызвать возгорание. Используйте на свой страх и риск, только если понимаете, за что отвечает конкретный GPIO-выход.
Для установки в 1 GPIO-выхода x1A в GPIOCommunity4 на тестируемой Q670 была дана команда: python3 intel_pch_gpio.py 4~x1A= 1. При работе в таком режиме, если при перечислении указанный GPIO находится в режиме «выход», меняется его значение и печатается сообщение об этом:
...
4~x1A TX 0x0 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x4A
Asked setting 4~x1A to target_value='1'
setting done, new value:
4~x1A TX 0x1 RX 0x0 TXDisable 0x0 RXDisable 0x1 Native 0x0 InterruptSel 0x4A
...
реализация - всё в одном файле
#!/usr/bin/env python3
"""
A script to read (and change) Intel 3xx-8xx PCH GPIO TX (output) lines
using only python>=3.10 stdlib
SPDX-License-Identifier: MIT
"""
import ctypes
import os
import pathlib
import sys
import select
import mmap
ACPIDBG_BIDI_FILE = pathlib.Path("/sys/kernel/debug/acpi/acpidbg")
ACPI_OBJ_NAME = r"\SBRG"
PHYS_MEM = pathlib.Path("/dev/mem")
# values common for 300-800 series intel chipsets
P2SB_PORT_GPIO_COMMUNITY0 = 0x6E
P2SB_PORT_GPIO_COUNT = 6
P2SB_PORT_SIZE = 0x10000
MAX_PAD_COUNT = 96 # maximal pad count for all communities
class StrViaFields:
def __str__(self):
def pretty(value):
if isinstance(value, int):
return f"0x{value:X}"
if isinstance(value, StrViaFields):
return f"({str(value).strip()})"
return value
def format_field(field_name: str) -> str:
if not field_name.strip("_01234567890"):
return ""
return f" {field_name} {pretty(getattr(self, field_name))}"
return "".join(format_field(field[0]) for field in self._fields_)
class RegisterFileStruct(ctypes.Structure, StrViaFields):
pass
class PadCfgDw(RegisterFileStruct):
_fields_ = [
("TX", ctypes.c_uint32, 1),
("RX", ctypes.c_uint32, 1),
("_0", ctypes.c_uint32, 6),
("TXDisable", ctypes.c_uint32, 1),
("RXDisable", ctypes.c_uint32, 1),
("Native", ctypes.c_uint32, 6),
("_1", ctypes.c_uint32, 1),
("_2", ctypes.c_uint32, 15), # don't decode fields below
# ('GPINMI', ctypes.c_uint32, 1),
# ('GPISMI', ctypes.c_uint32, 1),
# ('GPISCI', ctypes.c_uint32, 1),
# ('GPIAPIC', ctypes.c_uint32, 1),
# ('RXTXNative', ctypes.c_uint32, 2),
# ('RXInv', ctypes.c_uint32, 1),
# ('PreGlitch', ctypes.c_uint32, 1),
# ('RXEvent', ctypes.c_uint32, 3),
# ('RXRaw1', ctypes.c_uint32, 1),
# ('RXStSel', ctypes.c_uint32, 1),
# ('PadRst', ctypes.c_uint32, 2),
("InterruptSel", ctypes.c_uint8),
("_3", ctypes.c_uint8 * 3), # don't decode fields below
# ('StandbyTerm', ctypes.c_uint32, 2),
# ('Termination', ctypes.c_uint32, 4),
# ('Standby', ctypes.c_uint32, 18),
("_4", ctypes.c_uint8 * 8),
]
assert ctypes.sizeof(PadCfgDw) == 0x10, f"Unexpected {ctypes.sizeof(PadCfgDw)=}"
class GPIOCommunity(RegisterFileStruct):
_fields_ = [
("_0", ctypes.c_uint8 * 0xC), # ends 0x0C
("PADBAR", ctypes.c_uint32), # ends 0x10
]
def p2sbaddr(gpioidx, offset):
addr = (P2SB_PORT_GPIO_COMMUNITY0 - gpioidx) * P2SB_PORT_SIZE + offset
assert addr > 0
assert addr % 4 == 0
return addr
def main(argv: list[str]):
# GPIOS are mapped into Sideband Register Access BAR (SBREG_BAR)
# Its base address is hidden in PCIe config space, but can be accessed via SBRG ACPI value
sbreg_bar = int(os.getenv("SBREG_BAR", "0x0"), 16)
if not sbreg_bar:
try:
acpi_dbg = ACPIDBG_BIDI_FILE.open("r+b", buffering=0)
except Exception:
print(f"""Problem opening {ACPIDBG_BIDI_FILE},
esnure that CONFIG_ACPI_DEBUGGER is enabled in kernel config or acpi_dbg module loaded,
debugfs mounted to /sys/kernel/debug, and you are running with suitable root-like access.
note: CONFIG_ACPI_DEBUGGER is enabled in ubuntu, but not in other distros by default
Or provide the SBREG_BAR environment variable having its value before running this.
Some 3x0-5x0 PCHs have SBREG_BAR=0xFD000000 some 6x0 PCHs have SBREG_BAR=0xE0000000""")
os._exit(1)
with acpi_dbg:
acpi_dbg.write(f"Evaluate {ACPI_OBJ_NAME}\n".encode())
os.set_blocking(acpi_dbg.fileno(), False)
concat_result = ""
while select.select([acpi_dbg.fileno()], [], [], 1.0)[0]:
concat_result += acpi_dbg.read().decode()
for line in concat_result.splitlines():
if not line:
continue
print(line)
lparts = line.split("=")
if len(lparts) == 2:
sbreg_bar = int(lparts[1], 16)
break
else:
raise RuntimeError(
f"Address result not found in evaluation of {ACPI_OBJ_NAME=}\n"
"looks like incompatible hardware platform."
"Only Intel 3x0+ PCHs are known to be supported (practically tested up to 6x0 PCHs)"
)
print(f"SBREG_BAR=0x{sbreg_bar:X} based GPIOS, only TX pads filtered:")
with (
PHYS_MEM.open("r+b") as phys_mem_file,
mmap.mmap(
phys_mem_file.fileno(),
P2SB_PORT_SIZE * (P2SB_PORT_GPIO_COMMUNITY0 + 1),
offset=sbreg_bar,
) as regs_map,
memoryview(regs_map).cast("I") as regs_u32,
):
for gpioidx in range(0, P2SB_PORT_GPIO_COUNT):
def load(type, offset):
a = p2sbaddr(gpioidx, offset)
obj = type.from_buffer(regs_u32, a)
info = f"{type.__name__}@{a:06X}:"
if not isinstance(obj, ctypes.Array):
info += f" {obj}"
print(info)
return obj
gpio = load(GPIOCommunity, 0)
if (gpio.PADBAR < 0x600) or (0 != gpio.PADBAR % 0x80):
print(
f"Unexpected {gpio.PADBAR=:0x}hex, seems this platform lacks GPIOCommunity{gpioidx}"
)
continue
pads = load(PadCfgDw * MAX_PAD_COUNT, gpio.PADBAR)
for idx, p in enumerate(pads):
# only TX pads filtering
if p.RXDisable and not p.TXDisable and not p.Native:
gpiopath = f"{gpioidx}~x{idx:02X}"
print(gpiopath, p)
cmd_to_search = f"{gpiopath}="
if cmd_to_search in argv:
target_value = argv[1 + argv.index(cmd_to_search)]
print(f"Asked setting {gpiopath} to {target_value=}")
target_int = int(target_value)
if p.TX == target_int:
print("value already set, nothing to change")
else:
p.TX = target_int
print("setting done, new value:")
print(gpiopath, p)
if not argv:
print(
"\n"
"Arguments not passed, so only reading was done. If you truly understand which TX GPIO\n"
"to write you can do it by passing 2 arguments AT YOUR OWN RISK OF PERMANENT HARDWARE DAMAGE!\n"
"first is 'GPIO line id from first column, folowed by =', second is the desired value - '0' or '1'\n"
f"Example {sys.argv[0]} 4~x6B= 0\n"
)
sys.stdout.flush()
os._exit(0) # immediate exit without destroying python mapping objects linked from ctypes objects
if __name__ == "__main__":
main(sys.argv[1:])



