Appendices

This section provides additional information to supplement the primary text of the document.

Additional examples

This section provides descriptions of additional examples that are included in KasperskyOS Community Edition.

net_with_separate_vfs example

This example presents a basic case of network interaction using Berkeley sockets.

The example consists of Client and Server entities linked by a TCP socket using a loopback interface. Standard POSIX functions are used in the code of the entities.

To connect entities using a socket through a loopback, they must use the same network stack instance. This means that they must interact with a "shared" VFS entity (in this example, this entity is called NetVfs).

To correctly connect the Client and Server entities to the NetVfs entity, the Env entity must also be included in the solution.

The CMake system, which is included with KasperskyOS Community Edition, is used to build and run the example.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

See the Building and running examples section.

net2_with_separate_vfs example

This example demonstrates the special features of a solution in which an entity uses standard POSIX functions to interact with an external server.

The net2_with_separate_vfs example is a modified net_with_separate_vfs example. In contrast to the net_with_separate_vfs example, in this example an entity interacts over the network with an external server rather than another entity.

This example consists of the Client entity running in KasperskyOS on QEMU and the Server program running in a Linux host operating system. The Client entity and Server process are bound by a TCP socket. Standard POSIX functions are used in the code of the Client entity.

To connect the Client entity and the Server process using a socket, the Client entity must interact with NetVfs entity. During the build, the NetVfs entity is linked to a network driver that supports interaction with the Server process running in Linux.

To correctly connect the Client entity to the NetVfs entity, the Env entity must also be included in the solution.

The CMake system, which is included with KasperskyOS Community Edition, is used to build and run the example.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

See the Building and running examples section.

embedded_vfs example

This example demonstrates how to embed the virtual file system (VFS) provided in KasperskyOS Community Edition into an entity being developed.

In this example, the Client entity fully encapsulates the VFS implementation from KasperskyOS Community Edition. This lets you eliminate the use of IPC for all the standard I/O functions (stdio.h, socket.h, etc.) for debugging or performance improvement purposes, for example.

The Client entity tests the following operations:

• Create a folder.
• Create and delete a file.
• Read from a file and write to a file.

Supplied resources

The example includes the hdd.img image of a hard drive with the FAT32 file system.

This example does not contain an implementation of drivers of block devices used by the Client. These drivers (the ATA and SDCard entities) are provided in KasperskyOS Community Edition and are added in the build file ./CMakeLists.txt.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

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

See also Building and running examples section.

embed_ext2_with_separate_vfs example

This example shows how to embed a new file system into the virtual file system (VFS) that is provided in KasperskyOS Community Edition.

In this example, the Client entity tests the operation of file systems (ext2, ext3, ext4) on block devices. To do so, the Client calls the file system driver (the FileVfs entity) via IPC, and FileVfs in turn calls the block device via IPC.

The ext2 and ext3 file systems work with the default settings. The ext4 file system works if you disable extent (mkfs.ext4 -O ^64bit,^extent /dev/foo).

Example files

The code of the example and build scripts are available at the following path:

Building and running example

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

See also Building and running examples section.

Preparing an SD card to run on Raspberry Pi 4 B

To run the embed_ext2_with_separate_vfs example on Raspberry Pi 4 B, the SD card needs to have both a bootable partition with the solution image as well as 3 additional partitions with the ext2, ext3 and ext4 file systems, respectively.

multi_vfs_ntpd example

This example shows how to use an external NTP server in KasperskyOS. The kl.Ntpd entity is included in KasperskyOS Community Edition and is an implementation of an NTP client, which gets time parameters from an external NTP servers in the background and passes them to the KasperskyOS kernel.

The example also demonstrates the use of various virtual file systems (VFS) in a single solution. The example uses different VFS to access the functions for working with the file system and functions for working with the network:

• VfsNet is used for working with the network.
• VfsRamfs and VfsSdCardFs are used for working with the file system.

The Client entity uses standard libc library functions for getting time information, which are converted to calls to VFS entities via IPC.

The Env entity is used to pass environment variables and main function arguments to other entities.

The CMake system, which is included with KasperskyOS Community Edition, is used to build and run the example.

Supplied resources

The following configuration files are included in the example:

• ./resources/include/config.h.in contains a description of the backend file system that will be used in the solution: sdcard or ramfs.

  Each backend in the solution also uses a separate VFS: respectively VfsSdCardFs or VfsRamfs.

• The ./resources/ramfs/etc and /resources/sdcard/etc directories contain configuration files for the VFS and Ntpd entities.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

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

See also Building and running examples section.

multi_vfs_dns_client example

This example shows how to use an external DNS server in KasperskyOS.

