Getting started using rt-kernel

Evaluation board details

This example uses the Infineon evaluation board “XMC4800 Relax EtherCAT Kit”. It has a Cortex®-M4 running at 144 MHz, and it has 352 kB RAM and 2 MB flash. Details are found on https://www.infineon.com/cms/en/product/evaluation-boards/kit_xmc48_relax_ecat_v1/

You can use other evaluation boards supported by rt-kernel, but you need to adapt paths etc accordingly.

Install tools on a Linux Laptop

Install (see description elsewhere):

  • Workbench (Version 2020.1 or later)

  • Compiler

  • rt-kernel, use variant rt-kernel-xmc4

  • Segger J-link

  • Run pip install pyyaml

  • cmake (version 3.14 or later)

Copy the rt-kernel sources

Run (adapt paths):

cp -r /opt/rt-tools/rt-kernel-xmc4 /home/jonas/projects/profinetstack/rtkernelcopy/

Patch the source by using the patch file available in the p-net repository. Verify that you have the version of rt-kernel that the patch file is intended for. Run this in the root folder of the rt-kernel directory:

patch -p1 < PATH_TO_PNET/src/ports/rt-kernel/0001-rtkernel-for-Profinet.patch

You may want to change IP settings in rt-kernel-xmc4/bsp/xmc48relax/include/config.h.

In the root folder of the rt-kernel directory:

source setup.sh xmc48relax
make clean
make -j

Download and compile p-net

Clone the source:

git clone --recurse-submodules https://github.com/rtlabs-com/p-net.git

This will clone the repository with submodules. If you already cloned the repository without the --recurse-submodules flag then run this in the p-net folder:

git submodule update --init --recursive

The CMake build files for rt-kernel need to know which BSP you want to use, as well as the path to your rt-kernel source tree. Run the following to create and configure the build:

RTK=<PATH TO YOUR MODIFIED>/rt-kernel-xmc4 \
BSP=xmc48relax \
cmake -B build -S p-net \
-DCMAKE_TOOLCHAIN_FILE=cmake/tools/toolchain/rt-kernel.cmake \
-DCMAKE_ECLIPSE_EXECUTABLE=/opt/rt-tools/workbench/Workbench \
-DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE -G "Eclipse CDT4 - Unix Makefiles"

If you are using Windows, start the program “Command line” found in the rt-labs rt-collab Toolbox installation (adapt paths to your setup):

cd /c/Users/rtlfrm/Documents/Profinet

RTK=/c/Users/rtlfrm/Documents/Profinet/rt-kernel-xmc4 \
BSP=xmc48relax \
/c/Program\ Files/CMake/bin/cmake.exe -B build -S p-net \
-DCMAKE_TOOLCHAIN_FILE=cmake/tools/toolchain/rt-kernel.cmake \
-DCMAKE_ECLIPSE_EXECUTABLE=/opt/rt-tools/workbench/Workbench \
-DCMAKE_ECLIPSE_GENERATE_SOURCE_PROJECT=TRUE -G "Eclipse CDT4 - Unix Makefiles"

Depending on how you installed cmake, you might need to run snap run cmake instead of cmake. This creates build files in a folder named build. You can choose any name for the build folder, for instance if you want to build for multiple targets.

After running cmake you can run ccmake build or cmake-gui in the build folder to change settings.

Start Workbench:

/opt/rt-tools/workbench/Workbench

Two Workbench projects have been created by cmake. One project is for building the code, the other is for the p-net source code. You need at least to import the project for building the code.

Use the menu “File > Import”. Select “General > Existing Projects”. Click “Browse” and select the build directory that was created earlier.

Use the menu “Project > Build All” to build it.

An OSAL layer hosted in a separate directory is used by p-net, and is installed automatically during setup. For details see the tutorial page in this documentation.

More Workbench settings

If you intend to edit the p-net source code in the Workbench tool, you should also import the p-net source project. The files .project and .cproject have been created in the p-net repo by cmake.

Use the menu “File > Import”. Select “General > Existing Projects”. Click “Browse” and select the p-net repo directory.

After importing, right-click on the project and choose “New > Convert to a C/C++ project”. This will setup the project so that the indexer works correctly and the Workbench revision control tools can be used.

Run on target

Install J-link from https://www.segger.com/ Start Segger J-link GDB debug server:

