Использование слоя аппаратных абстракций (hal_api.h...

Использование слоя аппаратных абстракций (hal_api.h, hal_common.h, hal_env.h, hal_privregs.h)

12 января 2026

ID libkos_hal_api

API определены в заголовочных файлах sysroot-*-kos/include/coresrv/hal/hal_*.h из состава KasperskyOS SDK. Заголовочный файл hal_api.h содержит директивы включения остальных заголовочных файлов hal_*.h.

Основные возможности API:

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

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

Очистка кеша процессора

Чтобы очистить кеш процессора, нужно вызвать функцию KnHalFlushCache(), объявленную в заголовочном файле hal_api.h. Функция очищает кеш процессора всех доступных уровней. При этом можно очистить кеш данных и кеш инструкций, соответствующие заданному региону виртуальной памяти. К примеру, драйверу требуется очищать кеш данных процессора, который соответствует памяти, используемой для DMA, поскольку в результате кеширования содержимое этой памяти с позиции драйвера может отличаться от действительного содержимого, видимого устройству.

Также для очистки кеша процессора можно использовать функцию KosCpuCacheFlush() из API cpucache.h. В отличие от функции KnHalFlushCache(), которая всегда выполняет системный вызов для очистки кеша процессора, функция KosCpuCacheFlush() делает так только в том случае, если нет возможности выполнить очистку без этого системного вызова.

Аппаратная генерация случайных чисел

Чтобы получить случайные числа, сгенерированные аппаратно, нужно вызвать функцию KnHalGetEntropy(), объявленную в заголовочном файле hal_api.h.

Перезагрузка аппаратной платформы

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

Диагностический вывод программ

Чтобы поместить данные в диагностический вывод, нужно вызвать функцию KnHalDebugWrite(), объявленную в заголовочном файле hal_common.h. Эти данные будут выведены, например, через порт COM или USB (версии 3.0 или более поздней, с поддержкой DbC) в зависимости от конфигурации ядра.

Получение значений параметров аппаратной платформы

Чтобы получить значение параметра аппаратной платформы, нужно вызвать функцию KnHalGetEnv() или KnHalGetEnvMemRegion(), объявленные в заголовочном файле hal_env.h. Значения параметров аппаратной платформы содержат такие данные, как сведения о плате, архитектуре и частоте процессора, SMBIOS (System Management BIOS), FDT (Flattened Device Tree). Символьные константы с именами параметров определены в заголовочном файле sysroot-*-kos/include/hal/env_names.h из состава KasperskyOS SDK. Функцию KnHalGetEnvMemRegion() можно использовать только для получения сведений о SMBIOS и FDT (значения параметров с именами HAL_ENV_SMBIOS и HAL_ENV_GET_FDT_INFO соответственно).

Получение числа процессоров (вычислительных ядер) на аппаратной платформе

Чтобы получить число процессоров на аппаратной платформе, нужно вызвать функцию KnHalGetCpuCount(), объявленную в заголовочном файле hal_env.h.

Получение и установка значений привилегированных регистров периферийных устройств

Чтобы получить или задать значение привилегированного регистра периферийного устройства, нужно использовать функции, объявленные в заголовочном файле hal_privregs.h.

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

Чтобы задать значение регистра, нужно вызвать функцию KnHalSetPrivReg() или KnHalSetPrivRegRange().

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

Функции hal_api.h

Функция

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

KnHalFlushCache()

Назначение

Очищает кеш процессора.

Параметры

[in] type – значение, задающее тип кеша (кеш данных, кеш инструкций, кеш данных и кеш инструкций совместно). Тип параметра определен в заголовочном файле sysroot-*-kos/include/rtl/cpucache.h из состава KasperskyOS SDK.
[in] va – указатель на регион виртуальной памяти. Кеш, соответствующий этому региону, будет очищен.
[in] size – размер региона виртуальной памяти в байтах. Кеш, соответствующий этому региону, будет очищен.

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

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

KnHalGetEntropy()

Назначение

Позволяет получить случайные числа, сгенерированные аппаратно.

Параметры

[out] buffer – указатель на буфер для сохранения случайных байтовых значений.
[in] size – число случайных байтовых значений.

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

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

Функции hal_common.h

Функция

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

KnHalResetSystem()

Назначение

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

Параметры

Нет.

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

Если функция не реализована, возвращает rcUnimplemented.

KnHalDebugWrite()

Назначение

Помещает данные в диагностический вывод, который записывается, например, в порт COM или USB (версии 3.0 или более поздней, с поддержкой DbC).

Параметры

[in] buf – указатель на данные для помещения в диагностический вывод.
[in] size – размер данных для помещения в диагностический вывод, в байтах.

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

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

Функции hal_env.h

Функция

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

KnHalGetEnv()

Назначение

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

Параметры

[in] name – указатель на имя параметра.
[out] value – указатель на буфер для сохранения значения параметра.
[in] size – размер буфера, заданного через параметр value, в байтах.

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

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

Если размер буфера, заданного через параметр value, недостаточен, возвращает rcBufferTooSmall.

KnHalGetEnvMemRegion()

Назначение

Позволяет считать значение параметра аппаратной платформы вида 0x<базовый физический адрес региона памяти> 0x<размер региона памяти>\0 и получить из этого значения базовый физический адрес и размер региона памяти.

Параметры

[in] name – указатель на имя параметра.
[out] addr – указатель на базовый физический адрес региона памяти.
[out] size – указатель на размер региона памяти в байтах.

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

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

KnHalGetCpuCount()

Назначение

Позволяет получить число процессоров (вычислительных ядер) на аппаратной платформе.

Параметры

[out] count – указатель на число процессоров.

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

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

Функции hal_privregs.h

Функция

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

KnHalGetPrivReg()

Назначение

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

Параметры

[in] reg – указатель на имя регистра.
[out] val – указатель на значение регистра.

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

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

KnHalSetPrivReg()

Назначение

Задает значение привилегированного регистра периферийного устройства.

Параметры

[in] reg – указатель на имя регистра.
[in] val – значение регистра.

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

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

KnHalGetPrivRegRange()

Назначение

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

Параметры

[in] regRange – указатель на имя диапазона регистров.
[in] offset – смещение регистра в диапазоне регистров.
[out] val – указатель на значение регистра.

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

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

Если строка, заданная через параметр regRange, имеет длину больше допустимой, возвращает rcBufferTooLarge.

Если произошла ошибка IPC, возвращает rcFail.

Если имя диапазона регистров некорректно, или смещение регистра вне допустимого диапазона, возвращает rcInvalidArgument.

Если поток исполнения, в котором вызвана функция, привязан к прерыванию, возвращает rcInvalidThreadState. (О привязке потока исполнения к прерыванию см. "Управление обработкой прерываний (irq.h)".)

KnHalSetPrivRegRange()

Назначение

Задает значение привилегированного регистра периферийного устройства.

Параметры

[in] regRange – указатель на имя диапазона регистров.
[in] offset – смещение регистра в диапазоне регистров.
[in] val – значение регистра.

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

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

Если строка, заданная через параметр regRange, имеет длину больше допустимой, возвращает rcBufferTooLarge.

Если произошла ошибка IPC, возвращает rcFail.

Вам помогла эта статья?

Что нам нужно улучшить?

Спасибо за ваш отзыв, вы помогаете нам становиться лучше!