Make-based cross compilation example

Updated at:

This topic provides an example of Make-based cross compilation. You can skip this topic if you are using pre-compiled files from the software development kit (SDK).

This topic demonstrates the complete cross compilation and porting process using the porting of the SDK to the arm-linux platform as an example.

To compile libiot_sdk.a for a target embedded hardware platform, perform the following steps:

  1. Add a configuration file to the tools/board/ folder. The file name must be in the config.XXX.YYY format. The XXX part corresponds to the Hardware Abstraction Layer (HAL) code in the wrappers/os/XXX folder.

  2. In the configuration file, specify the following parameters:

    • The path to the cross compiler OVERRIDE_CC.

    • The path to the cross linker OVERRIDE_LD.

    • The path to the static library archiver OVERRIDE_AR.

    • The compilation options CONFIG_ENV_CFLAGS for compiling C files.

    • The linker options CONFIG_ENV_LDFLAGS for linking executable programs.

  3. Compile the SDK and fix potential cross-platform issues until the libiot_sdk.a file is generated in the target format.

  4. Compile libiot_hal.a for the target architecture.

  5. If the target platform is not supported, the source code for libiot_hal.a is not included in the C-Link SDK. In this case, you must implement the HAL_*() interface yourself.

The following section uses an unsupported arm-linux target platform as an example to demonstrate how to compile a usable libiot_sdk.a file for the platform.

Install the cross compilation toolchain

This example uses an Ubuntu 16.04 development environment.

$ sudo apt-get install -y gcc-arm-linux-gnueabihf
$ arm-linux-gnueabihf-gcc --version
arm-linux-gnueabihf-gcc (Ubuntu/Linaro 4.8.4-2ubuntu1~14.04.1) 4.8.4
Copyright (C) 2013 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.   

Add a configuration file

$ touch tools/board/config.arm-linux.demo
$ ls tools/board/
config.alios.mk3080  config.arm-linux.demo  config.ubuntu.x86       

Edit the configuration file

When you edit the configuration file, set the compilation options, toolchain, and the folders to skip during compilation.

$ vim tools/board/config.arm-linux.demo
CONFIG_ENV_CFLAGS = \
    -D_PLATFORM_IS_LINUX_ \
    -Wall \
    -DNO_EXECUTABLES

CONFIG_ENV_LDFLAGS = \
    -lpthread -lrt

OVERRIDE_CC = arm-linux-gnueabihf-gcc
OVERRIDE_AR = arm-linux-gnueabihf-ar
OVERRIDE_LD = arm-linux-gnueabihf-ld

CONFIG_wrappers :=           
Important

CONFIG_wrappers := skips the compilation of the wrappers folder, and -DNO_EXECUTABLES prevents the generation of executable programs. This helps prevent excessive errors when you compile libraries for unsupported platforms.

Select a configuration file

$ make reconfig

SELECT A CONFIGURATION:

1) config.alios.mk3080
2) config.arm-linux.demo
3) config.ubuntu.x86

#? 2

SELECTED CONFIGURATION:

VENDOR :   arm-linux

MODEL  :   demo
            

Cross-compile the library file libiot_sdk.a

This step does not compile the HAL. It only verifies that the cross compilation parameters in the configuration file are correct. If an error occurs, modify the configuration file and recompile until the process succeeds.

$ make

BUILDING WITH EXISTING CONFIGURATION:


VENDOR :   arm-linux

MODEL  :   demo


[CC] infra_timer.o                      <=  ...
[CC] infra_json_parser.o                <=  ...
[CC] infra_preauth.o                    <=  ...
            

Obtain the cross-compiled products, including static libraries and header files

$ ls -1 output/release/lib/
libiot_sdk.a
libiot_tls.a
            
  • The libiot_sdk.a file is the compiled IoT Platform SDK. It is in the ELF 32-bit LSB relocatable, ARM, EABI5 version 1 (SYSV) format, which is the cross compilation format for arm-linux.

  • The libiot_tls.a file is a cropped encryption and decryption library. You can use this library or the one provided by the platform to reduce the final firmware size.

$ ls -1 output/release/include/

dev_model_api.h
dev_sign_api.h
infra
mqtt_api.h
            

The dev_sign_api.h header file is required to use the Device Signature feature in the SDK. Similarly, the mqtt_api.h header file is required to use the MQTT Cloud Connection feature. You must also add the header files from the infra folder to the compilation search path.

Develop the HAL for an unadapted platform

For the libiot_hal.a library that implements the HAL interfaces HAL_XXX_YYY(), there are no restrictions on how you compile and generate it.

