Obtaining statistical data on the system through the libkos library API

The libkos library provides an API that obtains statistical data on CPU time and memory usage, and info on processes and threads. This API is defined in the header file sysroot-*-kos/include/coresrv/stat/stat_api.h from the KasperskyOS SDK.

The API includes KnGroupStatGetParam(), KnCpuStatGetParam(), KnTaskStatGetParam() functions that request the values of performance counters. To use these functions, you need to build a solution with a KasperskyOS kernel version that supports the full set of performance counters (for details, see image library). An exception to this rule includes calls of the KnGroupStatGetParam() function with the GROUP_PARAM_MEM_FREE and GROUP_PARAM_MEM_TOTAL values in the param parameter (see the table containing information about memory usage below) that can be successfully executed without a special kernel version.

Receiving information about CPU time

Uptime of CPUs (processor cores) is counted from the startup of the KasperskyOS kernel.

To obtain information about CPU time usage, use the KnGroupStatGetParam(), KnTaskStatGetParam() and KnCpuStatGetParam() functions. The values provided in the table below need to be passed in the param parameter of these functions. The CPU time obtained by calling the KnGroupStatGetParam(), KnTaskStatGetParam() or KnCpuStatGetParam() function is presented in nanoseconds. The CPU index (enumeration starts with zero) is the input parameter of the KnCpuStatGetParam() function. To get the total number of processors (computing cores) on the hardware platform, call the KnHalGetCpuCount() function from the hal_env.h API.

Information about CPU time

