Skip to content

Latest commit

 

History

History
247 lines (187 loc) · 12.1 KB

README.md

File metadata and controls

247 lines (187 loc) · 12.1 KB

Example of using the ExecutionManager component API

The KasperskyOS Community Edition SDK includes the ExecutionManager component. The ExecutionManager component provides a C++ interface for creating, starting, and stopping processes in solutions that are based on KasperskyOS. This example demonstrates a reference use of the ExecutionManager component API.

For more information about the ExecutionManager API, see the following topics: ExecutionManager component and Starting processes using the system program ExecutionManager in the KasperskyOS Community Edition Developer's Guide.

For additional details on KasperskyOS, including its limitations and known issues, please refer to the KasperskyOS Community Edition Online Help.

Table of contents

Solution overview

List of programs

  • Client—Program that manages two applications using IPC to interact with the ExecutionManager component
  • ExecMgrEntity—Program that provides an interface for creating, starting, and stopping processes
  • BlobContainer—Program that loads dynamic libraries used by other programs into shared memory
  • DCM—Program for dynamic creation of IPC channels
  • NameServer—Program that provides an interface for dynamically creating IPC channels
  • RAMDisk—Block device driver of a virtual drive in RAM
  • EntropyEntity—Random number generator
  • VfsRamFs—Program that supports RamFS file system

To make the client call the interface methods provided by the ExecutionManager component, the header file component/execution_manager/kos_ipc/execution_manager_proxy.h is included in the ./client/src/main.cpp file.

Initialization description

Statically created IPC channels
  • client.Client → kl.core.NameServer
  • client.Client → kl.bc.BlobContainer
  • client.Client → execution_manager.ExecMgrEntity
  • kl.bc.BlobContainer → kl.VfsRamFs
  • execution_manager.ExecMgrEntity → kl.bc.BlobContainer
  • kl.core.NameServer → kl.bc.BlobContainer
  • kl.VfsRamFs → kl.drivers.RAMDisk
  • kl.VfsRamFs → kl.EntropyEntity
  • kl.VfsRamFs → kl.bc.BlobContainer
  • kl.drivers.RAMDisk → kl.bc.BlobContainer
  • kl.EntropyEntity → kl.bc.BlobContainer

The ./einit/src/init.yaml.in template is used to automatically generate a part of the solution initialization description file init.yaml. For more information about the init.yaml.in template file, see the KasperskyOS Community Edition Online Help.

Security policy description

The ./einit/src/security.psl.in template is used to automatically generate a part of the security.psl file using CMake tools. The security.psl file contains a part of a solution security policy description. For more information about the security.psl file, see Describing a security policy for a KasperskyOS-based solution.

⬆ Back to Top

Getting started

Prerequisites

  1. To install KasperskyOS Community Edition SDK and run examples on QEMU or on a hardware platform, make sure you meet all the System requirements, which are listed in the KasperskyOS Community Edition Developer's Guide.
  2. Install KasperskyOS Community Edition SDK. You can download the latest version of the KasperskyOS Community Edition for free from os.kaspersky.com. The minimum required version of KasperskyOS Community Edition SDK is 1.3. For more information, see System requirements.
  3. Copy source files to your project directory.

Building and running the example

The example is built using the CMake build system, which is provided in the KasperskyOS Community Edition SDK.

To build the example, run the ./cross-build.sh script. There are environment variables that affect the build of the example:

  • SDK_PREFIX specifies the path to the installed version of the KasperskyOS Community Edition SDK. If the -s option is not specified when the cross-build.sh script has been run, it is necessary to set the value of the SDK_PREFIX environment variable.
  • TARGET specifies the target platform. (Currently only the aarch64-kos platform is supported.)

Syntax for using the cross-build.sh script:

$ ./cross-build.sh [-h] [-l] [-t TARGETS] [-s PATH] [-b PATH],

where:

  • -h, --help

    Help text.

  • -l, --list

    List of all CMake targets which are available for building.

  • -t, --target TARGETS

    List of CMake targets that you want to build. Enclose the entire list of targets in quotation marks and separate the individual targets within the quotation marks with a space character. If not specified, the default target sim will be built.

  • -s, --sdk-path PATH

    Path to the installed version of the KasperskyOS Community Edition SDK. The path must be set using either the value of the SDK_PREFIX environment variable or the -s option. The value specified in the -s option takes precedence over the value of the SDK_PREFIX environment variable.

  • -b, --build PATH

    Path to the generated CMake build directory. If not specified, the default path ./build will be used.

