KasperskyOS Community Edition 1.3

Managing processes (high-level API task.h)

The API is defined in the header file sysroot-*-kos/include/kos/task.h from the KasperskyOS SDK.

The API lets you create, start and terminate processes, and statically create IPC channels and pass handles.

Information about API functions is provided in the table below.

Creating processes

To create a process, call one of the following functions:

• KosTaskInitEx()
• KosTaskInit()
• KosTaskInitFromSegEx()
• KosTaskInitFromSeg()
• KosTaskLaunch()

Using the params parameter, these functions receive parameters of the created process via a structure containing the following fields:

• eiid – pointer to the process class name.
• endpointsCount – number of provided endpoints.

  The field can have a zero value if the process does not provide endpoints.

• endpoints – pointer to the array of structures containing the characteristics of provided endpoints (names and RIIDs of endpoints, names of interfaces).

  The type of structure is defined in the header file sysroot-*-kos/include/services/handle/if_connection.h from the KasperskyOS SDK.

  The field can have the RTL_NULL value if the process does not provide endpoints.

• args – pointer to the array of program startup parameters.

  The RTL_NULL value must be the last element of the array.

• envs – pointer to the array of environment variables of the program.

  The RTL_NULL value must be the last element of the array.

• flags:
  • KOS_TASK_FLAGS_NONE – no flags.
  • KOS_TASK_FLAG_DUMPABLE – the process switches to the "frozen" state as a result of an unhandled exception.

    For details about the "frozen" state, see Managing processes (low-level API task_api.h).

• componentTree – pointer to the structure containing information from the formal specification of the solution component.

  The type of structure is defined in the header file sysroot-*-kos/include/nk/types.h from the KasperskyOS SDK. This structure is an element of automatically generated transport code.

  If the field has a value other than RTL_NULL, the values in the eiid, endpointsCount and endpoints fields will be ignored, and the process class name and parameters of the provided endpoints (including the parameters of endpoints of embedded components) will be taken from the formal specification of the solution component.

The KosTaskInitEx(), KosTaskInit(), KosTaskInitFromSegEx() and KosTaskInitFromSeg() functions use the outTask output parameter to pass the pointer to the address of the object describing the child process. This object is a structure that is created in the memory of the parent process and the child process. The developer of a KasperskyOS-based solution does not need to perform operations with the fields of this structure. However, the pointer to this structure must be used as the process ID when calling API functions. A child process can get the address of the object describing it by calling the KosTaskGetSelf() function.

If statically created IPC channels are used for access to endpoints provided by a server process, the object describing this server process must be linked to the structures containing information about endpoints from the formal specification of the solution component. This is necessary so that client processes can receive information about endpoints provided by the server process when creating a static IPC channel. To link an object describing a child server process to structures containing information about endpoints from the formal specification of the solution component, this information must be passed through the componentTree field of the params parameter when calling the KosTaskInit*() functions or KosTaskLaunch() function. A server process that is already running can link the object describing it to structures containing information about endpoints from the formal specification of the solution component by calling the KosTaskSetComponentTree() function. This is required if the running server process does not have a parent process.

When the KosTaskInitEx(), KosTaskInit() or KosTaskLaunch() function is called, the ELF image from the defined executable file in ROMFS is loaded into the memory of the created process. If the ELF image contains the symbol table .symtab and string table .strtab, they are loaded into process memory. Using these tables, the kernel receives the names of functions for generating stack backtrace data (call stack information).

To get information about the ELF image loaded into process memory, call the KosTaskGetElfSegs() function.

When the KosTaskInit() or KosTaskLaunch() function is called, one of the following values is used as the process name and executable file name:

• Value of the eiid field, if the value of the componentTree field is equal to RTL_NULL.
• Name of the process class from the formal specification of the solution component, if the componentTree field value is different from RTL_NULL.

Likewise, these values are applied as the process name and/or executable file name if you call the KosTaskInitEx() or KosTaskInitFromSegEx() function with the RTL_NULL value in the name parameter and/or the path parameter. These values are also applied as the process name if you call the KosTaskInitFromSeg() function with the RTL_NULL value in the name parameter.

To use the KosTaskInitFromSegEx() and KosTaskInitFromSeg() functions, MDL buffers containing the ELF image segments must be created in advance. You must use the segs parameter to define the ELF image segments to be loaded into the memory of the created process.

You must use the entry and relocBase parameters of the KosTaskInitFromSegEx() function to define the program entry point and the ELF image load offset, respectively. The program entry point is the sum of the address specified in the e_entry field of the ELF image header and the ELF image load offset. The KnElfCreateVmSegEx() function declared in the header file sysroot-*-kos/include/coresrv/elf/elf_api.h from the KasperskyOS SDK generates a random offset for loading the ELF image and calculates the address of the program entry point according to this offset. (The ELF image load offset must be a random value to ensure ASLR support. For details about ASLR, see Managing processes (low-level API task_api.h).)