Function	Value of the `param` parameter	Obtained value
`KnGroupStatGetParam()`	`GROUP_PARAM_CPU_KERNEL`	Total uptime of all processors in kernel mode
`KnGroupStatGetParam()`	`GROUP_PARAM_CPU_USER`	Total uptime of all processors in user mode
`KnGroupStatGetParam()`	`GROUP_PARAM_CPU_IDLE`	Total uptime of all processors in idle mode
`KnTaskStatGetParam()`	`TASK_PARAM_TIME_TOTAL`	Total uptime of all processors used for execution of the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_TIME_USER`	Total uptime of all processors used for execution of the defined process in user mode
`KnCpuStatGetParam()`	`CPU_STAT_PARAM_IDLE`	Uptime of the defined processor in idle mode
`KnCpuStatGetParam()`	`CPU_STAT_PARAM_USER`	Uptime of the defined processor in user mode
`KnCpuStatGetParam()`	`CPU_STAT_PARAM_KERNEL`	Uptime of the defined processor in kernel mode

Receiving information about memory usage

To receive information about memory usage, you need to use the KnGroupStatGetParam() and KnTaskStatGetParam() functions. The values provided in the table below need to be passed in the param parameter of these functions. The memory size obtained by calling the KnGroupStatGetParam() or KnTaskStatGetParam() function is presented as the number of memory pages. The size of a memory page is 4 KB for all hardware platforms supported by KasperskyOS.

The size of physical memory used by a process refers only to the memory allocated directly for this process. For example, if the memory of a process is mapped to an MDL buffer created by another process, the size of this buffer is not included in this value.

Information about memory usage

Function	Value of the `param` parameter	Obtained value
`KnGroupStatGetParam()`	`GROUP_PARAM_MEM_TOTAL`	Size of all installed physical memory
`KnGroupStatGetParam()`	`GROUP_PARAM_MEM_FREE`	Size of free physical memory
`KnGroupStatGetParam()`	`GROUP_PARAM_MEM_EXEC`	Size of physical memory with the "execution access" attribute
`KnGroupStatGetParam()`	`GROUP_PARAM_MEM_SHARED`	Size of physical memory used as shared memory
`KnTaskStatGetParam()`	`TASK_PARAM_MEM_PHY`	Size of physical memory used by the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_MEM_VIRT`	Size of virtual memory of the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_MEM_SHARED`	Size of virtual memory of the defined process mapped to shared physical memory
`KnTaskStatGetParam()`	`TASK_PARAM_MEM_PAGE_TABLE`	Size of the page table of the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_VMM_FRAG_INDEX`	Average size of free virtual memory regions of the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_VMM_MAX_CONTIGIOUS_SPACE`	Maximum size of free virtual memory regions of the defined process

Obtaining information on processes and threads

In addition to information about CPU time and memory usage, the KnGroupStatGetParam() and KnTaskStatGetParam() functions also let you obtain information on processes and threads. To receive this information, the values provided in the table below need to be passed through the param parameter of these functions.

Information on processes and threads

Function	Value of the `param` parameter	Obtained value
`KnGroupStatGetParam()`	`GROUP_PARAM_TASKS`	Number of processes (excluding the kernel process)
`KnGroupStatGetParam()`	`GROUP_PARAM_THREADS`	Number of threads (including kernel threads)
`KnTaskStatGetParam()`	`TASK_PARAM_PPID`	ID of the parent process of the defined process (PPID)
`KnTaskStatGetParam()`	`TASK_PARAM_PRIO`	Priority of the initial thread of the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_STATE`	State of the defined process (according to the list of `TaskExecutionStates` defined in the header file `sysroot-*-kos/include/task/pcbpage.h` from the KasperskyOS SDK)
`KnTaskStatGetParam()`	`TASK_PARAM_IMGSIZE`	Image size of the program loaded into the memory of the defined process (in bytes)
`KnTaskStatGetParam()`	`TASK_PARAM_TIME_START`	Time (in nanoseconds) between startup of the kernel and startup of the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_HANDLES`	Number of handles owned by the defined process
`KnTaskStatGetParam()`	`TASK_PARAM_THREADS`	Number of threads in the defined process

In addition to the KnGroupStatGetParam() and KnTaskStatGetParam() functions, information on processes and threads can also be obtained by using the following functions:

KnTaskStatGetName() – gets the name of the defined process.
KnTaskStatGetPath() – gets the name of the executable file in ROMFS that was used to start the defined process.
This function can be used only if the process was started from an executable file in ROMFS. Otherwise, the function call will result in an empty string.
KnTaskStatGetId() – gets the ID of the defined process (PID).
KnTaskGetIdByName() gets the ID of the process (PID) with the defined name.

Obtaining information on CPU time and memory usage by each process

To get information about CPU time and memory usage by each process, do the following:

Get the list of processes by calling the KnGroupStatGetTaskList() function.
Get the number of items on the list of processes by calling the KnTaskStatGetTasksCount() function.
Iterate through the list of processes, repeating the following steps:
1. Get an item from the list of processes by calling the KnTaskStatEnumTaskList() function.
2. Get the process name by calling the KnTaskStatGetName() function.
  This is necessary to identify the process for which the information about CPU time and memory usage will be received.
3. Get information about CPU time and memory usage by calling the KnTaskStatGetParam() function.
4. Verify that the process was not terminated. If the process has terminated, discard the obtained information about the CPU time and memory used by this process.
  To verify that the process was not terminated, you need to call the KnTaskStatGetParam() function, using the param parameter to pass the TASK_PARAM_STATE value. A value other than TaskStateTerminated should be received.
5. Finish working with the item on the list of processes by calling the KnTaskStatCloseTask() function.
Finish working with the list of processes by calling the KnTaskStatCloseTaskList() function.

Calculating CPU load

Indicators of load on CPUs (processor cores) may be the following values:

Percent load of all processors
Percent load of all processors by each process
Percent load of each processor

These indicators are calculated for a specific time interval, at the start and end of which the information about CPU time utilization was received. (For example, CPU load can be monitored with periodic receipt of information about CPU time utilization.) The values obtained at the start of the interval need to be subtracted from the values obtained at the end of the interval. In other words, the following increments need to be obtained for the interval:

TK – uptime of all processors in kernel mode.
TKi [i=1,2,...,n] – uptime of the ith processor in kernel mode.
TU – uptime of all processors in user mode.
TUi [i=1,2,...,n] – uptime of the ith processor in user mode.
TIDLE – uptime of all processors in idle mode.
TIDLEi [i=1,2,...,n] – uptime of the ith processor in idle mode.
Tj [j=1,2,...,m] – CPU time spent on execution of the jth process.

The percent load of all processors is calculated as follows:

(TK+TU)/(TK+TU+TIDLE).

The percent load of the ith processor is calculated as follows:

(TKi+TUi)/(TKi+TUi+TIDLEi).

The percent load of all processors caused by the jth process is calculated as follows:

Tj/(TK+TU+TIDLE).

Page top