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 FLASH Studio are trademarks of Texas Instruments Incorporated. Sierra C is a trademark of Sierra Systems.

	i
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
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	Table of Contents
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
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	iii
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
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	v
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
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

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

5

1. General Information

1.1.Introduction

This manual describes the Sierra tools, including the compiler, assembler, and linker invoked by the TI FLASH Studio™ for development of Flash applications (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.

Typically, the TI FLASH Studio will handle all invocations of the compiler, 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, com68. These 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: asm68 which is invoked by the TI FLASH Studio, and asm68k which is included for developers who may 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 asm68k macros are in this section.

Section 4 is a brief discussion of the Sierra Systems linker, link68, and some of its features including relocation hole compression.

Section 5 describes the Sierra Systems utilities nm68 and size68, provided as part of the TI-89 / TI-92 Plus SDK for use by developers.

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:

•Bold text is used for names of functions, routines, files, keywords, directives, macros, flags, and registers. It is also used occasionally for emphasis.

•The Courier font is used to distinguish assembly or C program text.

•Italicized 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:

*	Match zero or more characters, where characters matched may be any
	character except the period (.). Dot-star (.*) at the end of a wildcard
	string matches files with and without extensions.

?

[char_set]

Match any character except the period (.).

Match any character in the character set char_set. Characters can be listed individually or as members of a range. A range is denoted by a hyphen (-) separated pair of characters; it includes the two characters and all characters lexically between them.

The following are examples of wildcard expansions:

*.*	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.
*.c *.s	Match all filenames with extensions of .c or .s in the current directory.
*.[cs]	Same as *.c *.s

c:\doc\version[0-9a-f].doc

Match all filenames in the subdirectory c:\doc with a base name of version followed by a hexadecimal digit and a .doc extension.

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001

Section 1: General Information

7

The following Sierra C utilities support command line wildcard expansion:

nm68	Symbol Table Name Utility
size68	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 filename preprocessor directive. Since this 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 (include), standard library (lib), executable (bin), and temporary (tmp) directories that are created by appending subdirectory names to the directory specified by the SIERRA environment variable. The SIERRA environment variable will be set when the setup program for the TI FLASH Studio is executed. The SIERRA environment variable must be set before using any of the Sierra utilities.

sierra

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	standard include files
LIB68	link68	standard libraries
	link68	default configuration file

Table 1.1: Environment Variables

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, and SIERRA are searched for in the order listed with the search terminating after the first defined variable is located. If either TMP68 or TMP is defined, the directory specified by that environment variable is used to hold temporary files. If the SIERRA environment variable is the only variable

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 tmp subdirectory located under the directory specified by SIERRA is 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 INCLUDE68 and SIERRA in the order listed to determine the locations of the standard include directories. If INCLUDE68 is defined, the semicolon-separated list of one or more directory paths defines the standard include directories. If the SIERRA environment variable is the only variable defined, the include subdirectory located under the directory specified by SIERRA is used as the standard include directory.

Utilities that search for files in standard include directories search for the two environment variables LIB68 and SIERRA in the order listed to determine the locations of the standard include directories. If LIB68 is defined, the semicolon-separated list of one or more directory paths defines the standard library directories. If the SIERRA environment variable is the only variable defined, the lib subdirectory located under the directory specified by SIERRA is used as the standard library directory.

1.4.Object File Format

This section describes the Common Object File Format (COFF) used by TI FLASH Studio. COFF is the format of the object files created by the

assemblers and linker, and recognized by TI 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	¦	Relocation information
•	Optional header information	¦	Line numbers
• A table of section headers		¦	A symbol table
• Data corresponding to the section header		¦	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

9

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

. . .

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

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001

10	Section 1: General Information

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 .text, .data, and .bss. In a Sierra Systems executable file, there is also usually a fourth section with the name .ld_tbl. TI-89 / TI-92 Plus apps and ASMs also have a .const section, and the .ld_tbl 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 physical address is the actual location in memory where a section is loaded. The virtual address of a section is 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.

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 supplied with the TI-89 / TI-92 Plus SDK. Note that structure members of type (unsigned) char, (unsigned) short, and (unsigned) long are defined as unsigned char arrays of length 1, 2, and 4, respectively. The structure members are represented as arrays of unsigned char to facilitate 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 are defined in file com_fmt.txt, also supplied with the

TI-89 / TI-92 Plus SDK.

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001

Section 1: General Information

11

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 are FILE_HDR and FILE_HDR_SIZE, the typedefs for the file header structure and file header size, respectively.

Bytes	Declaration	Name	Description
0-1	unsigned short	fh_magic	Magic number, 0x150
2-3	unsigned short	fh_nbr_sections	Number of section headers (equals the
			number of sections)
4-7	unsigned long	fh_time_date	Time and date stamp indicating when the
			file was created (expressed as the
			number of seconds since 00:00:00 GMT,
			January 1, 1970)
8-11	unsigned long	fh_symtab_ptr	File pointer containing the starting offset
			of the symbol table
12-15	unsigned long	fh_nbr_symtab_ents	Number of entries in the symbol table
16-17	unsigned short	fh_size_opt_hdr	Number of bytes in the optional header
18-19	unsigned short	fh_flags	Flags (see Table 1.4)

Table 1.3: File Header Contents

1.4.2.1.Magic Number

The magic number specifies the target machine on which the object file can be 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.

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	Section 1: General Information

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
FH_REL_STRPD	0x01	Relocation information stripped from file
FH_EXECUTABLE	0x02	File is executable (i.e., no unresolved references)
FH_LNNO_STRPD	0x04	Line numbers stripped from file
FH_LSYMS_STRPD	0x08	Local symbols stripped from file
FH_GSYMS_STRPD	0x10	Global symbols stripped from file
FH_ERR_IN_FILE	0x80	Error in object 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	Magic number, 0x107
2-3	unsigned short	version	Version stamp
4-7	unsigned long	tsize	Size of text in bytes
8-11	unsigned long	dsize	Size of initialized data in bytes
12-15	unsigned long	bsize	Size of uninitialized data in bytes
16-19	unsigned long	entry	Program entry point
20-23	unsigned long	text_start	Base address of text
24-27	unsigned long	data_start	Base address of data

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 file_fmt.txt are A_OUT_HDR and 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

Not for Distribution

Beta Version February 2, 2001

Section 1: General Information

13

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 file_fmt.txt are SECTION_HDR and SECTION_HDR_SIZE, the typedefs for the section header structure and section 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.

Bytes	Declaration	Name	Description
0-7	char	sh_name	8-character null-padded section name
8-11	unsigned long	sh_phys_addr	Physical address of section
12-15	unsigned long	sh_virt_addr	Virtual address of section
16-19	unsigned long	sh_size	Section size in bytes
20-23	unsigned long	sh_data_ptr	File pointer to raw data
24-27	unsigned long	sh_reloc_ptr	File pointer to relocation entries
28-31	unsigned long	sh_line_nbr_ptr	File pointer to line number entries
32-33	unsigned short	sh_nbr_reloc_ents	Number of relocation entries
34-35	unsigned short	sh_nbr_line_ents	Number of line number entries
36-39	unsigned long	sh_flags	Flags (see Table 1.7)

Table 1.6: Section Header Contents

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001

14	Section 1: General Information

The flags field defines the type of the section. Table 1.7 lists the definitions of the section header flags.

Mnemonic	Flag	Meaning
SH_REG	0x000	Regular section: alloc'd, not reloc'd, load'd
SH_DSECT	0x001	Dummy section: not alloc'd, reloc'd, not load'd
SH_NOLOAD	0x002	No load section: alloc'd, reloc'd, not load'd
SH_RESIDENT	0x002	Resident section: alloc'd, reloc'd, not load'd
SH_GROUP	0x004	Grouped section: formed from input sections
SH_PAD	0x008	Padding section: not alloc'd, not reloc'd, load'd
SH_FILLONLY	0x008	Fill only section: filled at run-time
SH_COPY	0x010	Copy section: copied at run-time from destination address to
		virtual address
SH_TEXT	0x020	Section contains executable text
SH_DATA	0x040	Section contains initialized data
SH_BSS	0x080	Section contains only uninitialized data
SH_ORG	0x100	Section contains ORG'd (absolute) data
SH_INFO	0x200	Comment section: not alloc'd, not reloc'd, not load'd
SH_OVERT	0x400	Overlay section: not alloc'd, reloc'd, not load'd
SH_LIB	0x800	Library section

Table 1.7: Section Header Flags

All sections, including sections with uninitialized data such as section .bss (blank 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 file_fmt.txt are RELOC_INFO and RELOC_INFO_SIZE, the typedefs for the relocation entry structure and relocation entry size, respectively.

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001

Section 1: General Information

15

Bytes	Declaration	Name	Description
0-3	unsigned long	r_virt_addr	Virtual address of reference
4-7	unsigned long	r_sym_index	Symbol table index
8-9	unsigned short	r_type_info	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	0x00	Reference is absolute, no relocation is necessary, the entry
		will be ignored
RL_DIR_BYTE	0x0F	Direct 8-bit reference to symbol's virtual address
RL_DIR_WORD	0x10	Direct 16-bit reference to symbol's virtual address
RL_DIR_LONG	0x11	Direct 32-bit reference to symbol's virtual address
RL_PC_BYTE	0x12	A PC-relative 8-bit reference to symbol's virtual address
RL_PC_WORD	0x13	A PC-relative 16-bit reference to symbol's virtual address
RL_PC_LONG	0x14	A PC-relative 32-bit reference to symbol's virtual address
RL_CMPLX_OP	0x40	Operator in a complex relocatable expression
RL_CMPLX_ABS	0x50	Absolute operand in a complex relocatable expression
RL_CMPLX_REL	0x60	Relocatable operand in a complex relocatable expression
RL_CMPLX_EXT	0x70	External operand in a complex relocatable expression

Table 1.9: Relocation Types

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.

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001

16	Section 1: General Information

The linker, which knows the addresses of all symbols, adds the address of the symbol referenced by the r_sym_index field to the contents of the hole. In 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 r_type_info field and the highest order byte of the r_sym_index field (assuming fewer than 16 million symbols) 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 and then into the unused byte in r_type_info 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.

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	hole address		entry count	type and size
Operator	operator code		–	RL_CMPLX_OP
Absolute Operand	value		–	RL_CMPLX_ABS
Reloc Operand	section offset		section index	RL_CMPLX_REL
External Operand	–		symbol index	RL_CMPLX_EXT

Table 1.10: Complex Relocation Entries

Note that the field r_type_info for the primary entry has the 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

17

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 -q1 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
virtual address	line number

Table 1.11: Line Number Grouping

Table 1.12 describes the fields within a line number entry. Defined in file_fmt.txt are LINE_NBR and LINE_NBR_SIZE, the typedefs for the line number entry structure and line number entry size, respectively.

Bytes	Declaration	Name	Description
0-3	unsigned long	l_sym_index	Symbol table index of function
0-3	unsigned long	l_phys_addr	Address of source line
4-5	unsigned short	l_line_nbr	Source line number

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.

The .bf (begin function) symbol entry immediately follows the auxiliary entry for the function name symbol. The absolute C source line number of the function's open brace is specified in the auxiliary entry for the .bf symbol (see section

1.4.9.4 Beginning of Blocks and Functions). Absolute C source line numbers

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001

18	Section 1: General Information

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

. . .

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 static defined 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.

TI-89 / TI-92 Plus Sierra C Assembler Reference Manual

Not for Distribution

Beta Version February 2, 2001