Vendor-provided CMSIS headers. CMSIS defines standard names for exception handlers, struct data layouts for core and peripheral registers, standard "intrinsics" such as __disable_irq() and __WFI(), global variables like SystemCoreClock and functions like SystemCoreClockUpdate(). Most vendors readily supply the necessary headers, along with the documentation required to use them.

Toolchain support for weak symbols: This feature is used to provide default implementations for newlib's system interface as well as for all handlers supported by a processor's vector table. Vendor libraries and application object files are ordered so that the desired definition will supersede the weak definition when necessary.

Toolchain support for inline functions: For speed many functions are defined as static functions in headers, with a toolchain-specific BSPACM_CORE_INLINE or BSPACM_CORE_INLINE_FORCED annotation to ensure that the implementation is inlined.

Toolchain support for linker optimizations, including placing each function and data object in its own section (gcc -ffunction-sections and -fdata-sections), and eliminating unreferenced sections from the executable (gcc -Wl,-gc-sections).

The GNU make build tool.

CMSIS Infrastructure

CMSIS provides core header files for each Cortex-M architecture, as well as a standard for vendor-specific peripheral interfaces. It also defines the names for exception handlers and core support functions, and provides example implementations of startup and system initialization code for each architecture.

Where vendor-supplied CMSIS support is adequate the vendor files are used. In other situations CMSIS standard implementations direct from ARM are used.

Startup Infrastructure

BSPACM provides its own linker scripts and startup assembly files that derive from the ARM examples. These scripts are shared by all applications; customization is performed through BSPACM support for weak symbols and preprocessor flags. BSPACM changes to support this generality includes:

In the linker script device-specific memory regions are included from an external file, the location of which is provided by the DEVICE_LDSCRIPT_PATH in make.

In the startup source the vector table is described by including a device-specific template file which specifies the order and names of entries in the table.

In the startup source the vector table is initialized with weak definitions for all peripheral exception handlers. These may be replaced by the application by simply providing a non-weak definition using the CMSIS standard name for the exception handler (e.g., SysTick_Handler and UART0_IRQHandler, not SysTickIntHandler or UARTIntHandler).

By default, the vector table gets a unique weak definition for each entry, allowing unexpected IRQs to be identified. A small amount of space can be regained by overriding the value of __STARTUP_USE_UNIQUE_DEFAULT_HANDLER when the startup files are assembled.

System Infrastructure

CMSIS specifies a number of standard variables and functions that are to be provided by the vendor. Among these are:

SystemCoreClock is a uint32_t global which represents the processor speed in Hertz.

SystemInit() is a function that is called within the startup code to initialize the clocks (and SystemCoreClock) prior to invoking constructors and calling main().

SystemCoreClockUpdate() is a function that reads the clock peripheral configuration and updates the value of SystemCoreClock.

BSPACM is written with the expectation that these and similar standard functions and data objects exist and may be used.

At this time Texas Instruments does not support CMSIS, so a minimum generic system_TM4C.c is provided in the TM4C device series area.

Although Silicon Labs (Energy Micro) does provide a CMSIS startup file, its SystemInit() fails to initialize SystemCoreClock. At this time, BSPACM has not chosen to fix this error locally.

Target System Model

BSPACM targets systems designed around ARM Cortex-M series microprocessors. The intent is that all architecture variations within Cortex-M will be supported: at the time of writing that includes Cortex-M0+, Cortex-M3, and Cortex-M4 devices.

To share implementation and concepts among the widest possible range of target platforms, the following taxonomy is used:

A board consists of a specific Cortex-M device along with supporting hardware such as LEDs, sensors, debug interfaces, etc. Examples of boards are the Texas Instruments Tiva Launchpad and Silicon Labs EFM32 Giant Gecko Starter Kit. Part of the description of a board includes its device.

A device is a specific Cortex-M microcontroller, with its peripherals, FLASH and SRAM sizes, etc. Examples of devices are the TM4C123GH6PM and the EFM32GG990F1024. Each device is an instance within a vendor device line.

A device line is the next generalization of Cortex-M microcontrollers from a specific vendor. These comprise the set of devices that share common properties, such as Cortex-M architecture and the set of supported peripherals (some of which may not be present on some devices). Examples of device lines are the TM4C123 and EFM32GG "Giant Gecko". A device line is a refinement of a device series.

A device series is the highest level of abstraction supported by BSPACM for aggregation of related microcontrollers. These comprise the set of device lines that share common properties, such as vendor and overall purpose. Examples of device series are the TM4C Tiva C Series and EFM32 Energy Micro product lines.

A BSPACM application is built for a specific board, by providing the BOARD make variable when compiling it. All further information not explicitly provided by the application is derived from the board identification.

