Texas Instruments TMS34010 User manual

~TEXAS
INSTRUMENTS
TMS34010 C Compiler
1988 Graphics Products

TMS34010 C Compiler
Reference Guide
•
TEXAS
INSTRUMENTS

IMPORTANT NOTICE
Texas Instruments (TI) reserves the right to make changes to or to discontinue
any semiconductor product or service identified in this publication
without
notice. TI advises its customers to obtain the latest version of the relevant in-
formation to verify, before placing orders, that the information being relied
upon is current.
TI warrants performance of its semiconductor products to current specifica-
tions in accordance
with TI's standard warranty. Testing and other quality
control techniques
are utilized to the extent TI deems necessary to support this
warranty. Unless mandated by government requirements, specific testing
of
all parameters of each device is not necessarily performed.
TI assumes no liability for TI applications assistance, customer product design,
software performance, or infringement
of patents or services described herein.
Nor does TI warrant or represent that license, either express or implied,
is
granted under any patent right, copyright, mask work right, or other intellec-
tual property right
of TI covering or relating to any combination, machine, or
process in
which such semiconductor p'roducts or services might be or are
used.
Copyright © 1988, Texas Instruments Incorporated

Contents
Section
1
1.1
1.2
1.3
1.4
2
2.1
2.2
2.3
2.4
3
3.1
3.1.1
3.1.2
3.1.3
3.2
3.2.1
3.2.2
3.3
3.3.1
3.3.2
3.3.3
3.3.4
3.4
3.5
3.5.1
3.5.2
3.5.3
3.5.4
3.6
4
4.1
4.2
4.3
4.4
4.5
4.6
4.7
4.8
4.9
Introduction
Software Development Tools Overview
Related Documentation
Style and Symbol Conventions
Getting Started
Compiler Installation
Installing the C Compiler on IBM/TI PCs with PC/MS-DOS
Installing the C Compiler on VAX/VMS ....... .
Installing the C Compiler on UNIX Systems ..... .
Installing the C Compiler on Macintosh/MPW Systems
C Compiler Operation
Preprocessor (gspcpp) Description
Invoking the C Preprocessor
General Information ..... .
Specifying Alternate Directories for Include Files
Parser (gspcc) Description
Invoking the Parser ...... .
General Information
...... .
Code Generator (gspcg) Description
Invoking the Code Generator ..
Pointers to Named Variables (-a Option)
Small Code Model (-s Option) .....
Checking for Stack Overflow (-x option)
Compiling and Assembling a Program
Linking a C Program
........... .
Runtime Initialization and Runtime Support
Sample Linker Command File
..... .
Autoinitialization
(ROM and RAM Models)
The -c and
-cr Linker Options
Archiving a C Program . . . . . . . .
The TMS34010 C Language
Identifiers, Keywords, and Constants
TMS34010 C Data Types
Object Alignment
Conversions
Expressions
Declarations
Initialization
of Static and Global Variables
asm Statement
Lexical Scope Rules
Page
1-1
1-2
1-4
1-5
1-6
2-1
2-2
2-3
2-4
2-5
3-1
3-2
3-2
3-3
3-4
3-6
3-6
3-7
3-8
3-8
3-9
3-10
3-10
3-11
3-13
3-13
3-14
3-15
3-15
3-16
4-1
4-2
4-4
4-6
4-6
4-7
4-8
4-10
4-10
4-11
iii

