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.
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
Add platform subdirectory name at below list for make pretty:
# Always pretty (e.g. for 'make pretty') these subdirectories.
PRETTY_SUBDIRS = \
cc2538 \
cc2650 \
efr32 \
nrf52840 \
simulation \
utils \
$(NULL)
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
.datasection 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 \