SPNU118 User guide

SPNU118Z September 1995 – March 2023 66AK2E05 , 66AK2H06 , 66AK2H12 , 66AK2H14 , AM1705 , AM1707 , AM1802 , AM1806 , AM1808 , AM1810 , AM5K2E04 , OMAP-L132 , OMAP-L137 , OMAP-L138 , SM470R1B1M-HT , TMS470R1A288 , TMS470R1A384 , TMS470R1A64 , TMS470R1B1M , TMS470R1B512 , TMS470R1B768

Read This First
1. About This Manual
2. How to Use This Manual
3. Notational Conventions
4. Related Documentation From Texas Instruments
5. Trademarks
1 Introduction to the Software Development Tools
1. 1.1 Software Development Tools Overview
2. 1.2 Tools Descriptions
2 Introduction to Object Modules
1. 2.1 Object File Format Specifications
2. 2.2 Executable Object Files
3. 2.3 Introduction to Sections
  1. 2.3.1 Special Section Names
4. 2.4 How the Assembler Handles Sections
5. 2.5 How the Linker Handles Sections
  1. 2.5.1 Combining Input Sections
  2. 2.5.2 Placing Sections
6. 2.6 Symbols
7. 2.7 Symbolic Relocations
8. 2.8 Loading a Program
3 Program Loading and Running
1. 3.1 Loading
  1. 3.1.1 Load and Run Addresses
  2. 3.1.2 Bootstrap Loading
2. 3.2 Entry Point
3. 3.3 Run-Time Initialization
4. 3.4 Arguments to main
5. 3.5 Run-Time Relocation
6. 3.6 Additional Information
4 Assembler Description
1. 4.1 Assembler Overview
2. 4.2 The Assembler's Role in the Software Development Flow
3. 4.3 Invoking the Assembler
4. 4.4 Controlling Application Binary Interface
5. 4.5 Naming Alternate Directories for Assembler Input
  1. 4.5.1 Using the --include_path Assembler Option
  2. 4.5.2 Using the TI_ARM_A_DIR Environment Variable
6. 4.6 Source Statement Format
7. 4.7 Literal Constants
8. 4.8 Assembler Symbols
9. 4.9 Expressions
10. 4.10 Built-in Functions and Operators
  1. 4.10.1 Built-In Math and Trigonometric Functions
11. 4.11 Unified Assembly Language Syntax Support
12. 4.12 Source Listings
13. 4.13 Debugging Assembly Source
14. 4.14 Cross-Reference Listings
5 Assembler Directives
1. 5.1 Directives Summary
2. 5.2 Directives that Define Sections
3. 5.3 Directives that Change the Instruction Type
4. 5.4 Directives that Initialize Values
5. 5.5 Directives that Perform Alignment and Reserve Space
6. 5.6 Directives that Format the Output Listings
7. 5.7 Directives that Reference Other Files
8. 5.8 Directives that Enable Conditional Assembly
9. 5.9 Directives that Define Union or Structure Types
10. 5.10 Directives that Define Enumerated Types
11. 5.11 Directives that Define Symbols at Assembly Time
12. 5.12 Miscellaneous Directives
13. 5.13 Directives Reference
  1. .align
  2. .asg/.define/.eval
  3. .asmfunc/.endasmfunc
  4. .bits
  5. .bss
  6. .byte/.ubyte/.char/.uchar
  7. .cdecls
  8. .common
  9. .copy/.include
  10. .cstruct/.cunion/.endstruct/.endunion/.tag
  11. .data
  12. .double
  13. .drlist/.drnolist
  14. .elfsym
  15. .emsg/.mmsg/.wmsg
  16. .end
  17. .fclist/.fcnolist
  18. .field
  19. .float
  20. .global/.def/.ref
  21. .group/.gmember/.endgroup
  22. .half/.short/.uhalf/.ushort
  23. .if/.elseif/.else/.endif
  24. .int/.unint/.long/.ulong/.word/.uword
  25. .label
  26. .length/.width
  27. .list/.nolist
  28. .loop/.endloop/.break
  29. .macro/.endm
  30. .mlib
  31. .mlist/.mnolist
  32. .newblock
  33. .option
  34. .page
  35. .retain / .retainrefs
  36. .sect
  37. .set/.equ
  38. .space/.bes
  39. .sslist/.ssnolist
  40. .state16
  41. .state32/.arm
  42. .string/.cstring
  43. .struct/.endstruct/.tag
  44. .symdepend
  45. .tab
  46. .text
  47. .thumb
  48. .title
  49. .unasg/.undefine
  50. .union/.endunion/.tag
  51. .usect
  52. .var
  53. .weak
