Texas instruments TI-89, TI-92 PLUS Assembler Reference Manual
TI-89 / TI-92 Plus
Sierra C™ Assembler Reference Manual, Beta Version .02
Important information
Texas Instruments makes no warranty, either expressed or implied, including but not limited to
any implied warranties of merchantability and fitness for a particular purpose, regarding any
programs or book materials and makes such materials available solely on an “as-is” basis.
In no event shall Texas Instruments be liable to anyone for special, collateral, incidental, or
consequential damages in connection with or arising out of the purchase or use of these
materials, and the sole and exclusive liability of Texas Instruments, regardless of the form of
action, shall not exceed the purchase price of this product. Moreover, Texas Instruments shall
not be liable for any claim of any kind whatsoever against the use of these materials by any
other party.
The latest version of this Guide, along with all other up-to-date information for developers, is
available at www.ti.com/calc/developers/.
© 2000, 2001 Texas Instruments
, TI-GRAPH LINK, and TI
Sierra C is a trademark of Sierra Systems.
FLASH
Studio are trademarks of Texas Instruments Incorporated.
Table of Contents
1. General Information..................................................................................5
1.1. Introduction ..........................................................................................................5
1.2. Command Line Wildcard Expansion....................................................................6
1.3. Environment Variables.........................................................................................7
1.4. Object File Format................................................................................................8
1.4.1. Definitions and Conventions.................................................................................10
1.4.1.1. Sections...................................................................................................10
1.4.1.2. Physical and Virtual Addresses...............................................................10
1.4.1.3. C Language COFF File Structures..........................................................10
1.4.2. File Header...........................................................................................................11
i
1.4.2.1. Magic Number.........................................................................................11
1.4.2.2. Optional Header Size ..............................................................................11
1.4.2.3. Flags........................................................................................................12
1.4.3. Optional Header ...................................................................................................12
1.4.4. Section Headers...................................................................................................13
1.4.5. Relocation Information..........................................................................................14
1.4.5.1. Relocation................................................................................................15
1.4.5.2. Complex Relocation ................................................................................16
1.4.6. Line Number Information......................................................................................17
1.4.7. Symbol Table........................................................................................................18
1.4.7.1. Special Symbols......................................................................................19
1.4.7.2. Inner Blocks.............................................................................................20
1.4.7.3. Symbols and Functions...........................................................................21
1.4.8. Symbol Table Entries ...........................................................................................21
1.4.8.1. Symbol Names........................................................................................22
1.4.8.2. Storage Class..........................................................................................22
1.4.8.3. Storage Classes for Special Symbols......................................................24
1.4.8.4. Symbol Value Field..................................................................................25
1.4.8.5. Section Number Field..............................................................................26
1.4.8.6. Section Numbers and Storage Classes...................................................27
1.4.8.7. Type Entry...............................................................................................28
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
ii
1.4.8.8. Type Entries and Storage Classes..........................................................30
1.4.9. Auxiliary Table Entries..........................................................................................31
1.4.9.1. Filenames................................................................................................32
1.4.9.2. Sections...................................................................................................32
1.4.9.3. Functions.................................................................................................32
1.4.9.4. Beginning of Blocks and Functions .........................................................33
1.4.9.5. End of Blocks and Functions...................................................................33
1.4.9.6. Arrays......................................................................................................34
1.4.9.7. Tag Names..............................................................................................34
1.4.9.8. End of Structures.....................................................................................35
1.4.9.9. Names Related to Structures, Unions, and Enumerations......................35
1.4.10. String Table........................................................................................................36
Table of Contents
2. Compiler.................................................................................................41
2.1. Introduction ........................................................................................................41
2.2. Invoking the Compiler ........................................................................................41
2.3. Command Line Flags.........................................................................................41
2.3.1. Usage...................................................................................................................42
2.3.2. Default Behavior...................................................................................................42
2.3.3. Description of Flags..............................................................................................43
2.4. Pragma Directives..............................................................................................51
2.5. Translation Limits...............................................................................................52
2.6. Reserved Keywords...........................................................................................53
2.6.1. ASM Keyword.......................................................................................................53
2.6.2. ANSI C Keywords.................................................................................................53
2.7. Constants...........................................................................................................54
2.7.1. Floating-Point Constants......................................................................................54
2.7.2. Integer Constants.................................................................................................54
2.7.3. Enumeration Constants........................................................................................55
2.7.4. Character Constants.............................................................................................56
2.8. Character Strings...............................................................................................57
2.9. Types and Representations...............................................................................58
2.9.1. Integer Types........................................................................................................59
2.9.2. Integer Representations.......................................................................................59
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Table of Contents
2.9.3. Floating-Point Types................................................................................60
2.9.4. Floating-Point Representations................................................................61
2.9.5. Enumeration Types..................................................................................63
2.9.6. Bit Field Description.................................................................................65
2.9.7. Bit Field Internal Representation..............................................................66
2.9.8. Const Type Specifier................................................................................67
2.9.9. Volatile Type Specifier .............................................................................68
2.9.10. Touch Operator......................................................................................69
2.9.11. Void Type Specifier................................................................................69
2.9.12. Void Pointer (void *)...............................................................................70
2.10. Conversions.....................................................................................................70
2.10.1. General Considerations .........................................................................70
2.10.2. Integer Types.........................................................................................71
iii
2.10.3. Floating-Point and Integer Types...........................................................71
2.10.4. Floating-Point Types..............................................................................72
2.10.5. Usual Arithmetic Conversions................................................................72
2.10.6. Restrictions ............................................................................................73
2.11. Function Calling Conventions ..........................................................................73
2.11.1. Declarations and Definitions ..................................................................74
2.11.1.1. Function Prototypes.........................................................................................74
2.11.1.2. Old-Style Declarations.....................................................................................75
2.11.1.3. Mixing Prototype and Old-Style Declarations ..................................................76
2.11.2. Passing Argument Values......................................................................77
2.11.3. Accessing Parameters...........................................................................78
2.11.4. Returning Values....................................................................................79
2.11.5. Register Usage ......................................................................................81
2.12. Compiler-Generated Function Calls.................................................................81
2.12.1. Internal Integer Arithmetic Functions .....................................................82
2.12.2. Internal Floating-Point Functions ...........................................................83
2.12.3. Debugging Functions.............................................................................86
2.13. Sections ...........................................................................................................87
2.14. Static Storage Initialization...............................................................................87
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
iv
Table of Contents
2.15. Compiler Algorithms.........................................................................................90
2.15.1. Register Allocation.................................................................................90
2.15.2. Switch Statements .................................................................................92
2.16. The C Preprocessor.........................................................................................93
2.16.1. Source File Inclusion..............................................................................94
2.16.2. Conditional Compilation.........................................................................94
2.16.3. Macro Replacement...............................................................................96
2.16.3.1. Argument Substitution .....................................................................................96
2.16.3.2. The # Operator (stringizing).............................................................................97
2.16.3.3. The ## Operator (concatenation).....................................................................97
2.16.3.4. Rescanning and Further Replacement............................................................97
2.16.4. Macro Redefinition.................................................................................97
2.16.5. Macro Examples ....................................................................................98
2.16.6. Line and Name Control..........................................................................99
2.16.7. Error Directive......................................................................................100
2.16.8. Pragma Directive..................................................................................100
2.16.9. Trigraph Sequences.............................................................................100
2.16.10. Comment Delimiters...........................................................................101
2.16.11. Predefined Macro Names ..................................................................101
2.17. Compiler Error Messages ..............................................................................102
3. Assembler............................................................................................129
3.1. Introduction ......................................................................................................129
3.1.1. Overview................................................................................................129
3.1.2. Prerequisite Reading..............................................................................130
3.1.3. Notational Conventions..........................................................................131
3.2. Invocation.........................................................................................................131
3.2.1. Command Line Syntax...........................................................................132
3.2.2. Command Line Flags.............................................................................132
3.2.3. File Name Conventions..........................................................................136
3.2.4. Environment Variables...........................................................................136
3.2.5. Invocation Examples..............................................................................137
3.3. Assembly Language.........................................................................................137
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Table of Contents
3.3.1. Overview................................................................................................138
3.3.2. Assembler Statements...........................................................................138
3.3.2.1. Statement Syntax (asm68) ..............................................................................138
3.3.2.2. Statement Syntax (asm68k) ............................................................................139
3.3.3. Character Set.........................................................................................140
3.3.4. Sections .................................................................................................140
3.3.4.1. Section Types..................................................................................................140
3.3.4.2. Creating Sections ............................................................................................141
3.3.4.3. Location Counter .............................................................................................141
3.3.4.4. Structure Templates ........................................................................................141
3.3.5. Symbols .................................................................................................141
3.3.5.1. Symbol Syntax.................................................................................................142
3.3.5.2. Labels..............................................................................................................143
3.3.5.3. Symbol Assignment.........................................................................................143
v
3.3.5.4. Comm and Lcomm Symbols............................................................................144
3.3.5.5. Undefined Symbols..........................................................................................144
3.3.5.6. Compiler Locals...............................................................................................145
3.3.5.7. Floating-Point Symbols....................................................................................145
3.3.6. Constants...............................................................................................145
3.3.6.1. Integer Constants ............................................................................................145
3.3.6.2. Character Constants........................................................................................146
3.3.6.3. Floating-Point Constants .................................................................................148
3.3.7. Expressions............................................................................................148
3.3.7.1. Operands.........................................................................................................148
3.3.7.2. Operators.........................................................................................................149
3.3.7.3. Expression Evaluation .....................................................................................150
3.4. Instruction Set..................................................................................................152
3.4.1. Syntax....................................................................................................152
3.4.2. Instruction Sizing....................................................................................152
3.4.3. Instruction Optimization..........................................................................153
3.5. Effective Addressing Modes.............................................................................155
3.5.1. Overview................................................................................................155
3.5.2. Terminology ...........................................................................................157
3.5.3. Effective Address Syntax.......................................................................158
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
vi
Table of Contents
3.5.4. Addressing Mode Selection ...................................................................160
3.5.4.1. PC-relative Coercion........................................................................................160
3.5.4.2. Displacement Sizing ........................................................................................161
3.5.4.3. Mode selection.................................................................................................162
3.6. Asm68 Assembler Directives ...........................................................................163
3.6.1. Asm68 Section Directives......................................................................164
3.6.2. Asm68 Symbol Directives......................................................................165
3.6.3. Asm68 Data/Fill Directives.....................................................................166
3.6.4. Asm68 Control Directives.......................................................................167
3.6.5. Asm68 Output Directives .......................................................................167
3.6.6. Asm68 Debugging Directives.................................................................168
3.6.7. Asm68 Directive Reference ...................................................................168
3.7. Asm68k Assembler Directives .........................................................................209
3.7.1. Asm68k Section Directives ....................................................................210
3.7.2. Asm68k Symbol Directives ....................................................................211
3.7.3. Asm68k Data/Fill Directives...................................................................212
3.7.4. Asm68k Control Directives.....................................................................213
3.7.5. Asm68k Output Directives......................................................................214
3.7.6. Asm68k Debugging Directives...............................................................214
3.7.7. Asm68k Directive Reference..................................................................215
3.8. Asm68k Macros ...............................................................................................271
3.8.1. User-Defined Macros.............................................................................271
3.8.1.1. Macro Definition...............................................................................................271
3.8.1.2. Macro Invocation .............................................................................................272
3.8.1.3. Parameters......................................................................................................273
3.8.1.4. Local Labels.....................................................................................................274
3.8.1.5. NARG Symbol..................................................................................................274
3.8.1.6. MEXIT Directive...............................................................................................274
3.8.1.7. Macro Examples..............................................................................................275
3.8.2. Structured Control Macros.....................................................................278
3.8.2.1. Structured Control Expressions.......................................................................278
3.8.2.2. Macro Invocation .............................................................................................280
3.8.2.3. Structured Control Reference..........................................................................280
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Table of Contents
vii
3.9. Instruction Set Summary..................................................................................289
4. Linker ...................................................................................................299
4.1. Introduction ......................................................................................................299
4.2. Link68 Inputs and Outputs...............................................................................299
4.3. Options.............................................................................................................300
4.3.1. Library Search Options ..........................................................................300
4.3.2. Option Flags...........................................................................................300
4.4. Object Files......................................................................................................302
4.4.1. Sections .................................................................................................302
4.5. Symbols ...........................................................................................................302
4.6. Relocation Entries............................................................................................303
4.7. Relocation Hole Compression..........................................................................303
4.8. Reserved Symbols...........................................................................................305
5. Utilities..................................................................................................309
5.1. Symbol Table Name Utility...............................................................................309
5.2. Object File Size Utility ......................................................................................313
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
viii
Table of Contents
Figures
Figure 1.1: Partial Sierra C Directory Structure ............................................................................7
Figure 2.1: Internal Integer Representations ..............................................................................60
Figure 2.2: Internal TI BCD Floating-Point Representation ........................................................61
Figure 2.3: Special Internal Floating-Point Representations.......................................................63
Figure 2.4: Floating-Point Emulation Code Word .......................................................................84
Figure 3.1: Expression Evaluation............................................................................................150
Figure 3.2: Instruction Sizing (asm68)......................................................................................152
Tables
Table 1.1: Environment Variables.................................................................................................7
Table 1.2: Object File Layout........................................................................................................9
Table 1.3: File Header Contents.................................................................................................11
Table 1.4: File Header Flags.......................................................................................................12
Table 1.5: Sierra Systems Optional Header Contents................................................................12
Table 1.6: Section Header Contents...........................................................................................13
Table 1.7: Section Header Flags ................................................................................................14
Table 1.8: Relocation Section Contents......................................................................................15
Table 1.9: Relocation Types.......................................................................................................15
Table 1.10: Complex Relocation Entries.....................................................................................16
Table 1.11: Line Number Grouping.............................................................................................17
Table 1.12: Line Number Section Contents................................................................................17
Table 1.13: COFF Symbol Table................................................................................................18
Table 1.14: Special Symbols in the Symbol Table......................................................................19
Table 1.15: Example Symbol Table for Functions and Nested Blocks .......................................20
Table 1.16: Symbol Table Entry..................................................................................................21
Table 1.17: Storage Classes.......................................................................................................23
Table 1.18: Storage Class of Special Symbols...........................................................................24
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Table of Contents
ix
Table 1.19: Storage Class and Value.........................................................................................25
Table 1.20: Section Number.......................................................................................................26
Table 1.21: Section Number and Storage Class.........................................................................27
Table 1.22: Fundamental Types.................................................................................................28
Table 1.23: Derived Types..........................................................................................................29
Table 1.24: Type Entries by Storage Class ................................................................................30
Table 1.25: Auxiliary Symbol Table Entries................................................................................31
Table 1.26: Auxiliary Symbol Entry for Filenames......................................................................32
Table 1.27: Auxiliary Symbol Entry for Sections.........................................................................32
Table 1.28: Auxiliary Symbol Entry for Functions.......................................................................33
Table 1.29: Auxiliary Symbol Entry for Beginning of Blocks and Functions................................33
Table 1.30: Auxiliary Symbol Entry for End of Blocks and Functions .........................................33
Table 1.31: Auxiliary Symbol Entry for Arrays ............................................................................34
Table 1.32: Auxiliary Symbol Entry for Tag Names....................................................................34
Table 1.33: Auxiliary Symbol Entry for End of Structures...........................................................35
Table 1.34: Auxiliary Symbol Entry for Structures, Unions, Enumerations.................................35
Table 1.35: Example String Table...............................................................................................36
Table 2.1: Escape Characters ....................................................................................................56
Table 2.2: Character Constants..................................................................................................57
Table 2.3: Integer Types.............................................................................................................59
Table 2.4: Determination of Argument Size................................................................................78
Table 2.5: Integer Arithmetic Functions......................................................................................82
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
x
Table of Contents
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Section 1: General Information
1. General Information..................................................................................5
1.1. Introduction ..........................................................................................................5
1.2. Command Line Wildcard Expansion....................................................................6
1.3. Environment Variables.........................................................................................7
1.4. Object File Format................................................................................................8
1.4.1. Definitions and Conventions ................................................................................10
1.4.1.1. Sections..................................................................................................10
1.4.1.2. Physical and Virtual Addresses..............................................................10
1.4.1.3. C Language COFF File Structures.........................................................10
1.4.2. File Header...........................................................................................................11
1
1.4.2.1. Magic Number.........................................................................................11
1.4.2.2. Optional Header Size ..............................................................................11
1.4.2.3. Flags........................................................................................................12
1.4.3. Optional Header ...................................................................................................12
1.4.4. Section Headers...................................................................................................13
1.4.5. Relocation Information..........................................................................................14
1.4.5.1. Relocation................................................................................................15
1.4.5.2. Complex Relocation ................................................................................16
1.4.6. Line Number Information......................................................................................17
1.4.7. Symbol Table........................................................................................................18
1.4.7.1. Special Symbols......................................................................................19
1.4.7.2. Inner Blocks.............................................................................................20
1.4.7.3. Symbols and Functions...........................................................................21
1.4.8. Symbol Table Entries ...........................................................................................21
1.4.8.1. Symbol Names........................................................................................22
1.4.8.2. Storage Class..........................................................................................22
1.4.8.3. Storage Classes for Special Symbols......................................................24
1.4.8.4. Symbol Value Field..................................................................................25
1.4.8.5. Section Number Field..............................................................................26
1.4.8.6. Section Numbers and Storage Classes...................................................27
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
2 Section 1: General Information
1.4.8.7. Type Entry...............................................................................................28
1.4.8.8. Type Entries and Storage Classes..........................................................30
1.4.9. Auxiliary Table Entries..........................................................................................31
1.4.9.1. Filenames................................................................................................32
1.4.9.2. Sections...................................................................................................32
1.4.9.3. Functions.................................................................................................32
1.4.9.4. Beginning of Blocks and Functions .........................................................33
1.4.9.5. End of Blocks and Functions...................................................................33
1.4.9.6. Arrays......................................................................................................34
1.4.9.7. Tag Names..............................................................................................34
1.4.9.8. End of Structures.....................................................................................35
1.4.9.9. Names Related to Structures, Unions, and Enumerations......................35
1.4.10. String Table........................................................................................................36
Figures
Figure 1.1: Partial Sierra C Directory Structure ............................................................................7
Tables
Table 1.1: Environment Variables.................................................................................................7
Table 1.2: Object File Layout........................................................................................................9
Table 1.3: File Header Contents.................................................................................................11
Table 1.4: File Header Flags.......................................................................................................12
Table 1.5: Sierra Systems Optional Header Contents................................................................12
Table 1.6: Section Header Contents...........................................................................................13
Table 1.7: Section Header Flags ................................................................................................14
Table 1.8: Relocation Section Contents......................................................................................15
Table 1.9: Relocation Types.......................................................................................................15
Table 1.10: Complex Relocation Entries.....................................................................................16
Table 1.11: Line Number Grouping.............................................................................................17
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Section 1: General Information
3
Table 1.12: Line Number Section Contents................................................................................17
Table 1.13: COFF Symbol Table................................................................................................18
Table 1.14: Special Symbols in the Symbol Table......................................................................19
Table 1.15: Example Symbol Table for Functions and Nested Blocks .......................................20
Table 1.16: Symbol Table Entry..................................................................................................21
Table 1.17: Storage Classes.......................................................................................................23
Table 1.18: Storage Class of Special Symbols...........................................................................24
Table 1.19: Storage Class and Value.........................................................................................25
Table 1.20: Section Number.......................................................................................................26
Table 1.21: Section Number and Storage Class.........................................................................27
Table 1.22: Fundamental Types.................................................................................................28
Table 1.23: Derived Types..........................................................................................................29
Table 1.24: Type Entries by Storage Class ................................................................................30
Table 1.25: Auxiliary Symbol Table Entries................................................................................31
Table 1.26: Auxiliary Symbol Entry for Filenames......................................................................32
Table 1.27: Auxiliary Symbol Entry for Sections.........................................................................32
Table 1.28: Auxiliary Symbol Entry for Functions.......................................................................33
Table 1.29: Auxiliary Symbol Entry for Beginning of Blocks and Functions................................33
Table 1.30: Auxiliary Symbol Entry for End of Blocks and Functions .........................................33
Table 1.31: Auxiliary Symbol Entry for Arrays ............................................................................34
Table 1.32: Auxiliary Symbol Entry for Tag Names....................................................................34
Table 1.33: Auxiliary Symbol Entry for End of Structures...........................................................35
Table 1.34: Auxiliary Symbol Entry for Structures, Unions, Enumerations.................................35
Table 1.35: Example String Table...............................................................................................36
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
4 Section 1: General Information
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
1. General Information
1.1. Introduction
This manual describes the Sierra tools, including the compiler, assembler, and
linker invoked by the TI
(apps) and Assembly Language Programs (ASMs) for the TI-89 / TI-92 Plus
calculators, and other Plusutilities that are available to the developer. They were
developed by Sierra Systems to support certain Motorola processors and
coprocessors and IEEE format floating-point numbers. Under license from Sierra
Systems, Texas Instruments has modified this software to support TI BCD
floating-point numbers, and support for coprocessors has been removed.
Although the software has not been modified to exclude support for processors
other than the 68000, the 68000 is the only processor supported by Texas
Instruments. The license from Texas Instruments to use these products is
restricted to development of software that is targeted to execute only on TI
calculators.
FLASH
Studio™ for development of Flash applications
5
Typically, the TI
assembler, and linker but information is included in the various sections to enable
developers to use them directly from the command line or create their own
makefile if they wish, although this is not encouraged.
Section 1 contains information that applies to all the tools and describes the
format of the object file generated.
Section 2 discusses features of the Sierra Systems C compiler,
include number formats, function calls, integer and floating-point arithmetic,
sections, register allocation, macros, possible error messages, and many others.
Section 3 describes both Sierra Systems assemblers:
the TI
wish to take advantage of the macro support it provides. Explanations of
assembler syntax, symbols, constants, expression evaluation, addressing
modes, and complete descriptions of assembler directives for both assemblers
and the
Section 4 is a brief discussion of the Sierra Systems linker,
its features including relocation hole compression.
Section 5 describes the Sierra Systems utilities
part of the TI-89 / TI-92 Plus SDK for use by developers.
FLASH
asm68k
FLASH
Studio, and
macros are in this section.
Studio will handle all invocations of the compiler,
. These
, and some of
, provided as
asm68k
com68
asm68
which is included for developers who may
and
nm68
which is invoked by
link68
size68
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
6
Section 1: General Information
Conventions used throughout this manual include:
text is used for names of functions, routines, files, keywords, directives,
Bold
•
macros, flags, and registers. It is also used occasionally for emphasis.
•
•
The
Courier
Italicized
font is used to distinguish assembly or C program text.
text indicates an input parameter that should be replaced by actual
data when used in code or entered on the command line.
Brackets ( [ ] ) enclose optional items.
•
The vertical bar ( | ) indicates that the separated items are alternatives.
•
1.2. Command Line Wildcard Expansion
A number of Sierra C™ utilities expand wildcards in command line filenames.
Wildcard characters are defined as follows:
*
?
[
char_set
Match zero or more characters, where characters matched may be any
character except the period (
string matches files with and without extensions.
Match any character except the period (.).
]
Match any character in the character set
listed individually or as members of a range. A range is denoted by a
hyphen (
and all characters lexically between them.
-
) separated pair of characters; it includes the two characters
.
). Dot-star (.*) at the end of a wildcard
char_set
. Characters can be
The following are examples of wildcard expansions:
*.*
*
*.?*
*.c *.s
*.[cs]
Match all filenames in the current directory.
Match all filenames without extensions in the current directory.
Match all filenames with extensions in the current directory.
Match all filenames with extensions of .c or .s in the current directory.
Same as
*.c *.s
c:\doc\version[0-9a-f].doc
Match all filenames in the subdirectory
version followed by a hexadecimal digit and a
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
with a base name of
c:\doc
extension.
.doc
Beta Version February 2, 2001
Section 1: General Information
The following Sierra C utilities support command line wildcard expansion:
7
nm68
size68
Symbol Table Name Utility
Object File Size Utility
1.3. Environment Variables
Some Sierra C utilities need to know the location of certain standard directories
to locate various files. For example, the compiler must know where to search for
files specified by the
#include
information varies depending on the installation, the utilities examine
environment variables to obtain information on the locations of these standard
directories.
Figure 1.1 shows the default standard include (
executable (
), and temporary (
bin
subdirectory names to the directory specified by the
variable. The
for the TI
FLASH
SIERRA
environment variable will be set when the setup program
Studio is executed. The
set before using any of the Sierra utilities.
sierra
filename
tmp
preprocessor directive. Since this
include
), standard library (
lib
),
) directories that are created by appending
environment
SIERRA
SIERRA
environment variable must be
include lib bin tmp
Figure 1.1: Partial Sierra C Directory Structure
Table 1.1 lists the environment variables referenced by Sierra C utilities together
with the utilities that reference the variables and the files that are referenced.
Variable Utility Files referenced
INCLUDE68 com68
LIB68 link68
link68
Table 1.1: Environment Variables
standard include files
standard libraries
default configuration file
Depending on which environment variables are set, the utilities that generate
temporary files will put their files in one of four places. The three environment
variables
TMP68, TMP
search terminating after the first defined variable is located. If either
is defined, the directory specified by that environment variable is used to
TMP
hold temporary files. If the
, and
SIERRA
SIERRA
environment variable is the only variable
are searched for in the order listed with the
TMP68
or
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
8
Section 1: General Information
defined, the
subdirectory located under the directory specified by
tmp
used to hold temporary files. If none of the three environment variables is
specified, the current directory is used to hold temporary files.
The C preprocessor searches for the two environment variables
SIERRA
directories. If
in the order listed to determine the locations of the standard include
INCLUDE68
is defined, the semicolon-separated list of one or more
directory paths defines the standard include directories. If the
environment variable is the only variable defined, the
located under the directory specified by
directory.
Utilities that search for files in standard include directories search for the two
environment variables
LIB68
locations of the standard include directories. If
semicolon-separated list of one or more directory paths defines the standard
library directories. If the
defined, the
subdirectory located under the directory specified by
lib
SIERRA
used as the standard library directory.
1.4. Object File Format
INCLUDE68
SIERRA
subdirectory
and
SIERRA
SIERRA
include
is used as the standard include
in the order listed to determine the
LIB68
is defined, the
environment variable is the only variable
SIERRA
SIERRA
is
and
is
This section describes the Common Object File Format (COFF) used by
TI
FLASH
assemblers and linker, and recognized by TI
Studio. COFF is the format of the object files created by the
FLASH
Studio and various object
file examination utilities. COFF is a standard file format and the Sierra Systems
implementation (with extensions disabled, -c assembler command line flag)
completely conforms to the format recognized by the AT&T UNIX System V
operating system.
COFF is ideally suited for developing embedded applications. Space is provided
for symbol and line number information used by debuggers and other
applications. Executable files can be divided into numerous independent sections
to allow support for systems with highly fragmented address spaces.
An object file contains the following:
A file header
•
Optional header information
•
A table of section headers
•
Data corresponding to the section header
•
Relocation information
¦
Line numbers
¦
A symbol table
¦
A string table
¦
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Section 1: General Information
Table 1.2 shows the overall object file structure.
FILE HEADER
Optional Information
Section 1 Header
. . .
Section n Header
Raw Data for Section 1
. . .
Raw Data for Section n
Relocation Info. for Section 1
. . .
Relocation Info. for Section n
Line Numbers for Section 1
. . .
9
Line Numbers for Section n
SYMBOL TABLE
STRING TABLE
Table 1.2: Object File Layout
Some or all of the last four sections (relocation, line number, symbol table, and
string table) may be missing from the final executable file. If the program is linked
with the -s flag, all four of these sections will be absent. The line number
information does not appear unless the program is compiled with the -q or
debug flag or assembled with the -L line number flag. If there are no unresolved
external symbols after linking, the relocation information is no longer needed and
is thus absent. If there are no symbols with names longer than eight characters,
the string table is not needed and is thus absent.
-q1
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
10
1.4.1. Definitions and Conventions
Before continuing, you should become familiar with the following terms and
conventions.
1.4.1.1. Sections
A section is the smallest portion of an object file that is relocated and able to be
positioned at an independent location in memory. In the default case, there are
three named sections with the names
executable file, there is also usually a fourth section with the name
TI-89 / TI-92 Plus apps and ASMs also have a
section is unused. Additional named and unnamed sections, up to a total of 126,
can also be added.
1.4.1.2. Physical and Virtual Addresses
The address of a section or symbol is the offset of that section or symbol from
address zero of the address space. The
memory where a section is loaded. The
address from which the section's data will execute. When a section's data has to
be copied from ROM to RAM at program startup, the ROM copy (source) of the
section's data is considered to be at the physical address and the RAM copy
(destination) of the section's data is considered to be at the virtual address. The
section header contains two address fields: a physical address and a virtual
address. In the case where a section's data gets copied from ROM to RAM, the
physical and virtual address entries will be different; but in the case where a
program executes out of ROM, the physical and virtual address entries for the
section's data will be the same.
Section 1: General Information
.text, .data
physical address
virtual address
, and
.const
. In a Sierra Systems
.bss
.ld_tbl
section, and the
is the actual location in
of a section is the
.ld_tbl
.
1.4.1.3. C Language COFF File Structures
The C language COFF file structures and macro definitions used internally by the
various Sierra Systems utilities that operate on object files are defined in the file
file_fmt.txt
members of type (
defined as
structure members are represented as arrays of
generating identical object files on host machines with different internal byte
orderings. Machine-dependent macros for reading and writing the structures in
file_fmt.txt
TI-89 / TI-92 Plus SDK.
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
supplied with the TI-89 / TI-92 Plus SDK. Note that structure
unsigned) char
unsigned char
are defined in file
arrays of length 1, 2, and 4, respectively. The
, (
unsigned) short
com_fmt.txt
Not for Distribution
, and (
unsigned char
, also supplied with the
unsigned) long
Beta Version February 2, 2001
are
to facilitate
Section 1: General Information
1.4.2. File Header
The file header contains the 20 bytes of information shown in Table 1.3. The last
two bytes are flags that are used by the linker and other object file utilities.
Defined in
file_fmt.txt
file header structure and file header size, respectively.
BytesDeclaration Name Description
are
FILE_HDR
and
FILE_HDR_SIZE
, the typedefs for the
11
0-1
2-3
4-7
8-11
12-15
16-17
18-19
unsigned short fh_magic
unsigned short fh_nbr_sections
unsigned long fh_time_date
unsigned long fh_symtab_ptr
unsigned long fh_nbr_symtab_ents
unsigned short fh_size_opt_hdr
unsigned short fh_flags
1.4.2.1. Magic Number
The
magic number
executed. The number 0x150 identifies the object file as a 68000 family
executable file. The number 0x150 is the only number recognized by the various
Sierra Systems utilities; an error will be reported if a file that does not begin with
0x150 is encountered.
Magic number, 0x150
Number of section headers (equals the
number of sections)
Time and date stamp indicating when the
file was created (expressed as the
number of seconds since 00:00:00 GMT,
January 1, 1970)
File pointer containing the starting offset
of the symbol table
Number of entries in the symbol table
Number of bytes in the optional header
Flags (see Table 1.4)
Table 1.3: File Header Contents
specifies the target machine on which the object file can be
1.4.2.2. Optional Header Size
The optional header shown in Table 1.5 is system-dependent and not specified
by the COFF standard. The size of the optional header is specified in the file
header to allow system-independent object file utilities to skip past the optional
header.
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
12
1.4.2.3. Flags
The last two bytes of the file header are flags that describe the type of the object
file. The file header flags are described in Table 1.4.
Mnemonic Flag Meaning
Section 1: General Information
FH_REL_STRPD
FH_EXECUTABLE
FH_LNNO_STRPD
FH_LSYMS_STRPD
FH_GSYMS_STRPD
FH_ERR_IN_FILE
Table 1.4: File Header Flags
1.4.3. Optional Header
The optional header contains information that varies among the systems that use
COFF. Applications place all system-dependent information in the optional
header. As previously stated, system-independent COFF utilities can skip past
the system-dependent optional header to perform tasks such as dumping the
symbol table.
Bytes Declaration Name Description
0-1
unsigned short magic
0x01 Relocation information stripped from file
0x02 File is executable (i.e., no unresolved references)
0x04 Line numbers stripped from file
0x08 Local symbols stripped from file
0x10 Global symbols stripped from file
0x80 Error in object file
Magic number, 0x107
2-3
4-7
8-11
12-15
16-19
20-23
24-27
unsigned short version
unsigned long tsize
unsigned long dsize
unsigned long bsize
unsigned long entry
unsigned long text_start
unsigned long data_start
Table 1.5: Sierra Systems Optional Header Contents
The Sierra Systems optional header is 28 bytes long, and the fields of the
optional header are described in Table 1.5. The optional header is present only
on linked executable files; it is not present on assembler-generated files or
partially linked files (-r flag). Defined in
A_OUT_HDR_SIZE
, the typedefs for the optional header structure and optional
header size, respectively.
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Version stamp
Size of text in bytes
Size of initialized data in bytes
Size of uninitialized data in bytes
Program entry point
Base address of text
Base address of data
file_fmt.txt
Not for Distribution
are
A_OUT_HDR
and
Beta Version February 2, 2001
Section 1: General Information
1.4.4. Section Headers
Every object file has one section header for each section in the file. The Sierra
Systems object file has at least three section headers. The section headers
describe the organization of data within the file. Table 1.6 describes the fields of
the section header. Defined in
SECTION_HDR_SIZE
, the typedefs for the section header structure and section
file_fmt.txt
header size, respectively.
The size of a section is always padded to a multiple of four bytes.
The file pointers are byte offsets from the beginning of the file, and can be used
to locate the start of the data, relocation, or line entries for the section.
BytesDeclaration Name Description
are
SECTION_HDR
and
13
0-7
8-11
12-15
16-19
20-23
24-27
28-31
32-33
34-35
36-39
char sh_name
unsigned long sh_phys_addr
unsigned long sh_virt_addr
unsigned long sh_size
unsigned long sh_data_ptr
unsigned long sh_reloc_ptr
unsigned long sh_line_nbr_ptr
unsigned short sh_nbr_reloc_ents
unsigned short sh_nbr_line_ents
unsigned long sh_flags
Table 1.6: Section Header Contents
8-character null-padded section name
Physical address of section
Virtual address of section
Section size in bytes
File pointer to raw data
File pointer to relocation entries
File pointer to line number entries
Number of relocation entries
Number of line number entries
Flags (see Table 1.7)
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
14
Section 1: General Information
The
field defines the type of the section. Table 1.7 lists the definitions of the
flags
section header flags.
Mnemonic Flag Meaning
SH_REG
SH_DSECT
SH_NOLOAD
SH_RESIDENT
SH_GROUP
SH_PAD
SH_FILLONLY
SH_COPY
SH_TEXT
SH_DATA
SH_BSS
SH_ORG
0x000 Regular section: alloc'd, not reloc'd, load'd
0x001 Dummy section: not alloc'd, reloc'd, not load'd
0x002 No load section: alloc'd, reloc'd, not load'd
0x002 Resident section: alloc'd, reloc'd, not load'd
0x004 Grouped section: formed from input sections
0x008 Padding section: not alloc'd, not reloc'd, load'd
0x008 Fill only section: filled at run-time
0x010 Copy section: copied at run-time from destination address to
virtual address
0x020 Section contains executable text
0x040 Section contains initialized data
0x080 Section contains only uninitialized data
0x100 Section contains
'd (absolute) data
ORG
SH_INFO
SH_OVERT
SH_LIB
0x200 Comment section: not alloc'd, not reloc'd, not load'd
0x400 Overlay section: not alloc'd, reloc'd, not load'd
0x800 Library section
Table 1.7: Section Header Flags
All sections, including sections with uninitialized data such as section
static storage), have an associated section header. Uninitialized sections have
symbols that refer to them and symbols that are defined in them, but they do not
have any relocation entries, line number entries, or data associated with them.
Therefore, uninitialized sections have a section header, but occupy no other
space in the object file. In the case of an uninitialized section, zeroes appear in
the fields for the number of relocation and line number entries, as well as in the
fields for all the file pointers.
1.4.5. Relocation Information
Object files have one relocation entry for each relocatable reference in a
text-type or data-type section. The relocation entries are automatically generated
by the assembler, and the information is used by the linker to resolve external
references. Table 1.8 describes the information carried in the object file for each
relocatable reference. Defined in
RELOC_INFO_SIZE
relocation entry size, respectively.
, the typedefs for the relocation entry structure and
file_fmt.txt
are
RELOC_INFO
and
.bss
(blank
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Section 1: General Information
Bytes Declaration Name Description
15
0-3
4-7
8-9
unsigned long r_virt_addr
unsigned long r_sym_index
unsigned short r_type_info
Virtual address of reference
Symbol table index
Relocation type (see Table 1.9)
Table 1.8: Relocation Section Contents
The first field of the relocation entry is the virtual address of the text or data to
which the entry applies. The 1-, 2-, or 4-byte area referenced by this first field is
known as a hole since the assembler cannot resolve the reference. The address
or PC-relative offset is ultimately determined and written to the hole by the linker.
The second field is the index of the symbol table entry for the symbol that is
being referenced. The third field indicates the type of relocation that is to be
applied. Table 1.9 lists the relocation types supported by Sierra Systems.
Mnemonic Flag Meaning
RL_FIXED
RL_DIR_BYTE
RL_DIR_WORD
RL_DIR_LONG
0x00 Reference is absolute, no relocation is necessary, the entry
will be ignored
0x0F Direct 8-bit reference to symbol's virtual address
0x10 Direct 16-bit reference to symbol's virtual address
0x11 Direct 32-bit reference to symbol's virtual address
RL_PC_BYTE
RL_PC_WORD
RL_PC_LONG
RL_CMPLX_OP
RL_CMPLX_ABS
RL_CMPLX_REL
RL_CMPLX_EXT
1.4.5.1. Relocation
There are two types of relocation: absolute and PC-relative. The assembler
reduces an unresolved reference to an offset from a relocatable section or an
offset from an external symbol. The offset is saved in the hole and the index of
the symbol (external symbol or section name symbol) is saved in the relocation
entry. In addition, if the reference is PC-relative, the address or section-relative
offset of the hole is subtracted from the contents of the hole.
0x12 A PC-relative 8-bit reference to symbol's virtual address
0x13 A PC-relative 16-bit reference to symbol's virtual address
0x14 A PC-relative 32-bit reference to symbol's virtual address
0x40 Operator in a complex relocatable expression
0x50 Absolute operand in a complex relocatable expression
0x60 Relocatable operand in a complex relocatable expression
0x70 External operand in a complex relocatable expression
Table 1.9: Relocation Types
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
16
The linker, which knows the addresses of all symbols, adds the address of the
symbol referenced by the
addition, if the reference is PC-relative and the hole is in a relocatable section,
the base address of this section is subtracted from the contents of the hole.
In the case of byte or word references (1-byte or 2-byte holes, respectively), it is
possible that the final value determined by the linker will fit in the hole but the
intermediate value to be filled in by the assembler will not fit. Sierra Systems has
added an extension to the COFF standard to remove this deficiency. In the
relocation entry, the higher order byte of the
order byte of the
r_sym_index
are unused. In the case of a 1-byte or 2-byte hole, the overflow first goes into the
unused byte in
r_sym_index
effectively providing the assembler with a 24-bit or 32-bit hole, respectively.
1.4.5.2. Complex Relocation
A complex relocatable expression is an expression that cannot be reduced at
assembly time to either an absolute value or a section-relative reference. For
example, an expression that references multiple external symbols and/or
symbols from different relocatable sections would be classified complex
relocatable.
r_sym_index
field (assuming fewer than 16 million symbols)
and then into the unused byte in
field to the contents of the hole. In
Section 1: General Information
r_type_info
field and the highest
r_type_info
A complex relocatable expression is saved in a sequence of auxiliary relocation
entries that follow the primary entry for the relocation hole. A separate entry is
used for each operand and each operator in the expression. Table 1.10
describes the different types of complex relocation entries. The complex
expression contained in the auxiliary relocation entries is subsequently evaluated
by the linker, and the result is placed in the hole referenced by the primary entry.
COFF Relocation Entry
r_virt_addr r_sym_index r_type_info
Primary Entry
Operator
Absolute Operand
Reloc Operand
External Operand
Table 1.10: Complex Relocation Entries
Note that the field
hole address entry count type and size
operator code –
value –
section offset section index
– symbol index
r_type_info
for the primary entry has the
RL_CMPLX_OP
RL_CMPLX_ABS
RL_CMPLX_REL
RL_CMPLX_EXT
RL_CMPLX_OP
bit
set to designate the start of a complex relocatable expression.
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Section 1: General Information
1.4.6. Line Number Information
The line number information in the object file is used for source-level debugging.
Line number information is present when C files are compiled with the -q or
debug flag or assembly language files are assembled with the -L line number
flag. When compiled or assembled with one of the above listed flags, a line
number entry is generated for every line of C or assembly language code. The
line number entries are grouped by section and within each section grouping the
entries are grouped by function as shown in Table 1.11.
symbol index 0
virtual address line number
virtual address line number
. . . . . .
symbol index 0
virtual address line number
-q1
17
virtual address line number
Table 1.11: Line Number Grouping
Table 1.12 describes the fields within a line number entry. Defined in
are
LINE_NBR
and
LINE_NBR_SIZE
structure and line number entry size, respectively.
Bytes Declaration Name Description
0-3
0-3
4-5
unsigned long l_sym_index
unsigned long l_phys_addr
unsigned short l_line_nbr
Table 1.12: Line Number Section Contents
The first line number entry within a function grouping specifies line number 0 and
has, in place of the virtual address, an index into the symbol table for the entry
containing the name of the function. The subsequent entries have the actual line
numbers relative to the open brace ' { ' that begins the function, and the address
of the text that corresponds to the line number. The line number entries are
ordered by increasing address.
file_fmt.txt
, the typedefs for the line number entry
Symbol table index of function
Address of source line
Source line number
The
(begin function) symbol entry immediately follows the auxiliary entry for
.bf
the function name symbol. The absolute C source line number of the function's
open brace is specified in the auxiliary entry for the
1.4.9.4 Beginning of Blocks and Functions
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
). Absolute C source line numbers
Not for Distribution
symbol (see section
.bf
Beta Version February 2, 2001
18
for all other lines in a function are computed by offsetting the relative line
numbers in the line number entries by the absolute line number in the
symbol's auxiliary entry.
1.4.7. Symbol Table
Because of symbolic debugging requirements, the order of the symbols within
the symbol table is very important. The symbols appear in the order shown in
Table 1.13.
filename 1
function 1
local symbols for function 1
function 2
local symbols for function 2
. . .
Section 1: General Information
.bf
statics for file 1
. . .
filename 2
local symbols for function 1
. . .
statics for file 2
. . .
all defined global symbols
all undefined global symbols
Table 1.13: COFF Symbol Table
Local symbols for a function are the symbols that are defined within a function
and accessible only within that function. The term statics as used in Table 1.13
identifies symbols that are C language variables of storage class
outside any function. The symbol table consists of at least one 18-byte entry per
symbol with some symbols followed by one or more auxiliary entries also 18
bytes each. A symbol table entry contains the name of the symbol (or file offset
to the name), the value, the type, and other information.
static
defined
TI-89 / TI-92 Plus Sierra C Assembler Reference Manual
Not for Distribution
Beta Version February 2, 2001
Loading...