Information about API functions is provided in the table below.
Using the API
An MDL buffer is used to create shared memory. An MDL buffer consists of one or more physical memory regions that can be mapped to the memory of multiple processes at the same time. A kernel object known as a memory descriptor list is used to map the MDL buffer to process memory. A memory descriptor list (MDL) is a data structure containing the addresses and sizes of physical memory regions comprising the MDL buffer. The MDL buffer handle identifies the memory descriptor list.
To create shared memory, a process needs to create an MDL buffer, map it to its own memory, and pass the MDL buffer handle via IPC to other processes that also need to map this MDL buffer to their own memory.
To create an MDL buffer, call the KnPmmMdlCreate(), KnPmmMdlCreateFromBuf() or KnPmmMdlCreateFromVm() function. The KnPmmMdlCreateFromBuf() function creates an MDL buffer and copies data to it. The KnPmmMdlCreateFromVm() function creates an MDL buffer and maps it to the memory of the calling process.
To reserve a virtual memory region and map the MDL buffer to it, call the KnPmmMdlMap() function. An MDL buffer can be mapped to multiple virtual memory regions of the same process.
An MDL buffer can be used to transfer large volumes of data between processes without creating shared memory. In this case, you must make sure that the MDL buffer is not mapped to the memory of multiple processes at the same time. Interacting processes must take turns mapping the MDL buffer to their own memory, reading and/or writing data and then freeing the virtual memory region that is mapped to this MDL buffer.
The Kaspersky Security Module cannot control data that is transferred between processes via the MDL buffer.
Deleting an MDL buffer
To delete an MDL buffer, complete the following steps:
Free the virtual memory regions mapped to the MDL buffer in all processes that are using this MDL buffer.
To complete this step, use the KnVmUnmap() function.
Close or revoke each MDL buffer handle in all processes that own these handles.
To complete this step, use the KnHandleClose() and/or KnHandleRevoke() functions that are declared in the header file sysroot-*-kos/include/coresrv/handle/handle_api.h from the KasperskyOS SDK.
Information about API functions
vmm_api.h functions
Function
Information about the function
KnPmmMdlCreate()
Purpose
Creates an MDL buffer.
Parameters
[in] size – size of the MDL buffer in bytes. It must be a multiple of the memory page size.
[in] flags – flags defining the access rights to the MDL buffer. The parameter type and flags are defined in the header file sysroot-*-kos/include/vmm/flags.h from the KasperskyOS SDK.
[out] outHandle – pointer to the MDL buffer handle.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Additional information
In the flags parameter, you can specify the following combinations of flags:
VMM_FLAG_RWX_MASK or VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE – read/write/execute access.
KnPmmMdlCreateFromVm()
Purpose
Creates an MDL buffer from physical memory that is mapped to the defined virtual memory region and maps the created MDL buffer to this region.
Parameters
[in] addr – page-aligned base address of the virtual memory region.
[in] size – size of the virtual memory region in bytes. It must be a multiple of the memory page size.
[in] flags – flags defining the access rights to the MDL buffer. The parameter type and flags are defined in the header file sysroot-*-kos/include/vmm/flags.h from the KasperskyOS SDK.
[out] outHandle – pointer to the MDL buffer handle.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Additional information
This function can be used if the defined virtual memory region is allocated with commitment.
In the flags parameter, you can specify the following combinations of flags:
VMM_FLAG_RWX_MASK or VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE – read/write/execute access.
KnPmmMdlCreateFromBuf()
Purpose
Creates an MDL buffer and copies data from the defined buffer to the MDL buffer.
Parameters
[in] offset – offset (in bytes) in the MDL buffer where the data write operation must start.
[in] size – size of the MDL buffer in bytes. It must be a multiple of the memory page size. The following condition must also be fulfilled: size>=bufSize+offset.
[in] flags – flags defining the access rights to the MDL buffer. The parameter type and flags are defined in the header file sysroot-*-kos/include/vmm/flags.h from the KasperskyOS SDK.
[in] buf – pointer to the buffer containing the data.
[in] bufSize – size (in bytes) of the buffer containing the data.
[out] outHandle – pointer to the MDL buffer handle.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Additional information
In the flags parameter, you can specify the following combinations of flags:
VMM_FLAG_RWX_MASK or VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE – read/write/execute access.
KnPmmMdlGetSize()
Purpose
Gets the size of the MDL buffer.
Parameters
[in] handle – MDL buffer handle.
[out] size – size (in bytes) of the MDL buffer.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
KnPmmMdlMap()
Purpose
Reserves a virtual memory region and maps the MDL buffer to it.
Parameters
[in] handle – MDL buffer handle.
[in] offset – offset (in bytes) in the MDL buffer where mapping should start. It must be a multiple of the memory page size.
[in] length – size (in bytes) of the part of the MDL buffer that needs to be mapped. It must be a multiple of the memory page size. The following condition must also be fulfilled: length<=size of MDL buffer-offset.
[in,optional] hint – page-aligned, preferred base address of the virtual memory region, or 0 to select this address automatically.
[in] prots – flags defining the parameters of the virtual memory region. The flags are defined in the header file sysroot-*-kos/include/vmm/flags.h from the KasperskyOS SDK.
[out] addr – pointer to the base address of the virtual memory region.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Additional information
In the prots parameter, you can specify the following flags:
VMM_FLAG_READ, VMM_FLAG_WRITE, VMM_FLAG_EXECUTE andVMM_FLAG_RWX_MASK – flags defining the access rights to the virtual memory region.
VMM_FLAG_LOW_GUARD, VMM_FLAG_HIGH_GUARD – adds a protected page to the beginning and end of the virtual memory region, respectively.
Permissible combinations of flags defining the access rights to the virtual memory region:
VMM_FLAG_RWX_MASK or VMM_FLAG_READ | VMM_FLAG_WRITE | VMM_FLAG_EXECUTE – read/write/execute access.
KnPmmMdlClone()
Purpose
Creates an MDL buffer based on an existing one.
The MDL buffer is created from the same regions of physical memory as the original buffer.
Parameters
[in] origin – handle of the original MDL buffer.
[in] offset – offset (in bytes) in the original MDL buffer where duplication should start. It must be a multiple of the memory page size.
[in] length – size (in bytes) of the part of the original MDL buffer that needs to be duplicated. It must be a multiple of the memory page size. The following condition must also be fulfilled: length<=size of original MDL buffer-offset.
[out] clone – pointer to the handle of the created MDL buffer.
Returned values
If successful, the function returns rcOk, otherwise it returns an error code.
Article ID: libkos_vmm_api_mdl, Last review: Feb 20, 2025