Troubleshoot real-time capable applications

  • Article

Here are some troubleshooting steps for problems that may occur during development of real-time capable applications (RTApps).

Debugging problems

Debugging may fail for the following reasons:

  • Windows Update replaces the USB driver for the real-time cores with a generic driver. To restore debugging functionality for the real-time cores, open a command-line interface using PowerShell or Windows Command Prompt with administrator privileges and re-enable real-time core debugging. The required USB driver is installed when you run:

    az sphere device enable-development --enable-rt-core-debugging

  • The debugging settings file contains errors. In this situation, the debugger may fail to start. If you have edited the debugger settings, make sure the syntax of the file is correct.

  • On-chip debugger may have already been started in another context. If you see an error such as "Debugger Server: Error: couldn't bind gdb to socket on port 4444: Address already in use" or "Error: libusb_open() failed with LIBUSB_ERROR_ACCESS", check to see if you already have an openocd or gdb process running.

    If you are running on Linux, the command sudo lsof -n -i :4444 | grep LISTEN should show any processes holding port 4444 open. Replacing 4444 with any other port mentioned in the error message should give the same information for that port.

  • You may be missing the libncurses5 package on your Ubuntu 20.04 system. If you see an error such as "error while loading shared libraries: libncurses.so.5: cannot open shared object file: No such file or directory", you should install the package as follows:

    sudo add-apt-repository universe
sudo apt-get install libncurses5

  • If you try to debug a high-level app and two RTApps at once using multiple instances of Visual Studio, the second instance of Visual Studio will be unable to connect to the debugger. To work around this problem, debug all apps from a single instance of Visual Studio, as described in Debug partner applications.

CMake problems

You may encounter the following problems when using CMake with an RTApp:

  • The first time you open a CMake project in Visual Studio, CMakeLists generation automatically runs and sets the component ID for the application. If you then delete the component ID—for example, because the application is in a GitHub repo and you've done a hard reset—the build fails. To resolve this problem, regenerate the CMake cache in Visual Studio.
  • The CMakeLists.txt startup item frequently regenerates. The CMakeLists task runs whenever Visual Studio regenerates the CMake cache. As a result, it may run often.
  • Visual Studio hangs when you build an RTApp with CMake. To avoid this problem use Visual Studio 2019 update 1 or later.

As a general note, if errors occur when you're working with CMake, try regenerating the CMake cache. This often resolves problems.