SLAU646F September   2015  – June 2020

 

  1.   Read This First
    1.     How to Use This User's Guide
    2.     Related Documentation
    3.     If You Need Assistance
    4.     Trademarks
  2. 1Introduction
  3. 2Installing MSP430 GCC Toolchain
    1. 2.1 Installing MSP430 GCC in CCS Releases Before v7.2
    2. 2.2 Installing MSP430 GCC as Stand-Alone Package
  4. 3Using MSP430 GCC Within CCS
    1. 3.1 Create New Project
    2. 3.2 Debug Using MSP-FET, MSPFET430UIF, eZ-FET, eZ430
    3. 3.3 Build Options for MSP430 GCC
      1. 3.3.1  GNU Compiler
      2. 3.3.2  GNU Compiler: Runtime
      3. 3.3.3  GNU Compiler: Symbols
      4. 3.3.4  GNU Compiler: Directories
      5. 3.3.5  GNU Compiler: Optimization
      6. 3.3.6  GNU Compiler: Preprocessor
      7. 3.3.7  GNU Compiler: Assembler
      8. 3.3.8  GNU Compiler: Debugging
      9. 3.3.9  GNU Compiler: Diagnostic Options
      10. 3.3.10 GNU Compiler: Miscellaneous
      11. 3.3.11 GNU Linker
      12. 3.3.12 GNU Linker: Basic
      13. 3.3.13 GNU Linker: Libraries
      14. 3.3.14 GNU Linker: Symbols
      15. 3.3.15 GNU Linker: Miscellaneous
      16. 3.3.16 GNU Objcopy Utility
    4. 3.4 CCS Compared to MSP430 GCC
  5. 4MSP430 GCC Stand-Alone Package
    1. 4.1 MSP430 GCC Stand-Alone Package Folder Structure
    2. 4.2 Package Content
    3. 4.3 MSP430 GCC Options
    4. 4.4 MSP430 Built-in Functions
    5. 4.5 Using MSP430 GCC Support Files
    6. 4.6 Quick Start: Blink the LED
      1. 4.6.1 Building with a Makefile
      2. 4.6.2 Building Manually with gcc
      3. 4.6.3 Debugging
        1. 4.6.3.1 Starting GDB Agent
          1. 4.6.3.1.1 Using the GUI
          2. 4.6.3.1.2 Using the Command Line
        2. 4.6.3.2 Debugging With GDB
          1. 4.6.3.2.1 Running a Program in the Debugger
          2. 4.6.3.2.2 Setting a Breakpoint
          3. 4.6.3.2.3 Single Stepping
          4. 4.6.3.2.4 Stopping or Interrupting a Running Program
      4. 4.6.4 Creating a New Project
    7. 4.7 GDB Settings
      1. 4.7.1 Console Application
      2. 4.7.2 Optional Parameters for msp430.dat
      3. 4.7.3 GUI Application
      4. 4.7.4 Attaching the Debugger
      5. 4.7.5 Configuring the Target Voltage
      6. 4.7.6 Resetting the Target
      7. 4.7.7 Halting the Target
  6. 5MSP430 GCC Features
    1. 5.1 C/C++ Attributes
      1. 5.1.1 GCC Function Attribute Support
      2. 5.1.2 GCC Data Attribute Support
      3. 5.1.3 GCC Section Attribute Support
    2. 5.2 Hints for Reducing the Size of MSP430 GCC Programs
      1. 5.2.1 The -mtiny-printf Option
      2. 5.2.2 The -ffunction-sections and -fdata-sections Options
      3. 5.2.3 Making Large Programs Fit Across Upper and Lower Memory
      4. 5.2.4 NOP Instructions Surrounding Interrupt State Changes
    3. 5.3 C Runtime Library (CRT) Startup Behavior
    4. 5.4 Using printf with MSP430 GCC
    5. 5.5 Link-time Optimization (LTO)
    6. 5.6 The __int20 Type and Pointers in the Large Memory Model
  7. 6Building MSP430 GCC From Sources
    1. 6.1 Required Tools
    2. 6.2 Building MSP430 GCC (Mitto Systems Limited)
      1. 6.2.1 Building a Native MSP430 GCC Toolchain
      2. 6.2.2 Building the MSP430 GCC Toolchain for Windows
    3. 6.3 Building MSP430 GCC Stand-Alone Full Package
  8. 7MSP430 GCC and MSPGCC
    1. 7.1 Calling Convention
    2. 7.2 Other Portions of the ABI
  9. 8Appendix
    1. 8.1 GCC Intrinsic Support
    2. 8.2 NOP Instructions Required Between Interrupt State Changes
  10. 9References
  11.   Revision History

4.3 MSP430 GCC Options

