|
BSP430
20141115
Board Support Package for MSP430 microcontrollers
|
|
BSP430
20141115
Board Support Package for MSP430 microcontrollers
|
The BSP430 configuration structure is implemented using the standard C preprocessor.
Because the BSP430 infrastructure enables and disables features within separate object files based on the flags presented at the time the source file is compiled, it is critical that all object files in an application have consistent flag definitions.
Each header in BSP430 that does not include another BSP430 file includes the file bsp430/core.h. Subject to configBSP430_CORE_INCLUDE_BSP430_CONFIG_FILE, the first thing this file does is:
Unlike all other BSP430 headers, the bsp430_config.h file is not accessed with a path that places it within the BSP430 hierarchy, but is assumed to exist within the application source area. It is in this file that application-specific configuration information should be placed.
The application-specific configuration file should end with:
This file consults the existing definitions (e.g. BSP430_PLATFORM_EXP430G2 or BSP430_PLATFORM_CUSTOM) to identify a platform-specific configuration file, which it then includes. In that file any previous requests for specific features, such as configBSP430_TIMER_CCACLK, are translated to requests for the underlying peripheral supported on that platform.
Every header that specifies a configuration option or parameter sets a default for that option if no previously encountered header provides an alternative. Not all parameters may be overridden by previous definitions; see @defaulted.
All overridable feature and parameter values must be provided in a way that ensures all source files see the same value. In most cases, they will be specified in the application bsp430_config.h. For temporary settings to evaluate alternatives they may be set by passing flags to the compiler through the EXT_CPPFLAGS environment or make variable.
If an application wishes to use a peripheral or enable a particular feature such as a serial console, it specifies this by defining a macro to 1 (to enable) or 0 (to disable). The specific peripheral or feature is reflected in the macro name. These macros are annotated with @cppflag to indicate that their values must evaluate to true or false within the context of a C preprocessor expression. In most cases the controlling macro has a lower-case prefix config, further highlighting that it is used for configuration requests and does not indicate that the feature is actually available; see Use of Configuration-Dependent Information.
For example, to use the HPL interface to digital I/O port 1 it is necessary to define configBSP430_HPL_PORT1:
If the HAL interface is desired, that must be requested using:
The HAL interface will always depend on the corresponding HPL interface, but BSP430 will automatically enable the underlying capabilities by default, so you don't need to ask for them explicitly.
Features that are expected to be used commonly such as configBSP430_LED are enabled by default and may be explicitly disabled if they are unused, but most features including microcontroller peripheral are disabled by default and must be explicitly enabled. Failure to correctly enable a resource that your application depends on can result in either compile-time or link-time errors.
BSP430 allows control of all values that an application or platform might wish to override, from common ones like BSP430_CLOCK_NOMINAL_MCLK_HZ to low-level ones like BSP430_UPTIME_DELAY_CCIDX where platform capabilities may require use of the default resource be re-assigned to an application-specific purpose. All such parameters are given default values, and are annotated with @defaulted in their description to highlight that their values may be overridden.
The override mechanism is to simply define a preferred value in the application or platform bsp430_config.h, as:
As a general rule, an option configBSP430_FOO serves as an indication that an application or library function requests that the named feature be made available. It is not a guarantee that the feature could be provided. The documentation for feature request macros (configBSP430_FOO) will always identify the functional macro (BSP430_FOO) that confirms availability of the feature. When this general rule applies, application code should check BSP430_FOO to see whether the request made through configBSP430_FOO could be satisfied.
For example, configBSP430_TIMER_CCACLK requests a timer be assigned that supports capturing events when an ACLK-based timer tick occurs, but whether such a timer is available is dependent on whether the platform headers supply a definition for BSP430_TIMER_CCACLK_PERIPH_CPPID. In the documentation, there is an @affects link from configBSP430_TIMER_CCACLK to BSP430_TIMER_CCACLK_PERIPH_CPPID and a @dependency link in the reverse direction. (This is a complex example: for technical reasons involving dependency separation BSP430_TIMER_CCACLK_PERIPH_CPPID is provided within the bsp430_config.h hierarchy; it in turn determines the value of BSP430_TIMER_CCACLK which is defined only once <bsp430/periph/timer.h> has been included.)
In cases where the affected macro is a C preprocessor symbol it should be checked following the standard for those macros:
bsp430/platform.h should be the first BSP430-related include file in implementation files, so that both the configuration information obtained through bsp430/core.h and any platform-specific restrictions/overrides are available.
In other cases like configBSP430_HPL_PORT7 simple use of the feature (viz., reference to BSP430_HPL_PORT7) will produce a compile-time error if the requested feature is not available on the target, so it is generally not necessary to explicitly check for success.
Internally BSP430 checks functional presence macro definitions that are internal to the MCU-specific headers provided by Texas Instruments. In some cases, it may be desirable to detect whether a feature is present without hard-coding checks of those internal macros.
As an example, the Power Management Module is only available on certain 5xx/6xx family MCUs. Rather than attempting to detect that situation and conditionally including bsp430/periph/pmm.h, the module header will do this and define a macro BSP430_MODULE_PMM that has a non-zero value only if the module is available. Thus you may use:
Copyright 2012-2014, Peter A. Bigot
1.8.8
