4. Software Development Kit

This section is dedicated to useful tips and hints about how to use the Software Development Kit (SDK) on a Linux development host machine for application development and debugging purposes.

The SDK is based on the Yocto Project SDK. Refer to the Yocto Project Application Development and the Extensible Software Development Kit (eSDK) [10] manual for additional information and tips.

On some platforms, a separate debug-sdk is available on request to debug system libraries. Additionally, this can be built from the BSP. This option is not available for the Yukon and V700 platforms, please consult the Programmer’s manual for further instructions on debugging system libraries.

4.1 Downloading and installing the SDK

The toolchain included in the SDK is an ARM GNU/Linux cross compiler based on the standard GNU GCC compiler toolchain. Additionally, the SDK contains header and library files for CCAux API and other peripherals. In order to download the SDK, visit the CrossControl support site. For support on SDK issues, please contact CrossControl directly.

The SDK comes in the form of a self-extracting shell script. It contains precompiled binaries for Linux host systems. There are two versions of the SDK; one for 32-bit i686 hosts and one for 64-bit x86 hosts. To install the SDK, move the script to the host computer and run the following shell command:

$ sh scriptname.sh -d <sdk install dir>

Omitting the -d flag will install the SDK to the default directory, /opt/cclinux/1.0.0.

Example output from installing the CCpilot yukon SDK:

./CCLinux-SDK-toolchain-x86_64-CCpilot-YUKON-3.4.0.0-rc2-17-g10023f68.sh -d ../../cclinux_sdk/yukon -y
CCLinux Distribution SDK installer version 3.4
==============================================
You are about to install the SDK to "/build/jenkins/workspace/ccapi_master/cclinux_sdk/yukon". Proceed [Y/n]? Y
Extracting SDK...............................................................................................done
Setting it up...done
SDK has been successfully set up and is ready to be used.

4.1.1 Starting a new session

Once installed, the SDK contains the sysroots directory with target and host system root file systems, and an environment setup file; environment-setup-<XXXX> (file ending varies depending on your platform). The environment setup file exports the correct $PATH and other important build environment variables, such as $CC and $CFLAGS. (Read the file content to get an understanding of the default settings).

This file needs to be sourced before using the SDK each time a new shell session is started:

$ source environment-setup-<XXXX>

Now the cross-compiler is ready to use.

4.1.2 Using correct development headers

The SDK is released containing binary images. This package contains libraries available at the unit and all header files for utilizing them. The header files are located in:

<sdk-install-dir>/sysroots/<targetsysroot>/usr/include/

and the libraries are found in these two directories:

<sdk-install-dir>/sysroots/<targetsysroot>/lib/

<sdk-install-dir>/sysroots/<targetsysroot>/usr/lib/

These directories are automatically added to the search path when sourcing the environment setup script and don’t need any special consideration.

If additional development files placed outside of the SDK installation directory are to be used they can be added to the compiler search path by appending the $CFLAGS/$CXXFLAGS variable. This can be done either in the project settings or in the Makefile using:

CFLAGS+= –I<path-to-headerfile-dir> -L<path-to-library-dir>

4.1.3 Compiler optimizations

The environment setup script automatically sets the –mcpu=<cpu> compiler flag for optimizing the code for the instruction set generated for the specific processor. Additionally, floating point computations are automatically set to use the available hardware acceleration.

To see which optimizations are done by default, study the content of the environment setup script. All these settings can be overridden after the script has been sourced. See the compiler documentation for additional information about available optimizer flags.

4.1.4 Special considerations using CCAux API

In order to build applications using functions from the CCAux API library, two steps need to be given special consideration in either the project file or the Makefile:

  1. The $LD variable should be overridden to use the same content as the $CXX variable

  2. The $CFLAGS/$CXXFLAGS must be appended with the -DLINUX flag

If either of these steps are omitted, the build will fail. See chapter 6.1 for examples of how to build CCAux API applications.

4.2 Debugging remotely

To debug system libraries, you must have the sdk-with-debugging installed on your host machine and use it to build your application.

To use GDB to debug an application running on the device, the application must have been compiled with the -g flag. Start gdbserver on the device:

~$ gdbserver :10000 testApplication

Then start the host GDB and connect to the server:

$ arm-poky-linux-gnueabi-gdb testApplication

$ (gdb) target remote Y.Y.Y.Y:10000

Above Y.Y.Y.Y is the IP address of the device. Then issue the set sysroot and set substitute-path commands. Notice that you’ll have to substitute $SDKTARGETSYSROOT text with environment variable content of the same name. GDB cannot read that variable.:

$ (gdb) set sysroot $SDKTARGETSYSROOT
$ (gdb) set substitute-path $SDKTARGETSYSROOT/usr/src

You can now debug the application normally, except that instead of issuing the run command one should use continue since the application is already running on the remote side.

Note that it is possible to fully debug the application but not to make system calls made by the application. Such system calls include calls to the soft float library, like divide, add or multiply on floating point variables. It is therefore recommended to use next rather than step when such system calls are being made.

4.3 Rauc Bundle Generation & Update

To create rauc bundles for RootFS, AppFS and Bootloader, you should have the image content ready, and the rauc tool should be installed in the sdk. To be able to generate a rauc bundle, you also need cerfiticate and key files which you should already have.

First step is creating a manifest file which will describe which image will be installed to where and also includes some meta info. Manifest files should have “.raucm” suffix. An example manifest file is shown below;

$ cat >> created-appfs-content/manifest.raucm << EOF
[update]
compatible=CrossControl Oy
version=2019.01-1
[image.appfs]
filename=appfs.ext4
EOF

Then you’re ready to create the rauc bundle. Example command to create a rauc bundle is shown below;

$ rauc --cert development-1.cert.pem --key development-1.key.pem bundle created-appfs-content/ update-appfs.raucb

After executing this command, update-appfs.raucb will be created as output. You can transfer this file to the device via USB stick, or scp etc. then you’re ready to update. System has a tool named cc-update which should be used to update the device. Example update command is shown below.

$ cc-update install update-appfs.raucb

After update is completed, the system will be rebooted automatically. Then the partitions will be synchronized on the background. Synchronization process also can be checked via dmesg, for example;

ccs@v705:~$ dmesg | grep cc-u
[    6.147643] cc-update: A/B partition synchronization check.
[    6.154967] cc-update: New update detected, synchronizing partitions.
[   19.607432] cc-update: Synchronization ongoing.
[   33.660078] cc-update: Partition synchronization completed.
[   33.671367] cc-update: Clearing update directory

Then update & sync will be completed.

4.4 Rauc USB Updates

There should be a rauc bundle which is created properly with a manifest, proper key and cert files. Then you can just put the rauc bundle inside the USB stick and plug it. System has a tool named cc-update which will be triggered by the USB event. The progress can be checked on dmesg, for example;

ccs@v705:~$ dmesg | grep cc-
[    5.799594] cc-update: A/B partition synchronization check.
[    5.799919] cc-update: Partitions are already synced.
[   13.936433] cc-update: Found USB image. Updating.

Here if you see the log “Found USB image. Updating.”, the update has started. The system will be rebooted after it’s completed and synchronize the images between partition afterwards.