TMS320C28x Assembly Language Tools
v15.9.0.STS
User's Guide
Literature Number: SPRU513I
September 2015
Contents
Preface....................................................................................................................................... 11
1 Introduction to the Software Development Tools.................................................................... 14
1.1 Software Development Tools Overview ................................................................................. 15
1.2 Tools Descriptions.......................................................................................................... 16
2 Introduction to Object Modules............................................................................................ 17
2.1 Executable Object Files ................................................................................................... 18
2.2 Introduction to Sections ................................................................................................... 18
2.2.1 Special Section Names........................................................................................... 19
2.3 How the Assembler Handles Sections .................................................................................. 20
2.3.1 Uninitialized Sections ............................................................................................. 20
2.3.2 Initialized Sections ................................................................................................ 21
2.3.3 User-Named Sections ............................................................................................ 21
2.3.4 Current Section .................................................................................................... 22
2.3.5 Section Program Counters....................................................................................... 22
2.3.6 Subsections ........................................................................................................ 22
2.3.7 Using Sections Directives ........................................................................................ 23
2.4 How the Linker Handles Sections........................................................................................ 26
2.4.1 Combining Input Sections........................................................................................ 26
2.4.2 Placing Sections................................................................................................... 27
2.5 Symbols ..................................................................................................................... 28
2.5.1 External Symbols.................................................................................................. 28
2.5.2 The Symbol Table................................................................................................. 29
2.6 Symbolic Relocations ...................................................................................................... 29
2.6.1 Expressions With Multiple Relocatable Symbols (COFF Only) ............................................. 29
2.7 Loading a Program......................................................................................................... 30
3 Program Loading and Running ............................................................................................ 31
3.1 Loading ...................................................................................................................... 32
3.1.1 Load and Run Addresses ........................................................................................ 32
3.1.2 Bootstrap Loading................................................................................................. 33
3.2 Entry Point................................................................................................................... 37
3.3 Run-Time Initialization ..................................................................................................... 37
3.3.1 _c_int00............................................................................................................. 37
3.3.2 RAM Model vs. ROM Model ..................................................................................... 38
3.3.3 Copy Tables........................................................................................................ 39
3.4 Arguments to main ......................................................................................................... 40
3.5 Run-Time Relocation ...................................................................................................... 40
3.6 Additional Information...................................................................................................... 40
4 Assembler Description........................................................................................................ 41
4.1 Assembler Overview ....................................................................................................... 42
4.2 The Assembler's Role in the Software Development Flow ........................................................... 43
4.3 Invoking the Assembler.................................................................................................... 44
4.4 Naming Alternate Directories for Assembler Input..................................................................... 45
4.4.1 Using the --include_path Assembler Option ................................................................... 46
4.4.2 Using the C2000_A_DIR Environment Variable .............................................................. 46
2
Contents SPRU513I–September 2015
Submit Documentation Feedback
Copyright © 2015, Texas Instruments Incorporated
www.ti.com
4.5 Source Statement Format................................................................................................. 47
4.5.1 Label Field.......................................................................................................... 48
4.5.2 Mnemonic Field.................................................................................................... 49
4.5.3 Operand Field...................................................................................................... 49
4.5.4 Comment Field .................................................................................................... 49
4.6 Literal Constants ........................................................................................................... 50
4.6.1 Integer Literals..................................................................................................... 50
4.6.2 Character String Literals.......................................................................................... 51
4.6.3 Floating-Point Literals............................................................................................. 52
4.7 Assembler Symbols........................................................................................................ 52
4.7.1 Identifiers ........................................................................................................... 52
4.7.2 Labels............................................................................................................... 53
4.7.3 Local Labels........................................................................................................ 53
4.7.4 Symbolic Constants............................................................................................... 56
4.7.5 Defining Symbolic Constants (--asm_define Option) ......................................................... 56
4.7.6 Predefined Symbolic Constants ................................................................................. 57
4.7.7 Registers ........................................................................................................... 58
4.7.8 Substitution Symbols.............................................................................................. 59
4.8 Expressions ................................................................................................................. 60
4.8.1 Mathematical and Logical Operators ........................................................................... 61
4.8.2 Relational Operators and Conditional Expressions........................................................... 62
4.8.3 Well-Defined Expressions........................................................................................ 62
4.8.4 Legal Expressions................................................................................................. 62
4.9 Built-in Functions and Operators......................................................................................... 63
4.9.1 Built-In Math and Trigonometric Functions .................................................................... 63
4.10 Specifying Assembler Fill Values (--asm_code_fill and --asm_data_fill)............................................ 64
4.11 TMS320C28x Assembler Modes......................................................................................... 65
4.11.1 C28x Object Mode ............................................................................................... 65
4.11.2 C28x Object - Accept C2xlp Syntax Mode.................................................................... 65
4.11.3 C28x FPU32 and FPU64 Object Modes ...................................................................... 66
4.11.4 C28x CLA Object Mode ......................................................................................... 67
4.12 Source Listings ............................................................................................................. 68
4.13 Debugging Assembly Source............................................................................................. 70
4.14 C-Type Symbolic Debugging for Assembly Variables (--cdebug_asm_data Option) ............................. 71
4.15 Cross-Reference Listings ................................................................................................. 72
4.16 Smart Encoding............................................................................................................. 73
4.17 Pipeline Conflict Detection ................................................................................................ 74
4.17.1 Protected and Unprotected Pipeline Instructions ............................................................ 74
4.17.2 Pipeline Conflict Prevention and Detection ................................................................... 74
4.17.3 Pipeline Conflicts Detected ..................................................................................... 75
5 Assembler Directives.......................................................................................................... 76
5.1 Directives Summary........................................................................................................ 77
5.2 Compatibility With the TMS320C1x/C2x/C2xx/C5x Assembler Directives.......................................... 81
5.3 Directives that Define Sections........................................................................................... 82
5.4 Directives that Initialize Values ........................................................................................... 84
5.5 Directives that Perform Alignment and Reserve Space............................................................... 86
5.6 Directives that Format the Output Listings.............................................................................. 87
5.7 Directives that Reference Other Files ................................................................................... 88
5.8 Directives that Enable Conditional Assembly........................................................................... 89
5.9 Directives that Define Union or Structure Types ....................................................................... 89
5.10 Directives that Define Enumerated Types .............................................................................. 89
5.11 Directives that Define Symbols at Assembly Time .................................................................... 90
5.12 Directives that Override the Assembler Mode.......................................................................... 90
3
SPRU513I–September 2015 Contents
Submit Documentation Feedback
Copyright © 2015, Texas Instruments Incorporated
www.ti.com
5.13 Miscellaneous Directives .................................................................................................. 91
5.14 Directives Reference....................................................................................................... 92
6 Macro Language Description ............................................................................................. 146
6.1 Using Macros.............................................................................................................. 147
6.2 Defining Macros........................................................................................................... 147
6.3 Macro Parameters/Substitution Symbols .............................................................................. 149
6.3.1 Directives That Define Substitution Symbols................................................................. 150
6.3.2 Built-In Substitution Symbol Functions........................................................................ 151
6.3.3 Recursive Substitution Symbols ............................................................................... 152
6.3.4 Forced Substitution .............................................................................................. 152
6.3.5 Accessing Individual Characters of Subscripted Substitution Symbols................................... 153
6.3.6 Substitution Symbols as Local Variables in Macros ........................................................ 154
6.4 Macro Libraries............................................................................................................ 154
6.5 Using Conditional Assembly in Macros ................................................................................ 155
6.6 Using Labels in Macros .................................................................................................. 157
6.7 Producing Messages in Macros ........................................................................................ 158
6.8 Using Directives to Format the Output Listing ........................................................................ 159
6.9 Using Recursive and Nested Macros .................................................................................. 160
6.10 Macro Directives Summary.............................................................................................. 161
7 Archiver Description ......................................................................................................... 162
7.1 Archiver Overview ........................................................................................................ 163
7.2 The Archiver's Role in the Software Development Flow............................................................. 164
7.3 Invoking the Archiver ..................................................................................................... 165
7.4 Archiver Examples........................................................................................................ 166
7.5 Library Information Archiver Description............................................................................... 167
7.5.1 Invoking the Library Information Archiver..................................................................... 167
7.5.2 Library Information Archiver Example......................................................................... 168
7.5.3 Listing the Contents of an Index Library ...................................................................... 168
7.5.4 Requirements .................................................................................................... 168
8 Linker Description ............................................................................................................ 169
8.1 Linker Overview........................................................................................................... 170
8.2 The Linker's Role in the Software Development Flow ............................................................... 171
8.3 Invoking the Linker........................................................................................................ 172
8.4 Linker Options............................................................................................................. 173
8.4.1 Wildcards in File, Section, and Symbol Patterns ............................................................ 175
8.4.2 Specifying C/C++ Symbols with Linker Options ............................................................. 175
8.4.3 Relocation Capabilities (--absolute_exe and --relocatable Options) ...................................... 176
8.4.4 Allocate Memory for Use by the Loader to Pass Arguments (--arg_size Option) ....................... 177
8.4.5 Control Linker Diagnostics...................................................................................... 177
8.4.6 Disable Automatic Library Selection (--disable_auto_rts Option).......................................... 178
8.4.7 Disable Conditional Linking (--disable_clink Option) ........................................................ 178
8.4.8 Link Command File Preprocessing (--disable_pp, --define and --undefine Options) ................... 178
8.4.9 Error Correcting Code Testing (--ecc Options) .............................................................. 180
8.4.10 Define an Entry Point (--entry_point Option) ................................................................ 180
8.4.11 Set Default Fill Value (--fill_value Option) ................................................................... 181
8.4.12 Define Heap Size (--heap_size Option)...................................................................... 181
8.4.13 Hiding Symbols ................................................................................................. 181
8.4.14 Alter the Library Search Algorithm (--library Option, --search_path Option, and C2000_C_DIR
Environment Variable)........................................................................................... 182
8.4.15 Change Symbol Localization.................................................................................. 184
8.4.16 Create a Map File (--map_file Option) ....................................................................... 186
8.4.17 Managing Map File Contents (--mapfile_contents Option) ................................................ 187
8.4.18 Disable Name Demangling (--no_demangle) ............................................................... 188
4
Contents SPRU513I–September 2015
Submit Documentation Feedback
Copyright © 2015, Texas Instruments Incorporated
www.ti.com
8.4.19 Disable Merging of Symbolic Debugging Information (--no_sym_merge Option) ...................... 188
8.4.20 Strip Symbolic Information (--no_symtable Option) ........................................................ 188
8.4.21 Name an Output Module (--output_file Option) ............................................................. 189
8.4.22 Prioritizing Function Placement (--preferred_order Option) ............................................... 189
8.4.23 C Language Options (--ram_model and --rom_model Options) .......................................... 189
8.4.24 Create an Absolute Listing File (--run_abs Option) ........................................................ 189
8.4.25 Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries)................................... 189
8.4.26 Define Stack Size (--stack_size Option) ..................................................................... 189
8.4.27 Enforce Strict Compatibility (--strict_compatibility Option) ................................................ 190
8.4.28 Mapping of Symbols (--symbol_map Option) ............................................................... 190
8.4.29 Introduce an Unresolved Symbol (--undef_sym Option)................................................... 190
8.4.30 Display a Message When an Undefined Output Section Is Created (--warn_sections)............... 190
8.4.31 Generate XML Link Information File (--xml_link_info Option)............................................. 190
8.5 Linker Command Files ................................................................................................... 191
8.5.1 Reserved Names in Linker Command Files.................................................................. 192
8.5.2 Constants in Linker Command Files .......................................................................... 192
8.5.3 The MEMORY Directive ........................................................................................ 193
8.5.4 The SECTIONS Directive....................................................................................... 197
8.5.5 Placing a Section at Different Load and Run Addresses................................................... 212
8.5.6 Using GROUP and UNION Statements ...................................................................... 214
8.5.7 Overlaying Pages ................................................................................................ 218
8.5.8 Special Section Types (DSECT, COPY, and NOLOAD) ................................................... 221
8.5.9 Configuring Error Correcting Code (ECC) with the Linker.................................................. 222
8.5.10 Assigning Symbols at Link Time.............................................................................. 224
8.5.11 Creating and Filling Holes ..................................................................................... 229
8.6 Linker Symbols............................................................................................................ 232
8.6.1 Using Linker Symbols in C/C++ Applications ................................................................ 232
8.6.2 Resolving Symbols with Object Libraries..................................................................... 233
8.7 Default Placement Algorithm ............................................................................................ 235
8.7.1 How the Allocation Algorithm Creates Output Sections .................................................... 235
8.7.2 Reducing Memory Fragmentation ............................................................................. 236
8.8 Linker-Generated Copy Tables ......................................................................................... 236
8.8.1 Using Copy Tables for Boot Loading.......................................................................... 236
8.8.2 Using Built-in Link Operators in Copy Tables................................................................ 237
8.8.3 Overlay Management Example ................................................................................ 237
8.8.4 Generating Copy Tables With the table() Operator ......................................................... 238
8.8.5 Copy Table Contents............................................................................................ 243
8.8.6 General Purpose Copy Routine................................................................................ 244
8.9 Linker-Generated CRC Tables.......................................................................................... 245
8.9.1 The crc_table() Operator........................................................................................ 245
8.9.2 Restrictions ....................................................................................................... 245
8.9.3 Examples ......................................................................................................... 246
8.9.4 Interface........................................................................................................... 248
8.9.5 A Special Note Regarding 16-Bit char ........................................................................ 251
8.10 Partial (Incremental) Linking............................................................................................. 252
8.11 Linking C/C++ Code...................................................................................................... 253
8.11.1 Run-Time Initialization ......................................................................................... 253
8.11.2 Object Libraries and Run-Time Support ..................................................................... 253
8.11.3 Setting the Size of the Stack and Heap Sections .......................................................... 253
8.11.4 Initializing and AutoInitialzing Variables at Run Time...................................................... 254
8.12 Linker Example............................................................................................................ 254
9 Absolute Lister Description ............................................................................................... 258
9.1 Producing an Absolute Listing .......................................................................................... 259
5
SPRU513I–September 2015 Contents
Submit Documentation Feedback
Copyright © 2015, Texas Instruments Incorporated