JLinkGDBServerExe

Select “USB” and target device “XMC4800-2048” in the GUI. Use “Little Endian”, Target interface “SWD” and speed “Auto Selection”.

Run the compiled code on target by right-clicking the Profinet build project, and selecting “Debug as > Hardware debugging”. Select J-Link. On the “Startup” tab enter monitor reset 0 in the “Run commands”. Click Apply and Close. Select pn_dev.elf and click OK. The download progress pop-up window should appear.

The resulting .elf file contains the sample application, the p-net stack, the rt-kernel, lwip and drivers.

If you need to adjust debugger settings later, right-click the Profinet build project, and select “Debug as > Debug configurations”. Select the “Profinet… ” node. You might need to double click “Hardware Debugging” if the child node does not appear. Typically these values have been automatically entered:

  • Tab “Main” C/C++ application: pn_dev.elf.

  • Tab “Debugger”. Debugger type J-Link. GDB command: ${COMPILERS}/arm-eabi/bin/arm-eabi-gdb.

To be able to view register content, use the MMR tab in the debug view. Select core “XMC4800”.

Open a terminal to view the debug output from the target, which will appear as for example /dev/ttyACM0. An example of a terminal program is picocom (add yourself to the dialout user group to avoid using sudo):

sudo picocom -b 115200 /dev/ttyACM0

You can step-debug in the Workbench GUI. Press the small “Resume” icon to have the target run continuously.

Adjust log level

In order to learn the Profinet communication model, it is very informative to adjust the log level to see the incoming and outgoing messages. See the tutorial page for details on how to adjust the log level.

However note that printing out log strings is slow, so you probably need to decrease the cyclic data frequency (see PLC timing settings below). It is recommended to use log level ERROR when running with short cycle times on a microcontroller, in order not to interfere with the real-time requirements of the Profinet communication.

Standalone rt-kernel project

This creates standalone makefiles.

Configure the build:

RTK=<PATH TO YOUR MODIFIED>/rt-kernel-xmc4 \
BSP=xmc48relax \
cmake -B build -S p-net \
-DCMAKE_TOOLCHAIN_FILE=cmake/tools/toolchain/rt-kernel.cmake \
-G "Unix Makefiles"

Build the code:

cmake --build build

Serial port baud rate

If you like to increase the baud rate of the serial port, change the value in the file bsp/xmc48relax/src/xmc48relax.c. For example change .baudrate = 115200, to .baudrate = 460800,.

To be able to run debug logging via serial cable, you need to increase the baudrate to 460800 bits/s.

PLC timing settings

The send clock is 1 ms in the GSDML file.

If you do lots of printouts (which are slow) from the application on the XMC4800 board, you might need to increase the reduction ratio in the PLC settings to avoid timeout errors.

In case of problems, increase the reduction ratio (and timeout) value a lot, and then gradually reduce it to find the smallest usable value.

Using the built-in rt-kernel shell

Press Enter key to enter the built-in rt-kernel shell via the serial console. To view a list of available commands, use:

help

Example commands:

ls /disk1
hexdump /disk1/pnet_data_ip.bin
rm /disk1/pnet_data_ip.bin
pnio_factory_reset
pnio_remove_files
pnio_show

Memory requirements for the tests

Note that the tests require a stack of at least 6 kB. You may have to increase CFG_MAIN_STACK_SIZE in your BSP include/config.h file.

Examining flash and RAM usage

The flash and RAM usage is shown by the tool arm-eabi-size. In this example we use:

CMAKE_BUILD_TYPE Release
LOG_LEVEL Warning
PNET_MAX_AR 1
PNET_MAX_SLOTS 5
PNET_MAX_SUBSLOTS 3

To estimate the binary size, link partially (without standard libraries). This example is for cortex-m4f MCU:s, such as XMC4800:

build$ make all
build$ /opt/rt-tools/compilers/arm-eabi/bin/arm-eabi-gcc -O3 -DNDEBUG -mcpu=cortex-m4 -mthumb -mfloat-abi=hard -mfpu=fpv4-sp-d16 CMakeFiles/pn_dev.dir/samples/pn_dev/sampleapp_common.o CMakeFiles/pn_dev.dir/src/ports/rt-kernel/sampleapp_main.o -o pn_dev.elf libprofinet.a -nostartfiles -nostdlib -r

