Взаимодействие со встроенным программным обеспечением аппаратной платформы (efi_api.h)

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

API обеспечивает возможность использовать функции встроенного программного обеспечения (англ. firmware) аппаратной платформы, доступные через интерфейс UEFI после загрузки KasperskyOS. (Об этих функциях см. раздел "Services – Runtime Services" спецификации UEFI.)

Поведение функций интерфейса UEFI на конкретной аппаратуре соответствует спецификации UEFI в той степени, в какой это определил разработчик этой аппаратуры.

Сведения о соответствии кодов возврата функций API и кодов возврата функций встроенного программного обеспечения аппаратной платформы приведены в заголовочном файле efi_api.h.

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

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

Начальным шагом является вызов функции EfiApiInit(), которая создает подключение вызывающего процесса к службе ядра, обеспечивающей взаимодействие со встроенным программным обеспечением через интерфейс UEFI.

Чтобы получить или установить текущее время, нужно вызвать функцию KnEfiGetTime() или KnEfiSetTime() соответственно.

Функции KnEfiGetTime() и KnEfiSetTime() нельзя использовать для получения и установки времени с высокой точностью, поскольку возможно вытеснение вызывающего потока исполнения.

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

Чтобы перечислить имена переменных UEFI и связанные с этими переменными уникальные идентификаторы поставщиков, нужно использовать функцию KnEfiGetNextVariableName().

Чтобы получить значение переменной UEFI, нужно вызвать функцию KnEfiGetVariable().

Чтобы создать, изменить или удалить переменную UEFI, нужно вызвать функцию KnEfiSetVariable(). Чтобы изменить атрибуты переменной UEFI, нужно удалить эту переменную и создать новую с новыми атрибутами.

Чтобы получить сведения о размерах переменных UEFI и памяти, предназначенной для хранения этих переменных, нужно использовать функцию KnEfiQueryVariableInfo().

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

Функции efi_api.h

Функция

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

KnEfiGetTime()

Назначение

Позволяет получить текущее время от источника времени на аппаратной платформе и характеристики этого источника.

Параметры

  • [out] time – указатель на структуру, содержащую сведения о времени. Тип структуры определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.
  • [out,optional] capabilities – указатель на структуру, содержащую характеристики источника времени, или RTL_NULL, если не требуется получать эти характеристики. Тип структуры определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnEfiSetTime()

Назначение

Устанавливает текущее время в источнике времени на аппаратной платформе.

Параметры

  • [in] time – указатель на структуру, содержащую сведения о времени. Тип структуры определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnEfiGetVariable()

Назначение

Позволяет получить значение переменной UEFI.

Параметры

  • [in] variableName – указатель на имя переменной. Тип символов определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK. Максимальный размер имени переменной (в символах), включая терминирующий ноль, соответствует значению константы MaxEfiStringLength, определенной в файле sysroot-*-kos/include/kl/core/Efi.idl из состава KasperskyOS SDK.
  • [in] vendorGuid – указатель на структуру, содержащую уникальный идентификатор поставщика, связанного с переменной. Тип структуры определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.
  • [out,optional] attributes – указатель на значение, биты которого интерпретируются как атрибуты переменной, или RTL_NULL, если не требуется получать атрибуты переменной. Константы атрибутов переменных определены в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.
  • [in,out] dataSize – входные данные: указатель на размер буфера, заданного через параметр data, в байтах, или указатель на нулевое целочисленное значение, чтобы определить требуемый размер этого буфера; выходные данные: указатель на размер данных, сохраненных в буфере, заданном через параметр data, в байтах, или требуемый размер этого буфера, в байтах. Максимальный размер буфера (в байтах) соответствует значению константы MaxEfiVariableSize, определенной в файле sysroot-*-kos/include/kl/core/Efi.idl из состава KasperskyOS SDK.
  • [out,optional] data – указатель на буфер со значением переменной. Можно указать RTL_NULL, если через параметр dataSize функция принимает нулевое значение.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnEfiGetNextVariableName()

Назначение

Перечисляет имена переменных UEFI.

