Page 1
TMS34010
C Compiler
User's Guide
."
TEXAS
INSTRUMENTS
SPVUOO5
Page 2
TMS34010 C
Col11piler
User's Guide
TEXAS
INSTRUMENTS
Page 3
IMPORTANT
NOTICE
Texas Instruments (TI) reserves the right
to
make changes in the devices or the
device specifications identified in this
publication
without
notice.
TI
advises
its customers
to
obtain the latest version
of
device specifications
to
verify,
before placing orders, that the information being relied upon by the customer
is
current.
In the absence
of
written agreement
to
the contrary, TI assumes no liability for
TI applications assistance, customer's product design, or infringement
of
pat-
ents or copyrights
of
third parties
by
or arising from use
of
semiconductor
devices described herein. Nor does
TI warrant or represent that any license,
either express or implied,
is
granted under any patent right, copyright. or other
intellectual property right
of
TI covering or relating
to
any combination, ma-
chine, or process in
which
such semiconductor devices might be or are used.
Copyright © 1986, Texas Instruments Incorporated
Page 4
Contents
Section
1
1.1
1.2
TMS34010 C Compiler
Package
Product
Overview
Applicable Documents
Documentation Conventions
Page
1-1
1-2
1-2
2
TMS34010 C Compiler
Package
Installation
2-1
2.1
Installation for Texas Instruments and
IBM
PC
Systems
........
2-2
2.1.1 Hardware Requirements
..............
........
2-2
2.1.2 Installation for TIPC and
IBM
PC
Systems
with
Dual Diskette Drives
2-2
2.1.3 Installation for
PC
Systems
with
a Winchester Disk and Single Diskette
Drive
..............
2-3
2.1.4 Tools Verification on
PC
Systems
2-4
2.2
VAXNMS
Systems
2-6
2.2.1 Installation Procedure
.....
2-6
2.2.2 Tools Verification . . . . .
2-6
2.3 VAX/ULTRIX and
VAX/UNIX
System V
2-7
2.3.1 Instanation Procedure
.......
2-7
2.3.2 Tools Verification on ULTRIX and UNIX Systems
2-7
3
Invocation
and
Operation
of
the
TMS34010 C Compiler
3-1
3.1
The TMS3401 0 C Preprocessor (GSPCPP)
3-2
3.1.1 Invoking GSPCPP
3-2
3.1.2 GSPCPP Options
.....
3-2
3.1.3 Operation
of
GSPCPP
3-3
3.2 The TMS3401 0 Parser (GSPCC)
3-3
3.2.1 Invoking the Parser
3-3
3.2.2 Operation
of
the Parser
3-4
3.3
,The
Code Generator (GSPCG)
3-4
3.3.1 Invoking GSPCG
3-4
3.3.2 GSPCG Options
3-5
3.3.3 Input Requirements
3-6
3.3.4 GSPCG Output
3-6
3.4 Batch Execution
of
the C Compiler
,3-6
3.5 Assembling a C Program
3-
7
3.6 Archiving a
C Program
3-
7
3.7 Linking a
C Program
3-7
3.7.1 Run-Time Initialization
3-7
3.7.2 Object Libraries and Run-Time Support
3-8
3.7.3 The
-c
Option
in
the Linker
3-8
3.7.4 Linker Command File
.........
3-8
iii
Page 5
4
The
TMS34010 C language
4-1
4.1
Identifiers and Keywords
4-2
4.2 Constants
4-2
4.3
TMS34010
C Data Types
4-2
4.3.1 Derived Types
4-3
4.4
Object Alignment
4-4
4.5 Conversions
4-4
4.6
Expressions
4-4
4.6.1 Void Expressions
4-4
4.6.2 Primary Expressions
4-5
4.6.3
Unary Operators in Expressions
4-5
4.6.4
Assignment Operators in Expressions
4-5
4.7 Declarations
4-5
4.7.1 Storage Class Specifiers
in
Declarations
4-5
4.7.2 Type Specifiers in Declarations
4-6
4.7.3
Structure and Union Declarations
4-6
4.7.4
Enumeration
Declarations
4-7
4.8 Initialization
of
Static and Global Variables
4-8
4.9
8sm
Statement
4-8
4.10
Lexi~al
Scope Rules
. .
..
4-10
5
TMS34010 C Run-Time
Environment
5-1
5.1
Memory Model
5-2
5.1.1
TMS34010
C Stacks
5-2
5.1.2 Global Variable Memory Allocation
5-3
5.1.3
Structure Packing and Field Manipulation
5-3
5.1.4 Array Alignment
5-3
5.2 Register Conventions
5-4
5.2.1 D.edicated Registers
5-4
5.2.2
Using Registers
5-4
5.2.3
Register
Variables
5-5
5.3 Integer Expression Analysis
5-5
5.4 Floating Point Conventions
5-6
5.5
Function
Call Conventions
5-7
5.5.1 Register Usage Within Functions
5-8
5.5.2 Passing Parameters
5-8
5.5.3 Local Frame Generation
5-9
5.5.4
Function Termination
5-10
5.5.5 Restoration
of
the
CaUer's
Environment
5-11
5.5.6 Return from Function
5-11
5.6 Interrupt Handling 5-11
5.7
System Initialization
5-12
5.7.1 System Stack
5-13
5.7.2 Program Stack
5-13
5.7.3 Initialization
of
Global Variables
5-13
iv
Page 6
6
6.1
6.1.1
6.2
6.3
6.4
A
8
C
D
E
TMS34010
Run-Time
Support
Memory
Management
...........
.
Specifying the
Size
of
Memory
to
Manage
String Functions
............
.
Character Typing and Conversion Macros
Miscellaneous Functions
.......
.
Fatal
Errors
Reference
Documents
C Preprocessor
Directives
Floating
Point
Facility
Interfacing
Assembly Language
with
C
6-1
6-2
6-2
6-2
6-3
6-3
A-1
8-1
C-1
D-1
E-1
v
Page 7
Illustrations
Figure Page
1
-1 . TMS34010
C Compiler Package Interaction . . . . . . . . . . . . . . . . . . . . .
..
1-1
5-1 .
Typical Function Call
with
Parameters
Passed,
No Value Returned
5-8
D-1. Single-Precision Floating Point Format . . . . . . . . . . . . . . . . . . . . . . . .
..
D-2
D-2. Double-Precision
Floating Point Format . . . . . . . . . . . . . . . . . . . . . . . .
..
D-3
D-3. Single-Precision Normalization . . . . . . . . . . . . . . . . . . . . .
..
D-5
Tables
Table Page
4-1. TMS34010 C Data Sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
..
4-3
D-1. Floating Point Error Descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
..
D-7
vi
Page 8
1.
TMS34010
C
Compiler
Package
Product
Overview
The C programming language has become one
of
the
dominant
languages
for
high-level graphics software. Thus, C
is
a logical choice
for
systems, periph-
eral, and applications software developers using the
TMS34010
Graphics
System Processor. GSP
C,
a compiler implementation for the TMS3401 0, has
been created
to
allow
developers
to
tap this software base
for
high-
performance
TMS34010
systems. GSP C accepts standard Kernighan and
Ritchie
C source code and produces
TMS34010
assembly language source
code.
The
TMS3401 0 C Compiler Package consists
of
a C Preprocessor, a Parser,
and a
Code Generator,
as
well
as
Run-Time Support and Floating Point Li-
braries. The
TMS3401 0 Assembly Language Package supports the assembly,
archiving,-
and linking
of
compiler-generated software. The resulting execut-
able code can be run on a TMS3401 0 target system. Target systems can
include software simulators, software development boards, Texas Instruments
XDS
(Extended Development Systems) units,
or
custom TMS3401 0 systems.
An illustration
of
this interaction
is
shown
in Figure
1-1.
1MS34010
FONTS
LIBRARY
1MS34010
MATH/GRAPHICS
FUNCTION
UBRARY
Figure
1-1.
TMS34010
C
Compiler
Package
Interaction
1-1
Page 9
TMS34010 C Compiler
Package
Product
Overview
1.1
Applicable
Documents
• Kernighan, B., and
D.
Ritchie.
The
C Programming Language, Pren-
tice-Hall, Englewood Cliffs,
New
Jersey, 1978.
• Kochan, Steve
G.
Programming in
C,
Hayden Book Company.
• Sobelman, Gerald
E.
and David
E.
Krekelberg.
Advanced
C:
Techniques
and
Applications, Que Corporation, 1985.
•
TMS34010
User's Guide (SPPU005), covering all the hardware related
subjects: architecture, registers, addressing
modes, etc.
•
TMS34010
Assembly Language Tools User's Guide
(SPDU076),
cov-
ering the
assembler, linker, archiver, and PROM programming utility.
•
TMS34010
Software Development Board User's Guide (SPVU002),
describing a PC-based
tool
for developing and debugging programs for
the
TMS3401
O.
•
TMS34010
XDS/22
User's Guide
(SPDU058)
describing the most
powerful
tool
available
for
developing software
for
the TMS3401
O.
•
TMS34010
Font
Library User's Guide
(SPVU005),
describing the
font
data structure and illustrating each
of
the available fonts.
1.2
Documentation
Conventions
1-2
The documentation conventions used
in
this
book
include:
<>
Angle brackets enclose user-supplied information that
is
to be typed
out;
for
example,
<filename>
indicates
that
the name
of
the file is
to
be entered. The brackets themselves
are
not
entered, except
in
the case
of
#include
statements used in illustrating the syntax
of
some macros
(see Section
6, TMS3401 0 Run-Time Support).
[]
Square brackets enclose optional items.
A
special
fbnt
is
used
for
information displayed on the screen.
Underscoring
is
used
to
indicate the information you type
in
response
to
prompts or other screen displays.
Italics
are
used
to
highlight
function names, commands, code, and similar
items
within
a text line.
Boldface type is used
to
indicate emphasis.
In Section 4, text in the left margin gives references
to
corresponding sections
in Kernighan and Ritchie's book,
The
C Programming Language, or indicates
additional information
not
included in their book.
Page 10
2.
TMS34010
C
Compiler
Package Installation
The TMS3401 0 C Compiler operates under these operating systems:
•
MS'
-DOS Version
2.1
(or
later)
• PC-DOS2 Version
2.1
(or later)
•
VAXNMS3
• VAX/ULTRIX™3
• VAX/UNIX™4
System V
MS-DOS
is
a trademark
of
Microsoft
Corporation.
2
PC-DOS
is
a trademark
of
International Business Machines.
3
VAX,
VMS,
and ULTRIX are trademarks
of
Digital Equipment Corporation.
4
UNIX
is
a trademark
of
AT&T
Bell Laboratories.
2-1
Page 11
TMS34010 C Compiler
Package
Installation
2.1
Installation
for
Texas
Instruments
and
IBM
PC
Systems
2.1.1
Hardware
Requirements
The TMS3401 0 C Compiler requires your system
to
be configured
with
512K
bytes
of
RAM.
It
is
also recommended that the system be configured
with
a
Winchester disk.
Note:
The
MS-
DOS/PC-DOS version
of
the
TMS34010
C compiler
is
distrib-
uted on
two
floppy
diskettes. The first step for the user is
to
make backup
copies
of
the software on blank diskettes. The backup diskettes should
be used in the system instead
of
the original diskettes. This
will
afford the
advantage
of
keeping the original copy free from accidental corruption.
2.1.2
Installation
for
TIPC
and
IBM
PC
Systems
with
Dual
Diskette
Drives
2-2
Warning:
Prior
to
proceeding,
make
sure
the
distribution
diskettes
have
write-protect
tabs
applied
to
prevent
the
risk
of
destroying
the
information
on
the
diskettes.
Use
the DISKCOPY command
to
back
up
the software package onto your
blank diskettes.
Follow these steps
to
perform this backup:
1)
Insert the
MS-
DOS or PC-DOS system diskette in drive
A:.
2)
Enter:
DISKCOPY A:
B:/FIV
3) The DISKCOPY
function
prompts you
to
place the source diskette in
drive
A:. Place one
of
the distribution diskettes in drive A:.
4)
You
are
now
prompted to place the destination diskette in drive
B:.
Place
a blank diskette in drive
B:.
The DISKCOPY function copies from the distribution diskette in drive
A:
to the blank diskette in drive
B:.
The
IF
option formats the destination
diskette before copying, precluding the possibility
of
directory errors on
the backup diskette. The
IV
option checks the diskette for media errors.
5) Repeat steps 2 through 5 for each distribution diskette.
Page 12
TMS34010 C Compiler
Package
Installation
2.1.3
Installation
for
PC
Systems
with
a
Winchester
Disk and
Single
Diskette
Drive
This procedure
is
for backup
of
the distribution diskettes on a second set
of
floppy
diskettes using a single
floppy
disk drive. Additionally, it
is
recom-
mended that the distribution diskettes be backed up on the Winchester,
both
for speed
of
access,
as
well
as
for
safety
of
the software.
MS-DOS
2.1
and PC-DOS
2.1
are
operating system versions that support a
hierarchical file system. For these systems
it
is
recommended that a subdirec-
tory
for
TMS3401 0 development tools be created.
Warning:
Prior
to
proceeding,
make
sure
the
distribution
diskettes
have
write-protect
tabs
applied
to
prevent
the
risk
of
destroying
the
information
on
the
diskettes.
To back up the distribution diskettes using the single
floppy
disk drive,
follow
these steps:
1)
Making sure that the
utility
function DISKCOPY.COM
is
available
for
execution, type:
DISKCOPY
A:
B:/F/V
2)
The DISKCOPY function prompts you to place the source diskette
in
drive
A.
Place one
of
the distribution diskettes
in
drive A:. The
DISKCOPY function accesses the disk to determine its type and format.
3)
You are then prompted to replace the source diskette in drive
A:
with
the
destination diskette. Place a blank diskette in drive
A:.
The
IF
option
of
the DISKCOPY function causes the destination diskette
to
be
formatted
before copying, precluding the possibility
of
directory errors on the
backup diskette. The
IV
option
checks the diskette
for
media errors.
4)
After DISKCOPY formats the. backup diskette, it prompts you
to
switch
back and forth between the source and destination diskettes, copying
the distribution diskette
to
the backup diskette. After each distribution
diskette has been copied,
DISKCOPY prompts you for more diskettes to
copy. Respond
YES
until all the distribution diskettes
are
copied.
If
you plan to place the TMS3401 0 software tools
in
a directory on the
Win-
. chester disk
as
recommended,
follow
these steps:
1)
Create a subdirectory
to
contain the
TMS34010
development tools by
typing:
MKDIR
\GSPTOOLS
2)
Make the
TMS34010
development tools directory the current directory
by typing:
CD \GSPTOOLS
2-3
Page 13
TMS34010 C Compiler
Package
Installation
3)
Place a distribution diskette in drive A:. Copy the contents
of
the
dis-
tribution diskette by typing:
COPY A:*.*
Li..
The IV
option
causes the system
to
verify that. after copying, the source
and the destination
files
are
identical.
4)
Repeat step 3
for
each distribution diskette.
5)
Makj3 sure the directory you placed the tools in (in this example,
GSPTOOLS)
is
in the current pathway.
2.1.4
Tools
Verification
on PC Systems
2-4
When the TMS3401 0 development tools have been backed up
and/or
copied
onto
the Winchester disk, verify that your copies
are
executable. Use the batch
file GSPC.BAT provided in the package
for
this verification. This batch file
first calls the C preprocessor (GSPCPP), then the parser (GSPCC), the code
generator next
(GSPCG), and finally the assembler (GSPA). The result
is
linkable object code. When using this batch file, remember that you must have
installed the
TMS34010
Assembly Language Package on your system; this
package
includes the assembler (GSPA), the linker (GSPLNK), the simulator
(GSPSIM).
and the archiver (GSPAR).
1)
To verify that the compiler
is
properly installed, invoke GSPC.BAT
to
compile the file TESTC34.C
by
typing:
GSPC TESTC34
2)
The batch file responds
with:
---[TESTC34]--C
Pre-Processor,
<version
number>
©
Copyright
1985,
1986
Texas
Instruments
Inc.
GSP C Compiler,
<version
number>
©
Copyright
1985,
1986
Texas
Instruments
Inc.
"TESTC34.C":
~~>
MAIN
GSP C Codegen,
<version
number>
©
Copyright
1985,
1986
Texas
Instruments
Inc.
"TESTC34.C":
~~>
MAIN
GSP
COFF
Assembler,
<version
number>
©
Copyright
1985,
1986
Texas
Instruments
Inc.
PASS
1
PASS
1.1
ON
SECTION
.text
PASS
2 .
No
Errors,
No
Warnings
3)
Verify the operation
of
the
TMS34010
linker. The link command file
TESTC34.CMD
is
included in the package
for
linking the
output
of
the
compiler and assembler together
with
the runtime support (RTS.LlB)
and floating
point
(FLlB.LlB)
libraries. Type:
GSPLNK TESTC34.CMD
Page 14
TMS34010
C
Compiler
Package
Installation
The
TMS3401
0 linker responds with:
GSP
COFF
Linker,
<version
number>
©
Copyright
1985,
1986
Texas
Instruments,
Inc.
where <version number>
is
the version number of the current
TMS34010
linker.
4)
Continue verification of the
TMS3401
0 development tools
by
invoking
the
TMS3401
0 simulator. Type:
GSPSIM
TESTC34
The
TMS34010
simulator responds by loading the linked output
TESTC34.0UT
and displaying the register file and status information.
After the simulator's display
has
been placed
on
the screen,
run
the
linked output by typing:
RUN
<return>
The simulator responds by displaying:
YOU'RE
OK,
WE'RE
OK!!!
in
white letters
in
the
center
of the scratch display area. Exit the simu-
lator by typing:
Q*
<return>
5)
Conclude the verification
session
by
testing the object/source archiver.
Type:
GSPAR!
RTS.L1B
The archiver responds by giving a table of contents for the runtime support library, similar to the following:
GSP
Archiver
<version
number>
©
Copyright
1985,
1986
Texas
Instruments,
Inc.
FILE
NAME
SIZE
DATE
atof.obj
1216
Tue
Aug 12
00
01
04
1986
atoi.obj
450
Tue
Aug
12
00
01
04
1986
boot.obj
572
Tue
Aug
12
00
01
04
1986
ctype.obj
464
Tue
Aug
12
00
01
04
1986
Itoa.obj
424
Tue
Aug
12
00
01
04
1986
memory.obj
1874
Tue
Aug 12
00
01
04
1986
movmem.obj
382
Tue
Aug
12
00
01
04
1986
printf.obj
878
Tue
Aug
12
00 01
04
1986
strcat.obj
358
Tue
Aug
12
00
01
04
1986
strchr.obj
352
Tue
Aug
12
00
01
04
1986
strcmp.obj
360
Tue
Aug
12
00
01 04
1986
strcpy.obj
350
Tue
Aug
12
00
01
04
1986
strlen.obj
340
Tue
Aug
12
00 01
04
1986
strncat.obj
374
Tue
Aug
12
00
01
04
1986
strncmp.obj
376
Tue
Aug
12
00
01 04
1986
strncpy.obj
372
Tue
Aug
12
00
01
04
1986
strrchr.obj
352
Tue
Aug
12
00
01
04
1986
fconvert.obj
342
Tue
Aug
12
00
01
04
1986
setjmp.obj
332
Tue
Aug
12
00
01 04
1986
2-5
Page 15
TMS34010 C Compiler
Package
Installation
2.2
VAX/VMS
Systems
The tape provided was made at
1600
BPI using the
VMS
BACKUP utility.
Follow
the instructions in this section
to
install and
verify
the tools contained
on the tape.
2.2.1
Installation
Procedure
1 )
Mount
the tape on your tape drive.
2)
Execute the
following
VMS
commands. Note
that
you must create a
destination directory in
which
to
put the tools. This example uses
DEST:<dest-directory> to indicate the destination. TAPE:
is
to
be re-
placed
with
the name
of
the tape drive being used in the backup proce-
dure.
$
allocate
$
init/den;1600
$
mount/for
$
backup
$
dismount
$
dealloc
TAPE:
TAPE:gspc
TAPE:
TAPE:gspc.bck
DEST:<dest-directory>
TAPE:
TAPE:
3)
The product tape contains a command file called setup. com. This file
is
used to set up
VMS
symbols that
allow
the tools
to
be executed
in
the
same manner
as
any other command. This command file must be run
as
follows:
$
@setup
DEST:<dest-directory>
This sets
up
symbols to be used to call the various tools. The symbols
defined
are
listed on the screen by the command file.
2.2.2
Tools
Verification
2-6
The product tape contains a test file (testc34.c) that can
be
compiled and
compared
with
testc34.cmp
to
ensure that the C compiler has been installed
correctly
and
is
functioning.
For
example, enter:
$
gspcpp
testc34
$
gspcc
testc34
$
gspcg
-*
testc34
This produces
an
assembly language file testc34.asm,
which
should
be
exactly
like
the file testc34.cmp shipped on the product tape.
Page 16
TMS34010 C Compiler
Package
Installation
2,3
VAX/ULTRIX
and
VAX/UNIX
System
V
The tape provided was made at
1600
BPI using the
tar
utility. This section
instructs you in
installing and verifying the tools contained on the tape.
2,3,1
Installation
Procedure
1)
Mount
the tape on your tape drive.
2) Make the current directory the directory into
which
the tools
will
be re-
stored.
3) Enter the
tar
command appropriate for your system;
for
example:
tar~
This copies the entire tape
into
the current directory.
2,3,2
Tools
Verification
on
ULTRIX
and
UNIX
Systems
The product tape contains a test file (testc34.c) that can be compiled
to
en-
sure that the
working
C compiler has been installed. The tape contains the
correct
output
file
to
compare
to
the file created during the test.
For
example, enter:
9MlQQQ testc34
~
testc34
~
.:l: testc34
This creates the assembly
file testc34.asm,
which
can be compared
to
the
testc34.cmp file shipped on the tape.
2-7
Page 17
TMS34010 C Compiler
Package
Installation
2-8
Page 18
3.
Invocation
and
Operation
of
the
TMS3401
0 C
Compiler
The TMS3401 0 C compiler consists
of
three parts:
• Preprocessor (GSPCPP)
• Parser (GSPCC)
• Code
generator (GSPCG)
The
output
of
the code generator must be assembled
with
the
TMS34010
COFF
(common
object file format) assembler and linked
with
TMS34010
C
Run-Time
Support
using the COFF linker
(GSPLNK)
to
produce executable
object
code. Refer
to
the
TMS34010
User's Guide and
UNIX
COFF
doc-
umentation for details
of
the
object file format.
Note:
Each
of
the tools discussed here has
options
available for use in the
in-
vocation (command) line. These
options
are unique among themselves
and must be used
as
shown
herein.
Any
other items included in the
in-
vocation may
be
ignored or may cause errors.
3-1
Page 19
Invocation
and
Operation
of
the
TMS34010 C Compiler
3.1
The
TMS34010
C
Preprocessor
(GSPCPP)
The C preprocessor, GSPCPP,
is
invoked
as
the first
pass
of
the TMS3401 0
C
compiler. GSPCPP handles macro definitions and substitutions, #include
files, line number directives, and conditional compilation. The preprocessor
requires the original
C source file
as
input and produces
as
output
a modified
source
file suitable for input
to
GSPCC.
This preprocessor
is
the
same
preprocessor described in
The
C Programming
Language,
by
B.
Kernighan and
D.
Ritchie (referred to hereafter
as
K&R).
Additional information
can
be
found in that book.
3.1.1
Invoking
GSPCPP
The preprocessor begins execution when the
following
command
is
entered:
where:
input
file
output
file
options
.9.2.I2.£E£
[input
file]
[output
file]
[option's]
is
the name
of
the C source file used
as
the input file.
If
no
extension
is
given,
an
extension
of
.c
is
assumed.
If
no input
file
is
given, a prompt appears.
is
the name
of
the file
output
by GSPCPP. The
output
file
can
be
omitted, in
which
case
the name given
to
the
out-
put-file defaults
to
the
input-file
name
with
an
extension
of
.cpp.
lists any
of
the available GSPCPP options (see Section
3.1.3). The options parameter can appear anywhere in the
invocation
line and can be used multiple times.
3.1.2
GSPCPP
Options
3-2
GSPCPP's options
are
case-sensitive,
single-letter fields prefixed
by
hy-
phens
(-).
Some options have additional fields,
which
immediately
follow
the
option letter
with
no
intervening
spaces. The following list describes
op-
tions available; each option
is
uppercase.
-p
Tells the preprocessor
not
to produce the line number and
file :i3-P information used by the compiler. The compilation is otherwise the same
as
if
this information were
produced.
-C
Copies comments to the
output
file. Otherwise, GSPCPP
strips comments.
-D<name>=def
Defines name
as
if
the
following
line appeared at the
top
of
the input file:
#define
name
def
The symbol name is then recognized for
#if
and
#ifdef
statements,
without
having been explicitly defined in the
text
of
the program.
Page 20
Invocation
and
Operation
of
the
TMS34010
C
Compiler
-I<dir>
The
=del
can be omitted, in
which
case name is defined
to
the value 1 .
This
option
can be used multiple times
for
defining
mul-
tiple names
by
separating the
-D
options
by
spaces.
(Uppercase
i) Adds dir to the list
of
directories
to
be
searched for
#include files. Omitting
dir
causes
option
-I
to be ignored. This option can
be
used mUltiple times,
each one separated by a space,
to
search more directories.
3.1.3
Operation
of
GSPCPP
GSPCPP maintains and recognizes the name -
-LlNE-
-
as
the current
line number
(a
decimal integer) and the name -
-FILE-
-
as
the current
file name
(a
C string). Note
that
these names begin
with
two
underscore
characters and end
with
two
underscore characters
with
no
spaces
be-
tween
the
characters.
You can use these names in the same
way
as
any
other defined
name,
including
using them in macros.
All
GSPCPP directives begin
with
the character
#,
which
must appear in
col-
umn 1.
Any
number
of
blanks and tabs are allowed between # and the
di-
rective name. The directives are described in Appendix
C,
and additional
information can be
found
in K&R.
The error messages produced
by
the preprocessor are self-explanatory; the line
number and the filename where the error occurred are printed along
with
the
diagnostic.
3.2
The
TMS34010
Parser
(GSPCC)
The parser, GSPCC, is the second pass
of
the C compiler.
It
reads
the
output
of
GSPCPP (the preprocessor), parses
it
perfo.rms syntax checking, and writes
an
intermediate file
for
input
to
the code generator (GSPCG).
3.2.1
Invoking
the
Parser
The parser
is
invoked
with
the
command:
~
[input
filel
[output
filel
1:.ll
where:
input
file
output
file
-z
is the name
of
the
input
file. The default extension
for
the
input
file
is
.cpp
if
none
is
specified.
If
no
input
file is given,
a
prompt
appears.
is
the name
of
the
output
file. This is
the
intermediate file
used
as
input
to
the GSPCG.
If
this argument is omitted, the
intermediate file is given the same name
as
the
input
file
with
the default extension .il.
is the
option
which
retains the
.cpp
input
file. The
.cpp
file
is
deleted
if
-z
is
not
specified. This parameter can be
placed anywhere in the invocation line.
3-3
Page 21
Invocation
and
Operation
of
the
TMS34010 C Compiler
3.2.2
Operation
of
the
Parser
The parser reads the C program (optionally preprocessed) and checks for er-
rors, then
outputs
an
intermediate file
which
is
used
as
input
to the code
generator.
Most
errors
are
fatal; that is, they prevent generation
of
an
intermediate file and
must be corrected before compilation can be completed.
Some errors,
how-
ever, merely produce warnings
which
hint
of
problems
but
do
not
prevent
compilation.
As function definitions
are
encountered, the parser prints a progress message
containing the name
of
the source file and the name
of
the function. For ex-
ample:
Iisource.cl':
=>
main
The message lets you
know
how
far along the compiler
is
in its execution and
helps identify the location
of
errors.
After it finishes parsing,
GSPCC deletes the
input
file if the
input
file's exten-
sion
is
.cpp
and the
-z
option
is
not
specified. Otherwise, the
input
file
is
kept.
3.3
The
Code
Generator
(GSPCG)
The code generator (GSPCG) converts the intermediate code generated by'the
parser
into
assembly language source code suitable
for
direct input
to
the as-
sembler
or
for modification
with
a text editor. The code produced by GSPCG
is
reentrant, relocatable, and can be stored in ROM.
3.3.1
Invoking
GSPCG
3-4
The
following
command invokes GSPCG:
.'l§££9:
[input
file]
[output
file]
[tempfile]
[options]
where:
input
file
output
file
tempfile
options
is the name
of
the
input
file,
which
is
the file
output
by
GSPCC
with
the
extension.if.
If
this argument
is
not
speci-
fied, a prompt appears.
is
the name
of
the
output
file to
be
generated. The default
name
for
the file
is
the name
of
the
input
file appended
with
the extension .8sm.
is
the name
of
the temporary file generated and used by the
GSPCG. The default name
is
the
input
filename appended
with
extension .tmp. This file is deleted after use by GSPCG.'
lists
any
of
the available GSPCG options (see Section 3.3.2,
GSPCG Options). These options can appear anywhere
in
the
invocation
line and
are
not
restricted
to
follow
the list
of
fi-
lenames.
Page 22
Invocation
and
Operation
of
the
TMS34010
C
Compiler
3.3.2
GSPCG
Options
The options parameter in the invocation command
is
a character preceded by
a hyphen in the format:
-x[x]
...
where x represents
an
option
character. These option characters can appear
anywhere in the invocation line; they
are
not
restricted
to
follow
the list
of
filenames given. Options can
be
strung together in any order.
The options available
are:
-a
Indicates there may be assignments
of
the form
·ptr=
...
where
ptr
is
a
pointer
to
a named variable. A module containing assignments
of
this
form can be compiled
without
this option, provided
ptr
does
not
point
to
a named variable. For example, if
ptr
points to
an
element
of a dy-
namically- or statically-allocated array, the assignment
of
values
to
the
array elements using the form
·ptr=
...
does
not
require compilation
of
the
module
with
the -a option. Structures
are
also
not
considered
to
be
named variables.
The compiler
normally remembers that a register contains a constant
or
the value
of
a named variable, so
it
does
not
'regenerate code to load that
value into a register. The compiler also assumes that
an
assignment
of
the form
·ptr=
...
does
not
assign a value
to
a named variable. Because
it
cannot
know
the named variable that this assignment affects,
if
any,
it
must forget the contents
of
all registers it assumed contained values
of
named variables upon encountering such
an
assignment. Thus,
when
the -a option
is
used, the compiler generates less efficient code, because
it forgets these registers' contents and has
to
regenerate the code.
However, this
is
very rarely a problem.
-0
Directs GSPCG
to
produce high-level-language debug directives in the
output
code. See the assembler section
of
the TMS34010 Assembly
Language Tools
User's Guide and the UNIX COFF documentation
for
more information about the types
of
debug information produced.
-v
Directs GSPCG
to
produce code
which
can run in a mUltiprocess envi-
ronment where
all variables may be considered volatile. This flag should
be used
to
compile modules
which
access variables
that
could be
modi-
fied by another task (process). In general, code generated this
way
is
somewhat less efficient.
-z
Causes GSPCG
to
not
delete the
input
file (intermediate file generated
by
GSPCC). This could be useful for generation
of
several object
mod-
ules
with
different GSPCG options.
-r
Causes GSPCG
to
periodically
write
a register status table to the
output
(assembly language) source file. The table
is
in the form
of
assembly
language comments, and lists each register currently used by
GSPCG.
It
also
shows
the type
of
each register's current contents. The table is
printed between statements whenever the contents
of
registers could
change. This
is
very useful
if
you
want
to
modify
the assembly language
output.
3-5
Page 23
Invocation
and
Operation
of
the
TMS34010 C Compiler
*
An example:
**********************************************
* AS -
EXPRESSION
FREE
*
* A7 - USER VARIABLE
FREE
SYMBOL;
-ABC
*
* A9 - USER
REGISTER
USED *
**********************************************
Instructs
GSP.CG
to
generate code
which
runs on certain preproduction
units
of
the TMS3401
O.
This option
is
not
needed when compiling code
·for production units
of
the TMS3401
O.
Certain instructions
not
available
in preproduction units
are
not
used when this
option
is
invoked.
3.3.3
Input
Requirements
GSPCG
input
must
be
the intermediate file produced by the parser. The
out-
put'of
the parser
is
fed,
without
modification, directly to the GSPCG.
3.3.4
GSPCG
Output
GSPCG converts the intermediate file generated
by
the parser into assembly
lanQuage
source code suitable for
input
to
the assembler
or
for
modification
with
a text editor. This code
is
reentrant, relocatable, and can
be
stored in
ROM.
3.4
Batch Execution
of
the C Compiler
3-6
The C compiler package contains the batch file GSPC.BAT,
which
executes
the three phases
of
the compiler and the assembler. This batch file
is
invoked
as
follows:
where:
input
file
Example:
is
the name
of
the C source file. The default extension
of
this
file
is
.c. A prompt appears
if
no file name
is
given.
.9.2E.£
PROGRAM
This example uses PROGRAM.C
as
the C source file and generates PRO-
GRAM.ASM
as
the assembly file and PROGRAM.OBJ
as
the object file.
PROGRAM.OBJ
can be used
as
input
to
the linker, GSPLNK.
Page 24
Invocation
and
Operation
of
the
TMS34010
C
Compiler
3.5
Assembling
a C
Program
The GSPC batch file
automatically
produces and assembles
TMS34010
as-
sembly language source from C programs, The assembly language source file
is
available
under
the name
<input
file>,ASM,
If
you
wish
to
see
an
assembler
listing
of
the file,
you
must
explicitly
assemble this file using the
-I
option
of
the
GSP assembler, •
Appendix
E is
an
example
showing
the assembly language produced from C
programs,
3.6
Archiving
a C
Program
C program
object
files may be archived using the GSPAR archiver program,
Libraries
should
be organized so
that
all references
to
external symbols
or
functions
are defined
within
the same library
or
in a
following
library, See the
TMS34010
Assembly
Language Tools User's Guide
for
more information,
3.7
Linking a C
Program
Modular
code is an
important
concept
in
writing
software
because it simplifies
the tasks
of
debugging
and
porting,
To
make
this
modularization
possible, the
programmer
must
have
the
capability
to
link
separate
modules
into
one exe-
cutable program, The
TMS3401
0 C
environment
offers
this
capability
by
pro-
viding
an assembler
that
produces
object
code
which
is linkable
by
the
TMS34010
linker.
In
the
simplest case, a C program consisting
of
modules
prog1,
prog2, etc, can
be
linked
to
produce
an
executable
output
file called
prog,out
by
invoking
the
linker
as
follows:
gsplnk
~
~
prog.out
progl.obj
prog2.obj
~
rts.lib
[flib.libJ
For
further
information,
refer
to
the
TMS34010
Assembly
Language Tools
User's Guide,
3.7.1
Run-Time
Initialization
All
C programs
must
be linked
with
an
object
module
called boot.obj,
which
contains
code
and data
for
initializing
the
run-time
environment, This
is
the
first
code
executed
when
the
program begins
running,
and
it
has the
following
responsi bi I ities:
• Sets
up
the
system stack.
• Processes
the
run-time
initialization table and auto-initializes
global
variables,
• Disables
interrupts and calls
-main.
Boot.obj
is
supplied
in
the
run-time
support
object
library RTS,LI
B,
If
you
use
the C code
option
with
GSPLNK
and
include
RTS,LlB in
your
link
control
file,
boot.obj
is
automatically
linked in (see Section 3,7,3, The
-c
Option
in the
Linker).
Alternatively,
you
can use the archiver GSPAR
to
extract
boot.obj
from
the library and
link
it
in explicitly.
3-7
Page 25
Invocation
and
Operation
of
the
TMS34010 C Compiler
3.7.2
Object
Libraries and
Run-Time
Support
The archive library RTS.LlB contains code for
boot.obj,
plus all additional C
run-time support functions. These functions
are
described in Section 6,
TMS34010
Run-Time Support.
If
your
program uses any
of
these functions,
RTS.LlB must be
linked in
with
your
object files.
Any
program
that
uses floating
point
math must include the
TMS34010
floating
point
library,
which
contains functions called
by
the compiled
pro-
gram
to
perform floating
point
operations. This library
is
called
FLlB.LlB
(see
Appendix D for
more information
about
the floating
point
library).
Note:
Programs that
do
not
use floating
point
need
not
be linked
with
FLlB.LlB.
You can create your
own
object libraries and link them in. The linker operates
so
that
only
those modules from the library
that
define unresolved references
will
be included and linked. Refer
to
the detailed linker documentation in
TMS34010
Assembly Language Tools User's Guide.
3.7.3
The
-c
Option
in
the
Linker
The linker has
an
option
-c
to
ease
linking C programs. Use the
-c
option
on
the command
line
or
in the
link
control file. The
-c
option
has the
following
effects:
• Forces
-c-intOO
to
be the entry point.
-c-intOO
is
the start
of
the
run-time initialization code in boot.obj. This
also causes
boot.obj
to
be
included from the archive library since
boot.obj
is
the module that de-
fines the
symbol
-c-intOO.
• Adds
two
bytes
of
zero padding at the end
of
the .data section. This
is
required
to
terminate the initialization tables.
3.7.4
Linker
Command
File
3-8
The
following
is
an
example
of
a typical command file
for
linking a C program.
The C program consists
of
two
C modules,
main.obj
and sub.obj, and
an
as-
sembly language module, asm.obj. The program uses floating
point
and se-
veral routines from
an
archive library called matrix.lib.
-c
-m
example.map
-0
example.out
main.obj
sub.obj
asm.obj
flib.lib
rts.lib
matrix.
lib
/*
linking
a C
program
*/
/*
create
a map
file
*/
/*
specify
name
of
output
file
*/
/*
user's
first
C
module
*/
/*
user's
secondC
module
*/
/*
user's
asm
module
*/
/*
floating
point
library
*/
/*
run-time
support
library
*/
/*
user's
archive
library
*/
Page 26
Invocation
and
Operation
of
the
TMS34010
C
Compiler
Example
Description.
First, the desired linker options are listed:
-c
Option used
for
linking C programs,
as
described in the previous sec-
tion.
If
-c
is
not
used, its effects must be provided using other linker
directives.
-m
Option used
to
create a map file.
Follow
the
option
with
a string that
represents a valid file name.
-0
If
no errors occur
during
link
time, the linker creates an .out (executa-
ble) file. The default file name for this file
is
a.out.
If
you
wish
to
alter
this default file
name, use the
-0
option
followed
by a string repres-
enting a valid file name.
Next, all the object files
to
be linked
are
listed, in any order. One
of
these files
must define the symbol
main, because boot.obj calls main
as
the start
of
your
C program.
Note:
If
any
of
the files
are
in assembly language,
they
may
not
contain .data
sections because this
will
corrupt the C auto-initialization environment.
Any
included .obj files
are
linked into the resultant
.out
file, whether they are
used
or
not,
while
only
referenced files from libraries
are
linked in.
Finally, all the archive object libraries
that
are
to
be searched
are
listed. Only
modules from the libraries
that
resolve unresolved references
are
included in
the
output
file.
3-9
Page 27
Invocation
and
Operation
of
the
TMS34010 C Compiler
3-10
Page 28
4.
The
TMS3401
0 C Language
The C language compiled by the TMS3401 0 C compiler
is
based on the
UNIX
System V C language
as
described by K&R
with
some additions and clarifica-
tions. The most significant differences
are:
•
Addition
of
enum data type.
• Unique member names in structures
not
required.
• Pointers to fields
within
structures
are
allowed.
• Structures and unions may be passed
as
parameters
to
functions, re-
turned by functions, and assigned directly.
This section
is
a comparison
of
the C language compiled by TMS3401 0 C and
the C language described by Kernighan and Ritchie
(K&R
C).
Note:
Only the differences in the
two
forms
of
the C language
are
discussed
here. The standard K&R C
is
followed
except
as
contradicted by this sec-
tion. Section numbers from K&R's
"C
Reference Manual", Appendix A
of
The
C Programming Language,
are
shown
in the left margin for reference.
4-1
Page 29
The
TMS34010
C Language
4.1
Identifiers
and
Keywords
K&R
2.2
K&R
2.3
TMS34010
C treats the first
31
characters
of
an
identifier
as
significant,
as
compared
with
eight
in
K&R
C.
This also applies
to
external names. Case
is
significant: uppercase characters are different from lowercase characters
for
identifier names in all TMS3401 0 C tools.
Three keywords exist
in
addition.
to
the list in K&R. The
new
keywords
are:
asm, void, and enum.
4.2
Constants
K&R
2.4.1
K&R
2.4.3
Added
type
K&R
2.5
All integer constants
are
of
type
int
(signed,
32-bit
length). Invalid digits in
constants
(i.e., 8 and 9 in octal) cause a warning message.
The escape code
\v
is
recognized in character and string constants
as
a vertical
tab character
(ASCII code
11).
in addition to the escape codes listed in K&R.
Enumeration constants
are
a special type
of
integer constant
not
described
by
K&R. An identifier declared
as
an
enumerator can be used wherever
an
integer
constant can be used.
See
Section 4.7.4, page
4-6,
for
more information.
The maximum length
of
any string constant
is
255
bytes in
TMS34010
C,
where the length
is
unlimited in K&R
C.
All characters after
an
embedded null byte in a string constant are ignored; in
other
words, the first null byte terminates the string. However, this does
not
apply
to
strings used
to
initialize arrays
of
characters.
Identical string constants
are
stored
as
a single string,
not
as
separate strings
as
in K&R
C.
However, this does
not
apply
to
strings used
for
any
auto-ini-
tialization
of
arrays
of
characters.
4.3
TM
834010 C Data
Types
K&R4.0
4-2
The char data type
is
signed. A separate type, unsigned char,
is
supported.
Long
and
int
are
functionally equivalent types, and either can be declared
unsigned. The properties
of
enum types
are
identical
to
those
of
unsigned
into
There
is
an
additional type called void,
which.is
used
to
declare a
function
that
returns no value. The compiler checks that functions declared
as
void
do
not
return values and that they
are
not
used
in
expressions. Functions
are
the
only type
of
objects
that
may be declared void.
Page 30
The
tMS34010
C Language
4.3.1
Deri~ed
Types
K&R
2.6
TMS34010
C allows any type declaration to have up to six derived types.
Constructions such
as
"pointer
to",
"array of", and
"function
returning" can
be combined and
applied only this number
of
times.
For
example:
int
(*
(*n
l]
l] ) ()
) ( ) ;
translates
as
"an array
of
arrays
of
pointers to functions returning pointers
to
functions returning integers."
It
has six derived types, the maximum allowed.
Structures, unions, and enumerations
are
not
considered derived types
for
the
purposes
of
these limits.
Also,
the derived type cannot contain more than three array derivations. Note
that each dimension in a
multi-dimensional array
is
a separate array derivation;
thus, arrays
are
limited to three dimensions in any type definition. However,
types can be combined
to
produce any dimensioned array.
For
example, the
following
construction declares x
as
a four-dimensional ar-
ray:
typedef
int
dim2l]
l];
dim2
xl]
l];
Table 4-1 summarizes TMS3401 0 C data types:
char
unsigned char
short
unsigned short
int
unsigned
int
long
unsigned long
pointers
float
double
enum
Table
4-1.
TMS34010 C Data
Sizes
8 bits, signed ASCII
8 bits, ASCII
16
bits
16
bits
32 bits
32 bits
32 bits
32
bits
32 bits
32
bits range: + -5.88 x 1
O(
-39)
through
+-1.70 x 10
38
64
bits range: + -1.11 x
1Q(
-308)
through
+ -8.99 x
10
308
1-32
bits - see Section 4.7.4
4-3
Page 31
The
TMS34010
C Language
4.4
Object
Alignment
All objects except structure members and array members
are
aligned on a
16-bit
(one
word)
boundary. In other words,
with
the exception
of
structure
and array members,
all objects begin at
bit
addresses whose
four
LSBs are
zeros.
In addition, because
of
the TMS3401
O's
bit
addressability, pointers can
point
to
any
bit
address. Signed objects
of
less than
16
bits
are
sign-extended
to
16
bits. Unsigned objects
of
less than
16
bits
are
zero-extended
to
16
bits.
Structure or array members
are
not
aligned
to
16-bit
boundaries. However, the
structure
or
array itself begins at a
16-bit
boundary. In the case
of
an
array
of
structures,
only
the first structure in the array
is
constrained
to
begin on a
16-bit
boundary.
For additional information on array alignment,
see
Structure Packing and Field
Manipulation, 5-3.
4.5
Conversions
K&R 6.1 Integer objects
are
always widened
to
32
bits when passed
as
arguments
to
a
function. Signed objects
of
less than
32
bits
are
sign-extended
to
32 bits;
unsigned objects
of
less than
32
bits
are
zero-extended
to
32
bits.
K&R6.3
K&R
14.4
The type char
is
signed and
is
therefore sign-extended
when
widened
to
in-
teger type. Sign extension can be disabled
by
using the type unsigned char.
Float and double types
are
converted
to
integer types by truncation.
All float variables
are
converted
to
doubles before arithmetic operations
or
before being passed
as
arguments
to
a function. .
Pointers and integers (or longs) may be freely converted, since each occupies
32
bits
of
storage.
Pointersto
one data type can also be converted
to
pointers
to
another data type, since the TMS3401 0 has no alignment restrictions and
all pointers
are
the same size.
4.6
Expressions
4.6.1
Void
Expressions
Added
type
4-4
A function
of
type
void
has no value (returns
no
value) and cannot be called
in any
way
except
as
a separate statement
or
as
the left operand
of
the comma
operator. Functions can be declared or typecast
as
void.
Page 32
The
TMS34010
C Language
4.6.2
Primary
Expressions
K&R
7.1 In
TMS34010
C,
functions
can return structures or unions. However, it
is
il-
legal to combine a function call
with
the structure-reference operator ".". Thus,
primary expressions
of
the form f(E).5
are
not
allowed. Note that this re-
striction does
not
apply to the indirect structure-reference operator "
....
", so
that
f(E)
....
s
is
legal.
The restriction
of
three array dimensions does
not
apply
to
expressions, be-
cause [ ]
is
treated
as
an
operator.
4.6.3
Unary
Operators
in Expressions
K&R
7.2 The value yielded by the sizeof operator
is
calculated
as
the total number
of
bits used to store the object divided
by
eight. (Eight
is
the number
of
bits
in
a character.) Size
of
can be legally applied
to
enum objects and
bit
fields: if
the
result
is
not
an
integer, it
is
rounded up to the nearest integer.
4.6.4
Assignment
Operators
in Expressions
K&R
7.14
The
obsolete C assignment operator =op
is
recognized
by
TMS34010
C,
along
with
the current op=. Its use, however, causes a warning message to
be issued.
4.7
Declarations
4.7.1
Storage
Class
Specifiers
in
Declarations
K&R 8.1 The first four local objects declared
as
register in a
function
will
be
stored
in
TMS34010
registers. A register can store
float
objects
as
well
as
objects
of
any
integer or pointer type, and
will
significantly improve the efficiency
of
ac-
cessing the object. See also Section 5.2, Register Conventions, page 5-4.
Register
variables declared
as
short
or char
are
treated
as
into
A register declaration
of
an
invalid type or a declaration after the first four re-
gisters have been declared
is
treated
as
a normal auto declaration.
Note
that
functions' arguments declared
as
register
are
not
implemented in this
release. The register class
is
ignored
for
argument variables.
4-5
Page 33
The
TMS34010
C Language
4.7.2
Type
Specifiers
in
Declarations
K&R
8.2
In addition
to
the type-specifiers listed in K&R, objects may be declared
with
enum-specifiers. Enumerations
are
described in Section 4.7.4, page
4-6.
K&R8.4
K&R 10
More type name combinations
are
allowed in
TMS34010
C than
in
K&R
C.
The adjectives
long
and
short
may be used
with
or
without
the
word
int; the
meaning
is
the same in either
case.
The
word
unsigned
can be used in
con-
junction
with
any integer type or alone;
if
alone,
int
is implied.
Long
float
is
a synonym
for
double. Otherwise,
only
one type specifier
is
allowed in a
declaration.
Contrary
to
K&R,
functions
may return structures or unions
in
TMS34010
C.
In addition, structures and unions may
be
used
as
parameters
to
functions and
may be directly assigned.
Formal parameters
to
a function may
be
declared
as
struct
or enum (in addi-
tion
to
the normal function declarations), since
TMS34010
C allows these
types
of
objects
to
be passed to functions.
4.7.3
Structure
and
Union
Declarations
K&R8.5
K&R
14.1
.
4-6
Since the TMS3401 0
is
bit-addressable, no alignment
of
any kind occurs for
structure members.
Ignore any comment in K&R
about
alignment
or
bounda-
ries for structure members. Note that a field
with
width
zero, normally used
to
force alignment.
is
ignored.
It
is
true, however,
that
bit
fields
are
limited to a
width
of
32
bits (see Object Alignment, page
4-4,
and Structure Packing and
Field Manipulation, page
5-3).
Any
integer type may be declared
asa
field. Fields
are
treated
as
signed unless
declared otherwise. Also, contrary
to
K&R, pointers
to
fields
are
legal in
TMS34010
C.
K&R states
that
structure and union member names must be mutually distinct.
In TMS3401 0
C,
members
of
different structures
or
unions may have the same
name. However, this requires that references
to
the member
be
fully qualified
through
all levels
of
nesting.
Again,
TMS34010
C
allows
assignment to
and
from structures, passing
structures as parameters,
and
returning structures from functions.
There
is
a comment in K&R regarding the compiler determining the type
of
a
structure reference
by
the member name. Since member names
are
not
re-
quired
to
be unique in TMS3401 0
C,
this
is
not
valid. All structure references
must be
fully
qualified
as
members
of
the structure or union
in
which
they
were declared.
Page 34
The
TMS34010
C Language
4.7.4
Enumeration
Declarations
Additional
Enumerations
allow
the use
of
named integer constants in
TMS34010
C.
The
syntax
of
an
enumeration declaration
is
very similar
to
that
of
a structure
or
union. The keyword enum
is
substituted
for
struct
or
union, and a list
of
enu-
merators
is
substituted
for
the list
of
members.
Enumeration declarations have a
"tag",
as
do
structure and union declarations.
This tag may be used in future declarations,
without
repeating the entire dec-
laration.
The list
of
enumerators
is
simply a comma-separated list
of
identifiers.
Each
identifier may be either alone
or
followed
by
an
equal sign and
an
integer
constant.
If
no
enumerators
with
"="
appear, then the values
of
the successive
enumerators begin at zero and increase
by
one
for
each identifier. An identifier
with
an
assigned value assumes
that
value, -and subsequent enumerators
continue
counting
by
one from there. The assigned value may
be
negative,
but
counting
still continues
by
positive one.
An object
of
type enum has a size determined
as
follows:
if
any
of
the object's
enumerators have negative values, the object occupies
32
bits. Otherwise, the
object occupies the minimum number
of
bits required
to
represent the largest
enumerator value
and
is
considered
to
be unsigned.
Unlike structure and union members, enumerators share their name space
with
ordinary variables and, therefore, must
not
conflict
with
variables
or
other en-
umerators in the same scope.
Enumerators may appear wherever integer constants are required
and, there-
fore, can participate in arithmetic expressions, case expressions, and so forth.
In addition, explicit integer expressions may be assigned
to
variables
of
type
enum. The compiler does no range checking
to
insure the value
will
fit
in the
enumeration field. The compiler does, however, issue a warning message
if
an
enumerator
of
one type
is
assigned
to
a variable
of
another.
Example:
enum
color
(red,blue,green=10,orange,purple=-2,cyan}
x;
This statement declares x
as
a variable
of
type enum The enumerators
(with
their values in parentheses)
are:
red
(0),
blue
(1),
green
(10),
orange
(11),
purple
(-2),
cyan
(-1).
The variable x is allocated
32
bits because
of
the ne-
gative values.
All
the
following
are legal operations:
x =
blue;
x =
blue
+
red;
x
100;
ired;
/*assume
i
has
been
declared
an
int*/
x = i +
cyan;
4-7
Page 35
The
TMS34010 C Language
'
4.8
Initialization
of
Static
and
Global
Variables
K&RB.6
An important difference between K&R C and TMS3401 0 C
is
that external and
static variables
are
not pre-initialized
to
zero unless the program explicitly does
so
or
it
is specified
as
an
option in the linker, GSPLNK.
If
a program requires that external and static variables be pre-initialized, the
linker
can
be
used to do this. In the linker control file,
use
a fill value
of
0 in
the
.bss section:
SECTIONS
.bssO
= bxOO;
}
4.9
8sm
Statement
Addi-
tional
4·8
TMS34010 C has
another "statement"
not
mentioned in K&R: the asm state-
ment. This statement allows assembly
language text
to
be imbedded in the
output
assembler source file. The form
of
the asm statement
is:
asm("<assembler
text)");
The assembler text is enclosed in double quotes. All the usual character string
escape codes have their normal meaning.
The assembler text
is
copied directly
to the assembler source file. Note that for GSPA,'
an
assembler text statement
without
a label must begin
with
a blank. '
The
asm statement injects one line
of
assembly language into the
output
of
the codegen. A series
of
asm commands places the instructions sequentially
into the codegen output
with
no intervening code.
Asm
statements do
not
follow
the syntactic restrictions
of
normal statements
and
can
appear anywhere in the C source, even outside blocks. However, they
are
ignored when they appear in a list
of
declarations.
Page 36
The
TMS34010
C
Language
Warning:
Extreme
care
must
be
taken
not
to
disrupt
the C environment
with
asm
commands.
No
checking
of
the
inserted
instructions
is
done.
Insertion
of
jumps
and
labels
into
C
code
may
cause
unpredictable
results
in
variables
manipulated
in
or
around
the
inserted
code.
This
command
is
provided
so
you
can
access
features
of
the
hardware,
which
by
definition
C
is
unable
to
access.
Specifically,
this
command
should
not
be
used
to
change
the
value
of
a C
variable;
however,
it
can
be
used
safely
to
read
the
current
value
of a variable.
In
addition,
the
asm
construct
should
not
be
used
to
insert
as-
sembler
directives
which
would
change
the
assembly
environ-
ment.
The asm command
is
very useful in the context
of
register variables. A register
variable
is
a variable in a C program
that
is declared by the user to reside in a
machine register. The
TMS3401 0 C compiler allows up to
four
machine reg-
isters
to
be allocated
to
register variables. These four registers, combined
with
the asm command, provide a means
of
manipulating data independently
of
the
C environment.
4.10
Lexical
Scope
Rules
The lexical scope rules stated in K&R apply
to
TMS3401 0 C also, except that
structures and unions each have
distinct
name spaces for their members. In
addition, the name space
of
both
enumeration variables and enumeration
constants
is
the same
as
for
ordinary variables.
4-9
Page 37
The
TMS34010
C Language
4-10
Page 38
5.
TMS34010
C
Run-Time
Environment
5-1
Page 39
TMS34010
C Run-Time
Environment
5.1
Memory
Model
TMS34010
C looks at memory
as
a single linear
block
partitioned
into
sub-
blocks containing various components
of
data and program code.
Each
vari-
able that
is
external
or
static
is
allocated a block
of
memory,
as
is
each
function,
Each
block
is
contiguous
and
is
limited in size
only
by
the size
of
memory available in the system. Dynamic memory allocation (mal/oc and
free) can
be
implemented by declaring a large global
or
static array and allo-
cating memory from it.
Note:
Placement
of
both
code and data
is
done
with
the linker.
Each
item
of
code
or
data can be' individually placed in memory,
but
generally this
is
not
necessary. Memory-mapped
I/O
can
be
an
exception,
but
access
to
such physical locations can usually be accomplished
with
C pointer types.
5.1.1
TMS34010
C Stacks
5-2
In
TMS34010
C,
there
are
two
stacks: the program stack (STK) and the sys-
tem stack (SP). The program stack passes parameters
to
functions
andallo-
cates local frames
for
functions. The system stack saves the status
of
the
calling .function; in other words,
it
saves registers. The
two
stacks
are
allocated .
by the
boot
module
as
a single static array called
sys-stack.
The program
stack pointer
STK
is
set
to
the
bottom
of
this array (the
low
address) and
grows·
up
to
higher addresses,
while
the system stack
is
set
to
the
top
of
the
array (the high address) and
grows
down
to
lower addresses. Thus, the
two
stacks
grow
toward each other,
as
illustrated in Figure
5-1.
This. arrangement
must
not
be altered by customizing the
boot
module.
Three registers
are
reserved
for
stack management:
SP
Points
to
the
top
of
the system stack
A14
(STK)
Points
to
the
top
of
the program stack
A13
(FP)
Points
to
the beginning
of
the current frame (frame pointer)
Manipulation
of
these registers
is
done
automatically
for
C functions by the C
environment; however, assembly language routines linked
with
C functions
must manipulate these registers according
to
the GSPC conventions.
Page 40
TMS34010
C
Run-Time
Environment
5.1.2
Global
Variable
Memory
Allocation
Each
external
or
static variable declared in a C program
is
allocated
an
exclusive contiguous space in memory by the compiler. Whereas the actual address
of
the space
is
decided by the linker, the codegen provides
that
the space is
always
allocated in multiples
of
words, and each variable is always aligned on
a
word
boundary.
5.1.3
Structure
Packing
and
Field
Manipulation
Structure elements are generally allocated space
as
needed
to
hold them.
Fields are allocated
as
many bits
as
requested, enumerated types
are
allocated
as
few
bits
as
possible
to
hold the maximum value
of
that
type, bytes are al-
located eight bits, and so on.
See
also
TMS34010
C .Data Sizes, page
4-3,
and Enumeration Declarations, page
4-6.
In the TMS3401 0, structure mapping is
done
according
~.o
standard C practice
with
one exception: a field
of
declared
width
zero does
not
cause a
word
alignment. Because
of
the GSP's bit-addressability,
word
alignment in a
structure does
not
necessarily produce more efficient code. However,
note
that
fields
which
straddle
word
boundaries
do
take longer
to
access since
both
words must be fetched
by
the processor; thus,
it
is
advisable
to
define struc-
tures and arrays
of
structures carefully
to
avoid fields
which
cross
word
boundaries.
If
a structure
is
declared
as
an
external
or
static variable, it
is
always placed
on a
word
boundary and
is
allocated space rounded up
to a word
boundary.
However,
when
an
array
of
structures
is
declared, no rounding
of
size
is
used:
exactly enough space
is
allocated
to
hold each structure element in
contig-
uous bits
of
memory.
5.1.4
Array
Alignment
In ANSI standard
C,
as
well
as
K&R C (Kernighan and Ritchie), arrays are
expected
to
always align their elements on a
word
boundary,
with
the excep-
tion
of
bytes,
which
may be aligned on a byte boundary. Because the
TMS34010
is
bit-addressable, this restriction becomes
both
unimportant and
inefficient. Thus, in
TMS34010
C,
arrays have no internal alignment. Each el-
ement
of
the array is allocated exactly
as
much space
as
needed
to
hold the
contents
with
no space between adjacent elements.
Note:
Like structures, a carefully defined array
(with
no
elements overlapping
word
boundaries)
will
allow
the program
to
run faster. In general, pixel
arrays are so aligned.
If
an
array
is
declared
as
an
external
or
static variable, the first element
of
the
array
is
placed
on a word
boundary and the array
is
allocated space rounded
up
to a word
boundarY:
This method
of
handling
an
array allows more control over the environment
than standard
C allows. Arrays
of
bits
or
pixels
are
now
directly accessible (a.
5-3
Page 41
TMS34010
C
Run-Time
Environment
necessity
for
a graphics
environment),
and
memory-mapped
I/O
is
much
more
straightforward.
5.2
Register
Conventions
Strict
conventions
are used
to
determine
which
registers are used
for
what
operations in the C environment. A
good
understanding
of
these
conventions
is
necessary
to
interface assembly language
to
a C program.
5.2.1
Dedicated
Registers
Three registers are used exclusively
by
the C environment
and
cannot
be
mo-
dified
by
a user in any
way
other
than
those
prescribed in Section 5.5,
Func-
tion
Call Conventions, page
5-7.
These registers
are:
SP
A14
(STK)
A13
(FP)
Pointer
to
the
top
of
the
system stack
Pointer
to
the
program
(user)
stack
Pointer
to
the
base
of
the
currently active frame
5.2.2
Using
Registers
5-4
Registers
AO
through A 12
are generally available
for
use by a
function.
However,
two
conventions
apply:
1)
A
function
must
save
the
contents
of
each register used on entrance
to
the
function
and restore
those
contents
on exiting
the
function.
A8
is
the
only
exception; its
contents
do
not
have
to
be saved and restored.
2)
If
an integer value or a
pointer
is
to
be returned
from a function;
it
must
be placed in A8.
The codegen uses the registers in the
following
fashion:
Address generation
Expression analysis
Holding
constants
Return
value/Scratch
User register variabJes
Note:
AO,A2,A4,A6
A1,A3,A5,A7
A1,
A3,
A5,
A7,
A9
through
A12
A8
A9,
A10,
A11,
A12
Registers
BO
through
B14
are available for use
by
the
assembly-language
programmer and are
not
used
by
the
C compiler.
Address generation registers are allocated on a least-recently-used
(LRU)
basis,
with
the
low
registers allocated first. Expression analysis registers are
allocated from high
to
low
registers, based on availability and current use.
(Note
that
all integer expression analysis uses
32-bit
math.)
To
hold
con-
stants,
both
the
user registers and
the
expression analysis registers can be
used and are allocated
from
high
to
low
registers.
Page 42
TMS34010 C Run-Time
Environment
Note:
The codegen constantly keeps track
of
the contents
of
the registers and
will
attempt
to
reuse register data
if
it
is
at all possible. Therefore, it
is
inadvisable to
modify
with
an
in-line
assembly construct
(or
with a mod-
ification
of
codegen
output)
any register already used in a function. Use
the
-r
option
of
the codegen
to
produce the compiler's information about
use
of
registers and to place
it
in the
output
file.
5.2.3
Register
Variables
The codegen provides
up
to
four
active register variables at a time
for
each
function. These
are
requested via the register storage class. (Refer to Storage
Class Specifiers
in
Declarations, page
4-5,
and K&R for more information.)
The codegen
allocates these variables from registers
A9
through
A12 in as-
cending order; thus, the first variable declared
register
is
placed
in
A9, the
second in
A10, and so on. A register variable can contain any integer type, a
pointer
to
any type,
or
a float (doubles or structures
are
not
allowed).
If
more
than four register variables are declared, the excess
are
treated
as
normal vari-
ables.
Register variables declared
as
short
or
char
are
treated
as
long.
Note:
Using register variables
vastly
increases the efficiency
of
code generated
for
some statements, sometimes by a factor
of
two
or
more. Because the
codegen makes
no
attempt
to
keep track
of
operations involving register
variables, you
are
free
to
manipulate them
by
using
in-line
assembly lan-
guage.
5.3
Integer
Expression Analysis
All integer expression analysis is performed in A file registers using the GSP
32-bit
math instructions. Moreover, all multiplicative operations
are
performed
into
odd registers. For this reason,
only
A1, A3, A5, and A7
are
used
for
gen-
eral-purpose expression registers.
TMS34010 C follows
exactly the standard precedence rules
of
K&R
C.
Order
of
analysis, however,
for
any operator's operands is based on the relative
complexity
of
the operands: the more complex operand
is
always analyzed
first.
In this way,
thecodegen
minimizes the number
of
operations
which
must
be performed
to
fully
analyze
an
expression. (This does
not
apply to operators
which
specify order
of
analysis
of
operands, such
as
the comma,
&&,
and
II
operators.)
If
the codegen runs
out
of
registers for use, one
of
these used registers
is
se-
lected
for
reuse and its contents
are
saved on the system stack
to
be restored
later. This frees a register temporarily.
5-5
Page 43
TMS34010 C Run-Time
Environment
5.4
Floating
Point
Conventions
5-6
A floating
point
value is represented in 32 bits for single precision and in
64
bits
for
double precision. All operations
are
done
in double precision,
so
single
precision
(32-bit)
values and integers are converted before any operations are
perform~d.
The
following
functionality is provided:
• Addition, subtraction,
mul~iplication,
division, negation, increment, dec-
rement
• Cl;>mparisons
•
Conversions
Unsigned integer
to
double, double
to
unsigned integer
Unsigned integer
to
float, float
to
unsigned integer
Signed integer
to
double, double
to
signed integer
Signed integer
to
float, float
to
signed integer
Float
to
double, double
to
float
•
Error handling
The TMS3401 0 floating
point
package
is
a custom-coded package that does
not
follow
usual C calling conventions. The calling conventions
for
routines
work
like a classic operand stack. First, the codegen pushes the floating
point
argument(s)
onto
the argument stack, then generates a call
to
a floating
point
function. The floating
point
function pops the arguments
off
the stack, per-
forms the operation
and pushes the result back
onto
the stack. The compiler
has
no
knowledge
of
the interned format
of
the floating
point
numbers, and the
only restriction
is
on the size
of
the number. This allows you
to
customize a
floating
point
package
for
your environment.
Some
floating
point
functions
exp~ct
integer arguments or return integer val-
ues.
For floating
point
functions, all integers are passed and returned in reg-
ister A8.
The
following
functional definitions apply
to
the floating
point
package and
are
used
by
the compiler. More detailed information about each one
of
the
functions can be found in Appendix
O.
-FP-AOD.
-FP-MINUS.
-FP_DIV
•.
_FP_MUlT
Each
takes
two
doubles and returns a double result.
-FP-NEGATE
Returns the negated value
of
the operand passed.
-FP-COMPARE
Takes
two
floats and a comparison operator (in A8) and
Note:
returns
an
integer result
of
0 or 1 based on the compar-
ison;
also sets the status ..
The compiler assumes that the status register is also appropriately set
upon return from the
-FP-COMPARE
function.
-FP-DECR
Takes one double and returns
two:
the
top
of
the stack
is
the
original argument decremented
by
one; the second
item on the stack
is
the original argument (unchanged).
Page 44
TMS34010 C Run-Time
Environment
-FP-INCR
-FP_ITOD
-FP-UTOD
-FP-DTOI
-FP-DTOU
-
FP-ITOF
-FP-UTOF
-FP-FTOI
-FP-FTOU
-FP-FTOD
-FP-DTOF
fp-error
Takes one double and returns
two:
the
top
of
the stack
is
the original argument incremented by one; the second
item on the stack
is
the original argument (unchanged).
Converts the signed integer argument (in
AS) to a
dou-
ble return value.
Converts the unsigned integer argument (in
AS)
to
a
double
return value.
Converts the double argument
to
a signed integer return
value (in
AS). .
Converts the double argument
to
an
unsigned integer
return value (in
AS).
Converts the signed integer argument (in AS)
to
a float
return value.
Converts the unsigned integer argument (in
AS)
to
a
float return value.
Converts the float argument
to
a signed integer return
value (in
AS).
Converts the float argument
to
an
unsigned integer re-
turn value (in
AS).
Converts the float argument
to
a double return value.
Converts the double argument
to
a float return value.
Called when
an
exception occurs in one
of
the
float-
ing-point
math routines. Takes one argument, the error
number. These numbers
are
defined by the floating
point
package,
as
is
the action
of
the function (see Appendix
D). This function
is
not
generally called from user code
but
by the floating
point
package. This function
follows
standard calling conventions, so it can be defined entirely in
C.
5.5
Function
Call
Conventions
All function calls performed in the
C.
environment
follow
a strict set
of
rules
used by the compiler
to
avoid corruption
of
the
run-time
environment. The
rules depend on
whether
arguments
are
to
be passed
to
a function, whether
the function returns a
value, and the type
of
the return value
(if
any).
Figure 5-1 illustrates a
function
call.
5-7
Page 45
TMS34010 C Run-Time
Environment
BEFORE
CALL
AFTER
PASSING
ARGUMENTS
UPON
ENTRY
AFTER.
SAVING
AFTER
ALLOCATING
.
USED
REGISTERS
LOCAL
FRAME
A13-+t------i
A13 A13
A13
A13
AR~N
•
•
AR~N
•
•
AR~N
•
•
A14-+1------i
AR~N
•
•
A14
ARG
1
A14'
ARG
1
A14'
ARB
1
A13'
ARB
1
LOCAL
FRAME
A14"
,
,-
V
/
SP'
SP'
OLD OLD
REGISTERS
.
REGISTERS
SP'
(A13)
(A13)
OLD
PC
OLD
PC
OLD
PC
SP
OLDA14
OLD
A14
OLD
A14
OLD
A14
SP-+l------i
Figure
5-1.
Typical
Function
Call
with
Parameters
Passed,
No
Value
Returned
5.5.1
Register
Usage
Within
Functions
Each
function must save the contents
of
each register used
on
entrance
to
the
function and restore those contents on exiting the function.
AB
is
the only
exception; its contents
do
not
have
to
be saved and restored.
If
an
integer value
or
a pointer
is
to
be returned from a
function,
it must
be
placed in
AB.
Registers
BO
through B14
are
available for use by the assembly-language
programmer and
are
not
used by the C compiler.
5.5.2 Passing
Parameters
5-8
Any
parameters passed
to
a C function
follow
the strict rules used by the
compiler. These
rules are in the
following
list.
Note:
If
these rules
are
not
followed,
the
Crun-time
environment
will
be cor-
rupted and
will
crash at some later time.
1 )
If
the function
is
defined
not
to
have any parameters, none may
be
passed.
2)
If
the function
is
defined
to
have one
or
more parameters,
at
least
one
parameter must be passed
to
the function.,
Page 46
TMS34010 C Run-Time
Environment
3)
If
space must be allocated on the stack
for
a return value, it must be al-
located
before any other function call setup action.
If
the function returns a double, a float, or a structure type, space must
be
allocated on the stack for the return value, regardless
of
whether the
caller
will
use the data.
4)
Parameters
to
the function
are
passed in reverse order; that is, the last
parameter
is
pushed first and the first
is
pushed last. This feature allows
variable-length
argument lists
to
be handled easily.
5)
All
integer types
are
widened
to
32-bit
integers. (See Conversions, page
4-4.)
6)
All floating
point
values are converted
to
doubles.
7)
Structures are
"widened"
to
the next larger
word
boundary.
Note:
Passing structures
to
functions can be dangerous. The called
function
must
know
the correct size
of
the structure in order
to
handle the call
properly.
If
the sizes
do
not
match, unpredictable results occur. There
is
no compile-time check for this in
C.
8)
The called routine does all cleanup
of
the stack, so the caller does
not
need
to
do
anything after the actual call
to
the function.
5.5.3
Local
Frame
Generation
The first steps taken by the called function
are:
1)
Saves any registers
which
are
modified
by
the function
(including
the
frame pointer
if
the function has local variables). This
is
accomplished
via the
MMTM
instruction, pushing the original values
of
the used reg-
isters
onto
the system stack.
2)
If
there are local variables, sets the frame pointer
(A13)
to
point
to
the
top
of
the program stack
(A14)
and then allocates the local frame by
incrementing the program stack.
5-9
Page 47
TMS34010
C
Run-Time
Environment
Notes:
1. The status register
is
not
saved.
2
..
There
is
not
an
explicit argument
pointer
in this scheme. The frame
pointer
(A13)
is
located at the end
of
the argument list and at the
beginning
of
the local frame, so
both
arguments and local variables
can be indexed from the frame pointer.
3.
Register
AS
is
used
as
the return value register; and
thus
is never saved
in a normal function. Therefore, this register can be modified
without
having
to
save it on the system stack.
5.5.4
Function
Termination
5-10
At
the termination
of
a function, the function:
1)
Handles any return values
to
be passed
to
the caller.
2)
Restores the caller's registers.
3) Restores the local frame
of
the caller.
There
are
three
Cases
of
return value types and each has a method
of
handling:
Pointers
or
integer
return
values:
Returned in register
AB.
Because
of
this use
of
register A8,
it
is
never saved at function entry. Thus,
A8
may be
used
as
a scratch register between function calls. Note
that
since integer
values
are
not
returned on the stack,
it
is
not
necessary
for
the caller
to
al-
locate
space for them prior
to
passing parameters.
Floating
point
return
values:
Returned on the stack. Either a single
or
a
double
precision value can be returned. Upon return, the value appears
to
have been "pushed" on the stack. The space
for
the return value must be
allocated by the caller before the call,
followed
by a save
of
the program
stack pointer to the system stack.
Structure
return
values:
Returned on the program stack,
as
floating
point
values
are.
It
is
assumed that the space
is
allocated, and
that
the program .
stack pointer (STK)
is
saved on the system stack.
Note:
The size
of
a structure returned
is
rounded
up
to
the next
word
boundary.
This makes handling easier. Upon return, the structure appears
to
have
been
"pushed"
on the stack.
Page 48
TMS34010 C Run-Time
Environment
5.5.5
Restoration
of
the
Caller's
Environment
It
is the responsibility
of
the called
function
to
restore the environment
of
the
caller before returning. In general, this involves restoration
of
the caller's reg-
isters and
deletion
of
the local frame
(including
arguments).
The first task
is
to
restore the caller's registers. This can be done
with
an
MMFM
instruction, corresponding
to
the
MMTM
given at function entry.
Note
that
the status register need
not
be saved
or
restored.
If
local variables
were allocated, the frame pointer must also be restored and shouid
be
included
in the register list
for
the register save instructions.
There
are
two
methods for deletion
of
local variables and arguments:
• Function returns value
on
stack,
or
has arguments. In the latter the old
program stack pointer
is
pushed on the stack
(below
the old value). To
restore the
caller's stack,
copy
this value from the system stack (SP)
to
the program stack pointer,
A14
(STK).
•
No
arguments, no return value on stack.
If
a local frame was allocated,
decrement
A14
by
the size
of
the local frame and return.
If
no frame was
allocated,
just
return.
Note
that
the
old
program stack pointer
is
not
saved for either
(1
) the case
of
values returned on the stack
or
(2)
the case
of
no arguments.
5.5.6
Return
from
Function
The last instruction executed
by
the function
is a RETS.
Normally, the'
in-
struction has
an
argument
of
zero,
but
if
the function had arguments
or
re-
turned a
value on the stack, the instruction
RETS
2 must be executed
to
pop
the caller's
old
program stack pointer
off
the stack,
5.6
Interrupt
Handling
Interrupts can be handled directly
with
C functions through the use
of
re-
served function names. These names
are
of
the form: .
c-
int##
where
two
pound
signs
(##)
indicate a
two-digit
interrupt number. For ex-
ample:
c-intOO
(system
reset
interrupt)
c-intOl
.,.
c-int99
By naming a
function
in this way, the user specifies
that
the function is to be
used
to
handle
an
interrupt, and the codegen generates special code
for
an
interrupt routine.
Any
register used
(with
the exception
of
SP and STK)
is
saved by the interrupt
handler,
including
AB.
In a normal
function,
A8
need
not
be saved; however,
in the case
of
an
interrupt,
A8
must
be
saved.
To return from the interrupt, use the
RETI
instruction. This restores the status
of
the interrupted function, .
5-11
Page 49
TMS34010 C Run-Time
Environment
An interrupt function may perform any task a normal function may perform:
access global variables,
allocate local variables,
call
other functions, etc.
Notes:
1.
It
is your responsibility
to
handle any special masking
of
interrupts.
You
can
reenable the interrupts and
do
any masking required
without
corrupting the C environment.
2.
An interrupt handler must
be
declared
with
no arguments.
If
it
is
de-
clared to have arguments, the interrupt handler
will
not
run correctly.
3.
An interrupt handler may
not
be called by the user code. Because the
linkage
is
set up for handling interrupts, a C calling sequence
will
not
be
handled correctly, and the system could crash.
4.
c-intOO
is
used
as
the system reset interrupt. This routine initializes the
system and calls the user's
main function. Note that when the user's
function
is
called, the interrupts
are
still disabled; thus,
it
is
the user's
responsibility
to
enable interrupts
if
they are.needed.
5.
Any
interrupt handler can
be
used to handle any interrupt or multiple
interrupts. The codegen does
not
generate any code specific
to
the
particular interrupt,
with
the exception
of
the system reset interrupt
c-intOO,
which
must
be
used
as
system reset and cannot have any
local variables (since
it
is
assumed that at system reset the stack
has
not
yet been allocated).
To attach
an
interrupt handler to
an
interrupt, the address
of
the in-
terrupt must be placed in the proper interrupt vector. This
can
be done
with
the assembler and linker, creating a simple table
of
addresses and
linking
to
the proper location.
5.7
System
Initialization
5-12
Before any C code may
be
run, the C run-time environment must be created.
This environment is represented in the program stack and the system stack,
so these must be properly constructed and initialized.
In
addition, any vari-
ables
which
were declared to be automatically initialized at program entry
must
be
initialized before calling user code.
Two
stacks
are
used
to
manage the C run-time environment:
Program stack
(STK)
System
stack (SP)
These stacks must
be
initialized by the
boot
function before any user code is
executed. The stacks
are
located in the static array
SYS-STACK,
declared in
the module
BOOT.C, and share the space by
growing
toward each other from
opposite ends
of
the space .. A stack overflow occurs when the stacks overlap.
The size
of
SYS-STACK
may be changed by modifying source code and re-
compiling
BOOT.C. There
is
no protection in the run-time code against stack
overflows, so stack size should be chosen
with
care.
Page 50
TMS34010 C Run-Time
Environment
5.7.1
System
Stack
The system stack
is
pointed
to
by
the
SP
register and
grows
toward
low
me-
mory. This stack
is
used by
function
calls
to
save the context
of
the calling
function, including any registers used by the called function. This stack
is
supported directly
by
the TMS3401 0 instruction set, and register
SP
is dedi-
cated
to
stack management. The system stack
is
manipulated
by
C primarily
through
the use
of
four commands:
•
MMTM
Save Registers
•
MMFM
Restore Registers
•
CALLA
(or
CALL) Call a Function
•
RETS
(or RETI) Return from a Function (or Interrupt)
It
is
also used
by
interrupts
to
save the status
of
the interrupted function.
5.7.2
Program
Stack
The program stack
is
used
for
frame generation; i.e.,
to
pass arguments
to
functions and allocate local (temporary) variables for the called functions. The
program stack
is
controlled entirely in software, using
A14
to
point
to
the
current
"top
of
stack", and
grows
toward
high memory. Thus,
A14
is a
dedi-
cated register
in
the C environment, and
it
must be carefully manipulated
to
avoid system crashes.
5.7.3
Initialization
of
Global
Variables
Before execution
of
your
program, any global variables declared
to
be pre-
initialized
must
be initialized
by
the
boot
program. This is
done
through
the
use
of
initialization tables placed in the .data section
of
the
program object
module.
Any
module generated
by
the compiler may produce these tables,
and the linker appends them
into
one table.
Note:
Because the .data section
is
used
by
the codegen
to
contain initialization
tables only,
you
are
not
allowed to place any other data in this section.
Doing so causes corruption in the
initialization table format, causing
un-
predictable results.
Global
and static variables that are
not
autoinitialized are
not
guaranteed
to
be initialized
to
O.
5-13
Page 51
TMS34010 C Run-Time
Environment
5-14
Page 52
6.
TMS34010
Run-Time
Support
6-1
Page 53
TMS340~O
Run-Time
Support
6.1
Memory
Management
Five routines
are
provided
to
implement C dynamic memory management.
These routines
are:
malloe
Allocates
an
area
of
a specified size in memory.
ealloe
Allocates and clears
an
area
of
memory.
realloe
Re-allocates a previously allocated memory
area
with a new
size.
free
De-allocates space allocated by cal/oc, mal/oc,
or
real/oc.
movmem
Moves a specified number
of
bytes from one address
to
another.
6.1.1
Specifying
the
Size
of
Memory
to
Manage
The amount
of
memory managed by the memory management routines
is
specified by the macro
memory-size
in
the
RTS
(run-time
support) module
memory.c,
which
contains the source code
for
all
the
memory management
routines. By modifying this value and recompiling the module, the amount
of
memory used can be changed.
6.2
String
Functions
6-2
Several functions
are
provided to
allow
manipulation
of
strings, search for
characters, and comparison
of
strings. These functions
are:
streat
*
strneat
*
strehr
strrehr
stremp
strnemp
strepv
*
strnepv
*
strlen
Appends a string
onto
the end
of
another string.
Appends a string
of
up
to
n characters
onto
another string.
Searches
for
the first occurrence
of
a character in a string.
Searches
for
the last occurrence
of
a character in a string.
Compares
two
strings.
Compares
up
to
n characters in
two
strings.
Copies a string
to a new
location.
Copies up
to
n characters
of
a string
to a new
location.
Returns the length
of
a string.
• When using functions that move or copy strings, ensure
that
the destination
is
large enough
to
contain the result.
Page 54
TMS3401 0 Run-Time
Support
6.3
Character
Typing
and Conversion
Macros
These macros determine the types
of
characters contained in variables, arrays,
constants, etc. The
library file ctype.h must be included in
your
file
to
use the
functions. The character typing macros
are:
isalnum
isalpha
isascii
iscntrl
isdigit
islower
isprint
ispunct
isspace
isupper
isxdigit
Detects alphanumeric ASCII characters.
Detects alphabetic
ASCII characters.
Detects
ASCII characters.
Detects control characters.
Detects numeric characters.
Detects lowercase alphabetic
ASCII characters.
Detects printable
ASCII characters.
Detects
ASCII punctuation characters.
Detects
ASCII spacebar, tab (horizontal
or
vertical), carriage
return, form feed, and newline characters.
Detects uppercase
ASCII alphabetic characters.
Detects hexadecimal
digit
characters.
Conversion
of
uppercase characters to lowercase, and vice versa, and conver-
sion
of
non-ASCII
characters to ASCII can be done
with
the
following
mac-
ros.
Include the library file ctype.h
to
use them.
tolower
toupper
toascii
Converts uppercase alphabetic characters
to
lowercase.
Converts lowercase alphabetic characters
to
uppercase.
Converts
non-ASCII
characters
to
ASCII characters.
6.4
Miscellaneous
Functions
setjmp
longjmp
Saves calling function's context in environment buffer.
Restores context
of
calling function from environment buffer.
6-3
Page 55
atof
Convert
ASCII
to
Floating
Point
atof
Syntax
double
atof(nptr)
char *nptr;
Description
This function converts a string
of
ASCII characters
to
floating-point
values.
.
6-4
The string
is
given in the format:
[space]
[sign]digits[.digits]
[eIE[sign] integer]
The
space
shown
in the format
is
white
space and
is
indicated by a space-
bar, horizontal
or
vertical tab, carriage return, form feed,
or
newline. Fol-
lowing
the space indicator is
an
optional sign, and then digits representing
the integer part
of
the number. The fractional part
of
the number follows,
then the
exponent,
including
the
option
of
a sign.
The first unrecognized character terminates the string.
The
ata! function does
not
account for any overflow resulting from the
conversion .
Page 56
atoi
Syntax
Description
Convert
ASCII
to
Integer
double
atoi(nptr)
char *nptr;
atoi
This
function
converts a string
of
ASCII characters
to
integer values. The
string
is
given in the format:
[space]
[sign]digits
The space
shown
in the format is
white
space and is indicated by a space-
bar, horizontal or vertical tab, carriage return, form feed,
or
newline. Fol-
lowing
the space indicator is
an
optional
sign, and then
digits
representing
the number.
The first unrecognized character terminates
the
string.
The
aloi
function
does
not
account
for
any
overflow
resulting from the
conversion.
6-5
Page 57
calloc
Syntax
D~scription
Example
6·6
Allocate and Clear Mtitmory
#include <memory.h>
char
·calloc(num,size)
int
num;
/*
number
of
items
to
clear * /
int
size;
/*
size
of
each item * /
calloc
This routine allocates a packet
of
memory large enough
to
contain num
objects
of
the specified size and refUrns a pointer to
it
If
it
cannot allocate
the packet (i.e.;
if
it
runs
out
of
memory).
it
returns a null pointer
(0).
This
fuhctionalso
initializes the allocated memory to all zeros. Refer to Section
e.1.1,
Specifying the Size
of
Memory
to
Managlil, for more information on
allocating memory.
ptr
=
calloc(10,2)
;
/*
allocate/clear
10
words
*/
Page 58
free
Free
Memory
from
Allocation
Syntax
#include <memory.h>
int
free(pointer)
char
·pointer;
free
Description
This routine deallocates a packet
of
memory (pointed to
by
pointer) previ-
ously allocated by mal/oc, cal/oc, or real/oc.
If
you attempt
to
free a packet
not
previously allocated, the function takes no action and returns. Refer
to
Section 6.1.1, Specifying the Size
of
Memory
to
Manage,
for
more infor-
mation on allocating memory.
Example
char
*x;
x =
malloc(lO);
free(x);
/*
allocate
10
bytes
*/
/*
free
10
bytes
*/
6-7
Page 59
· isxxxxx
Character
Typing
Macros
isxxxxx
Syntax
#include
<ctype.h>
int
isxxxxx( character)
char character;
Description
These macros identify a particular type
of
character, such
as
alphabetic,
6-8
alphanumeric, numeric, ASCII, etc.
If
the argument character
is
one
of
the
characters designated by the macro
name, the macro returns a nonzero
in-
teger. Otherwise, it returns
O.
The character
typing
macros
are:
isalnum
isalpha
isascii
iscntrl
isdigit
islower
isprint
ispunct
isspace
isupper
isxdigit
Detects alphanumeric ASCII characters.
Detects
alphabetic ASCII characters.
Detects
ASCII characters.
Detects
control characters.
Detects numeric characters.
Detects
lowercase alphabetic ASCII characters.
Detects
printable ASCII characters.
Detects
ASCII punctuation characters.
Detects
ASCII spacebar, tab (horizontal
or
vertical), car-
riage
return, formfeed, and
newline
characters.
Detects uppercase
ASCII alphabetic characters.
Detects
hexadecimal
digit
characters.
Page 60
longjmp
Restore
Environment
longjmp
Syntax
#include <setjmp.h>
longjmp(env,val)
jmp-buf
env; /* environment save
buffer'
/
int
val; /* value
to
be returned by corresponding "setjmp" • /
Description
This function restores the context
of
a calling
function's
environment.
It
is
used in
conjunction
with
setjmp. These
two
functions provide transfer
of
control from a nested series
of
functions back
to
a specified
point
with-
out
using a series
of
return statements.
6-9
Page 61
Itoa
Convert
Long
to
ASCII
Itoa
Syntax
int
Itoa(n,buffer)
long n;
/*
number
to
convert * /
char *buffer;
/*
buffer
to
put
result in * /
Description This function converts a long integer
to
the equivalent ASCII string.
If
the
input
number
is
negative, a leading minus sign
is
output. The
It08
function
returns the number
of
characters placed in the buffer.
6-10
Page 62
malloc
Allocate
Memory
Syntax
#include <memory.h>
char
*malloc(size)
int
size;
/*
size
of
block in bytes
*/
malloc
Description
This routine allocates a packet
of
memory
of
a specified size and returns a
pointer
to
it.
If
mal/oc
is
unable
to
allocate the packet (i.e.,
if it
runs
out
of
memory), it returns a
null
pointer
(0).
This function does
not
modify the
memory
it
allocates. Refer
to
Section
6.1
.1
, Specifying the Size
of
Memory
to Manage, for more information on
allocating memory.
6-11
Page 63
movmem
Move
Memory
movmem
Syntax
#include
<memory.h>
char *movmem(src,dest,count);
char
'src
; /* source address
0/
char °dest; /* destination address * /
char count; /* number
of
bytes
to
move
0/
Description This routine moves count bytes
of
memory from source address
to
dest
6-12
address. The source and destination areas can be overlapping. Refer
to
Section 6.1.1, Specifying the Size
of
Memory
to
Manage,
for
more infor-
mation on allocating memory.
Page 64
realloc
Re-allocate
Memory
realloc
Syntax
#include
<memory.h>
char *realloc(ptr,newlength)
char
*ptr ; /*number
of
items
to
clear * /
int
newlength ;
/*
new
size
of
packet·
/
Description
This routine chan,ges the size
of
the allocated data
area
pointed
to
by
the
first argument,
ptr,
to
the size specified by the second argument,
newlength.
It
returns a pointer
to
the space allocated since the packet and
its contents may have
to
be moved in order
to
expand.
Any
memory freed
by this operation is deallocated.
If
an
error occurs, the
function
returns zero.
Refer
to
Section 6.1.1, Specifying the Size
of
Memory
to
Manage,
for
more
information on allocating memory.
6-13
Page 65
,
setjmp
Saves
Environment
setimp
Syntax
#include
<setjmp.h>
int
setjmp( env)
jmp-buf
env;
Description
This function saves the context
of
a calling
function's
environment.
It
is
6-14
used in
conjunction
with
/ongjmp. These
two
functions
provide transfer
of
control from a nested series
of
functions back
to
a specified
point
without
using a series
of
return statements.
The
setjmp function returns zero
when
called,
but
if
/ongjmp
is
executed
it
"returns" a second time, returning the value specified
by
the /ongjmp.
Page 66
strcat
Concatenate
Strings
Syntax
#include
<string.h>
char ·strcat(string1 ,string2)
char
·string1,
'string2;
strcat
Description
The strcat function appends a
copy
of
string2
to
the end
of
string 1 and re-
turns a pointer
to
the first character
of
string 1
6-15
Page 67
strchr
Syntax
Description
6-16
.
FindCharacterinString-FirstOccurrence
#inclu~e
<string.h>
unsigned char *strchr(s,c)
unsigned char *s,c;
strchr
This function finds the firSt occurrence
of
the character c in the string.s
and
returns a pointer
to
it.
If
the character
is
not found, strchr returns a null.
strchr
is
equivalent
to
other C compilers' index.
Page 68
strcmp
Syntax
Description
Compare
Strings
#include
<string.h>
int
strcmp(string1
,string2)
char
'string1
,'string2;
strcmp
This
function
compares
two
strings, character
by
character, and returns an
indicator
of
which
string
is
lower
in the
ASCII
character set.
The
indicators
are:
-1
if
string 1 is less than string2
o
if
string 1
is
equal
to
string2
1
if
string 1
is
greater
than
string2
6-17
Page 69
strcpy
Copy
String
Syntax #include
<string.h>
char *strcpy(to,from)
char. *to, *from;
strcpy
Description This function copies the string at the address from
into
the address to and
returns a pointer to this destination string.
6-18
Page 70
strlen
Length
of
String
Syntax
#include
<string.h>
unsigned
int
strlen(string)
char
'string;
strlen
Description
The function returns the length
of
string. In
C,
a character string
is
termi-
nated by the first byte
with
a value
of
zero. The returned result does
not
include the zero byte.
6-19
Page 71
strncat
Concatenate
n Characters
of
String
strncat
Syntax
#include
<string.h>
char 'strncat(string1 ,string2,max)
char
'string1,
*string2;
unsigned
int
max;
Description
This function appends a
copy
of
string2, or the first max characters
of
6-20
string2 (whichever
is
smaller),
to
the end
of
string
1.
It
also returns a
pointer
to
the destination string.
Page 72
strncmp
Syntax
Description
Compare n Characters
in
String
#include
<string.h>
char 'strncmp(string1 ,string2,n)
char
'string1,
'string2;
unsigned
int
n;
strncmp
This function compares
two
strings, character
by
character, and indicates
which
string
is
lower
in the ASCII character set. Only n characters
are
compared; if either string has less than n characters, the comparison stops
at the end
of
the shorter string. The indicators
are:
-1
if stringl
is
less than string2
o
if
stringl
is
equal
to
string2
1
if
string 1
is
greater than string2
6-21
Page 73
strncgy
Syntax
Description
6-22
Cogy n Characters
to
String
#include <string.h>
char
"strncpy(to,from,n)
char "to, "from;
unsigned
int
n;
strncgy
This function copies the string at address from into the address to. Only
n . characters
are
copied.
If
the
input
string is less than n characters, in
length, the remainder
of
the destination field is padded
with
zeros.
If
the
input
string has n or more characters,
the,
string to will
not
be
termi-
nated
by an. end
of
string character. The
strncpy
function returns the
address
cif
the destination string.
Page 74
strrchr
Find
Character
in
String-Last
Occurrence
Syntax
#include
<string.h>
unsigned char 'strrchr(s,c)
unsigned char
's,c;
strrchr
Description
This function finds the last occurrence
of
the character c in string
sand
returns a pointer
to
it.
If
the character c
is
not
found
in the string, strrchr
returns a null.
stm;hr
is
equivalent
to
other C compilers' rindex.
6-23
Page 75
toascii
Syntax
Description
6-24
Convert
to
ASCII
#include <ctype.h>
char toascii(c)
char
c;
toascii
This macro converts the argument c to its ASCII equivalent by masking the
bottom seven bits.
Page 76
tolower
Convert
to
Lowercase
Syntax
#include
<ctype.h>
char
tolower(c)
char
c;
tolower
Description
This macro converts the uppercase argument c
to
its lowercase form.
If
the
argument
is
already in lowercase, the macro returns the argument
un-
changed. .
6-25
Page 77
toupper
Convert
to
Uppercase
Syntax
#include
<ctype.h>
char
toupper(c)
char
c;
toupper
Description
This macro converts the lowercase argument c
to
its uppercase form.
If
the
argument
is
already in
uppercase,the
macro returns the argument
un-
changed. .
6-26
Page 78
A. Fatal Errors
Compiler error messages appear in a straightforward format
showing
the line
number in
which
the error occurs and the text
of
the message:
"name.c", line
n:
<error message>
Any
of
the errors
shown
in this section cause the compiler to abort imme-
diately. Text enclosed in single or double quotes in these error messages
is
replaced
with
actual text from the program,
your
own
symbols, filenames,
memory allocations, etc.
error: cannot allocate sufficient memory
The compiler requires a minimum
of
512K bytes
of
memory to run; this
message indicates a lack
of
necessary memory. Supply more dynamic
RAM.
error: can't open "filename"
as
source
The compiler
cannot
find the file name
as
entered. Check for spelling
errors; check
for
the existence
of
the file named.
error: can't open
"filename"
as
intermediate file
The compiler cannot create the
output
file. This
is
usually caused by ei-
ther
an
error in the syntax
of
the filename
or
a full disk.
error: illegal extension
"ext"
on
output
file
The intermediate file cannot have a
".c"
extension.
·····fatal
errors found: no intermediate file produced
This message
is
printed after
an
unsuccessful compilation. Correct the
errors (other messages
will
indicate particular errors) and try compilation
again.
cannot recover from earlier errors: goodbyel
An error has occurred
that
prevents the compiler from continuing.
A-1
Page 79
Appendix A
A-2
Page 80
B.
Reference
Documents
The
following
Texas Instruments publications provide additional information
about the
TMS3401 0 and may be ordered from a TI Sales Office
or
authorized
distributor.
'.
•
TMS34010
User's Guide, (SPVU001)
•
TMS34010
Assembly Language Tools User's Guide, (SPVU004)
•
TMS34010
Data Sheet (SPPS011)
• TMS4161 Data Sheet
• TMS4461
Data Sheet
The
following
books or articles provide further background in C programming,
in graphics, and system concepts associated
with
graphics.
• Cody, William J., Jr., and William Waite,
Software
Manual
for the Ele-
mentary Functions,
P~enticeHall,
Englewood Cliffs,
New
Jersey, 1980.
•
Kernighan,
B,
and
D.
Ritchie.
The
C Programming Language, Prentice-
Hall, Englewood Cliffs; !'Jew
Jersey, 1978. '
•
Kochan, Steve
G.
Programmi,!g
in
C,
Hayden Book Company.
• Sobelman, Gerald
E.,
and David
E.
Krekelberg.
Advanced
C: Techniques
and
Applications, Que Corporation, 1985.
• Harbison,
S.,
and
G.
Steele. C: A Reference Manual, Prentice-Hall, En-
glewood
Cliffs, New Jersey, 1984. .
8-1
Page 81
Appendix B
B-2
Page 82
C. C Preprocessor
Directives
The C preprocessor provided
with
this package is standard and
follows
K&R
exactly. This appendix is simply
an
overview
of
the
functionality
of
the direc-
tives.
. c-,
Page 83
#define
Macro
Definition
with
Arguments
#define
Syntax
#define
<name>
(arg,
...
,arg)
<token-string>
Description
Subsequent occurrences
of
name
followed
immediately
by
a list
of
argu-
Example
C-2
ments separated
by
commas and enclosed in parentheses
are
replaced
by
token-string, where each occurrence
of
an
argument
is
replaced
by
the
corresponding set
of
tokens from the comma-separated ,string. When a
macro
with
arguments is expanded, the arguments are placed
into
the ex-
panded token-string unchanged. After the entire token-string has been expanded,
GSPCPP scans again
for
names
to
expand
atthe
beginning'
of
the
newly
created token-string,
which
allows for' nested macros. '
Note that there
is
no space between name and the open parenthesis at the
beginning
of
the argument list.
AI~o;
there
is
no trailing semicolon (;).
#define
f(a,b,c)
3*a+b-c
causes
f(27,begin,minus)
whenever it occurs in the code,
to
be expanded
to
3*27+begin-minus
Page 84
#else
Reverse
Conditional
Compilation
#else
Syntax
#else
Description
The lines
of
code between
this
directive and
#endif
will
appear in
the
out-
put
if
and
only
if
the
test directive corresponding
to
this #else produces an
untrue
result.
C-3
Page 85
#endif
End
of
Conditional
Compilation
#endif
Syntax
#endif
Description Ends a section
of
lines begun
by
a test directive (#if, #ifdef, or #ifndef).
C-4.
Each
test directive must have a matching #endif. Conditional compilation
sequences may be nested.
Page 86
#if
Begin
Conditional
Compilation
#if
Syntax
#if
<constant-expression>
Description
The lines
of
code between
#if
and
#endif
or #e/se
will
appear in the
output
if
and
only
if
the constant-expression evaluates
to
a non-zero value. All
bi-
nary non-assignment C operators, the
7:
operator, the unary -,
],
and!
op-
erators
are
all legal in constant-expression. The precedence
of
the operators
is
the same
as
in the definition
of
the C language. There
is
also a unary
operator
called defined,
which
can be used in constant-expression in these
two
forms:
defined(
<name»,
or
defined
<name>
This allows the the
utility
of
#ifdef
and
#ifndef
in a
#if
directive. Only these
operators, integer constants, and names
which
are
known
by GSPCPP
should be used in constant-expression. In particular, the sizeof operator
is
not
available.
C-5
Page 87
#ifdef
Begin
Conditional
Compilation
#ifdef
Syntax
#ifdef
<name>
Description Inserts the lines
of
code between
#ifdef
and
#endif
or
#e/se
into
the
output
C-6
if
and
only
if
name has been defined
(by
#define) and has
not
been the
subject
of
a subsequent #undef.
•
Page 88
#ifndef
Begin
Conditional
Compilation
#ifndef
Syntax
#ifndef
<name>
Description
The lines
of
code between
#ifndef
and
#endif
or
#else
will
appear in
the
output
if
and
only
if
name has
not
been defined
(by
#define) or has been
the subject
of
a subsequent #undef.
C-7
Page 89
#include
Syntax
File Inclusion
#include "filename"
or
#include <filename>
#include
Description
Includes at this
point
in the code the contents
of
the given filename,
which
C-8
will
then
be
run
~hrough
GSPCPP. Either double quotes or angle brackets
l'!re
used to enclose filename.
The filename can include a pathname
with
directories and so forth.
If
no
directory
is
specified, the
file
is
looked for in:
1 ) Current directory
2) Directories specified using
-I
option (see Section 3.1.3, Operation
of
GSPCPP, page
3-3).
Page 90
#Iine
Line
Number
Specification
#Iine
Syntax
#line
<integer-constant>
["<filename>"]
Description
Causes generation
of
line control information for the next pass
of
the
compiler.
integer-constant
is
the line number
of
the next line, and filename
is
the file where
that
line exists.
If
no filename
is
given, the current filename
(given by the
last #Iine directive)
is
unchanged.
This directive can be used
to
set the - -
LI
N E - - and - -
FI
LE '--
symbols (see Section 3.1.3, Operation
of
GSPCPP).
C-9
Page 91
#undef
Cancellation
of
Definition
#lmdef
Syntax
#undef <name>
Description
Causes the definition
of
name
to
be forgotten.
C-10
Page 92
D. Floating
Point
Facility
The TMS3401 0 C
floating-point
package allows you
to
perform
real
number
arithmetic operations from
C.
The TMS3401 0
floating-point
functions have a
special
C assembly language interlace and, therefore,
do
not
adhere
to
the C
function calling convention. The TMS3401 0 C compiler performs
real
number
arithmetic in double precision. The
following
operations
are
included in the
C floating
point
package:
• Addition, subtraction, multiplication, division, negation, increment. and
decrement
for
double-precision format
• Comparisons
for
double precision format
• Conversions
Signed/unsigned integer
to
double
Double to signed/unsigned integer
Signed/unsigned integer
to
float
Float
to
signed/unsigned integer
Float
to
double
Double
to
float
• Creation
of
a floating
point
number in either single-
or
double-precision
format from
an
ASCII string
• Error detection and exception handling.
These operations/conversions
are
described on the
following
pages.
D-1
Page 93
Appendix
0
D.1
Single-Precision
Floating-Point
Format
0-2
The single-precision
floating-point
format supported by the
TMS34010
C
floating-point
RTS
is a 32-bit
format: a sign bit,
an
8-bit
biased exponent, and
a
23-bit
mantissa. The three component fields
are
positioned in the
32-bit
field format
as
follows:
3130
2322
o
lsi
EXP
I
MANTISSA
MSB
LSB
Figure
0-1.
Single-Precision
Floating
Point
Format
Hence, the sign
is
in
bit
31
of
the
32-bit
field, the exponent resides
in
bits 23
through
30, and the mantissa in bits 0 through 22.
Given a sign
bit
s,
an
exponent
e,
and a mantissa
f,
then the value V
of
the
floating
point
number X=(s,e,f)
is
as
follows:
•
If
s = 0, e = 255, and f = 0, then V =
+infinity
•
If
s = 1, e = 255, and f = 0, then V =
-infinity
•
If
0 < e < 255 and f
'"
0, then V = (_1)s*2
e
-
127
(.f)
( V
=
Not
Valid
if
the number X=(s,e,f)
is
not
a normalized floating
point
number.
See
Floating Point Arithmetic, Rounding, and Normalization,
page D-4.)
•
If
s = 0, e = 0, and f = 0, then V = 0
•
For all other cases, V =
Not
Valid
Precision in the single-precision format
is
greater than six decimal digits and
the range
includes the
following:
• 5.87747 x
10-
39
to
1.70141 x
10
38
(positive range)
(5.87747 E-39
to
1.70141 E38, in C format)
• -1.70141 *
10
38
to
-5.87747 *
10-
39
(negative range)
(-1.70141 E38
to
-5.87747 E-39, in C format)
• 0 (zero)
• + /-infinity
Page 94
Appendix
D
0.2
Double-Precision
Floating-Point
Format
The double precision floating
point
format supported
by
the
TMS34010
C
floating
point
RTS
is a 64-bit
format: a sign bit.
an
11-bit
biased exponent, a
52-bit
mantissa. The three component fields are positioned in the
64-bit
field
format
as
follows:
6362
5251
o
lsi
EXP
I
MANTISSA
MSB LSB
Figure
0-2.
Double-Precision
Floating
Point
Format
Hence, the sign
bit
is
bit
63
of
the
64-bit
field, the exponent resides in bits
52 through
62, and the mantissa is in bits 0 through
51
.
Given
an
sign
bit
s,
an
exponent
e,
and a mantissa f, then the value V
of
the
floating
point
number
X=(s,e,f)
is
as
follows:
•
If
s = 0, e = 2047, and f = 0, then V =
+infinity
•
If
s = 1, e = 2047, and f = 0, then V =
-infinity
•
If
0 < e < 2047 and f ¢ 0, then V = (_1)5 2e-1023(.f)
(V = Not
Valid
if
the number X=(s,e,f) is
not
a normalized floating
point
number.
See
Floating Point Arithmetic, Rounding, and Normalization,
page D-4.)
•
If
s = 0, e = 0, and f = 0, then V = 0
•
For all other cases, V =
Not
Valid
Precision in the double- precision format
is
greater than fifteen decimal digits
and the range
includes the
following:
•
1.11254 x 10-
308
to
8.98847 x
10
308
(positive range)
(1.11254
E-308
to
8.98847 E308, in C format)
• -8.98847 x 1 0
308
to
-1
.11
254 x 10-
308
( negative range)
( -8.98847
E308
to
-1.11254
E-308, in C format)
• 0 (zero)
• + / -
infinity
0-3
Page 95
Appendix
0
0.3
Floating
Point
Arithmetic,
Rounding,
and
Normalization
D-4
While floating
point
packages
do
not
always implement a rounding scheme,
rounding does increase the precision
of
operations and conversions. The
TMS34010
C floating
point
RTS
package implements rounding in any
func-
tion where
it
is
applicable. The particular scheme implemented in the
TMS34010
RTS
package
is
known
as
"round
toward infinity". This
is
the na-
tural rounding method whereby negative-valued floating
point
numbers are
rounded toward negative
infinity
and positive-valued numbers
are
rounded
toward positive infinity. Because
all mantissas
are
unsigned, this type
of
rounding
is
accomplished
by
adding one
to
the retained part
of
a mantissa
whenever the most significant
bit
discarded was a one. The exception
to
this
is
when
a floating
point
number
is
converted
to
an
integer, in
which
case the
fractional part
is
truncated.
In addition
to
the "round toward
infinity"
feature, the TMS3401 0 C floating
point
RTS
package also implements extended real-number arithmetic. This
means
that
the subset
of
real
numbers representable by the
RTS
package,
along
with
+ / - infinity, form a well-ordered set. Moreover, it means
that
arithmetic operations
with
+ / -
infinity
as
one
or
both
operands can be per-
formed
with
certain error generating exceptions (see Table
0-1,
page
0-7).
The extended real number system
is
critical
to
advanced mathematic and en-
gineering
disciplines and its implementation can, therefore, be extremely use-
ful.
Note:
The implementation
of
extended real-number arithmetic does
not
affect
the arithmetic
when
neither operand
is
+ / - infinity. Extended
real
arith-
metic
is
strictly
an
added feature.
Floating-point
numbers
which
have
an
invalid value V are never generated
by
TMS34010
C floating
point
functions. In addition, .all floating
point
numbers
generated by the
TMS3401 0 C functions
are
normalized. Oenormalized
num-
bers
are
considered
to
be invalid and
as
such are never generated
by
any
function.
Normalized
floating-point
numbers
(with
the exception
of
zero and
+/-
infin-
ity) have a one in the
MSB
of
the mantissa. Oenormalized results
are
always
normalized
before their return.
If
normalization cannot be accomplished in the
format's range, then the appropriate
underflow
error
is
generated. A float-
ing-point
number
is
normalized
by
shifting the mantissa left until the
MSB
of
the mantissa
is
one and then subtracting the shift
count
from the exponent.
An
example
of
single precision normalization
is
shown
in Figure
0-3.
Page 96
Appendix
0
31
23 22
o
11
101000001 1
00001111000011110000111
OENORMALIZEO FLOATING NUMBER
31
23 22
o
11
1 00111101 1
11110000111100001110000
SAME NUMBER
AFTER
NORMALIZATION
Figure
0-3.
Single-Precision
Normalization
,
Normalization
for the
double
precision format
is
done
in
the same manner.
0.4
Floating
Point
Interface
Floating
point
functions
do
not
adhere
to
the C calling convention and cannot
be
called via a C function call.
Each
floating
point
function requires its argu-
ments
to
be
in
a particular order on the program stack: the
32
least-significant
bits
of
double precision numbers are pushed
onto
the stack first; the 32
most-significant bits are pushed on
last. Integer arguments and results are
passed via register
AB.
If
you
wish
to
call the
functions
directly (bypassing the C compiler), you must
do
so via TMS3401 0 assembly language.
0.4.1
Floating
Point
Conversions
The
TMS34010 C floating-point
conversion functions can be classified
into
two
categories:
• The "exact" conversion functions: .
-
FP
-ITOD
- signed integer
to
double
-
FP
- FTOD - float
to
double
-
FP
_ UTOD - unsigned integer
to
double
•
The "best
fit"
conversion functions:
-FP-DTOF -double
to
float
-
FP
- FTOI - float
to
signed integer
-
FP
_ DTOI -
double
to
signed integer
-
FP
-ITOF
- signed integer
to
float
-
FP
- UTOF - unsigned integer
to
float
The "exact" conversion functions
are
such that the value
Vs
of
the number in
the source format is
exactly equal
to
Vd,
the value
of
the number
in
the desti-
nation format. Hence,
"exact" conversion functions never cause a loss
of
precision, and a
"faithful"
representation
of
the source number in the destina-
tionformat
is
one
that
has the same value (Vs = Vd).
The
"best
fit"
conversion
functions
are
those
which
cannot always make the
conversion so that
Vs = Vd.
Hence, they must convert
to
the closest possible
0-5
Page 97
Appendix 0
value representable in.
th~
cjes1:inati.on
format. Since the set
of
possible values
representable
by the destination format
is
always finite (although very large),
this "best
fit"
value
Vd
does exist and
is
unique. A conversion error
is
gener-
ated whenever
Vs
lies outside the range
of
the destination format unless
-1
<
Vs < 1. A "faithful"
representation
of
the.
source number in the destination
format
is
defined
as
the unique number such that
Vd
best fits
Vs.
·0.5
Floating-Point
Error Exception Handling
D-6
Numerous errors
are
detectable by the TMS34010 C
floating-point
run-time
support functions, and you can trap
every error that
is
detected.
Each
error
Can
be trapped independently, so you
are
free to trap one type
of
error while ac-
cepting the default result on any
or
all others. This trapping is done by means
of
a user-defimible error exception handling routine called
fp-error.
This rou-
tine
is
called by the floating
point
package whenever one
of
the detectable
errors occurs. For a complete list
of
detectable errors,
see
Table
0-1,
page
0-7.
When
an
error is encountered,
fp-error
is
called using the C calling conven-
tion,
with
an
error number passed
as
an
argument.
An
example
of
fp-error
might
be:
void
fp -error
(err)
int
err;
(
switch(err)
(
1:
2:
3:
printf("CONVERSION
ERROR");
return;
5:
6:
7:
pr
intf ( "ARITHMETIC
OVERFLOW");
return;
Note:
This example routine attempts no error recovery,
but
it
would
be
useful in
debugging
an
algorithm.
Page 98
Appendix
0
Table
0-1.
Floating
Point
Error
Descriptions
Error
Functions
Code
Generating
Error
Description
(decimal)
the
Error
1
-FP-DTOI
Conversion error: Generated
if
destination format cannot
-FP-DTOU
faithfully represent source value(essentially
2
-FP-DTOF
an
overflow occurs
when
trying
to
make the conversion
3
-FP-FTOI
from source format
to
destination format).
-FP-FTOU
4
-FP-ADD
Infinity
- infinity: Default result
is
zero.
5
-FP-ADD
Overflow: Generated
when
there
is
an
6
-FP-MUL
overflow
during
an
arithmetic operation (i.e.,
7
-FP-DIV
the result
is
too
big
to
be represented in the given format).
Default result
is
+ / - infinity.
11
-FP-MUL
Infinity
x 0: default result
is
zero.
12
-FP-ADD
Underflow: Generated
when
there
is
an
underflow
13
-FP_MUL
during
an
arithmetic operation (Le., the
14
_FP_DIV
result
is
too
small
to
be represented in the given format). De-
fault result
is
zero.
15
-FP-DIV
Divide by zero: Default result
is
+ / - infinity.
16
-FP-DIV
Infinity/infinity:
Default result
is
+/-1.
0.5.1
Default
Error
Exception
Handler
The default error exception handler
fp-error
can be modified
to
meet
your
specific needs. As supplied, the routine
is
as
follows:
void
fp-error
(error_code)
int
error -code;
[
return;
/*
does
nothing
*/
}
0.6
Function
Descriptions
This section contains a description
of
each
of
the TMS3401 0 C floating
point
RTS
(Run-Time Support) functions.
Each
function
is
covered in a one-page
summary describing its inputs, outputs, error detection, and argument passing.
Argument passing
is
described via a convention indicating arguments
as
de-
scribed
below. The
following
notations and conventions
are
used in the
function
summaries:
float
double
int
opcode
single-precision
floating-point
number
(32
bits)
double-precision
floating-point
number
(64
bits)
integer
(32
bits)
32-bit
operation code
0-7
Page 99
Appendix 0
D-8
Note:
There
are
hever more than
two
inputs
to
a function,
with
the exception
of
FP-COMPARE,
which
has
three. Also, every function returns
only
one
result
though
it
may
be
an
integer, a single precision, or a double precision
number. Remember that single and double precision results
are
returned
via the argument stack,
while
integer results
are
returned via register
AS.
Page 100
FP
ADD
Double
Precision Add FP
ADD
Input(s)
double1, dauble2
Output(s)
double
Action
double1 + double2
.....
double
Description
This function takes
two
double-precision
floating-point
numbers and forms
their sum.
Errors Overflow (error code # =
5)
Underflow
(error code # =
12)
Infinity -Infinity
(error code # = 4)
Example
This
is
an
example
of
C code
which
generates a call
to -FP
-ADD.
main(
)
{
double
a,b,c
c = a + b ;
} ;
/*
declare
three
double
precision
floating
point
numbers
*/
/*
end
of
main
*/
D-9
Loading...