The GNU compiler, assembler, and linker in the MSP430 GCC toolchain support the target-specific options listed in Table 4-2, Table 4-3, and Table 4-4, in addition to the standard options. For the full list of options for the GNU compiler, refer to the GCC online documentation. For the full list of options for the GNU assembler (gas) and linker (ld), refer to the GNU binutils online documentation. The manifest distributed with the toolchain specifies the version numbers of each of the components.

Table 4-2 MSP430 GCC Command Options
Option Description
-masm-hex This option forces assembly output to always use hex constants. Normally such constants are signed decimals, but this option is available for test suite or aesthetic purposes.
-mcode-region=
-mdata-region=		 These options change the behavior of the compiler and linker. The names of function and data sections are modified so that they will be placed in a specific way across the upper and lower memory regions, according to the rules in the linker script. These options have no effect unless -mlarge is also passed. Possible values are:
  • upper
    • The compiler adds the “.upper” prefix to section names.
    • The linker adds the “.upper” prefix to all section names that do not already have a prefix.
  • either
    • The compiler adds the “.either” prefix to section names.
    • The linker adds the “.either” prefix to all section names that do not already have a prefix.
    • The linker places “.either” sections in the lower memory region. If the lower memory region overflows, the linker shuffles sections between the upper and lower memory regions to try to get the program to fit.
  • lower
    • Neither the compiler nor the linker adds the “.lower” prefix unless the
      -muse-lower-region-prefix option is also passed.
    • For -mdata-region=lower, the compiler assumes data is in the lower region of memory (in the 16-bit address range below address 0x10000), so MSP430 instructions can be generated to handle data. For other values passed to
      -mdata-region, the compiler assumes data could be in the entire 20-bit address range, so MSP430X instructions must be used to handle data. This results in increased code size compared to -mdata-region=lower.
    • Object files compiled with -mdata-region=lower cannot be linked with object files compiled with a different -mdata-region value.
  • none
    • Neither the compiler nor the linker makes any changes to section names.

The default settings for these options are: -mdata-region=lower and -mcode-region=none.

-mhwmult= This option describes the type of hardware multiply supported by the target.

Accepted values:

  • 'none' for no hardware multiply
  • '16bit' for the original 16-bit-only multiply supported by early MCUs
  • '32bit' for the 16/32-bit multiply supported by later MCUs
  • 'f5series' for the 16/32-bit multiply supported by F5-series MCUs.
  • 'auto' can also be given. This tells GCC to deduce the hardware multiply support based upon the MCU name provided by the '-mmcu' option.

If no -mmcu option is specified, then no hardware multiply support is assumed. 'auto' is the default setting.

Hardware multiplies are normally performed by calling a library routine. This saves space in the generated code. When compiling at -O3 or higher, however, the hardware multiplier is invoked inline. This makes for larger but faster code.

The hardware multiply routines disable interrupts while running and restore the previous interrupt state when they finish. This makes them safe to use inside interrupt handlers as well as in normal code.
-mdisable-device-warnings Disable warnings emitted when the devices.csv file cannot be found by the compiler.
-minrt This option is deprecated. The toolchain now dynamically decides which start up and initialization/termination functions are required.
-mlarge Use large-model addressing (20-bit pointers, 20-bit size_t). Small-model addressing is the default.
-mmax-inline-shift=<0,64> This option takes an integer between 0 and 64 inclusive. The value sets the maximum number of inline shift instructions to emit to perform a shift operation by a constant amount. If this value will be exceeded, an MSPABI helper function is used instead. The default value is 4.

This option affects only cases where a shift by multiple positions cannot be completed with a single instruction (for example, all shifts by more than one position on the MSP430 ISA). Shifts of a 32-bit value are at least twice as costly, so the value passed for this option is divided by 2 and the resulting value is used instead.

-mmcu= This option selects the MCU to target. This is used to create a C preprocessor symbol based upon the MCU name, converted to upper case and prefixed and postfixed with '__'. This in turn is used by the 'msp430.h' header file to select an MCU-specific supplementary header file.

The option also sets the ISA to use. If the MCU name is one that is known to only support the 430 ISA then that is selected, otherwise the 430X ISA is selected. A generic MCU name of 'msp430' can also be used to select the 430 ISA. Similarly, the generic 'msp430x' MCU name selects the 430X ISA.

In addition, an MCU-specific linker script is added to the linker command line. The script's name is the name of the MCU with '.ld' appended. Thus specifying '-mmcu=xxx' on the gcc command line defines the C preprocessor symbol __XXX__ and causes the linker to search for a script called 'xxx.ld'. This option is also passed on to the assembler.