5
5.1
5.1.1
5.1.2
5.1.3
5.1.4
5.1.5
5.1.6
5.1.7
5.2
5.2.1
5.2.2
5.2.3
5.3
5.3.1
5.3.2
5.3.3
5.3.4
5.3.5
5.4
5.4.1
5.4.2
5.4.3
5.5
5.6
5.7
5.7.1
5.7.2
5.7.3
5.7.4
5.7.5
5.8
5.8.1
5.8.2
Runtime Environment
Memory Model .... .
Sections ...... .
Stack Management .
Dynamic Memory Allocation
RAM and ROM Models . . . .. . ....
Allocating Memory for Static and Global Variables
Packing Structures and Manipulating Fields
Array Alignment . .
Register Conventions ........... .
Dedicated Registers .......... .
Using Registers ............ .
Register Variables ........... .
Function Structure and Calling Conventions
Responsibilities of a Calling Function .
Responsibilities of a Called Function ..
Setting up the Local Frame ...... .
Accessing Arguments and Local Variables
Returning Structures from Functions
Interfacing C with Assembly Language
Assembly Language Modules
Inline Assembly Language
Modifying Compiler Output
Interrupt Handling
Integer Expression Analysis .
Floating-Point Support ....
Floating-Point Formats ..
Double':'Precision Functions
Single-Precision Functions
Conversion Functions
Floating-Point Errors
System Initialization
Initializing the Stack ....... .
Autoinitialization of Variables and Constants
6 Runtime-Support Functions
6.1 Header Files ................. .
6.1.1 Diagnostic Messages (assert.h) .... .
6.1.2 Character Typing and Conversion (ctype.h)
6.1.3 Limits (float.h and limits.h) ..... .
6.1.4 Floating-Point Math (math.h, errno.h)
6.1.5 Nonlocal Jumps (setjmp.h)
6.1.6 Variable Arguments (stdarg.h)
6.1.7 Standard Definitions (stddef.h)
6.1.8 General Utilities (stdlib.h)
6.1.9 String Functions (string.h)
6.1.10 Time Functions (time.h) . ........ .
6.2 Summary of Runtime-Support Functions and Macros
6.3 Functions Reference ................ .
A
B
iv
Error Messages
C Preprocessor Directives
5-1
5-2
5-2
5-3
5-4
5-4
5-5
5-5
5-5
5-6
5-6
5-6
5-7
5-8
5-8
5-9
5-10
5-10
5-11
5-12
5-12
5-15
5-15
5-16
5-17
5-17
5-17
5-19
5-20
5-21
5-21
5-22
5-22
5-23
6-1
6-2
6-2
6-3
6-3
6-5
6-5
6-6
6-6
6-6
6-7
6-8
6-9
6-14
A-1
B-1

Illustrations
Figure Page
1-1 TMS34010 Software Development Flow . . . . . . . . . . . . . . . . . . . . . . . . .. 1-2
3-1 Compiling a C Program ........................................ 3-1
3-2 Input and Output Files for the C Preprocessor . . . . . . . . . . . . . . . . . . . . .. 3-2
3-3 Input and Output Files for the C Parser ......................... " 3-6
3-4 Input and Output Files for the C Code Generator .................... 3-8
3-5 An Example of a Linker Command File .. . . . . . . . . . . . . . . . . . . . . . . . . .. 3-14
5-1 The Program and System Stacks ................................. 5-3
5-2 An Example of a Function Call . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 5-8
5-3 Single-Precision Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 5-18
5-4 Double-Precision Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 5-18
5-5 Format of Initialization Records in the .cinit Section .................. 5-24
5-6 ROM Model of Autoinitialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 5-25
5- 7 RAM Model of Autoinitialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .. 5-26
Table
6-1
6-2
Tables
Macros that Supply Integer Type Range Limits (Iimits.h)
Macros that Supply Floating-Point Range Limits (float.h)
Page
6-3
6-4
v

Preface
The TMS34010 C Compiler Reference Guide contains the following sections:
Section 1 Introduction
Overviews the TMS34010 development tools and the code development
process, lists related documentation, describes style and symbol conventions
used in this document, and provides a walkthrough.
Section 2 Software Installation
Contains instructions for installing the C compiler on VAX/VMS, VAX/Ultrix,
VAX/System V, IBM-PC/PC-DOS, and TI-PC/MS-DOS systems.
Section 3 Compiler Operation
Describes the three major components of the C compiler (preprocessor, parser,
and code generator), contains instructions for invoking these components
in-
dividually or for invoking batch files to compile and assemble a C source file,
discusses linking C programs, and discusses archiving C programs.
Section 4 TMS34010 C Language
Discusses the differences between the C language supported by the
TMS34010 C compiler and standard Kernighan and Ritchie C.
Section 5 Runtime Environment
Contains technical information on how the compiler uses the TMS3401 0 ar-
chitecture; discusses memory and register conventions, stack organization,
function-call conventions, and system initialization; provides information
needed
for interfacing assembly language to C programs.
Section 6 Runtime-Support Functions
Describes the header files that are included with the C compiler, as well as the
macros, functions, and types that they declare, summarizes the runtime-
support
functions according to category (header), and provides an alphabet-
ical reference
of the runtime-support functions.
Appendix A Error Messages
Shows the format of compiler error messages and lists all the error messages
that are fatal.
Appendix B Preprocessor Directives
Describes the standard preprocessor directives that the compiler supports.
vi