You can use the KosTaskInitFromSegEx() function to load the symbol table .symtab, string table .strtab and ELF image header into the memory of the created process. The ELF image header should be loaded if data from this header must be available in the created process.

Data passed to the KosTaskInitFromSegEx() function via the segs, entry, and relocBase parameters and the parameters associated with loading the symbol table .symtab and string table .strtab are prepared by the KnElfCreateVmSegEx() function declared in the header file sysroot-*-kos/include/coresrv/elf/elf_api.h from the KasperskyOS SDK.

The KosTaskInitFromSeg() function is a simplified version of the KosTaskInitFromSegEx() function and does not let you load the symbol table .symtab, string table .strtab and ELF image header into process memory, and does not let you define the ELF image load offset (instead, it sets a null offset).

The KosTaskLaunch() function creates and immediately starts a process without the capability to statically create IPC channels.

Statically created IPC channels

Before starting processes, you can create IPC channels between them. You can create multiple IPC channels with different names between one client process and one server process. You can create IPC channels with the same name between one server process and multiple client processes.

To create an IPC channel with a name matching the name of a server process class, call the KosTaskConnect() function.

To create an IPC channel with a defined name, call the KosTaskConnectToService() function.

To use the created IPC channel, you need to get the client IPC handle on the client process side by calling the ServiceLocatorConnect() function. On the server process side, you need to get the server IPC handle by calling the ServiceLocatorRegister() function. These functions use the channelName parameter to receive the name of the IPC channel. (The ServiceLocatorConnect() and ServiceLocatorRegister() functions are declared in the header file sysroot-*-kos/include/coresrv/sl/sl_api.h from the KasperskyOS SDK.)

Transferring handles

A parent process can transfer one or more handles to a child process that is not yet running. (General information about transferring handles is provided in the Transferring handles section.)

To pass a handle to a child process, call the KosTaskTransferResource() function while specifying the handle of the resource transfer context object, the permissions mask, and the conditional name of the descendant of the transferred handle in addition to the other parameters.

To find the descendant of a handle transferred by a parent process, call the KosTaskLookupResource() function while specifying the conditional name of the descendant of the handle that was defined by the parent process when calling the KosTaskTransferResource() function.

Starting processes

To create and immediately start a process without statically creating IPC channels, call the KosTaskLaunch() function.

To start an already created process for which you can create the necessary IPC channels before starting this process, call the KosTaskRunEx() or KosTaskRun() function.

Use the fsBackend parameter of the KosTaskRunEx() function to specify whether to use the kernel or the system program fsusr to support the ROMFS file system for the started process. Use of the fsusr program ensures that the ROMFS image resides in the user space. The user space can host a significantly larger ROMFS image than the kernel space.

To enable the use of a ROMFS file system residing in the user space, include the fsusr program into the KasperskyOS-based solution and create an IPC channel named kl.core.FSUsr from the process that needs to use this file system to the process named kl.core.FSUsr. (The client portion of the fsusr program is included in the libkos library.) To check whether the fsusr program is included in your KasperskyOS SDK, verify that the sysroot-*-kos/bin/fsusr executable file is available.

To specify how to support the file system in an already running process, call the KosTaskSetSelfFSBackend() function. This function can be used as follows. The parent process indicates that the fsusr program supports its ROMFS file system, and loads the required ROMFS image by calling the KnFsChange() function. (The KnFsChange() function is declared in the header file sysroot-*-kos/include/coresrv/fs/fs_api.h from the KasperskyOS SDK.) Then the parent process starts the child process by calling the KosTaskRunEx() function and specifies that the ROMFS file system for the child process is supported by the fsusr program. As a result, the child process will use the ROMFS image that is placed in the user space by the parent process by default.

If the parent process does not need to terminate the child process or wait for its termination, the object describing the child process must be deleted and the counter for links to it must be reset by using the KosTaskPut() function after the child process is started. The KosTaskLaunch() function calls the KosTaskPut() function after the child process is started.

Terminating processes

The API terminates and waits for termination of child processes.

To terminate a child process, call the KosTaskStop() or KosTaskStopAndWait() function.

To wait for a child process to terminate on its own initiative, call the KosTaskWait() function.

To ensure that the kernel object describing a child process is deleted after this process is terminated, its handle in the parent process must be closed before or after termination of the child process. The handle of the child process is closed when the object describing the child process is deleted from the memory of the parent process. To delete an object describing a child process, reset the counter for links to this object by using the KosTaskPut() function. The KosTaskLaunch() function calls the KosTaskPut() function after the child process is started.

For details about terminating processes, see Managing processes (low-level API task_api.h).

Information about API functions

task.h functions