Manually passing a linker script using the -T option prevents this linker script from being used automatically. To augment rather than displace this linker script, use the --script option to pass directly to the linker (-Wl,--script=).
-mrelax This option enables both assembler and linker relaxation, which are optimizations that modify the code that was emitted by the compiler. See the descriptions of the -mQ option for the assembler and --relax option for the linker for more information. By default, assembler relaxation is disabled, and linker relaxation is enabled.
-msilicon-errata=NAME[,NAME...] This option implements fixes for named silicon errata. Multiple silicon errata can be specified by multiple uses of the -msilicon-errata option or by including the errata names, separated by commas, on an individual -msilicon-errata option. Errata names currently recognized by the assembler are:

cpu4 = PUSH #4 and PUSH #8 need longer encodings on the MSP430. This errata is enabled by default; it cannot be disabled.

cpu8 = Do not set the SP to an odd value.

cpu11 = Do not update the SR and the PC in the same instruction.

cpu12 = Do not use the PC in a CMP or BIT instruction.

cpu13 = Do not use an arithmetic instruction to modify the SR.

cpu19 = Insert NOP after CPUOFF.
-msim This option links to the simulator runtime libraries and linker script. Overrides any scripts that would be selected by the '-mmcu=' option.
-msmall Use small-model addressing (16-bit pointers, 16-bit size_t). This is the default.
-msilicon-errata-warn=NAME[,NAME...] This option is similar to the -msilicon-errata option, except that instead of fixing the specified errata, a warning message is issued instead. This option can either be used with -msilicon-errata to generate messages whenever a problem is fixed, or used on its own to inspect code for potential problems.
-mtiny-printf This option links a reduced-size implementation of the printf() and puts() library functions. This reduced size implementation is not reentrant, so should be used with care in multi-threaded applications. Buffering of the string to be output has been removed from printf() and puts(), so user implementations of the system write() function must also implement buffering. The library implementation of write() that is included with MSP430 GCC does buffer the output string.
-muse-lower-region-prefix This option adds the ".lower" prefix to function or data section names when
-mdata-region=lower or -mcode-region=lower is passed.
-mwarn-mcu
-mno-warn-mcu		 This option enables or disables warnings about conflicts between the MCU name specified by the -mmcu option and the ISA set by the -mcpu option or the hardware multiply support set by the -mhwmult option. It also toggles warnings about unrecognized MCU names. This option is on by default.

Most assembler and linker options specific to MSP430 are passed automatically by the GCC wrapper, depending on the options passed to GCC itself. Table 4-3 and Table 4-4 list options that control behavior specific to the assembler and linker.

When passing an option to the assembler via the GCC wrapper (msp430-elf-gcc), the option must be prefixed with “ -Wa, ”. For example, to pass -mU to the assembler, you would pass -Wa,-mU to msp430-elf-gcc.

The assembler emits warnings when instructions to enable or disable interrupts are used without surrounding NOP instructions. See Section 8.2 for details. This behavior can be modified using the options in Table 4-3.

Table 4-3 MSP430 GCC Assembler Options
Option Description
-mn Insert NOPs around interrupt enable/disable instructions.
-mN Do not insert NOPs around interrupt enable/disable instructions (default).
-mQ Enable assembler relaxation. The assembler tries to replace some instructions with alternate versions that have smaller code sizes. This is disabled by default.
-mu Warn or insert NOP instructions (default) around an instruction that may change the interrupt enable state if it is not known how the state will change. Whether a warning is emitted or a NOP is inserted is dependent on which of the -m{N,n,Y,y} options are set.
-mU Do not warn or insert NOP instructions around an instruction that may change the interrupt enable state if it is not known how the state will change.
-my Warn about missing NOPs around interrupt enable/disable instructions (default).
-mY Do not warn about missing NOPs around interrupt enable/disable instructions.

When passing options to the linker via the GCC wrapper (msp430-elf-gcc), the option must be prefixed with “ -Wl, ”. For example, to pass --disable-sec-transformation to the linker, you would pass
-Wl,--disable-sec-transformation to msp430-elf-gcc.

Table 4-4 MSP430 GCC Linker Options
Option Description
--disable-sec-transformation Disable the transformation of section names in object files being linked, based on the
-mdata-region and -mcode-region options. For example, passing
“-mdata-region=either -Wl,--disable-sec-transformation” to msp430-elf-gcc instructs the compiler to add the “.either” prefix to data section names being compiled, but the linker will not add the “.either” prefix to any section names in the object files it is passed.
--relax --no-relax Enable or disable relaxation. The linker tries to replace some instructions with alternate versions that have smaller code sizes. Relaxation may grow short branch instructions that do not reach their target. Linker relaxation is enabled by default and cannot be disabled when linking executable files.
Table 4-5 MSP430 Objdump Options
Option Description
--symtab-meta Print the symbol meta-information entries from the .symtab_meta section of the specified ELF object or executable file.