Использование DMA (dma.h)

API определен в заголовочном файле sysroot-*-kos/include/coresrv/io/dma.h из состава KasperskyOS SDK.

API предназначен для организации обмена данными между устройствами и оперативной памятью в режиме прямого доступа к памяти (англ. Direct Memory Access, DMA), при котором процессор не используется.

Сведения о функциях API приведены в таблице ниже.

Использование API

Типовой сценарий использования API включает следующие шаги:

1. Создание буфера DMA.

   Буфер DMA –это буфер, состоящий из одного или нескольких регионов физической памяти (блоков), используемых для DMA. Буфер DMA, состоящий из нескольких блоков, можно использовать, если устройство поддерживает режим "scatter/gather DMA". Буфер DMA, состоящий из одного блока, можно использовать, если устройство поддерживает режим "scatter/gather DMA" или "continuous DMA". Вероятность создать буфер DMA, состоящий из одного большого блока, ниже, чем вероятность создать буфер DMA, состоящий из нескольких небольших блоков. Это особенно актуально при высокой фрагментации физической памяти.

   Если устройство поддерживает только режим "continuous DMA", то даже при задействовании IOMMU нужно использовать буфер DMA, состоящий из одного блока.

   Чтобы выполнить этот шаг, нужно вызвать функцию KnIoDmaCreate() или KnIoDmaCreateContinuous(). Функция KnIoDmaCreateContinuous() создает буфер DMA, состоящий из одного блока. Функция KnIoDmaCreate() создает буфер DMA, состоящий из одного блока, если значение 2^order равно значению size/размер страницы памяти, или значение 2^order является ближайшим большим к значению size/размер страницы памяти в упорядоченном по возрастанию множестве {2^(order-1);size/размер страницы памяти;2^order}. Если значение size/размер страницы памяти больше значения 2^order, функция KnIoDmaCreate() может создать буфер DMA, состоящий из нескольких блоков.

   Параметры кеширования буфера DMA могут быть изменены вызовом функции KnIoDmaModify().

   Дескриптор буфера DMA можно передать другому процессу через IPC.

2. Отображение буфера DMA на память процессов.

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

   Чтобы зарезервировать регион виртуальной памяти и отобразить на него буфер DMA, нужно вызвать функцию KnIoDmaMap().

   Дескриптор, полученный при вызове функции KnIoDmaMap(), нельзя передать другому процессу через IPC.

3. Открытие доступа к буферу DMA для устройства вызовом функции KnIoDmaBegin() или KnIoDmaBeginEx().

   Вызов функции KnIoDmaBegin() или KnIoDmaBeginEx() необходим, чтобы создать объект ядра, содержащий адреса и размеры блоков, из которых состоит буфер DMA. Эти сведения необходимы устройству, чтобы использовать буфер DMA. Устройство может работать как с физическими, так и с виртуальными адресами в зависимости от того, задействован ли IOMMU. Если IOMMU задействован, нужно использовать функцию KnIoDmaBegin() или KnIoDmaBeginEx(), и объект будет содержать виртуальные и физические адреса блоков. Если IOMMU не задействован, нужно использовать функцию KnIoDmaBegin(), и объект будет содержать только физические адреса блоков.

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

   Дескриптор, полученный при вызове функции KnIoDmaBegin() или KnIoDmaBeginEx(), нельзя передать другому процессу через IPC.