You can also use the compilation system of the IoT Platform C-Link SDK for devices to develop and generate this library.

Copy the HAL implementation code

In the wrappers/os folder, create a folder with the same name as XXX in tools/board/config.XXX.YYY to store the HAL implementation.

Because the target platform is arm-linux, you can copy the HAL implementation from the Ubuntu folder. The following code shows an example:

$ cd wrappers/os/

$ ls
freertos  nos  nucleus  ubuntu

wrappers/os$ cp -rf ubuntu arm-linux

wrappers/os$ rm -f arm-linux/HAL_UART_linux.c

wrappers/os$ ls
arm-linux freertos  nos  nucleus  ubuntu

wrappers/os$ tree -A arm-linux/
arm-linux/
+-- HAL_AWSS_linux.c
+-- HAL_Crypt_Linux.c
+-- HAL_FS_Linux.c
+-- HAL_KV_linux.c
+-- HAL_OS_linux.c
+-- HAL_TCP_linux.c
+-- HAL_UDP_linux.c
            

Enable the previously disabled compilation switch

$ vim tools/board/config.arm-linux.demo

CONFIG_ENV_CFLAGS = \
    -D_PLATFORM_IS_LINUX_ \
    -Wall\
    -DNO_EXECUTABLES

CONFIG_ENV_LDFLAGS = \
    -lpthread -lrt

OVERRIDE_CC = arm-linux-gnueabihf-gcc
OVERRIDE_AR = arm-linux-gnueabihf-ar
OVERRIDE_LD = arm-linux-gnueabihf-ld

# CONFIG_wrappers :=
          

A # symbol before CONFIG_wrappers := comments out the line, which includes wrappers in the compilation process.

Try to cross-compile the copied HAL code

$ make reconfig

SELECT A CONFIGURATION:

1) config.alios.mk3080
2) config.arm-linux.demo
3) config.ubuntu.x86

#? 2

SELECTED CONFIGURATION:

VENDOR :   arm-linux
MODEL  :   demo

...


$ make
            

The wrappers/os/arm-linux/*.c files are compiled successfully, and the libiot_hal.a file is generated in the arm-linux format.

Cross-compile the sample program

  • Now that you have libiot_hal.a, libiot_tls.a, and libiot_sdk.a, you can cross-compile the sample program executable and run it on the target embedded hardware development board.

  • Remove the -DNO_EXECUTABLES switch from the config.arm-linux.demo file to compile the sample source code in the */examples/ folder.

  • When you remove the -DNO_EXECUTABLES switch, also remove the '' after -Wall on the preceding line.

The modified config.arm-linux.demo file is as follows.


$ vi tools/board/config.arm-linux.demo

CONFIG_ENV_CFLAGS = \
    -D_PLATFORM_IS_LINUX_ \
    -Wall

CONFIG_ENV_LDFLAGS = \
    -lpthread -lrt

OVERRIDE_CC = arm-linux-gnueabihf-gcc
OVERRIDE_AR = arm-linux-gnueabihf-ar
OVERRIDE_LD = arm-linux-gnueabihf-ld

# CONFIG_wrappers :=
            

The -DNO_EXECUTABLES switch is removed from CONFIG_ENV_CFLAGS, and the sample executable program is now included in the compilation scope.

Reload the configuration file and cross-compile the executable program

$ make reconfig

$ make            

If the following compilation output is displayed, sample programs such as mqtt-example are successfully compiled and stored in the output/release/bin folder.

[LD] dev-sign-example                   <=  ...
[LD] mqtt-example                       <=  ...
[LD] linkkit-example-solo               <=  ...

$ cd output/release/bin/

$ ls
dev-sign-example  linkkit-example-solo  mqtt-example

$ file *

dev-sign-example:     ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked ...

linkkit-example-solo: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked ...

mqtt-example:         ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), dynamically linked ...
            

You can use the file command to check if the executable program is cross-compiled for the arm-linux architecture.

Run the sample program

You can use a method such as SCP or TFTP to copy the sample program, such as mqtt-example, to your target development board to run and debug it.

  • If the sample program runs on the target board as it does on Ubuntu, the HAL code in the wrappers/os/arm-linux folder is correct.

  • If the sample program runs but behaves differently than on Ubuntu, focus on modifying and debugging the HAL implementation.

  • The HAL code in the wrappers/os/arm-linux folder was copied from the Ubuntu host and may not be suitable for arm-linux.

Repeat these steps until the development of libiot_hal.a is complete and correct.