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

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

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

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

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

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

Создание буфера 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 можно передать другому процессу через IPC.
Отображение буфера DMA на память процессов.
Один буфер DMA может быть отображен на несколько регионов виртуальной памяти одного или нескольких процессов, которые владеют дескриптором этого буфера DMA. В результате отображения процессы получают доступ к буферу DMA на чтение и/или запись.

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

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

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

Чтобы выполнить этот шаг, нужно вызвать функцию KnIoDmaGetInfo() или KnIoDmaContinuousGetDmaAddr(). Функция KnIoDmaGetInfo() позволяет получить номер страницы памяти (frame) и порядок (order) для каждого блока. (Номер страницы памяти, умноженный на размер страницы памяти, дает адрес блока. Значение 2^order представляет собой размер блока в страницах памяти.) Функцию KnIoDmaContinuousGetDmaAddr() можно использовать, если буфер DMA состоит из одного блока. Эта функция позволяет получить адрес блока. (В качестве размера блока нужно принять размер буфера DMA, заданный при его создании.)

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

Если удалить объект ядра, созданный при вызове функции KnIoDmaBegin(), то при задействовании IOMMU доступ устройства к буферу DMA будет запрещен. Чтобы удалить этот объект, нужно вызвать функцию KnHandleClose(), указав дескриптор, который был получен при вызове функции KnIoDmaBegin(). (Функция KnHandleClose() объявлена в заголовочном файле sysroot-*-kos/include/coresrv/handle/handle_api.h из состава KasperskyOS SDK.)

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

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

Освободить регионы виртуальной памяти, зарезервированные при вызовах функции KnIoDmaMap().
Чтобы выполнить этот шаг, нужно использовать функцию KnHandleClose(), указывая дескрипторы, которые были получены при вызовах функции KnIoDmaMap(). (Функция KnHandleClose() объявлена в заголовочном файле sysroot-*-kos/include/coresrv/handle/handle_api.h из состава KasperskyOS SDK.)

Этот шаг нужно выполнить для всех процессов, на память которых отображен буфер DMA.
Удалить объект ядра, созданный вызовом функции KnIoDmaBegin().
Чтобы выполнить этот шаг, нужно вызвать функцию KnHandleClose(), указав дескриптор, который был получен при вызове функции KnIoDmaBegin().
Закрыть или отозвать каждый дескриптор буфера DMA во всех процессах, которые владеют этими дескрипторами.
Чтобы выполнить этот шаг, нужно использовать функцию KnHandleClose() и/или KnHandleRevoke(), которые объявлены в заголовочном файле sysroot-*-kos/include/coresrv/handle/handle_api.h из состава KasperskyOS SDK.

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

Функции dma.h