4. Получение сведений о буфере DMA.

   На этом шаге нужно получить адреса и размеры блоков из объекта ядра, созданного вызовом функции KnIoDmaBegin() или KnIoDmaBeginEx(). Полученные адреса и размеры в дальнейшем требуется передать устройству, используя, например, MMIO. После получения этих сведений устройство может записывать в буфер DMA и/или читать из него.

   Чтобы выполнить этот шаг, нужно вызвать одну из следующих функций:

   • KnIoDmaGetInfo();
   • KnIoDmaGetPhysInfo();
   • KnIoDmaContinuousGetDmaAddr();
   • KnIoDmaContinuousGetPhysAddr().

   Функции KnIoDmaGetInfo() и KnIoDmaGetPhysInfo() позволяют получить номер страницы памяти (frame) и порядок (order) для каждого блока. (Номер страницы памяти, умноженный на размер страницы памяти, дает адрес блока. Значение 2^order представляет собой размер блока в страницах памяти.) Через выходной параметр outInfo эти функции передают объект KosObject, который содержит структуру со сведениями о буфере DMA (об объектах KosObject см. "Использование объектов KosObject (objects.h)"). Тип структуры определен в заголовочном файле sysroot-*-kos/include/io/io_dma.h из состава KasperskyOS SDK. Функция KnIoDmaGetInfo() заполняет данными все поля структуры, а функция KnIoDmaGetPhysInfo() заполняет данными только поля count и descriptors, записывая в остальные поля нули. При использовании функции KnIoDmaGetInfo() массив descriptors содержит номера виртуальных страниц памяти, если IOMMU задействован, и номера физических страниц памяти, если IOMMU не задействован. При использовании функции KnIoDmaGetPhysInfo() массив descriptors содержит номера физических страниц памяти независимо от того, задействован IOMMU или нет.

   Функции KnIoDmaContinuousGetDmaAddr() и KnIoDmaContinuousGetPhysAddr() можно использовать, если буфер DMA состоит из одного блока. Эти функции позволяет получить адрес блока. (В качестве размера блока нужно принять размер буфера DMA, заданный при его создании.) Функция KnIoDmaContinuousGetDmaAddr() передает через выходной параметр addr виртуальный адрес, если IOMMU задействован, и физический адрес, если IOMMU не задействован. Функция KnIoDmaContinuousGetPhysAddr() передает через выходной параметр addr физический адрес независимо от того, задействован IOMMU или нет.

   На Raspberry Pi 4 B функция KnIoDmaGetPhysInfo() позволяет получить действительные номера физических страниц, а функция KnIoDmaGetInfo() позволяет получить номера физических страниц со смещением, обусловленным тем, что некоторые устройства используют при DMA трансляцию VPU (Visual Processing Unit). Аналогично функции KnIoDmaContinuousGetPhysAddr() и KnIoDmaContinuousGetDmaAddr() позволяют получить действительный и смещенный физический адрес соответственно.

API включает вспомогательные функции KnIoDmaHandlesClear() и KnIoDmaHandlesClose(). Функция KnIoDmaHandlesClear() инициализирует структуру для хранения дескрипторов, которые создаются на шаге 1, 2 и 3. Функция KnIoDmaHandlesClose() закрывает дескрипторы, сохраненные в этой структуре (вызывая функцию KnHandleClose() из API handle_api.h), и инициализирует ее. При вызове функции KnIoDmaHandlesClose() отсутствие всех или части дескрипторов в структуре не приводит к ошибке, и присутствующая часть дескрипторов будет закрыта. Функции KnIoDmaHandlesClear() и KnIoDmaHandlesClose() можно использовать следующим образом. Перед выполнением шага 1 инициализировать структуру для хранения дескрипторов вызовом функции KnIoDmaHandlesClear(). Затем при выполнении шагов 1, 2 и 3 сохранять дескрипторы в этой структуре. В дальнейшем это позволит закрыть все созданные дескрипторы одним вызовом функции KnIoDmaHandlesClose(). Например, при возникновении ошибки на одном из шагов может потребоваться закрыть все уже созданные дескрипторы, чтобы освободить выделенные ресурсы.

Закрытие доступа к буферу DMA для устройства

Закрыть доступ к буферу DMA для устройства можно, если только задействован IOMMU. Если удалить объект ядра, созданный при вызове функции KnIoDmaBegin() или KnIoDmaBeginEx(), то доступ устройства к буферу DMA будет закрыт. Чтобы удалить этот объект, нужно закрыть его дескриптор.

Удаление буфера DMA

Чтобы удалить буфер DMA, нужно выполнить следующие шаги:

1. Освободить регионы виртуальной памяти, зарезервированные при вызовах функции KnIoDmaMap().

   Чтобы выполнить этот шаг, нужно закрыть дескрипторы, которые были получены при вызовах функции KnIoDmaMap().

   Этот шаг нужно выполнить для всех процессов, на память которых отображен буфер DMA.

2. Удалить объект ядра, созданный вызовом функции KnIoDmaBegin() или KnIoDmaBeginEx().

   Чтобы выполнить этот шаг, нужно закрыть дескриптор, который был получен при вызове функции KnIoDmaBegin() или KnIoDmaBeginEx().

3. Закрыть или отозвать каждый дескриптор буфера DMA во всех процессах, которые владеют этими дескрипторами.

Для закрытия дескрипторов при выполнении этих шагов можно использовать функцию KnIoDmaHandlesClose().

Сведения о функциях API

Функции dma.h