The example also demonstrates the use of various virtual file systems (VFS) in a single solution. The example uses different VFS to access the functions for working with the file system and functions for working with the network:

• VfsNet is used for working with the network.
• VfsRamfs and VfsSdCardFs are used for working with the file system.

The Client entity uses standard libc library functions for accessing a DNS service, which are converted to calls to VFS entities via IPC.

The Env entity is used to pass environment variables and main function arguments to other entities.

The CMake system, which is included with KasperskyOS Community Edition, is used to build and run the example.

Supplied resources

The following configuration files are included in the example:

• ./resources/include/config.h.in contains a description of the backend file system that will be used in the solution: sdcard or ramfs.

  Each backend in the solution also uses a separate VFS: respectively VfsSdCardFs or VfsRamfs.

• The ./resources/ramfs/etc and /resources/sdcard/etc directories contain configuration files for the VFS entities.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

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

See also Building and running examples section.

multi_vfs_dhcpcd example

Example use of the kl.Dhcpcd entity.

The Dhcpcd entity is an implementation of a DHCP client, which gets network interface parameters from an external DHCP server in the background and passes them to a virtual file system (VFS) entity.

The example also demonstrates the use of different VFS in a single solution. The example uses different VFS to access the functions for working with the file system and functions for working with the network:

• VfsNet is used for working with the network.
• VfsRamfs and VfsSdCardFs are used for working with the file system.

The Client entity uses standard libc library functions for getting information on network interfaces (ioctl), which are converted to calls to VFS entities via IPC.

The Env entity is used to pass environment variables and main function arguments to other entities.

The CMake system, which is included with KasperskyOS Community Edition, is used to build and run the example.

Supplied resources

The following configuration files are included in the example:

• ./resources/include/config.h.in contains a description of the backend file system that will be used in the solution: sdcard or ramfs.

  Each backend in the solution also uses a separate VFS: respectively VfsSdCardFs or VfsRamfs.

• The ./resources/ramfs/etc and /resources/sdcard/etc directories contain configuration files for the VFS and Dhcpcd entities.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

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

See also Building and running examples section.

mqtt_publisher example

Example use of the MQTT protocol in KasperskyOS.

In this example, an MQTT subscriber must be started on the host operating system, and an MQTT publisher must be started on KasperskyOS. The Publisher entity is an implementation of an MQTT publisher that publishes the current time with a 5-second interval.

When the example starts and runs successfully, an MQTT subscriber started on the host operating system prints a "received PUBLISH" message with a "datetime" topic.

The example also demonstrates the use of various virtual file systems (VFS) in a single solution. The example uses different VFS to access the functions for working with the file system and functions for working with the network:

• VfsNet is used for working with the network.
• VfsRamfs and VfsSdCardFs are used for working with the file system.

The Env entity is used to pass environment variables and main function arguments to other entities.

The CMake system, which is included with KasperskyOS Community Edition, is used to build and run the example.

Starting Mosquitto

To run this example, a Mosquitto MQTT broker must be installed and started on the host system. To install and start Mosquitto, run the following commands:

To start an MQTT subscriber on the host system, run the following command:

Supplied resources

The following configuration files are included in the example:

• ./resources/include/config.h.in contains a description of the backend file system that will be used in the solution: sdcard or ramfs.

  Each backend in the solution also uses a separate VFS: respectively VfsSdCardFs or VfsRamfs.

• The ./resources/ramfs/etc and /resources/sdcard/etc directories contain configuration files for the VFS and Ntpd entities.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

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

See also Building and running examples section.

mqtt_subscriber example

Example use of the MQTT protocol in KasperskyOS.

In this example, an MQTT publisher must be started on the host operating system, and an MQTT subscriber must be started on KasperskyOS. The Subscriber entity is an implementation of an MQTT subscriber.

When the example starts and runs successfully, an MQTT subscriber started on KasperskyOS prints a "Got message with topic: my/awesome/topic, payload: hello" message.

The example also demonstrates the use of various virtual file systems (VFS) in a single solution. The example uses different VFS to access the functions for working with the file system and functions for working with the network:

• VfsNet is used for working with the network.
• VfsRamfs and VfsSdCardFs are used for working with the file system.

The Env entity is used to pass environment variables and main function arguments to other entities.

The CMake system, which is included with KasperskyOS Community Edition, is used to build and run the example.

Starting Mosquitto

To run this example, a Mosquitto MQTT broker must be installed and started on the host system. To install and start Mosquitto, run the following commands:

To start an MQTT publisher on the host system, run the following command:

Supplied resources

The following configuration files are included in the example:

• ./resources/include/config.h.in contains a description of the backend file system that will be used in the solution: sdcard or ramfs.

  Each backend in the solution also uses a separate VFS: respectively VfsSdCardFs or VfsRamfs.

