Skip to content

README.md

Latest commit

 

History

History
202 lines (155 loc) · 10.2 KB

README.md

File metadata and controls

202 lines (155 loc) · 10.2 KB

Using error handling via IPC

This example demonstrates error handling in KasperskyOS IPC through a distributed system with two servers (C and C++) and two clients (C and C++) requesting addition operations. It showcases client management of server errors — particularly simulated temporary unavailability — via retry logic. The system also includes logging infrastructure with a log server and output channel.

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

  • ServerC—C-language server that provides addition services via the NumberSummation interface for ClientC and ClientCXX clients. It uses static IPC connections and intentionally returns an rcBusy ("server busy") error for every second request to simulate load. The server logs its activity and is protected by a security policy that restricts access to authorized clients.
  • ServerCXX—C++-language server that provides addition services via the NumberSummation interface for ClientC and ClientCXX clients. It uses static IPC connections and intentionally returns an EBUSY ("server busy") error for every second request to simulate load. The server logs its activity and is protected by a security policy that restricts access to authorized clients.
  • ClientC—C-language client that sends addition requests to both ServerC and ServerCXX via static IPC. It selects the target server randomly and implements error handling with policy-defined retry limits.
  • ClientCXX—C++-language client that sends addition requests to both ServerC and ServerCXX via static IPC. It selects the target server randomly and implements error handling with policy-defined retry limits.
  • Server—System program that implements a log server to which other programs forward messages. To send messages to the log server, programs use the logrr_cpp library, which filters messages by log level. The log server forwards the received messages to the output channel named FsOutputChannel.
  • FsOutputChannel—System program that implements an output channel for the Server program. The output channel saves messages received from the log server to a file.
  • DCM—System program for dynamic creation of IPC channels.
  • EntropyEntity—System program that implements random number generation.
  • VfsSdCardFs—System program that supports the file system of SD cards.
  • SDCard—SD card driver.

When you build the example for the target hardware platform, platform-specific drivers are automatically included in the solution:

  • BSP—Hardware platform support package (Board Support Package). Provides cross-platform configuration of peripherals for the Radxa ROCK 3A and Raspberry Pi 4 B.
  • GPIO—GPIO support driver for the Radxa ROCK 3A.
  • PinCtrl—Low-level pin multiplexing (pinmux) configuration driver for the Radxa ROCK 3A.
  • Bcm2711MboxArmToVc—Driver for working with the VideoCore (VC6) coprocessor via mailbox technology for Raspberry Pi 4 B.

Initialization description

The solution initialization description file named init.yaml is generated during the solution build process based on the ./einit/src/init.yaml.in template. The macros in @INIT_*@‌ ‌format contained in the template are automatically expanded in the resulting init.yaml file. For more details, refer to init.yaml.in template.

Security policy description

The ./einit/src/security.psl file describes the security policy of the solution. The declarations in the PSL file are provided with comments that explain the purpose of these declarations. For more information about the security.psl file, see Describing a security policy for a KasperskyOS-based solution.

The security policy defined in security.psl ensures proper access control, allowing only specified clients to send requests to servers and limiting the number of retries to prevent excessive resource consumption.

⬆ Back to Top

Getting started

Prerequisites

  1. Confirm that your host system meets all the System requirements listed in the KasperskyOS Community Edition Developer's Guide.
  2. Install the KasperskyOS Community Edition SDK version 1.4. You can download it for free from os.kaspersky.com.
  3. Copy the source files of this example to your local project directory.
  4. Set up the build environment by sourcing the SDK setup script in your terminal session: 
    source /opt/KasperskyOS-Community-Edition-<platform>-<version>/common/set_env.sh
  5. Build the necessary drivers from source only if you intend to run this example on Radxa ROCK 3A hardware. This step is not required for QEMU or Raspberry Pi 4 B.

Building and running the example

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

QEMU

To build the example to run on QEMU, go to the directory with the example and run the following commands:

$ cmake -B build -D CMAKE_TOOLCHAIN_FILE="$KOSCEDIR/toolchain/share/toolchain-aarch64-kos.cmake"
$ cmake --build build --target {kos-qemu-image|sim}

where:

  • kos-qemu-image creates a KasperskyOS-based solution image for QEMU that includes the example;
  • sim creates a KasperskyOS-based solution image for QEMU that includes the example and runs it.

After a successful build, the kos-qemu-image solution image will be located in the ./build/einit directory.

Hardware

To build the example to run on the target hardware platform, go to the directory with the example and run the following commands:

$ cmake -B build -D CMAKE_TOOLCHAIN_FILE="$KOSCEDIR/toolchain/share/toolchain-aarch64-kos.cmake"
$ cmake --build build --target {kos-image|sd-image}

where:

  • kos-image creates a KasperskyOS-based solution image that includes the example;
  • sd-image creates a file system image for a bootable SD card.

After a successful build, the kos-image solution image will be located in the ./build/einit directory. The hdd.img bootable SD card image will be located in the ./build directory.

To run the example on the target hardware platform:

  1. Connect the SD card to the computer.

  2. Copy the bootable SD card image to the SD card using the 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.

  3. Connect the bootable SD card to the board.

  4. Supply power to the board 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 a bootable SD card to run the example by following the instructions:

  2. Run the example by following the instructions in the KasperskyOS Community Edition Online Help.

⬆ Back to Top

CMake input files

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

./client_c/CMakeLists.txt—CMake commands for building the ClientC program.

./client_cpp/CMakeLists.txt—CMake commands for building the ClientCXX program.

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

./server_c/CMakeLists.txt—CMake commands for building the ServerC program.

./server_cpp/CMakeLists.txt—CMake commands for building the ServerCXX program.

./CMakeLists.txt—CMake commands for building the solution.

Usage

Build and run the example. All logged messages are written to a log file. The file's location is determined by the LOG_DIR parameter of the create_logrr_fs_output_channel() function in the ./einit/CMakeLists.txt file.

⬆ Back to Top

© 2026 AO Kaspersky Lab