6 Macro Language Description
1. 6.1 Using Macros
2. 6.2 Defining Macros
3. 6.3 Macro Parameters/Substitution Symbols
4. 6.4 Macro Libraries
5. 6.5 Using Conditional Assembly in Macros
6. 6.6 Using Labels in Macros
7. 6.7 Producing Messages in Macros
8. 6.8 Using Directives to Format the Output Listing
9. 6.9 Using Recursive and Nested Macros
10. 6.10 Macro Directives Summary
7 Archiver Description
1. 7.1 Archiver Overview
2. 7.2 The Archiver's Role in the Software Development Flow
3. 7.3 Invoking the Archiver
4. 7.4 Archiver Examples
5. 7.5 Library Information Archiver Description
8 Linker Description
1. 8.1 Linker Overview
2. 8.2 The Linker's Role in the Software Development Flow
3. 8.3 Invoking the Linker
4. 8.4 Linker Options
5. 8.5 Linker Command Files
6. 8.6 Linker Symbols
7. 8.7 Default Placement Algorithm
  1. 8.7.1 How the Allocation Algorithm Creates Output Sections
  2. 8.7.2 Reducing Memory Fragmentation
8. 8.8 Using Linker-Generated Copy Tables
9. 8.9 Linker-Generated CRC Tables
  1. 8.9.1 Using the crc_table() Operator in the SECTIONS Directive
  2. 8.9.2 A Note on the TMS570_CRC64_ISO Algorithm
10. 8.10 Partial (Incremental) Linking
11. 8.11 Linking C/C++ Code
12. 8.12 Linker Example
9 Absolute Lister Description
1. 9.1 Producing an Absolute Listing
2. 9.2 Invoking the Absolute Lister
3. 9.3 Absolute Lister Example
10Cross-Reference Lister Description
1. 10.1 Producing a Cross-Reference Listing
2. 10.2 Invoking the Cross-Reference Lister
3. 10.3 Cross-Reference Listing Example
11Object File Utilities
1. 11.1 Invoking the Object File Display Utility
2. 11.2 Invoking the Disassembler
3. 11.3 Invoking the Name Utility
4. 11.4 Invoking the Strip Utility
12Hex Conversion Utility Description
1. 12.1 The Hex Conversion Utility's Role in the Software Development Flow
2. 12.2 Invoking the Hex Conversion Utility
  1. 12.2.1 Invoking the Hex Conversion Utility From the Command Line
  2. 12.2.2 Invoking the Hex Conversion Utility With a Command File
3. 12.3 Understanding Memory Widths
4. 12.4 The ROMS Directive
  1. 12.4.1 When to Use the ROMS Directive
  2. 12.4.2 An Example of the ROMS Directive
5. 12.5 The SECTIONS Directive
6. 12.6 The Load Image Format (--load_image Option)
  1. 12.6.1 Load Image Section Formation
  2. 12.6.2 Load Image Characteristics
7. 12.7 Excluding a Specified Section
8. 12.8 Assigning Output Filenames
9. 12.9 Image Mode and the --fill Option
10. 12.10 Array Output Format
11. 12.11 Building a Table for an On-Chip Boot Loader
12. 12.12 Using Secure Flash Boot on TMS320F2838x Devices
13. 12.13 Controlling the ROM Device Address
14. 12.14 Control Hex Conversion Utility Diagnostics
15. 12.15 Description of the Object Formats
13Sharing C/C++ Header Files With Assembly Source
1. 13.1 Overview of the .cdecls Directive
2. 13.2 Notes on C/C++ Conversions
3. 13.3 Notes on C++ Specific Conversions
4. 13.4 Special Assembler Support
A Symbolic Debugging Directives
1. A.1 DWARF Debugging Format
2. A.2 Debug Directive Syntax
B XML Link Information File Description
1. B.1 XML Information File Element Types
2. B.2 Document Elements
  1. B.2.1 Header Elements
  2. B.2.2 Input File List
  3. B.2.3 Object Component List
  4. B.2.4 Logical Group List
  5. B.2.5 Placement Map
  6. B.2.6 Far Call Trampoline List
  7. B.2.7 Symbol Table
C Hex Conversion Utility Examples
1. C.1 Scenario 1 -- Building a Hex Conversion Command File for a Single 8-Bit EPROM
  1. C.1.1 Linker Command File and Link Map for Scenario 1
  2. 482
  3. C.1.2 Hex Conversion Command File for Scenario 1
  4. 484
  5. C.1.3 Contents of Hex Map File example1.mxp
2. C.2 Scenario 2 -- Building a Hex Conversion Command File for 16-BIS Code
  1. C.2.1 Linker Command File for Scenario 2
  2. 488
  3. C.2.2 Hex Conversion Command File for Scenario 2
  4. 490
  5. C.2.3 Contents of Hex Map File example2.mxp
3. C.3 Scenario 3 -- Building a Hex Conversion Command File for Two 8-Bit EPROMs
  1. C.3.1 Linker Command File for Scenario 3
  2. 494
  3. C.3.2 Hex Conversion Command File for Scenario 3
  4. 496
  5. C.3.3 Contents of Hex Map File example3.mxp
  6. 498
D Glossary
1. D.1 Terminology
E Revision History
E Earlier Revisions

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:

armcl [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:

armcl --run_linker {--rom_model \| --ram_model} filenames [--output_file=name.out]
	--library= libraryname

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].

.byteparameter₁[, ... , parameter_n]

The TMS470 and TMS570 devices are collectively referred to as ARM.
The ARM 16-bit instruction set is referred to as 16-BIS.
The ARM 32-bit instruction set is referred to as 32-BIS.

Other symbols and abbreviations used throughout this document include the following:

Symbol	Definition
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