• The ./resources/ramfs/etc and /resources/sdcard/etc directories contain configuration files for the VFS and Ntpd entities.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

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

See also Building and running examples section.

gpio_input example

Example use of the GPIO driver.

This example lets you verify the functionality of GPIO input pins. The "gpio0" port is used. All pins except those indicated in exceptionPinArr array are set for input by default. The voltage on the pins corresponds to the state of the registers of the pull-up resistors. The state of all pins, starting from GPIO0 (accounting for the pins indicated in the exceptionPinArr array), will be read in succession. Messages about the state of the pins will be displayed on the console. The delay between the readings of adjacent pins is determined by the DELAY_S macro (the time is indicated in seconds).

exceptionPinArr is an array of GPIO pin numbers that need to be excluded from the example. This may be necessary if some pins are already being used for other functions, e.g. if pins are being used for a UART connection during debugging.

If you build and run this example on QEMU, an error will occur. This is the expected behavior, because there is no GPIO driver for QEMU.

If you build and run this example on Raspberry Pi 4 B, an error will occur.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

See the Building and running examples section.

gpio_output example

Example use of the GPIO driver.

This example lets you verify the functionality of GPIO output pins. The "gpio0" port is used. The initial state of all GPIO pins should correspond to a logical zero (no voltage on the pin). All pins other than those indicated in the exceptionPinArr array are configured for output. Each pin, starting with GPIO0 (accounting for those indicated in the exceptionPinArr array), will be sequentially changed to a logical one (voltage on the pin) and then to a logical zero. The delay between the changes of pin state is determined by the DELAY_S macro (the time is indicated in seconds). The pins are turned on/off from GPIO0 to GPIO27 and then back against to GPIO0.

exceptionPinArr is an array of GPIO pin numbers that need to be excluded from the example. This may be necessary if some pins are already being used for other functions, e.g. if pins are being used for a UART connection during debugging.

If you build and run this example on QEMU, an error will occur. This is the expected behavior, because there is no GPIO driver for QEMU.

If you build and run this example on Raspberry Pi 4 B, an error will occur.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

See the Building and running examples section.

gpio_interrupt example

Example use of the GPIO driver.

This example lets you verify the functionality of GPIO pin interrupts. The "gpio0" port is used. In the pinsBitmap bitmask of the CallBackContext interrupt context, the pins from exceptionPinArr array are marked as handled so that the example can properly terminate later. All pins other than those indicated in the exceptionPinArr array are switched to the PINS_MODE state. An interrupt handler will be registered for all pins other than those indicated in the exceptionPinArr array.

In an endless loop, the example checks whether the pinsBitmap bitmask from the CallBackContext interrupt context is equal to the DONE_BITMASK bitmask (which corresponds to the condition when an interrupt has occurred on each GPIO pin). Additionally, the handler function for the latest interrupted pin is removed in the loop. When a pin is interrupted for the first time, the handler function is called, which marks the corresponding pin in the pinsBitmap bitmask in the CallBackContext interrupt context. The handler function for this pin is removed later.

Keep in mind how the example may be affected by the initial state of the registers of pull-up resistors for each pin.

Interrupts for the GPIO_EVENT_LOW_LEVEL and GPIO_EVENT_HIGH_LEVEL events are not supported.

exceptionPinArr is an array of GPIO pin numbers that need to be excluded from the example. This may be necessary if some pins are already being used for other functions, e.g. if pins are being used for a UART connection during debugging.

If you build and run this example on QEMU, an error will occur. This is the expected behavior, because there is no GPIO driver for QEMU.

If you build and run this example on Raspberry Pi 4 B, an error will occur.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

See the Building and running examples section.

Page top

gpio_echo example

Example use of the GPIO driver.

This example makes it possible to verify the functionality of GPIO pins as well as the operation of GPIO interrupts. The "gpio0" port is used. The output pin (GPIO_PIN_OUT) should be connected to the input pin (GPIO_PIN_IN). The output pin (the pin number is defined in the GPIO_PIN_OUT macro) as well as the input pin (GPIO_PIN_IN) are configured. Use of the input pin is configured in the IN_MODE macro. The interrupt handler for the input pin is registered. The state of the output pin changes several times. If the example works correctly, then when the state of the output pin changes the interrupt handler will be called and will display the state of the input pin. What's more, the state of the output pin and the input pin must match.

If you build and run this example on QEMU, an error will occur. This is the expected behavior, because there is no GPIO driver for QEMU.

If you build and run this example on Raspberry Pi 4 B, an error will occur.

Example files

The code of the example and build scripts are available at the following path:

Building and running example

See the Building and running examples section.