Using the hardware abstraction layer (hal_api.h, hal_common.h, hal_env.h, hal

Using the hardware abstraction layer (hal_api.h, hal_common.h, hal_env.h, hal_privregs.h)

APIs are defined in the header files sysroot-*-kos/include/coresrv/hal/_*.h from the KasperskyOS SDK. The hal_api.h header file contains directives for including the rest of the hal_*.h header files.

Main capabilities of the API:

Flush the processor cache.
Get hardware-generated random numbers.
Restart the hardware platform.
Perform diagnostic output of programs.
Get the values of hardware platform parameters.
Get the number of processors (computing cores) on the hardware platform.
Get and set the values of privileged registers of peripheral devices.

Information about API functions is provided in the tables below.

Flushing the processor cache

To clear the processor cache, call the KnHalFlushCache() function that is declared in the hal_api.h header file. This function flushes the processor cache of all accessible levels. You can also clear the data cache and instructions cache corresponding to the defined virtual memory region. For example, a driver must clear the processor data cache corresponding to the memory used for DMA because the caching process may cause the contents of this memory from the driver's perspective to differ from the actual contents visible to the device.

You can also flush the processor cache by using the KosCpuCacheFlush() function from the cpucache.h API. In contrast to the KnHalFlushCache() function, which always executes a system call to flush the processor cache, the KosCpuCacheFlush() function does this only if there is no capability to flush the processor cache without this system call.

Hardware-generated random numbers

To get hardware-generated random numbers, call the KnHalGetEntropy() function that is declared in the hal_api.h header file.

Restarting the hardware platform

To restart the hardware platform, call the KnHalResetSystem() function that is declared in the hal_common.h header file.

Diagnostic output of programs

To put data into diagnostic output, call the KnHalDebugWrite() function that is declared in the hal_common.h header file. For example, this data will be output via the COM or USB port (version 3.0 or later, with DbC support) depending on the kernel configuration.

Getting the values of hardware platform parameters

To get the value of a hardware platform parameter, call the function KnHalGetEnv() or KnHalGetEnvMemRegion() defined in the header file hal_env.h. The values of hardware platform parameters contain data, such as information about the motherboard, architecture, CPU frequency, SMBIOS (System Management BIOS), and FDT (Flattened Device Tree). Symbolic constants containing the names of parameters are defined in the header file sysroot-*-kos/include/hal/env_names.h from the KasperskyOS SDK. The KnHalGetEnvMemRegion() function can be used only to get information about the SMBIOS and FDT (the values of parameters named HAL_ENV_SMBIOS and HAL_ENV_GET_FDT_INFO, respectively).

Getting the number of processors (computing cores) on the hardware platform

To get the number of processors on the hardware platform, call the KnHalGetCpuCount() function that is declared in the hal_env.h header file.

Getting and setting the values of privileged registers of peripheral devices

To get or set the value of the privileged register of a peripheral device, use the functions declared in the hal_privregs.h header file.

To get the value of a register, call the KnHalGetPrivReg() or KnHalGetPrivRegRange() function.

To define a register value, call the KnHalSetPrivReg() or KnHalSetPrivRegRange() function.

Information about API functions

hal_api.h functions

Function	Information about the function
`KnHalFlushCache()`	Purpose Flushes the processor cache. Parameters [in] `type` – value defining the cache type (data cache, instructions cache, or joint data and instructions cache). The parameter type is defined in the header file `sysroot-*-kos/include/rtl/cpucache.h` from the KasperskyOS SDK. [in] `va` – pointer to the virtual memory region. The cache corresponding to this region will be flushed. [in] `size` – size (in bytes) of the virtual memory region. The cache corresponding to this region will be flushed. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnHalGetEntropy()`	Purpose Gets hardware-generated random numbers. Parameters [out] `buffer` – pointer to the buffer used to save the random byte values. [in] `size` – number of random byte values. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Function

Information about the function

KnHalFlushCache()

Purpose

Flushes the processor cache.

Parameters

[in] type – value defining the cache type (data cache, instructions cache, or joint data and instructions cache). The parameter type is defined in the header file sysroot-*-kos/include/rtl/cpucache.h from the KasperskyOS SDK.
[in] va – pointer to the virtual memory region. The cache corresponding to this region will be flushed.
[in] size – size (in bytes) of the virtual memory region. The cache corresponding to this region will be flushed.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

KnHalGetEntropy()

Purpose

Gets hardware-generated random numbers.

Parameters

[out] buffer – pointer to the buffer used to save the random byte values.
[in] size – number of random byte values.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

hal_common.h functions

Function	Information about the function
`KnHalResetSystem()`	Purpose Restarts the hardware platform. Parameters N/A Returned values If the function has not been implemented, `rcUnimplemented` is returned.
`KnHalDebugWrite()`	Purpose Puts data into the diagnostic output that is written, for example, to a COM port or USB port (version 3.0 or later, with DbC support). Parameters [in] `buf` – pointer to the data to be put into the diagnostic output. [in] `size` – size of the data to be put into the diagnostic output (in bytes). Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Function

Information about the function

KnHalResetSystem()

Purpose

Restarts the hardware platform.

Parameters

N/A

Returned values

If the function has not been implemented, rcUnimplemented is returned.

KnHalDebugWrite()

Purpose

Puts data into the diagnostic output that is written, for example, to a COM port or USB port (version 3.0 or later, with DbC support).

Parameters

[in] buf – pointer to the data to be put into the diagnostic output.
[in] size – size of the data to be put into the diagnostic output (in bytes).

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

hal_env.h functions

Function	Information about the function
`KnHalGetEnv()`	Purpose Gets the value of a hardware platform parameter. Parameters [in] `name` – pointer to the parameter name. [out] `value` – pointer to the buffer used to save the parameter value. [in] `size` – size of the buffer defined via the `value` parameter (in bytes). Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the size of the buffer defined via the `value` parameter is insufficient, the function returns `rcBufferTooSmall`.
`KnHalGetEnvMemRegion()`	Purpose Gets the value of a hardware platform parameter in the format `0x`<`base physical address of memory region`> `0x`<`memory region size`>`\0` and gets the base physical address and size of the memory region from this value. Parameters [in] `name` – pointer to the parameter name. [out] `addr` – pointer to the base physical address of the memory region. [out] `size` – pointer to the size of the memory region (in bytes). Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnHalGetCpuCount()`	Purpose Gets the number of processors (computing cores) on the hardware platform. Parameters [out] `count` – pointer to the number of processors. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.

Function

Information about the function

KnHalGetEnv()

Purpose

Gets the value of a hardware platform parameter.

Parameters

[in] name – pointer to the parameter name.
[out] value – pointer to the buffer used to save the parameter value.
[in] size – size of the buffer defined via the value parameter (in bytes).

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

If the size of the buffer defined via the value parameter is insufficient, the function returns rcBufferTooSmall.

KnHalGetEnvMemRegion()

Purpose

Gets the value of a hardware platform parameter in the format 0x<base physical address of memory region> 0x<memory region size>\0 and gets the base physical address and size of the memory region from this value.

Parameters

[in] name – pointer to the parameter name.
[out] addr – pointer to the base physical address of the memory region.
[out] size – pointer to the size of the memory region (in bytes).

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

KnHalGetCpuCount()

Purpose

Gets the number of processors (computing cores) on the hardware platform.

Parameters

[out] count – pointer to the number of processors.

Returned values

If successful, the function returns rcOk, otherwise it returns an error code.

hal_privregs.h functions

Function	Information about the function
`KnHalGetPrivReg()`	Purpose Gets the value of a peripheral device privileged register. Parameters [in] `reg` – pointer to the register name. [out] `val` – pointer to the register value. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnHalSetPrivReg()`	Purpose Sets the value of a peripheral device privileged register. Parameters [in] `reg` – pointer to the register name. [in] `val` – value of the register. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code.
`KnHalGetPrivRegRange()`	Purpose Gets the value of a peripheral device privileged register. Parameters [in] `regRange` – pointer to the name of the registers range. [in] `offset` – register offset in the registers range. [out] `val` – pointer to the register value. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the string defined via the `regRange` parameter has a length greater than the permitted length, the function returns `rcBufferTooLarge`. If an IPC error occurred, the function returns `rcFail`. If the name of the registers range is incorrect or if the register offset is outside of the permissible range, the function returns `rcInvalidArgument`. If the thread in which the function is called is attached to an interrupt, the function returns `rcInvalidThreadState`. (For details about attaching a thread to an interrupt, see Managing interrupt processing (irq.h).)
`KnHalSetPrivRegRange()`	Purpose Sets the value of a peripheral device privileged register. Parameters [in] `regRange` – pointer to the name of the registers range. [in] `offset` – register offset in the registers range. [in] `val` – value of the register. Returned values If successful, the function returns `rcOk`, otherwise it returns an error code. If the string defined via the `regRange` parameter has a length greater than the permitted length, the function returns `rcBufferTooLarge`. If an IPC error occurred, the function returns `rcFail`. If the name of the registers range is incorrect or if the register offset is outside of the permissible range, the function returns `rcInvalidArgument`. If the thread in which the function is called is attached to an interrupt, the function returns `rcInvalidThreadState`. (For details about attaching a thread to an interrupt, see Managing interrupt processing (irq.h).)

Page top