Directory Structure

The structure of the BSPACM workspace reflects the taxonomy in Target System Model. You can browse the current directory structure through the BSPACM github project page.

The board directory contains subdirectories for each supported board. The manufacturer's preferred name for the board, in lower case, should be used as the subdirectory name.

The device directory contains a series of subdirectories: each series contains subdirectories for each of its lines, which in turn contain subdirectories for each of its devices. Again the manufacturer's preferred name, in lower case, is used for each directory.

the include directory contains a hierarchy of C header files that will be located using angle-bracket include directives in C sources. The top level contains only a subdirectory bspacm, ensuring that each included file is associated with the BSPACM namespace and does not conflict with vendor or third-party libraries.

the src directory contains a hierarchy of C implementation files. Source directories are further refined to reflect the include files for which they provide implementation.

the toolchain directory contains material specific to the compiler/linker toolchain, using the CMSIS standard toolchain identifiers GCC (GNU Tools for ARM Embedded Processors) and the unsupported toolchains ARM, G++, and IAR. Each toolchain directory will contain material such as linker scripts and CMSIS-standard assembly language startup sources for each Cortex-M architecture.

The include and src directories are reproduced as necessary within the board and device hierarchies so that specific implementations are associated with the most general level to which they apply.

Other directories such as examples, doc, and maintainer are either self-explanatory or not relevant to most users.

Include File Hierarchies

All header files in BSPACM are placed so that they are included with the angle-bracket version of C's #include preprocessor directive with the leading bspacm enforcing placement in a namespace.

<bspacm/core.h> is the primary entry point to BSPACM, bringing in the device-specific files and key macros and inline functions.

<bspacm/config.h> provides declarations for peripherals and other functionality available on the board for which the application is built. It in turn includes the header <bspacm/appconf.h> which may be overridden on a per-application basis, but which is provided by the board-specific hierarchy when this is unnecessary.

The bspacm/utility hierarchy provides common interface to non-peripheral capabilities, such as <bspacm/utility/led.h>.

The bspacm/periph hierarchy provides common interface to peripherals such as UARTs, SPI, I2C, timers, real-time clocks, etc.

The bspacm/newlib hierarchy provides access to BSPACM's Interfacing with newlib (libc) support infrastructure.

Other directories and files may be added over time.

Templates and Internal Include Files

The bspacm/internal hierarchy provides header files that should not be made visible in public API for various reasons. Internal header files named something.inc are template files that are included into headers or implementation files, possibly multiple times, to specialize code or data structures for specific purposes, such as defining a standard IRQHandler function or filling out a device description table.

Include Search Order

Multiple include/bspacm hierarchies may combine to produce the environment used for a particular application. The application may add its own hierarchy first, but the core make infrastructure will also search the board, device, device line, and device series (in that order) before falling back to the generic hierarchy. Device-specific template (.inc) and header files are found within the extended set of hierarchies.

Source File Hierarchies

Implementation files are placed into subdirectories of src corresponding to the header file that they implement.

As with include files, there are specific source directories available at the board, device, device line, and device series layers as well as the application. Unlike include files, there is no ordered searching within these directories: the full path to each implementation file that contributes to an application are added to the list of source files by one of the Makefile components. See Makefile Architecture.

Board and Device Hierarchies

Board Hierarchy

The board hiearchy contains subdirectories for each supported board, identified by the manufacturer's preferred name, in lower case. This identifier is also used as the value of the BOARD variable in the Makefile architecture.

Within each board directory should be the following files:

Makefile.board

Set the board identifier in the BOARD make variable. Then include the appropriate Makefile.device from the device hierarchy, with an absolute path generally beginning with $(BSPACM_ROOT).

Any other board- or device-specific make variables may also be set. Generally these should begin with the prefix BOARD_. For example, BOARD_STYLE is used in EFM32 boards to distinguish DK (development kit) from STK (starter kit).

README

Contain salient information about the board: a link to manufacturer's home page, basic characteristics like flash/RAM sizes, pin assignments for LEDs, buttons, and console UART, and whatever else might be useful. Don't repeat information that can easily be found elsewhere; don't make the reader go hunting for the most basic information.

This file may have a suffix such as .md (Markdown), .rst (reStructuredText), or .txt (plain text) identifying the text markup style used within the file.

include/bspacm/appconf.h

A header file included by <bspacm/config.h> that provides declarations related for common peripherals such as the default UART device. It may be copied to the application source directory and modified to meet specific application needs.

The contents of this file should be synchronized with the corresponding src/periph_config.c file.

src/periph_config.c

