MSP430 Assembly
Language Tools
v15.9.0.STS User's Guide
SLAU131 - REVISED SEPTEMBER, 2015
13 Sharing C/C++ Header Files With Assembly Source
You can use the .cdecls assembler directive to share C headers containing declarations and prototypes between C and assembly code. Any legal C/C++ can be used in a .cdecls block and the C/C++ declarations will cause suitable assembly to be generated automatically, allowing you to reference the C/C++ constructs in assembly code.
13.1 Overview of the .cdecls Directive
The .cdecls directive allows programmers in mixed assembly and C/C++ environments to share C headers containing declarations and prototypes between the C and assembly code. Any legal C/C++ can be used in a .cdecls block and the C/C++ declarations will cause suitable assembly to be generated automatically. This allows the programmer to reference the C/C++ constructs in assembly code — calling functions, allocating space, and accessing structure members — using the equivalent assembly mechanisms. While function and variable definitions are ignored, most common C/C++ elements are converted to assembly: enumerations, (non function-like) macros, function and variable prototypes, structures, and unions.
See the .cdecls directive description for details on the syntax of the .cdecls assembler directive.
The .cdecls directive can appear anywhere in an assembly source file, and can occur multiple times within a file. However, the C/C++ environment created by one .cdecls is not inherited by a later .cdecls; the C/C++ environment starts over for each .cdecls instance.
For example, the following code causes the warning to be issued:
.cdecls C,NOLIST
%{
#define ASMTEST 1
%}
.cdecls C,NOLIST
%{
#ifndef ASMTEST
#warn "ASMTEST not defined!" /* will be issued */
#endif
%}
Therefore, a typical use of the .cdecls block is expected to be a single usage near the beginning of the assembly source file, in which all necessary C/C++ header files are included.
Use the compiler --include_path=path options to specify additional include file paths needed for the header files used in assembly, as you would when compiling C files.
Any C/C++ errors or warnings generated by the code of the .cdecls are emitted as they normally would for the C/C++ source code. C/C++ errors cause the directive to fail, and any resulting converted assembly is not included.
C/C++ constructs that cannot be converted, such as function-like macros or variable definitions, cause a comment to be output to the converted assembly file. For example:
; ASM HEADER WARNING - variable definition 'ABCD' ignored
The prefix ASM HEADER WARNING appears at the beginning of each message. To see the warnings, either the WARN parameter needs to be specified so the messages are displayed on STDERR, or else the LIST parameter needs to be specified so the warnings appear in the listing file, if any.
Finally, note that the converted assembly code does not appear in the same order as the original C/C++ source code and C/C++ constructs may be simplified to a normalized form during the conversion process, but this should not affect their final usage.
13.2 Notes on C/C++ Conversions
The following sections describe C and C++ conversion elements that you need to be aware of when sharing header files with assembly source.
13.2.1 Comments
Comments are consumed entirely at the C level, and do not appear in the resulting converted assembly file.
13.2.2 Conditional Compilation (#if/#else/#ifdef/etc.)
Conditional compilation is handled entirely at the C level during the conversion step. Define any necessary macros either on the command line (using the compiler --define=name=value option) or within a .cdecls block using #define. The #if, #ifdef, etc. C/C++ directives are not converted to assembly .if, .else, .elseif, and .endif directives.
13.2.3 Pragmas
Pragmas found in the C/C++ source code cause a warning to be generated as they are not converted. They have no other effect on the resulting assembly file. See the .cdecls topic for the WARN and NOWARN parameter discussion for where these warnings are created.
13.2.4 The #error and #warning Directives
These preprocessor directives are handled completely by the compiler during the parsing step of conversion. If one of these directives is encountered, the appropriate error or warning message is emitted. These directives are not converted to .emsg or .wmsg in the assembly output.
13.2.5 Predefined symbol _ _ASM_HEADER_ _
The C/C++ macro _ _ASM_HEADER_ _ is defined in the compiler while processing code within .cdecls. This allows you to make changes in your code, such as not compiling definitions, during the .cdecls processing.
NOTE
Be Careful With the _ _ASM_HEADER_ _ MacroYou must be very careful not to use this macro to introduce any changes in the code that could result in inconsistencies between the code processed while compiling the C/C++ source and while converting to assembly.
13.2.6 Usage Within C/C++ asm( ) Statements
The .cdecls directive is not allowed within C/C++ asm( ) statements and will cause an error to be generated.
13.2.7 The #include Directive
The C/C++ #include preprocessor directive is handled transparently by the compiler during the conversion step. Such #includes can be nested as deeply as desired as in C/C++ source. The assembly directives .include and .copy are not used or needed within a .cdecls. Use the command line --include_path option to specify additional paths to be searched for included files, as you would for C compilation.
13.2.8 Conversion of #define Macros
Only object-like macros are converted to assembly. Function-like macros have no assembly representation and so cannot be converted. Pre-defined and built-in C/C++ macros are not converted to assembly (i.e., __FILE__, __TIME__, __TI_COMPILER_VERSION__, etc.). For example, this code is converted to assembly because it is an object-like macro:
#define NAME Charley
This code is not converted to assembly because it is a function-like macro:
#define MAX(x,y) (x>y ? x : y)
Some macros, while they are converted, have no functional use in the containing assembly file. For example, the following results in the assembly substitution symbol FOREVER being set to the value while(1), although this has no useful use in assembly because while(1) is not legal assembly code.
#define FOREVER while(1)
Macro values are not interpreted as they are converted. For example, the following results in the assembler substitution symbol OFFSET being set to the literal string value 5+12 and not the value 17. This happens because the semantics of the C/C++ language require that macros are evaluated in context and not when they are parsed.
#define OFFSET 5+12
Because macros in C/C++ are evaluated in their usage context, C/C++ printf escape sequences such as \n are not converted to a single character in the converted assembly macro. See Section 13.2.11 for suggestions on how to use C/C++ macro strings.
Macros are converted using the .define directive (see Section 13.4.2), which functions similarly to the .asg assembler directive. The exception is that .define disallows redefinitions of register symbols and mnemonics to prevent the conversion from corrupting the basic assembly environment. To remove a macro from the assembly scope, .undef can be used following the .cdecls that defines it (see Section 13.4.3).
The macro functionality of # (stringize operator) is only useful within functional macros. Since functional macros are not supported by this process, # is not supported either. The concatenation operator ## is only useful in a functional context, but can be used degenerately to concatenate two strings and so it is supported in that context.
13.2.9 The #undef Directive
Symbols undefined using the #undef directive before the end of the .cdecls are not converted to assembly.
13.2.10 Enumerations
Enumeration members are converted to .enum elements in assembly. For example:
enum state { ACTIVE=0x10, SLEEPING=0x01, INTERRUPT=0x100, POWEROFF, LAST};
is converted to the following assembly code:
state .enum
ACTIVE .emember 16
SLEEPING .emember 1
NTERRUPT .emember 256
POWEROFF .emember 257
LAST .emember 258
.endenum
The members are used via the pseudo-scoping created by the .enum directive.
The usage is similar to that for accessing structure members, enum_name.member.
This pseudo-scoping is used to prevent enumeration member names from corrupting other symbols within the assembly environment.
13.2.11 C Strings
Because C string escapes such as \n and \t are not converted to hex characters 0x0A and 0x09 until their use in a string constant in a C/C++ program, C macros whose values are strings cannot be represented as expected in assembly substitution symbols. For example:
#define MSG "\tHI\n"
becomes, in assembly:
.define """\tHI\n""",MSG ; 6 quoted characters! not 5!
When used in a C string context, you expect this statement to be converted to 5 characters (tab, H, I, newline, NULL), but the .string assembler directive does not know how to perform the C escape conversions.
You can use the .cstring directive to cause the escape sequences and NULL termination to be properly handled as they would in C/C++. Using the above symbol MSG with a .cstring directive results in 5 characters of memory being allocated, the same characters as would result if used in a C/C++ strong context. (See Section 13.4.7 for the .cstring directive syntax.)
13.2.12 C/C++ Built-In Functions
The C/C++ built-in functions, such as sizeof( ), are not translated to their assembly counterparts, if any, if they are used in macros. Also, their C expression values are not inserted into the resulting assembly macro because macros are evaluated in context and there is no active context when converting the macros to assembly.
Suitable functions such as $sizeof( ) are available in assembly expressions. However, as the basic types such as int/char/float have no type representation in assembly, there is no way to ask for $sizeof(int), for example, in assembly.
13.2.13 Structures and Unions
C/C++ structures and unions are converted to assembly .struct and .union elements. Padding and ending alignments are added as necessary to make the resulting assembly structure have the same size and member offsets as the C/C++ source. The primary purpose is to allow access to members of C/C++ structures, as well as to facilitate debugging of the assembly code. For nested structures, the assembly .tag feature is used to refer to other structures/unions.
The alignment is also passed from the C/C++ source so that the assembly symbol is marked with the same alignment as the C/C++ symbol. (See Section 13.2.3 for information about pragmas, which may attempt to modify structures.) Because the alignment of structures is stored in the assembly symbol, built-in assembly functions like $sizeof( ) and $alignof( ) can be used on the resulting structure name symbol.
When using unnamed structures (or unions) in typedefs, such as:
typedef struct { int a_member; } mystrname;
This is really a shorthand way of writing:
struct temporary_name { int a_member; };
typedef temporary_name mystrname;
The conversion processes the above statements in the same manner: generating a temporary name for the structure and then using .define to output a typedef from the temporary name to the user name. You should use your mystrname in assembly the same as you would in C/C++, but do not be confused by the assembly structure definition in the list, which contains the temporary name. You can avoid the temporary name by specifying a name for the structure, as in:
typedef struct a_st_name { ... } mystrname;
If a shorthand method is used in C to declare a variable with a particular structure, for example:
extern struct a_name { int a_member; } a_variable;
Then after the structure is converted to assembly, a .tag directive is generated to declare the structure of the external variable, such as:
_a_variable .tag a_st_name
This allows you to refer to _a_variable.a_member in your assembly code.
13.2.14 Function/Variable Prototypes
Non-static function and variable prototypes (not definitions) will result in a .global directive being generated for each symbol found.
See Section 13.3.1 for C++ name mangling issues.
Function and variable definitions will result in a warning message being generated (see the WARN/NOWARN parameter discussion for where these warnings are created) for each, and they will not be represented in the converted assembly.
The assembly symbol representing the variable declarations will not contain type information about those symbols. Only a .global will be issued for them. Therefore, it is your responsibility to ensure the symbol is used appropriately.
See Section 13.2.13 for information on variables names which are of a structure/union type.
13.2.15 C Constant Suffixes
The C constant suffixes u, l, and f are passed to the assembly unchanged. The assembler will ignore these suffixes if used in assembly expressions.
13.2.16 Basic C/C++ Types
Only complex types (structures and unions) in the C/C++ source code are converted to assembly. Basic types such as int, char, or float are not converted or represented in assembly beyond any existing .int, .char, .float, etc. directives that previously existed in assembly.
Typedefs of basic types are therefore also not represented in the converted assembly.
13.3 Notes on C++ Specific Conversions
The following sections describe C++ specific conversion elements that you need to be aware of when sharing header files with assembly source.
13.3.1 Name Mangling
Symbol names may be mangled in C++ source files. When mangling occurs, the converted assembly will use the mangled names to avoid symbol name clashes. You can use the demangler (dem430) to demangle names and identify the correct symbols to use in assembly.
To defeat name mangling in C++ for symbols where polymorphism (calling a function of the same name with different kinds of arguments) is not required, use the following syntax:
extern "C" void somefunc(int arg);
The above format is the short method for declaring a single function. To use this method for multiple functions, you can also use the following syntax:
extern "C" {
void somefunc(int arg);
int anotherfunc(int arg);
...
}
13.3.2 Derived Classes
Derived classes are only partially supported when converting to assembly because of issues related to C++ scoping which does not exist in assembly. The greatest difference is that base class members do not automatically become full (top-level) members of the derived class. For example:
----------------------------------------------------------
class base
{
public:
int b1;
};
class derived : public base
{
public:
int d1;
}
In C++ code, the class derived would contain both integers b1 and d1. In the converted assembly structure "derived", the members of the base class must be accessed using the name of the base class, such as derived.__b_base.b1 rather than the expected derived.b1.
A non-virtual, non-empty base class will have __b_ prepended to its name within the derived class to signify it is a base class name. That is why the example above is derived.__b_base.b1 and not simply derived.base.b1.
13.4 Special Assembler Support
13.4.1 Enumerations (.enum/.emember/.endenum)
The following directives support a pseudo-scoping for enumerations:
| ENUM_NAME | .enum |
| MEMBER1 | .emember [value] |
| MEMBER2 | .emember [value] |
| ... | |
| .endenum |
The .enum directive begins the enumeration definition and .endenum terminates it.
The enumeration name (ENUM_NAME) cannot be used to allocate space; its size is reported as zero.
The format to use the value of a member is ENUM_NAME.MEMBER, similar to a structure member usage.
The .emember directive optionally accepts the value to set the member to, just as in C/C++. If not specified, the member takes a value one more than the previous member. As in C/C++, member names cannot be duplicated, although values can be. Unless specified with .emember, the first enumeration member will be given the value 0 (zero), as in C/C++.
The .endenum directive cannot be used with a label, as structure .endstruct directives can, because the .endenum directive has no value like the .endstruct does (containing the size of the structure).
Conditional compilation directives (.if/.else/.elseif/.endif) are the only other non-enumeration code allowed within the .enum/.endenum sequence.
13.4.2 The .define Directive
The .define directive functions in the same manner as the .asg directive, except that .define disallows creation of a substitution symbol that has the same name as a register symbol or mnemonic. It does not create a new symbol name space in the assembler, rather it uses the existing substitution symbol name space. The syntax for the directive is:
.define substitution string, substitution symbol name
The .define directive is used to prevent corruption of the assembly environment when converting C/C++ headers.
13.4.3 The .undefine/.unasg Directives
The .undef directive is used to remove the definition of a substitution symbol created using .define or .asg. This directive will remove the named symbol from the substitution symbol table from the point of the .undef to the end of the assembly file. The syntax for these directives is:
.undefine substitution symbol name
.unasg substitution symbol name
This can be used to remove from the assembly environment any C/C++ macros that may cause a problem.
Also see Section 13.4.2, which covers the .define directive.
13.4.4 The $defined( ) Built-In Function
The $defined directive returns true/1 or false/0 depending on whether the name exists in the current substitution symbol table or the standard symbol table. In essence $defined returns TRUE if the assembler has any user symbol in scope by that name. This differs from $isdefed in that $isdefed only tests for NON-substitution symbols. The syntax is:
$defined( substitution symbol name)
A statement such as ".if $defined(macroname)" is then similar to the C code "#ifdef macroname".
See Section 13.4.2 and Section 13.4.3 for the use of .define and .undef in assembly.
13.4.5 The $sizeof Built-In Function
The assembly built-in function $sizeof( ) can be used to query the size of a structure in assembly. It is an alias for the already existing $structsz( ). The syntax is:
$sizeof( structure name)
The $sizeof function can then be used similarly to the C built-in function sizeof( ).
The assembler's $sizeof( ) built-in function cannot be used to ask for the size of basic C/C++ types, such as $sizeof(int), because those basic type names are not represented in assembly. Only complex types are converted from C/C++ to assembly.
Also see Section 13.2.12, which notes that this conversion does not happen automatically if the C/C++ sizeof( ) built-in function is used within a macro.
13.4.6 Structure/Union Alignment and $alignof( )
The assembly .struct and .union directives take an optional second argument which can be used to specify a minimum alignment to be applied to the symbol name. This is used by the conversion process to pass the specific alignment from C/C++ to assembly.
The assembly built-in function $alignof( ) can be used to report the alignment of these structures. This can be used even on assembly structures, and the function will return the minimum alignment calculated by the assembler.
13.4.7 The .cstring Directive
You can use the .cstring directive to cause the escape sequences and NULL termination to be properly handled as they would in C/C++.
.cstring "String with C escapes.\nWill be NULL terminated.\012"
See Section 13.2.11 for more information on the .cstring directive.
Copyright© 2015, Texas Instruments Incorporated. An IMPORTANT NOTICE for this document addresses availability, warranty, changes, use in safety-critical applications, intellectual property matters and other important disclaimers.