Hardware platform firmware communication (efi

Hardware platform firmware communication (efi_api.h)

This API is defined in the header file sysroot-*-kos/include/coresrv/efi/efi_api.h from the KasperskyOS SDK.

This API provides the capability to use the hardware platform's firmware functions that are available through the UEFI interface after KasperskyOS is loaded. (For more information about these functions, see the "Services – Runtime Services" section of the UEFI specification.)

The extent to which the behavior of UEFI interface functions on specific hardware corresponds to the UEFI specification is determined by the developer of this hardware.

The header file efi_api.h provides information about how the return codes of API functions are mapped to the return codes of the hardware platform's firmware functions.

Information about API functions is provided in the table below.

Using the API

The initial step is to call the EfiApiInit() function, which creates a connection between the calling process and the core endpoint that facilitates interaction with firmware via the UEFI interface.

To get or set the current time, call the KnEfiGetTime() or KnEfiSetTime() function, respectively.

The KnEfiGetTime() and KnEfiSetTime() functions cannot be used to get and set the time with high precision because the calling thread may be evicted.

To restart the hardware platform, call the KnEfiResetSystem() function.

To enumerate the names of UEFI variables and the unique vendor IDs related to these variables, use the KnEfiGetNextVariableName() function.

To get the value of a UEFI variable, call the KnEfiGetVariable() function.

To create, edit, or delete a UEFI variable, call the KnEfiSetVariable() function. To edit attributes of a UEFI variable, you must delete this variable and create a new one with the new attributes.

To get information about the sizes of UEFI variables and the memory intended for storing these variables, use the KnEfiQueryVariableInfo() function.

Information about API functions

efi_api.h functions

Function	Information about the function
`KnEfiGetTime()`	Purpose Lets you get the current time from the time source on the hardware platform and the characteristics of this source. Parameters [out] `time` – pointer to the structure containing time information. The type of structure is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. [out,optional] `capabilities` – pointer to the structure containing time source characteristics, or `RTL_NULL` if these characteristics are not needed. The type of structure is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnEfiSetTime()`	Purpose Sets the current time in the time source on the hardware platform. Parameters [in] `time` – pointer to the structure containing time information. The type of structure is defined in the header file `sysroot-*-kos/include/efi/types.h` from the KasperskyOS SDK. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnEfiGetVariable()`	Purpose Gets the value of the UEFI variable. Parameters [in] `variableName` – pointer to the name of the variable. The type of symbols is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. The maximum size of a variable name (in symbols), including the terminating zero, corresponds to the value of the `MaxEfiStringLength` constant defined in the file `sysroot--kos/include/kl/core/Efi.idl` from the KasperskyOS SDK. [in] `vendorGuid` is a pointer to the structure containing the unique ID of the vendor related to the variable. The type of structure is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. [out,optional] `attributes` – pointer to the value whose bits are interpreted as the attributes of the variable, or `RTL_NULL` if the variable attributes are not needed. The constants of variable attributes are defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. [in,out] `dataSize` – input data: pointer to the buffer size defined via the `data` parameter (in bytes), or the pointer to the null integer value to determine the required size of this buffer; output data: pointer to the size of the data stored in the buffer as defined via the `data` parameter (in bytes), or the required size of this buffer (in bytes). The maximum data size (in bytes) corresponds to the value of the `MaxEfiVariableSize` constant defined in the `sysroot-*-kos/include/kl/core/Efi.idl` file from the KasperskyOS SDK. [out,optional] `data` – pointer to the buffer containing the variable value. You can specify `RTL_NULL` if the function accepts a null value via the `dataSize` parameter. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnEfiGetNextVariableName()`	Purpose Enumerates the names of the UEFI variables. Parameters [in,out] `variableNameSize` – input data: pointer to the buffer size defined via the `variableName` parameter (in bytes); output data: pointer to the required buffer size for the variable name if the function terminates with the `rcBufferTooSmall` code (in bytes). The maximum buffer size (in bytes) corresponds to the doubled value of the `MaxEfiStringLength` constant defined in the `sysroot--kos/include/kl/core/Efi.idl` file from the KasperskyOS SDK. [in,out] `variableName` – input data: pointer to the buffer containing the variable name (with a terminating zero) received during the previous call of the function; output data: pointer to the buffer containing the variable name (with a terminating zero) received during the current call of the function. The type of symbols is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. If the function is being called for the first time, you must pass a buffer filled with zeros. [in,out] `vendorGuid` – input data: pointer to the structure containing the unique ID of the vendor that is related to the variable and whose name was received during the previous call of the function; output data: pointer to the structure containing the unique ID of the vendor that is related to the variable and whose name was received during the current call of the function. The type of structure is defined in the header file `sysroot-*-kos/include/efi/types.h` from the KasperskyOS SDK. If the function uses the `variableName` parameter to accept a buffer filled with zeros, the contents of the structure passed to the function via this parameter is ignored. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnEfiSetVariable()`	Purpose Specifies the value of the UEFI variable. Parameters [in] `variableName` – pointer to the name of the variable. The type of symbols is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. The maximum size of a variable name (in symbols), including the terminating zero, corresponds to the value of the `MaxEfiStringLength` constant defined in the file `sysroot--kos/include/kl/core/Efi.idl` from the KasperskyOS SDK. [in] `vendorGuid` is a pointer to the structure containing the unique ID of the vendor related to the variable. The type of structure is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. [in] `attributes` – value whose bits are interpreted as attributes of the variable. The constants of variable attributes are defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. [in] `dataSize` – size of data in the buffer as defined via the `data` parameter (in bytes), or `0` to delete the variable. The maximum size of this data (in bytes) corresponds to the value of the `MaxEfiVariableSize` constant defined in the `sysroot-*-kos/include/kl/core/Efi.idl` file from the KasperskyOS SDK. [in,optional] `data` – pointer to the buffer containing the variable value. You can specify `RTL_NULL` if the `dataSize` parameter is set to `0`. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnEfiQueryVariableInfo()`	Purpose Gets information about UEFI variables. Parameters [in] `attributes` – value whose bits are interpreted as attributes of the variables whose information you need to get. Each corresponding variable must have the entire set of defined attributes (excluding those that are ignored by the UEFI specification). The constants of variable attributes are defined in the header file `sysroot-*-kos/include/efi/types.h` from the KasperskyOS SDK. [out] `maximumVariableStorageSize` is a pointer to the size (in bytes) of memory that is intended for storing variables with specific attributes. [out] `remainingVariableStorageSize` is a pointer to the size (in bytes) of the unused portion of memory that is intended for storing variables with specific attributes. [out] `maximumVariableSize` – pointer to the maximum size among all the sizes of variables with the defined attributes (in bytes). Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnEfiResetSystem()`	Purpose Restarts the hardware platform. Parameters [in] `resetType` – value that defines the restart type, such as cold or hot restart. The parameter type is defined in the header file `sysroot--kos/include/efi/types.h` from the KasperskyOS SDK. [in] `resetStatus` – code that indicates the restart status, such as normal restart or restart due to malfunction. If it is a normal restart, `EFI_SUCCESS` must be specified. The parameter type and error codes are defined in the header file `sysroot--kos/include/efi/errors.h` from the KasperskyOS SDK. [in,optional] `dataSize` – size of data in the buffer as defined via the `resetData` parameter (in bytes), or `0` if you do not need to specify any information about the causes of the restart. The maximum size of this data (in bytes) corresponds to the value of the `MaxEfiResetDataSize` constant defined in the `sysroot-*-kos/include/kl/core/Efi.idl` file from the KasperskyOS SDK. [in,optional] `resetData` – pointer to the buffer containing information about the causes of the restart. You can specify `RTL_NULL` if the `dataSize` parameter is set to `0`. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`EfiApiInit()`	Purpose Creates a connection between the calling process and the core endpoint that facilitates interaction with the hardware platform's firmware via the UEFI interface. Parameters N/A Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Page top