An implementation file that provides definitions for common peripherals such as the default UART device. The PERIPH_CONFIG_SRC variable used by Makefile Architecture defaults to the version supplied here, but it may be overridden to provide an application-specific implementation.

include/bspacm/internal/board/led.inc

A template file included by device-specific header and implementation files to describe the LEDs that are available on the board.

Device Hierarchy

The device hierarchy contains (recursively) information on each device series, line, and specific device supported in the baseline BSPACM infrastructure. At the top level is the device series, identified by the manufacturer's preferred name.

Each layer in the hierarchy has include and src subdirectories that provide interface and implementation specific to that layer. In addition, the following files are found at various levels in this hierarchy:

Makefile.device

This file is necessarily found at the device layer of the hierarchy (e.g., device/efm32/efm32gg/efm32gg990f256/Makefile.device).

Set the device identifier in the DEVICE make variable. Provide definitions for TARGET_MFLAGS, TARGET_CPPFLAGS, ARM_PROCESSOR, and other variables that cannot be defined at the line or series levels.

End by including the appropriate Makefile.line from the device hierarchy, with an absolute path generally beginning with $(BSPACM_ROOT).

Makefile.line

This file is necessarily found at the line layer of the hierarchy (e.g., device/efm32/efm32gg/Makefile.line).

Set the device line identifier in the DEVICE_LINE make variable. Provide definitions for TARGET_MFLAGS, TARGET_CPPFLAGS, ARM_PROCESSOR, and other variables that cannot be defined at the series level.

Then include the appropriate Makefile.series from the device hierarchy, with an absolute path generally beginning with $(BSPACM_ROOT).

Makefile.series

This file is necessarily found at the series layer of the hierarchy (e.g., device/efm32/Makefile.series).

Set the device line identifier in the DEVICE_LINE make variable. Provide defaults for TARGET_MFLAGS, TARGET_CPPFLAGS, ARM_PROCESSOR, and other variables that have not already been defined.

Define BOARD_LIBVENDOR_A to the archive file for vendor libraries such as TivaWare or emlib. Provide the necessary make rules to build that archive.

Append to BOARD_LIBBSPACM_SRC any device-specific implementation files.

Define a command DO_FLASH_IMAGE which takes a single argument that is the name of an ARM binary and programs it into the board.

memory.ld

A file for the GCC toolchain describing the memory regions, i.e. size of flash and ram available on the device. The file will be included into the generic linker script for the processor.

Generally this is found at the device (deepest) level. If it is not placed there, the DEVICE_LDSCRIPT_PATH make variable must be defined to instruct the linker where it can be found.

include/bspacm/internal/device/vector_table.inc

A file describing the entries in the interrupt vector table for the device, in a form suitable for inclusion into linker scripts and/or startup sources. The file wraps the standard names, in order, with a macro that is expanded in context to create a CMSIS standard *_IRQHandler definition or reference.

Generally this is found at the line level.

include/bspacm/internal/periph

A directory containing template files included by device-specific header and implementation files to declare or define specific peripherals. The files should have a base name corresponding to the peripheral; e.g. usart.inc or leuart.inc.

Makefile Architecture

BSPACM uses GNU make features to simplify the build process at the cost of increased maintainer complexity.

Each application has its own Makefile which initializes the SRC variable to the list of application-specific sources, then includes $(BSPACM_ROOT)/make/Makefile.common. That file then includes board and device specific files, constructs compiler and linker arguments, and provides the rules necessary to build the libraries, object files, and application itself.

BSPACM's make infrastructure preprocesses source files to determine dependencies, and automatically rebuilds all files that are affected by source code changes.

Object files specific to an application, including the startup and system modules from CMSIS, are compiled and stored in the current directory alongside the Makefile. Object files and libraries that should be independent of the application are stored in the BSPACM board directory.

Standard targets include:

app.axf builds the application into ELF format
install downloads the application to the board, after building it
clean removes all application-specific build files. This should be done when rebuilding an application for a new board, as the object files may have invalid references.
realclean removes all board-specific build files. This may be necessary when changing code-generation and link-related toolchain flags.

Variables Used in Building Applications

All make variables should be documented within make/Makefile.common and the reader is directed there for full details. Only the most commonly specified variables are described here. See the various example applications to learn more.

SRC

This variable contains the list of source code files, exclusive of vendor and BSPACM libraries, that contribute to an application. C (.c), C++ (.cc), and assembly-with-c-preprocessor (.S) sources are recognized, and make build rules dynamically created to build the object files and place them in the current directory.

BOARD

This variable must be set to identify the target for the application. The value is the board identifier as specified by the corresponding subdirectory of $(BSPACM_ROOT)/boards

Table of Contents