Параметры

  • [in,out] variableNameSize – входные данные: указатель на размер буфера, заданного через параметр variableName, в байтах; выходные данные: указатель на требуемый размер буфера для имени переменной, если функция завершается с кодом rcBufferTooSmall, в байтах. Максимальный размер буфера (в байтах) соответствует удвоенному значению константы MaxEfiStringLength, определенной в файле sysroot-*-kos/include/kl/core/Efi.idl из состава KasperskyOS SDK.
  • [in,out] variableName – входные данные: указатель на буфер с именем переменной (с терминирующим нулем), полученным при предыдущем вызове функции; выходные данные: указатель буфер с именем переменной (с терминирующим нулем), полученной при текущем вызове функции. Тип символов определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK. Если функция вызывается первый раз, нужно передать буфер, заполненный нулями.
  • [in,out] vendorGuid – входные данные: указатель на структуру, содержащую уникальный идентификатор поставщика, связанного с переменной, имя которой получено при предыдущем вызове функции; выходные данные: указатель на структуру, содержащую уникальный идентификатор поставщика, связанного с переменной, имя которой получено при текущем вызове функции. Тип структуры определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK. Если через параметр variableName функция принимает буфер, заполненный нулями, то содержимое структуры, передаваемой функции через этот параметр, игнорируется.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnEfiSetVariable()

Назначение

Устанавливает значение переменной UEFI.

Параметры

  • [in] variableName – указатель на имя переменной. Тип символов определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK. Максимальный размер имени переменной (в символах), включая терминирующий ноль, соответствует значению константы MaxEfiStringLength, определенной в файле sysroot-*-kos/include/kl/core/Efi.idl из состава KasperskyOS SDK.
  • [in] vendorGuid – указатель на структуру, содержащую уникальный идентификатор поставщика, связанного с переменной. Тип структуры определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.
  • [in] attributes – значение, биты которого интерпретируются как атрибуты переменной. Константы атрибутов переменных определены в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.
  • [in] dataSize – размер данных в буфере, заданном через параметр data, в байтах, или 0, чтобы удалить переменную. Максимальный размер этих данных (в байтах) соответствует значению константы MaxEfiVariableSize, определенной в файле sysroot-*-kos/include/kl/core/Efi.idl из состава KasperskyOS SDK.
  • [in,optional] data – указатель на буфер со значением переменной. Можно указать RTL_NULL, если в параметре dataSize указан 0.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnEfiQueryVariableInfo()

Назначение

Позволяет получить сведения о переменных UEFI.

Параметры

  • [in] attributes – значение, биты которого интерпретируется как атрибуты переменных, о которых нужно получить сведения. Каждая соответствующая переменная должна иметь весь набор заданных атрибутов (за исключением игнорируемых по спецификации UEFI). Константы атрибутов переменных определены в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.
  • [out] maximumVariableStorageSize – указатель на размер памяти, которая предназначена для хранения переменных с заданными атрибутами, в байтах.
  • [out] remainingVariableStorageSize – указатель на размер неиспользованной части памяти, которая предназначена для хранения переменных с заданными атрибутами, в байтах.
  • [out] maximumVariableSize – указатель на максимальный из размеров переменных с заданными атрибутами, в байтах.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

KnEfiResetSystem()

Назначение

Перезагружает аппаратную платформу.

Параметры

  • [in] resetType – значение, задающее тип перезагрузки (например, "холодная" или "горячая" перезагрузка). Тип параметра определен в заголовочном файле sysroot-*-kos/include/efi/types.h из состава KasperskyOS SDK.
  • [in] resetStatus – код, отражающий статус перезагрузки (например, штатная перезагрузка или перезагрузка из-за сбоя). В случае штатной перезагрузки, нужно указать EFI_SUCCESS. Тип параметра и коды ошибок определены в заголовочном файле sysroot-*-kos/include/efi/errors.h из состава KasperskyOS SDK.
  • [in,optional] dataSize – размер данных в буфере, заданном через параметр resetData, в байтах, или 0, если не требуется указывать сведения о причинах перезагрузки. Максимальный размер этих данных (в байтах) соответствует значению константы MaxEfiResetDataSize, определенной в файле sysroot-*-kos/include/kl/core/Efi.idl из состава KasperskyOS SDK.
  • [in,optional] resetData – указатель на буфер со сведениями о причинах перезагрузки. Можно указать RTL_NULL, если в параметре dataSize указан 0.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

EfiApiInit()

Назначение

Создает подключение вызывающего процесса к службе ядра, обеспечивающей взаимодействие со встроенным программным обеспечением аппаратной платформы через интерфейс UEFI.

Параметры

Нет.

Возвращаемые значения

В случае успеха возвращает rcOk, иначе возвращает код ошибки.

В начало