Managing I/O memory isolation (iommu_api.h)
The API is defined in the sysroot-*-kos/include/coresrv/iommu/iommu_api.h header file from the KasperskyOS SDK.
The API is intended for managing the isolation of physical memory regions used by devices on a PCIe bus for DMA. (Isolation is provided by the IOMMU.)
Information about API functions is provided in the table below.
Using the API
A device on the PCIe bus cannot use DMA unless the device is attached to the IOMMU domain. After a device is attached to the IOMMU domain, the device can access all DMA buffers that are associated with this IOMMU domain. A device can be attached to only one IOMMU domain at a time, but multiple devices can be attached to the same IOMMU domain. A DMA buffer can be associated with multiple IOMMU domains at the same time. Each IOMMU domain is associated with only one process, but multiple IOMMU domains can be associated with the same process. The capability to create multiple IOMMU domains associated with the same process allows you to restrict access to DMA buffers for different devices managed by the same process.
The API lets you create IOMMU domains, attach devices on a PCIe bus to IOMMU domains, and detach devices on the PCIe bus from IOMMU domains. A device is normally attached to an IOMMU domain when its driver is initialized. A device is usually detached from an IOMMU domain when errors are encountered during driver initialization or driver finalization.
A DMA buffer is associated with an IOMMU domain when calling the KnIoDmaBegin() and KnIoDmaBeginEx() functions that are included in the dma.h API. The KnIoDmaBegin() function associates a DMA buffer with an automatically created IOMMU domain. Each process may be associated with only one such IOMMU domain. This IOMMU domain is created after the first successful call of the KnIommuAttachDevice() function and exists throughout the entire lifetime of the process. The KnIoDmaBeginEx() function associates a DMA buffer with the IOMMU domain that was created by calling the KnIommuCreateDomain() function. Each process may be associated with multiple IOMMU domains that were created by KnIommuCreateDomain() function calls. These IOMMU domains may be removed prior to process termination by closing their handles.
To attach a device to an automatically created IOMMU domain or detach it, you must call the KnIommuAttachDevice() or KnIommuDetachDevice() function, respectively.
To attach a device to an IOMMU domain that was created by calling the KnIommuCreateDomain() function or detach it, you must call the KnIommuAttachDeviceToDomain() or KnIommuDetachDeviceFromDomain() function, respectively.
Information about API functions
iommu_api.h functions
Function |
Information about the function |
|---|---|
|
Purpose Attaches a device on a PCIe bus to the automatically created IOMMU domain associated with the calling process. Parameters
Returned values If successful, the function returns Additional information If IOMMU is not enabled, |
|
Purpose Detaches a device on a PCIe bus from the automatically created IOMMU domain associated with the calling process. Parameters
Returned values If successful, the function returns Additional information If IOMMU is not enabled, |
|
Purpose Creates an IOMMU domain associated with the calling process. Parameters
Returned values If successful, the function returns |
|
Purpose Attaches a device on a PCIe bus to the defined IOMMU domain associated with the calling process. Parameters
Returned values If successful, the function returns |
|
Purpose Detaches a device on a PCIe bus from the defined IOMMU domain associated with the calling process. Parameters
Returned values If successful, the function returns |