Texas Instruments TMS320C28x User Manual
TMS320C28x Assembly Language Tools
v20.12.0.STS
User’s Guide
Literature Number: SPRU513V
JULY 2001 – REVISED DECEMBER 2020
www.ti.com Table of Contents
Table of Contents
Read This First......................................................................................................................................................................... 11
About This Manual..................................................................................................................................................................11
How to Use This Manual........................................................................................................................................................ 11
Notational Conventions.......................................................................................................................................................... 12
Related Documentation From Texas Instruments.................................................................................................................. 13
Trademarks............................................................................................................................................................................ 13
1 Introduction to the Software Development Tools.............................................................................................................. 15
1.1 Software Development Tools Overview........................................................................................................................... 16
1.2 Tools Descriptions............................................................................................................................................................17
2 Introduction to Object Modules...........................................................................................................................................19
2.1 Object File Format Specifications.................................................................................................................................... 20
2.2 Executable Object Files................................................................................................................................................... 20
2.3 Introduction to Sections....................................................................................................................................................20
2.3.1 Special Section Names............................................................................................................................................. 21
2.4 How the Assembler Handles Sections............................................................................................................................. 21
2.4.1 Uninitialized Sections................................................................................................................................................ 22
2.4.2 Initialized Sections.....................................................................................................................................................22
2.4.3 User-Named Sections............................................................................................................................................... 23
2.4.4 Current Section..........................................................................................................................................................23
2.4.5 Section Program Counters........................................................................................................................................ 24
2.4.6 Subsections............................................................................................................................................................... 24
2.4.7 Using Sections Directives..........................................................................................................................................25
2.5 How the Linker Handles Sections.................................................................................................................................... 27
2.5.1 Combining Input Sections..........................................................................................................................................28
2.5.2 Placing Sections........................................................................................................................................................ 29
2.6 Symbols........................................................................................................................................................................... 29
2.6.1 Global (External) Symbols.........................................................................................................................................30
2.6.2 Local Symbols........................................................................................................................................................... 30
2.6.3 Weak Symbols...........................................................................................................................................................30
2.6.4 The Symbol Table......................................................................................................................................................31
2.7 Symbolic Relocations.......................................................................................................................................................32
2.7.1 Expressions With Multiple Relocatable Symbols (COFF Only)................................................................................. 32
2.8 Loading a Program...........................................................................................................................................................33
3 Program Loading and Running........................................................................................................................................... 35
3.1 Loading............................................................................................................................................................................ 36
3.1.1 Load and Run Addresses.......................................................................................................................................... 36
3.1.2 Bootstrap Loading..................................................................................................................................................... 37
3.2 Entry Point........................................................................................................................................................................40
3.3 Run-Time Initialization......................................................................................................................................................41
3.3.1 The _c_int00 Function............................................................................................................................................... 41
3.3.2 RAM Model vs. ROM Model...................................................................................................................................... 41
3.3.3 About Linker-Generated Copy Tables....................................................................................................................... 43
3.4 Arguments to main........................................................................................................................................................... 44
3.5 Run-Time Relocation........................................................................................................................................................44
3.6 Additional Information...................................................................................................................................................... 44
4 Assembler Description.........................................................................................................................................................45
4.1 Assembler Overview........................................................................................................................................................ 46
4.2 The Assembler's Role in the Software Development Flow.............................................................................................. 47
4.3 Invoking the Assembler....................................................................................................................................................48
4.4 Controlling Application Binary Interface........................................................................................................................... 49
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
3
Table of Contents
www.ti.com
4.5 Naming Alternate Directories for Assembler Input........................................................................................................... 49
4.5.1 Using the --include_path Assembler Option.............................................................................................................. 50
4.5.2 Using the C2000_A_DIR Environment Variable........................................................................................................51
4.6 Source Statement Format................................................................................................................................................ 52
4.6.1 Label Field................................................................................................................................................................. 53
4.6.2 Mnemonic Field......................................................................................................................................................... 53
4.6.3 Operand Field............................................................................................................................................................54
4.6.4 Comment Field.......................................................................................................................................................... 54
4.7 Literal Constants.............................................................................................................................................................. 54
4.7.1 Integer Literals...........................................................................................................................................................54
4.7.2 Character String Literals............................................................................................................................................56
4.7.3 Floating-Point Literals................................................................................................................................................57
4.8 Assembler Symbols......................................................................................................................................................... 57
4.8.1 Identifiers................................................................................................................................................................... 57
4.8.2 Labels........................................................................................................................................................................ 57
4.8.3 Local Labels.............................................................................................................................................................. 58
4.8.4 Symbolic Constants...................................................................................................................................................59
4.8.5 Defining Symbolic Constants (--asm_define Option).................................................................................................60
Example 4-3. Using Symbolic Constants Defined on Command Line................................................................................61
4.8.6 Predefined Symbolic Constants................................................................................................................................ 61
4.8.7 Registers................................................................................................................................................................... 61
4.8.8 Substitution Symbols................................................................................................................................................. 63
4.9 Expressions......................................................................................................................................................................63
4.9.1 Mathematical and Logical Operators.........................................................................................................................64
4.9.2 Relational Operators and Conditional Expressions................................................................................................... 65
4.9.3 Well-Defined Expressions..........................................................................................................................................65
4.9.4 Legal Expressions..................................................................................................................................................... 65
4.10 Built-in Functions and Operators....................................................................................................................................66
4.10.1 Built-In Math and Trigonometric Functions..............................................................................................................66
4.11 TMS320C28x Assembler Extensions.............................................................................................................................67
4.11.1 C28x Support...........................................................................................................................................................67
4.11.2 C28x FPU32 and FPU64 Extensions.......................................................................................................................68
4.11.3 C28x CLA Extensions..............................................................................................................................................68
4.12 Source Listings...............................................................................................................................................................69
4.13 Debugging Assembly Source.........................................................................................................................................71
4.14 Cross-Reference Listings...............................................................................................................................................72
4.15 Smart Encoding..............................................................................................................................................................73
4.16 Pipeline Conflict Detection............................................................................................................................................. 74
4.16.1 Protected and Unprotected Pipeline Instructions.................................................................................................... 74
4.16.2 Pipeline Conflict Prevention and Detection............................................................................................................. 74
4.16.3 Pipeline Conflicts Detected......................................................................................................................................74
5 Assembler Directives........................................................................................................................................................... 77
5.1 Directives Summary......................................................................................................................................................... 78
5.2 Directives that Define Sections........................................................................................................................................ 82
Example 5-1. Sections Directives.......................................................................................................................................83
5.3 Directives that Initialize Values.........................................................................................................................................83
5.4 Directives that Perform Alignment and Reserve Space................................................................................................... 86
5.5 Directives that Format the Output Listings....................................................................................................................... 87
5.6 Directives that Reference Other Files.............................................................................................................................. 88
5.7 Directives that Enable Conditional Assembly...................................................................................................................89
5.8 Directives that Define Union or Structure Types.............................................................................................................. 89
5.9 Directives that Define Enumerated Types........................................................................................................................89
5.10 Directives that Define Symbols at Assembly Time.........................................................................................................89
5.11 Miscellaneous Directives................................................................................................................................................90
5.12 Directives Reference......................................................................................................................................................91
6 Macro Language Description.............................................................................................................................................155
6.1 Using Macros................................................................................................................................................................. 156
6.2 Defining Macros............................................................................................................................................................. 157
6.3 Macro Parameters/Substitution Symbols....................................................................................................................... 158
6.3.1 Directives That Define Substitution Symbols...........................................................................................................159
6.3.2 Built-In Substitution Symbol Functions.................................................................................................................... 160
4 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com
Table of Contents
6.3.3 Recursive Substitution Symbols.............................................................................................................................. 161
6.3.4 Forced Substitution..................................................................................................................................................161
6.3.5 Accessing Individual Characters of Subscripted Substitution Symbols...................................................................161
6.3.6 Substitution Symbols as Local Variables in Macros................................................................................................ 162
6.4 Macro Libraries.............................................................................................................................................................. 163
6.5 Using Conditional Assembly in Macros..........................................................................................................................163
6.6 Using Labels in Macros..................................................................................................................................................165
6.7 Producing Messages in Macros..................................................................................................................................... 166
6.8 Using Directives to Format the Output Listing................................................................................................................166
6.9 Using Recursive and Nested Macros.............................................................................................................................168
6.10 Macro Directives Summary.......................................................................................................................................... 169
7 Archiver Description.......................................................................................................................................................... 171
7.1 Archiver Overview.......................................................................................................................................................... 172
7.2 The Archiver's Role in the Software Development Flow................................................................................................ 172
7.3 Invoking the Archiver......................................................................................................................................................173
7.4 Archiver Examples......................................................................................................................................................... 173
7.5 Library Information Archiver Description........................................................................................................................ 175
7.5.1 Invoking the Library Information Archiver................................................................................................................ 175
7.5.2 Library Information Archiver Example..................................................................................................................... 176
7.5.3 Listing the Contents of an Index Library.................................................................................................................. 176
7.5.4 Requirements.......................................................................................................................................................... 176
8 Linker Description.............................................................................................................................................................. 177
8.1 Linker Overview............................................................................................................................................................. 178
8.2 The Linker's Role in the Software Development Flow....................................................................................................178
8.3 Invoking the Linker......................................................................................................................................................... 179
8.4 Linker Options................................................................................................................................................................ 180
8.4.1 Wildcards in File, Section, and Symbol Patterns.....................................................................................................182
8.4.2 Specifying C/C++ Symbols with Linker Options...................................................................................................... 182
8.4.3 Relocation Capabilities (--absolute_exe and --relocatable Options)....................................................................... 182
8.4.4 Allocate Memory for Use by the Loader to Pass Arguments (--arg_size Option)....................................................183
8.4.5 Compression (--cinit_compression and --copy_compression Option).....................................................................184
8.4.6 Compress DWARF Information (--compress_dwarf Option)................................................................................... 184
8.4.7 Control Linker Diagnostics.......................................................................................................................................184
8.4.8 Automatic Library Selection (--disable_auto_rts Option)......................................................................................... 185
8.4.9 Disable Conditional Linking (--disable_clink Option)............................................................................................... 185
8.4.10 Do Not Remove Unused Sections (--unused_section_elimination Option)........................................................... 185
8.4.11 Linker Command File Preprocessing (--disable_pp, --define and --undefine Options)..........................................185
8.4.12 Error Correcting Code Testing (--ecc Options)...................................................................................................... 187
8.4.13 Define an Entry Point (--entry_point Option)......................................................................................................... 188
8.4.14 Set Default Fill Value (--fill_value Option)..............................................................................................................188
8.4.15 Define Heap Size (--heap_size Option).................................................................................................................189
8.4.16 Hiding Symbols......................................................................................................................................................189
8.4.17 Alter the Library Search Algorithm (--library, --search_path, and C2000_C_DIR )................................................189
8.4.18 Change Symbol Localization................................................................................................................................. 192
8.4.19 Create a Map File (--map_file Option)................................................................................................................... 193
8.4.20 Managing Map File Contents (--mapfile_contents Option).................................................................................... 194
8.4.21 Disable Name Demangling (--no_demangle)........................................................................................................ 195
8.4.22 Disable Merging of Symbolic Debugging Information (--no_sym_merge Option) ................................................ 196
8.4.23 Strip Symbolic Information (--no_symtable Option)...............................................................................................196
8.4.24 Name an Output Module (--output_file Option)..................................................................................................... 196
8.4.25 Prioritizing Function Placement (--preferred_order Option)...................................................................................197
8.4.26 C Language Options (--ram_model and --rom_model Options)............................................................................ 197
8.4.27 Retain Discarded Sections (--retain Option)..........................................................................................................197
8.4.28 Create an Absolute Listing File (--run_abs Option)............................................................................................... 198
8.4.29 Scan All Libraries for Duplicate Symbol Definitions (--scan_libraries)...................................................................198
8.4.30 Define Stack Size (--stack_size Option)................................................................................................................ 198
8.4.31 Enforce Strict Compatibility (--strict_compatibility Option).....................................................................................198
8.4.32 Mapping of Symbols (--symbol_map Option)........................................................................................................ 198
8.4.33 Introduce an Unresolved Symbol (--undef_sym Option)....................................................................................... 199
8.4.34 Display a Message When an Undefined Output Section Is Created (--warn_sections)........................................ 199
8.4.35 Generate XML Link Information File (--xml_link_info Option)................................................................................199
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
5
Table of Contents
www.ti.com
8.4.36 Zero Initialization (--zero_init Option).................................................................................................................... 199
8.5 Linker Command Files................................................................................................................................................... 200
8.5.1 Reserved Names in Linker Command Files............................................................................................................ 201
8.5.2 Constants in Linker Command Files........................................................................................................................201
8.5.3 Accessing Files and Libraries from a Linker Command File................................................................................... 201
8.5.4 The MEMORY Directive.......................................................................................................................................... 203
8.5.5 The SECTIONS Directive........................................................................................................................................ 206
8.5.6 Placing a Section at Different Load and Run Addresses.........................................................................................219
8.5.7 Using GROUP and UNION Statements.................................................................................................................. 222
8.5.8 Overlaying Pages.................................................................................................................................................... 227
8.5.9 Special Section Types (DSECT, COPY, NOLOAD, and NOINIT)............................................................................ 229
8.5.10 Configuring Error Correcting Code (ECC) with the Linker.....................................................................................230
8.5.11 Assigning Symbols at Link Time............................................................................................................................ 232
8.5.12 Creating and Filling Holes..................................................................................................................................... 238
8.6 Linker Symbols...............................................................................................................................................................242
8.6.1 Using Linker Symbols in C/C++ Applications.......................................................................................................... 242
8.6.2 Declaring Weak Symbols.........................................................................................................................................243
8.6.3 Resolving Symbols with Object Libraries................................................................................................................ 243
8.7 Default Placement Algorithm..........................................................................................................................................244
8.7.1 How the Allocation Algorithm Creates Output Sections.......................................................................................... 245
8.7.2 Reducing Memory Fragmentation........................................................................................................................... 245
8.8 Using Linker-Generated Copy Tables............................................................................................................................ 245
8.8.1 Using Copy Tables for Boot Loading....................................................................................................................... 246
8.8.2 Using Built-in Link Operators in Copy Tables.......................................................................................................... 246
8.8.3 Overlay Management Example............................................................................................................................... 247
8.8.4 Generating Copy Tables With the table() Operator................................................................................................. 247
8.8.5 Compression........................................................................................................................................................... 251
8.8.6 Copy Table Contents............................................................................................................................................... 255
8.8.7 General Purpose Copy Routine...............................................................................................................................256
8.9 Linker-Generated CRC Tables and CRC Over Memory Ranges................................................................................... 257
8.9.1 Using the crc_table() Operator in the SECTIONS Directive.................................................................................... 257
8.9.2 Using the crc() Operator in the MEMORY Directive................................................................................................ 262
8.9.3 A Special Note Regarding 16-Bit char.....................................................................................................................266
8.10 Partial (Incremental) Linking........................................................................................................................................ 267
8.11 Linking C/C++ Code.....................................................................................................................................................268
8.11.1 Run-Time Initialization........................................................................................................................................... 268
8.11.2 Object Libraries and Run-Time Support................................................................................................................ 268
8.11.3 Setting the Size of the Stack and Heap Sections.................................................................................................. 268
8.11.4 Initializing and AutoInitialzing Variables at Run Time.............................................................................................269
8.12 Linker Example............................................................................................................................................................ 269
9 Absolute Lister Description...............................................................................................................................................273
9.1 Producing an Absolute Listing........................................................................................................................................274
9.2 Invoking the Absolute Lister........................................................................................................................................... 275
9.3 Absolute Lister Example................................................................................................................................................ 276
10 Cross-Reference Lister Description............................................................................................................................... 279
10.1 Producing a Cross-Reference Listing.......................................................................................................................... 280
10.2 Invoking the Cross-Reference Lister............................................................................................................................281
10.3 Cross-Reference Listing Example................................................................................................................................282
11 Object File Utilities............................................................................................................................................................283
11.1 Invoking the Object File Display Utility......................................................................................................................... 284
11.2 Invoking the Disassembler........................................................................................................................................... 285
11.3 Invoking the Name Utility..............................................................................................................................................285
11.4 Invoking the Strip Utility................................................................................................................................................286
12 Hex Conversion Utility Description.................................................................................................................................287
12.1 The Hex Conversion Utility's Role in the Software Development Flow........................................................................ 288
12.2 Invoking the Hex Conversion Utility............................................................................................................................. 289
12.2.1 Invoking the Hex Conversion Utility From the Command Line.............................................................................. 289
12.2.2 Invoking the Hex Conversion Utility With a Command File................................................................................... 292
12.3 Understanding Memory Widths....................................................................................................................................293
12.3.1 Target Width.......................................................................................................................................................... 293
12.3.2 Specifying the Memory Width................................................................................................................................293
6 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com
Table of Contents
12.3.3 Partitioning Data Into Output Files.........................................................................................................................294
12.3.4 Specifying Word Order for Output Words..............................................................................................................297
12.4 The ROMS Directive.................................................................................................................................................... 297
12.4.1 When to Use the ROMS Directive......................................................................................................................... 298
12.4.2 An Example of the ROMS Directive...................................................................................................................... 299
12.5 The SECTIONS Directive.............................................................................................................................................300
12.6 The Load Image Format (--load_image Option)...........................................................................................................302
12.6.1 Load Image Section Formation............................................................................................................................. 302
12.6.2 Load Image Characteristics...................................................................................................................................302
12.7 Excluding a Specified Section......................................................................................................................................303
12.8 Assigning Output Filenames........................................................................................................................................ 303
12.9 Image Mode and the --fill Option..................................................................................................................................304
12.9.1 Generating a Memory Image.................................................................................................................................304
12.9.2 Specifying a Fill Value............................................................................................................................................304
12.9.3 Steps to Follow in Using Image Mode................................................................................................................... 305
12.10 Array Output Format.................................................................................................................................................. 305
12.11 Building a Table for an On-Chip Boot Loader.............................................................................................................305
12.11.1 Description of the Boot Table...............................................................................................................................305
12.11.2 The Boot Table Format........................................................................................................................................ 305
12.11.3 How to Build the Boot Table.................................................................................................................................306
12.11.4 Booting From a Device Peripheral.......................................................................................................................306
12.11.5 Setting the Entry Point for the Boot Table............................................................................................................307
12.11.6 Using the C28x Boot Loader................................................................................................................................307
12.12 Using Secure Flash Boot on TMS320F2838x Devices.............................................................................................. 312
12.13 Controlling the ROM Device Address........................................................................................................................ 313
12.14 Control Hex Conversion Utility Diagnostics................................................................................................................314
12.15 Description of the Object Formats..............................................................................................................................315
12.15.1 ASCII-Hex Object Format (--ascii Option)........................................................................................................... 315
12.15.2 Intel MCS-86 Object Format (--intel Option)........................................................................................................316
12.15.3 Motorola Exorciser Object Format (--motorola Option)....................................................................................... 317
12.15.4 Extended Tektronix Object Format (--tektronix Option)....................................................................................... 318
12.15.5 Texas Instruments SDSMAC (TI-Tagged) Object Format (--ti_tagged Option)................................................... 319
12.15.6 TI-TXT Hex Format (--ti_txt Option).....................................................................................................................320
12.16 Hex Conversion Utility Error Messages..................................................................................................................... 321
13 Sharing C/C++ Header Files With Assembly Source.....................................................................................................323
13.1 Overview of the .cdecls Directive................................................................................................................................. 324
13.2 Notes on C/C++ Conversions...................................................................................................................................... 324
13.2.1 Comments............................................................................................................................................................. 324
13.2.2 Conditional Compilation (#if/#else/#ifdef/etc.)....................................................................................................... 325
13.2.3 Pragmas................................................................................................................................................................ 325
13.2.4 The #error and #warning Directives...................................................................................................................... 325
13.2.5 Predefined symbol __ASM_HEADER__............................................................................................................... 325
13.2.6 Usage Within C/C++ asm( ) Statements............................................................................................................... 325
13.2.7 The #include Directive........................................................................................................................................... 325
13.2.8 Conversion of #define Macros...............................................................................................................................325
13.2.9 The #undef Directive............................................................................................................................................. 326
13.2.10 Enumerations...................................................................................................................................................... 326
13.2.11 C Strings..............................................................................................................................................................326
13.2.12 C/C++ Built-In Functions..................................................................................................................................... 327
13.2.13 Structures and Unions......................................................................................................................................... 327
13.2.14 Function/Variable Prototypes...............................................................................................................................328
13.2.15 C Constant Suffixes.............................................................................................................................................328
13.2.16 Basic C/C++ Types..............................................................................................................................................328
13.3 Notes on C++ Specific Conversions............................................................................................................................ 328
13.3.1 Name Mangling..................................................................................................................................................... 328
13.3.2 Derived Classes.................................................................................................................................................... 329
13.3.3 Templates.............................................................................................................................................................. 329
13.3.4 Virtual Functions....................................................................................................................................................329
13.4 Special Assembler Support..........................................................................................................................................329
13.4.1 Enumerations (.enum/.emember/.endenum).........................................................................................................329
13.4.2 The .define Directive..............................................................................................................................................330
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
7
Table of Contents
www.ti.com
13.4.3 The .undefine/.unasg Directives............................................................................................................................ 330
13.4.4 The $defined( ) Built-In Function........................................................................................................................... 330
13.4.5 The $sizeof Built-In Function................................................................................................................................. 330
13.4.6 Structure/Union Alignment and $alignof( ).............................................................................................................331
13.4.7 The .cstring Directive.............................................................................................................................................331
A Symbolic Debugging Directives....................................................................................................................................... 333
A.1 DWARF Debugging Format...........................................................................................................................................334
A.2 Debug Directive Syntax................................................................................................................................................. 334
B XML Link Information File Description.............................................................................................................................335
B.1 XML Information File Element Types.............................................................................................................................336
B.2 Document Elements...................................................................................................................................................... 336
B.2.1 Header Elements.................................................................................................................................................... 336
B.2.2 Input File List...........................................................................................................................................................337
B.2.3 Object Component List............................................................................................................................................338
B.2.4 Logical Group List................................................................................................................................................... 339
B.2.5 Placement Map....................................................................................................................................................... 341
B.2.6 Symbol Table...........................................................................................................................................................342
C CRC Reference Implementation........................................................................................................................................343
C.1 Compilation Instructions................................................................................................................................................ 344
C.2 Reference CRC Calculation Routine............................................................................................................................. 344
Example C-1. Reference Implementation of a CRC Calculation Function: ref_crc.c....................................................... 344
C.3 Linker-Generated Copy Tables and CRC Tables...........................................................................................................347
Example C-2. Main Routine for Example Application: main.c.......................................................................................... 347
Example C-3. Checking CRC Values: check_crc.c.......................................................................................................... 348
Example C-4. Task1 Routine: task1.c...............................................................................................................................348
Example C-5. Task2 Routine: task2.c...............................................................................................................................348
Example C-6. Task3 Routine: task3.c...............................................................................................................................349
Example C-7. Example 1 Command File: ex1.cmd (for COFF)....................................................................................... 349
D Glossary..............................................................................................................................................................................351
D.1 Terminology................................................................................................................................................................... 351
Revision History.................................................................................................................................................................... 358
List of Figures
Figure 1-1. TMS320C28x Software Development Flow............................................................................................................ 16
Figure 2-1. Partitioning Memory Into Logical Blocks................................................................................................................. 21
Figure 2-2. Using Sections Directives Example.........................................................................................................................26
Figure 2-3. Object Code Generated by the File in Figure 2-2 ...................................................................................................27
Figure 2-4. Combining Input Sections to Form an Executable Object Module.......................................................................... 28
Figure 3-1. Bootloading Sequence (Simplified)......................................................................................................................... 37
Figure 3-2. Bootloading Sequence with Secondary Bootloader................................................................................................ 38
Figure 3-3. Autoinitialization at Run Time..................................................................................................................................42
Figure 3-4. Initialization at Load Time........................................................................................................................................43
Figure 4-1. The Assembler in the TMS320C28x Software Development Flow......................................................................... 47
Figure 4-2. Example Assembler Listing..................................................................................................................................... 70
Figure 5-1. The .field Directive...................................................................................................................................................84
Figure 5-2. Initialization Directives.............................................................................................................................................85
Figure 5-3. The .align Directive..................................................................................................................................................86
Figure 5-4. The .space and .bes Directives............................................................................................................................... 87
Figure 5-5. The .field Directive.................................................................................................................................................114
Figure 5-6. Single-Precision Floating-Point Format................................................................................................................. 115
Figure 5-7. The .usect Directive...............................................................................................................................................153
Figure 7-1. The Archiver in the TMS320C28x Software Development Flow........................................................................... 172
Figure 8-1. The Linker in the TMS320C28x Software Development Flow...............................................................................178
Figure 8-2. Memory Map Defined in The MEMORY Directive ................................................................................................205
Figure 8-3. Section Placement Defined by The SECTIONS Directive ....................................................................................208
Figure 8-4. Run-Time Execution of Moving a Function from Slow to Fast Memory at Run Time ...........................................222
Figure 8-5. Memory Allocation Shown in The UNION Statement and Separate Load Addresses for UNION Sections .........224
Figure 8-6. Overlay Pages Defined in Example 8-5 and Example 8-6 ................................................................................... 229
Figure 8-7. Compressed Copy Table....................................................................................................................................... 251
Figure 8-8. Handler Table........................................................................................................................................................ 252
Figure 8-9. CRC_TABLE Conceptual Model............................................................................................................................260
8 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com
Table of Contents
Figure 8-10. CRC Storage Format for Memory Ranges.......................................................................................................... 265
Figure 8-11. CRC Data Flow Example.....................................................................................................................................266
Figure 9-1. Absolute Lister Development Flow........................................................................................................................274
Figure 10-1. The Cross-Reference Lister Development Flow................................................................................................. 280
Figure 12-1. The Hex Conversion Utility in the TMS320C28x Software Development Flow................................................... 288
Figure 12-2. Hex Conversion Utility Process Flow.................................................................................................................. 293
Figure 12-3. Object File Data and Memory Widths..................................................................................................................294
Figure 12-4. Data, Memory, and ROM Widths.........................................................................................................................296
Figure 12-5. The infile.out File Partitioned Into Four Output Files........................................................................................... 299
Figure 12-6. Sample Hex Converter Out File for Booting From 8-Bit SPI Boot....................................................................... 309
Figure 12-7. Sample Hex Converter Out File for C28x 16-Bit Parallel Boot GP I/O................................................................ 310
Figure 12-8. Sample Hex Converter Out File for Booting From 8-Bit SCI Boot....................................................................... 311
Figure 12-9. ASCII-Hex Object Format....................................................................................................................................315
Figure 12-10. Intel Hexadecimal Object Format...................................................................................................................... 316
Figure 12-11. Motorola-S Format.............................................................................................................................................317
Figure 12-12. Extended Tektronix Object Format.................................................................................................................... 318
Figure 12-13. TI-Tagged Object Format.................................................................................................................................. 319
Figure 12-14. TI-TXT Object Format....................................................................................................................................... 321
List of Tables
Table 4-1. TMS320C28x Assembler Options.............................................................................................................................48
Table 4-2. C28x Processor Symbolic Constants........................................................................................................................61
Table 4-3. CPU and CPU Control Registers.............................................................................................................................. 62
Table 4-4. FPU and FPU Control Registers............................................................................................................................... 62
Table 4-5. VCU Registers.......................................................................................................................................................... 62
Table 4-6. Operators Used in Expressions (Precedence)..........................................................................................................64
Table 4-7. Built-In Mathematical Functions................................................................................................................................ 66
Table 4-8. Symbol Attributes...................................................................................................................................................... 72
Table 4-9. Smart Encoding for Efficiency................................................................................................................................... 73
Table 4-10. Smart Encoding Intuitively...................................................................................................................................... 73
Table 4-11. Instructions That Avoid Smart Encoding................................................................................................................. 74
Table 5-1. Directives that Control Section Use.......................................................................................................................... 78
Table 5-2. Directives that Gather Sections into Common Groups............................................................................................. 78
Table 5-3. Directives that Affect Unused Section Elimination.................................................................................................... 78
Table 5-4. Directives that Initialize Values (Data and Memory)..................................................................................................78
Table 5-5. Directives that Perform Alignment and Reserve Space............................................................................................ 79
Table 5-6. Directives that Format the Output Listing..................................................................................................................79
Table 5-7. Directives that Reference Other Files....................................................................................................................... 80
Table 5-8. Directives that Affect Symbol Linkage and Visibility..................................................................................................80
Table 5-9. Directives that Define Symbols at Assembly Time ...................................................................................................80
Table 5-10. Directives that Enable Conditional Assembly......................................................................................................... 80
Table 5-11. Directives that Define Union or Structure Types..................................................................................................... 81
Table 5-12. Directives that Create or Affect Macros.................................................................................................................. 81
Table 5-13. Directives that Control Diagnostics......................................................................................................................... 81
Table 5-14. Directives that Perform Assembly Source Debug................................................................................................... 81
Table 5-15. Directives that Are Used by the Absolute Lister......................................................................................................81
Table 5-16. Directives that Perform Miscellaneous Functions................................................................................................... 81
Table 6-1. Substitution Symbol Functions and Return Values................................................................................................. 160
Table 6-2. Creating Macros......................................................................................................................................................169
Table 6-3. Manipulating Substitution Symbols......................................................................................................................... 169
Table 6-4. Conditional Assembly............................................................................................................................................. 169
Table 6-5. Producing Assembly-Time Messages.....................................................................................................................169
Table 6-6. Formatting the Listing............................................................................................................................................. 169
Table 8-1. Basic Options Summary......................................................................................................................................... 180
Table 8-2. File Search Path Options Summary........................................................................................................................180
Table 8-3. Command File Preprocessing Options Summary................................................................................................... 180
Table 8-4. Diagnostic Options Summary................................................................................................................................. 180
Table 8-5. Linker Output Options Summary.............................................................................................................................181
Table 8-6. Symbol Management Options Summary................................................................................................................ 181
Table 8-7. Run-Time Environment Options Summary............................................................................................................. 181
Table 8-8. Link-Time Optimization Options Summary..............................................................................................................181
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
9
Table of Contents www.ti.com
Table 8-9. Miscellaneous Options Summary........................................................................................................................... 182
Table 8-10. Predefined C28x Macro Names............................................................................................................................ 186
Table 8-11. Groups of Operators Used in Expressions (Precedence)..................................................................................... 234
Table 10-1. Symbol Attributes in Cross-Reference Listing...................................................................................................... 282
Table 12-1. Basic Hex Conversion Utility Options................................................................................................................... 289
Table 12-2. Boot-Loader Options............................................................................................................................................. 306
Table 12-3. Boot Table Source Formats.................................................................................................................................. 307
Table 12-4. Boot Table Format.................................................................................................................................................307
Table 12-5. Options for Specifying Hex Conversion Formats.................................................................................................. 315
Table A-1. Symbolic Debugging Directives.............................................................................................................................. 334
10 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com Read This First
Preface
Read This First
About This Manual
The TMS320C28x Assembly Language Tools User's Guide explains how to use the following Texas Instruments
Code Generation object file tools:
• Assembler
• Archiver
• Linker
• Library information archiver
• Absolute lister
• Cross-reference lister
• Disassembler
• Object file display utility
• Name utility
• Strip utility
• Hex conversion utility
How to Use This Manual
This book helps you learn how to use the Texas Instruments object file and assembly language tools designed
specifically for the TMS320C28x™ 16-bit devices. This book consists of four parts:
• Introductory information, consisting of Chapter 1 through Chapter 3, gives you an overview of the object
file and assembly language development tools. Chapter 2, in particular, explains object modules and how
they can be managed to help your TMS320C28x application load and run. It is highly recommended that
developers become familiar with what object modules are and how they are used before using the assembler
and linker.
• Assembler description, consisting of Chapter 4 through Chapter 6, contains detailed information about
using the assembler. Chapter 4 and Chapter 5 explain how to invoke the assembler and discuss source
statement format, valid constants and expressions, assembler output, and assembler directives. Chapter 6
focuses on the macro language.
• Linker and other object file tools description, consisting of Chapter 7 through Chapter 12, describes in
detail each of the tools provided with the assembler to help you create executable object files. Chapter 7
provides details about using the archiver to create object libraries. Chapter 8 explains how to invoke the
linker, how the linker operates, and how to use linker directives. Chapter 11 provides a brief overview of some
of the object file utilities that can be useful in examining the content of object files as well as removing symbol
and debug information to reduce the size of a given object file. Chapter 12 explains how to use the hex
conversion utility.
• Additional Reference material, consisting of Appendix A through Appendix D, provides supplementary
information including symbolic debugging directives used by the TMS320C28x C/C++ compiler. A description
of the XML link information file and a glossary are also provided.
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
11
Read This First www.ti.com
Notational Conventions
This document uses the following conventions:
• Program listings, program examples, and interactive displays are shown in a special typeface .
Interactive displays use a bold version of the special typeface to distinguish commands that you enter from
items that the system displays (such as prompts, command output, error messages, etc.).
Here is a sample of C code:
#include <stdio.h>
main()
{ printf("hello world\n");
}
• In syntax descriptions, the instruction, command, or directive is in a bold typeface and parameters are in an
italic typeface. Portions of a syntax that are in bold should be entered as shown; portions of a syntax that are
in italics describe the type of information that should be entered.
• Square brackets ( [ and ] ) identify an optional parameter. If you use an optional parameter, you specify the
information within the brackets. Unless the square brackets are in the bold typeface, do not enter the
brackets themselves. The following is an example of a command that has an optional parameter:
cl2000 [options] [filenames] [--run_linker [link_options] [object files]]
• Braces ( { and } ) indicate that you must choose one of the parameters within the braces; you do not enter the
braces themselves. This is an example of a command with braces that are not included in the actual syntax
but indicate that you must specify either the --rom_model or --ram_model option:
cl2000 --run_linker
[--output_file= name.out] --library= libraryname
{--rom_model | --ram_model} filenames
• In assembler syntax statements, The leftmost character position, column 1, is reserved for the first character
of a label or symbol. If the label or symbol is optional, it is usually not shown. If it is a required parameter, it is
shown starting against the left margin of the box, as in the example below. No instruction, command,
directive, or parameter, other than a symbol or label, can begin in column 1.
symbol
.usect "section name", size in bytes[, alignment]
• Some directives can have a varying number of parameters. For example, the .byte directive can have
multiple parameters. This syntax is shown as [, ..., parameter].
.byte
parameter1[, ... , parametern]
• The TMS320C2800 core is referred to as TMS320C28x or C28x.
• Other symbols and abbreviations used throughout this document include the following:
Symbol
B,b Suffix — binary integer
H, h Suffix — hexadecimal integer
LSB Least significant bit
MSB Most significant bit
0x Prefix — hexadecimal integer
Q, q Suffix — octal integer
Definition
12 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com
Read This First
Related Documentation From Texas Instruments
See the following resources for further information about the TI Code Generation Tools:
• Code Composer Studio: Documentation Overview
• Texas Instruments E2E Community: Software Tools Forum
You can use the following books to supplement this user's guide:
SPRU514 TMS320C28x Optimizing C/C++ Compiler User's Guide. Describes the TMS320C28x C/C++
compiler. This C/C++ compiler accepts ANSI standard C/C++ source code and produces assembly
language source code for the TMS320C28x devices.
SPRU127 TMS320C2xx User's Guide. Discusses the hardware aspects of the TMS320C2xx 16-bit fixed-
point digital signal processors. It describes the architecture, the instruction set, and the on-chip
peripherals.
SPRU430 TMS320C28x DSP CPU and Instruction Set Reference Guide. Describes the central processing
unit (CPU) and the assembly language instructions of the TMS320C28x fixed-point CPU. It also
describes emulation features available on these devices.
SPRU566 TMS320x28xx, 28xxx DSP Peripherals Reference Guide. Describes all the peripherals available
for TMS320x28xx and TMS320x28xxx devices.
SPRUHS1 TMS320C28x Extended Instruction Sets Technical Reference Manual describes the
architecture, pipeline, and instruction sets of the TMU, VCRC, VCU-II, FPU32, and FPU64
accelerators.
SPRAC71 TMS320C28x Embedded Application Binary Interface Application Report. Provides a
specification for the ELF-based Embedded Application Binary Interface (EABI) for the TMS320C28x
family of processors from Texas Instruments. The EABI defines the low-level interface between
programs, program components, and the execution environment, including the operating system if
one is present.
SPRAAO8 Common Object File Format Application Report. Provides supplementary information on the
internal format of COFF object files. Much of this information pertains to the symbolic debugging
information that is produced by the C compiler.
Trademarks
TMS320C28x™ are trademarks of Texas Instruments.
All trademarks are the property of their respective owners.
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
13
Read This First www.ti.com
This page intentionally left blank.
14 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com Introduction to the Software Development Tools
Chapter 1
Introduction to the Software Development Tools
The TMS320C28x™ is supported by a set of software development tools, which includes an optimizing C/C++
compiler, an assembler, a linker, and assorted utilities. This chapter provides an overview of these tools.
The TMS320C28x is supported by the following assembly language development tools:
• Assembler
• Archiver
• Linker
• Library information archiver
• Absolute lister
• Cross-reference lister
• Object file display utility
• Disassembler
• Name utility
• Strip utility
• Hex conversion utility
This chapter shows how these tools fit into the general software tools development flow and gives a brief
description of each tool. For convenience, it also summarizes the C/C++ compiler and debugging tools. For
detailed information on the compiler and debugger, and for complete descriptions of the TMS320C28x, refer to
the books listed in Related Documentation From Texas Instruments.
1.1 Software Development Tools Overview....................................................................................................................16
1.2 Tools Descriptions......................................................................................................................................................17
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
15
C
source
files
C/C++
compiler
Assembler
source
Assembler
Library-build
utility
Run-time-
support
library
Archiver
Archiver
Macro
library
Linker
C2xx
assembler
source
Transition
assistant
Assembler
source
Macro
source
files
Object
files
Library of
object
files
Executable
object file
Debugging
tools
Absolute lister
Hex-conversion
utility
Cross-reference
lister
Object file
utilities
C28x
EPROM
programmer
Post-link
optimizer
Introduction to the Software Development Tools
www.ti.com
1.1 Software Development Tools Overview
Figure 1-1 shows the TMS320C28x software development flow. The shaded portion highlights the most common
development path; the other portions are optional. The other portions are peripheral functions that enhance the
development process.
16 TMS320C28x Assembly Language Tools
v20.12.0.STS
Figure 1-1. TMS320C28x Software Development Flow
Copyright © 2020 Texas Instruments Incorporated
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
www.ti.com
Introduction to the Software Development Tools
1.2 Tools Descriptions
The following list describes the tools that are shown in Figure 1-1:
• The C/C++ compiler accepts C/C++ source code and produces TMS320C28x machine code object
modules. See the TMS320C28x Optimizing C/C++ Compiler User's Guide for more information. A shell
program, an optimizer, and an interlist utility are included in the installation:
– The shell program enables you to compile, assemble, and link source modules in one step.
– The optimizer modifies code to improve the efficiency of C/C++ programs.
– The interlist utility interlists C/C++ source statements with assembly language output to correlate code
produced by the compiler with your source code.
• The assembler translates assembly language source files into machine language object modules. Source
files can contain instructions, assembler directives, and macro directives. You can use assembler directives
to control the assembly process, including the source listing format, data alignment, and section content. See
Chapter 4 through Chapter 6. See the TMS320C28x DSP CPU and Instruction Set Reference Guide for
detailed information on the assembly language instruction set.
• The linker combines object files into a single executable object module. It performs symbolic relocation and
resolves external references. The linker accepts relocatable object modules (created by the assembler) as
input. It also accepts archiver library members and output modules created by a previous linker run. Link
directives allow you to combine object file sections, bind sections or symbols to addresses or within memory
ranges, and define global symbols. See Chapter 8.
• The archiver allows you to collect a group of files into a single archive file, called a library. The most common
use of the archiver is to collect a group of object files into an object library. The linker extracts object library
members to resolve external references during the link. You can also use the archiver to collect several
macros into a macro library. The assembler searches the library and uses the members that are called as
macros by the source file. The archiver allows you to modify a library by deleting, replacing, extracting, or
adding members. See Section 7.1.
• The library information archiver allows you to create an index library of several object file library variants,
which is useful when several variants of a library with different options are available. Rather than refer to a
specific library, you can link against the index library, and the linker will choose the best match from the
indexed libraries. See Section 7.5 for more information about using the archiver to manage the content of a
library.
• You can use the library-build utility to build your own customized run-time-support library. See the
TMS320C28x Optimizing C/C++ Compiler User's Guide for more information.
• The hex conversion utility converts object files to TI-Tagged, ASCII-Hex, Intel, Motorola-S, or Tektronix
object format. Converted files can be downloaded to an EPROM programmer. See Chapter 12.
• The absolute lister uses linked object files to create .abs files. These files can be assembled to produce a
listing of the absolute addresses of object code. See Chapter 9.
• The cross-reference lister uses object files to produce a cross-reference listing showing symbols, their
definition, and their references in the linked source files. See Chapter 10.
• The main product of this development process is a executable object file that can be executed on a
TMS320C28x device. You can use one of several debugging tools to refine and correct your code. Available
products include:
– An instruction-accurate and clock-accurate software simulator
– An XDS emulator
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
17
Introduction to the Software Development Tools
www.ti.com
In addition, the following utilities are provided to help examine or manage the content of a given object file:
• The object file display utility prints the contents of object files and object libraries in either human readable
or XML formats. See Section 11.1.
• The disassembler decodes the machine code from object modules to show the assembly instructions that it
represents. See Section 11.2.
• The name utility prints a list of symbol names for objects and functions defined or referenced in an object file
or object archive. See Section 11.3.
• The strip utility removes symbol table and debugging information from object files and object libraries. See
Section 11.4.
18 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com Introduction to Object Modules
Chapter 2
Introduction to Object Modules
The assembler creates object modules from assembly code, and the linker creates executable object files from
object modules. These executable object files can be executed by a TMS320C28x device.
Object modules make modular programming easier because they encourage you to think in terms of blocks of
code and data when you write an assembly language program. These blocks are known as sections. Both the
assembler and the linker provide directives that allow you to create and manipulate sections.
This chapter focuses on the concept and use of sections in assembly language programs.
2.1 Object File Format Specifications.............................................................................................................................20
2.2 Executable Object Files............................................................................................................................................. 20
2.3 Introduction to Sections............................................................................................................................................ 20
2.4 How the Assembler Handles Sections..................................................................................................................... 21
2.5 How the Linker Handles Sections.............................................................................................................................27
2.6 Symbols.......................................................................................................................................................................29
2.7 Symbolic Relocations................................................................................................................................................ 32
2.8 Loading a Program.....................................................................................................................................................33
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
19
Introduction to Object Modules www.ti.com
2.1 Object File Format Specifications
The TI Code Generation Tools for C28x support the use of either the COFF ABI or the Embedded Application
Binary Interface (EABI). The ABI used is determined by the --abi command-line option. The default ABI is COFF.
The object file format generated by the tools differs depending on the ABI used:
• COFF: These object files conform to the Common Object File Format (COFF). See the Common Object File
Format Application Report (SPRAAO8) for details on this format.
• EABI: These object files conform to the ELF (Executable and Linking Format) binary format, which is used by
EABI. See the TMS320C28x Optimizing C/C++ Compiler User's Guide (SPRU514) for information on using
the EABI ABI. The complete EABI specifications can be found in the C28x Embedded Application Binary
Interface Application Report (SPRAC71. The ELF object files conform to the December 17, 2003 snapshot of
the System V generic ABI (or gABI). This specification is currently maintained by SCO.
2.2 Executable Object Files
The linker can be used to produce static executable object modules. An executable object module has the same
format as object files that are used as linker input. The sections in an executable object module, however, have
been combined and placed in target memory, and the relocations are all resolved.
To run a program, the data in the executable object module must be transferred, or loaded, into target system
memory. See Chapter 3 for details about loading and running programs.
2.3 Introduction to Sections
The smallest unit of an object file is a section. A section is a block of code or data that occupies contiguous
space in the memory map. Each section of an object file is separate and distinct.
COFF format executable object files contain sections.
ELF format executable object files contain segments. An ELF segment is a meta-section. It represents a
contiguous region of target memory. It is a collection of sections that have the same property, such as writeable
or readable. An ELF loader needs the segment information, but does not need the section information. The ELF
standard allows the linker to omit ELF section information entirely from the executable object file.
Object files usually contain three default sections:
.text section
.data section Usually contains initialized data
.ebss section (for COFF)
.bss section (for EABI)
Contains executable code
Usually reserves space for uninitialized variables
1
Note that the .data section is used mainly for EABI. For COFF, the compiler generates .cinit sections that are
used to initialize the .ebss section. The assembler can be used to place initialized data in the .data section for
both COFF and EABI.
The assembler and linker allow you to create, name, and link other kinds of sections. The .text, .data, and .ebss
or .bss sections are archetypes for how sections are handled.
There are two basic types of sections:
Initialized sections
Uninitialized sections Reserve space in the memory map for uninitialized data. The .ebss or .bss section is uninitialized;
Contain data or code. The .text and .data sections are initialized; user-named sections created with
the .sect assembler directive are also initialized.
user-named sections created with the .usect assembler directive are also uninitialized.
1
Some targets allow content other than text, such as constants, in .text sections.
20 TMS320C28x Assembly Language Tools
v20.12.0.STS
Copyright © 2020 Texas Instruments Incorporated
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
www.ti.com
Introduction to Object Modules
Several assembler directives allow you to associate various portions of code and data with the appropriate
sections. The assembler builds these sections during the assembly process, creating an object file organized as
shown in Figure 2-1.
One of the linker's functions is to relocate sections into the target system's memory map; this function is called
placement. Because most systems contain several types of memory, using sections can help you use target
memory more efficiently. All sections are independently relocatable; you can place any section into any allocated
block of target memory. For example, you can define a section that contains an initialization routine and then
allocate the routine in a portion of the memory map that contains ROM. For information on section placement,
see the "Specifying Where to Allocate Sections in Memory" section of the TMS320C28x Optimizing C/C++
Compiler User's Guide .
Figure 2-1 shows the relationship between sections in an object file and a hypothetical target memory. (This
figure shows COFF sections. For EABI, the .ebss section would be .bss.) ROM may be EEPROM, FLASH or
some other type of physical memory in an actual system.
Figure 2-1. Partitioning Memory Into Logical Blocks
2.3.1 Special Section Names
You can use the .sect and .usect directives to create any section name you like, but certain sections are treated
in a special manner by the linker and the compiler's run-time support library. If you create a section with the
same name as a special section, you should take care to follow the rules for that special section.
A few common special sections are:
• .text -- Used for program code.
• .data -- Used for initialized non-const objects (global variables). (Used mainly with EABI)
• .ebss (COFF) or .bss (EABI) -- Used for uninitialized objects (global variables).
• .econst (COFF) or .const (EABI) -- Used for initialized const objects (string constants, variables declared
const).
• .cinit -- Used to initialize C global variables at startup.
• .stack -- Used for the function call stack.
• .esysmem (COFF) or .sysmem (EABI) - Used for the dynamic memory allocation pool.
For more information on sections, see the "Specifying Where to Allocate Sections in Memory" section of the
TMS320C28x Optimizing C/C++ Compiler User's Guide .
2.4 How the Assembler Handles Sections
The assembler identifies the portions of an assembly language program that belong in a given section. The
assembler has the following directives that support this function:
• .bss
• .data
• .sect
• .text
• .usect
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
21
Introduction to Object Modules
www.ti.com
The .bss and .usect directives create uninitialized sections; the .text, .data, and .sect directives create initialized
sections.
You can create subsections of any section to give you tighter control of the memory map. Subsections are
created using the .sect and .usect directives. Subsections are identified with the base section name and a
subsection name separated by a colon; see Section 2.4.6.
Note
If you do not use a section directive, the assembler assembles everything into the .text section.
2.4.1 Uninitialized Sections
Uninitialized sections reserve space in TMS320C28x memory; they are usually placed in RAM. These sections
have no actual contents in the object file; they simply reserve memory. A program can use this space at run time
for creating and storing variables.
Uninitialized data areas are built by using the following assembler directives.
• The .bss directive reserves space in the .bss section.
• The .usect directive reserves space in a specific uninitialized user-named section.
Each time you invoke the .bss or .usect directive, the assembler reserves additional space in the .bss or the
user-named section. The syntax is:
.bss symbol , size in words[, blocking flag[, alignment flag] ]
symbol .usect " section name ", size in words[, blocking flag[, alignment flag] ]
symbol points to the first word reserved by this invocation of the .usect directive. The symbol corresponds to the name of
size in words is an absolute expression (see Section 4.9). The .usect directive reserves size in words words in section name. You
blocking flag is an optional parameter. If you specify a value greater than 0 for this parameter, the assembler allocates size in
alignment flag is an optional parameter. It causes the assembler to allocate the specified size in words on long word boundaries.
section name specifies the user-named section in which to reserve space. See Section 2.4.3.
the variable for which you are reserving space. It can be referenced by any other section and can also be declared
as a global symbol (with the .global directive).
must specify a size; there is no default value.
words contiguously. This means the allocated space does not cross a page boundary unless its size is greater than
a page, in which case the allocated space starts a page boundary. By default, the compiler causes this flag to be set
to 0 so that DP load optimization is used. The compiler provides the "blocked" and "noblocked" variable attributes
for controlling blocking on a per-variable basis. For examples of DP load optimization, see the Tools Insider blog in
TI's E2E community.
The resulting alignment will be on a boundary that is 2 to the power of the specified alignment flag. For example, an
alignment flag of 5 gives an alignment of 2**5, which is 32 words.
Initialized section directives (.text, .data, and .sect) change which section is considered the current section (see
Section 2.4.4). However, the .bss and .usect directives do not change the current section; they simply escape
from the current section temporarily. Immediately after a .bss or .usect directive, the assembler resumes
assembling into whatever the current section was before the directive. The .bss and .usect directives can appear
anywhere in an initialized section without affecting its contents. For an example, see Section 2.4.7.
The .usect directive can also be used to create uninitialized subsections. See Section 2.4.6 for more information
on creating subsections.
The .common directive (EABI only) is similar to directives that create uninitialized data sections, except that
common symbols are created by the linker instead.
2.4.2 Initialized Sections
Initialized sections contain executable code or initialized data. The contents of these sections are stored in the
object file and placed in TMS320C28x memory when the program is loaded. Each initialized section is
independently relocatable and may reference symbols that are defined in other sections. The linker automatically
22 TMS320C28x Assembly Language Tools
v20.12.0.STS
Copyright © 2020 Texas Instruments Incorporated
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
www.ti.com
Introduction to Object Modules
resolves these references. The following directives tell the assembler to place code or data into a section. The
syntaxes for these directives are:
.text
.data
.sect " section name "
The .sect directive can also be used to create initialized subsections. See Section 2.4.6, for more information on
creating subsections.
2.4.3 User-Named Sections
User-named sections are sections that you create. You can use them like the default .text, .data, and .ebss
or .bss sections, but each section with a distinct name is kept distinct during assembly.
For example, repeated use of the .text directive builds up a single .text section in the object file. This .text section
is allocated in memory as a single unit. Suppose there is a portion of executable code (perhaps an initialization
routine) that you want the linker to place in a different location than the rest of .text. If you assemble this segment
of code into a user-named section, it is assembled separately from .text, and you can use the linker to allocate it
into memory separately. You can also assemble initialized data that is separate from the .data section, and you
can reserve space for uninitialized variables that is separate from the .ebss or .bss section.
These directives let you create user-named sections:
• The .usect directive creates uninitialized sections that are used like the .ebss or .bss section. These sections
reserve space in RAM for variables.
• The .sect directive creates initialized sections, like the default .text and .data sections, that can contain code
or data. The .sect directive creates user-named sections with relocatable addresses.
The syntaxes for these directives are:
symbol
.usect " section name ", size in words[, blocking flag[, alignment flag ] ]
.sect " section name "
When using COFF, you can create up to 32,767 distinct named sections. When using EABI, the maximum
number of sections is 232-1 (4294967295).
The section name parameter is the name of the section. For the .usect and .sect directives, a section name can
refer to a subsection; see Section 2.4.6 for details.
Each time you invoke one of these directives with a new name, you create a new user-named section. Each time
you invoke one of these directives with a name that was already used, the assembler resumes assembling code
or data (or reserves space) into the section with that name. You cannot use the same names with different
directives. That is, you cannot create a section with the .usect directive and then try to use the same section
with .sect .
2.4.4 Current Section
The assembler adds code or data to one section at a time. The section the assembler is currently filling is the
current section. The .text, .data, and .sect directives change which section is considered the current section.
When the assembler encounters one of these directives, it stops assembling into the current section (acting as
an implied end of current section command). The assembler sets the designated section as the current section
and assembles subsequent code into the designated section until it encounters another .text, .data, or .sect
directive.
If one of these directives sets the current section to a section that already has code or data in it from earlier in
the file, the assembler resumes adding to the end of that section. The assembler generates only one contiguous
section for each given section name. This section is formed by concatenating all of the code or data which was
placed in that section.
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
23
Introduction to Object Modules
www.ti.com
2.4.5 Section Program Counters
The assembler maintains a separate program counter for each section. These program counters are known as
section program counters, or SPCs.
An SPC represents the current address within a section of code or data. Initially, the assembler sets each SPC
to 0. As the assembler fills a section with code or data, it increments the appropriate SPC. If you resume
assembling into a section, the assembler remembers the appropriate SPC's previous value and continues
incrementing the SPC from that value.
The assembler treats each section as if it began at address 0; the linker relocates the symbols in each section
according to the final address of the section in which that symbol is defined. See Section 2.7 for information on
relocation.
2.4.6 Subsections
A subsection is created by creating a section with a colon in its name. Subsections are logical subdivisions of
larger sections. Subsections are themselves sections and can be manipulated by the assembler and linker.
The assembler has no concept of subsections; to the assembler, the colon in the name is not special. The
subsection .text:rts would be considered completely unrelated to its parent section .text, and the assembler will
not combine subsections with their parent sections.
Subsections are used to keep parts of a section as distinct sections so that they can be separately manipulated.
For instance, by placing each function and object in a uniquely-named subsection, the linker gets a finer-grained
view of the section for memory placement and unused-function elimination.
By default, when the linker sees a SECTION directive in the linker command file like ".text", it will gather .text
and all subsections of .text into one large output section named ".text". You can instead use the SECTION
directive to control the subsection independently. See Section 8.5.5.1 for an example.
You can create subsections in the same way you create other user-named sections: by using the .sect or .usect
directive.
The syntaxes for a subsection name are:
symbol
.usect " section_name : subsection_name ", size in words[, blocking flag[, alignment flag] ]
.sect " section_name : subsection_name "
A subsection is identified by the base section name followed by a colon and the name of the subsection. The
subsection name may not contain any spaces.
A subsection can be allocated separately or grouped with other sections using the same base name. For
example, you create a subsection called _func within the .text section:
.sect ".text:_func"
Using the linker's SECTIONS directive, you can allocate .text:_func separately, or with all the .text sections.
You can create two types of subsections:
• Initialized subsections are created using the .sect directive. See Section 2.4.2.
• Uninitialized subsections are created using the .usect directive. See Section 2.4.1.
Subsections are placed in the same manner as sections. See Section 8.5.5 for information on the SECTIONS
directive.
24 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com
Introduction to Object Modules
2.4.7 Using Sections Directives
Figure 2-2 shows how you can build sections incrementally, using the sections directives to swap back and forth
between the different sections. You can use sections directives to begin assembling into a section for the first
time, or to continue assembling into a section that already contains code. In the latter case, the assembler simply
appends the new code to the code that is already in the section.
The format in Figure 2-2 is a listing file. Figure 2-2 shows how the SPCs are modified during assembly. A line in
a listing file has four fields:
Field 1 contains the source code line counter.
Field 2 contains the section program counter.
Field 3 contains the object code.
Field 4 contains the original source statement.
See Section 4.12 for more information on interpreting the fields in a source listing.
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
25
Introduction to Object Modules
www.ti.com
Figure 2-2. Using Sections Directives Example
26 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com
Introduction to Object Modules
As Figure 2-3 shows, the example code in Figure 2-2 creates four sections:
.text contains twelve 16-bit words of object code.
.data contains seven 16-bit words of initialized data.
.bss reserves ten 16-bit words in memory.
newvars is a user-named section created with the .usect directive; it contains eight 16-bit words in memory.
The second column shows the object code that is assembled into these sections; the first column shows the
source statements that generated the object code.
Figure 2-3. Object Code Generated by the File in Figure 2-2
2.5 How the Linker Handles Sections
The linker has two main functions related to sections. First, the linker uses the sections in object files as building
blocks; it combines input sections to create output sections in an executable output module. Second, the linker
chooses memory addresses for the output sections; this is called placement. Two linker directives support these
functions:
• The MEMORY directive allows you to define the memory map of a target system. You can name portions of
memory and specify their starting addresses and their lengths.
• The SECTIONS directive tells the linker how to combine input sections into output sections and where to
place these output sections in memory.
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
27
Introduction to Object Modules
www.ti.com
Subsections let you manipulate the placement of sections with greater precision. You can specify the location of
each subsection with the linker's SECTIONS directive. If you do not specify a subsection, the subsection is
combined with the other sections with the same base section name. See Section 8.5.5.1.
It is not always necessary to use linker directives. If you do not use them, the linker uses the target processor's
default placement algorithm described in Section 8.7. When you do use linker directives, you must specify them
in a linker command file.
Refer to the following sections for more information about linker command files and linker directives:
• Section 8.5, Linker Command Files
• Section 8.5.4, The MEMORY Directive
• Section 8.5.5, The SECTIONS Directive
• Section 8.7, Default Placement Algorithm
2.5.1 Combining Input Sections
Figure 2-4 provides a simplified example of the process of linking two files together.
Note that this is a simplified example, so it does not show all the sections that will be created or the actual
sequence of the sections. See Section 8.7 for the actual default memory placement map for TMS320C28x. (The
following figure shows sections used by COFF. For EABI, change the .ebss section to .bss.)
Figure 2-4. Combining Input Sections to Form an Executable Object Module
28 TMS320C28x Assembly Language Tools
v20.12.0.STS
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
www.ti.com
Introduction to Object Modules
In Figure 2-4, file1.obj and file2.obj have been assembled to be used as linker input. Each contains
the .text, .data, and .ebss default sections; in addition, each contains a user-named section. The executable
object module shows the combined sections. The linker combines the .text section from file1.obj and the .text
section from file2.obj to form one .text section, then combines the two .data sections and the two .ebss sections,
and finally places the user-named sections at the end. The memory map shows the combined sections to be
placed into memory.
2.5.2 Placing Sections
Figure 2-4 illustrates the linker's default method for combining sections. Sometimes you may not want to use the
default setup. For example, you may not want all of the .text sections to be combined into a single .text section.
Or you may want a user-named section placed where the .data section would normally be allocated. Most
memory maps contain various types of memory (RAM, ROM, EEPROM, FLASH, etc.) in varying amounts; you
may want to place a section in a specific type of memory.
For further explanation of section placement within the memory map, see the discussions in Section 8.5.4 and
Section 8.5.5. See Section 8.7 for the actual default memory allocation map for TMS320C28x.
2.6 Symbols
An object file contains a symbol table that stores information about symbols in the object file. The linker uses this
table when it performs relocation. See Section 2.7.
An object file symbol is a named 32-bit integer value, usually representing an address. A symbol can represent
such things as the starting address of a function, variable, section, or an absolute integer (such as the size of the
stack).
Symbols are defined in assembly by adding a label or a directive such as .set .equ .bss, or .usect.
Symbols have a binding, which is similar to the C concept of linkage. Both COFF and ELF file formats may
contain symbols bound locally and globally. ELF also binds symbols as weak symbols.
• Global symbols are visible to the entire program. The linker does not allow more than one global definition
of a particular symbol; it issues a multiple-definition error if a global symbol is defined more than once. (The
assembler can provide a similar multiple-definition error for local symbols.) A reference to a global symbol
from any object file refers to the one and only allowed global definition of that symbol. Assembly code must
explicitly make a symbol global by adding a .def, .ref, or .global directive. (See Section 2.6.1.)
• Local symbols are visible only within one object file; each object file that uses a symbol needs its own local
definition. References to local symbols in an object file are entirely unrelated to local symbols of the same
name in another object file. By default, a symbol is local. (See Section 2.6.2.)
• Weak symbols (EABI only) are symbols that may be used but not defined in the current module. They may
or may not be defined in another module. A weak symbol is intended to be overridden by a strong (non-weak)
global symbol definition of the same name in another object file. If a strong definition is available, the weak
symbol is replaced by the strong symbol. If no definition is available (that is, if the weak symbol is
unresolved), no error is generated, but the weak variable's address is considered to be null (0). For this
reason, application code that accesses a weak variable must check that its address is not zero before
attempting to access the variable. (See Section 2.6.3.)
Absolute symbols are symbols that have a numeric value. They may be constants. To the linker, such symbols
are unsigned values, but the integer may be treated as signed or unsigned depending on how it is used. The
range of legal values for an absolute integer is 0 to 2^32-1 for unsigned treatment and -2^31 to 2^31-1 for signed
treatment.
In general, common symbols (see .common directive) are preferred over weak symbols.
See Section 4.8 for information about assembler symbols.
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Copyright © 2020 Texas Instruments Incorporated
TMS320C28x Assembly Language Tools
v20.12.0.STS
29
Introduction to Object Modules
www.ti.com
2.6.1 Global (External) Symbols
Global symbols are symbols that are either accessed in the current module but defined in another (an external
symbol) or defined in the current module and accessed in another. Such symbols are visible across object
modules. You must use the .def, .ref, or .global directive to identify a symbol as external:
.def The symbol is defined in the current file and may be used in another file.
.ref The symbol is referenced in the current file, but defined in another file.
.global The symbol can be either of the above. The assembler chooses either .def or .ref as appropriate for each symbol.
The following code fragment illustrates these definitions.
.def x
.ref y
.global z
.global q
x: ADD AR1, #56h
B y, UNC
q: ADD AR1, #56h
B z, UNC
In this example, the .def definition of x says that it is an external symbol defined in this file and that other files
can reference x. The .ref definition of y says that it is an undefined symbol that is defined in another file.
The .global definition of z says that it is defined in some file and available in this file. The .global definition of q
says that it is defined in this file and that other files can reference q.
The assembler places x, y, z, and q in the object file's symbol table. When the file is linked with other object files,
the entries for x and q resolve references to x and q in other files. The entries for y and z cause the linker to look
through the symbol tables of other files for y's and z's definitions.
The linker attempts to match all references with corresponding definitions. If the linker cannot find a symbol's
definition, it prints an error message about the unresolved reference. This type of error prevents the linker from
creating an executable object module.
An error also occurs if the same symbol is defined more than once.
2.6.2 Local Symbols
Local symbols are visible within a single object file. Each object file may have its own local definition for a
particular symbol. References to local symbols in an object file are entirely unrelated to local symbols of the
same name in another object file.
By default, a symbol is local.
2.6.3 Weak Symbols
Weak symbols are symbols that may or may not be defined.
Note
Weak symbols are supported only in EABI mode.
The linker processes symbols that are defined with a "weak" binding differently from symbols that are defined
with global binding. Instead of including a weak symbol in the object file's symbol table (as it would for a global
symbol), the linker only includes a weak symbol in the output of a "final" link if the symbol is required to resolve
an otherwise unresolved reference.
This allows the linker to minimize the number of symbols it includes in the output file's symbol table by omitting
those that are not needed to resolve references. Reducing the size of the output file's symbol table reduces the
time required to link, especially if there are a large number of pre-loaded symbols to link against. This feature is
particularly helpful for OpenCL applications.
30 TMS320C28x Assembly Language Tools
v20.12.0.STS
Copyright © 2020 Texas Instruments Incorporated
SPRU513V – JULY 2001 – REVISED DECEMBER 2020
Submit Document Feedback
Loading...