For example, review the following command:

$ SDK_PREFIX=/opt/KasperskyOS-Community-Edition-<version> ./cross-build.sh

The command builds the example and runs the KasperskyOS-based solution image on QEMU. The solution image is based on the SDK found in the /opt/KasperskyOS-Community-Edition-<version> path, where version is the latest version number of the KasperskyOS Community Edition SDK.

QEMU

Running cross-build.sh creates a KasperskyOS-based solution image that includes the example. The kos-qemu-image solution image is located in the ./<build_path>/einit directory, where build_path is the path to the generated CMake build directory.

The cross-build.sh script both builds the example on QEMU and runs it.

Hardware

Running cross-build.sh creates a KasperskyOS-based solution image that includes the example and a bootable SD card image for Raspberry Pi 4 B or Radxa ROCK 3A. The kos-image solution image is located in the ./<build_path>/einit directory. The hdd.img bootable SD card image is located in the ./<build_path> directory.

  1. To copy the bootable SD card image to the SD card, connect the SD card to the computer and run the following command:

$ sudo dd bs=64k if=build/hdd.img of=/dev/sd[X] conv=fsync,

where [X] is the final character in the name of the SD card block device.

  1. Connect the bootable SD card to the Raspberry Pi 4 B or Radxa ROCK 3A.
  2. Supply power to the Raspberry Pi 4 B or Radxa ROCK 3A and wait for the example to run.

You can also use an alternative option to prepare and run the example:

  1. Prepare the required hardware platform and bootable SD card for it by following the instructions:
  2. Run the example as described in the KasperskyOS Community Edition Online Help

CMake input files

When you develop a KasperskyOS-based solution, use the recommended structure of project directories to simplify usage of CMake scripts.

The CMakeLists.txt files use standard CMake syntax and scripts from the platform, nk, install, and image SDK libraries.

./сlient/CMakeLists.txt—CMake commands for building the Сlient program. Link the client executable file to the client proxy library of ExecutionManager component by adding the following command to the CMake file for building the client:

target_link_libraries (${PROGRAM_NAME} ${vfs_CLIENT_LIB}
                                       ${execution_manager_EXECMGR_PROXY})

./einit/CMakeLists.txt—CMake commands for building the Einit program and the solution image.

./execution_manager/CMakeLists.txt—CMake commands for building the ExecMgrEntity program. The ExecutionManager component is provided in the SDK as a set of static libraries and header files, and is built for a specific solution by using the CMake command create_execution_manager_entity() from the CMake library execution_manager:

include (execution_manager/create_execution_manager_entity)
create_execution_manager_entity(ENTITY         ${PROGRAM_NAME}
                                NK_MODULE_NAME ${PROJECT_NAME}
                                MAIN_CONN_NAME ${PROGRAM_NAME}
                                ROOT_PATH      "/"
                                VFS_CLIENT_LIB ${vfs_CLIENT_LIB})

For a description of the parameters, see Starting processes using the system program ExecutionManager.

./CMakeLists.txt—CMake commands for building the solution. In this file, the following commands are required to connect the ExecutionManager component:

find_package (execution_manager REQUIRED)
include_directories (${execution_manager_INCLUDE})
add_subdirectory (execution_manager)

⬆ Back to Top

Usage

Build and run the example. After running the example, the following actions will be executed:

  1. The KasperskyOS kernel runs the Einit initialization process.
  2. The Einit initializes static IPC channels and runs all processes except two applications which are run by the Client.
  3. The Client executes the following actions:
  4. Publishes the provided endpoints on the name server.
  5. Starts two applications.
  6. Waits for notifications from the applications.
  7. Stops both applications.
  8. On successful completion of work, the client and applications print messages to standard output. The expected output is contained in the ./expected_output.txt file.

Trademarks

Registered trademarks and endpoint marks are the property of their respective owners.

Raspberry Pi is a trademark of the Raspberry Pi Foundation.

⬆ Back to Top

© 2025 AO Kaspersky Lab