Функция	Сведения о функции
`KnIoDmaCreate()`	Назначение Создает буфер DMA. Параметры [in] `order` – параметр, задающий минимальное число страниц памяти (2^order) в блоке. [in] `size` – размер буфера DMA в байтах. Должен быть кратен размеру страницы памяти. [in] `flags` – флаги, задающие параметры буфера DMA. Тип параметра и флаги определены в заголовочном файле `sysroot-*-kos/include/io/io_dma.h` из состава KasperskyOS SDK. [out] `outRid` – указатель на дескриптор буфера DMA. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения В параметре `flags` можно указать следующие флаги: `DMA_DIR_TO_DEVICE` – устройство имеет доступ к буферу DMA на чтение. `DMA_DIR_FROM_DEVICE` – устройство имеет доступ к буферу DMA на запись. `DMA_DIR_BIDIR` – устройство имеет доступ к буферу DMA на чтение и запись. `DMA_ZONE_DMA32` – для создания буфера DMA разрешено использовать только первые четыре гигабайта физической памяти. `DMA_ATTR_WRITE_BACK`, `DMA_ATTR_WRITE_THROUGH`, `DMA_ATTR_CACHE_DISABLE`, `DMA_ATTR_WRITE_COMBINE`, `DMA_RULE_CACHE_VOLATILE`, `DMA_RULE_CACHE_FIXED` – управление кешированием.
`KnIoDmaCreateContinuous()`	Назначение Создает буфер DMA, состоящий из одного блока. Параметры [in] `size` – размер буфера DMA в байтах. Должен быть кратен размеру страницы памяти. [in] `flags` – флаги, задающие параметры буфера DMA. Тип параметра и флаги определены в заголовочном файле `sysroot-*-kos/include/io/io_dma.h` из состава KasperskyOS SDK. [out] `outRid` – указатель на дескриптор буфера DMA. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения В параметре `flags` можно указать следующие флаги: `DMA_DIR_TO_DEVICE` – устройство имеет доступ к буферу DMA на чтение. `DMA_DIR_FROM_DEVICE` – устройство имеет доступ к буферу DMA на запись. `DMA_DIR_BIDIR` – устройство имеет доступ к буферу DMA на чтение и запись. `DMA_ZONE_DMA32` – для создания буфера DMA разрешено использовать только первые четыре гигабайта физической памяти. `DMA_ATTR_WRITE_BACK`, `DMA_ATTR_WRITE_THROUGH`, `DMA_ATTR_CACHE_DISABLE`, `DMA_ATTR_WRITE_COMBINE`, `DMA_RULE_CACHE_VOLATILE`, `DMA_RULE_CACHE_FIXED` – управление кешированием.
`KnIoDmaMap()`	Назначение Резервирует регион виртуальной памяти и отображает на него буфер DMA. Параметры [in] `rid` – дескриптор буфера DMA. [in] `offset` – смещение в буфере DMA, с которого нужно начать отображение, в байтах. Должно быть кратно размеру страницы памяти. [in] `length` – размер части буфера DMA, которую нужно отобразить, в байтах. Должен быть кратен размеру страницы памяти. Также должно выполняться условие: length<=размер буфера DMA-offset. [in,optional] `hint` – странично выравненный желаемый базовый адрес региона виртуальной памяти или `0`, чтобы этот адрес был выбран автоматически. [in] `vmflags` – флаги, задающие права доступа к региону виртуальной памяти. Флаги определены в заголовочном файле `sysroot-*-kos/include/vmm/flags.h` из состава KasperskyOS SDK. [out] `addr` – базовый адрес региона виртуальной памяти. [out] `handle` – указатель на дескриптор, который используется для освобождения региона виртуальной памяти. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения В параметре `vmflags` можно указать следующие флаги: `VMM_FLAG_READ` – доступ на чтение. `VMM_FLAG_WRITE` – доступ на запись.
`KnIoDmaModify()`	Назначение Изменяет параметры кеширования буфера DMA. Параметры [in] `rid` – дескриптор буфера DMA. [in] `newAttr` – флаги, задающие параметры кеширования буфера DMA. Флаги определены в заголовочном файле `sysroot-*-kos/include/io/io_dma.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки. Дополнительные сведения Функцию можно использовать, если выполняются следующие условия: Буфер DMA был создан с указанием флага `DMA_RULE_CACHE_VOLATILE`. Буфер DMA не отображен на виртуальную память. Предыдущий вызов функции (если он был) был выполнен с указанием флага `DMA_RULE_CACHE_VOLATILE`. В параметре `newAttr` можно указать следующие флаги: `DMA_ATTR_WRITE_BACK`, `DMA_ATTR_WRITE_THROUGH`, `DMA_ATTR_CACHE_DISABLE`, `DMA_ATTR_WRITE_COMBINE`, `DMA_RULE_CACHE_VOLATILE` – управление кешированием.
`KnIoDmaGetInfo()`	Назначение Позволяет получить сведения о буфере DMA. Сведения включают адреса и размеры блоков. Параметры [in] `rid` – дескриптор буфера DMA. [out] `outInfo` – указатель на адрес объекта, содержащего сведения о буфере DMA. Тип объекта определен в заголовочном файле `sysroot-*-kos/include/io/io_dma.h` из состава KasperskyOS SDK. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnIoDmaContinuousGetDmaAddr()`	Назначение Позволяет получить адрес блока для буфера DMA, состоящего из одного блока. Параметры [in] `rid` – дескриптор буфера DMA. [out] `addr` – адрес блока. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.
`KnIoDmaBegin()`	Назначение Открывает доступ к буферу DMA для устройства. Параметры [in] `rid` – дескриптор буфера DMA. [out] `handle` – указатель на дескриптор объекта ядра, содержащего адреса и размеры блоков, которые необходимы устройству, чтобы использовать буфер DMA. Возвращаемые значения В случае успеха возвращает `rcOk`, иначе возвращает код ошибки.

В начало