Study the resulting executable:

build$ arm-eabi-size pn_dev.elf
   text   data    bss     dec      hex  filename
 127421     16   1388  128825    1f739  pn_dev.elf

Values in bytes (including the rt-kernel RTOS).

  • text: code in flash

  • data: Memory, statically initialized

  • bss: Memory, zero-initialized. For example the stack.

  • dec = text + data + bss

  • hex = text + data + bss (in hexadecimal)

The flash usage is text + data, as the RAM initialization values are stored in flash.

Run tests on XMC4800 target

In order to compile the test code, make sure to use BUILD_TESTING and that TEST_DEBUG is disabled. Reduce PNET_MAX_FILENAME_SIZE to 30 bytes. This is done via ccmake, which should be started in the build directory:

ccmake .

Set CFG_MAIN_STACK_SIZE to at least 8192 in rt-kernel-xmc4/bsp/xmc48relax/include/config.h

The resulting file after compiling is named pf_test.elf

Add a new hardware debugging configuration, where the C/C++ application on the “Main” tab is set to pn_dev.elf.

The test will run on the target board when starting hardware debugging. You might need to press the Play button in the Workbench if you have enabled breakpoints.

Run tests on the QEMU emulator

On a Linux laptop, install the package rt-collab-qemu.

Patch the rt-kernel. Use the BSP “integrator”, which is intended for emulation. You need to increase the main stack size in rt-kernel/bsp/integrator/include/config.h. Modify CFG_MAIN_STACK_SIZE.

In the root folder of the rt-kernel directory:

source setup.sh integrator
make clean
make -j

In the parent directory of p-net, configure a new build directory:

RTK=<PATH TO YOUR MODIFIED>/rt-kernel \
BSP=integrator \
cmake -B build.integrator -S p-net \
-DCMAKE_TOOLCHAIN_FILE=cmake/tools/toolchain/rt-kernel.cmake \
-G "Unix Makefiles"

If necessary adjust the settings:

ccmake build.integrator/

Build only the pf_test binary:

cmake --build build.integrator/ -j --target pf_test

Start the emulator:

/opt/rt-tools/qemu/bin/qemu-system-arm -M integratorcp -nographic -semihosting -kernel build.integrator/pf_test.elf

If you add -s it it possible to connect with gdb to port 1234 from Workbench. By adding -S qemu will wait for gdb to connect.

To send a command line argument to the gtest binary, add --append "<gtest_command". For example --append "--gtest_filter=AlarmUnitTest*" or --append "--gtest_filter=CmrpcTest.CmrpcConnectReleaseTest".

Exit QEMU with CTRL-A X (not CTRL-A CTRL-X).

SNMP

To enable SNMP support, set the PNET_OPTION_SNMP value to ON.

See Network topology detection for more details on SNMP and how to verify the SNMP communication to the p-net stack.

IP-stack LWIP

The rt-kernel uses the “lwip” IP stack.

To enable logging in lwip, modify the file rt-kernel-xmc4/lwip/src/include/lwip/lwipopts.h.

Make sure general logging is enabled:

#define LWIP_DEBUG 1
#define LWIP_DBG_MIN_LEVEL          LWIP_DBG_LEVEL_ALL
#define LWIP_DBG_TYPES_ON           LWIP_DBG_ON

And enable debug logging of the modules you are interested in:

#define PBUF_DEBUG                  LWIP_DBG_OFF
#define IP_DEBUG                    LWIP_DBG_ON
#define IGMP_DEBUG                  LWIP_DBG_ON
#define TCPIP_DEBUG                 LWIP_DBG_ON

Rebuild rt-kernel.

Increase LWIP resources

In order to handle incoming data, you might need to increase buffer sizes for the lwip IP stack.

In the file lwip/src/include/lwip/lwipopts.h or in lwip/src/include/lwip/opt.h (which holds the default values), increase the values for MEMP_NUM_NETBUF and PBUF_POOL_SIZE.

It can also be beneficial to increase the values eth_cfg.rx_buffers and eth_cfg.rx_task_prio found in the bsp/xmc48relax/src/lwip.c file.

For debugging you can enable LWIP_STATS_DISPLAY in the lwipopts.h file, and then trigger the stats_display() function.