Section 1
Introduction
The TMS34010 Graphics System Processor is an advanced 32-bit micro-
processor optimized for graphics systems. The TMS3401 0 is a member
of the
TMS340 family of computer graphics products from Texas Instruments.
The TMS3401 0 is well supported by a full set of hardware and software de-
velopment tools, including a C compiler, a full-speed emulator, a software
simulator, and
an IBM/TI-PC development board. (Section 1.1 describes
these tools.)
This reference guide describes the
TMS34010 C compiler. Its main purpose
is to present the details and characteristics of this particular C compiler; it as-
sumes that you already
know how to write C programs. We suggest that you
obtain a copy
of The C Programming Language, by Brian W. Kernighan and
Dennis M. Ritchie (published by Prentice-Hall); use this reference guide
as a
supplement
to the Kernighan and Ritchie book.
The TMS3401 0 C compiler can be installed on the
following systems:
• pes:
IBM-PC with PC-DOS
TI-PC with MS-DOS
• VAX:
VMS
Ultrix
• Apollo Workstations:
Domain/IX
AEGIS
•
Sun-3 Workstations with Unix
• Macintosh with MPW
Topics in this introductory section include:
Section Page
1.1 Software Development Tools Overview ................................................. 1-2
1.2 Related Documentation ............................................................................ 1 -4
1.3 Style and Symbol Conventions ................................................................ 1-5
1.4 Getting Started ........................................................................................... 1 -6
1-1

Introduction - Software Development Tools Overview
1.1 Software Development Tools Overview
1-2
Object
Libraries
Figure 1-1 illustrates the TMS34010 software development flow. The center
portion
of the figure highlights the most common path of software develop-
ment; the other portions are optional.
................
.. .. .. .. .. .. .. ..
..
.. .. .. .. .. .. ..
................
.. .. .. .. .. .. .. ..
Figure 1-1. TMS34010 Software Development Flow

Introduction - Software Development Tools Overview
The following list describes the tools that are shown in Figure 1-1.
• The C compiler accepts C source code and produces TMS34010 as-
sembly language source code. The C compiler has three parts: a pre-
processor, a parser, and a code generator. Section 3 describes compiler
invocation and operation.
• The assembler translates assembly language source files into machine
language object files.
• The archiver allows you to collect a group of files into a single archive
file.
(An archive file is called a library.) It also allows you to modify a
library
by deleting, replacing, extracting, or adding members. One of the
most useful applications
of the archiver is to build a library of object
modules.
Two object libraries and a source library are included with the
C compiler:
flib.lib contains floating-point arithmetic routines.
rts.lib contains standard runtime-support functions.
rts.src contains the source for the functions in rts .lib.
Several application-specific object libraries are available as separate GSP
products:
The
math/graphics function library contains math functions
for performing algebraic, trigonometric, and transcendental oper-
ations
as well as graphics functions for performing viewport man-
agement, bit-mapped text, graphics output, color-palette control,
three-dimensional transformations, and graphics initialization.
The
font library contains a variety of proportionally spaced and
monospaced fonts. You can use the functions in the graphics
li-
brary to display the fonts.
The
CCITT data compression function library contains
CCITT-compatible routines for compressing and decompressing
monochrome image data.
The
8514 adaptor emulation function library contains rou-
tines for use with the IBM PS/2 high-resolution display. '
These
functions and routines can be called from C programs. You can
also create
your own object libraries. To use an object library, you must
specify the library name
as linker input; the linker will include the library
members
that define any functions called from a C program.
• The linker combines object files into a single executable object module.
As the linker creates the executable module,
it performs relocation and
resolves external references. The linker accepts relocatable COFF object
files and object libraries
as input.
• The main purpose of this development process is to produce a module
that can be executed in a TMS3401 0 target system. You can use one
of several debugging tools to refine and correct your code. Available
products include: a software
simulator that runs on PCs, a PC-based
software development board (SOB), and a realtime in-circuit
XDS/22 emulator.
• An object format converter is also available; it converts a COFF ob-
ject file into an Intel, Tektronix, or TI-tagged object-format file that can
be
downloaded to an EPROM programmer.
1-3