Set Up the Build Environment

To promote free and open development, OpenThread uses GNU Autotools in the build toolchain. Currently, this toolchain is required for porting OpenThread to a new hardware platform.

Other build toolchains might be supported in the future, but are currently not in the scope of this porting guide.

Note: In all path and code examples in this porting guide, always replace platform-name with the name of your new platform example. Most of the examples in the guide use a platform name of efr32.

GNU Autoconf

The Autoconf script contains the basic system configuration options, including specific platform-relative macro definitions. These macros can be exposed for conditional compilation in other Makefiles during the pre-compiling phase.

The OpenThread Autoconf script is located at: /openthread/configure.ac

Platform example name

In the AC_ARG_WITH(examples ...) macro, add the new hardware platform example name. The name should be added in alphabetical order.

Example:

AC_ARG_WITH(examples,
    [AS_HELP_STRING([--with-examples=TARGET],
        [Specify the examples from one of: none, simulation, cc2538, cc2650, efr32, nrf52840 @<:@default=none@:>@.])],
    [
        case "${with_examples}" in
        none)
            ;;
        simulation|cc2538|cc2650|efr32|nrf52840)
            if test ${enable_posix_app} = "yes"; then
                AC_MSG_ERROR([--with-examples must be none when POSIX apps are enabled by --enable-posix-app])
            fi
            ;;
        *)
            AC_MSG_ERROR([Invalid value ${with_examples} for --with-examples])
            ;;
        esac
    ],
    [with_examples=none])

Platform-specific C preprocessor symbol

Define a platform-specific C preprocessor symbol for the platform example and expose it.

The platform-specific C preprocessor symbol is exposed at include/openthread-config.h. By including the symbol in this header file, we can leverage it in our source code for preprocessor conditional compilation cases.

Example:

case ${with_examples} in
 
    ...
 
    efr32)
        OPENTHREAD_EXAMPLES_EFR32=1
        AC_DEFINE_UNQUOTED([OPENTHREAD_EXAMPLES_EFR32],[${OPENTHREAD_EXAMPLES_EFR32}],[Define to 1 if you want to use efr32 examples])
        ;;
 
...
 
esac
 
...
 
AC_SUBST(OPENTHREAD_EXAMPLES_EFR32)
AM_CONDITIONAL([OPENTHREAD_EXAMPLES_EFR32], [test "${OPENTHREAD_EXAMPLES}" = "efr32"])

Makefile output directory

In the AC_CONFIG_FILES macro, add a Makefile output directory for the platform example.

Example:

AC_CONFIG_FILES ([
       examples/platforms/efr32/Makefile
])

GNU Automake

Create and modify Automake files to support the new platform example.

The following platform-specific Automake files need to be created:

/openthread/examples/Makefile-platform-name
/openthread/examples/platforms/platform-name/Makefile.am
/openthread/examples/platforms/platform-name/Makefile.platform.am

See /examples for sample implementations of these files.

The following Automake files also need to be updated with your platform information:

Linker script configuration

The GNU Linker script describes how to map all sections in the input files (.o "object" files generated by the GNU Compiler Collection (GCC)) to the final output file (for example, .elf). It also determines the storage location of each segment of an executable program, as well as the entry address. The platform-specific linker script is often provided with the platform's BSP.

Configure the ld tool to point to the platform-specific linker script using the -T option of the LDADD_COMMON variable.

Create /openthread/examples/platforms/platform-name/Makefile.platform.am and point the new platform to its linker script:

if OPENTHREAD_EXAMPLES_EFR32
    LDADD_COMMON                                                      += \
    $(top_builddir)/examples/platforms/efr32/libopenthread-efr32.a       \
    $(top_srcdir)/third_party/silabs/gecko_sdk_suite/v1.0/platform/radio/rail_lib/autogen/librail_release/librail_efr32xg12_gcc_release.a \
    $(NULL)
 
LDFLAGS_COMMON                                                        += \
    -T $(top_srcdir)/third_party/silabs/gecko_sdk_suite/v1.0/platform/Device/SiliconLabs/EFR32MG12P/Source/GCC/efr32mg12p.ld \
    $(NULL)
endif # OPENTHREAD_EXAMPLES_EFR32

Add the platform's linker script configuration to the /openthread/examples/platforms/Makefile.platform.am utility Makefile:

if OPENTHREAD_EXAMPLES_EFR32
include $(top_srcdir)/examples/platforms/efr32/Makefile.platform.am
endif

Subdirectory configuration

Modify /openthread/examples/platforms/Makefile.am to configure the package subdirectories for the new platform example.

Add the platform subdirectory name in the list for make dist, in alphabetical order:

# Always package (e.g. for 'make dist') these subdirectories.
 
DIST_SUBDIRS                           = \
    cc2538                               \
    cc2650                               \
    efr32                                \
    nrf52840                             \
    simulation                           \
    utils                                \
    $(NULL)

Append platform subdirectory name to the SUBDIRS variable:

# Always build (e.g. for 'make all') these subdirectories.
 
if OPENTHREAD_EXAMPLES_EFR32
    SUBDIRS                           += efr32
endif

Toolchain startup code

Toolchain startup code is often provided along with the platform's BSP. This code typically:

Implements the entry function (Reset_Handler) of the executable program
Defines the interrupt vector table
Initializes the Heap and Stack
Copies the .data section from non-volatile memory to RAM
Jumps to the application main function to execute the application logic

The startup code (C or assembly source code) must be added to the platform-specific Makefile.am, otherwise some key variables used in the linker script cannot be quoted correctly:

/openthread/examples/platforms/platform-name/Makefile.am

Example:

libopenthread_efr32_a_SOURCES   =  \
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/hardware/kit/common/bsp/bsp_bcc.c \
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/hardware/kit/common/bsp/bsp_stk.c \
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/platform/Device/SiliconLabs/EFR32MG12P/Source/system_efr32mg12p.c \
@top_builddir@/third_party/silabs/gecko_sdk_suite/v1.0/platform/Device/SiliconLabs/EFR32MG12P/Source/GCC/startup_efr32mg12p.c \

Overview

Implement Platform Abstraction Layer APIs