Extension functions

The extension automatically detects a KasperskyOS project in the open workspace and starts. The detection parameter is the presence of the .vscode/kos_project.json file or einit directory in the workspace. If the extension has not automatically activated in the directory but you are certain that it is a KasperskyOS project, run the command KOS: Activate extension in this directory. This command activates the extension and creates an empty .vscode/kos_project.json file in the project directory. To cancel manual activation, delete this file.

After startup, the extension adds the following buttons to the lower panel of the Visual Studio Code editor:

• – select the build target.
• – start the project in QEMU.
• – start the selected target with debugging.
• – build all targets.
• – build the selected target.
• – clear the build directory.
• – switch the build type.
• – enable/disable the project build with tests.
• – select the target platform for the build.
• – select the device or QEMU emulator.
• – display the SDK version.

Functions that provide buttons can also be called from the command line of the code editor, which can be opened by pressing F1. All commands have the KOS: prefix.

Working with a basic KasperskyOS image

The extension lets you avoid having to completely build a KasperskyOS-based solution after making changes to application code. Instead, you can use the following scenario:

1. Running a basic KasperskyOS-based solution image, included in the SDK, in the QEMU emulator. The basic image contains all the system programs required to run and debug programs packaged in KPA packages.
2. Build an application and package it into a KPA package. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Install a program from a KPA package into the solution image that was run at step 1 and start it under KasperskyOS.
4. Make changes to the application code.
5. Repeat steps 2–5.
6. With the extension, you can also debug a program that is running in a basic KasperskyOS image. For more details, refer to Debugging programs that are part of a KPA package.

Create a basic solution security policy description

The extension lets you automatically create basic solution security policy descriptions for a project.

To create a basic security policy description:

1. Make sure that the KasperskyOS SDK Extension is installed and active.
2. Press F1.
3. Run the command KOS: Generate policy file for current project.
4. Select the type of basic policy description that you want to create:
   • Grant all permissions: create a basic solution security policy description that allows all interactions between different processes of any class and between these processes and the KasperskyOS kernel, and that also allows any process to initialize the startup of processes.
   • Grant necessary permissions: create a basic solution security policy description that allows all interactions between different processes of any class and between these processes and the KasperskyOS kernel, and that also determines the necessary permissions for initializing the startup of processes based on the init.yaml.in file within the project.
5. Enter the file name for saving the created security policy description.

Running tests

After the extension is activated, the Testing tab () appears on the side panel of Visual Studio Code. When you select the Testing tab, the code editor window displays a tree of tests created using the Google Test library and found in files in the test/ directory.

To run the tests, tap the button. All detected tests are run by default. However, you can select specific tests on the tabs containing the source code of the tests, or you can select specific groups of tests by selecting them from the tree of all tests. You can only run tests that are added to CMakeLists.txt files for building programs using the kl_kos_add_small_test() or generate_kos_test() CMake commands from the TestGenerator CMake library included in the SDK.

The test results and log files are located in the directory <build_directory>/bin/tests/output.

Starting solution security policy tests

The extension lets you run solution security policy tests for a project if they were created based on the solution security policy description.

To build and run solution security policy tests:

1. Make sure that the solution security policy description contains the solution security policy tests.
2. Make sure that the CMake commands for building solution security policy tests have been added to one of the CMakeLists.txt files of the project.
3. Make sure that the KasperskyOS SDK Extension is installed and active.
4. Build all targets by clicking the button in the lower panel.
5. Click the build target selection button and select the target named kos-qemu-image-PalTest<N>-sim (N refers to the PSL file index within the list of PSL files containing solution security policy tests).
6. Click the button to build the selected target.

Starting a basic KasperskyOS-based solution image

The basic KasperskyOS-based solution image is included in the SDK and contains all the system programs required to run and debug programs packaged in KPA packages.

To start a basic KasperskyOS-based solution image from Visual Studio Code:

1. Make sure that the KasperskyOS SDK Extension is installed and active.
2. Click the device selection button on the lower panel or press F1 and run the command KOS: Select Device.
3. Select Create new emulator.
4. Select kos_base-dev.
5. In the opened field, enter the additional QEMU flags and press Enter, or immediately press Enter to use the default flags.
6. In the opened field, enter the name of the new emulator and press Enter, or immediately press Enter to use the automatically generated name.
7. Wait until the previous command completes.
8. In the notification about the new emulator being created, click the Start button.
9. Wait for the emulator to finish loading.

Building programs in Visual Studio Code

To build a program in Visual Studio Code:

1. Open the program project directory in Visual Studio Code.
2. Make sure that the project was correctly identified based on the appearance of additional extension buttons in the lower panel. If the buttons do not appear, manually activate the solution by running the command KOS: Activate extension in this directory.
3. Select the build architecture by clicking the button for selecting the target platform for the build .
4. Build all targets by clicking the button in the lower panel.

Starting programs in a basic solution image

If a program that you want to start uses file systems (via the VFS component), the following is required before starting the program:

1. Use the menu to open the extension settings window: File → Preferences → Settings, then select Extensions → KasperskyOS.
2. Set the client:kl.VfsSdCardFs value for the VFS_FILESYSTEM_BACKEND environment variable in the Application Environment Variables parameter.

To start a program in a basic solution image:

1. Open the program project directory in Visual Studio Code.
2. Make sure that the project was correctly identified based on the appearance of additional extension buttons in the lower panel. If the buttons do not appear, manually activate the solution by running the command KOS: Activate extension in this directory.
3. Make sure that the basic solution image is started according to the instructions provided in the Starting a basic KasperskyOS-based solution image section.
4. Click the button for selecting the device or QEMU emulator in the lower panel.
5. Select the previously started basic solution image.
6. Build the program according to the instructions provided in the Building a program in Visual Studio Code section.
7. Make sure that the program has been packed into a KPA package.

   You must use the CMake commands of the kpa library to pack a program into a KPA package.

8. Click the target selection button . In the drop-down list, select the built program KPA package that is signed as [application] in the list.
9. Click the start button . The program will be installed to the selected basic image and will automatically start.

Debugging a program that is part of a KPA package

Unlike debugging programs in a KasperskyOS-based solution, debugging a program in a KPA package means you don’t have to rebuild the entire KasperskyOS-based solution after updating the application code.

The scenario for debugging a program that is part of a KPA package looks as follows:

1. Install the KasperskyOS SDK Extension.
2. Build an application and package it into a KPA package. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Run a basic KasperskyOS image from KasperskyOS Community Edition with a GDB server built into the kernel.
4. Connect the debugger to the GDB server of the kernel. The debugger can be connected at program startup or while the program is running. Details:
   • Connecting a debugger at program startup.
   • Connecting a debugger while a program is running.
5. Debugging a program using the Visual Studio Code graphical user interface. For more details, refer to the Visual Studio Code documentation: https://code.visualstudio.com/docs/editor/debugging .

Connecting a debugger when starting a program in a basic image

To connect a debugger to the GDB server of the kernel while starting a program in QEMU using the Visual Studio Code extension:

1. Set a breakpoint in the program source code before the fragment to be debugged.
2. Build the program. You must use the CMake commands of the kpa library to pack a program into a KPA package.
3. Run a basic KasperskyOS image from KasperskyOS Community Edition.
4. Wait for the basic image to finish loading and install the program by running the command KOS: Install package.
5. On the side bar of Visual Studio Code, click Run and debug > create a launch.json file and then select KasperskyOS Debugger.

   This will create a debug configuration file named launch.json.

6. In the launch.json file, in the field of the configuration named (kos/gdb) Launch & debug application, specify the path to the binary file of your program resulting from the build, and the program name. In the eiid field, you need to specify the kl.Kds value.
7. Start debugging by clicking the (kos/gdb) Launch & debug application button on the lower pane.
8. In the drop-down list, select the configuration named (kos/gdb) Launch & debug application.
9. The debug console will show a message stating that the program is ready for debugging. Click Continue, and program execution will be stopped at the breakpoint that you selected at step 1.

Connecting a debugger while a program is running from a basic image

To connect a debugger to the GDB server of the kernel while the program is running in QEMU using the Visual Studio Code extension:

1. Add an infinite loop to the main function of the program. This enables the debugger to connect to the running program.
2. Set a breakpoint in the program source code before the fragment to be debugged.
3. Build the program. You must use the CMake commands of the kpa library to pack a program into a KPA package.
4. Run a basic KasperskyOS image from KasperskyOS Community Edition.
5. On the side bar of Visual Studio Code, click Run and debug > create a launch.json file and then select KasperskyOS Debugger.

   This will create a debug configuration file named launch.json.

6. In the launch.json file, in the field of the configuration named (kos/gdb) Attach to process, specify the path to the binary file of your program resulting from the build.
7. Start the program in the basic image.
8. Start debugging by clicking the (kos/gdb) Attach to process button on the lower pane.
9. In the drop-down list, select the configuration named (kos/gdb) Attach to process and select the name of the program to debug.
10. The debug console will show a message stating that the program is ready for debugging. Click Continue, and program execution will be stopped at the breakpoint that you selected at step 2.