ZiLOG Developer Studio II-

Transcription

Z8XXZDS0200ZCC
ZiLOG Developer Studio II—Z8
User Manual
UM004407-0104
www.zilog.com
This publication is subject to replacement by a later edition. To determine whether a later edition exists, or
to request copies of publications, contact:
ZiLOG Worldwide Headquarters
532 Race Street
San Jose, CA 95126
Telephone: 408.558.8500
Fax: 408.558.8300
www.ZiLOG.com
Document Disclaimer
ZiLOG is a registered trademark of ZiLOG Inc. in the United States and in other countries. All other products and/or service
names mentioned herein may be trademarks of the companies with which they are associated.
©2004 by ZiLOG, Inc. All rights reserved. Information in this publication concerning the devices, applications, or technology
described is intended to suggest possible uses and may be superseded. ZiLOG, INC. DOES NOT ASSUME LIABILITY FOR OR
PROVIDE A REPRESENTATION OF ACCURACY OF THE INFORMATION, DEVICES, OR TECHNOLOGY DESCRIBED
IN THIS DOCUMENT. ZiLOG ALSO DOES NOT ASSUME LIABILITY FOR INTELLECTUAL PROPERTY INFRINGEMENT RELATED IN ANY MANNER TO USE OF INFORMATION, DEVICES, OR TECHNOLOGY DESCRIBED HEREIN
OR OTHERWISE. Devices sold by ZiLOG, Inc. are covered by warranty and limitation of liability provisions appearing in the
ZiLOG, Inc. Terms and Conditions of Sale. ZiLOG, Inc. makes no warranty of merchantability or fitness for any purpose Except
with the express written approval of ZiLOG, use of information, devices, or technology as critical components of life support systems is not authorized. No licenses are conveyed, implicitly or otherwise, by this document under any intellectual property rights.
UM004407-0104
ZiLOG Developer Studio II
Z8 User Manual
iii
Table of Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Manual Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxii
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiii
Additional Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiii
Readme.txt File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiii
Quick Tours in Z8 Developer’s Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxiii
ZiLOG Technical Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Supported ZiLOG Parts and Emulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
ZiLOG Parts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
Supported ZiLOG Emulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxiv
File Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
.asm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
.c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
.hex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
.lib . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
.lis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
.lnk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxv
.lod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
.lst . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
.mak . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
.map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
.obj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvi
.pro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
.s . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
.src . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
.srec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
.wsp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxvii
1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Supported Host System Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Recommended Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Minimum Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Software Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Z8 Developer’s Environment Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Developer’s Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Programmer’s Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
ANSI C-Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Macro Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Linker/Locator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
UM004407-0104
Z8 User Manual
iv
2
Integrated Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Instruction Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Emulator Drivers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Developer’s Environment Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Sample Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Create a New Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Add a File to the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Set Up the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Save the Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Debugging Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Set Up the Debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Switch to Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Disassemble the Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Set Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Emulator Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Change CPU Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Set Up the Z8 Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Instruction Simulator Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Change CPU Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Set Up the Simulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Command Processor Quick Tour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Write a Command Script File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Running the OTP from the Command Processor Toolbar . . . . . . . . . . . . . . . . . . . . 36
Running the Event System from the Command Processor Toolbar . . . . . . . . . . . . . 38
Running Trace from the Command Processor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Running ZDS II from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Building a Project from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Running the Compiler from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Running the Assembler from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Running the Linker from the Command Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Main Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
File Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Edit Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Build Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Command Processor Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Debug Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Debug Windows Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
UM004407-0104
Z8 User Manual
v
Project Workspace Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Build Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debug Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Find in Files Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Find in Files 2 Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Messages Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
New File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Open File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
New Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Open Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Save Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Close Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Save . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Save As . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Save All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Print Preview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Print Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recent Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Recent Projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Undo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Redo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cut . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Copy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Go to Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Find . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Find in Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Replace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Event System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Clear Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
View Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
62
63
65
65
66
66
66
67
67
67
68
68
69
69
71
72
72
72
73
73
73
73
75
75
75
75
75
75
76
76
76
76
76
76
76
77
78
79
80
80
80
Z8 User Manual
vi
3
Debug Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Status Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Project Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Add Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Remove Selected File(s) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Export Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Build Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Compile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Rebuild All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Stop Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Update All Dependencies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Debug . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
Set Active Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Manage Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Tools Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Trace and Event System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
OTP Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Customize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Window Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
New Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Close All . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Cascade . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Tile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Arrange Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Help Menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Help Topics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Online Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
About . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Status Bar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Code Line Indicators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Debug Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Debug Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Download Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Reset Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
UM004407-0104
Z8 User Manual
vii
4
Stop Debugging Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Go Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Run to Cursor Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Break Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step Into Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step Over Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Step Out Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Next Instruction Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Insert/Remove Breakpoint Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enable/Disable Breakpoint Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disable All Breakpoints Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Remove All Breakpoints Button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Debug Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Registers Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Special Function Registers Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Clock Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Memory Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Watch Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Locals Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Call Stack Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Symbols Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disassembly Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Trace Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Inserting Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Viewing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Moving to a Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Disabling Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Removing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Set Up the Z8 Emulator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Real-Time Trace System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Complex Breakpoint and Event Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the ANSI C-Compiler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Run-Time Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Errors <errno.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Standard Definitions <stddef.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Diagnostics <assert.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character Handling <ctype.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Limits <limits.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
140
140
140
140
140
140
141
141
141
141
141
141
142
143
143
144
145
150
152
153
153
154
155
160
160
161
162
162
162
163
163
163
164
167
169
170
171
171
172
173
174
Z8 User Manual
viii
Floating Point <float.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Mathematics <math.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Nonlocal Jumps <setjmp.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Variable Arguments <stdarg.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Input/Output <stdio.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Utilities <stdlib.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
String Handling <string.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Nonstandard I/O Functions <sio.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Architecture-Specific Functions <Z8.h> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Run-Time Library Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
acos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
asin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
assert . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atan2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atoi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bsearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
calloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ceil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cosh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
div . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
fabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
floor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
fmod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
fprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
free . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
frexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GET_ERF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GET_REG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GET_RREG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getche . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
getchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
gets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
175
176
178
179
180
180
182
184
185
186
187
187
188
188
189
189
189
190
190
191
191
192
192
193
193
194
194
195
195
196
196
197
199
200
200
201
201
202
202
203
203
Z8 User Manual
ix
init_uart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isalnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isalpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
iscntrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isdigit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isgraph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
islower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isprint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ispunct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isupper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
isxdigit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
kbhit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
labs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ldexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ldiv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
log10 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
longjmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
memchr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
memcmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
memcpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
memmove . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
memset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
modf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
pow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
putch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
putchar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
puts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
qsort . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
rand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
realloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
scanf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET_ERF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
setjmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SET_VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sinh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
204
205
205
205
206
206
206
207
207
207
208
208
208
209
209
210
210
211
211
212
212
213
213
213
214
214
215
215
219
220
220
221
221
222
222
226
226
227
227
228
228
Z8 User Manual
x
sqrt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
srand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
sscanf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strcat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strchr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strcmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strcpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strcspn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strlen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strncat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strncmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strncpy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strpbrk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strrchr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strspn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strtod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strtok . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
strtol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tanh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
tolower . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
toupper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
va_arg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
va_end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
va_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
vsprintf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Setting C-Compiler Options Using #Pragmas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma alias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma noalias . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma cpu <cpu name> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma globalcopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma noglobalcopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma globalcse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma noglobalcse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma globaldeadvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma noglobaldeadvar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma globalfold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma noglobalfold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma intrinsics: <state> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
229
229
229
230
230
231
231
232
232
232
233
233
234
234
235
235
235
236
237
238
238
239
239
239
240
241
242
242
243
243
243
243
243
243
243
244
244
244
244
244
244
Z8 User Manual
xi
#pragma nointrinsics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nobss . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma jumpopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nojumpopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma localcopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nolocalcopy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma localcse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nolocalcse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma localfold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nolocalfold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma localopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nolocalopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma noopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma optlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nooptlink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma optsize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma optspeed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma peephole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nopeephole . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma promote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nopromote . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma sdiopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nosdiopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma stkck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nostkck . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma strict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
#pragma nostrict . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Embedding Assembly in C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C Variables in Embedded Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Calling Assembly from C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigned Function Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Passing Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Return Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preserving Registers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the .FRAME Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Alignment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting C Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I speed up the compiler? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I call assembly from C? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Why does the compiler generate temporary variables? . . . . . . . . . . . . . . . . . . . . .
How do I make my C program smaller? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
244
244
244
244
244
244
245
245
245
245
245
245
245
245
245
245
245
245
246
246
246
246
246
246
246
246
246
246
247
248
248
248
249
249
250
250
250
250
251
251
252
Z8 User Manual
xii
5
Why is my code bigger when I select Optimize for Size than
when I select Optimize for Speed? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I make my C program faster? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I create an interrupt handler in C? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Can interrupt handlers take arguments? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
What is a register variable? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I embed assembly into my C code? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Why does the compiler give incompatible type errors? . . . . . . . . . . . . . . . . . . . . .
Why do floating-point operations give incorrect results? . . . . . . . . . . . . . . . . . . . .
Why don’t I see codes generated for my C statements? . . . . . . . . . . . . . . . . . . . . .
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Preprocessor Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Front-End Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Code Generator Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Macro Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Address Spaces and Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Allocating Processor Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Address Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assigning Memory at Link Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Output Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source Listing (.lst) Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Object Code (.obj) File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source Language Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
General Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assembler Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HIGH and LOW Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Decimal Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hexadecimal Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Binary Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Octal Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Floating-Point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ALIGN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.COMMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
252
252
252
253
253
253
254
254
254
254
255
257
265
267
268
268
268
268
270
270
270
271
272
272
273
274
274
275
275
275
275
276
276
276
276
276
277
277
277
277
Z8 User Manual
xiii
6
CPU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Data Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
END . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
EQU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
INCLUDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NEWPAGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NOLIST . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SEGMENT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TITLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
VECTOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XDEF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XREF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conditional Assembly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conditional Assembly Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MACRO Definition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Macro Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local Macro Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Optional Macro Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Exiting a Macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Delimiting Macro Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Local Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Importing and Exporting Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Label Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Label Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Addressing Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source Language Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compatibility Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting the Assembler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Using the Linker/Locator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linker Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
<outputfile>=<module list> . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
CHANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COLOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
278
278
282
284
284
285
285
286
286
286
287
287
288
288
288
289
289
290
292
292
292
293
293
294
294
295
295
295
295
295
296
296
300
303
303
309
310
311
312
313
313
Z8 User Manual
xiv
DEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
DEFINE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FORMAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
GROUP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HEADING . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOCATE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MAXHEXLEN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
MAXLENGTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NOCOLOR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NODEBUG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NOMAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
NOWARN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ORDER . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
RANGE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SEARCHPATH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SEQUENCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SORT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
SPLITTABLE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UNRESOLVED IS FATAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WARN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WARNING IS FATAL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
WARNOVERLAP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Linker Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
+ (Add) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
& (And) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
BASE OF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COPY BASE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
COPY TOP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
/ (Divide) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
FREEMEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
HIGHADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LENGTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
LOWADDR . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
* (Multiply) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Decimal Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Hexadecimal Numeric Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
| (Or) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
<< (Shift Left) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
>> (Shift Right) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
314
315
315
315
316
316
316
322
322
322
323
323
323
323
324
324
325
325
325
326
326
326
327
327
328
328
328
328
329
330
330
330
330
330
331
332
332
332
332
332
333
Z8 User Manual
xv
- (Subtract) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
TOP OF . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
^ (Bitwise Exclusive Or) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
~ (Not) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Troubleshooting the Linker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I speed up the linker? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I generate debug information without generating code? . . . . . . . . . . . . . .
How much memory is my program using? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I create a hex file? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
How do I determine the size of my actual hex code? . . . . . . . . . . . . . . . . . . . . . . .
How do I get my program to start from reset with the interrupts disabled? . . . . . .
Warning Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
A ANSI C Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Tokens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
String Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Punctuators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Arithmetic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Other Operands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Sequence Points . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Primary Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Postfix Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Unary Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Cast Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Multiplicative Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Additive Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bitwise Shift Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Equality Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bitwise AND Operator (&) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bitwise Exclusive OR Operator (^) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bitwise Inclusive OR Operator (|) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
333
333
333
333
334
334
334
334
335
335
335
335
337
338
338
339
340
340
341
346
351
352
352
353
353
353
355
357
357
359
360
363
366
367
368
369
370
370
371
371
372
Z8 User Manual
xvi
Logical AND Operator (&&) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Logical OR Operator (||) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conditional Operator (?:) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Assignment Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Comma Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constant Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Declarations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Storage-Class Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Structure and Union Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Enumeration Specifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Declarators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Type Definitions and Type Equivalence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Labeled Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Compound Statement (or Block) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Expression and Null Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Selection Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Iteration Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Jump Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
External Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Function Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
External Object Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
B ANSI C Preprocessing Directives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Conditional Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Source File Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
372
373
373
374
375
376
377
377
377
378
378
379
380
383
384
389
390
391
393
393
393
394
394
395
396
397
398
400
400
400
400
401
403
405
405
407
407
407
407
408
409
Z8 User Manual
xvii
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Macro Replacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Argument Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The # Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
The ## Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Rescanning and Further Replacement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scope of Macro Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Line Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Semantics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Error Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Pragma Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Null Directive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Predefined Macro Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
C Shortcut Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
File Menu Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Edit Menu Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Project Menu Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Build Menu Shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
409
409
409
410
410
410
411
411
412
412
413
415
415
415
415
415
416
416
417
417
417
418
418
419
427
Z8 User Manual
xviii
List of Figures
Figure 1. New Project Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Figure 2. Configure New Project Dialog Box—Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Figure 3. Test Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Figure 4. Build Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Figure 5. Debug Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Figure 6. Disassembly Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Figure 7. Z8 Integrated Development Environment (IDE) Window . . . . . . . . . . . . . . . 54
Figure 8. File Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Figure 9. Edit Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Figure 10. Build Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Figure 11. Command Processor Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Figure 12. Debug Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Figure 13. Debug Windows Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Figure 14. Debug Windows Toolbar (with the Z8 Emulator Connected) . . . . . . . . . . . . 60
Figure 15. Project Workspace Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Figure 16. Edit Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Figure 17. Inserting a Bookmark . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Figure 18. Bookmark Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Figure 19. Build Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Figure 20. Debug Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Figure 21. Find in Files Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Figure 22. Find in Files 2 Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Figure 23. Messages Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Figure 24. Command Output Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Figure 25. Open Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Figure 26. New Project Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Figure 27. Configure New Project Dialog Box—Step 1 . . . . . . . . . . . . . . . . . . . . . . . . . 70
Figure 28. Open Project Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Figure 29. Save As Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Figure 30. Print Preview Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Figure 31. Go to Line Number Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Figure 32. Find Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
UM004407-0104
Z8 User Manual
xix
Figure 33. Find in Files Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Figure 34. Replace Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Figure 35. Breakpoints Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Figure 36. Add Files to Project Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Figure 37. Project Settings Dialog Box–General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Figure 38. Project Settings Dialog Box (C Tab, General Category) . . . . . . . . . . . . . . . . 85
Figure 39. Project Settings Dialog Box (C Tab, Code Generation Category) . . . . . . . . 87
Figure 40. Project Settings Dialog Box (C Tab, Optimizations Category) . . . . . . . . . . . 90
Figure 41. Project Settings Dialog Box (C Tab, Listing Files Category) . . . . . . . . . . . . 93
Figure 42. Project Settings Dialog Box (C Tab, Preprocessor Category) . . . . . . . . . . . . 95
Figure 43. Project Settings Dialog Box–Assembler Tab . . . . . . . . . . . . . . . . . . . . . . . . . 96
Figure 44. Project Settings Dialog Box (Linker Tab, General Category) . . . . . . . . . . . . 99
Figure 45. Project Settings Dialog Box (Linker Tab, Input Category) . . . . . . . . . . . . . 101
Figure 46. Additional Linker Directives Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . 103
Figure 47. Custom Link Control File Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
Figure 48. Project Settings Dialog Box (Linker Tab, Output Category) . . . . . . . . . . . . 105
Figure 49. Project Settings Dialog Box–Target Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Figure 50. Project Settings Dialog Box (Debugger Tab, Simulator Driver) . . . . . . . . . 109
Figure 51. Project Settings Dialog Box (Debugger Tab, Emulator Driver) . . . . . . . . . 110
Figure 52. Configure Emulator Driver Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
Figure 53. Save As Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Figure 54. Select Configuration Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Figure 55. Select Active Configuration List Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
Figure 56. Project Settings Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Figure 57. Manage Configurations Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Figure 58. Add Project Configuration Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
Figure 59. Trace and Event System Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
Figure 60. OTP Dialog Box (in Standalone Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
Figure 61. OTP Dialog Box (in Debug Mode) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Figure 62. Programmed Option Bits Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Figure 63. Customize Dialog Box–Toolbars Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Figure 64. New Toolbar Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Figure 65. Customize Dialog Box–Commands Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Figure 66. Options Dialog Box—General Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Figure 67. Options Dialog Box—Editor Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Figure 68. Syntax Coloring Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
UM004407-0104
Z8 User Manual
xx
Figure 69. Font Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 70. Options Dialog Box—Debugger Tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 71. Debug and Debug Window Toolbars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 72. Debug Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 73. Debug Windows Toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 74. Debug Windows Toolbar (with the Z8 Emulator Connected) . . . . . . . . . . .
Figure 75. Registers Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 76. Special Function Registers Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 77. Clock Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 78. Memory Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 79. Memory Window—Starting Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 80. Memory Window—Requested Address . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 81. Fill Memory Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 82. Save to File Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 83. Load from File Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 84. Watch Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 85. Locals Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 86. Call Stack Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 87. Symbols Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 88. Disassembly Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 89. Trace Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 90. Unfiltered Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 91. Disassembled Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 92. Raw Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 93. Save Trace Data File Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 94. Trace and Event System Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 95. Setting a Breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 96. Viewing Breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 97. Unfiltered Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 98. Disassembled Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 99. Raw Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 100. Save Trace Data File Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Figure 101. Trace and Event System Dialog Box . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
UM004407-0104
133
134
138
139
142
142
143
144
145
145
146
146
147
148
149
150
152
153
153
154
155
156
156
157
158
159
161
161
165
166
166
166
167
Z8 User Manual
xxi
List of Tables
Table 1.
Table 2.
Table 3.
Table 4.
Table 5.
Table 6.
Table 7.
Table 8.
Table 9.
Table 10.
Table 11.
Table 12.
Table 13.
Table 14.
Table 15.
Table 16.
Table 17.
Table 18.
Table 19.
Table 20.
Table 21.
Table 22.
Table 23.
UM004407-0104
Script File Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Command Line Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Assembler Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Compiler Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Debugger Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Librarian Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Linker Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
General Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Target Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Assembler Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Compiler Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Librarian Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Linker Command Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Standard Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Nonstandard Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Function Value Locations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249
Z8 Address Spaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
Predefined Segments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
Operator Precedence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Addressing Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Z8 Directive Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
Character Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
Trigraph Sequences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
Z8 User Manual
xxii
Preface
This user manual describes the Z8 instruction set developer’s environment.
MANUAL ORGANIZATION
This manual includes the following:
Chapter 1, “Getting Started,” briefly describes the tools that make up Z8 developer’s environment including the developer’s environment as well as quick tours that show you how
to use the developer’s environment. See page 1.
Chapter 2, “Main Components,” contains all the main components of the Z8 developer’s
environment and briefly explains their options. The main components are the toolbars,
windows, menu bar, and dialog boxes associated with the menu choices. See page 53.
Chapter 3, “Debugging,” contains information on debugging your program as well as
information on how to use the debugger with the ZiLOG simulator and emulator drivers.
See page 137.
Chapter 4, “Using the ANSI C-Compiler,” contains detailed information about using the
Z8 developer’s environment ANSI C-Compiler, such as formatting run-time libraries. See
page 169.
Chapter 5, “Using the Macro Assembler,” contains detailed information on how to use the
Z8 developer’s environment Macro Assembler as well as a description of the assembler’s
source language syntax. See page 267.
Chapter 6, “Using the Linker/Locator,” contains detailed information about the Z8 developer’s environment linker/locator including the commands supported by the linker. See
page 309.
Appendix A, “ANSI C Language,” contains the ANSI C language supported by the Z8
developer’s environment ANSI C-Compiler. See page 337.
Appendix B, “ANSI C Preprocessing Directives,” describes the ANSI C preprocessor
commands supported by the Z8 developer’s environment ANSI C-Compiler. See
page 405.
Appendix C, “Shortcut Keys,” lists the shortcut keys for the Z8 developer’s environment.
See page 417.
Note: For quick access to specific information, refer to the Index on page 427.
UM004407-0104
Preface
Z8 User Manual
xxiii
CONVENTIONS
The following conventions provide consistent user instructions and examples:
•
Menu commands and software button names are indicated in boldface letters. System
responses or prompts are not in boldface.
•
Carriage returns follow all user entries unless otherwise noted. The carriage return key
is referred to as the Return key.
•
The phrase CTRL X (where x is any key) means to press the key labeled CTRL while
simultaneously pressing another key; for example, CTRL Y.
The following conventions are used in this manual.
italics
Expressions in italics indicate variables to be replaced by specific values. For example, the
statement: watch <identifier> requires you to substitute a value for <identifier>.
Bold
Menu commands and software button names are bold to make them stand out in the text.
Likewise, bold is used to denote your executing a command (Press OK).
Monospaced type
This font represents information that you type or on-screen text (Type a: setup).
ADDITIONAL INFORMATION
Before you use technical support, consult the following documentation:
Readme.txt File
Refer to the readme.txt file in the following directory for last minute tips and information about problems that might occur while installing or running Z8 developer’s environment:
ZILOGINSTALL\ZDSII_product_version\
where ZILOGINSTALL is the ZDS II installation directory, product is the specific ZDS II
product, and version is the ZDS II version number.
Quick Tours in Z8 Developer’s Environment
After reading Chapter 1, “Getting Started” (starting on page 1), and Chapter 2, “Main
Components” (starting on page 53), you will have a familiarity with the Z8 developer’s
environment. Be sure to go through the quick tours starting on page 7.
UM004407-0104
Preface
Z8 User Manual
xxiv
ZILOG TECHNICAL SUPPORT
For technical questions about our products and tools or for design assistance, please use
our web page:
http://www.zilog.com
You must provide the following information in your support ticket:
•
•
•
•
•
Product release number (Located in the heading of the toolbar)
Product serial number
Type of hardware you are using
Exact wording of any error or warning messages
Any applicable files attached to the e-mail
To receive ZilOG Developer Studio (ZDS) II product updates and notifications, register at
the Technical Support web page.
SUPPORTED ZILOG PARTS AND EMULATORS
The Z8 developer’s environment supports the following ZiLOG parts and emulators.
ZiLOG Parts
To find out which ZiLOG parts are supported, use the following procedure:
1. Open a project in ZDS II.
2. From the Project menu, select Settings.
The Project Settings dialog box is displayed.
3. Use the CPU Family and CPU drop-down list box on the General tab to see the
supported ZiLOG parts.
Supported ZiLOG Emulators
To find out which ZiLOG emulators are supported, use the following procedure:
3. Select the Debugger tab.
4. From the Driver drop-down list, select Emulator Driver.
5. Click Configure Emulator Driver.
The Configure Emulator Driver dialog box is displayed.
UM004407-0104
Preface
Z8 User Manual
xxv
6. To see the supported emulators, use the Name drop-down list box in the Configure
Emulator Driver dialog box.
FILE TYPES
This section describes the file types used with the ZiLOG Developer Studio II.
.asm
This extension indicates that the file is an assembly language file.
.c
This extension indicates that the file is a C source file.
.hex
The linker/locator can generate several different object formats including Intel Hex
Records (.hex). Use the Executable Format drop-down list box in the Output category on
the Linker tab of the Project Settings dialog box to choose this format. See “Executable
Format” on page 105.
.lib
Static libraries have the .lib extension and are a collection of .obj files. To create a
static library, select New Project from the File menu. In the File Name field, type the
name of your library. You do not have to type the extension .lib. The extension is added
automatically. The Z8 developer’s environment creates a library file. See “New Project”
on page 69.
.lis
Select the Generate Compiler Listing File (.lis) check box in the Listing Files category of
the C (Compiler) tab of the Project Settings dialog box to tell the compiler to create a listing file (with the .lis file extension). All source lines are duplicated in this file, as are
any errors encountered by the compiler. See “Generate Compiler Listing File (.lis)” on
page 94.
.lnk
This extension indicates that the file is a link control file, an input file for the linker. These
files are displayed as shortcuts in Windows Explorer. You can open and read these files
using the ZDS II editor.
UM004407-0104
Preface
Z8 User Manual
xxvi
.lod
The linker/locator can generate several different object formats including IEEE 695
(.lod). Use the Executable Format drop-down list box in the Output category on the
Linker tab of the Project Settings dialog box to choose this format. See “Executable Format” on page 105.
.lst
This extension indicates an assembly listing file. To generate an assembly listing file,
select the Generate Listing File (.lst) check box of the Assembler tab of the Settings dialog
to tell the assembler to create an assembly listing file. The default is checked. See “Generate Listing File (.lst)” on page 97.
Select the Generate Listing File (.lst) check box of the Listing Files category of the C
(Compiler) tab to tell the compiler whether to keep the assembly source file after compiling your code. This can be useful when you want to inspect or modify the assembly code
generated by the compiler. Deselecting this option causes the compiler to remove the
.lst file after it has been assembled. See “Generate Listing File (.lst)” on page 94.
Note: The addresses in the assembly listing are relative. To convert the relative addresses into
absolute addresses, use the -relist option for the assembler. See “Source Listing (.lst)
.mak
This extension indicates that the file is a project make file. The format is
<project_name><current_configuration>.mak. To generate a make file, see “Export
Makefile” on page 112.
.map
The Generate Map File check box in the General category of the Linker tab on the Project
Settings dialog box determines whether the linker generates a link map file each time it is
run. The link map file is named your project’s name with the .map extension. See
page 100, page 316, and page 334.
.obj
Use the ANSI C-Compiler to convert your C source files with the .c extension into relocatable object modules with the .obj extension. The ANSI C-Compiler can be configured
using the Project Settings dialog box (C tab). See “C (Compiler) Tab” on page 84.
Use the Macro Assembler to translate Z8 assembly language files with the .asm extension
into relocatable object modules with the .obj extension. The Macro Assembler is configured using the Project Settings dialog box (Assembler tab). See “Assembler Tab” on
page 96. After your relocatable object modules are complete, convert them into an executable program using the linker/locator.
UM004407-0104
Preface
Z8 User Manual
xxvii
.pro
Project files have the .pro extension and are typically named after your project's name.
The Z8 developer’s environment creates a project file. The .pro file contains configuration information for your project. To create a new project, select New Project from the
File menu. In the File Name edit field, type the name of your project. You do not have to
type the extension .pro. It is added automatically. See “New Project” on page 69.
.s
This extension indicates that the file is an assembly source file.
.src
This extension indicates that the file is an assembly source file that was generated by the
compiler.
.srec
The linker/locator can generate several different object formats including Motorola SRecords (.srec). Use the Executable Format drop-down list box in the Output category
on the Linker tab of the Project Settings dialog box to choose this format. See “Executable
.wsp
This extension indicates that the file is a workspace file.
From the File menu, select Save Project. Saving your project creates a <name>.wsp file
where <name> is your project file name. This .wsp file contains all user interface specific
project configuration information such as window and toolbar positions. The .wsp file
resides in the same directory as your project file. See “Save Project” on page 72.
UM004407-0104
Preface
Z8 User Manual
1
1
Getting Started
This chapter describes the tools that make up the Z8 developer’s environment and provides a quick tour of the Z8 developer’s environment and Debug mode, so you can be
working with our graphical user interface in a short time. The following topics are covered:
•
•
•
•
•
•
•
•
•
UM004407-0104
“Supported Host System Configuration” on page 2
“Software Installation” on page 2
“Z8 Developer’s Environment Tools” on page 3
“Developer’s Environment Quick Tour” on page 7
“Debugging Quick Tour” on page 12
“Emulator Quick Tour” on page 15
“Instruction Simulator Quick Tour” on page 16
“Command Processor Quick Tour” on page 17
“Running ZDS II from the Command Line” on page 42
1 Getting Started
Z8 User Manual
2
SUPPORTED HOST SYSTEM CONFIGURATION
To effectively use this software and documentation, you need a basic understanding of the
C and assembly languages, the Z8 architecture, and Microsoft Windows.
Recommended Configuration
•
•
•
•
•
•
•
•
•
PC running MS Windows XP, SP1
Pentium III/500-MHz processor or higher
128-MB RAM
110-MB hard disk space
Super VGA Video Adapter
CD-ROM drive
Ethernet port
One or more RS-232 communication ports
Internet browser (Internet Explorer or Netscape)
Minimum Configuration
•
•
•
•
•
•
•
•
•
PC running MS Windows 98SE/WinNT 4.0—SP6/Win2000—SP3/WinXP—SP1
Pentium II 233-MHz processor
96-MB RAM
25-MB hard disk space (documentation not included)
Super VGA Video Adapter
CD-ROM drive
Ethernet port
One or more RS-232 communication ports
Internet browser (Internet Explorer or Netscape)
Note: The memory requirements might vary from system to system depending on the size of the
assembly or C source files. If your system has only 8 MB of RAM, C source files with
large functions and very large assembly files might cause an out-of-memory message on
your system.
SOFTWARE INSTALLATION
Perform the following procedure to install the Z8 developer’s environment:
1. Insert the CD in your CD-ROM drive.
UM004407-0104
1 Getting Started
Z8 User Manual
3
2. Follow the setup instructions on your screen.
Install the application in the location where you want it.
Z8 DEVELOPER’S ENVIRONMENT TOOLS
The Z8 developer’s environment is a tightly coupled collection of software development
tools under the direction of a developer’s environment, similar to Microsoft’s Developer
Studio. The developer’s environment lets you configure, manage, and execute each of the
tools in the system.
The Z8 developer’s environment is for the Z8 family of processors. Using the Z8 developer’s environment, embedded applications are developed more efficiently and intuitively
than ever before.
With the Z8 developer’s environment, you access all the tools through the Z8 developer’s
environment. Those tools include the following:
•
•
•
•
•
•
•
•
•
•
Developer’s environment
Programmer's editor
Macro Assembler
ANSI C-Compiler
Linker/locator
Integrated Command Processor
Automated make facility
Debug mode
Instruction Simulator
Emulator drivers
These tools are briefly discussed in this chapter. To read detailed information about the
main components in the Developer’s Environment as well as about the menus and dialog
boxes, see Chapter 2, “Main Components,” starting on page 53.
Developer’s Environment
The Z8 developer’s environment allows you to use standard Windows techniques to organize projects, write code, compile or assemble files, create executable programs, and
debug programs without leaving Windows or using a DOS window.
The developer’s environment includes the following main components.
Menu Bar
•
UM004407-0104
File menu
1 Getting Started
Z8 User Manual
4
•
•
•
•
•
•
•
Edit menu
View menu
Project menu
Build menu
Tools menu
Window menu
Help menu
For a detailed discussion on all the options and dialog boxes in the menu bar, see “Menu
Bar” on page 67.
Toolbars
•
•
•
•
•
•
File toolbar
Build toolbar
Edit toolbar
Command Processor toolbar
Debug toolbar
Debug Windows toolbar
For more information on these components, see “Toolbars” on page 54.
Windows
•
•
•
•
•
•
•
Project Workspace window
Edit window
Build Output window
Debug Output window
Find in Files Output windows
Messages Output window
Command Output window
For a detailed discussion on all the window options and dialog boxes, see “Windows” on
page 61.
Programmer’s Editor
The Z8 developer’s environment comes with a Windows-based programmer's editor.
UM004407-0104
1 Getting Started
Z8 User Manual
5
ANSI C-Compiler
The ANSI C-Compiler is an optimizing compiler that supports memory models. Use the
ANSI C-Compiler to convert your C source files with the .c extension into relocatable
object modules with the .obj extension. The ANSI C-Compiler can be configured using
the Project Settings dialog box (C tab). The Z8 developer’s environment ANSI C-Compiler also comes with a powerful optimizer that can be configured using the Project Settings dialog box (Code Generation, Optimizations categories on the C tab). See “C
(Compiler) Tab” on page 84 for information on the C (Compiler) tab options.
Note: For reference information on the compiler, see Chapter 4, “Using the ANSI C-Compiler,”
starting on page 169.
Macro Assembler
The Macro Assembler supports a wide range of conditional assembly directives and
assembler options. Use the Macro Assembler to translate Z8 assembly language files with
the .asm extension into relocatable object modules with the .obj extension. After your
relocatable object modules are complete, convert them into an executable program using
the linker/locator. The Macro Assembler is configured using the Project Settings dialog
box (Assembler tab). See “Assembler Tab” on page 96 for information on the Assembler
tab options.
Note: For reference information on the assembler, see Chapter 5, “Using the Macro Assembler,”
starting on page 267.
Linker/Locator
The linker/locator has a rich command language that enables you to link object modules
and libraries and locate code and data anywhere in memory. Use the linker/locator to
merge relocatable object modules and libraries into an executable program. An executable
program can be sent to an EPROM programmer to produce a final product or to the debugger for testing.
The linker/locator uses link control files to control the linking and locating process. Link
control files can be created by the developer’s environment for you, or you can create your
own. In most cases, the developer’s environment creates your link control files for you.
However, if your application requires special linking, refer to “Linker Commands” on
page 310 for the commands that make up a link control file.
Note: The best way to create your own link control file is to have the developer’s environment
create a template for you and then modify the template to meet your needs with the editor.
The Z8 developer’s environment linker/locator can generate several different object formats including IEEE 695 (.lod), Intel Hex Records (.hex), and Motorola S-Records
(.srec), which are useful when programming an EPROM after testing is complete.
IEEE 695 is the default format of the linker/locator because it is the preferred format for
debugging.
UM004407-0104
1 Getting Started
Z8 User Manual
6
The linker/locator can be configured, including the object format to be used, using the
Project Settings dialog box (Linker tab). See “Linker Tab” on page 98 for information on
the Linker tab options.
Note: For reference information on the linker/locator, see Chapter 6, “Using the Linker/Locator,”
starting page 309.
Integrated Command Processor
The Command Processor allows you to use commands or script files to automate the execution of a significant portion of the Integrated Development Environment’s (IDE’s) functionality. This is useful for tasks such as regression testing. Please see the “Command
Processor Quick Tour” on page 17 for details on using the Command Processor and
descriptions of supported commands.
Debug Mode
The Debug mode gives you complete control over your programs while running them on
the Z8 Instruction Simulator or the Z8 emulator. After an executable file is generated
using the linker/locator, you can test your program using the debugger running within the
Z8 developer’s environment. The debugger is invoked when you select Go or Reset from
the Debug submenu of the Build menu.
The debugger (Debug mode) requires that a driver be selected before your programs can
be executed. A driver can be a simulator or an emulator driver. The Instruction Simulator
is the default driver, but you can change the driver in the Project Settings dialog box
(Debugger tab).
Note: For more information on debugging, see Chapter 3, “Debugging,” starting on page 137.
Instruction Simulator
The Z8 developer’s environment Instruction Simulator interfaces with the debugger to
simulate the execution of programs without using an emulator or target hardware. The Z8
Simulator is selected using the Project Settings dialog box (Debugger tab). See “Debugger
Tab” on page 108 for information on the Debugger tab options. The Instruction Simulator
uses the debugger commands to perform complicated tasks such as simulating serial I/O
and interrupts.
Emulator Drivers
To find out which ZiLOG emulators are supported, use the following procedure:
3. Select the Debugger tab.
UM004407-0104
1 Getting Started
Z8 User Manual
7
4. From the Driver drop-down list, select Emulator Driver.
6. To see the supported emulators, use the Name drop-down list box in the Configure
Emulator Driver dialog box.
DEVELOPER’S ENVIRONMENT QUICK TOUR
This quick tour shows you how to use the Z8 developer’s environment. In order to begin
this tour, you need a basic understanding of Microsoft Windows and a basic understanding
of Microsoft Developer’s Studio. Estimated time for completing this exercise is 15 minutes.
In this tour, you do the following:
•
•
•
•
Create a new project
Add a file to the project
Modify the settings for the project
Build the project
When you complete this tour, you have a test.lod file that is used in the Debugging
Quick Tour.
Note: Be sure to read Chapter 2, “Main Components,” starting on page 61, to learn more about all
the dialog boxes and their options discussed in this tour.
Sample Program
For the purpose of this quick tour, your Z8 developer’s environment directory is
ZILOGINSTALL\ZDSII_product_version\
Create a New Project
1. To create a new project, select New Project from the File menu.
The New Project dialog box is displayed.
From the New Project dialog box, click on the Browse button (
) to navigate to the
directory where you want your project to reside. For this quick tour, place your project
in the following directory:
ZILOGINSTALL\ZDSII_product_version\samples\processor_type_ledBlink\ledblink_asm\src\
2. In the File Name field, type the name of your project. Name this project test.
UM004407-0104
1 Getting Started
Z8 User Manual
8
The Z8 developer’s environment creates a project file. Project files have the .pro
extension and are typically named after your project's name. You do not have to type
the extension .pro. It is added automatically.
3. Click Select to return to the New Project dialog box.
4. Select the CPU family in the CPU Family drop-down list box. For this project, select
Z86D35.
5. Select the CPU in the CPU drop-down list box. For this project, select Z86D35AXJ.
6. For the project type, select the appropriate format. For this project, select Executable.
See Figure 1.
Figure 1. New Project Dialog Box
The default is to create an IEEE 695 executable format (.lod). For more information,
see “Linker Tab” on page 106.
7. Click Continue.
The Configure New Project dialog box is displayed.
8. Deselect the C Runtime Library check box, select No for the standard startup (boot)
module, and select the small memory model. See Figure 2.
UM004407-0104
1 Getting Started
Z8 User Manual
9
Figure 2. Configure New Project Dialog Box—Step 1
9. Click Next.
10. Click Finish.
Add a File to the Project
In this section, you add a file to the test project.
1. From the Project menu, select Add Files.
The Add Files to Project dialog box is displayed.
2. In the Add Files to Project dialog box, navigate to the following directory:
ZILOGINSTALL\ZDSII_product_version\ samples\processor_type_ledBlink\ledblink_asm\src\
3. Highlight the following file by clicking on it:
ledblink_asm.s
4. Click Add to add this file to the test project.
See Figure 3.
UM004407-0104
1 Getting Started
Z8 User Manual
10
Figure 3. Test Project
Notes: To view the files in the Edit window during the quick tour, double-click on the file in the
Project Workspace window.
To delete a file from a project, select the file in the tree view and press Alt+Delete.
Set Up the Project
Before you save and build the test project, change the settings in the Project Settings dialog box.
The Project Settings dialog box includes six tabs you must go through to set up the
project settings. Within the C (Compiler) and Linker tabs are categories that allow you
to set up subsettings on that specific tab’s category. For more information, see
“Settings” on page 90.
UM004407-0104
1 Getting Started
Z8 User Manual
11
2. In the drop-down list box in the upper left corner of the Project Settings dialog box,
make sure that Debug is selected.
For your convenience, the Debug configuration is a predefined configuration of
defaults set for debugging. For more information on project configurations such as
adding your own configuration, see “Set Active Configuration” on page 123.
3. Click OK.
4. Click OK to save all the settings on the Project Settings dialog box.
5. Click Yes to the warning message saying, "The project settings have
changed since the last build. Would you like to rebuild the
affected files?"
6. Watch the compilation process in the Build Output window (see Figure 4).
Figure 4. Build Output Window
UM004407-0104
1 Getting Started
Z8 User Manual
12
When the Build completed message is displayed in the Build Output window, you
have successfully built the test project and created a test.lod file to debug in the
Debugging Quick Tour.
Save the Project
You need to save your project. From the File menu, select Save Project.
DEBUGGING QUICK TOUR
This tour is designed to acquaint you with the Z8 developer’s environment debugger. You
must have an executable file called test.lod before continuing with this quick tour. By
completing the steps in the previous tour, the system creates a test.lod file in the following directory:
ZILOGINSTALL\ZDSII_product_version\ samples\processor_type_ledBlink\ledblink_asm\src\
Estimated time for completing this exercise is 15 minutes.
Note: Before doing this tour, read Chapter 2, “Main Components,” starting on page 61 to learn
more about the Debug toolbar (page 147) and Debug Windows toolbar (page 150).
In this tour, you do the following:
•
•
•
•
•
Set up the debugger
Activate Debug mode
Disassemble the code
Use the step features
Set breakpoints
Set Up the Debugger
Drivers are used to manage communication between your PC and the target device. A target device can be either an emulator or a simulator. By selecting a driver from the Driver
drop-down list box on the Project Settings dialog box (Debugger tab), you define where
your code runs.
For the purpose of this tour, a default driver has been selected for you. Make sure the
default driver, the Z8 Simulator, is applicable for your intended use.
Notes: For more information on using the Instruction Simulator with the Z8 developer’s
environment, see “Instruction Simulator Quick Tour” on page 16 before returning
to the next section of this tour.
For more information on using an emulator such as the Z8 emulator with the Z8
developer’s environment, see “Emulator Quick Tour” on page 15 before returning
to the next section of this tour.
UM004407-0104
1 Getting Started
Z8 User Manual
13
Switch to Debug Mode
Click the Reset button (
) on the Build toolbar to switch to Debug mode.
In Debug mode, the developer’s environment displays messages in the Debug Output window. The Debug toolbar and Debug Windows toolbar are displayed. The
ledblink_asm.s file is opened in the Edit window with the PC code line indicator (yellow arrow) at line 64. Blue dots are displayed to the left of all valid code lines; these are
lines where breakpoints can be set, the program can be run to, and so on.
The status bar displays the current status of your program’s execution. The status can be
STOP, STEP, or RUN. In STOP mode, your program is not executing. In STEP mode, a
Step Into, Step Over, or Step Out command is in progress. In RUN mode, a Go command
has been issued with no animate active.
Note: The status bar is either a box displayed in the upper right corner under the title bar or a
horizontal bar under the buttons, depending on your screen resolution.
See Figure 5.
Figure 5. Debug Mode
UM004407-0104
1 Getting Started
Z8 User Manual
14
Disassemble the Code
1. From the Debug Windows toolbar, click the Disassembly Window
button (
) to open the Disassembly window (Figure 6).
Figure 6. Disassembly Window
The Disassembly window displays assembly-level code corresponding to the sourcelevel code. The debugger lets you set breakpoints and step the code at the assembly
level as well as the C level.
2. Close the Disassembly window.
Set Breakpoints
Note: You can add a maximum of 64 breakpoints to a program.
1. Click the Step Into button (
) on the Debug toolbar once.
The Step Into button executes the code one statement at a time. In the Edit window,
the PC code line indicator moves to line 65.
2. Click in line 92 of the ledblink_asm.s file.
3. Click the Run to Cursor button (
) once.
In the Edit window, the PC code line indicator moves to line 92.
4. Click the Insert/Remove Breakpoint button (
UM004407-0104
) to set a breakpoint.
1 Getting Started
Z8 User Manual
15
A red octagon is displayed to the left of line 92.
5. Click the Reset button on the Build or Debug toolbar.
6. Click the Go button (
) to execute the code up to the breakpoint.
The PC code line indicator stops on the breakpoint at line 92.
7. Click the Enable/Disable Breakpoint button (
).
The breakpoint turns white, indicating that it is disabled.
8. Place your cursor in the gutter to the left of line 97 and double-click.
A red octagon is displayed to the left of line 97.
9. Click the Reset button.
10. Click the Go button.
The PC code line indicator stops on the breakpoint at line 97.
11. Click the Remove All Breakpoints button (
).
The breakpoints on lines 92 and 97 are deleted.
12. Click the Stop Debugging button (
) to exit the debugger.
You have successfully completed the Debugging Quick Tour for the Z8 developer’s environment.
EMULATOR QUICK TOUR
Use the Debugging Quick Tour in conjunction with this quick tour. Follow the steps in this
section for changing the CPU and setting up the emulator and then return to the Debugging Quick Tour.
Change CPU Selection
The CPU selection must be supported by the emulator you are using. Make sure the CPU
Family and CPU drop-down list boxes on the Project Settings dialog box (General tab) are
changed. See “CPU” on page 92.
UM004407-0104
1 Getting Started
Z8 User Manual
16
Set Up the Z8 Emulator
Use the following procedure to set up the emulator:
2. Click the Debugger tab.
3. Select Emulator Driver from the Driver drop-down list box.
5. Select the appropriate emulator from the Name drop-down list box.
6. Type the IP address in the IP Address field.
7. Type the port number in the TCP Port field.
8. Use the Voltage drop-down list box to select the appropriate target VCC voltage from
a list. If the emulator is not connected to a target, select Standalone.
The selected target VCC voltage needs to match the target application board's VCC. If
the emulator detects a VCC that is much lower than the selected VCC, ZDS II displays
a message that the target is not present and to check the target connection or VCC.
9. Select the appropriate clock frequency or enter the clock frequency in the Other field.
The default is 18.432.
10. Click OK to close and save the settings for the Configure Emulator Driver dialog box.
11. Click OK to close and save the settings for the Project Settings dialog box.
Now return to “Switch to Debug Mode” on page 13 in the Debugging Quick Tour and follow the procedures in that tour.
INSTRUCTION SIMULATOR QUICK TOUR
Use the Debugging Quick Tour in conjunction with this tour. Follow the steps in this section for changing the CPU, setting up the simulator, and then returning to the Debugging
Quick Tour.
Drivers are used to manage communication between your PC and the target device. A target device can be either an emulator or a simulator. By selecting a driver from the Driver
drop-down list box on the Project Settings dialog box (Debugger tab), you define where
your code runs.
Change CPU Selection
The CPU selection must be supported by the driver you are using. Make sure the CPU
Family and CPU drop-down list boxes on the Project Settings dialog box (General tab) are
changed.
UM004407-0104
1 Getting Started
Z8 User Manual
17
Set Up the Simulator
For the purpose of the Debugging Quick Tour, a default driver has been selected for you.
Make sure the default driver, Z8 Simulator is applicable for your intended use.
1. Select Settings from the Project menu.
3. Select Simulator in the Driver drop-down list box.
4. Make sure the Simulator Throttle speed is appropriate. The recommended setting is
50%.
Moving the thumb bar or scrolling the scroll bar adjusts the Simulator Throttle from
1% to 100%. A 1% throttle means that the simulator uses approximately 1% of the
system's resources while executing your program's instructions. This leaves plenty of
power to do other things while the simulator is running. A throttle of 100% uses
virtually all of your CPU's processing time to execute your program, allowing it to
complete faster.
5. In the Clock Speed field, type the appropriate speed.
6. Select the Load Memory Files check box if you want the debugger to automatically
load your memory files into the target platform's memory each time the debugger is
executed.
7. Select the Write Memory Files check box if you want the debugger to automatically
write your memory files into the target platform's memory each time the debugger is
executed.
COMMAND PROCESSOR QUICK TOUR
The Command Processor allows you to use commands or script files to automate the execution of a significant portion of the IDE’s functionality.
You can run commands in one of the following ways:
•
Using the Command Processor toolbar in the IDE
Commands entered into the Command Processor toolbar are executed after you press
the Enter (or Return) key or click the Run Command button.
•
Using the batch command to run a command script file from the Command
Processor toolbar
For example:
batch "c:\path\to\command\file\runall.cmd"
batch "commands.txt"
UM004407-0104
1 Getting Started
Z8 User Manual
18
•
Using the command script file when the IDE is started
You need to precede the script file with an at symbol (@) when passing the command
file to the IDE on the command line. For example:
zds2ide @c:\path\to\command\file\runall.cmd
zds2ide @commands.txt
Commands and associated results are displayed in the Command Output window in the
IDE and, if logging is enabled (see “log” on page 26), in the log file as well. You can prevent commands from being displayed by preceding a command with an at (@) symbol (for
example, @print "hello"), but the results are still displayed.
Write a Command Script File
A script file is a text-based file that contains a collection of commands. The file can be
created with any editor that can save or export files in a text-based format. Each command
must be listed on its own line. Anything following a semicolon (;) is considered a comment.
Sample Command Script File
; change to correct default directory
cd "m:\z8\test\focustests"
open project "focus1.pro"
log "focus1.log" ; Create log file
log on ; Enable logging
rebuild
reset
bp done
go
wait 2000 ; Wait 2 seconds
print "pc = %x" reg PC
log off ; Disable logging
quit ; Exit debug mode
open project "focus2.pro"
reset
bp done
go
wait 2000 ; Wait 2 seconds
log "focus2.log" ; Open log file
log on ; Enable logging
print "pc = %x" reg PC
log off ; Disable logging
quit ; Exit debug mode
This script consecutively opens two projects, sets a breakpoint at label done, runs to the
breakpoint, and logs the value of the PC register. After the second project is complete, the
script exits the IDE. The first project is also rebuilt.
UM004407-0104
1 Getting Started
Z8 User Manual
19
Supported Script File Commands
Table 1 lists ZDS II menu commands and dialog box options that have corresponding
script file commands.
Table 1. Script File Commands
ZDS II
Menus
ZDS II Commands
File
Edit
Dialog Box Options
Script File Commands
Page
New Project
new project
page 27
Open Project
open project
page 27
Exit
exit
page 25
list bp
page 26
cancel bp
cancel all
page 24
page 23
add file
page 22
CPU Family
CPU
Output Files Directory
option general cpu
Table 8
on
page 33
Project Settings (C tab,
General category)
Debug Information
Optimizations
Watch Compilation Process
Max Errors
Use Floating Point Library
Memory Model
option compiler debug
option compiler optspeed
option compiler watch
option compiler maxerrs
option compiler fplib
option compiler model
Table 4
on
page 29
Code Generation category)
Debug Information
Const Variable Placement
Alias Checking
ANSI Promotions
Strict ANSI Conformance
Frames
Use Intrinsics
Use Register Variables
option compiler debug
option compiler const
option compiler alias
option compiler promote
option compiler strict
option compiler optlink
option compiler intrinsic
option compiler regvar
Table 4
on
page 29
Breakpoints
Go to Code
Enable All
Disable All
Remove
Remove All
Project
Add Files
Project Settings (General
tab)
UM004407-0104
option general outputdir
1 Getting Started
Z8 User Manual
20
Table 1. Script File Commands (Continued)
ZDS II
Menus
ZDS II Commands
Dialog Box Options
Optimizations category)
Type
Peephole Optimizations
Loop Optimizations
Span-Dependent Instructions
Branch Optimizations
Optimize for
option compiler localopt
Table 4
option compiler globalopt on
page 29
option compiler localcse
option compiler globalcse
option compiler localfold
option compiler globalfold
option compiler localcopy
option compiler globalcopy
option compiler peephole
option compiler loopopt
option compiler sdiopt
option compiler jmpopt
Listing Files category)
Generate Compiler Listing File (.lis)
List Include Files in .lis
Expand Macros on Error
Generate Assembly Source (.src)
Interleave Source and Assembly
Generate Listing File (.lst)
option compiler list
option compiler listinc
option compiler expmac
option compiler asm
option compiler intsrc
option compiler keeplst
Table 4
on
page 29
Preprocessor category)
Preprocessor Definitions
Standard Include Paths
User Include Paths
option compiler define
option compiler stdinc
option compiler usrinc
Table 4
on
page 29
Optimizations
Common Subexpressions
Constant Folding
Copy Propagation
Project Settings (Assembly Debug Information
tab)
Jump Optimization
Generate Object
Ignore Case
Expand Macros
Page Length
Page Width
Display Errors/Warnings Only
Display Warnings
Include Path
Defines
UM004407-0104
Page
option assembler debug
Table 3
option assembler sdiopt
on
option assembler genobj
page 28
option assembler igcase
option assembler list
option assembler listmac
option assembler pagelen
option assembler pagewidth
option assembler quiet
option assembler warn
1 Getting Started
Z8 User Manual
21
ZDS II
Menus
ZDS II Commands
Dialog Box Options
Page
Project Settings (Linker tab, Output File Name
General category)
Object/Library Modules
Generate Warnings
Generate Debug Info
Generate Map File
Ignore Case
Symbol Cross-Reference
option linker of
option linker objlibmods
option linker warn
option linker debug
option linker map
option linker igcase
option linker xref
Table 7
on
page 33
Project Settings (Linker tab, Object/Library Modules
Input category)
Startup Module
Link Control File
option linker objlibmods
option linker startup
option linker createnew
option linker linkctlfile
option linker usecrun
Table 7
on
page 33
Project Settings (Linker tab, Output File
Output category)
Executable Format
Use Runtime Library
option linker of
option linker exeform
option linker usecrun
Table 7
on
page 33
Project Settings (Target tab) Char
Short
Float
Long
Int
Double
Bitfield
Code
RData
option target charsize
option target shortsize
option target floatsize
option target longsize
option target intsize
option target doublesize
option target bitfieldsize
option target code
option target rdata
Table 9
on
page 34
Project Settings (Debugger
tab, Simulator driver)
Simulator
Simulator Throttle
Load Memory Files
Write Memory Files
Clock Speed
option debugger driver
option debugger readmem
option debugger writemem
option debugger throttle
option debugger clock
Table 5
on
page 32
Project Settings (Debugger
tab, Emulator Driver)
Emulator Driver
Name
IP Address
TCP Port
Voltage
Clock Frequency (MHz)
option debugger driver
option debugger ice
Table 5
on
page 32
Use C Runtime Library
Build
option debugger port
option debugger baud
option debugger clock
Export Makefile
make
page 27
Build
build
rebuild
page 23
page 35
Rebuild All
rebuildall
page 35
UM004407-0104
1 Getting Started
Z8 User Manual
22
ZDS II
Menus
ZDS II Commands
Dialog Box Options
Stop Build
Debug
Connect to Target
Download Code
Stop Debugging
Reset
Go
Run to Cursor
Break
Step Into
Step Over
Step Out
Set Next Instruction
Page
stop
page 36
quit
reset
go
page 34
page 35
page 26
stop
stepin
step
stepout
page 36
page 35
page 35
page 35
Commands are not case sensitive.
In directory or path-based parameters, you can use \, \\, or / as separators as long as you
use the same separator throughout a single parameter. For example, the following examples are legal:
cd "..\path\to\change\to"
cd "..\\path\\to\\change\\to"
cd "../path/to/change/to"
The following examples are illegal:
cd "..\path/to\change/to"
cd "..\\path\to\change\to"
add file
The add file command adds the given file to the currently open project. If the full path
is not supplied, the current working directory is used. The following is the syntax of the
add file command:
add file "<filename>"
For example:
add file "blah.asm"
batch
The batch command runs a script file through the Command Processor. If the full path is
not supplied, the current working directory is used. The following is the syntax of the
batch command:
batch [wait] "<filename>"
UM004407-0104
1 Getting Started
Z8 User Manual
23
<wait>
blocks other executing batch files until the invoked batch file is
completed—useful when nesting batch files
For example:
BATCH "commands.txt"
batch wait "d:\batch\do_it.cmd"
bp
The bp command sets a breakpoint at a given label in the active file. The bp command has
the following syntax:
bp [temporary] [module <mod>] line <expr> \
[:<count>][condition]"<cond>"] \
[do"<commands>"]
[:<count>] is the number of times the IDE can encounter the breakpoint before stopping
execution.
<commands> is a list of commands to execute after encountering the breakpoint.
<cond> is a string interpreted as an expression whose value must be nonzero before the
debugger executes <commands>. If <cond> displays without <commands> and if
<cond> equals zero, the debugger executes a go command.
For example:
bp main
bp line 20
build
The build command builds the currently open project. This command blocks the execution of other commands until the build process is complete. The following is the syntax of
the build command:
build
cancel all
The cancel all command clears all breakpoints in the active file. The following is the
syntax of the cancel all command:
cancel all
For example:
cancel all
UM004407-0104
1 Getting Started
Z8 User Manual
24
cancel bp
The cancel bp command clears the breakpoint at bp list index num in the active file. The
following is the syntax of the cancel bp command:
cancel bp <num>
For example:
cancel bp 3
cd
The cd command changes the working directory to dir. The following is the syntax of the
cd command:
cd "<dir>"
For example:
cd "c:\temp"
cd "../another_dir"
examine (?) for Expressions
The examine command evaluates the given expression and displays the result. It accepts
any legal expression made up of constants, program variables, and C operators. The examine command takes the following form:
? [<data_type>] [<radix>] <expr> [:<count>]
<data_type> can consist of one of the following types:
short
int[eger]
long
ascii
asciz
<radix> can consist of one of the following types:
dec[imal]
hex[adecimal]
oct[al]
bin[ary]
Omitting a <data_type> or <radix> results in using the $data_type or $radix pseudovariable, respectively.
[:<count>] represents the number of items to display.
The following are examples:
? x
shows the value of x using $data_type and $radix.
UM004407-0104
1 Getting Started
Z8 User Manual
25
? ascii STR
shows the ASCII string representation of STR.
? 0x1000
shows the value of 0x1000 in the $data_type and $radix.
? *0x1000
shows the byte at address 0x1000.
? *0x1000 :25
shows 25 bytes at address 0x1000.
? L0
shows the value of register D0:0 using $data_type and $radix.
? asciz D0:0
shows the null-terminated string pointed to by the contents of register D0:0.
examine (?) for Variables
The examine command displays the values of variables. This command works for values
of any type, including arrays and structures. The following is the syntax:
? <expression>
To see the value of z, enter
?z
To see the nth value of array x, enter
? x[n]
To see all values of array x, enter
?x
To see the nth through the n+5th values of array x, enter
?x[n]:5
If x is an array of pointers to strings, enter
? asciz *x[n]
Note: When displaying a structure's value, the examine command also displays the names of each
of the structure's elements.
exit
The exit command exits the IDE. The following is the syntax of the exit command:
exit
UM004407-0104
1 Getting Started
Z8 User Manual
26
go
The go command starts or runs the debugger on the target machine. The go command can
take one of three forms:
•
go
resumes execution from the current location.
•
go <identifier>
resumes execution at the function identified by <identifier>.
•
go lines <expression>
resumes execution at the line number of the file currently shown in the Edit window
identified by the value of <expression>.
go
go lines 213
list bp
The list bp command displays a list of all of the current breakpoints of the active file.
The following is the syntax of the list bp command:
list bp
log
The log command defines the file to use as your script (sets the log file). The log command can take one of three forms:
•
log "<filename>" [APPEND]
sets the file name for the script file. If APPEND is not provided, this command results
in a new log when the log is next activated.
•
log on
loads the file (activates the log).
•
log off
quits and logs off the file (deactivates the log).
For example:
log "buildall.log"
@log on
@log off
UM004407-0104
1 Getting Started
Z8 User Manual
27
make
The make command exports a buildable project in make file format. The following is the
syntax of the make command:
make label -f "<filename>"
For example:
make Debug -f sampleproject_Debug.mak
make rebuildall -f sampleproject_Debug.mak
new project
The new project command creates a new project designated by project_name, target,
and the type supplied. If the full path is not supplied, the current working directory is used.
By default, existing projects with the same name are replaced. Use NOREPLACE to prevent
the overwriting of existing projects. The following is the syntax of the new project
command:
new project "<name>" "<target>" "<exe|lib>" [NOREPLACE]
<name> is the name of the new project.
<target> must match that of the IDE (that is, the Z8 IDE can only create Z8-based
projects).
<exe|lib> The type parameter must be either exe (Executable) or lib (Static Library).
NOREPLACE Optional parameter to use to prevent the overwriting of existing projects
For example:
new project "test1.pro" "Z8" "exe"
new project "test1.pro" "Z8" "exe" NOREPLACE
open project
The open project command opens the project designated by project_name. If the full
path is not supplied, the current working directory is used. The command fails if the specified project does not exist. The following is the syntax of the open project command:
open project "<project_name>"
For example:
open project "test1.pro"
open project "c:\projects\test1.pro"
option
The option command manipulates project settings for the currently open project. Each
call to option applies to a single tool but can set multiple options for the given tool. The
following is the syntax for the option command:
option <tool_name> expr1 expr2 . . . exprN,
UM004407-0104
1 Getting Started
Z8 User Manual
28
where
expr is (<option name> = <option value>)
For example:
option
option
option
option
option
option
option
assembler debug = TRUE
compiler alias = TRUE
debugger readmem = TRUE
librarian warn = FALSE
linker igcase = "FALSE"
general cpu=Z86C40
target code = 0000-FFFF
Note: Many of these script file options are also available from the command line. For more
details, see “Running ZDS II from the Command Line” on page 42.
Table 2 lists some command line examples and the corresponding script file commands.
Table 2. Command Line Examples
Script File Command Examples
Corresponding Command Line Examples
option compiler keepasm = TRUE
Z8cc -keepasm
option compiler keepasm = FALSE
Z8cc -nokeepasm
option compiler const = RAM
Z8cc -const:RAM
option assembler debug = TRUE
Z8asm -debug
option linker igcase = "FALSE"
Z8link -NOigcase
option librarian warn = FALSE
Z8lib -nowarn
Table 3 through Table 9 list the available script file options for each tool.
Table 3. Assembler Options
Option Name
Description
Acceptable Values
debug
Toggles debug information.
TRUE, FALSE
genobj
Toggles object generation.
TRUE, FALSE
igcase
Toggles Ignore Case.
TRUE, FALSE
list
Toggles listing file generation.
TRUE, FALSE
listmac
Toggles macro expansion.
TRUE, FALSE
pagelen
Sets page length.
integer
pagewidth
Sets page width.
integer
quiet
Toggles quiet assemble.
TRUE, FALSE
UM004407-0104
1 Getting Started
Z8 User Manual
29
Table 3. Assembler Options (Continued)
Option Name
Description
Acceptable Values
sdiopt
Toggles Jump Optimization.
TRUE, FALSE
warn
Toggles display warnings.
TRUE, FALSE
Table 4. Compiler Options
Option Name
Description
Acceptable Values
alias
Toggles checking alias information.
TRUE, FALSE
asm
Runs the assembler. The default is TRUE.
TRUE, FALSE
asmsw="string"
Passes assembler switches in string to assembler. For example:
option compiler asmsw="-define:TEST"
TRUE, FALSE
bitfieldsize=n
Sets the size of a short data type in bits. The default is 24.
Changing this value can cause the compilation to fail.
integer
charsize=n
Sets the size of a char data type in bits. The default is 8.
integer
const
Selects where const variables are placed. For example:
option compiler const=RAM
RAM, ROM
cpu=cpu
Sets the CPU and model. For example:
option compiler cpu=z86c40
string
debug
Toggles debug information generation.
TRUE, FALSE
define=def
Sets preprocessor definitions.
string
doublesize=n
integer
embedded
Runs the compiler in embedded mode. This switch allows the
near, far, interrupt, and other embedded keywords to be
used. The Z8CC compiler requires this switch for proper code
generation.
TRUE, FALSE
expmac
Toggles the expansion of macros on error. The default is FALSE. TRUE, FALSE
floatsize=n
integer
fplib
Toggles the use of the floating-point library. The default is
FALSE.
TRUE, FALSE
globalcse
Toggles application of global common subexpression
optimizations.
TRUE, FALSE
globalcopy
Toggles the application of global copy propagation optimizations. TRUE, FALSE
UM004407-0104
1 Getting Started
Z8 User Manual
30
Table 4. Compiler Options (Continued)
Option Name
Description
Acceptable Values
globaldead
The compiler removes code that never gets executed.
TRUE, FALSE
globalfold
Toggles the application of global constant folding optimizations. TRUE, FALSE
globalopt
Toggles global optimizations.
help
Prints a list of options.
intrinsics
Toggles use of intrinsics.
TRUE, FALSE
intsize=n
Sets the size of an int data type in bits. The default is 24.
integer
intsrc
Toggles the interleaving of source and assembly in generated list TRUE, FALSE
file.
jmpopt
Toggles application of branch optimizations.
TRUE, FALSE
keepasm
Keeps the assembler source file. The default is FALSE.
TRUE, FALSE
keeplnk
Keeps the .lnk link control file. This file is created in order to
link applications. The default is FALSE.
TRUE, FALSE
keeplst
Toggles the generation of assembly listing files (.lst). The
default is FALSE.
TRUE, FALSE
link
Runs the linker. The default is FALSE.
TRUE, FALSE
list
Toggles the generation of list file (.lis). The default is FALSE. TRUE, FALSE
listinc
Toggles the listing of includes in generated list file.
localcopy
Toggles the application of local copy propagation optimizations. TRUE, FALSE
localcse
Toggles application of local common subexpression
optimizations.
TRUE, FALSE
localfold
Toggles the application of local constant folding optimizations.
TRUE, FALSE
localopt
Toggles local optimizations.
TRUE, FALSE
longsize=n
Sets the size of a long data type in bits. The default is 32.
integer
loopopt
Toggles application of loop optimizations.
TRUE, FALSE
maxerrs
Sets the compilation errors maximum. The default is 50.
integer
model=model
Selects the memory model. Select S for a small memory model, ‘S’ (small model),
which is the most efficient model. Select L for a large memory
‘L’ (large model)
model, which is less efficient than the small model. The default is
L.
UM004407-0104
TRUE, FALSE
TRUE, FALSE
1 Getting Started
Z8 User Manual
31
Option Name
Description
Acceptable Values
optlink
Uses a static frame for local variables and function arguments.
This switch is required if the supplied run-time library is used.
Although this switch is not required in other cases, it results in
smaller, faster executables by minimizing use of the stack.
TRUE (use static
frames), FALSE (use
dynamic frames)
optsize
Optimizes code for size. The default is TRUE.
TRUE, FALSE
optspeed
Toggles optimizing for speed.
TRUE (optimize for
speed), FALSE
(optimize for size)
peephole
Toggles application of peephole optimizations.
TRUE, FALSE
promote
Toggles ANSI promotions.
TRUE, FALSE
quiet
Suppresses title information that is normally displayed to the
TRUE, FALSE
screen. Errors and warnings are still displayed. The default setting
is to display title information.
regvar
Toggles use of register variables.
ram
Sets the range for RAM.
rom
Sets the range for RAM.
sdiopt
Toggles application of span-dependent instructions optimizations. TRUE, FALSE
shortsize=n
integer
stdinc:path_list
Sets the path for the standard include files. This defines the
location of include files using the #include file.h syntax.
Multiple paths are separated by semicolons. For example:
option compiler stdinc="c:\Z8rtl;c:\myinc"
string (separate
multiple paths with
semicolons)
TRUE, FALSE
In this example, the compiler looks for the include file in
1. the default directory
2. the c:\Z8rtl directory
3. the c:\myinc directory
If the file is not found after searching the entire path, the compiler
flags an error.
Omitting this switch tells the compiler to search only the current
directory.
stkck
Performs stack checking. The default is FALSE.
TRUE, FALSE
strict
Toggles strict ANSI conformance. The default is TRUE.
TRUE, FALSE
strtabsz=n
Sets the amount of memory to use to store strings and identifier
names. The default and maximum are both 32000 bytes.
integer
UM004407-0104
1 Getting Started
Z8 User Manual
32
Option Name
Description
Acceptable Values
trace1
Debug information for internal use.
trace2
trace3
usrinc:path_list
Sets the search path for user include files. This defines the
location of include files using the #include "file.h" syntax.
Multiple paths are separated by semicolons. For example:
option compiler
usrinc="c:\ZiLOGrtl;c:\myinc"
string (separate
multiple paths with
semicolons)
2. the c:\ZiLOGrtl directory
If the file is not found after searching the entire path, the compiler
flags an error.
Omitting this switch tells the compiler to search only the current
directory.
version
Prints the version number of the compiler.
watch
Toggles watch compilation.
TRUE, FALSE
Table 5. Debugger Options
Option Name
Description
Acceptable Values
baud
Sets the baud rate for communication with the emulator.
integer
clock
Sets the clock speed (simulator only).
string (for example, 20.00000)
driver
Sets the debug driver (simulator or emulator interface).
string
ice
Selects an emulator.
integer
port
Sets the communication port (emulator only).
integer
readmem
Toggles load memory from file on debugger startup.
TRUE, FALSE
simio
Enables/disables simulated I/O devices.
TRUE, FALSE
throttle
Sets the simulator throttle percent (simulator only).
integer (0–100)
upload
Toggles loading program on startup.
TRUE, FALSE
writemem
Toggles the saving of memory to file on debugger exit.
TRUE, FALSE
UM004407-0104
1 Getting Started
Z8 User Manual
33
Table 6. Librarian Options
Option Name
Description
Acceptable Values
outfile
Sets the output file name for the built library.
string
warn
Toggles the display of warnings.
string
Table 7. Linker Options
Option Name
Description
Acceptable Values
createnew
Toggles the creation of link control files on build.
integer: 0 (create new
file), 1 (use existing file)
debug
Toggles debug information generation.
TRUE, FALSE
exeform
Sets the resulting executable format.
string: “IEEE 695”,
"Intel Hex16", "Intel
Hex32", “Motorola S"
igcase
Toggles case sensitivity.
TRUE (case insensitive),
FALSE (case sensitive)
linkctlfile
Sets the link control file (path and) name. The value is only
used when createnew is set to 1.
string
map
Toggles map file generation.
TRUE, FALSE
objlibmods
Sets the object/library modules to be linked into the result file. string
of
Sets the output file (path and) name.
string
startup
Sets the startup module.
string
usecrun
Toggles the inclusion of the C run-time library.
TRUE, FALSE
warn
Toggles the display of warnings.
TRUE, FALSE
xref
Toggles symbol cross reference.
TRUE, FALSE
Table 8. General Options
Option Name
Description
Acceptable Values
cpu
Sets the CPU.
string
outputdir
Sets the output directory.
string
UM004407-0104
1 Getting Started
Z8 User Manual
34
Table 9.
Target Options
Option Name
Description
Acceptable Values
bitfieldsize
Sets the size in bits of the bitfield type.
integer
charsize
Sets the size in bits of the char type.
integer
code
Sets the size range for the code memory space.
string (min–max, for example, “0000–FFFF”)
doublesize
Sets the size in bits of the double type.
integer
floatsize
Sets the size in bits of the float type.
integer
intsize
Sets the size in bits of the int type.
integer
longsize
Sets the size in bits of the long type.
integer
shortsize
Sets the size in bits of the short type.
integer
rdata
Sets the size range for the RData memory space. string (min–max, for example, “00–FF”)
xdata
Sets the size range for the XData memory space. string (min–max, for example, “00–FF”)
print
The print command writes formatted data to the Command Output window and the log
(if the log is enabled). Each expression is evaluated, and the value is inserted into the
format_string. The following is the syntax of the print command:
print "<format_string>" expression1 expression2 ... expressionN
For example:
PRINT "the pc is %x" REG PC
print "pc: %x, sp: %x" REG PC REG SP
pwd
The pwd command retrieves the current working directory. The following is the syntax of
the pwd command:
pwd
quit
The quit command exits the debugger. The following is the syntax of the quit command:
quit
UM004407-0104
1 Getting Started
Z8 User Manual
35
rebuild
The rebuild command rebuilds the currently open project. This command blocks the
execution of other commands until the build process is complete. The following is the syntax of the rebuild command:
rebuild
rebuildall
The rebuildall command rebuilds all of the files in the currently open project. This
command also relinks the project. The following is the syntax of the rebuildall command:
rebuildall "<project_name>"
For example:
rebuildall "sample.pro"
reset
The reset command restarts the program in the debugger. The following is the syntax of
the reset command:
reset
step
The step command performs count steps (stepovers) in the active file. If the count is not
provided, a single step is performed. The following is the syntax of the step command:
step [count]
For example:
step
step 3
stepin
The stepin command steps into the function at the PC. If there is no function at the current PC, this command is equivalent to step 1. The following is the syntax of the
stepin command:
stepin
stepout
The stepout command steps out of the function. The following is the syntax of the
stepout command:
stepout
UM004407-0104
1 Getting Started
Z8 User Manual
36
stop
The stop command pauses the debugger when it is running. The following is the syntax
of the stop command:
stop
wait
The wait command instructs the command processor to wait the specified milliseconds
before executing the next command. The following is the syntax of the wait command:
wait <milliseconds>
For example:
wait 5000
wait bp
The wait bp command instructs the Command Processor to wait until the debugger stops
executing. The optional max_milliseconds parameter provides a method to limit the
amount of time a wait takes (that is, wait until the debugger stops or max_milliseconds
passes). The following is the syntax of the wait bp command:
wait bp [max_milliseconds]
For example:
wait bp
wait bp 2000
Running the OTP from the Command Processor Toolbar
For the Z86D53 Family only, use the following procedure to run the OTP:
1. Create a project or open a project with the Z86D53 Family of processors selected in
the CPU Family and CPU fields of the General tab of the Project Settings dialog box.
See “General Tab” on page 91.
The Emulator Ethernet address is needed by the OTP and can be entered in the
Configure Emulator Driver dialog box. See “Emulator Driver” on page 110.
2. In the Command field, type in the following command sequence to use the OTP:
OTP Command_Option ["path\file"] [OPTIONBITS="0,1,2,3,..."] [SERIALNUMBER =
"hexvalue"] [SERIALADDRESS ="hexvalue"] [SERIALSIZE ="hexvalue"]
[SERIALINCTYPE [NONE | SEQUENTIAL | PSEUDORANDOM]] [PAD :<hexvalue>] [REPEAT]
Note: <> indicates a variable; [] indicates optional commands.
Caution: The OTP dialog box and the Command Processor interface use the same parameters. If an option is not specified with the Command Processor interface, the
UM004407-0104
1 Getting Started
Z8 User Manual
37
current setting in the OTP dialog box is used. If a setting is changed with the
Command Processor interface, the OTP dialog box settings are changed.
Option Definitions
Command_Option
This option defines the command to be used by the
OTP. This option is required. The options are as
follows:
BURN | VERIFY | BLANKCHECK |
RAMCHECKSUM | DEVICECHECKSUM |
READOPTIONS | READDEVICE
["path\file"]
This option defines the file to be used. The file must
include the absolute path and must be enclosed by
double quotation marks. For example:
"C:\Program File\test.hex"
Note: If you are referencing files across a network,
select Map Network Drive from the Tools menu in
Windows Explorer to map the remote file system as a
network drive letter and use the network drive letter in
your command files instead of the full network path.
[OPTIONBITS="0,1,2,3,..."]
Defines which programming option bits are going to be
programmed. The options correspond to the ones listed
in the Programming Option Bits area in the OTP dialog
box (see “OTP Programming” on page 129). The
options available depend on the CPU and CPU family
selected on the General tab of the Project Settings
dialog box (see “General Tab” on page 91). Separate
numbers with a comma.
[SERIALNUMBER = "hexvalue"] Defines the serial number loaded into the part.
[SERIALADDRESS ="hexvalue"] Defines the address at which the serial number is
loaded.
[SERIALSIZE ="hexvalue"]
Defines the size of the serial number.
[SERIALINCTYPE [NONE |
Defines how the serial number is incremented on
SEQUENTIAL | PSEUDORANDOM]] subsequent burns.
[PAD :<hexvalue>]
If defined, the hexvalue is used to pad the hex file.
[REPEAT]
This option sets up the OTP to burn recursively. The
OTP executes the command, changes processor, and
then prompts to repeat the operation. You are given the
option to continue or stop. (Optional)
UM004407-0104
1 Getting Started
Z8 User Manual
38
Examples
The following are valid examples:
OTP BLANKCHECK
This command checks that the device does not contain any data.
OTP BURN
"c:\testing\test.hex" PAD :FF REPEAT
or
otp burn "c:\testing\test.hex" pad :FF repeat
The file test.hex is loaded into emulator RAM. The unused memory is filled with FF.
The data is burned from emulator RAM to OTP memory and then verified. After the programming is completed, a dialog box is displayed, prompting you to program an additional unit. Click Yes or No.
OTP VERIFY
The file test.hex in emulator RAM is verified against internal OTP.
Note: This example assumes that you are using the same hex file that was downloaded in
the previous example.
OTP SETUP
The current OTP parameters settings (hex file name and path, option bits selected, and
serial number address, size, starting point, and method of incrementing) are displayed in
the Command Output window.
OTP RAMCHECKSUM
This command calculates the checksum of the data in emulator RAM. The result is displayed in the Command Output window. Use this command before burning the OTP.
OTP DEVICECHECKSUM
This command calculate the checksum of data in emulator OTP. The result is displayed in
the Command Output window. Use this command after burning the OTP. The result
matches the result of OTP RAMCHECKSUM if the burn was successful.
OTP READOPTIONS
This command checks which programming option bits were burned. The result is displayed in the Command Output window.
Running the Event System from the Command Processor Toolbar
The ZDS II—Z8 Emulator allows you to run the event system from the Command Processor toolbar. You can use Command Processor keywords to set up, enable, and disable the
event system. Each of the parameters is persistent, which allows for the repetition of the
event settings with a minimum amount of repeated data entry.
UM004407-0104
1 Getting Started
Z8 User Manual
39
The following command structure is supported for the event system using the Command
Processor toolbar:
[EVENT][sp][WHEN][sp]<PC="####">[sp]<AND>[sp]<PCMASK ="####">[sp]<AND>[sp]
<PORT<port#>="##">[sp]<AND>[sp]PORT<port#>MASK="##">[sp]<AND>[sp]
<TRIGGERIN[:<0|1>|[sp]OFF>[THEN][sp]<BREAK|BREAKONLIMIT[:limit]]
Note: <> indicates optional commands; [] indicates required commands; [sp] indicates
the space character; “####” indicates a hexadecimal number with required
quotation marks. The entries are not case sensitive.
These keywords and options are defined as follows:
EVENT
Keyword for the script command parser (required).
WHEN
AND
Required to concatenate more than one item in the condition (WHEN) statement.
PC="####"
This option defines the Program Counter (PC) address to match on. "####"
indicates a hex number with required quotation marks. This option provides
support for 16 bits.
PCMASK="####"
This option defines the mask that is applied against the PC value. A bit value of
zero is a don’t care and matches either 0 or 1 values in the PC. This option provides
support for a 16-bit mask.
PORT<port#>="##"
This option defines the register address to match on. This option provides support
for 8 bits. port# can be 0, 1, 2, or 3.
PORT<port#>MASK="##"
This option defines the mask that is applied against the register address value. This
option provides support for 8 bits. port# can be 0, 1, 2, or 3.
TRIGGERIN<:#|[sp]OFF> This option defines the trigger-in condition. Following TRIGGERIN with either :0
or :1 enables the trigger-in condition and sets the desired match value to 0 or 1,
respectively. Following TRIGGERIN with [sp]OFF disables the trigger-in
condition.
THEN
BREAK
This option enables the break-on-match action (and disables the break-on-bufferlimit action).
BREAKONLIMIT[:limit]
This option enables the break-on-buffer-limit action (and disables the break-onmatch action). Optionally, the buffer limit can be modified by entering a colon
followed by a value from 0 to 64 (indicating the maximum size of the trace buffer
in 1-kbyte increments).
Note: The parser requires all three keywords (EVENT, WHEN, and THEN).
Items not included in the condition (WHEN) or action (THEN) are not modified.
UM004407-0104
1 Getting Started
Z8 User Manual
40
An individual term within the WHEN statement can be reset with either the DISABLE or
CLEAR command syntax:
EVENT WHEN PC CLEAR THEN
EVENT WHEN PORT0 DISABLE THEN
Examples
The following example is entered directly in the Command field as a single line:
EVENT WHEN PC = "0400" AND PCMASK="0FFF" AND PORT0="12" AND PORT0MASK="FF" THEN BREAK
Note: The “\” character can be used in a command batch text file to continue an event entry as
shown in the next example taken from a ZDS II batch file, testevent.txt.
The following example is from a script file that uses the batch-processing mode of the
Command Processor:
EVENT \
WHEN PC="2000" PCMASK="FFFF" AND \
PORT0="12" AND PORT0MASK="FF" AND \
PORT3="56" AND PORT3MASK="FF" AND \
TRIGGERIN:1 \
THEN \
BREAKONLIMIT:64 \
EVENTS Keyword
The entire event system can be enabled and disabled from the Command Processor using
the EVENTS keyword followed by the ENABLE or DISABLE command:
EVENTS ENABLE
or
EVENTS DISABLE
The event system configuration can be viewed using the following command:
EVENTS SETUP
The entire event system configuration can be reset with the following command:
EVENTS RESET
Running Trace from the Command Processor
The ZDS II—Z8 Emulator allows you to run trace from the Command Processor toolbar.
Each of the parameters is persistent, which allows for the repetition of the trace commands
with a minimum amount of repeated data entry. Command Processor keywords have been
added to allow for easy scripting to both configure and display trace.
UM004407-0104
1 Getting Started
Z8 User Manual
41
The following command structure for setting trace options can be used with the Command
Processor toolbar:
[TRACE][sp][SET][sp]<[BREAKONFULL] ON | OFF>[sp]<[FILTER] RAW | DISASM |
UNFILTERED>
the space character. The entries are not case sensitive.
TRACE
SET
BREAKONFULL
This option sets up the trace system to break run execution when trace is full.
The two options for this parameter are ON or OFF.
FILTER
This option sets up the filter to be used in the display or sent to a file. The
three options for this parameter are RAW, DISASM (disassembled raw trace),
and UNFILTERED.
RAW trace frames contain bus cycle information and can include emulator
“idle” cycle information in the trace display. DISASM is disassembled trace
that is processed RAW trace frames. The number of DISASM frames
displayed is always less than the number of RAW trace frames requested.
Extra time is needed by the IDE to get the RAW trace information and then
disassemble it. UNFILTERED is the exact information as stored in the trace
emulator memory.
Examples
TRACE SET BREAKONFULL ON FILTER RAW
TRACE SET BREAKONFULL OFF
TRACE SET FILTER DISASM
The following command structure is supported for getting trace frames in different formats using the Command Processor toolbar:
[TRACE][sp][GET][sp][FRAMES="#####"] [sp]<[FILTER] RAW | DISASM |
UNFILTERED>[sp]<"File to export to">
the space character; “####” indicates a hexadecimal number with required
quotation marks. The entries are not case sensitive.
UM004407-0104
1 Getting Started
Z8 User Manual
42
TRACE
GET
FRAMES="#####"
This sets up the number of trace frames to be loaded. If the number
of frames specified exceeds the number of frames available, only the
number of frames available will be returned. "####" indicates a
number with required quotation marks. The trace buffer contains
65,535 frames, and the shortcut of "-1" requests the entire trace
buffer.
FILTER
This option sets up the filter to be used in the display or sent to a
file. The three options for this parameter are RAW, DISASM
(disassembled trace), and UNFILTERED.
RAW trace frames contain bus cycle information and can include
emulator “idle” cycle information in the trace display. DISASM is
disassembled trace that is processed RAW trace frames. The number
of DISASM frames displayed is always less than the number of
RAW trace frames requested. Extra time is needed by the IDE to get
the RAW trace information and then disassemble it. UNFILTERED
is the exact information as stored in the trace emulator memory.
"File to export to" This is an optional parameter that specifies the file that the trace can
be written to for review at a later time. The path and file name must
be the last entries on the command line.
Examples
TRACE GET FRAMES="6000" FILTER RAW
TRACE GET FRAMES="6000"
TRACE GET FRAMES="-1" FILTER RAW "C:\TEST.TXT"
The current trace configuration can be viewed using the following command:
TRACE SETUP
RUNNING ZDS II FROM THE COMMAND LINE
You can run ZDS II from the command line. ZDS II generates a make file
(project_Debug.mak or project_Release.mak, depending on the project configuration)
every time you build or rebuild a project. For a project named test.pro set up in the
Debug configuration, ZDS II generates a make file named test_Debug.mak in the
project directory. You can use this make file to run your project from the command line.
UM004407-0104
1 Getting Started
Z8 User Manual
43
Building a Project from the Command Line
To build a project from the command line, use the following procedure:
1. Add the ZDS II bin directory (for example, C:\Program
Files\ZiLOG\ZDSII_Z8_4.1.0\bin) to your path by setting the PATH
environment variable.
The make utility is available in this directory.
2. Change to the project directory.
3. Export a buildable project in make file format. For example:
make Debug -f sampleproject_Debug.mak
make rebuildall -f sampleproject_Debug.mak
Running the Compiler from the Command Line
To run the compiler from the command line:
1. Open the make file in a text editor.
2. Copy the options in the CFLAGS section.
3. In a Command Prompt window, type the path to the compiler, the options from the
CFLAGS section (on a single line and without backslashes), and your C file. For
example:
C:\PROGRA~1\ZiLOG\ZDSII_Z8_4.1.0\bin\Z8cc -alias -asm -const:RAM -debug
-define:_z8f64 -NOexpmac -NOfplib -intsrc -intrinsic -NOkeepasm -NOkeeplst
-NOlist -NOlistinc -maxerrs:50 -NOmodsect -promote -quiet -NOstrict -NOwatch
-optsize -localopt -localcse -localfold -localcopy -peephole -globalopt
-NOglobalcse -NOglobalfold -NOglobalcopy -NOloopopt -NOsdiopt -NOjmpopt
-stdinc:"..\include;C:\PROGRA~1\ZiLOG\ZDSII_Z8_4.1.0\include"
-usrinc:"..\include" -cpu:z86c40 -bitfieldsize:24 -charsize:8 -doublesize:32
-floatsize:32 -intsize:24 -longsize:32 -shortsize:16 -asmsw:"-cpu:z86c40"
test.c
Notes: If you use DOS, use double quotation marks for the -stdinc and -usrinc commands
for the C-Compiler. For example:
-stdinc:"C:\z8\include"
If you use cygwin, use single quotation marks on both sides of a pair of braces for the
-stdinc and -usrinc commands for the C-Compiler. For example:
-stdinc:'{C:\z8\include}'
UM004407-0104
1 Getting Started
Z8 User Manual
44
Running the Assembler from the Command Line
To run the assembler from the command line:
2. Copy the options in the AFLAGS section.
3. In a Command Prompt window, type the path to the assembler, the options from the
AFLAGS section (on a single line and without backslashes), and your assembly file.
For example:
C:\PROGRA~1\ZiLOG\ZDSII_Z8_4.1.0\bin\Z8asm -debug -genobj -NOigcase
-include:"..\include" -list -NOlistmac -name -pagelen:56 -pagewidth:80 -quiet
-warn -NOzmasm -cpu:z86c40 test.asm
Running the Linker from the Command Line
To run the linker from the command line:
2. In a Command Prompt window, type the path to the linker and your linker file. For
example:
C:\PROGRA~1\ZiLOG\ZDSII_Z8_4.1.0\bin\z8lnk @e:\z8\rtl\testfiles\test\test.lnk
Command Line Options
Table 10, Table 11, Table 12, and Table 13 describe the command line options.
Notes: If you use DOS, use double quotation marks for the -stdinc and -usrinc commands
for the C compiler. For example:
-stdinc:"C:\z8\include"
If you use cygwin, use single quotation marks on both sides of a pair of braces for the
-stdinc and -usrinc commands for the C compiler. For example:
-stdinc:'{C:\z8\include}'
Table 10. Assembler Command Line Options
Option Name
Description
-cpu:name
Sets the CPU.
-debug
Generates debug information for the symbolic debugger. The default setting is
-nodebug.
-define:name[=value]
Defines a symbol and sets it to the constant value. For example:
-define:DEBUG=0
This option is equivalent to the C #define statement. The alternate syntax,
-define:myvar, is the same as -define:myvar=1.
UM004407-0104
1 Getting Started
Z8 User Manual
45
Table 10. Assembler Command Line Options (Continued)
Option Name
Description
-genobj
Generates an object file with the .obj extension. This is the default setting.
-help
Displays the assembler help screen.
-igcase
Suppresses case sensitivity of user-defined symbols. When this option is used, the
assembler converts all symbols to uppercase. This is the default setting.
-include:path
Allows the insertion of source code from another file into the current source file during
assembly.
-list
Generates an output listing with the .lst extension. This is the default setting.
-listmac
Expands macros in the output listing. This is the default setting.
-listoff
Does not generate any output in list file until a directive in assembly file sets the listing
as on.
-metrics
Keeps track of how often an instruction is used. This is a static rather than a dynamic
measure of instruction frequency.
-name
Displays the name of the source file being assembled.
-nodebug
Does not create a debug information file for the symbolic debugger. This is the default
setting.
-nogenobj
Does not generate an object file with the .obj extension. The default setting is
genobj.
-noigcase
Enables case sensitivity of user-defined symbols. The default setting is igcase.
-nolist
Does not create a list file. The default setting is list.
-nolistmac
Does not expand macros in the output listing. The default setting is listmac.
-noquiet
Displays title and other information. This is the default.
-nosdiopt
Does not perform span-dependent optimizations. All size optimizable instructions use
the largest instruction size. The default is sdiopt.
-nowarns
Suppresses the generation of warning messages to the screen and listing file. A warning
count is still maintained. The default is to generate warning messages.
-pagelength:n
Sets the new page length for the list file. The page length must immediately follow the =
(with no space between). The default is 56. For example:
-pagelength=60
-pagewidth:n
Sets the new page width for the list file. The page width must immediately follow the =
(with no space between). The default and minimum page width is 80. The maximum
page width is 132. For example:
-pagewidth=132
-quiet
Suppresses title information that is normally displayed to the screen. Errors and
warnings are still displayed. The default setting is to display title information.
UM004407-0104
1 Getting Started
Z8 User Manual
46
Table 10. Assembler Command Line Options (Continued)
Option Name
Description
-relist:mapfile
Generates an absolute listing by making use of information contained in a linker map
file. This results in a listing that matches linker-generated output. mapfile is the name of
the map file created by the linker. For example:
-relist:product.map
-sdiopt
Performs span-dependent optimizations. The smallest instruction size allowed is
selected for all size optimizable instructions. This is the default setting.
-trace
-version
Prints the version number of the assembler.
-warns
Toggles display warnings.
Table 11. Compiler Command Line Options
Option Name
Description
-alias
Enables alias checking. The compiler assumes that program variables can be aliased. The
default is noalias.
-asm
Assembles compiler-generated assembly file. This switch results in the generation of an
object module. The assembly file is deleted if no assemble errors are detected and the
keepasm switch is not given. The default is asm.
-asmsw:"sw"
Passes sw to the assembler when assembling the compiler-generated assembly file.
-bitfieldsize:n
Sets the size of container type for bitfield in bits. The default is 16. Changing this value
can cause the compilation to fail.
-charsize:n
Sets the size of a char data type in bits. The default is 8. Changing this value can cause the
compilation to fail.
-const:[ram|rom] Selects where const variables are placed.
-cpu:cpu
Sets the CPU. For example:
-cpu:Z86C40
-debug
Generates debug information for the symbolic debugger.
-define:def
Defines a symbol and sets it to the constant value. For example:
-define:DEBUG=0
This option is equivalent to the C #define statement. The alternate syntax,
-doublesize:n
Sets the size of double data type in bits. The default is 32. Changing this value can cause
the compilation to fail.
-expmac
Expands macros in displayed source lines when an error is detected. This is useful for
debugging macro expansions. The default is noexpmac.
UM004407-0104
1 Getting Started
Z8 User Manual
47
Table 11. Compiler Command Line Options (Continued)
Option Name
Description
-floatsize:n
Sets the size of float data type in bits. The default is 32. Changing this value can cause the
compilation to fail.
-fplib
Links with the floating-point emulation library.
-globalcopy
Turns on the application of global copy propagation optimizations.
-globalcse
Turns on application of global common subexpression optimizations.
-globaldead
Removes code that never gets executed.
-globalfold
Turns on the application of global constant folding optimizations.
-globalopt
Turns on global optimizations.
-help
Displays the compiler help screen.
-intrinsics
Specifies that intrinsic functions are to be expanded to inline code.
-intsize:n
Sets the size of an int data type in bits. The default is 16. Changing this value can cause
-intsrc
Integrates source code with the compiler assembly language output. This is the default.
-jmpopt
Turns on application of branch optimizations.
-keepasm
Keeps the compiler-generated assembly file. The default is nokeepasm.
-keeplnk
Keeps the .lnk link control file. This file is created in order to link applications. The default
is nokeeplnk.
-keeplst
Keeps the assembly listing file (.lst). The default is nokeeplst.
-link
Links after assembly.
-list
Generates a .lis source listing file. The default is nolist.
-listinc
Displays included files in the compiler listing file.
-localcopy
Turns on the application of local copy propagation optimizations.
-localcse
Turns on machine-level (local) common subexpression elimination optimization. This is
the default.
-localfold
Turns on the application of local constant folding optimizations.
-localopt
Turns on local optimizations.
-longsize:n
Sets the size of a long data type in bits. The default is 32. Changing this value can cause
-loopopt
Turns on application of loop optimizations.
-maxerrs:n
Specifies the maximum number of errors allowed before aborting the compilation process.
The default is 50.
UM004407-0104
1 Getting Started
Z8 User Manual
48
Option Name
Description
-model:model
Selects the memory model. Select S for a small memory model, which is the most efficient
model. Select L for a large memory model, which is less efficient than the small model.
The default is L.
-noalias
Disables alias checking. Use of this switch can reduce the size of executable files and
speed program execution. However, before specifying noalias, be sure that the program
does not use aliases, either directly or indirectly.
An alias occurs when two variables can reference the same memory location. The
following example illustrates an alias:
func{}
{
int x,*p;
p=&x;
/* both "x" and "*p" refer to same location */
.
.
.
}
If both *p and x are used below the assignment, malignant aliases exist, and the noalias
switch must not be used. Otherwise, the alias is benign, and the noalias switch can be
used.
-noasm
Does not assemble the compiler-generated assembly file. The default is asm.
-nocode
Internal use only.
-nodebug
Does not generate symbol debug information.
-noexpmac
Does not expand macros in the compiler listing file. This is the default.
-nofplib
Does not link with floating-point emulation library.
-noglobalcopy
Turns off the application of global copy propagation optimizations.
-noglobalcse
Turns off application of global common subexpression optimizations.
-noglobaldead
The compiler does not remove code that never gets executed.
-noglobalfold
Turns off the application of global constant folding optimizations
-noglobalopt
Turns off global optimizations.
-nointrinsics
Specifies that intrinsic functions are not to be expanded to inline code.
-nointsrc
Does not integrate source code with the assembly language output. The default is
intsrc.
-nojmpopt
Turns off application of branch optimizations.
-nokeepasm
Deletes the compiler-generated assembly file. This is the default.
UM004407-0104
1 Getting Started
Z8 User Manual
49
Option Name
Description
-nokeeplnk
Does not keep the .lnk link control file. This is the default.
-nokeeplst
Does not keep the assembly listing file (.lst). This is the default.
-nolink
Does not link. This is the default.
-nolist
Does not produce a source listing. All errors are identified on the console. This is the
default.
-nolistinc
Does not show include files in the compiler listing file.
-nolocalcopy
Turns off the application of local copy propagation optimizations.
-nolocalcse
Turns off the application of local common subexpression optimizations.
-nolocalfold
Turns off the application of local constant folding optimizations.
-nolocalopt
Turns off local optimizations.
-noloopopt
Turns off the application of loop optimizations
-noopt
Disables optimization.
-nop1
Internal use only.
-nop2
Internal use only.
-nopeephole
Turns off the application of peephole optimizations.
-nopromote
Turns off ANSI promotions.
-noquiet
Displays the title information.
-noregvar
Turns off the use of register variables.
-nosdiopt
Disables span-dependent instruction optimizations.
-nostkck
Does not perform stack checking. This is the default.
-nostrict
Does not flag warnings for obsolete features. This is the default.
-nowatch
Does not display passes of the compiler as they are invoked.
-optsize
Optimizes code for size.
-optspeed
Optimizes code for speed. This is the default.
-peephole
Turns on the application of peephole optimizations.
-promote
Turns on ANSI promotions.
-quiet
Suppresses title information that is normally displayed to the screen. Errors and warnings
are still displayed. The default setting is to display title information.
-regvar
Turns on the use of register variables.
-sdiopt
Performs span-dependent instructions optimization. This optimization results in branches
generated by the compiler taking the shortest form possible. This is the default.
UM004407-0104
1 Getting Started
Z8 User Manual
50
Option Name
Description
-shortsize:n
Sets the size of a short data type in bits. The default is 16. Changing this value can cause
-stdinc:"path"
Sets the path for the standard include files. This defines the location of include files using
the #include file.h syntax. Multiple paths are separated by semicolons. For example:
-stdinc:"c:\Z8rtl;c:\myinc"
2. the c:\Z8rtl directory
If the file is not found after searching the entire path, the compiler flags an error.
Omitting this switch tells the compiler to search only the current directory.
-stkck
Performs stack checking.
-strict
Checks for conformance to the ANSI standard and its obsolescent features. These include
old-style parameter type declarations, empty formal parameter lists, and calling functions
with no prototype in scope. When any of these features are used, a warning is flagged. The
compiler requires this switch for proper code generation because it makes use of a static
frame.
-strtabsz:n
Sets the amount of memory to use to store strings and identifier names. The default and
maximum are both 32000 bytes.
-trace1
-trace2
-trace3
-usrinc:"path"
Sets the search path for user include files. This defines the location of include files using
the #include "file.h" syntax. Multiple paths are separated by semicolons. For
example:
-usrinc:"c:\ZiLOGrtl;c:\myinc"
2. the c:\ZiLOGrtl directory
If the file is not found after searching the entire path, the compiler flags an error.
Omitting this switch tells the compiler to search only the current directory.
-version
Prints the version number of the compiler.
-watch
Displays passes of the compiler as they are invoked.
UM004407-0104
1 Getting Started
Z8 User Manual
51
Table 12. Librarian Command Line Options
Option Name
Description
-help
Displays the librarian help screen.
-list
Generates an output listing with the .lst extension. This is the default setting.
-noquiet
Displays the title information.
-nowarn
Suppresses warning messages.
-quiet
Suppresses title information that is normally displayed to the screen. Errors and warnings are still
displayed. The default setting is to display title information.
-version
Displays the version number of the librarian.
-warn
Displays warnings.
Table 13. Linker Command Line Options
Option Name
Description
copy segment = space
Makes a copy of a segment into a specified address space.
-debug
Turns on debug information generation.
define symbol = expr
Defines a symbol and sets it to the constant value. For
example:
-define:DEBUG=0
This option is equivalent to the C #define statement. The
alternate syntax,
-format:[intel|intel32|srec|omf695] Sets the format of the hex file output of the linker to srec
(Motorola S-records), intel or intel32 (Intel Hex
records), or omf695 (IEEE695 format).
-igcase
Suppresses case sensitivity of user-defined symbols. When
this option is used, the linker converts all symbols to
uppercase. This is the default setting.
locate segment at expr
Specifies the address where a group, address space, or
segment is to be located.
-nodebug
Turns off debug information generation.
-noigcase
Enables case sensitivity of user-defined symbols. The default
setting is igcase.
order segment_list or space_list
Establishes a linking sequence and sets up a dynamic range
for contiguously mapped address spaces.
UM004407-0104
1 Getting Started
Z8 User Manual
52
Table 13. Linker Command Line Options (Continued)
Option Name
Description
range space = address_range
Sets the lower and upper bounds of a group, address space, or
segment.
sequence segment_list or space_list
Allocates a group, address space, or segment in the order
specified.
UM004407-0104
1 Getting Started
Z8 User Manual
53
2
Main Components
This chapter discusses all the main components of the Z8 developer’s environment:
•
•
•
•
•
Toolbars (see page 54)
Windows (see page 61)
Menu bar (see page 67)
Menus (see on page 67)
Dialog boxes (see page 67)
To effectively understand how to use the developer’s environment, be sure to go through
the quick tours in Chapter 1, “Getting Started,” on page 1.
Note: The Command Processor allows you to use commands or script files to automate the
execution of a significant portion of the IDE’s functionality. For more information about
using the Command Processor, see “Command Processor Quick Tour” on page 17.
After the discussion of the toolbars and windows, this chapter discusses the menu bar (see
Figure 7) from left to right—File, Edit, View, Project, Build, Tools, Window, and Help—
and the dialog boxes accessed from the menus. For example, the Project Settings dialog
box is discussed as a part of the Project menu section. Refer to the List of Figures on
page xviii if you want to see a list of the dialog boxes and their respective page numbers.
UM004407-0104
2 Main Components
Z8 User Manual
54
Figure 7. Z8 Integrated Development Environment (IDE) Window
For a table of all the shortcuts used in the Z8 developer’s environment, see Appendix C,
“Shortcut Keys,” starting on page 417.
TOOLBARS
The toolbars give you quick access to most features of the Z8 developer’s environment.
You can use these buttons to perform any task.
Note: There are cue cards for the toolbars. As you scroll across the toolbars, the main function of
the button is displayed. Also, you can drag and move the toolbars to different areas on the
screen.
These are the available toolbars:
•
•
•
•
UM004407-0104
File toolbar (page 55)
Edit toolbar (page 56)
Build toolbar (page 56)
Command Processor toolbar (page 58)
2 Main Components
Z8 User Manual
55
•
•
Debug toolbar (page 58)
Debug Windows toolbar (page 60)
Note: For more information on Debugging, refer to Chapter 3, “Debugging,” starting on
page 137.
File Toolbar
The File toolbar (Figure 8) allows you to perform basic functions with your files.
Figure 8. File Toolbar
New Button
The New button creates a new file.
Open Button
The Open button opens an existing file.
Save Button
The Save button saves the active file.
Save All Button
The Save All button saves all files.
Cut Button
The Cut button deletes selected text from a file and puts it on the clipboard.
Copy Button
The Copy button copies selected text from a file and puts it on the clipboard.
Paste Button
The Paste button pastes the current contents of the clipboard into a file.
Delete Button
The Delete button deletes selected text from a file and puts it on the clipboard.
Print Button
The Print button prints the active file.
UM004407-0104
2 Main Components
Z8 User Manual
56
Workspace Window Button
The Workspace Window button shows or hides the Project Workspace window.
Output Window Button
The Output Window button shows or hides the Build Output window.
Edit Toolbar
The Edit toolbar (Figure 9) allows you to perform basic edit functions.
Figure 9. Edit Toolbar
Find in Files Button
This button opens the Find in Files dialog box for you to search files.
Find Field
To locate text in the currently selected file, type the text in the Find field and press the
Enter key. The search term is highlighted in the file. To search again, press the Enter key
again.
Build Toolbar
The Build toolbar (Figure 10) allows you to build your projects and select a project configuration.
Figure 10. Build Toolbar
Select Active Configuration List Box
The Select Active Configuration drop-down list box lets you select the configuration for
your project. See “Set Active Configuration” on page 115 for more information.
Compile/Assemble File Button
The Compile/Assemble File button compiles or assembles the active file in the Edit
window.
UM004407-0104
2 Main Components
Z8 User Manual
57
Build Button
The Build button builds your project by compiling and/or assembling any files that have
changed since the last build and then relinks the project.
Rebuild All Button
The Rebuild All button rebuilds all files and relinks the project.
Stop Build Button
The Stop Build button stops a build in progress.
Connect to Target
The Connect to Target button starts a debug session and initializes the communication to
the target hardware. Clicking this button does not download the software or reset to main.
Use this button to access target registers, memory, and so on, without loading new code or
to avoid overwriting the target’s code with the same code. This button is not enabled when
the target is the simulator.
Download Code
The Download Code button downloads the executable file for the currently open project to
the target for debugging. The button also initializes the communication to the target hardware if it has not been done yet. Use this button anytime during a debug session.
Note: The current code on the target is overwritten.
Reset Button
The Reset button resets the debugger. By default, clicking the Reset button resets the PC to
symbol 'main'. If you deselect the Reset to Symbol 'main' (Where Applicable) check box
on the Debugger tab of the Options dialog box (see page 133), the PC resets to the first
line of the program.
Go Button
The Go button invokes Debug mode (makes the debugger run).
Insert/Remove Breakpoint Button
The Insert/Remove Breakpoint button allows you to add a breakpoint in a file at the line
where the cursor is or to delete a breakpoint from the line where the cursor is. You can set
a breakpoint in any line with a blue dot displayed to the left of the line (shown in Debug
mode only).
UM004407-0104
2 Main Components
Z8 User Manual
58
Enable/Disable Breakpoint Button
The Enable/Disable Breakpoint button allows you to activate a breakpoint in a file at the
line where the cursor is or deactivate a breakpoint at the line where the cursor is. A red
octagon indicates an enabled breakpoint; a white octagon indicates a disabled breakpoint.
Remove All Breakpoints Button
The Remove All Breakpoints button deletes all breakpoints in all open files.
Command Processor Toolbar
The Command Processor toolbar (Figure 11) allows you to execute IDE and debugger
commands. See “Supported Script File Commands” on page 19 for a list of supported
commands.
Figure 11. Command Processor Toolbar
Run Command Button
The Run Command button executes the command in the Command field. Click the Stop
Command button to stop the command being run. The Command Output window displays
the results of the command.
Stop Command Button
The Stop Command button stops the command being run from the Command field.
Command Field
The Command field allows you to enter a new command. Click the Run Command
button to execute the command. Click the Stop Command button to stop the command
being run. The Command Output window displays the results of the command.
Debug Toolbar
The Debug toolbar (Figure 12) allows you to perform debugger functions.
Figure 12. Debug Toolbar
UM004407-0104
2 Main Components
Z8 User Manual
59
Download Code
Reset Button
Stop Debugging Button
The Stop Debugging button exits you out of the debugger (leaves Debug mode).
To stop Debug mode, click the Break button.
Go Button
Run to Cursor Button
The Run to Cursor button makes the debugger run to the line containing the cursor. You
can only use this command for a line with a blue dot displayed to the left of the line.
Break Button
The Break button pauses the program execution and stops the debugging in progress.
Step Into Button
The Step Into button executes the code one statement at a time.
Step Over Button
The Step Over button steps to the next statement regardless of whether the current statement is a call to another function.
Step Out Button
The Step Out button executes the remaining lines in the current function and returns to
execute the next statement in the caller function.
Set Next Instruction Button
The Set Next Instruction button sets the next instruction at the current line.
UM004407-0104
2 Main Components
Z8 User Manual
60
a breakpoint in any line with a blue dot displayed to the left of the line.
Disable All Breakpoints Button
The Disable All Breakpoints button deactivates all breakpoints in all open files. To delete
breakpoints from your program, use the Remove All Breakpoints button.
The Remove All Breakpoints button deletes all breakpoints in all open files. To deactivate
breakpoints in your program, use the Disable All Breakpoints button.
Debug Windows Toolbar
The Debug Windows toolbar (Figure 14 or Figure 14, depending on if you are using the
Z8 emulator) allows you to display the Debug windows.
Figure 13. Debug Windows Toolbar
Figure 14. Debug Windows Toolbar (with the Z8 Emulator Connected)
Registers Window Button
The Registers Window button displays or hides the Registers window.
Special Function Registers Window Button
The Special Function Registers Window button displays or hides the Special Function
Registers window.
UM004407-0104
2 Main Components
Z8 User Manual
61
Clock Window Button
The Clock Window button displays or hides the Clock window.
Memory Window Button
The Memory Window button displays or hides the Memory window.
Watch Window Button
The Watch Window button displays or hides the Watch window.
Locals Window Button
The Locals Window button displays or hides the Locals window.
Call Stack Window Button
The Call Stack Window button displays or hides the Call Stack window.
Symbols Window Button
The Symbols Window button displays or hides the Symbols window.
Disassembly Window Button
The Disassembly Window button displays or hides the Disassembly window.
Trace Window Button
Note: The Trace Window button is only available if you are using the Z8 emulator.
Click the Trace Window button to display or hide the Trace window.
WINDOWS
The Z8 developer’s environment contains the following windows that allow you to see
various aspects of the tools while working with your project:
•
•
•
•
•
•
•
•
UM004407-0104
Project Workspace window (page 62)
Edit window (page 63)
Build Output window (page 65)
Debug Output window (page 65)
Find in Files Output window (page 65)
Find in Files 2 Output window (page 66)
Messages Output window (page 66)
Command Output window (page 67)
2 Main Components
Z8 User Manual
62
Project Workspace Window
The Project Workspace window (Figure 15) on the left side of the Z8 developer’s environment allows you to view your project files.
Figure 15. Project Workspace Window
To use the right-click menus in the Project Workspace window, highlight a file or folder
and then click on the right button of your mouse.
Depending on which file or folder is highlighted, the right-click menu allows you to do the
following:
•
•
•
•
•
•
UM004407-0104
Dock the Project Workspace window
Hide the Project Workspace window
Remove the highlighted file from the project
Build project files or external dependencies
Build or compile the highlighted file
Undock the Project Workspace window, allowing it to float in the Edit window
2 Main Components
Z8 User Manual
63
Edit Window
The Edit window (Figure 16) on the right side of the Z8 developer’s environment allows
you to edit the files in your project.
Figure 16. Edit Window
There are three right-click menus in the Edit window, depending on where you click.
When you right-click on the title bar of a file, the Dock right-click menu allows you to do
the following:
•
Dock or undock the file
You can dock the file to the top, left, bottom, or right of the Edit window.
•
Return the moved window to its original position (MDI Child)
You can select the position of the window: minimized, maximized, or restored (MDI
Child as).
When you right-click in a file, the right-click menu allows you to do the following
(depending on whether you are running in Debug mode):
•
•
•
•
•
•
•
UM004407-0104
Cut, copy, and paste text
Go to the Disassembly window
Show the program counter
Insert, edit, enable, disable, or remove breakpoints
Reset the debugger
Stop debugging
Start or continue running the program (Go)
2 Main Components
Z8 User Manual
64
•
•
•
•
•
Run to the cursor
Pause the debugging (Break)
Step into, over, or out of program instructions
Set the next instruction at the current line
Insert or remove bookmarks (see “Inserting Bookmarks” on page 64)
When you right-click outside of all files, the right-click menu allows you to do the following:
•
Show or hide the Output windows, Project Workspace window, status bar, File
toolbar, Build toolbar, Edit toolbar, Command Processor toolbar, Debug toolbar,
Debug Windows toolbar
•
•
Change the way files are displayed in the Edit window (Workbook Mode)
Customize the buttons and toolbars
Inserting Bookmarks
You can use the Edit window right-click menu to insert a bookmark.
1. Click on the line where you want the bookmark and click your right mouse button to
bring up the right-click menu (Figure 17).
Figure 17. Inserting a Bookmark
2. Select Insert Bookmark.
A cyan box represents the bookmark, as shown in Figure 18.
UM004407-0104
2 Main Components
Z8 User Manual
65
Figure 18. Bookmark Example
To remove a bookmark, click your cursor in a line with a bookmark, right-click to bring up
the right-click menu, and select Remove Bookmark.
Build Output Window
The Build Output window (Figure 19) holds all text messages generated by the tools,
including error and warning messages generated by the compiler, assembler, and linker.
The scroll bars are used to move through the messages. You can use the right-click menu
to copy or clear text in the window.
Figure 19. Build Output Window
Debug Output Window
The Debug Output window (Figure 20) holds all text messages generated by the debugger,
while you are in Debug mode. The scroll bars are used to move through the messages. You
can use the right-click menu to copy or clear text in the window.
Figure 20. Debug Output Window
UM004407-0104
2 Main Components
Z8 User Manual
66
Find in Files Output Window
The Find in Files Output window (Figure 21) holds the results of the Find in Files command (available from the Edit menu and the Edit toolbar). The scroll bars are used to
move through the messages. You can use the right-click menu to copy or clear text in the
window.
Figure 21. Find in Files Output Window
Find in Files 2 Output Window
The Find in Files 2 Output window (Figure 22) holds the results of the Find in Files command (available from the Edit menu and the Edit toolbar) when the Output to Pane 2 button is selected. The scroll bars are used to move through the messages. You can use the
right-click menu to copy or clear text in the window.
Figure 22. Find in Files 2 Output Window
Messages Output Window
The Messages Output window (Figure 23) holds informational messages intended for the
user. The scroll bars are used to move through messages. You can use the right-click menu
to copy or clear text in the window.
Figure 23. Messages Output Window
UM004407-0104
2 Main Components
Z8 User Manual
67
Command Output Window
The Command Output window (Figure 24) holds all text messages and output generated
by the IDE as it executes commands. The scroll bars are used to move through messages.
You can use the right-click menu to copy or clear text in the window.
Figure 24. Command Output Window
MENU BAR
The menu bar lists menu items that you use in the Z8 developer’s environment. Each
menu bar item, when selected, displays a list of selection items. If an option on a menu
item ends with an ellipsis (...), selecting the option displays a dialog box. The following
items are listed on the menu bar:
•
•
•
•
•
•
•
•
File
Displays the File menu (see page 67).
Edit
Displays the Edit menu (see page 75).
View
Displays the View menu (see page 80).
Project
Displays the Project menu (see page 81).
Build
Displays the Build menu (see page 112).
Tools
Displays the Tools menu (see page 119).
Window
Displays the Window menu (see page 134).
Help
Displays the Help menu (see page 135).
FILE MENU
The File menu enables you to perform basic commands in the developer’s environment:
•
•
•
•
•
UM004407-0104
New File (see page 68)
Open File (see page 68)
Close File (see page 69)
New Project (see page 69)
Open Project (see page 71)
2 Main Components
Z8 User Manual
68
•
•
•
•
•
•
•
•
•
•
•
Save Project (see page 72)
Close Project (see page 72)
Save (see page 72)
Save As (see page 73)
Save All (see page 73)
Print (see page 73)
Print Preview (see page 73)
Print Setup (see page 75)
Recent Files (see page 75)
Recent Projects (see page 75)
Exit (see page 75)
New File
Select New File from the File menu to create a new file in the Edit window.
Open File
Select Open File from the File menu to display the Open dialog box (Figure 25), which
allows you to open the files for your project.
Figure 25. Open Dialog Box
Note: To delete a file from your project, use the Open Project dialog box. Highlight the file and
press the Delete key. Answer the prompt accordingly.
UM004407-0104
2 Main Components
Z8 User Manual
69
Close File
Select Close File from the File menu to close the selected file.
New Project
To create a new project, do the following:
1. Select New Project from the File menu.
The New Project dialog box is displayed as shown in Figure 26.
Figure 26. New Project Dialog Box
2. From the New Project dialog box, click on the Browse button (
directory where you want to save your project.
) to navigate to the
3. In the File Name field, type the name of your project.
You do not have to type the extension .pro. The extension is added automatically.
4. Click Select to return to the New Project dialog box.
5. In the CPU Family drop-down list box, select a product family.
6. In the CPU drop-down list box, select the appropriate CPU.
7. In the Project Type drop-down list box, select Executable to build an application or
select Static Library to build a static library.
The default is Executable, which creates an IEEE 695 executable format (.lod). For
more information, see “Linker Tab” on page 98.
8. Click Continue.
The Configure New Project dialog box is displayed, as shown in Figure 27.
UM004407-0104
2 Main Components
Z8 User Manual
70
Figure 27. Configure New Project Dialog Box—Step 1
9. Select whether your project is linked to the C run-time library, floating-point library,
or neither; select whether your project is linked to the standard startup module; select
static or dynamic frames; select a small or large memory model; and click Next.
Static frames hold arguments and local variables in static locations that are dictated by
the linker. A separate static memory is allocated for automatic variables of a function.
The linker generates a call graph of the functions and reuses this memory for other
functions whenever there is no overlap. Static frames are overlaid by the linker based
on the program’s call graph; they can be overridden with the reentrant keyword.
Passing arguments in static frames is done by placing the arguments into static
locations of memory. Each argument is given a unique public name derived from the
name of the function being called.
The only restrictions in static frames are that functions are not reentrant (that is, direct
and indirect recursion are not supported), and indirect function calls are not supported.
If your program does not need recursion and reentrancy, static frames are usually more
efficient than dynamic frames.
Dynamic frames hold arguments and local variables on the run-time stack, allow
recursion, and allow reentrancy. Dynamic frames are the usual way of storing
information about an instance of a function call. Passing argument in dynamic frames
is done by pushing the arguments on the stack in reverse (right to left) order.
UM004407-0104
2 Main Components
Z8 User Manual
71
Note: For reasonably small, efficient, and flexible code, select Small from the Memory Model
drop-down list box (in the General category of the C tab) and select Dynamic Frames when
building your project.
The small memory model is useful for small programs or programs that require very efficient code. Code can be any size. The small memory model uses the general-purpose registers 0–FFH; the global and local variables and the stack need to fit within 256 bytes
(20H-FFH). In the small model, all data are stored in RData in the range 20H to FFH
(including static call frames), except for objects declared using the rom or far storage
class (which are stored in program ROM or EData, respectively). Dynamic call frames are
allocated in RData.The global variables can be manually placed into the address range
100H–EFFH using the far keyword.
The large memory model is less efficient than the small model. The large model is best
suited for programs that need a large amount of data storage and do not have strict timing
requirements. In the large model, all data are stored in EData in the range 100H to the top
of RAM (including static call frames), except for objects declared using the rom or near
storage class (which are stored in program ROM or RData, respectively). Dynamic call
frames are allocated in EData. The large memory model uses the whole internal register
memory with a limit of EFFH for devices with 4K; this allows the global and local variables and the stack to fit within the range of 000H–EFFH. Global variables that need to be
accessed efficiently can be located in the range 20H–FFH using the near keyword.
Note: For reasonably small, efficient, and flexible code, select Small for the memory model and
select the Dynamic Frames button.
10. Enter the memory ranges appropriate for the target CPU and click Finish.
Open Project
To open an existing project, use the following procedure:
1. Select Open Project from the File menu.
The Open Project dialog box is displayed, as shown in Figure 28.
UM004407-0104
2 Main Components
Z8 User Manual
72
Figure 28. Open Project Dialog Box
2. Use the Look In drop-down list box to navigate to the appropriate directory where
your project is located.
3. Click Open to open to open your project.
Notes: To quickly open a project you were working in recently, see “Recent Projects” on page 75.
To delete a project file, use the Open Project dialog box. Highlight the file and press the
Delete key. Answer the prompt accordingly.
Save Project
Select Save Project from the File menu to save the currently active project. Saving your
project creates a <name>.wsp file where <name> is your project file name. This .wsp file
saves all the configurations for your project and for the Z8 developer’s environment.
Note: The .wsp file resides in the same directory as your project file. If you delete this file, you
lose the configurations for your project.
Close Project
Select Close Project from the File menu to close the currently active project.
Save
Select Save from the File menu to save the selected file.
UM004407-0104
2 Main Components
Z8 User Manual
73
Save As
To save a selected file with a new name, perform the following steps:
1. Select Save As from the File menu.
The Save As dialog box is displayed, as shown in Figure 29.
Figure 29. Save As Dialog Box
2. Use the Save In drop-down list box to navigate to the appropriate folder.
3. Enter the new file name in the File Name field.
4. Use the Save as Type drop-down list box to select the file type.
5. Click Save.
A copy of the file is saved with the name you entered.
Save All
Select Save All from the File menu to save all of the files.
Print
Select Print from the File menu to print the file you have active in the Edit window.
Print Preview
Select Print Preview from the File menu to display the file you want to print in Preview
mode in a new window.
1. In the Edit window, highlight the file you want to show a Print Preview.
UM004407-0104
2 Main Components
Z8 User Manual
74
2. From the File menu, select Print Preview.
The file is shown in Print Preview in a new window. As shown in Figure 30, SIO.C is
in Print Preview mode.
Figure 30. Print Preview Window
3. To print the file, click Print.
To cancel the print preview, click Close. The file returns to its edit mode in the Edit
window.
UM004407-0104
2 Main Components
Z8 User Manual
75
Print Setup
Select Print Setup from the File menu to display the Print Setup dialog box, which allows
you to determine the printer’s setup before you print the file.
Recent Files
Select Recent Files from the File menu to quickly open a previously opened file.
Recent Projects
Select Recent Projects from the File menu to quickly open a previously opened project.
Exit
Select Exit from the File menu to exit the application. Your project is automatically saved
before the Z8 developer’s environment closes.
EDIT MENU
The Edit menu lets you perform basic editing commands and contains the following
options:
•
•
•
•
•
•
•
•
•
•
•
•
•
Undo
Redo (see page 76)
Cut (see page 76)
Copy (see page 76)
Paste (see page 76)
Delete (see page 76)
Go to Line (see page 76)
Find (see page 76)
Find in Files (see page 77)
Replace (see page 78)
Breakpoints (see page 79)
Event System (see page 80)
Clear Trace (see page 80)
Undo
Select Undo from the Edit menu to undo the last command or action you performed.
UM004407-0104
2 Main Components
Z8 User Manual
76
Redo
Select Redo from the Edit menu to redo the last command or action you performed.
Cut
Select Cut from the Edit menu to delete selected text from a file and put it on the clipboard.
Copy
Select Copy from the Edit menu to copy selected text from a file and put it on the clipboard.
Paste
Select Paste from the Edit menu to paste the current contents of the clipboard into a file.
Delete
Select Delete from the Edit menu to delete selected text from a file.
Go to Line
Select Go to Line from the Edit menu to display the Go to Line Number dialog box, as
shown in Figure 31.
Figure 31. Go to Line Number Dialog Box
Enter the line number in the edit field and click Go To to advance the program counter to
the selected line of code.
Find
To find text, use the following procedure:
1. Select Find from the Edit menu.
The Find dialog box is displayed as shown in Figure 32.
UM004407-0104
2 Main Components
Z8 User Manual
77
Figure 32. Find Dialog Box
2. Enter the text to search for in the Find What field or select a recent entry from the Find
What drop-down list box. (If you select text in a source file before displaying the
Replace dialog box, the text is displayed in the Find What field.)
3. Select the Match Case button if you want the search to be case sensitive
4. Select the Regular Expression button if you want to use regular expressions.
5. Select the Wrap Around Search button to have the whole file searched.
6. Select the direction of the search with the Up or Down button.
7. Click Find Next to jump to the next occurrence of the search text or click Mark All to
display a cyan box next to each line containing the search text.
Note: After clicking Find Next, the dialog box closes. You can press the F3 key to find the next
occurrence of the search term without displaying the Find dialog box again.
Find in Files
To find text in multiple files, use the following procedure:
1. Select Find in Files from the Edit menu.
The Find in Files dialog box is displayed as shown in Figure 33.
Figure 33. Find in Files Dialog Box
UM004407-0104
2 Main Components
Z8 User Manual
78
2.
Enter the text to search for in the Find field or select a recent entry from the Find
drop-down list box.
3. Select the file type to search from the In File Types drop-down list box.
4. Use the Browse button ( ) or the In Folder drop-down list box to select where the
files are located that you want to search.
5. Select the Match Whole Word Only button if you want to only find words.
6. Select the Match Case button if you wan the search to be case sensitive.
7. Select the Look in Subfolders button if you want to search within subfolders.
8. Select the Output to Pane 2 button if you want the search results displayed in the Find
in files 2 Output window. If this button is not selected, the search results are displayed
in the Find in Files Output window.
9. Click Find to start the search.
Replace
To find and replace text in an active file, use the following procedure:
1. Select Replace from the Edit menu.
The Replace dialog box is displayed as shown in Figure 34.
Figure 34. Replace Dialog Box
2. Enter the text to search for in the Find What field or select a recent entry from the Find
What drop-down list box. (If you select text in a source file before displaying the
Replace dialog box, the text is displayed in the Find What field.)
3. Enter the replacement text in the Replace With field or select a recent entry from the
Replace With drop-down list box.
4. Select the Match Case button if you want the search to be case sensitive
5. Select the Regular Expression button if you want to use regular expressions.
UM004407-0104
2 Main Components
Z8 User Manual
79
6. Select the Wrap Around Search button to have the whole file searched.
7. Select the direction of the search with the Up or Down button.
8. Click Find Next to jump to the next occurrence of the search text, click Replace to
replace the highlighted text, or click Replace All to automatically replace all instances
of the search text.
Breakpoints
Select Breakpoints from the Edit menu to view, go to, or remove breakpoints. You can
access the dialog box (see Figure 35) during Debug mode and Release mode.
Figure 35. Breakpoints Dialog Box
Go to Code
To move the cursor to a particular breakpoint you have set in a file, highlight the breakpoint in the Breakpoints dialog box and click Go to Code.
Enable All
To make all listed breakpoints active, click Enable All.
Disable All
To make all listed breakpoints inactive, click Disable All.
Remove
To delete a particular breakpoint, highlight the breakpoint in the Breakpoints dialog box
and click Remove.
Remove All
To delete all of the listed breakpoints, click Remove All.
UM004407-0104
2 Main Components
Z8 User Manual
80
Note: For more information on breakpoints, see “Using Breakpoints” on page 160.
Event System
Note: The Event System command is only available if you are using the Z8 emulator.
Select Event System from the Edit menu to enable or disable the use of the events specified in the Trace and Event System dialog box (see “Trace and Event System” on
page 119). When the event system is enabled, a check mark is displayed to the left of the
command in the Edit menu.
Clear Trace
Note: The Clear Trace command is only available if you are using the Z8 emulator.
Select Clear Trace from the Edit menu to delete the trace data when ZDS II is in Debug
mode.
VIEW MENU
The View menu allows you to select the windows you want on the Z8 developer’s environment.
The View menu contains these options:
•
•
•
•
Debug Windows
Workspace
Output (see page 81)
Status Bar (see page 81)
Debug Windows
When you are in Debug mode (running the debugger), you can select any of the eight
Debug windows. From the View menu, select Debug Windows and then the appropriate
Debug window.
The Debug Windows submenu contains the following:
•
•
•
•
•
UM004407-0104
Registers (see page 143)
Special Function Registers (see page 143)
Clock (see page 144)
Memory (see page 145)
Watch (see page 150)
2 Main Components
Z8 User Manual
81
•
•
•
•
Locals (see page 152)
Call Stack (see page 153)
Symbols (see page 153)
Disassembly (see page 154)
Note: The Trace window is only available if you are using the Z8 emulator.
•
Trace (see page 155)
Note: For more information on the Debug windows, see Chapter 3, “Debugging,” starting on
page 137.
Workspace
Select Workspace from the View menu if you want to have the Project Workspace window displayed.
Output
Select Output from the View menu if you want to have the Build Output window displayed.
Status Bar
Select Status Bar from the View menu if you want to have the status bar, beneath the
Build Output window, displayed.
PROJECT MENU
The Project menu allows you to add files to your project, set configurations for your
project, and export a make file.
The Project menu contains the following options:
•
•
•
•
Add Files
Remove Selected File(s) (see page 82)
Settings (see page 82)
Export Makefile (see page 112)
Add Files
To add files to your project, use the following procedure:
1. From the Project menu, select Add Files.
2. In the Add Files to Project dialog box (Figure 36), navigate to the appropriate
directory where the files you want to add are saved.
UM004407-0104
2 Main Components
Z8 User Manual
82
Figure 36. Add Files to Project Dialog Box
3. Click on the file you want to add or highlight multiple files by clicking on each file
while holding down the Shift or Ctrl key.
4. Click Add to add these files to your project.
Remove Selected File(s)
Select Remove Selected File(s) from the Project menu to delete highlighted files in the
Project Workspace window.
Settings
Select Settings from the Project menu to display the Project Settings dialog box, which
allows you to change your active configuration as well as set up your project.
The Project Settings dialog box has the following six tabs you must go through to set up
the project settings:
•
•
•
•
•
•
General tab (see page 83)
C (Compiler) tab (see page 84)
Assembler tab (see page 96)
Linker tab (see page 98)
Target tab (see page 106)
Debugger tab (see page 108)
Within the C (Compiler) and Linker tabs are categories that allow you to set up subsettings
on that specific tab’s category. The categories for the C (Compiler) tab are General, Code
UM004407-0104
2 Main Components
Z8 User Manual
83
Generation, Optimizations, Listing Files, and Preprocessor. The categories for the Linker
tab are General, Input, and Output.
Note: If you change project settings that affect the build, the following message is displayed:
“The project settings have changed since the last build. Would you
like to rebuild the affected files?” Click Yes to save and then rebuild the
project.
General Tab
From the Project Settings dialog box, select the General tab.
The options on the General tab (Figure 37) are described in this section.
Figure 37. Project Settings Dialog Box–General Tab
CPU Family
The CPU Family drop-down list box allows you to select the appropriate Z8 family.
CPU
The CPU drop-down list box defines which CPU you want to define for the Z8
target.
UM004407-0104
2 Main Components
Z8 User Manual
84
To change the CPU for your project, select the appropriate CPU in the CPU drop-down list
box.
Note: Selecting a CPU does not automatically select include files for your C or assembly source
code. Include files must be manually included in your code. Selecting a new CPU
automatically updates the ROM range for that CPU.
Output Files Directory
The Output Files Directory field contains the path where your output files are created and
stored. The following is the default directory:
ZILOGINSTALL\ZDSII_product_version\samples\
For more information for output files for the linker, see “Linker Commands” on page 310.
C (Compiler) Tab
From the Project Settings dialog box, select the C tab. The contents of the C (Compiler)
tab determine which options are to be applied to the compiled files.
The options on the C tab of the Project Settings dialog box are described in this section.
General Category
Figure 38 shows the General category of the C tab.
UM004407-0104
2 Main Components
Z8 User Manual
85
Figure 38. Project Settings Dialog Box (C Tab, General Category)
Debug Information
The Debug Information drop-down list box lets you generate information for debugging
by selecting Generate Debug Info. If you do not want to generate Debug information,
select None.
Optimizations
The Optimizations drop-down list box allows you to select the optimizations you want.
The choices are Disable, Maximize Speed, Minimize Size, and Custom.
The Z8 developer’s environment ANSI C-Compiler comes with a powerful optimizer that
makes your programs smaller and/or faster. If you leave all optimizer options set at the
defaults, you get the best possible code while minimally interfering with debugging.
Watch Compilation Process
The Watch Compilation Process drop-down list box tells the compiler to display messages
during each pass of the compiler as it is running, along with the name of each function as
it is being processed, in the Build Output window. Select Verbose for long compilation
processes so that you know how the compiler is progressing. To show minimal messages
during compiling, select Quiet or Default.
UM004407-0104
2 Main Components
Z8 User Manual
86
Max Errors
The Max Errors field allows you to define the maximum number of errors encountered
before the compiler stops processing your source file. The default is 50.
Use Floating Point Library
The Use Floating Point Library check box tells the compiler whether floating-point operations are used. This option must be selected if you are using any floating-point operations.
Caution: This option is not selected automatically; therefore, if you use floating-point operations,
you must set it. Deselecting this option might significantly reduce code size and compile
time. However, if you use floating-point operations without setting this option, unexpected results occur.
Memory Model
The Memory Model drop-down list box tells the compiler to which memory model is
going to be used. Select Small for a small memory model or select Large for a large memory model.
The small memory model is useful for small programs or programs that require very efficient code. Code can be any size. The small memory model uses the general-purpose registers 0–FFH; the global and local variables and the stack need to fit within 256 bytes
(20H-FFH). In the small model, all data are stored in RData in the range 20H to FFH
(including static call frames), except for objects declared using the rom or far storage
class (which are stored in program ROM or EData, respectively). Dynamic call frames are
allocated in RData.The global variables can be manually placed into the address range
100H–EFFH using the far keyword.
The large memory model is less efficient than the small model. The large model is best
suited for programs that need a large amount of data storage and do not have strict timing
requirements. In the large model, all data are stored in EData in the range 100H to the top
of RAM (including static call frames), except for objects declared using the rom or near
storage class (which are stored in program ROM or RData, respectively). Dynamic call
frames are allocated in EData. The large memory model uses the whole internal register
memory with a limit of EFFH for devices with 4K; this allows the global and local variables and the stack to fit within the range of 000H–EFFH. Global variables that need to be
accessed efficiently can be located in the range 20H–FFH using the near keyword.
drop-down list box and select Dynamic Frames (in the Code Generation category) when
Code Generation Category
Figure 39 shows the Code Generation category of the C tab.
UM004407-0104
2 Main Components
Z8 User Manual
87
Figure 39. Project Settings Dialog Box (C Tab, Code Generation Category)
Debug Information
The Debug Information drop-down list box lets you generate information for debugging
by selecting Generate Debug Info. If you do not want to generate Debug information,
select None.
Const Variable Placement
The Const Variable Placement area lets you choose where const variables are placed. You
can select RAM or ROM; RAM is the default.
Alias Checking
The Alias Checking check box tells the compiler not to perform some optimizations
because more than one pointer to the same object might exist. Deselecting this option
might result in more efficient code. However, if you access a variable in more than one
way, the compiler might generate incorrect code.
Note: Aliasing seldom appears in most C programs. The #pragma alias and #pragma
noalias ANSI preprocessor directives can be placed in your C source files to control the
alias checking at the function level.
UM004407-0104
2 Main Components
Z8 User Manual
88
ANSI Promotions
When selected, the ANSI Promotions check box tells the compiler to perform the default
integral promotions as defined by ANSI standard. The default is checked. Default integral
promotions are promotions that occur automatically when a smaller base typed variable is
used in an expression with larger base typed variables, for example, when mixing chars
and ints in an expression, the compiler type casts the chars into ints. There is no loss of
precision when calculating an expression.
Often in embedded applications, you want greater control over the code being generated.
By deselecting this option, you can gain more control over how the compiler generates
code. By deselecting this option, the compiler generates smaller, faster code because
implicit conversions from chars to ints to longs are no longer inserted. However, your
code might not execute properly if you inadvertently rely on the ANSI promotions. The
#pragma promote and #pragma nopromote preprocessor directives can be inserted
into your source file for function-level control over the ANSI promotions.
Select the ANSI Promotions check box when you need a local stack frame that is longer
than 127 bytes.
Strict ANSI Conformance
When selected, the Strict ANSI Conformance check box tells the compiler to look for
strict conformance to the ANSI standard. The default is checked. The use of any obsolete
feature, such as old-style function argument syntax and missing function prototypes,
causes the compiler to generate warning messages.
Note: The ZDS II compiler is more sensitive to ANSI standards than the ZDS compiler. While it
is preferred that nonstandard code is updated, in cases where this is not an option, deselect
the Strict ANSI Conformance check box.
Frames
Select Static Frames for static frames or select Dynamic Frames for dynamic frames.
•
Static frames hold arguments and local variables in static locations that are dictated by
the linker. A separate static memory is allocated for automatic variables of a function.
The linker generates a call graph of the functions and reuses this memory for other
functions whenever there is no overlap. Static frames are overlaid by the linker based
on the program’s call graph; they can be overridden with the reentrant keyword.
Passing arguments in static frames is done by placing the arguments into static
locations of memory. Each argument is given a unique public name derived from the
name of the function being called.
The only restrictions in static frames are that functions are not reentrant (that is, direct
and indirect recursion are not supported), and indirect function calls are not supported.
If your program does not need recursion and reentrancy, static frames are usually more
efficient than dynamic frames.
UM004407-0104
2 Main Components
Z8 User Manual
89
•
Dynamic frames hold arguments and local variables on the run-time stack, allow
recursion, and allow reentrancy. Dynamic frames are the usual way of storing
information about an instance of a function call. Passing argument in dynamic frames
is done by pushing the arguments on the stack in reverse (right to left) order.
drop-down list box (in the General category of the C tab) and select Dynamic Frames when
Use Intrinsics
When selected, the Use Intrinsics check box tells the compiler to generate in-line code
functions whenever possible. Intrinsics are simple functions like strcpy and memset that
can be generated in-line for more efficient or generic code. However, the code size might
increase if you use the intrinsics function frequently. The default is checked.
Use Register Variables
The Use Register Variables check box tells the compiler to use registers to store variables
in when it can for local variables and passed parameters, making the resulting code
smaller and faster. If you do not check this box, the compiler stores all local variables and
passed parameters in the static frames of functions. Which option to select depends solely
on the application.
Note: If you select this option, unexpected values are displayed in the Watch window and Locals
window because a specific register only holds the value of the specific register while the
code requires it.
Optimizations Category
The ANSI C-Compiler comes with a powerful optimizer that makes your programs
smaller and/or faster. If you leave all Optimizer options set at their defaults, you get the
best possible code while minimally interfering with debugging. However, Z8
developer’s environment gives you the ability to selectively disable most optimizations
using the Project Settings dialog box (C tab, Optimizations category).
Note: Some optimizations are performed regardless of optimizer settings because disabling them
causes an exponential expansion in code size. Changing any option and clicking OK
causes a message to display asking you if you want to “dirty” the C source files. If you
click Yes, all C files are recompiled when you run the make utility.
The optimizer independently performs local and global optimizations that you select in the
Type drop-down list box. Local optimizations are performed on a basic block basis. That
is, their scope is very limited, confined to straight-line code with no jumps or loops. Global optimizations are performed at the function level and work across jumps and loops.
Figure 40 shows the Optimizations category of the C tab.
UM004407-0104
2 Main Components
Z8 User Manual
90
Figure 40. Project Settings Dialog Box (C Tab, Optimizations Category)
Local Optimizations
Local optimizations are performed on a basic block basis. A basic block is a straight line
code that can only be entered at the top and exited at the bottom. Local optimizations
improve your program by cleaning up inefficiencies induced by C, compiler code generation, or poor coding practices. Because these inefficiencies are very common, local optimizations can improve your code's performance by up to 50%.
Normally, set all local optimizations because having them set causes the compiler to generate more efficient code and has negligible affects on debugging capabilities. However, if
the generated code contains errors, deselecting one of these optimizations might give you
a workaround.
For local optimizations, do the following:
1. Select Local from the Type drop-down list box.
2. In the Optimizations drop-down list box, select Maximize Speed or Minimize Size
for preset optimization configurations; select Disable for no optimizations; or select
UM004407-0104
2 Main Components
Z8 User Manual
91
Custom to choose which optimizations are performed. A description of each of the
optimizations follows:
– The Common Subexpressions check box controls the execution of common
subexpression elimination. Common subexpressions are expressions that occur
more than once in your program. As long as there is an efficient location to store
the expression’s value, subsequent occurrences of the expression need not be
recalculated. Instead, the result of the first occurrence of the expression is used.
For example:
a = b + c;
d = b + c;
–
is converted to
a = b + c;
d = a;
The Constant Folding check box determines whether constant folding
optimization is performed. Constant folding is performed when an expression
contains constant values that can be folded into a single constant without changing
the value of the expression. For example:
c = 10 * 10;
is converted to
c = 100;
if statements are another example of constant folding. For example:
#define X 10
if (X > 10)
++x;
else
--x;
–
–
UM004407-0104
--x;
The Copy Propagation check box determines whether the copy propagation
optimization is performed. Copy propagation is a special case of common
subexpression elimination where constant values can be substituted for arbitrarily
complex expressions. For example:
a = 10;
b = 10;
c = a * b;
–
is converted to
is converted to
a = 10;
b = 10;
c = 10 * 10;
The Peephole Optimizations check box determines whether peephole
optimizations are performed. Peephole optimizations are target-specific
optimizations that take into account the nuances of the Z8’s instruction set. These
optimizations convert short sequences of instructions (not necessarily contiguous)
into shorter, more efficient sequences.
For the Optimize For buttons, select Speed or Size.
2 Main Components
Z8 User Manual
92
Global Optimizations
Global optimizations are performed at the function, rather than the basic block, level. Global optimizations can significantly increase code efficiency in some cases. However, global optimizations rarely improve code efficiency by more than 10%.
Some global optimizations, especially common subexpression elimination, might make
debugging difficult because code is moved around in seemingly random ways.
Not all global optimizations are implemented for all target processors.
For global optimizations, do the following:
1. Select Global from the Type drop-down list box.
2. In the Optimizations drop-down list box, select Maximize Speed or Minimize Size
for preset optimization configurations; select Disable for no optimizations; or select
Custom to choose which optimizations are performed. A description of each of the
optimizations follows:
– The Loop Optimizations check box determines whether optimizations are
performed on loops in your program. Loop optimizations can improve
performance by rearranging code so that it is executed inside the loop only if
absolutely necessary. Also, the location of the comparison for loop termination
might be moved in order to minimize the number of jumps necessary to
implement the loop.
– The Common Subexpressions check box determines whether global common
subexpressions are eliminated. Global common subexpressions are similar to
local common subexpressions but are performed across basic blocks. For
example:
a = b + c;
if (x)
d = b + c;
else
e = b + c;
–
–
UM004407-0104
is converted to
a = b + c;
if (x)
d = a;
else
e = a;
The Span-Dependent Instructions check box determines whether span-dependent
instructions are optimized. Span-dependent instructions are those that can have
more than one form based on the distance of the instruction from its destination.
Relative jumps and calls are the primary span-dependent instructions. The spandependent instruction optimization modifies all such instructions to be of the
smallest form possible.
The Branch Optimizations check box determines whether branch optimizations
are performed. Branch optimizations reduce the number of branches necessary to
implement your flow of control. Typically, nested if-else statements and switch
statements cause unconditional branches to other unconditional branches. The
branch optimization removes these redundant branches.
2 Main Components
Z8 User Manual
93
–
The Constant Folding check box determines whether the global constant folding
optimization is performed. Global constant folding is similar to local constant
folding but is performed across basic blocks. For example:
a = 10;
b = 20;
if (x)
c = a + b;
–
a = 10;
b = 20;
if (x)
c = 30;
The Copy Propagation check box determines whether the global copy propagation
optimization is performed. Global copy propagation is similar to local copy
propagation, but is performed across basic blocks. For example:
a = 10;
b = 20;
if (x)
c = a + b;
–
is converted to
is converted to
a = 10;
b = 20;
if (x)
c = 10 + 20;
For the Optimize For buttons, select Speed or Size.
Listing Files Category
Figure 41 shows the Listing Files category of the C tab.
Figure 41. Project Settings Dialog Box (C Tab, Listing Files Category)
UM004407-0104
2 Main Components
Z8 User Manual
94
Generate Compiler Listing File (.lis)
When selected, the Generate Compiler Listing File (.lis) check box tells the compiler to
create a listing file (with the .lis file extension). All source lines are duplicated in this
file, as are any errors encountered by the compiler.
List Include Files in .lis
When selected, the List Include Files in .lis check box tells the compiler whether the contents of all files included using the #include preprocessor directive must be duplicated in
the compiler listing file. This can be helpful if there are errors in included files.
Expand Macros on Error
When selected, the Expand Macros on Error check box tells the compiler to expand all C
macros on C source lines written to the message window when an error occurs. This
option helps in detecting macro expansion errors in your C code.
Generate Assembly Source (.src)
When selected, the Generate Assembly Source (.src) check box tells the compiler to create
the assembly source code.
Interleave Source and Assembly
When selected, the Interleave Source and Assembly check box tells the compiler to
include the associated C source code in the generated assembly source files.
When selected, the Generate Listing File (.lst) check box tells the compiler whether to
keep the assembly source file after compiling your code. This can be useful when you
want to inspect or modify the assembly code generated by the compiler. Deselecting this
option causes the compiler to remove the .lst file after it has been assembled.
Preprocessor Category
Figure 42 shows the Preprocessor category of the C tab.
UM004407-0104
2 Main Components
Z8 User Manual
95
Figure 42. Project Settings Dialog Box (C Tab, Preprocessor Category)
Preprocessor Definitions
The Preprocessor Definitions field is equivalent to placing #define preprocessor directives before any lines of code in your program. It is useful for conditionally compiling
code. Do not put a space between the symbol\name and equal sign; however, multiple
symbols can be defined and must be separated by commas.
Standard Include Path
The Standard field allows you to specify the series of paths for the compiler to use when
searching for standard include files. Standard include files are those included with the
#include <file.h> preprocessor directive. If more than one path is used, the paths are
separated by semicolons (;). The compiler first checks the current directory, then the paths
in the Standard field. The default standard includes are located in the
ZILOGINSTALL\include\ directory, where ZILOGINSTALL is the ZDS II installation
directory (which is assumed to be C:\Program Files\ZiLOG).
User Include Path
The User field allows you to specify the series of paths for the compiler to use when
searching for user include files. User include files are those included with the #include
UM004407-0104
2 Main Components
Z8 User Manual
96
"file.h" in the compiler. If more than one path is used, the paths are separated by semicolons (;). The compiler first checks the current directory, then the paths in the User field.
Assembler Tab
In the Project Settings dialog box, select the Assembler tab. The assembler uses the contents of the Assembler tab to determine which options are to be applied to the files assembled.
The options on the Assembler tab (Figure 43) are described in this section.
Figure 43. Project Settings Dialog Box–Assembler Tab
Debug Information
When selected, the Debug Information check box tells the assembler to place debugging
information into relocatable object modules. The default is checked.
Jump Optimization
When selected, the Jump Optimization check box allows the assembler to replace relative
jump instructions (JR and DJNZ) with absolute jump instructions when the target label is
either
•
UM004407-0104
outside of the +127 to –128 range
2 Main Components
Z8 User Manual
97
For example, when the target is out of range, the assembler changes
DJNZ r0, lab
to
DJNZ r0, lab1
JR lab2
lab1:JP lab
lab2:
•
external to the assembly file
When the target label is external to the assembly file, the assembler always assumes
that the target address is out of range. However, if you do not want the assembler to
make these replacements, deselect Jump Optimization.
The default is checked.
Generate Object
When selected, the Generate Object check box tells the assembler to generate relocatable
object files. The default is checked.
Ignore Case
When selected, the Ignore Case check box tells the assembler to convert all symbols to
uppercase.
When selected, the Generate Listing File check box tells the assembler to create an assembly listing file. The default is checked.
Expand Macros
When selected, the Expand Macros check box tells the assembler to expand macros in the
assembly listing file.
Page Length
When the assembler generates the listing file, the Page Length field sets the maximum
number of lines between page breaks. The default is 56.
Page Width
When the assembler generates the listing file, the Page Width field sets the maximum
number of characters on a line. The default is 80; the maximum width is 132.
Display Errors/Warnings Only
When selected, the Display Errors/Warnings Only check box tells the assembler if it can
display messages other than errors and warnings in the Build Output window.
UM004407-0104
2 Main Components
Z8 User Manual
98
Display Warnings
When selected, the Display Warnings check box tells the assembler to display warnings in
the Build Output window.
Include Path
The Include Path field allows you to specify the series of paths for the assembler to use
when searching for include files. The assembler first checks the current directory, then the
paths in the Include Path field.
Defines
The Defines field is equivalent to placing <symbol> EQU <value> in your assembly source
code. It is useful for conditionally built code. Each defined symbol must have a corresponding value (<name>=<value>). Multiple symbols can be defined and must be separated by commas.
Linker Tab
In the Project Settings dialog box, select the Linker tab.
The options on the Linker tab are described in this section.
General Category
Figure 44 shows the General category of the Linker tab.
UM004407-0104
2 Main Components
Z8 User Manual
99
Figure 44. Project Settings Dialog Box (Linker Tab, General Category)
Output File Name
You can change the name of your executable in the Output File Name field. After your
program is linked, the appropriate extension is added.
Use the Object/Library Modules field to list object files and libraries that you want linked
into the project executable. Separate modules with a comma.
Generate Warnings
This check box determines whether the linker generates warning messages. If you do not
select this option, the linker does not display warning messages in the message window.
Generate Debug Info
This check box determines whether the linker places debugging information into your executable files. This option is applicable only if you select the executable format IEEE 695.
Note: The Generate Debug Information options on the C tab must be checked before this check
box has any effect.
UM004407-0104
2 Main Components
Z8 User Manual
100
Generate Map File
This check box determines whether the linker generates a link map file each time it is run.
The link map file is named your project’s name with the .map extension. See page 316
and page 334.
Note: The link map is an important place to look for memory restriction or layout problems.
Ignore Case
This check box determines whether the linker ignores the case of public symbols.
Symbol Cross-Reference
This check box determines whether the linker generates symbol cross-references in the
map file. If disabled, this option speeds up your linking process.
Perform Re-List
This check box determines whether the linker includes a “relist” target in the generated
make file and whether the build target uses it. This feature is not checked by default.
Note: If the Generate Assembly Source (.src) check box on the C tab (Listing Files
category) is not checked, only the assembly files are relisted.
Input Category
Figure 45 shows the Input category of the Linker tab.
UM004407-0104
2 Main Components
Z8 User Manual
101
Figure 45. Project Settings Dialog Box (Linker Tab, Input Category)
Use the Object/Library Modules field to list object files and libraries that you want linked
into the project executable. Separate modules with a comma.
Startup Module
All C programs require some initialization before the main function is called. This is typically done in a startup module. In the Startup Module area, select one of the three buttons:
•
Select the Included in Project button if the startup module is already included in your
project.
•
Select the Standard button to link the startup module supplied with ZDS II into the
project executable.
•
Select the Custom button to define the file name and path of a custom startup module.
Caution: If you select the Included in Project button or the Custom button and use the startup
source or object provided with the tools (startup.asm or startup.obj), building the
UM004407-0104
2 Main Components
Z8 User Manual
102
project results in linker warnings. Follow these steps to add the correct linker directives
to initialize variables in your project:
1. Open your project.
3. In the Input category of the Linker tab, select the Standard button and click OK.
4. Click Yes to the warning message: "The project settings have changed
since the last build. Would you like to rebuild the affected
files?"
5. Open the generated link control file (project_name.lnk) and copy everything from
ORDER DATA,TEXT to the next blank line.
The link control file is generated even if the build is not successful.
6. Paste the directives into the Additional Linker Directives dialog box (Figure 46).
7. Click OK to return to the Project Settings dialog box.
8. Click OK to save your settings.
Click Yes to the warning message: "The project settings have changed
since the last build. Would you like to rebuild the affected
files?"
Link Control File
The linker is automatically invoked when you click Build or Rebuild All on the Build
toolbar to your project. The linker executes controls found in a predetermined link control
file. In the Link Control File area, select one of the three buttons:
•
Select the Create New button if you want ZDS II to automatically generate a link
control file.
When you select the Create New button, the Add Directives button is enabled. Click
Add Directives to display the Additional Linker Directives dialog box (Figure 46).
UM004407-0104
2 Main Components
Z8 User Manual
103
Figure 46. Additional Linker Directives Dialog Box
The only time you need to add directives is if you have, for example, a module that
must be loaded at a specific address or if you want to change the order sections are
loaded into memory. For more information about the linker, see Chapter 6, “Using the
Linker/Locator.”
If you are using IPWorks, IPWorks supplies a linker command file, so you need to
select the Use Existing button in the Input category of the Linker tab to prevent ZDS II
from creating a new linker command file.
After you finish adding directives, click OK.
•
Select the Custom button to define the file name and path of a custom link control file.
When you select the Custom button, the Edit Custom button is enabled. Click Edit
Custom to display the Custom Link Control File dialog box (Figure 47).
UM004407-0104
2 Main Components
Z8 User Manual
104
Figure 47. Custom Link Control File Dialog Box
After you finish editing the link control file, click OK.
•
Select the Use Existing button and use the Browse button (
control file the linker uses.
) to select which link
Use C Runtime Library
The Use C Runtime Library check box allows you to use the run-time library.
Note: When you have an assembly project, deselect this check box to turn off the run-time
library. If you do not deselect this check box, you get the message "Symbol: Linker
Warning: 724 "_main has not been defined."
Output Category
Figure 48 shows the Output category of the Linker tab.
UM004407-0104
2 Main Components
Z8 User Manual
105
Figure 48. Project Settings Dialog Box (Linker Tab, Output Category)
Output File
You can change the name of your executable in the Output File field. After your program
is linked, the appropriate extension is added.
Executable Format
This drop-down list box determines which object format is used when the linker generates
an executable file. The linker supports the following formats: IEEE 695 (.lod), Intel
Hex16 and Hex32 (.hex), and Motorola S-Records (.srec) which are useful when programming an EPROM after testing is complete. IEEE 695 is the default format of the
linker/locator because it is the preferred format for debugging.
Use Runtime Library
The Use Runtime Library drop-down list box allows you to select the run-time library.
UM004407-0104
2 Main Components
Z8 User Manual
106
Target Tab
From the Project Settings dialog box, select the Target tab.
The options on the Target tab (Figure 49) are described in this section.
Figure 49. Project Settings Dialog Box–Target Tab
Object Size
Object sizes are the number of bits for each base type (short, int, and so on) in C. If you are
porting existing code from one target platform to another—for example, from another
software vendor to Z8 developer’s environment—knowing the size of each object and setting up Z8 developer’s environment to match the import size can save you a significant
amount of time.
The Object Size group contains the following:
•
•
•
•
•
UM004407-0104
Char
Short
Float
Long
Int
2 Main Components
Z8 User Manual
107
•
•
Double
Bitfield
The drop-down list boxes for the object sizes are used to define the sizes of data objects to
the C-Compiler. The list boxes allow you to configure the number of bits of each of the
base data types. Modifying the sizes of data types can be useful when porting existing
code from another target processor or from another software vendor. Some data types cannot be modified and are therefore grayed.
Caution: Your programs might not run correctly if you compile files from the same program under
different object size settings. Also, changing object sizes might prevent you from using
the C run-time library routines.
Memory
Memory ranges are used to determine the amount of memory available on your target system. Using this information, Z8 developer’s environment lets you know when your code
or data has grown beyond your system’s capability. The system also uses memory ranges
to automatically locate your code or data.
The Memory group of fields defines the memory layout of your target system. The Memory fields on the Target tab of the Project Settings dialog box allow you to configure the
ranges of memory available on your target Z8 microcontroller. These ranges vary from
processor to processor, as well as from target system to target system.
Depending on your CPU selection, the Memory group can contain the following fields:
•
•
•
RData
Code
XData
Address ranges are set in the Target tab of the Project Settings dialog box (see page 106).
The following is the syntax of a memory range:
<low address> – <high address> [,<low address> – <high address>] ...
where <low address> is the hexadecimal lower boundary of a range and <high address> is
the hexadecimal higher boundary of the range. The following are legal memory ranges:
00-df
0000-ffff
0000-1fff,4000-5fff
Holes in your memory can be defined for the linker using this mechanism. The linker does
not place any code or data outside of the ranges specified here. If your code or data cannot
be placed within the ranges, a range error is generated.
UM004407-0104
2 Main Components
Z8 User Manual
108
To minimize RData use in a small or large memory model, see the following example:
//
// Minimizing usage of DATA in small model
// (works for large model too)
//
#include <stdio.h>
rom char fmt1[] = "Hello World #%d\n";
// Store this string in ROM
rom char fmt2[] = "-----------------\n";
// Store in ROM
char fmt[20];
// RDATA format string holder
void rom_to_data_copy(char *dest,char rom *src)
{
while (*src)
*dest++ = *src++;
*dest = '\0';
}
void main()
{
rom_to_data_copy(fmt,fmt2);
// Copy from ROM to DATA
printf(fmt); // Prints "------------------\n");
printf(fmt,1000);
// Prints "Hello World #1000\n"
rom_to_data_copy(fmt,fmt2)
}
Debugger Tab
In the Project Settings dialog box, select the Debugger tab.
The source-level debugger is a program that allows you to find problems in your code at
the C or assembly level. The Windows interface is quick and easy to use. You can also
write batch files to automate debugger tasks.
From the Build menu, go to the Debug submenu and select Reset or Go. This moves you
into Debug mode.
You are now in Debug mode as shown in the Output window (Debug tab). The Debug
toolbar and Debug Windows toolbar are displayed.
Your understanding of the debugger design can improve your productivity because it
affects your view of how things work. The debugger requires a driver that is specific to a
target platform. A target platform is either an emulator or a simulator. A simulator requires
UM004407-0104
2 Main Components
Z8 User Manual
109
no hardware because it simulates the function of your target platform on your PC. Drivers
for emulators require that your PC be connected to the appropriate hardware. Currently,
the debugger supports drivers for the Z8 simulator and Z8 emulator.
Simulator
When you select Simulator from the Driver drop-down list box, you can configure the
simulator on the Debugger tab (Figure 50).
Figure 50. Project Settings Dialog Box (Debugger Tab, Simulator Driver)
Simulator Throttle
Moving the thumb bar or scrolling the scroll bar adjusts the Simulator Throttle from 1% to
100%. A 1% throttle means that the simulator uses approximately 1% of the system's
resources while executing your program's instructions. This leaves plenty of power to do
other things while the simulator is running. A throttle of 100% uses virtually all of your
CPU’s processing time to execute your program, allowing it to complete faster but slows
any other Windows functions down considerably. The recommended setting is 50%.
Load Memory Files
This check box determines whether the debugger automatically loads your memory files
into the target platform's memory each time the debugger is executed.
UM004407-0104
2 Main Components
Z8 User Manual
110
Write Memory Files
This check box determines whether the debugger automatically writes your memory files
into the target platform's memory each time the debugger is executed.
Clock Speed
In the Clock Speed field, type the appropriate speed. The default is 20.000000.
Note: The frequency is now automatically selected from the IDE using one of the following
methods:
•
When the target is the Simulator, set the Clock Speed on the Debugger tab of the
Project Settings dialog box.
•
When the target is the Z8 emulator, set the clock frequency in the Configure Emulator
Driver dialog box (see “Configure Emulator Driver Dialog Box” on page 111).
Emulator Driver
When you select Emulator Driver from the Driver drop-down list box, you can configure
the emulator on the Debugger tab (Figure 51).
Figure 51. Project Settings Dialog Box (Debugger Tab, Emulator Driver)
UM004407-0104
2 Main Components
Z8 User Manual
111
Configure Emulator Driver
Click Configure Emulator Driver to configure the emulator and to display the Configure
Emulator Driver dialog box (Figure 52).
Figure 52. Configure Emulator Driver Dialog Box
•
•
•
•
Use the Name drop-down list box to select the appropriate emulator.
Type the IP address in the IP Address field.
Type the port number in the TCP Port field.
Use the Voltage drop-down list box to select the appropriate target VCC voltage from
•
Select the appropriate clock frequency or enter the clock frequency in the Other field.
Note: The frequency is now automatically selected from the IDE using one of the following
methods:
•
Project Settings dialog box (see “Debugger Tab” on page 108).
•
Driver dialog box.
UM004407-0104
2 Main Components
Z8 User Manual
112
Export Makefile
Export Makefile exports a buildable project in external make file format. To do this, complete the following procedure:
1. From the Project menu, select Export Makefile.
The Save As dialog box (Figure 53) is displayed.
Figure 53. Save As Dialog Box
2. Navigate to the directory where you want to save your project.
The default location is in your project directory.
3. Type the make file name in the File Name field and click Save.
You do not have to type the extension .mak. The extension is added automatically.
The project is now available as an external make file.
BUILD MENU
With the Build menu, you can build individual files as well as your project. You can also
use this menu to select or add configurations for your project.
The Build menu has the following options:
•
•
•
•
UM004407-0104
Compile
Build
Rebuild All
Stop Build
2 Main Components
Z8 User Manual
113
•
•
•
•
Update All Dependencies
Debug
Set Active Configuration (page 115)
Manage Configurations (page 117)
Compile
Select Compile from the Build menu to compile or assemble the active file in the Edit
window.
Build
Select Build from the Build menu to build your project. The build compiles and/or assembles any files that have changed since the last build and then relinks the project.
Rebuild All
Select Rebuild All from the Build menu to rebuild all the files in your project. This option
also relinks the project.
Stop Build
Select Stop Build from the Build menu to stop a build in progress.
Update All Dependencies
Select Update All Dependencies from the Build menu to update your source file dependencies.
Debug
From the Build menu, you can access the following functions for the debugger:
•
•
•
•
•
•
•
•
•
UM004407-0104
Connect to Target (see page 114)
Download Code (see page 114)
Stop Debugging (see page 114)
Reset (see page 114)
Go (see page 114)
Run to Cursor (see page 114)
Break (see page 114)
Step Into (see page 114)
Step Over (see page 115)
2 Main Components
Z8 User Manual
114
•
•
Step Out (see page 115)
Set Next Instruction (see page 115)
Note: For more information on the debugger, see Chapter 3, “Debugging,” starting on page 137.
Connect to Target
The Connect to Target button starts a debug session and initializes the communication to
the target hardware. Clicking this button does not download the software or reset to main.
Use this button to access target registers, memory, and so on, without loading new code or
to avoid overwriting the target’s code with the same code. This button is not enabled when
the target is the simulator.
Download Code
Stop Debugging
Select Stop Debugging from the Debug submenu to exit Debug mode.
Reset
Select Reset from the Debug submenu to reset the debugger. By default, selecting Reset
resets the PC to symbol 'main'. If you deselect the Reset to Symbol 'main' (Where Applicable) check box on the Debugger tab of the Options dialog box (see page 133), the PC
resets to the first line of the program.
Go
Select Go from the Debug submenu to invoke Debug mode (make the debugger run).
Run to Cursor
Select Run to Cursor from the Debug submenu to make the debugger run to the line containing the cursor.
Break
Select Break from the Debug submenu to break the program execution and stop the
debugging in progress.
Step Into
Select Step Into from the Debug submenu to execute the code one statement at a time.
UM004407-0104
2 Main Components
Z8 User Manual
115
Step Over
Select Step Over from the Debug submenu to step to the next statement regardless of
whether the current statement is a call to another function.
Step Out
Select Step Out from the Debug submenu to execute the remaining lines in the current
function and return to execute the next statement in the caller function.
Set Next Instruction
Select Set Next Instruction from the Debug submenu to set the next instruction at the current line.
Set Active Configuration
There are two standard configuration settings:
•
Debug
This configuration contains all the project settings for running the project in Debug
mode.
•
Release
This configuration contains all the project settings for creating a Release version of
the project.
For each project, you can modify the settings, or you can create your own configurations.
These configurations allow you to easily switch between project setting types without having to remember all the setting changes that need to be made for each type of build that
might be necessary during the creation of a project. All changes to project settings are
stored in the current configuration setting.
Note: To add your own configuration(s), see “Manage Configurations” on page 117.
There are three ways to change the configuration settings:
•
•
•
Select Configuration dialog box (page 115)
Select Active Configuration list box (page 116)
Project Settings dialog box (page 116)
Select Configuration Dialog Box
You can use the Select Configuration dialog box to select the active configuration you
want.
1. From the Build menu, select Set Active Configuration to display the Select
Configuration dialog box (Figure 54).
UM004407-0104
2 Main Components
Z8 User Manual
116
Figure 54. Select Configuration Dialog Box
2. Highlight the configuration and click OK.
Select Active Configuration List Box
You can use the Select Active Configuration drop-down list box (Figure 55) in the Z8
developer’s environment. This list box is part of the Build toolbar.
Figure 55. Select Active Configuration List Box
Project Settings Dialog Box
You can use the Project Settings dialog box (from the Project menu, select Settings) to
select the configuration for your project (see Figure 56).
UM004407-0104
2 Main Components
Z8 User Manual
117
Figure 56. Project Settings Dialog Box
1. From the Project menu, select Settings to display the Project Settings dialog box.
2. In the drop-down list box, select the configuration.
Manage Configurations
For your specific needs, you can add different configurations for your projects.
To add a customized configuration, do the following:
1. From the Build menu, select Configurations.
This displays the Manage Configurations dialog box shown in Figure 57.
UM004407-0104
2 Main Components
Z8 User Manual
118
Figure 57. Manage Configurations Dialog Box
2. From the Manage Configurations dialog box, click Add.
This displays the Add Project Configuration dialog box (Figure 58).
Figure 58. Add Project Configuration Dialog Box
3. Type the name of the configuration in the Configuration Name field.
4. Select a target from the Target drop-down list box.
5. Select a similar configuration from the Copy Settings From drop-down list box.
6. Click OK.
Your new configuration is displayed in the configurations list in the Manage
Configurations dialog box.
7. Click Close.
The new configuration is the current configuration as shown in the Select Active
Configuration drop-down list box on the Build toolbar (on the Z8 developer’s
environment).
Now that you have created a blank template, you are ready to select the settings for
this new configuration.
8. From the Project menu, select Settings to display the Project Settings dialog box.
9. Select the settings for the new configuration and click OK.
UM004407-0104
2 Main Components
Z8 User Manual
119
10. From the File menu, select Save All.
TOOLS MENU
The Tools menu lets you select the toolbars you want on the Z8 developer’s environment.
The default shows the menu bar, File toolbar, Build toolbar, and Edit toolbar. When you
are in Debug mode (running the debugger), the Debug and Debug Windows are displayed.
The Tools menu has the following options:
•
•
•
•
Trace and Event System
OTP Programming (page 121)
Customize (page 126)
Options (page 129)
Trace and Event System
Note: The Trace and Event System command is only available if you are using the Z8 emulator.
To specify events to trace, use the following procedure:
1. Select Clear Trace from the Edit menu to delete old trace data.
2. Select Trace and Event System from the Tools menu.
The Trace and Event System dialog box (Figure 59) is displayed.
UM004407-0104
2 Main Components
Z8 User Manual
120
Figure 59. Trace and Event System Dialog Box
3. Select the Enable Event System check box.
4. Select the check boxes in the When area to specify the events that you want traced:
If you select the Program Counter or any of the ports, enter a number in the Mask field
to specify a single data point or a range of data. Entering 00 in a Mask field indicates
“Don’t Care,” and the corresponding Program Counter or port setting is ignored.
Entering FF in a Mask field specifies that an exact match must be found for the
Program Counter or port setting.
If you select the Trigger In check box, select 0 or 1 for the trigger.
5. Select the Break button if you want a break after the event is traced or select the Event
Position in Buffer button to control how much is traced.
6. Click OK.
7. From the Build menu, select the Debug submenu and then select Reset.
This switches ZDS II to Debug mode.
UM004407-0104
).
2 Main Components
Z8 User Manual
121
9. When the program execution breaks or stops, click the Trace Window button (
).
The Trace window is displayed. For more information about using the Trace window,
see “Trace Window” on page 160.
10. Click Get Frames.
ZDS II uploads the most recently collected trace data from the emulator to your host
computer.
Note: When you have specified events to be traced in the Trace and Event System dialog box,
you can disable or enable them by selecting Event System from the Edit menu.
OTP Programming
For the Z86D35 Family, there are two modes in which to run the OTP:
•
in Standalone mode
In Standalone mode, you select and download the hex file once, burn the OTP, switch
the device, and continue to burn as many devices as needed. Standalone mode is
recommended when you are burning more than one device.
Note: A null target connector is required for Standalone mode. For more details, see the
Z86D35 In-Circuit Emulator Startup Guide (QS0041).
•
in Debug mode
In Debug mode, the hex file is automatically loaded when you switch ZDS II into
Debug mode. Debug mode is recommended when you are checking a device that has
already been programmed.
Use the following procedure to run the OTP in Standalone mode:
1. Create a project or open a project with Z86D35 selected in the CPU Family field on
the General tab of the Project Settings dialog box. See “General Tab” on page 83.
2. Ensure that the target board is powered up and the Z8 emulator is connected and
operating properly.
3. Enter the emulator Ethernet address in the Configure Emulator Driver dialog box (see
“Emulator Driver” on page 110).
4. Select OTP Programming from the Tools menu.
ZDS II connects to the target and sets up communication. The OTP dialog box
(Figure 60) is displayed, with the appropriate programming option bits for the selected
CPU.
UM004407-0104
2 Main Components
Z8 User Manual
122
Figure 60. OTP Dialog Box (in Standalone Mode)
5. Type the path and hex file name to be programmed in the Hex File field or click on the
Browse button (
) to navigate to the hex file.
6. If you do not want to fill the unused memory locations, select the None button in the
Pad File With area; otherwise, select the FF, 00, or Other button. If you select the
Other button, type the number that you want to fill the unused memory locations with
in the Other field.
7. Click Load File to load the hex file into emulator RAM.
8. Click Ram Checksum to calculate the checksum of data in emulator RAM.
The result is displayed in the Status area.
9. Select which option bits to program in the Programming Option Bits area.
UM004407-0104
2 Main Components
Z8 User Manual
123
Notes: The options displayed depend on which CPU and CPU family were selected on
the General tab of the Program Settings dialog box.
Do not select both the EPROM Protect and WDT Permanently Enabled bits if you
need to access the device again.
10. If you do not want a serial number loaded into the part, select the None button in the
Method area; otherwise, use the following procedure to load a serial number:
a. Select the Sequential or Pseudorandom button to determine how the serial number
is incremented on subsequent burns.
b. Select the size of the serial number (1, 2, 3, or 4 bytes) in the Serial Number Size
area.
c. Enter the starting serial number in the Serial Number field.
d. Enter the address that you want the serial number loaded at in the Address field.
This address can be any location in the OTP.
Note: The address for the serial number needs to be outside of the program data range.
11. Click Blank Check to find out if the OTP device is completely erased.
12. Click Burn to write the hex file to OTP memory and then verify that it has been
written correctly.
13. Click OTP Checksum to calculate the checksum of data in emulator OTP.
The result is displayed in the Status area. If this number matches the RAM checksum,
the burn was successful.
Use the following procedure to run the OTP in Debug mode:
1. Create a project or open a project with Z86D35 selected in the CPU Family field on
the General tab of the Project Settings dialog box. See “General Tab” on page 83.
2. Ensure that the target board is powered up and the Z8 emulator is connected and
operating properly.
3. Enter the emulator Ethernet address in the Configure Emulator Driver dialog box (see
“Emulator Driver” on page 110).
4. Select OTP Programming from the Tools menu.
ZDS II connects to the target and sets up communication. The OTP dialog box
(Figure 61) is displayed, with the appropriate programming option bits for the selected
CPU.
UM004407-0104
2 Main Components
Z8 User Manual
124
Figure 61. OTP Dialog Box (in Debug Mode)
5. If you do not want to fill the unused memory locations, select the None button in the
Pad File With area; otherwise, select the FF, 00, or Other button. If you select the
Other button, type the number that you want to fill the unused memory locations with
in the Other field.
6. Click Ram Checksum to calculate the checksum of data in emulator RAM.
7. Select which option bits to program in the Programming Option Bits area.
Notes: The options displayed depend on which CPU and CPU family were selected on
the General tab of the Program Settings dialog box.
Do not select both the EPROM Protect and WDT Permanently Enabled bits if you
need to access the device again.
UM004407-0104
2 Main Components
Z8 User Manual
125
8. If you do not want a serial number loaded into the part, select the None button in the
Method area; otherwise, use the following procedure to load a serial number:
a. Select the Sequential or Pseudorandom button to determine how the serial number
is incremented on subsequent burns.
b. Select the size of the serial number (1, 2, 3, or 4 bytes) in the Serial Number Size
area.
c. Enter the starting serial number in the Serial Number field.
d. Enter the address that you want the serial number loaded at in the Address field.
This address can be any location in the OTP.
Note: The address for the serial number needs to be outside of the program data range.
9. Click Blank Check to find out if the OTP device is completely erased.
10. Click Burn to write the hex file to OTP memory and then verify that it has been
written correctly.
11. Click OTP Checksum to calculate the checksum of data in emulator OTP.
If this number matches the RAM checksum, the burn was successful.
If you want to check a chip that has already been programmed, use the following methods:
•
If you do not have the hex file that was burned on the chip, click Read to read what
data was burned on the chip.
The results are displayed in the Status area.
•
If you know which hex file was burned on the chip, browse to the hex file location,
click Load File, and then click Read Options to check which options are currently
programmed on the OTP.
When you click Read Options, the Programmed Option Bits dialog box is displayed
(Figure 62).
UM004407-0104
2 Main Components
Z8 User Manual
126
Figure 62. Programmed Option Bits Dialog Box
•
If you know which hex file was burned on the chip, browse to the hex file location,
click Load File, and then click Verify to check the hex file against the chip. The
results are displayed in the Status area.
When you click Verify, ZDS II reads and compares the hex file contents with the
current contents of OTP memory. This function does not change target OTP memory.
Note: Use the right-click menu in the Status area to copy or clean any of the text in the
Status area.
Customize
The Customize dialog box contains two tabs, Toolbars and Commands.
Toolbars Tab
The Toolbars tab (Figure 63) lets you select the toolbars you want to display on the Z8
developer’s environment, change the way the toolbars are displayed, or create a new toolbar.
Note: You cannot delete, customize, or change the name of the default toolbars.
UM004407-0104
2 Main Components
Z8 User Manual
127
Figure 63. Customize Dialog Box–Toolbars Tab
To create a new toolbar, use the following procedure:
1. Select Customize from the Tools menu.
The Customize dialog box is displayed.
2. Click on the Toolbars tab.
3. Click New.
The New Toolbar dialog box is displayed as shown in Figure 64.
Figure 64. New Toolbar Dialog Box
UM004407-0104
2 Main Components
Z8 User Manual
128
4. In the Toolbar Name field, type the name of the new toolbar.
5. Click OK.
The new toolbar is displayed as a gray box.
You can change the name by selecting the new toolbar in the toolbars list box, typing a
new name in the Toolbar Name field, and pressing the Enter key.
6. Click the Commands tab.
7. Drag buttons from any category to your new toolbar.
Note: To delete the new toolbar, select the new toolbar in the Toolbars list box and click Delete.
8. Click OK to apply your changes or click Cancel to close the dialog box without
making any changes.
Commands Tab
The Commands tab lets you view the following by selecting the categories:
•
•
•
•
•
•
•
File toolbar (described on page 55)
Edit toolbar (described on page 56)
Build toolbar (described on page 56)
Debug toolbar (described on page 58)
Debug Windows toolbar (described on page 60)
Command Processor toolbar (descibed on page 58)
Menu bar (described on page 67)
To see a description of each button on the toolbars, highlight the icon as shown in
Figure 65.
UM004407-0104
2 Main Components
Z8 User Manual
129
Figure 65. Customize Dialog Box–Commands Tab
Options
The Options dialog box contains three tabs:
•
•
•
General
Editor (page 130)
Debugger (page 133)
General Tab
The General tab (Figure 66) has five buttons:
•
Select the Save Files Before Build button to save files before you build. This option is
selected by default.
•
Select the Automatically Reload Externally Modified Files button to automatically
reload externally modified files. This option is not selected by default.
•
Select the Load Last Project on Startup button to load the most recently active project
when you start ZDS II. This option is not selected by default.
UM004407-0104
2 Main Components
Z8 User Manual
130
•
Select the Show the Full Path in the Document Window’s Title Bar button to add the
complete path to the name of each file open in the Edit window.
•
Select the Save/Restore Project Workspace button to save the project workspace
settings each time you exit from ZDS II. This option is selected by default.
Select a number of commands to save in the Commands to Keep field or click Clear to
delete the saved commands.
Figure 66. Options Dialog Box—General Tab
Editor Tab
Use the Editor tab to change the default settings of the editor for your assembly, C, and
default files:
1. From the Tools menu, select Options.
The Options dialog box is displayed.
2. Click on the Editor tab (Figure 67).
UM004407-0104
2 Main Components
Z8 User Manual
131
Figure 67. Options Dialog Box—Editor Tab
3. Select a file type from the File Type drop-down list box.
4. In the Tabs area, do the following:
– Use the Tab Size field to change the number of spaces that a tab indents code.
– Select the Insert Spaces button or the Keep Tabs button.
– Select the Show Tabs check box if you want a symbol displayed in your code
indicating tab placement.
5. Click Syntax Coloring.
The Syntax Coloring dialog box is displayed as shown in Figure 68.
UM004407-0104
2 Main Components
Z8 User Manual
132
Figure 68. Syntax Coloring Dialog Box
–
–
–
Select the Use Syntax Coloring check box if you want the program to be color
coded. Use the Current Colors area to define which colors are assigned to
keywords, quotes, comments, default text, and the background.
Select the Case Sensitive check box if you want the compiler to distinguish
between upper case and lower case letters.
Use the Comment Definitions area to define comment characters.
6. Click OK to close the Syntax Coloring dialog box.
7. On the Editor tab, click Select Font.
8. The Font dialog box is displayed as shown in Figure 69.
UM004407-0104
2 Main Components
Z8 User Manual
133
Figure 69. Font Dialog Box
You can change the font, font style, font size, and script style.
9. Click OK to close the Font dialog box.
10. Click OK to close the Options dialog box.
Debugger Tab
The Debugger tab (Figure 70) has six check boxes:
•
Select the Save Project Before Start of Debug Session check box to save the current
project before entering the Debug mode. This option is selected by default.
•
Select the Reset to Symbol 'main' (Where Applicable) check box to skip the startup
(boot) code and start debugging at the main function for a project that includes a C
language main function. When this check box is selected, a user reset (clicking the
Reset button on the Build and Debug toolbars, selecting Reset from the Debug
submenu, or using the reset script command) results in the program counter (PC)
pointing to the beginning of the main function. When this check box is not selected, a
user reset results in the PC pointing to the first line line of the program (the first line of
the startup code).
•
When the Show DataTips Pop-Up Information check box is selected, you can hold the
mouse cursor over a variable in a C file in the Edit window in Debug mode, and the
value is displayed.
UM004407-0104
2 Main Components
Z8 User Manual
134
•
Select the Hexadecimal Display check box to change the values in the Watch and
Locals windows to hexadecimal format. Deselect the check box to change the values
in the Watch and Locals windows to decimal format.
•
Select the Load Debug Information (Current Project) check box to load the debug
information for the currently open project when the Connect to Target command is
executed (from the Debug submenu or from the Connect to Target button). This option
is selected by default.
•
Select the Activate Breakpoints check box for the breakpoints in the current project to
be active when the Connect to Target command is executed (from the Debug submenu
or from the Connect to Target button). This option is selected by default.
Figure 70. Options Dialog Box—Debugger Tab
WINDOW MENU
The Window menu allows you to select the ways you want to arrange your files in the Edit
window and allows you to activate the Project Workspace window or the Output window.
The Windows menu contains the following options:
•
•
•
•
UM004407-0104
New Window (page 135)
Close (page 135)
Close All (page 135)
Cascade
2 Main Components
Z8 User Manual
135
•
•
Tile
Arrange Icons
New Window
Select New Window to create a copy of the file you have active in the Edit window.
Close
Select Close to close the active file in the Edit window.
Close All
Select Close All to close all the files in the Edit window.
Cascade
Select Cascade to cascade the files in the Edit window. Use this option to display all open
windows whenever you cannot locate a window.
Tile
Select Tile to tile the files in the Edit window so that you can see all of them at once.
Arrange Icons
Select Arrange Icons to arrange the files alphabetically in the Edit window.
HELP MENU
The Help menu contains the following options:
•
•
•
Help Topics
Online Registration
About (see page 136)
Help Topics
Select Help Topics to display the ZDS II online help.
Online Registration
Select Online Registration to display the ZiLOG Customer Support web page.
To register your copy of ZDS II, log in to ZiLOG Support.
UM004407-0104
2 Main Components
Z8 User Manual
136
About
Select About to display the registration key and version information.
UM004407-0104
2 Main Components
Z8 User Manual
137
3
Debugging
The source-level debugger is a program that allows you to find problems in your code at
the C or assembly level. You can also write batch files to automate debugger tasks (see
“Command Processor Quick Tour” on page 17). The following topics are covered in this
chapter:
•
•
•
•
•
•
•
“Status Bar” on page 138
“Code Line Indicators” on page 139
“Debug Output Window” on page 139
“Debug Toolbar” on page 139
“Debug Windows” on page 142
“Using Breakpoints” on page 160
“Using the Emulator” on page 163
Click the Reset button (
) on the Build toolbar to switch to Debug mode.
You are now in Debug mode as shown in the Output window (Debug tab). The Debug
toolbar and Debug Windows toolbar are displayed as shown in Figure 71.
UM004407-0104
3 Debugging
Z8 User Manual
138
Figure 71. Debug and Debug Window Toolbars
Note: If you edit and build code while in Debug mode, you need to stop and restart the debugger
to load the new code. The new code is not automatically reloaded.
STATUS BAR
The status bar displays the current status of your program’s execution. The status can be
STOP, STEP, or RUN. In STOP mode, your program is not executing. In STEP mode, a
Step Into, Step Over, or Step Out command is in progress. In RUN mode, a Go command
has been issued with no animate active.
Note: The status bar is either a box displayed in the upper right corner under the title bar or a
horizontal bar under the buttons, depending on your screen resolution.
UM004407-0104
3 Debugging
Z8 User Manual
139
CODE LINE INDICATORS
The Edit window displays your source code with line numbers and code line indicators.
The debugger indicates the status of each line visually with the following code line indicators:
•
A red octagon indicates an active breakpoint at the code line; a white octagon
indicates a disabled breakpoint.
•
Blue dots are displayed to the left of all valid code lines; these are lines where
breakpoints can be set, the program can be run to, and so on.
Note: Some source lines do not have blue dots because the code has been optimized out of the
executable (and the corresponding debug information).
•
A PC code line indicator (yellow arrow) indicates a code line at which the program
counter (PC) is located.
•
A PC code line indicator on a breakpoint (yellow arrow on a red octagon) indicates a
code line indicator has stopped on a breakpoint.
If the program counter steps into another file in your program, the Edit window switches
to the new file automatically.
DEBUG OUTPUT WINDOW
The Debug Output window displays the result of certain commands and error messages.
Error messages are displayed in red. The window also displays command output from
debugger script files.
DEBUG TOOLBAR
The Debug toolbar (Figure 72) allows you to perform debugger functions.
Figure 72. Debug Toolbar
Download Code
UM004407-0104
3 Debugging
Z8 User Manual
140
Reset Button
Stop Debugging Button
The Stop Debugging button exits you from the debugger (leave Debug mode).
To stop Debug mode, use the Break button (described on page 140).
Go Button
The Go button executes the code until there is either a breakpoint or the STOP command
is initiated. In Normal execution mode, the status bar changes to RUN. In Stepped execution mode, the status bar changes to STEP. This command cannot be used if the program
execution status is RUN, as shown in the status bar.
Note: This command cannot be invoked when the program execution status is not in the STOP
mode. An error message, ERROR - Process is still running, displays.
Run to Cursor Button
The Run to Cursor button makes the debugger run to the line containing the cursor. You
can only use this command for a line with a blue dot displayed to the left of the line.
Break Button
The Break button pauses the program execution and stops the debugging in progress.
Step Into Button
The Step Into button executes the code one statement at a time. If the line is a module with
debug information, this command steps into the module. If the Disassembly window is
opened, this command executes one line of the assembly code; otherwise, it executes one
line of source code.
Note: The status bar changes to STEP until the line is executed. Then the status bar changes back
to STOP.
Step Over Button
The Step Over button steps to the next statement regardless of whether the current statement is a call to another function.
UM004407-0104
3 Debugging
Z8 User Manual
141
Step Out Button
The Step Out button executes the remaining lines in the current function and returns to
execute the next statement in the caller function.
Note: The message ERROR - PC has entered an unknown region is displayed when
there is no debugging information available. If you use the default startup module in the
compiler and the default linker, you are not able to step into the program until the main
module is executed because there is no debug information available in the startup program.
You have to set a breakpoint and execute the code continuously (using the Go command)
until it reaches the main module. The status bar changes to STEP until the code stopped
line is executed. Then, the status bar changes back to STOP.
Set Next Instruction Button
The Set Next Instruction button allows you to set the next instruction at the current line.
a breakpoint in any line with a blue dot displayed to the left of the line. For more information on breakpoints, see “Using Breakpoints” on page 160.
For more information on breakpoints, see “Using Breakpoints” on page 160.
Disable All Breakpoints Button
The Disable All Breakpoints button deactivates all breakpoints in all open files. To delete
breakpoints from your program, use the Remove All Breakpoints button.
The Remove All Breakpoints button deletes all breakpoints in all open files. To deactivate
breakpoints in your program, use the Disable All Breakpoints button.
UM004407-0104
3 Debugging
Z8 User Manual
142
DEBUG WINDOWS
The Debug Windows toolbar (Figure 74 or Figure 74, depending on if you are using the
Z8 emulator) allows you to open the following Debug windows:
•
•
•
•
•
•
•
•
•
•
Registers window (see page 143)
Special Function Registers window (see page 143)
Clock window (see page 144)
Memory window (see page 145)
Watch window (see page 150)
Locals window (see page 152)
Call Stack window (see page 153)
Symbols window (see page 153)
Disassembly window (see page 154)
Trace window (see page 155)
Figure 73. Debug Windows Toolbar
Figure 74. Debug Windows Toolbar (with the Z8 Emulator Connected)
UM004407-0104
3 Debugging
Z8 User Manual
143
Registers Window
Click the Registers Window button to show or hide the Registers window. The Registers
window (Figure 75) displays all the registers in the standard Z8 architecture.
Figure 75. Registers Window
To change register values, do the following:
1. In the Registers window, highlight the value you want to change.
2. Type the new value and press the Enter key.
The changed value is displayed in red.
Special Function Registers Window
Click the Special Function Registers Window button to show or hide the Special Function
Registers window. The Special Function Registers window (Figure 76) displays all the
special function registers in the standard Z8 architecture. Addresses F00 through FFF are
reserved for special function registers (SFRs).
UM004407-0104
3 Debugging
Z8 User Manual
144
Figure 76. Special Function Registers Window
Note: There are several SFRs that when read are cleared or clear an associated register.
To prevent the debugger from changing the behavior of the code, a special group of
SFRs was created that groups these state changing registers. The group is called
CHANGE_STATE_REG. If this group is selected, the behavior of the code
changes, and the program must be reset.
To change special function register values, do the following:
1. In the Special Function Registers window, highlight the value you want to change.
Clock Window
Click the Clock Window button to show or hide the Clock window.
The Clock window displays the number of states executed since the last reset. You can
reset the contents of the Clock window at any time by selecting the number of cycles (6 in
Figure 77), type 0, and press the Enter key. Updated vales are displayed in red.
UM004407-0104
3 Debugging
Z8 User Manual
145
Figure 77. Clock Window
Memory Window
Click the Memory Window button to show or hide the Memory window (Figure 78).
Figure 78. Memory Window
The Memory window displays data located in program memory. The address is displayed
in the far left column with a C# to denote the code address space or with an R# to denote
the Rdata address space.
Note: For RData, the Memory window shows the whole internal data memory.
Changing Values
To change the values in the Memory window, do the following:
1. In the window, highlight the value you want to change.
The values begin in the second column after the Address column.
Note: The ASCII text for the value is shown in the last column.
UM004407-0104
3 Debugging
Z8 User Manual
146
Viewing Addresses
To quickly view or search for an address in the Memory window, do the following:
1. In the Memory window, highlight the address in the Address field, as shown in
Figure 79.
Note: To view the values for other memory spaces, replace the C with a different valid memory
prefix. You can also change the current memory space by selecting the space name in the
Space drop-down list.
Figure 79. Memory Window—Starting Address
2. Type the address you want to find and press the Enter key.
For example, find 0395.
The system moves the selected address to the top of the Memory window, as shown in
Figure 80.
Figure 80. Memory Window—Requested Address
UM004407-0104
3 Debugging
Z8 User Manual
147
Filling Memory
Use this procedure to write a common value in all the memory spaces in the specified
address range, for example, to clear memory for the specified address range.
To fill a specified address range of memory, do the following:
1. Select the memory space (Code or Rdata) in the Space drop-down list.
2. Right-click in the Memory window list box to display the right-click menu.
3. Select Fill Memory.
The Fill Memory dialog box is displayed, as shown in Figure 81.
Figure 81. Fill Memory Dialog Box
4. In the Fill Value area, select the characters to fill memory with or select the Other
button.
If you select the Other button, type the fill characters in the Other field.
5. Type the start address in hexadecimal format in the Start Address (Hex) field and type
the end address in hexadecimal format in the End Address (Hex) field.
This address range is used to fill memory with the specified value.
6. Click OK to fill the selected memory.
Saving to a File
Use this procedure to save memory specified by an address range to a binary, hexadecimal, or text file.
Perform the following steps to save memory to a file:
1. Select the memory space (Code or Rdata) in the Space drop-down list.
3. Select Save to File.
The Save to File dialog box is displayed, as shown in Figure 82.
UM004407-0104
3 Debugging
Z8 User Manual
148
Figure 82. Save to File Dialog Box
4. In the File Name field, enter the path and name of the file you want to save the
memory to or click the Browse button (
) to search for a file or directory.
5. Type the start address in hexadecimal format in the Start Address (Hex) field and type
the end address in hexadecimal format in the End Address (Hex) field.
This specifies the address range of memory to save to the specified file.
6. Select whether to save the file as text, hex (hexadecimal), or binary.
7. Click OK to save the memory to the specified file.
Loading from a File
Use this procedure to load or to initialize memory from an existing binary, hexadecimal,
or text file.
Perform the following steps to load a file into the code’s memory:
1. Select Rdata memory space in the Space drop-down list.
3. Select Load from File.
The Load from File dialog box is displayed, as shown in Figure 83.
UM004407-0104
3 Debugging
Z8 User Manual
149
Figure 83. Load from File Dialog Box
4. In the File Name field, enter the path and name of the file to load or
click the Browse button (
) to search for the file.
5. In the Start Address (Hex) field, enter the start address.
6. Select whether to load the file as text, hex (hexadecimal), or binary.
7. Click OK to load the file's contents into the selected memory.
Note: The Page Up and Page Down keys (on your keyboard) are not functional in the Memory
window. Instead, use the up and down arrow buttons to the right of the Space and Address
fields.
UM004407-0104
3 Debugging
Z8 User Manual
150
Watch Window
Click the Watch Window button to show or hide the Watch window (Figure 84).
Figure 84. Watch Window
The Watch window displays all the variables and their values defined using the WATCH
command. If the variable is not in scope, the variable is not displayed. The values in the
Watch window change as the program executes. Updated values appear in red.
The 0x prefix indicates that the values are displayed in hexadecimal format. If you want
the values to be displayed in decimal format, select Hexadecimal Display from the rightclick menu.
Note: If the Watch window displays unexpected values, deselect the Use Register Variables check
box in the Code Generation category of the C (Compiler) tab on the Project Settings dialog
box. See page 89.
Adding New Variables
To add new variables in the Watch window, select the variable in the source file, drag, and
drop it into the window. Another way to add new variables is to use the following procedure:
1. Click once on <new watch> in the Expression column.
This activates the column so that you can type the expression accurately.
UM004407-0104
3 Debugging
Z8 User Manual
151
2. Type the expression and press the Enter key.
The value is displayed in the Value column.
Changing Values
To change values in the Watch window, do the following:
1. In the window, highlight the value you want to change.
Removing an Expression
To remove an expression from the Watch window, do the following:
1. In the Expression column, click once on the expression you want to remove.
2. Press the Delete key to clear both columns.
Viewing a Hexadecimal Value
To view the hexadecimal values of an expression, type hex expression in the Expression
column and press the Enter key. For example, type hex tens. The hexadecimal value displays in the Value column.
To view the hexadecimal values for all expressions, select Hexadecimal Display from the
right-click menu.
Note: You can also type just the expression (for example, type tens) to view the hexadecimal
value of any expression. Hexadecimal format is the default.
Viewing a Decimal Value
To view the decimal values of an expression, type dec expression in the Expression column and press the Enter key. For example, type dec huns. The decimal value displays in
the Value column.
To view the hexadecimal values for all expressions, select Hexadecimal Display from the
right-click menu.
Viewing an ASCII Value
To view the ASCII values of an expression, type ascii expression in the Expression column and press the Enter key. For example, type ascii ones. The ASCII value displays
in the Value column.
UM004407-0104
3 Debugging
Z8 User Manual
152
Viewing a NULL-Terminated ASCII (ASCIZ) String
To view the NULL-terminated ASCII (ASCIZ) values of an expression, type asciz
expression in the Expression column and press the Enter key. For example, type asciz
ones. The ASCIZ value displays in the Value column.
Locals Window
Click the Locals Window button to show or hide the Locals window. The Locals window
(Figure 85) displays all local variables that are currently in scope. Updated values appear
in red.
The 0x prefix indicates that the values are displayed in hexadecimal format. If you want
the values to be displayed in decimal format, select Hexadecimal Display from the rightclick menu.
Note: If the Locals window displays unexpected values, deselect the Use Register Variables
check box in the Code Generation category of the C (Compiler) tab on the Project Settings
dialog box. See page 89.
Figure 85. Locals Window
UM004407-0104
3 Debugging
Z8 User Manual
153
Call Stack Window
Click the Call Stack Window button to show or hide the Call Stack window (Figure 86). If
you want to copy text from the Call Stack Window, select the text and then select Copy
from the right-click menu.
Figure 86. Call Stack Window
The Call Stack window allows you to view function frames that have been pushed onto the
stack. Information in the Call Stack window is updated every time a debug operation is
processed.
Symbols Window
Click the Symbols Window button to show or hide the Symbols window (Figure 87).
Figure 87. Symbols Window
Note:
Close the Symbols window before running a command script.
UM004407-0104
3 Debugging
Z8 User Manual
154
The Symbols window displays the address for each symbol in the program.
Disassembly Window
Click the Disassembly Window button to show or hide the Disassembly window
(Figure 88).
Figure 88. Disassembly Window
The Disassembly window displays the assembly code associated with the code shown in
the Code window. For each line in this window, the address location, the machine code,
the assembly instruction, and its operands are displayed.
When you right-click in the Disassembly window, the right-click menu allows you to do
the following:
•
•
•
Copy text
Go to the source code
Insert, edit, enable, disable, or remove breakpoints
For more information on breakpoints, see “Using Breakpoints” on page 160.
•
•
•
•
•
•
UM004407-0104
Reset the debugger
Stop debugging
Start or continue running the program (Go)
Run to the cursor
Pause the debugging (Break)
Step into, over, or out of program instructions
3 Debugging
Z8 User Manual
155
•
•
Set the next instruction at the current line
Enable and disable source annotation and source line numbers
Trace Window
Note: The Trace window is only available if you are using the Z8 emulator.
Trace information is collected for every clock cycle during Debug mode unless the event
system is enabled (by selecting Event System from the Edit menu). Click the Trace Window button to show or hide the Trace window (Figure 89).
Figure 89. Trace Window
When you right-click in the Trace window, the right-click menu allows you to do the following:
•
•
switch to unfiltered trace data, raw trace data, or disassembled trace data
save the trace data to a file
The Trace window displays unfltered trace data (Figure 90), disassembled trace data
(Figure 91), or raw trace data (Figure 92) for each clock cycle or for specified events.
Unfilteired Trace is useful to export for external parsing; the Trace window displays the
latched program counter (the address of the instruction currently being executed by the
instruction unit), register data, and CPU flags. Disassembled Trace displays the execution
history as a stream of assembly instructions; the Trace window displays the program
counter (PC), op code, and instruction for each clock cycle. Raw Trace displays exactly
what occurs for each clock cycle and is useful for reducing execution time; the Trace
window displays the core state, read register (RR), write register (RW), register address
(Reg Addr), register data (Reg Data), flags, program counter (PC), and stack pointer (SP)
for each clock cycle. A check mark is displayed to the left of the current view in the
Options menu.
UM004407-0104
3 Debugging
Z8 User Manual
156
Figure 90. Unfiltered Trace
Figure 91. Disassembled Trace
UM004407-0104
3 Debugging
Z8 User Manual
157
Figure 92. Raw Trace
To trace a specified number of clock cycles, use the following procedure:
1. Make sure that there is no check mark to the left of the Event System command in the
Edit menu. A check mark indicates that the event system is enabled.
Debug mode.
) or Reset button (
3. Click the Trace Window button (
) on the Build toolbar to switch to
).
The Trace window is displayed.
4. Click Clear Trace to delete old trace data.
5. Run the project past the point that you want to examine closely and then click the
Break button (
).
6. Enter the number of clock cycles (frames) that you want to trace in the Get Frames
field.
The maximum number of frames available is 65536 (64K).
computer.
8. Click Options to display the Options menu.
9. Select Show Unfiltered Trace, Show Disassembled Trace, or Show Raw Trace to
switch to unfiltered trace data, disassembled trace data, or raw trace data. Doubleclick on a line of data in the Trace window to highlight the corresponding line of Code
in the Edit window.
UM004407-0104
3 Debugging
Z8 User Manual
158
10. To save your trace data, select Save Trace to File.
The Save Trace Data File dialog box (Figure 93) is displayed.
Figure 93. Save Trace Data File Dialog Box
11. Use the Look In drop-down list box to navigate to the appropriate folder.
12. Enter the file name in the File Name field.
13. Click Save.
The trace data are saved as a text file.
UM004407-0104
3 Debugging
Z8 User Manual
159
4. Select the check boxes in the When area to specify the events that you want traced:
If you select the Program Counter or any of the ports, enter a number in the Mask field
to specify a single data point or a range of data. Entering 00 in a Mask field for a port
indicates “Don’t Care,” and the port is ignored.
If you select the Trigger In check box, select 0 or 1 for the trigger.
5. Select the Break button if you want a break after the event is traced or select the Event
Position in Buffer button to control how much is traced.
6. Click OK.
UM004407-0104
).
3 Debugging
Z8 User Manual
160
).
computer.
Note: When you have specified events to be traced in the Trace and Event System dialog
box, you can disable or enable them by selecting Event System from the Edit
menu.
USING BREAKPOINTS
This section to describes how to work with breakpoints while you are debugging. The following topics are covered:
•
•
•
•
•
•
“Inserting Breakpoints” on page 160
“Viewing Breakpoints” on page 161
“Moving to a Breakpoint” on page 162
“Enabling Breakpoints” on page 162
“Disabling Breakpoints” on page 162
“Removing Breakpoints” on page 163
Inserting Breakpoints
There are three ways to place a breakpoint in your file:
•
Click on the line of code where you want to insert the breakpoint. You can set a
breakpoint in any line with a blue dot displayed to the left of the line (shown in Debug
mode only).
Click the Insert/Remove Breakpoint button (
) on the Build or Debug toolbar.
•
Click on the line where you want to add a breakpoint and select Insert Breakpoint
from the right-click menu. You can set a breakpoint in any line with a blue dot
displayed to the left of the line (shown in Debug mode only).
•
Double-click in the gutter to the left of the line where you want to add a breakpoint.
You can set a breakpoint in any line with a blue dot displayed to the left of the line
(shown in Debug mode only).
A red octagon shows that you have set a breakpoint at that location (see Figure 95).
UM004407-0104
3 Debugging
Z8 User Manual
161
Figure 95. Setting a Breakpoint
Viewing Breakpoints
There are two ways to view breakpoints in your project:
•
Select Breakpoints from the Edit menu to display the Breakpoints dialog box
(Figure 96).
•
Select Edit Breakpoints from the right-click menu to display the Breakpoints dialog
box.
You can use the Breakpoints dialog box to view, go to, enable, disable, or remove breakpoints in an active project when in or out of Debug mode.
Figure 96. Viewing Breakpoints
UM004407-0104
3 Debugging
Z8 User Manual
162
Moving to a Breakpoint
To quickly move the cursor to a breakpoint you have previously set in your project, do the
following:
1. Select Breakpoints from the Edit menu.
The Breakpoints dialog box is displayed.
2. Highlight the breakpoint you want.
3. Click Go to Code.
Your cursor moves to the line where the breakpoint is set.
Enabling Breakpoints
To make all breakpoints in a project active, do the following:
1. Select Breakpoints from the Edit menu.
The Breakpoints dialog box is displayed.
2. Click Enable All.
Check marks are displayed to the left of all enabled breakpoints.
3. Click OK.
There are three ways to enable one breakpoint:
•
Double-click on the white octagon to remove the breakpoint and then double-click
where the octagon was to enable the breakpoint.
•
Place your cursor in the line in the file where you want to activate a disabled
breakpoint and click the Enable/Disable Breakpoint button on the Build or Debug
toolbar.
•
Place your cursor in the line in the file where you want to activate a disabled
breakpoint and select Enable Breakpoint from the right-click menu.
The white octagon becomes a red octagon to indicate that the breakpoint is enabled.
Disabling Breakpoints
There are two ways to make all breakpoints in a project inactive:
•
Select Breakpoints from the Edit menu to display the Breakpoints dialog box. Click
Disable All. Disabled breakpoints are still listed in the Breakpoints dialog box. Click
OK.
•
Click the Disable All Breakpoints button on the Debug toolbar.
UM004407-0104
3 Debugging
Z8 User Manual
163
There are two ways to disable one breakpoint:
•
Place your cursor in the line in the file where you want to deactivate an active
breakpoint and click the Enable/Disable Breakpoint button on the Build or Debug
toolbar.
•
Place your cursor in the line in the file where you want to deactivate an active
breakpoint and select Disable Breakpoint from the right-click menu.
The red octagon becomes a white octagon to indicate that the breakpoint is disabled.
Removing Breakpoints
There are two ways to delete all breakpoints in a project:
•
Remove All and then click OK. The breakpoints are removed from the Breakpoints
dialog box and the file.
•
Click the Remove All Breakpoints button on the Build or Debug toolbar.
There are four ways to delete one breakpoint:
•
•
Double-click on the red octagon to remove the breakpoint.
Remove and then click OK. The breakpoint is removed from the Breakpoints dialog
box and the file.
•
Place your cursor in the line in the file where there is a breakpoint and click the Insert/
Remove Breakpoint button on the Build or Debug toolbar.
•
Place your cursor in the line in the file where there is a breakpoint and select Remove
Breakpoint from the right-click menu.
USING THE EMULATOR
When you use the Z8 emulator, you can access the following additional ZDS II features:
•
•
“Real-Time Trace System” on page 164
“Complex Breakpoint and Event Detection” on page 167
Set Up the Z8 Emulator
Use the following procedure to set up the emulator:
3. Select Emulator Driver from the Driver drop-down list box.
UM004407-0104
3 Debugging
Z8 User Manual
164
5. Select the appropriate emulator from the Name drop-down list box.
6. Type the IP address in the IP Address field.
7. Type the port number in the TCP Port field.
8. Use the Voltage drop-down list box to select the appropriate target VCC voltage from
9. Select the appropriate clock frequency or enter the clock frequency in the Other field.
10. Click OK to close and save the settings for the Configure Emulator Driver dialog box.
Real-Time Trace System
Trace information is collected for every clock cycle during Debug mode unless the event
system is enabled (by selecting Event System from the Edit menu). To trace a specified
number of clock cycles, use the following procedure:
1. Make sure that there is no check mark to the left of the Event System command in the
Edit menu. A check mark indicates that the event system is enabled.
Debug mode.
) or Reset button (
3. Click the Trace Window button (
) on the Build toolbar to switch to
).
4. Click Clear Trace to delete old trace data.
5. Run the project past the point that you want to examine closely and then click the
Break button (
).
6. Enter the number of clock cycles (frames) that you want to trace in the Get Frames
field.
The maximum number of frames available is 65536 (64K).
computer.
UM004407-0104
3 Debugging
Z8 User Manual
165
8. Click Options to display the Options menu.
9. Select Show Unfiltered Trace, Show Disassembled Trace, or Show Raw Trace to
switch to unfiltered trace data (Figure 97), disassembled trace data (Figure 98), or raw
trace data (Figure 99). Double-click on a line of data in the Trace window to highlight
the corresponding line of Code in the Edit window.
Unfiltered Trace is useful to export for external parsing; the Trace window displays
the latched program counter (the address of the instruction currently being executed
by the instruction unit), register data, and CPU flags. Disassembled Trace displays the
execution history as a stream of assembly instructions; the Trace window displays the
program counter (PC), op code, and instruction for each clock cycle. Raw Trace
displays exactly what occurs for each clock cycle and is useful for reducing execution
time; the Trace window displays the core state, read register (RR), write register
(RW), register address (Reg Addr), register data (Reg Data), flags, program counter
(PC), and stack pointer (SP) for each clock cycle. A check mark is displayed to the left
of the current view in the Options menu.
Figure 97. Unfiltered Trace
UM004407-0104
3 Debugging
Z8 User Manual
166
Figure 98. Disassembled Trace
Figure 99. Raw Trace
10. To save your trace data, select Save Trace to File.
The Save Trace Data File dialog box (Figure 100) is displayed.
Figure 100. Save Trace Data File Dialog Box
11. Use the Look In drop-down list box to navigate to the appropriate folder.
12. Enter the file name in the File Name field.
13. Click Save.
The trace data are saved as a text file.
UM004407-0104
3 Debugging
Z8 User Manual
167
Complex Breakpoint and Event Detection
4. Select the Break When Trace Buffer Is Full check box if you want ZDS II to stop
processor execution each time the Trace buffer fills. This action leads to frequent
breaks in execution for many programs. This feature is not checked by default.
5. Select an event in the list box.
You can specify up to four events.
UM004407-0104
3 Debugging
Z8 User Manual
168
6. For each event, do the following:
a. Select the check boxes in the When area to specify the events that you want
traced.
If you select the Program Counter, Register Address, or Register Data check box,
enter a number in the Mask field to specify a single data point or a range of data.
If you select the Flags check box, select which flags to use. Enter a number in the
corresponding Mask field to specify a single data point or a range of data.
b. Select the check boxes in the Then area to specify which actions to perform. If
you want to specify multiple events, select the Arm Next Event check box.
7. Click OK.
).
).
The Trace window is displayed. For more information about using the Trace window,
see “Trace Window” on page 155.
computer.
Note: When you have specified events to be traced in the Trace and Event System dialog
box, you can disable or enable them by selecting Event System from the Edit
menu.
UM004407-0104
3 Debugging
Z8 User Manual
169
4
Using the ANSI C-Compiler
This chapter provides you information on writing C programs with the ANSI C-Compiler:
•
•
•
•
•
•
•
“Using the Run-Time Library” on page 170
“Run-Time Library Functions” on page 186
“Setting C-Compiler Options Using #Pragmas” on page 243
“Embedding Assembly in C” on page 246
“Calling Assembly from C” on page 248
“Troubleshooting C Programs” on page 250
“Error Messages” on page 254
For more information on using the compiler in the developer’s environment, refer to
Chapter 1, “Getting Started,” starting on page 1 and Chapter 2, “Main Components,” starting on page 53.
Note: The Z8 C-Compiler is optimized for embedded applications in which execution speed and
code size are crucial. Consequently, it does not support returning a struct by value from a
function. Instead, use the more efficient coding style of passing a pointer to the struct,
which allows the called function to modify the struct that is pointed to.
UM004407-0104
4 Using the ANSI C-Compiler
Z8 User Manual
170
USING THE RUN-TIME LIBRARY
The ANSI C-Compiler provides a collection of run-time libraries for use with your C programs. The following sections describe the use and format of the run-time libraries.
Each library function is declared in a header. The #include preprocessor directive makes
the header's contents available. The header declares a set of related functions plus any necessary types and additional macros needed to facilitate their use. All external identifiers
declared in any of the headers are reserved, whether or not the associated header is
included. All external identifiers and macro names that begin with an underscore are also
reserved. If the program redefines a reserved external identifier, even with a semantically
equivalent form, the behavior is indeterminate.
Note: The run-time library routines were compiled using the static frames and are not reentrant
for the sake of efficient code. If you want to recompile the files for reentrancy, then add the
source files to your project as any other source file.
Some run-time library routines are large and must not be used in small model. These
include printf, strtok, strcat, tan, sin, cos, and pow. You need to be careful when
adding run-time routines to a small model project.
Standard and nonstandard headers are listed in Table 14 and Table 15 and described in the
following sections.
Table 14. Standard Headers
Header
Description
Page
<errno.h>
Errors
page 171
<stddef.h>
Standard defines
page 171
<assert.h>
Diagnostics
page 172
<ctype.h>
Character-handling functions
page 173
<limits.h>
Integer limits
page 174
<float.h>
Floating-point limits
page 175
<math.h>
Math functions
page 176
<setjmp.h>
Nonlocal jump functions
page 178
<stdarg.h>
Variable arguments functions
page 179
<stdio.h>
Standard input/output functions
page 180
<stdlib.h>
General utilities functions
page 180
<string.h>
String-handling functions
page 182
UM004407-0104
Z8 User Manual
171
Table 15. Nonstandard Headers
Header
Description
Page
<sio.h>
Nonstandard IO functions
page 184
<Z8.h>
Z8-specific functions and defines
page 185
If a file with any of these names, not provided as part of the compiler, is placed in any of
the standard places for a source file to be included, the behavior is undefined.
Headers can be included in any order; each can be included more than once in a given
scope, with no adverse effect. Headers are included in the code before the first reference to
any of the functions it declares, types or macros it defines.
Note: The include header files are located in the following directory:
ZILOGINSTALL\ZDSII_product_version\include\
Errors <errno.h>
The <errno.h> header defines macros relating to the reporting of error conditions.
Macros
EDOM
Expands to a distinct nonzero integral constant expression.
ERANGE
Expands to a distinct nonzero integral constant expression.
errno
Expands to a modifiable value that has type volatile int, the value of which is set
to a positive error number by several library functions. It is initialized to zero at
program startup, but is never set to zero by any library function. The value of
errno can be set to nonzero by a library function call whether or not there is an
error, provided the use of errno is not documented in the description of the
function in the Standard.
Additional macro definitions, beginning with E and an uppercase letter, can also be specified by the implementation.
Standard Definitions <stddef.h>
The following types and macros are defined in several headers referred to in the descriptions of the functions declared in that header, as well as the common <stddef.h> standard header.
UM004407-0104
Z8 User Manual
172
Types
ptrdiff_t
Signed integral type of the result of subtracting two pointers.
size_t
Unsigned integral type of the result of the sizeof operator.
wchar_t
Integral type whose range of values can represent distinct codes for all
members of the largest extended character set specified among the
supported locales.
Macros
errno
Expands to a modifiable value that has type volatile int, the value of
which is set to a positive error number by several library functions. It is
initialized to zero at program startup, but is never set to zero by any
library function. The value of errno can be set to nonzero by a library
function call whether or not there is an error, provided the use of errno
is not documented in the description of the function in the Standard.
NULL
Expands to a null pointer constant.
offsetof(type, identifier)
The offset in bytes, from the beginning of a structure designated by
type, to the member designated by identifier.
Diagnostics <assert.h>
The <assert.h> header declares one macro and refers to another macro.
Macro
NDEBUG
Is not defined by <assert.h>. If NDEBUG is defined at the point in the
source file where <assert.h> is included, use of the assert macro has no
effect.
Function
void assert(int expression);
UM004407-0104
Tests for logic error.
Z8 User Manual
173
Character Handling <ctype.h>
The <ctype.h> header declares several functions useful for testing and mapping characters. In all cases the argument is an int, the value of which is represented as an unsigned
char or equals the value of the macro EOF. If the argument has any other value, the behavior is undefined.
Functions
The functions in this section return nonzero (true) if, and only if, the value of the argument
c conforms to that in the description of the function. The term printing character refers to
a member of a set of characters, each of which occupies one printing position on a display
device. The term control character refers to a member of a set of characters that are not
printing characters.
Character Testing
int isalnum(int c);
Tests for alphanumeric character.
int isalpha(int c);
Tests for alphabetic character.
int iscntrl(int c);
Tests for control character.
int isdigit(int c);
Tests for decimal digit.
int isgraph(int c);
Tests for printable character except space.
int islower(int c);
Tests for lowercase character.
int isprint(int c);
Tests for printable character.
int ispunct(int c);
Tests for punctuation character.
int isspace(int c);
Tests for white-space character.
int isupper(int c);
Tests for uppercase character.
int isxdigit(int c);
Tests for hexadecimal digit.
Character Case Mapping
int tolower(int c);
Tests character and converts to lowercase if uppercase.
int toupper(int c);
Tests character and converts to uppercase if lowercase.
UM004407-0104
Z8 User Manual
174
Limits <limits.h>
The <limits.h> header defines macros that expand to various limits and parameters.
Sizes of Integral Types
CHAR_BIT
Maximum number of bits for smallest object that is not a bit-field (byte).
CHAR_MAX
Maximum value for an object of type char.
CHAR_MIN
Minimum value for an object of type char.
INT_MAX
Maximum value for an object of type int.
INT_MIN
Minimum value for an object of type int.
LONG_MAX
Maximum value for an object of type long int.
LONG_MIN
Minimum value for an object of type long int.
SCHAR_MAX
Maximum value for an object of type signed char.
SCHAR_MIN
Minimum value for an object of type signed char.
SHRT_MAX
Maximum value for an object of type short int.
SHRT_MIN
Minimum value for an object of type short int.
UCHAR_MAX
Maximum value for an object of type unsigned char.
UINT_MAX
Maximum value for an object of type unsigned int.
ULONG_MAX
Maximum value for an object of type unsigned long int.
USHRT_MAX
Maximum value for an object of type unsigned short int.
If the value of an object of type char sign-extends when used in an expression, the value of
CHAR_MIN is the same as that of SCHAR_MIN and the value of CHAR_MAX is the
same as that of SCHAR_MAX.
If the value of an object of type char does not sign-extend when used in an expression, the
value of CHAR_MIN is 0 and the value of CHAR_MAX is the same as that of
UCHAR_MAX.
UM004407-0104
Z8 User Manual
175
Floating Point <float.h>
The <float.h> header defines macros that expand to various limits and parameters.
Characteristics of Floating Types
DBL_DIG
Number of decimal digits of precision.
DBL_MANT_DIG
Number of base-FLT_RADIX digits in the floating-point mantissa
DBL_MAX
Maximum represented floating-point numbers.
DBL_MAX_EXP
Maximum integer such that FLT_RADIX raised to that power
approximates a floating-point number in the range of represented
numbers.
DBL_MAX_10_EXP
Maximum integer such that 10 raised to that power approximates a
floating-point number in the range of represented value
((int)log10(FLT_MAX), and so on).
DBL_MIN
Minimum represented positive floating-point numbers.
DBL_MIN_EXP
Minimum negative integer such that FLT_RADIX raised to that power
approximates a positive floating-point number in the range of
represented numbers.
DBL_MIN_10_EXP
Minimum negative integer such that 10 raised to that power
represented values ((int)log10(FLT_MIN), and so on).
FLT_DIG
FLT_MANT_DIG
Number of base-FLT_RADIX digits in the floating-point mantissa.
FLT_MAX
FLT_MAX_EXP
numbers.
FLT_MAX_10_EXP
FLT_MIN
FLT_MIN_EXP
represented numbers
FLT_MIN_10_EXP
FLT_RADIX
Radix of exponent representation.
UM004407-0104
Z8 User Manual
176
FLT_ROUND
Rounding mode for floating-point addition.
-1 indeterminable
0 toward zero
1 to nearest
2 toward positive infinity
3 toward negative infinity
LDBL_DIG
LDBL_MANT_DIG
Number of base-FLT_RADIX digits in the floating-point mantissa.
LDBL_MAX
LDBL_MAX_EXP
numbers.
LDBL_MAX_10_EXP
LDBL_MIN
LDBL_MIN_EXP
represented numbers.
LDBL_MIN_10_EXP
Mathematics <math.h>
The <math.h> header declares several mathematical functions and defines three macros.
The functions take double-precision arguments and return double-precision values. Integer
arithmetic functions and conversion functions are discussed later.
Macros
EDOM
Expands to distinct nonzero integral constant expressions.
ERANGE
HUGE_VAL
Expands to a positive double expression, not necessarily represented as a
float.
UM004407-0104
Z8 User Manual
177
Treatment of Error Conditions
The behavior of each of these functions is defined for all values of its arguments. Each
function must return as if it were a single operation, without generating any externally visible exceptions.
For all functions, a domain error occurs if an input argument to the function is outside the
domain over which the function is defined. On a domain error, the function returns a specified value; the integer expression errno acquires the value of the macro EDOM.
Similarly, a range error occurs if the result of the function cannot be represented as a double value. If the result overflows (the magnitude of the result is so large that it cannot be
represented in an object of the specified type), the function returns the value of the macro
HUGE_VAL, with the same sign as the correct value of the function; the integer expression errno acquires the value of the macro ERANGE. If the result underflows (the magnitude of the result is so small that it cannot be represented in an object of the specified
type), the function returns zero.
Functions
Trigonometric
double acos(double x);
Calculates arc cosine of x.
double asin(double x)
Calculates arc sine of x.
double atan(double x);
Calculates arc tangent of x.
double atan2(double y, double x);
Calculates arc tangent of y/x.
double cos(double x);
Calculates cosine of x.
double sin(double x);
Calculates sine of x.
double tan(double x);
Calculates tangent of x.
Hyperbolic
double cosh(double x);
Calculates hyperbolic cosine of x.
double sinh(double x);
Calculates hyperbolic sine of x.
double tanh(double x);
Calculates hyperbolic tangent of x.
UM004407-0104
Z8 User Manual
178
Exponential and Logarithmic
double exp(double x);
Calculates exponential function of x.
double frexp(double value, int *exp);
Shows x as product of mantissa (the value returned by
frexp) and 2 to the n.
double ldexp(double x, int exp);
Calculates x times 2 to the exp.
double log(double x);
Calculates natural logarithm of x.
double log10(double x);
Calculates base 10 logarithm of x.
double modf(double value,
double *iptr);
Breaks down x into integer (the value returned by modf)
and fractional (n) parts.
Power
double pow(double x, double y);
Calculates x to the y.
double sqrt(double x);
Finds square root of x.
Nearest Integer, abs
remdouble ceil(double x);
Finds integer ceiling of x.
double fabs(double x);
Finds absolute value of x.
double floor(double x);
Finds largest integer less than or equal to x.
double fmod(double x,double y);
Finds floating-point remainder of x/y.
Nonlocal Jumps <setjmp.h>
The <setjmp.h> header declares two functions and one type, for bypassing the normal
function call and return discipline.
Type
jmp_buf
UM004407-0104
An array type suitable for holding the information needed to restore a
calling environment.
Z8 User Manual
179
Functions
int setjmp(jmp_buf env);
Saves a stack environment.
void longjmp(jmp_buf env, int val);
Restores a saved stack environment.
Variable Arguments <stdarg.h>
The <stdarg.h> header declares a type and a function and defines two macros, for
advancing through a list of arguments whose number and types are not known to the called
function when it is translated.
A function can be called with a variable number of arguments of varying types. “Function
Definitions” parameter list contains one or more parameters. The rightmost parameter
plays a special role in the access mechanism and is designated parmN in this description.
Type
va_list
An array type suitable for holding information needed by the macro va_arg and the
function va_end. The called function declares a variable (referred to as ap in this
section) having type va_list. The variable ap can be passed as an argument to another
function.
Variable Argument List Access Macros and Function
The va_start and va_arg macros described in this section are implemented as macros,
not as real functions. If #undef is used to remove a macro definition and obtain access to
a real function, the behavior is undefined.
Functions
void va_start(va_list ap, parmN);
Sets pointer to beginning of argument list.
type va_arg (va_list ap, type);
Retrieves argument from list.
void va_end(va_list ap);
Resets pointer.
UM004407-0104
Z8 User Manual
180
Input/Output <stdio.h>
The <stdio.h> header declares input and output functions.
Functions
Formatted Input/Output
int printf(const char *format, ...);
Writes formatted data to stdout.
int scanf(const char *format, ...);
Reads formatted data from stdin.
int sprintf(char *s, const char *format, ...);
Writes formatted data to string.
int sscanf(const char *s, const char *format, ...);
Reads formatted data from string.
int vsprintf(char *s, const char *format, va_list arg);
Writes formatted data to a string.
Character Input/Output
int getchar(void);
Reads a character from stdin.
char *gets(char *s);
Reads a line from stdin.
int putchar(int c);
Writes a character to stdout (macro version).
int puts(const char *s);
Writes a line to stdout.
General Utilities <stdlib.h>
The <stdlib.h> header declares several types, functions of general utility, and macros.
Types
div_t
Structure type that is the type of the value returned by the div function.
ldiv_t
Structure type that is the type of the value returned by the ldiv function.
size_t
wchar_t
Integral type whose range of values can represent distinct codes for all members of
the largest extended character set specified among the supported locales.
UM004407-0104
Z8 User Manual
181
Macros
EDOM
ERANGE
HUGE_VAL
Expands to a positive double expression, not necessarily represented as a
float.
MB_CUR_MAX
Expands to a positive integer expression whose value is the maximum
number of bytes in multi-byte character for the extended character set
specified by the current locale.
NULL
RAND_MAX
Expands to an integral constant expression, the value of which is the
maximum value returned by the rand function.
Functions
String Conversion
The functions atof, atoi, and atol do not affect the value of the macro errno on an
error. If the result cannot be represented, the behavior is undefined.
double atof(const char *nptr);
Converts string to float.
int atoi(const char *nptr);
Converts string to int.
long int atol(const char *nptr);
Converts string to long.
double strtod(const char *nptr, char **endptr);
Converts string pointed to by nptr to a
double.
long int strtol(const char *nptr,char **endptr, int base); Converts string to a long decimal integer
that is equal to a number with the
specified radix.
Pseudorandom Sequence Generation
int rand(void)
Gets a pseudorandom number.
void srand(unsigned int seed);
Initializes pseudorandom series.
Memory Management
The order and contiguity of storage allocated by successive calls to the calloc, malloc,
and realloc functions are unspecified. The pointer returned if the allocation succeeds is
suitably aligned so that it can be assigned to a pointer to any type of object and then used
UM004407-0104
Z8 User Manual
182
to access such an object in the space allocated (until the space is explicitly freed or reallocated).
void *calloc(size_t nmemb, size_t size);
Allocates storage for array.
void free(void *ptr);
Frees a block allocated with calloc, malloc, or realloc.
void *malloc(size_t size);
Allocates a block.
void *realloc(void *ptr, size_t size);
Reallocates a block.
Searching and Sorting Utilities
void *bsearch(const void *key, const void *base, size_t nmemb, size_t Performs binary search.
size, int (*compar)(const void *,const void *));
void qsort(void *base, size_t nmemb, size_t size, int (*compar)(const
void *, const void *));
Performs quick sort.
Integer Arithmetic
int abs(int j);
Finds absolute value of integer value.
div_t div(int numer, int denom);
Computes integer quotient and remainder.
long int labs(long int j);
Finds absolute value of long integer value.
ldiv_t ldiv(long int numer, long int denom);
Computes long quotient and remainder.
String Handling <string.h>
The <string.h> header declares several functions useful for manipulating character
arrays and other objects treated as character arrays. Various methods are used for determining the lengths of arrays, but in all cases a char* or void* argument points to the initial
(lowest addressed) character of the array. If an array is written beyond the end of an object,
the behavior is undefined.
Type
size_t
Macro
NULL
UM004407-0104
Z8 User Manual
183
Functions
Copying
void *memcpy(void *s1, const void *s2, size_t n);
Copies a specified number of characters
from one buffer to another.
void *memmove(void *s1, const void *s2, size_t n); Moves a specified number of characters
from one buffer to another.
char *strcpy(char *s1, const char *s2);
Copies one string to another.
char *strncpy(char *s1, const char *s2, size_t n);
Copies n characters of one string to another.
Concatenation
char *strcat(char *s1, const char *s2);
Appends a string.
char *strncat(char *s1, const char *s2, size_t n);
Appends n characters of string.
Comparison
The sign of the value returned by the comparison functions is determined by the sign of
the difference between the values of the first pair of characters that differ in the objects
being compared.
int memcmp(const void *s1, const void *s2, size_t n);
Compares the first n characters.
int strcmp(const char *s1, const char *s2);
Compares two strings.
int strncmp(const char *s1, const char *s2, size_t n);
Compares n characters of two strings.
UM004407-0104
Z8 User Manual
184
Search
void *memchr(const void *s, int c, size_t n);
Returns a pointer to the first occurrence, within
a specified number of characters, of a given
character in the buffer.
char *strchr(const char *s, int c);
Finds first occurrence of a given character in
string.
size_t strcspn(const char *s1, const char *s2);
Finds first occurrence of a character from a
given character in string.
char *strpbrk(const char *s1, const char *s2);
Finds first occurrence of a character from one
string to another.
char *strrchr(const char *s, int c);
Finds last occurrence of a given character in
string.
size_t strspn(const char *s1, const char *s2);
Finds first substring from a given character set
in string.
char *strstr(const char *s1, const char *s2);
Finds first occurrence of a given string in
another string.
char *strtok(char *s1, const char *s2);
Finds next token in string.
Miscellaneous
void *memset(void *s, int c, size_t n);
Uses a given character to initialize a specified
number of bytes in the buffer.
size_t strlen(const char *s);
Finds length of string.
Nonstandard I/O Functions <sio.h>
This header contains some input/output functions whose use is nonstandard.
Functions
int kbhit(void);
Returns number of characters waiting at the UART.
int getch(void);
Returns the next key stroke at the UART.
int getche(void);
Returns the next character at the UART after echoing it.
void init_uart(void);
Initialize the Z8 UART.
void putch(char);
Sends a character to the UART.
UM004407-0104
Z8 User Manual
185
Architecture-Specific Functions <Z8.h>
The Z8 has many special function registers (SFRs) and bits that are hard to manage. Z8.h
defines macros and structures that make using the Z8 architecture easier.
Interrupt-Handling Macros
EI ( )
Enable interrupts macro.
DI ( )
Disable interrupts macro.
SET_VECTOR (vec,func) Set interrupt vector macro.
RESET
Reset vector
IRQ0
Interrupt request zero
IRQ1
Interrupt request one
IRQ2
Interrupt request two
IRQ3
Interrupt request three
IRQ4
Interrupt request four
IRQ5
Interrupt request five
SET_REG (regnum,val)
Set working register intrinsic. regnum must be one of: R0, R1,
R2,...R15.
SET_RREG (regnum,val) Set working register pair intrinsic. regnum must be one of: RR0, RR2,
RR4,...RR14.
GET_REG (regnum)
Get value of a working register. regnum must be one of: R0, R1,
...R15.
GET_RREG (regnum)
Get value of a working register pair. regnum must be one of: RR0,
RR2, RR4,...RR14.
SET_ERF (regnum,val)
Set ERF intrinsic.
GET_ERF (regnum,)
Get value of an ERF intrinsic.
Special Function Register Macros
SPL
Stack pointer bits 7-0
RP
Register pointer
FLAGS
Program control flags
IMR
Interrupt mask register
IRQ
Interrupt register request
UM004407-0104
Z8 User Manual
186
IPR
Interrupt priority register
P01M
Ports 0 & 1 mode
P2M
Port 2 mode
P3M
Port 3 mode
PRE0
T0 prescalar
T0
Timer/counter 0
PRE1
T1 prescalar
T1
Timer mode
RUN-TIME LIBRARY FUNCTIONS
This section covers the following:
abs
acos
asin
assert
atan
atan2
atof
atoi
atol
bsearch
calloc
ceil
cos
cosh
DI
div
EI
exp
fabs
floor
fmod
free
frexp
GET_ERF
GET_REG
GET_RREG
getch
getche
getchar
gets
init_uart
isalnum
isalpha
iscntrl
isdigit
isgraph
islower
isprint
ispunct
isspace
isupper
isxdigit
kbhit
labs
ldexp
ldiv
log
log10
longjmp
malloc
memchr
memcmp
memcpy
memmove
memset
modf
pow
printf
putch
putchar
puts
qsort
rand
realloc
scanf
SET_ERF
setjmp
SET_VECTOR
sin
sinh
sprintf
sqrt
srand
sscanf
strcat
strchr
strcmp
strcpy
strcspn
strlen
strncat
strncmp
strncpy
strpbrk
strrchr
strspn
strstr
strtod
strtok
strtol
tan
tanh
tolower
toupper
va_arg
UM004407-0104
Z8 User Manual
187
va_end
va_start
vprintf
vsprintf
abs
Computes the absolute value of an integer j. If the result cannot be represented, the behavior is undefined.
Synopsis
#include <stdlib.h>
int abs(int j);
Returns
The absolute value.
Example
int I=-5632;
int j;
j=abs(I);
acos
Computes the principal value of the arc cosine of x. A domain error occurs for arguments
not in the range [-1,+1].
Synopsis
#include <math.h>
double acos(double x);
Returns
The arc cosine in the range [0, pi].
Example
double y=0.5635;
double x;
x=acos(y)
UM004407-0104
Z8 User Manual
188
asin
Computes the principal value of the arc sine of x. A domain error occurs for arguments not
in the range [-1,+1].
Synopsis
#include <math.h>
double asin(double x);
Returns
The arc sine in the range [-pi/2,+pi/2].
Example
double y=.1234;
double x;
x = asin(y);
assert
Puts diagnostics into programs. When it is executed, if expression is false (that is, evaluates to zero), the assert macro writes information about the particular call that failed
(including the text of the argument, the name of the source file, and the source line number—the latter are respectively the values of the preprocessing macros __FILE__ and
__LINE__) on the serial port via the putch() function. It then loops forever.
Synopsis
#include <assert.h>
void assert(int expression);
Returns
If expression is true (that is, evaluates to nonzero), the assert macro returns no value.
Example
char str[]="COMPASS";
assert(str!=0);
UM004407-0104
Z8 User Manual
189
atan
Computes the principal value of the arc tangent of x.
Synopsis
#include <math.h>
double atan(double x);
Returns
The arc tangent in the range (-pi/2, +pi/2).
Example
double y=.1234;
double x;
x=atan(y);
atan2
Computes the principal value of the arc tangent of y/x, using the signs of both arguments
to determine the quadrant of the return value. A domain error occurs if both arguments are
zero.
Synopsis
#include <math.h>
double atan2(double y, double x);
Returns
The arc tangent of y/x, in the range [-pi, +pi].
Example
double y=.1234;
double x;
x=atan2(y);
atof
Converts the string pointed to by nptr to double representation. Except for the behavior on
error, it is equivalent to strtod (nptr, (char **)NULL).
Synopsis
#include <stdlib.h>
double atof(char *nptr);
UM004407-0104
Z8 User Manual
190
Returns
The converted value.
Example
char str []="1.234";
double x;
x= atof(str);
atoi
Converts the string pointed to by nptr to int representation. Except for the behavior on
error, it is equivalent to (int)strtol(nptr, (char **)NULL, 10).
Synopsis
#include <stdlib.h>
int atoi(char *nptr);
Returns
Example
char str []="50";
int x;
x=atoi(str);
atol
Converts the string pointed to by nptr to long int representation. Except for the behavior
on error, it is equivalent to strtol(nptr, (char **)NULL, 10).
Synopsis
#include <stdlib.h>
long int atol(char *nptr);
Returns
Example
char str[]="1234567";
long int x;
x=atol(str);
UM004407-0104
Z8 User Manual
191
bsearch
Searches an array of nmemb objects, the initial member of which is pointed to by base, for
a member that matches the object pointed to by key. The size of each object is specified by
size.
The array has been previously sorted in ascending order according to a comparison function pointed to by compar, which is called with two arguments that point to the objects
being compared. The function returns an integer less than, equal to, or greater than zero if
the first argument is considered to be respectively less than, equal to, or greater than the
second.
Synopsis
#include <stdlib.h>
void *bsearch(void *key, void *base,
size_t nmemb, size_t size,
int (*compar)(void *, void *));
Returns
A pointer to the matching member of the array or a null pointer, if no match is found.
Example
int 1st[]={2,5,8,9};
int k=8;
int compare (int x, int y);
int *result;
result = bsearch(&k, 1st, 4, sizeof(int), compare);
calloc
Allocates space for an array of nmemb objects, each of whose size is size. The space is initialized to all bits zero.
Synopsis
#include <stdlib.h>
void *calloc(size_t nmemb, size_t size);
Returns
A pointer to the start (lowest byte address) of the allocated space. If the space cannot be
allocated, or if nmemb or size is zero, the calloc function returns a null pointer.
Example
char *buf;
buf = (char*)calloc(40, sizeof(char));
UM004407-0104
Z8 User Manual
192
if (buf != NULL)
/*success*/
else
/*fail*/
ceil
Computes the smallest integer not less than x.
Synopsis
#include <math.h>
double ceil(double x);
Returns
The smallest integer not less than x, expressed as a double.
Example
double y=1.45;
double x;
x=ceil(y);
cos
Computes the cosine of x (measured in radians). A large magnitude argument can yield a
result with little or no significance.
Synopsis
#include <math.h>
double cos(double x);
Returns
The cosine value.
Example
double y=.1234;
double x;
x=cosh(y)
UM004407-0104
Z8 User Manual
193
cosh
Computes the hyperbolic cosine of x. A range error occurs if the magnitude of x is too
large.
Synopsis
#include <math.h>
double cosh(double x);
Returns
The hyperbolic cosine value.
Example
double y=.1234;
double x
x=cosh(y);
DI
The DI macro is a Z8 family specific macro that embeds assembly language instructions
into C source code which when executed disables all interrupts.
Synopsis
#include <Z8.h>
void DI(void);
Example
#include <Z8.h>
extern interrupt void reset(void);
void main(void)
{
SET_VECTOR(RESET,reset);
DI();
...
EI();
}
/*
/*
/*
/*
setup reset vector */
disable interrupts */
initialize system */
enable interrupts */
Note: The DI macro is a nonstandard feature of the Z8 compiler.
UM004407-0104
Z8 User Manual
194
div
Computes the quotient and remainder of the division of the numerator numer by the
denominator denom. If the division is inexact, the sign of the quotient is that of the mathematical quotient, and the magnitude of the quotient is the largest integer less than the magnitude of the mathematical quotient.
Synopsis
#include <stdlib.h>
div_t div(int numer, int denom);
Returns
A structure of type div_t, comprising both the quotient and the remainder. The structure
contains the following members, in either order:
int quot;
int rem;
/* quotient */
/* remainder */
Example
int x=25;
int y=3;
div_t t;
int q;
int r;
t=div (x,y);
q=t.quot;
r=t.rem;
EI
The EI macro is an Z8 family specific macro that embeds assembly language instructions
into C source code which when executed enables all interrupts.
Synopsis
#include <Z8.h>
void EI(void);
UM004407-0104
Z8 User Manual
195
Example
#include <Z8.h>
void main(void)
{
SET_VECTOR(RESET,reset);
DI();
...
EI();
}
/*
/*
/*
/*
setup reset vector */
disable interrupts */
initialize system */
enable interrupts */
Note: The EI intrinsic is a nonstandard feature of the Z8 compiler.
exp
Computes the exponential function of x. A range error occurs if the magnitude of x is too
large.
Synopsis
#include <math.h>
double exp(double x);
Returns
The exponential value.
Example
double y=.1234;
double x;
x=exp(y)
fabs
Computes the absolute value of a floating-point number x.
Synopsis
#include <math.h>
double fabs(double x);
Returns
The absolute value of x.
UM004407-0104
Z8 User Manual
196
Example
double y=6.23;
double x;
x=fabs(y);
floor
Computes the largest integer not greater than x.
Synopsis
#include <math.h>
double floor(double x);
Returns
The largest integer not greater than x, expressed as a double.
Example
double y=6.23;
double x;
x=floor(y);
fmod
Computes the floating-point remainder of x/y. If the quotient of x/y cannot be represented,
the behavior is undefined.
Synopsis
#include <math.h>
double fmod(double x, double y);
Returns
The value of x if y is zero. Otherwise, it returns the value f, which has the same sign as x,
such that x - i * y + f for some integer i, where the magnitude of f is less than the magnitude of y.
Example
double y=7.23;
double x=2.31;
double z;
z=fmod(y,x);
UM004407-0104
Z8 User Manual
197
fprintf
Writes output to the specified output, under control of the string pointed to by format that
specifies how subsequent arguments are converted for output.
A format string contains two types of objects: plain characters and conversion specifications, each of which fetch zero or more subsequent arguments. The results are undefined if
there are insufficient arguments for the format. If the format is exhausted while arguments
remain, the excess arguments are evaluated but otherwise ignored. The fprintf function
returns when the end of the format string is encountered.
Each conversion specification is introduced by the character %. After the %, the following
appear in sequence:
•
•
Zero or more flags that modify the meaning of the conversion specification.
•
An optional precision that gives the minimum number of digits to appear for the d, i,
o, u, x, and X conversions, the number of digits to appear after the decimal point for e,
E, and f conversions, the maximum number of significant digits for the g and G
conversions, or the maximum number of characters to be written from a string in s
conversion. The precision takes the form of a period (.) followed by an optional
decimal integer; if the integer is omitted, it is treated as zero. The amount of padding
specified by the precision overrides that specified by the field width.
•
An optional h specifies that a following d, i, o, u, x, or X conversion character applies
to a short_int or unsigned_short_unt argument (the argument has been promoted
according to the integral promotions, and its value is converted to short_int or
unsigned_short_int before printing). An optional l (ell) specifies that a following d, i,
o, u, x or X conversion character applies to a long_int or unsigned_long_int argument.
An optional L specifies that a following e, E, f, g, or G conversion character applies to
a long_double argument. If an h, l, or L appears with any other conversion character, it
is ignored.
•
•
A character that specifies the type of conversion to be applied.
An optional decimal integer specifying a minimum field width. If the converted value
has fewer characters than the field width, it is padded on the left (or right, if the left
adjustment flag, described later, has been given) to the field width. The padding is
with spaces unless the field width integer starts with a zero, in which case the padding
is with zeros.
A field width or precision, or both, can be indicated by an asterisk * instead of a digit
string. In this case, an int argument supplies the files width or precision. The
arguments specifying field width or precision displays before the argument (if any) to
be converted. A negative field width argument is taken as a - flag followed by a
positive field width. A negative precision argument is taken as if it were missing.
Note: For more specific information on the flag characters and conversion characters for the
fprintf function, see “fprintf Flag Characters” on page 198.
UM004407-0104
Z8 User Manual
198
Synopsis
#include <stdio.h>
int fprintf(output, char *format, ...);
Returns
The number of characters transmitted or a negative value if an output error occurred.
Example
fprintf(stdout, "Hello world\n");
fprintf Flag Characters
-
The result of the conversion is left-justified within the field.
+
The result of a signed conversion always begins with a plus or a minus sign.
space
If the first character of a signed conversion is not a sign, a space is added before the result.
If the space and + flags both appear, the space flag is ignored
#
The result is to be converted to an ''alternate form''. For c, d, i, s, and u conversions, the
flag has no effect. For o conversion, it increases the precision to force the first digit of the
result to be a zero. For x (or X) conversion, a nonzero result always contains a decimal
point, even if no digits follow the point (normally, a decimal point appears in the result of
these conversions only if a digit follows it). For g and G conversions, trailing zeros are not
removed from the result, as they normally are.
fprintf Conversion Characters
d,i,o,u,x,X
The int argument is converted to signed decimal (d or i), unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (x or X); the letters
abcdef are used for x conversion and the letters ABCDEF for X conversion. The
precision specifies the minimum number of digits to appear; if the value being
converted can be represented in fewer digits, it is expanded with leading zeros.
The default precision is 1. The result of converting a zero value with a precision of
zero is no characters.
f
The double argument is converted to decimal notation in the style [-]ddd.ddd,
where the number of digits after the decimal point is equal to the precision
specification. If the precision is missing, it is taken as 6; if the precision is
explicitly zero, no decimal point appears. If a decimal point appears, at least one
digit appears before it. The value is rounded to the appropriate number of digits.
UM004407-0104
Z8 User Manual
199
e,E
The double argument is converted in the style [-]d.ddde+dd, where there is one
digit before the decimal point and the number of digits after it is equal to the
precision; when the precision is missing, six digits are produced; if the precision is
zero, no decimal point appears. The value is rounded to the appropriate number of
digits. The E conversion character produces a number with E instead of e
introducing the exponent. The exponent always contains at least two digits.
However, if the magnitude to be converted is greater than or equal to lE+100,
additional exponent digits are written as necessary.
g,G
The double argument is converted in style f or e (or in style E in the case of a G
conversion character), with the precision specifying the number of significant
digits. The style used depends on the value converted; style e is used only if the
exponent resulting from the conversion is less than -4 or greater than the
precision. Trailing zeros are removed from the result; a decimal point appears
only if it is followed by a digit.
c
The int argument is converted to an unsigned char, and the resulting character is
written.
s
The argument is taken to be a (const char *) pointer to a string. Characters from
the string are written up to, but not including, the terminating null character, or
until the number of characters indicated by the precision are written. If the
precision is missing it is taken to be arbitrarily large, so all characters before the
first null character are written.
p
The argument is taken to be a (const void) pointer to an object. The value of the
pointer is converted to a sequence of hex digits.
n
The argument is taken to be an (int) pointer to an integer into which is written the
number of characters written to the output stream so far by this call to fprintf.
No argument is converted.
%
A % is written. No argument is converted.
In no case does a nonexistent or small field width cause truncation of a field. If the result
of a conversion is wider than the field width, the field is expanded to contain the conversion result.
free
Causes the space pointed to by ptr to be deallocated, that is, made available for further
allocation. If ptr is a null pointer, no action occurs. Otherwise, if the argument does not
match a pointer earlier returned by the calloc, malloc, or realloc function, or if the
space has been deallocated by a call to free or realloc, the behavior is undefined. If
freed space is referenced, the behavior is undefined.
UM004407-0104
Z8 User Manual
200
Synopsis
#include <stdlib.h>
void free(void *ptr);
Example
char *buf;
buf=(char*) calloc(40, sizeof(char));
free(buf);
frexp
Breaks a floating-point number into a normalized fraction and an integral power of 2. It
stores the integer in the int object pointed to by exp.
Synopsis
#include <math.h>*
double frexp(double value, int *exp);
Returns
The value x, such that x is a double with magnitude in the interval [1/2, 1] or zero, and
value equals x times 2 raised to the power *exp. If value is zero, both parts of the result are
zero.
Example
double x, y=16.4;
int n;
y=frexp(x,&n);
GET_ERF
The GET_ERF intrinsic returns the value of a register in an expanded register file (ERF).
The erf argument is specific to your target CPU and is defined in the header file with the
same name as your target CPU.
Synopsis
#include <Z86C95.h>
int GET_ERF(char erf);
Returns
The value of the register.
UM004407-0104
Z8 User Manual
201
Example
char x;
x = GET_ERF(SC0N);
Note: This function is nonstandard.
GET_REG
The GET_REG function returns the current value of a working register. regnum must be
one of the following:
R0
R1
R2
R3
R4
R5
R6
R9
R10
R11
R12
R13
R14
R15
R7
R8
Synopsis
#include <Z8.h>
int GET_REG(int regnum);
Example
int rval;
rval = GET_REG(R0);
GET_RREG
The GET_RREG function returns the current value of a working register. regnum must be
one of the following:
RR0
RR2
RR4
RR6
RR8
RR10
RR12
RR14
Synopsis
#include <Z8.h>
int GET_RREG(int regnum);
Example
int rval;
rval = GET_RREG(RR0);
UM004407-0104
Z8 User Manual
202
getch
Waits for the next character to appear at the serial port and returns its value. This function
does not wait for end-of-line to return as getchar does. getch does not echo the character received.
Synopsis
#include <sio.h>
int getch(void);
Returns
The next character that appears at the serial.
Example
int i;
i=getch();
Notes: Use of this function is nonstandard.
The getch function uses the serial port settings defined in sio.c. You might need to
modify sio.c to suit your needs. sio.c resides in the following directory:
ZILOGINSTALL\ZDSII_product_version\src\rtl\common\
getche
Waits for the next character to appear at the serial port, echoes it, and returns its value.
This function does not wait for end-of-line to return as getchar does.
Synopsis
#include <sio.h>
int getche(void);
Returns
The next character that appears at the serial port.
Example
int i;
i=getche();
UM004407-0104
Z8 User Manual
203
The getche function uses the serial port settings defined in sio.c. You might need to
getchar
Waits for the next character to appear at the serial port and return its value.
Synopsis
#include <stdio.h>
int getchar(void);
Returns
The next character from the input stream pointed to by stdin. If the stream is at end-of-file,
the end-of-file indicator for the stream is set, and getchar returns EOF. If a read error
occurs, the error indicator for the stream is set, and getchar returns EOF.
Example
inti;
i=getchar();
gets
Reads characters from a UART into the array pointed to by s, until end-of-file is encountered or a new-line character is read. The new-line character is discarded and a null character is written immediately after the last character read into the array.
Synopsis
#include <stdio.h>
char *gets(char *s);
Returns
The value of s if successful. If a read error occurs during the operation, the array contents
are indeterminate, and a null pointer is returned.
Example
char *r;
char buf [80];
r=gets(buf);
UM004407-0104
Z8 User Manual
204
if (r==NULL)
/*No input*/
init_uart
Initializes the Z8 UART.
init_uart is defined in the file sio.c. You might need to modify sio.c to suit your
needs. sio.c resides in the following directory:
The init_uart function has arguments that configure either UART0 or UART1 and
select the UART passed as the current one for use. All calls to putch and getch use the
current UART. You can also move between the two UARTs using the new select_port
function. For example:
#include <stdio.h>
#include <sio.h>
// non-standard I/O
void main()
{
init_uart(_UART0,_DEFFREQ,_DEFBAUD);
init_uart(_UART1,_DEFFREQ,_DEFBAUD);
select_port(_UART0);
printf("Hello UART0\n"); // Write to uart0
select_port(_UART1);
printf("Hello UART1\n"); // Write to uart1
}
Notes: When using UART1, a null modem adapter is required.
_DEFFREQ is now automatically selected from the IDE using the one of the
following methods:
•
Project Settings dialog box (see “Simulator” on page 109).
•
Driver dialog box (see “Configure Emulator Driver Dialog Box” on page 111).
Synopsis
#include<sio.h>
void init_uart(void),
UM004407-0104
Z8 User Manual
205
Example
init_uart() ;
isalnum
Tests for any character for which isalpha or isdigit is true.
Synopsis
#include <ctype.h>
int isalnum(int c);
Example
int r;
char c='a';
r=isalnum(c)
isalpha
Tests for any character for which isupper or islower is true.
Synopsis
#include <ctype.h>
int isalpha(int c);
Example
int r;
char c='a';
r=isalpha(c)
iscntrl
Tests for any control character.
Synopsis
#include <ctype.h>
int iscntrl(int c);
Example
int r;
char c=NULL;
r=iscntrl(c);
UM004407-0104
Z8 User Manual
206
isdigit
Tests for any decimal digit.
Synopsis
#include <ctype.h>
int isdigit(int c);
Example
int r;
char c='4';
r=isdigit(c);
isgraph
Tests for any printing character except space (' ').
Synopsis
#include <ctype.h>
int isgraph(int c);
Example
int r;
char c='';
r=isgraph(c);
islower
Tests for any lowercase letter 'a' to 'z'.
Synopsis
#include <ctype.h>
int islower(int c);
Example
int r;
char c='a';
r=islower(c);
UM004407-0104
Z8 User Manual
207
isprint
Tests for any printing character including space (' ').
Synopsis
#include <ctype.h>
int isprint(int c);
Example
int r;
char c='1';
r=isprint(c);
ispunct
Tests for any printing character except space (' ') or a character for which isalnum is true.
Synopsis
#include <ctype.h>
int ispunct(int c);
Example
int r;
char c='a';
r=ispunct(c);
isspace
Tests for the following white-space characters: space (' '), form feed ('\f'), new line ('\n'),
carriage return ('\r'), horizontal tab ('\t'), or vertical tab ('\v').
Synopsis
#include <ctype.h>
int isspace(int c);
Example
int r;
char c='';
r=isspace(0);
UM004407-0104
Z8 User Manual
208
isupper
Tests for any uppercase letter 'A' to 'Z'.
Synopsis
#include <ctype.h>
int isupper(int c);
Example
int r;
char c='a';
r=isupper(c);
isxdigit
Tests for any hexadecimal digit '0' to '9' and 'A' to 'F'.
Synopsis
#include <ctype.h>
int isxdigit(int c);
Example
int r;
char c='f';
r=isxdigit(c)
kbhit
Determines whether or not there is a character waiting at the serial port.
Synopsis
#include <sio.h>
int kbhit(void);
Returns
The number of characters waiting at the serial port. Zero means there are no characters
waiting.
Example
int i;
i=kbhit();
UM004407-0104
Z8 User Manual
209
The kbhit function uses the serial port settings defined in sio.c. You might need to
labs
Computes the absolute value of a long int j.
Synopsis
#include <stdlib.h>
long int labs(long int j);
Example
long int i=-193250;
long int j
j=labs(i);
ldexp
Multiplies a floating-point number by an integral power of 2. A range error can occur.
Synopsis
#include <math.h>
double ldexp(double x, int exp);
Returns
The value of x times 2 raised to the power of exp.
Example
double x=1.235
int exp=2;
double y;
y=ldexp(x,exp);
UM004407-0104
Z8 User Manual
210
ldiv
Computes the quotient and remainder of the division of the numerator numer by the
denominator denom. If the division is inexact, the sign of the quotient is that of the mathematical quotient, and the magnitude of the quotient is the largest integer less than the magnitude of the mathematical quotient.
Synopsis
#include <stdlib.h>
ldiv_t ldiv(long int numer, long int denom);
Example
long int x=25000;
long int y=300;
div_t t;
int q;
int r;
t=div(x,y);
q=t.quot;
r=t.rem;
log
Computes the natural logarithm of x. A domain error occurs if the argument is negative. A
range error occurs if the argument is zero.
Synopsis
#include <math.h>
double log(double x);
Returns
The natural logarithm.
Example
double x=2.56;
double y;
y=log(x);
UM004407-0104
Z8 User Manual
211
log10
Computes the base-ten logarithm of x. A domain error occurs if the argument is negative.
A range error occurs if the argument is zero.
Synopsis
#include <math.h>
double log10(double x);
Returns
The base-ten logarithm.
Example
double x=2.56;
double y;
y=log10(x);
longjmp
Restores the environment saved by the most recent call to setjmp in the same invocation
of the program, with the corresponding jmp_buf argument. If there has been no such call,
or if the function containing the call to setjmp has executed a return statement in the
interim, the behavior is undefined.
All accessible objects have values as of the time longjmp was called, except that the values of objects of automatic storage class that do not have volatile type and have been
changed between the setjmp and longjmp call are indeterminate.
As it bypasses the usual function call and returns mechanisms, the longjmp function executed correctly in contexts of interrupts, signals, and any of their associated functions.
However, if the longjmp function is invoked from a nested signal handler (that is, from a
function invoked as a result of a signal raised during the handling of another signal), the
behavior is undefined.
Synopsis
#include <setjmp.h>
void longjmp(jmp_buf env, int val);
Returns
After longjmp is completed, program execution continues as if the corresponding call to
setjmp had just returned the value specified by val. The longjmp function cannot cause
setjmp to return the value 0; if val is 0, setjmp returns the value 1.
UM004407-0104
Z8 User Manual
212
Example
int i;
jmp_buf (env)
i=setjmp(env)
longjmp(env,i);
malloc
Allocates space for an object whose size is specified by size.
Synopsis
#include <stdlib.h>
void *malloc(size_t size);
Returns
A pointer to the start (lowest byte address) of the allocated space. If the space cannot be
allocated, or if size is zero, the malloc function returns a null pointer.
Example
char *buf;
buf=(char*) malloc(40,sizeof(char));
if(buf !=NULL)
/*success*/
else
/*fail*/
memchr
Locates the first occurrence of c (converted to an unsigned char) in the initial n characters
of the object pointed to by s.
Synopsis
#include <string.h>
void *memchr(void *s, int c, size_t n);
Returns
A pointer to the located character, or a null pointer if the character does not occur in the
object.
Example
char *p1;
c='p';
p1=memchr(str,c,sizeof(char));
UM004407-0104
Z8 User Manual
213
memcmp
Compares the first n characters of the object pointed to by s2 to the object pointed to by s1.
Synopsis
#include <string.h>
int memcmp(void *s1, void *s2, size_t n);
Returns
An integer greater than, equal to, or less than zero, according as the object pointed to by s1
is greater than, equal to, or less than the object pointed to by s2.
Example
char s1[]="COMPASS";
char s2[]="IDE";
int res;
res=memcmp(s1, s2, sizeof (char));
memcpy
Copies n characters from the object pointed to by s2 into the object pointed to by s1. If the
two regions overlap, the behavior is undefined.
Synopsis
#include <string.h>
void *memcpy(void *s1, void *s2, size_t n);
Returns
The value of s1.
Example
char s1[10];
char s2[10] = "COMPASS";
memcpy(s1, s2, 8);
memmove
Moves n characters from the object pointed to by s2 into the object pointed to by s1. Copying between objects that overlap takes place correctly.
Synopsis
#include <string.h>
void *memmove(void *s1, void *s2, size_t n);
UM004407-0104
Z8 User Manual
214
Returns
The value of s1.
Example
char s1[10];
s1=memmove(s1, s2, 8*sizeof(char));
memset
Copies the value of c (converted to an unsigned char) into each of the first n characters of
the object pointed to by s.
Synopsis
#include <string.h>
void *memset(void *s, int c, size_t n);
Returns
The value of s.
Example
char str[20];
char c='a';
str=memset(str, c, 10*sizeof(char));
modf
Breaks the argument value into integral and fractional parts, each of which has the same
sign as the argument. It stores the integral part as a double in the object pointed to by iptr.
Synopsis
#include <math.h>
double modf(double value, double *iptr);
Returns
The signed fractional part of value.
Example
double x=1.235;
double f;
double I;
i=modf(x, &f);
UM004407-0104
Z8 User Manual
215
pow
Computes the x raised to the power of y. A domain error occurs if x is zero and y is less
than or equal to zero, or if x is negative and y is not an integer. A range error can occur.
Synopsis
#include <math.h>
double pow(double x, double y);
Returns
The value of x raised to the power y.
Example
double x=2.0;
double y=3.0;
double=res;
res=pow(x,y);
printf
Writes output to the stream pointed to by stdout, under control of the string pointed to by
format that specifies how subsequent arguments are converted for output.
A format string contains two types of objects: plain characters, which are copied
unchanged to stdout, and conversion specifications, each of which fetch zero or more subsequent arguments. The results are undefined if there are insufficient arguments for the
format. If the format is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored. The printf function returns when the end of the format
string is encountered.
appear in sequence:
•
•
Zero or more flags that modify the meaning of the conversion specification.
•
An optional precision that gives the minimum number of digits to appear for the d, i,
o, u, x, and X conversions, the number of digits to appear after the decimal point for e,
E, and f conversions, the maximum number of significant digits for the g and G
conversions, or the maximum number of characters to be written from a string in s
conversion. The precision takes the form of a period (.) followed by an optional
UM004407-0104
An optional decimal integer specifying a minimum field width. If the converted value
has fewer characters than the field width, it is padded on the left (or right, if the left
adjustment flag, described later, has been given) to the field width. The padding is
with spaces unless the field width integer starts with a zero, in which case the padding
is with zeros.
Z8 User Manual
216
decimal integer; if the integer is omitted, it is treated as zero. The amount of padding
specified by the precision overrides that specified by the field width.
•
An optional h specifies that a following d, i, o, u, x, or X conversion character applies
to a short_int or unsigned_short_unt argument (the argument has been promoted
according to the integral promotions, and its value is converted to short_int or
unsigned_short_int before printing). An optional l (ell) specifies that a following d, i,
o, u, x or X conversion character applies to a long_int or unsigned_long_int argument.
An optional L specifies that a following e, E, f, g, or G conversion character applies to
a long_double argument. If an h, l, or L appears with any other conversion character, it
is ignored.
•
•
A character that specifies the type of conversion to be applied.
A field width or precision, or both, can be indicated by an asterisk * instead of a digit
string. In this case, an int argument supplies the files width or precision. The
arguments specifying field width or precision displays before the argument (if any) to
be converted. A negative field width argument is taken as a - flag followed by a
positive field width. A negative precision argument is taken as if it were missing.
Note: For more specific information on the flag characters and conversion characters for the
printf function, see “printf Flag Characters” on page 218.
Synopsis
#include <stdio.h>
int printf(char *format, ...);
Returns
The number of characters transmitted, or a negative value if an output error occurred.
Example
int i=10;
printf("This is %d",i);
To minimize RData use in a small or large memory model, see the following example:
//
// Minimizing usage of DATA in small model
// (works for large model too)
//
#include <stdio.h>
rom char fmt1[] = "Hello World #%d\n";
// Store this string in ROM
rom char fmt2[] = "-----------------\n";
// Store in ROM
char fmt[20];
// RDATA format string holder
UM004407-0104
Z8 User Manual
217
void rom_to_data_copy(char *dest,char rom *src)
{
while (*src)
*dest++ = *src++;
*dest = '\0';
}
void main()
{
printf(fmt,1000);
// Prints "Hello World #1000\n"
rom_to_data_copy(fmt,fmt2)
}
Note: The sio.c run-time library points all calls to the printf function to UART0. If you want
to use UART1, use a null modem adapter and change the following statement in the sio.c
library
#define UART0
to
#define UART1
The sio.c library resides in the following directory:
product, and version is the ZDS II version number. It is set up for 56 Kbaud, no parity, 1
stop bit, and 8 data bits.
UM004407-0104
Z8 User Manual
218
printf Flag Characters
-
The result of the conversion is left-justified within the field.
+
The result of a signed conversion always begins with a plus or a minus sign.
space
If the first character of a signed conversion is not a sign, a space is added before the result.
If the space and + flags both appear, the space flag is ignored
#
The result is to be converted to an “alternate form.” For c, d, i, s, and u conversions, the
flag has no effect. For o conversion, it increases the precision to force the first digit of the
result to be a zero. For x (or X) conversion, a nonzero result always contains a decimal
point, even if no digits follow the point (normally, a decimal point appears in the result of
these conversions only if a digit follows it). For g and G conversions, trailing zeros are
not removed from the result, as they normally are.
printf Conversion Characters
d,i,o,u,x,X
The int argument is converted to signed decimal (d or i), unsigned octal (o),
unsigned decimal (u), or unsigned hexadecimal notation (x or X); the letters
abcdef are used for x conversion and the letters ABCDEF for X conversion. The
precision specifies the minimum number of digits to appear; if the value being
converted can be represented in fewer digits, it is expanded with leading zeros.
The default precision is 1. The result of converting a zero value with a precision
of zero is no characters.
f
The double argument is converted to decimal notation in the style [-]ddd.ddd,
where the number of digits after the decimal point is equal to the precision
specification. If the precision is missing, it is taken as 6; if the precision is
explicitly zero, no decimal point appears. If a decimal point appears, at least one
digit appears before it. The value is rounded to the appropriate number of digits.
e,E
The double argument is converted in the style [-]d.ddde+dd, where there is one
digit before the decimal point and the number of digits after it is equal to the
precision; when the precision is missing, six digits are produced; if the precision
is zero, no decimal point appears. The value is rounded to the appropriate number
of digits. The E conversion character produces a number with E instead of e
introducing the exponent. The exponent always contains at least two digits.
However, if the magnitude to be converted is greater than or equal to lE+100,
additional exponent digits are written as necessary.
g,G
The double argument is converted in style f or e (or in style E in the case of a G
conversion character), with the precision specifying the number of significant
digits. The style used depends on the value converted; style e is used only if the
exponent resulting from the conversion is less than -4 or greater than the
precision. Trailing zeros are removed from the result; a decimal point appears
only if it is followed by a digit.
UM004407-0104
Z8 User Manual
219
c
The int argument is converted to an unsigned char, and the resulting character is
written.
s
The argument is taken to be a (const char *) pointer to a string. Characters from
the string are written up to, but not including, the terminating null character, or
until the number of characters indicated by the precision are written. If the
precision is missing it is taken to be arbitrarily large, so all characters before the
first null character are written.
p
The argument is taken to be a (const void) pointer to an object. The value of the
pointer is converted to a sequence of hex digits.
n
The argument is taken to be an (int) pointer to an integer into which is written the
number of characters written to the output stream so far by this call to printf.
No argument is converted.
%
A % is written. No argument is converted.
In no case does a nonexistent or small field width cause truncation of a field. If the result
of a conversion is wider than the field width, the field is expanded to contain the conversion result.
putch
Writes a character to the serial port.
Synopsis
#include <sio.h>
void putch(int c);
Example
char c='c';
putch(c);
Note: The putch function is nonstandard.
The sio.c run-time library points all calls to the putch function to UART0. If you want
to use UART1, use a null modem adapter and change the following statement in the sio.c
library
#define UART0
to
#define UART1
UM004407-0104
Z8 User Manual
220
putchar
Writes a character to the serial port.
Synopsis
#include <stdio.h>
int putchar(int c);
Returns
The character written. If a write error occurs, putchar returns EOF.
Example
int i;
charc='a';
i=putchar(c);
puts
Writes the string pointed to by s to the serial port and appends a new-line character to the
output. The terminating null character is not written.
Synopsis
#include <stdio.h>
int puts(char *s);
Returns
EOF if an error occurs; otherwise, it is a non-negative value.
Example
int i;
char strp[]="COMPASS";
i=puts(str);
Note: The sio.c run-time library points all calls to the puts function to UART0. If you want to
use UART1, use a null modem adapter and change the following statement in the sio.c
library
#define UART0
UM004407-0104
Z8 User Manual
221
to
#define UART1
product, and version is the ZDS II version number. It is set up for 56 Kbaud, no parity, 1
stop bit, and 8 data bits.
qsort
Sorts an array of nmemb objects, the initial member of which is pointed to by any base.
The size of each object is specified by size.
The array is sorted in ascending order according to a comparison function pointed to by
compar, which is called with two arguments that point to the objects being compared. The
function returns an integer less than, equal to, or greater than zero if the first argument is
considered to be respectively less than, equal to, or greater than the second.
If two members compare as equal, their order in the sorted array is unspecified.
Synopsis
#include <stdlib.h>
void qsort(void *base, size_t nmemb, size_t size,
int (*compar)(void *, void *));
Example
int lst[]={5,8,2,9};
int compare (int x, int y);
qsort (lst, sizeof(int), 4, compare);
rand
Computes a sequence of pseudorandom integers in the range 0 to RAND_MAX.
Synopsis
#include <stdlib.h>
int rand(void)
Returns
A pseudorandom integer.
UM004407-0104
Z8 User Manual
222
Example
int i;
srand(1001);
i=rand();
realloc
Changes the size of the object pointed to by ptr to the size specified by size. The contents
of the object are unchanged up to the lesser of the new and old sizes. If ptr is a null pointer,
the realloc function behaves like the malloc function for the specified size. Otherwise,
if ptr does not match a pointer earlier returned by the calloc, malloc, or realloc function, or if the space has been deallocated by a call to the free or realloc function, the
behavior is undefined. If the space cannot be allocated, the realloc function returns a
null pointer and the object pointed to by ptr is unchanged. If size is zero, the realloc
function returns a null pointer and, if ptr is not a null pointer, the object it points to is freed.
Synopsis
#include <stdlib.h>
void *realloc(void *ptr, size_t size);
Returns
Returns a pointer to the start (lowest byte address) of the possibly moved object.
Example
char *buf;
buf=(char*)realloc(40,sizeof(buf));
if(buf !=NULL)
/*success*/
else
/*fail*/
scanf
Reads input from the stream pointed to by stdin, under control of the string pointed to by
format that specifies the admissible input sequences and how they are to be converted for
assignment, using subsequent arguments as pointers to the object to receive the converted
input. If there are insufficient arguments for the format, the behavior is undefined. If the
format is exhausted while arguments remain, the excess arguments are evaluated but otherwise ignored.
The format is composed of zero or more directives from the following list:
•
•
UM004407-0104
one or more white-space characters
an ordinary character (not %)
Z8 User Manual
223
•
a conversion specification
appear in sequence:
•
•
•
An optional assignment-suppressing character *.
•
A character that specifies the type of conversion to be applied. The valid conversion
characters are described below.
An optional decimal integer that specifies the maximum field width.
An optional h, l or L indicating the size of the receiving object. The conversion
characters d, l, n, o, and x can be preceded by h to indicate that the corresponding
argument is a pointer to short_int rather than a pointer to int, or by l to indicate that it
is a pointer to long_int. Similarly, the conversion character u can be preceded by h to
indicate that the corresponding argument is a pointer to unsigned_short_int rather than
a pointer to unsigned_int, or by l to indicate that it is a pointer to unsigned_long_int.
Finally, the conversion character e, f, and g can be preceded by l to indicate that the
corresponding argument is a pointer to double rather than a pointer to float, or by L to
indicate a pointer to long_double. If an h, l, or L appears with any other conversion
character, it is ignored.
The scanf function executes each directive of the format in turn. If a directive fails, as
detailed below, the scanf function returns. Failures are described as input failures (due to
the unavailability of input characters), or matching failures (due to inappropriate input).
A directive composed of white space is executed by reading input up to the first nonwhite-space character (which remains unread), or until no more characters can be read. A
white-space directive fails if no white-space character can be found.
A directive that is an ordinary character is executed by reading the next character of the
stream. If the character differs from the one comprising the directive, the directive fails,
and the character remains unread.
A directive that is a conversion specification defines a set of matching input sequences, as
described below for each character. A conversion specification is executed in the following steps:
1. Input white-space characters (as specified by the isspace function) are skipped, unless
the specification includes a ’[’, ’c,’ or ’n’ character.
2. An input item is read from the stream, unless the specification includes an n character.
An input item is defined as the longest sequence of input characters (up to any
specified maximum field width) which is an initial subsequence of a matching
sequence. The first character, if any, after the input item remains unread. If the length
of the input item is zero, the execution of the directive fails: this condition is a
matching failure, unless an error prevented input from the stream, in which case it is
an input failure.
UM004407-0104
Z8 User Manual
224
3. Except in the case of a % character, the input item (or, in the case of a %n directive,
the count of input characters) is converted to a type appropriate to the conversion
character. If the input item is not a matching sequence, the execution of the directive
fails: this condition is a matching failure. Unless assignment suppression was
indicated by a *, the result of the conversion is placed in the object pointed to by the
first argument following the format argument that has not already received a
conversion result. If this object does not have an appropriate type, or if the result of
the conversion cannot be represented in the space provided, the behavior is undefined.
Note: See “scanf Conversion Characters” for valid input information.
Synopsis
#include <stdio.h>
int scanf(char *format, ...);
Returns
The value of the macro EOF if an input failure occurs before any conversion. Otherwise,
the scanf function returns the number of input items assigned, which can be fewer than
provided for, or even zero, in the event of an early conflict between an input character and
the format.
Example
int i
scanf("&d",&i);
scanf Conversion Characters
d
Matches an optionally signed decimal integer, whose format is the same as expected for
the subject sequence of the strtol function with the value 10 for the base argument. The
corresponding argument is a pointer to integer.
i
Matches an optionally signed integer, whose format is the same as expected for the
subject sequence of the strtol function with the value 0 for the base argument. The
o
Matches an optionally signed octal integer, whose format is the same as expected for the
u
Matches an unsigned decimal integer, whose format is the same as expected for the
corresponding argument is a pointer to unsigned integer.
x
Matches an optionally signed hexadecimal integer, whose format is the same as expected
for the subject sequence of the strtol function with the value of 16 for the base argument.
The corresponding argument is a pointer to integer.
UM004407-0104
Z8 User Manual
225
e,f,g
Matches an optionally signed floating-point number, whose format is the same as
expected for the subject string of the strtod function. The corresponding argument is a
pointer to floating.
s
Matches a sequence of non-white-space characters. The corresponding argument is a
pointer to the initial character of an array large enough to accept the sequence and a
terminating null character, which is added automatically.
[
Matches a sequence of expected characters (the scanset). The corresponding argument is
a pointer to the initial character of an array large enough to accept the sequence and a
terminating null character, which is added automatically. The conversion character
includes all subsequent characters is the format string, up to and including the matching
right bracket ( ] ). The characters between the brackets (the scanlist) comprise the scanset,
unless the character after the left bracket is a circumflex ( ^ ), in which case the scanset
contains all characters that do not appear in the scanlist between the circumflex and the
right bracket. As a special case, if the conversion character begins with [] or [^], the right
bracket character is in the scanlist and next right bracket character is the matching right
bracket that ends the specification. If a - character is in the scanlist and is neither the first
nor the last character, the behavior is indeterminate.
c
Matches a sequence of characters of the number specified by the field width (1 if no field
width is present in the directive). The corresponding argument is a pointer to the initial
character of an array large enough to accept the sequence. No null character is added.
p
Matches a hexadecimal number. The corresponding argument is a pointer to a pointer to
void.
n
No input is consumed. The corresponding argument is a pointer to integer into which is to
be written the number of characters read from the input stream so far by this call to the
scanf function. Execution of a %n directive does not increment the assignment count
returned at the completion of execution of the scanf function.
%
Matches a single %; no conversion or assignment occurs.
If a conversion specification is invalid, the behavior is undefined.
The conversion characters e, g, and x can be capitalized. However, the use of upper case is
ignored.
If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs
before any characters matching the current directive have been read (other than leading
white space, where permitted), execution of the current directive terminates with an input
failure; otherwise, unless execution of the current directive is terminated with a matching
failure, execution of the following directive (if any) is terminated with an input failure.
If conversion terminates on a conflicting input character, the offending input character is
left unread in the input stream. Trailing white space (including new-line characters) is left
unread unless matched by a directive. The success of literal matches and suppressed
assignments is not directly determinable other than using the %n directive.
UM004407-0104
Z8 User Manual
226
SET_ERF
The SET_ERF intrinsic function sets a register in an expanded register file (ERF) to a
value.
Synopsis
#include <Z8.h>
void SET_ERF(char erf, char value);
Example
#include <Z8.h>
SET_ERF(SC0N, 20);
Note: The ERFs are different for many members of the Z8 family. Therefore, you must include
the header file that corresponds to the name of your target microcontroller. <Z8.h> is just
an example.
setjmp
Saves its calling environment in its jmp_buf argument, for later use by the longjmp function.
Synopsis
#include<setjmp.h>
int setjmp(jmp_buf env);
Returns
If the return is from a direct invocation, the setjmp function returns the value zero. If the
return is from a call to the longjmp function, the setjmp function returns a nonzero
value.
Example
int i;
jmp_buf(env);
i=setjmp(env);
longjmp(env, i);
UM004407-0104
Z8 User Manual
227
SET_VECTOR
The SET_VECTOR macro is a Z8 family specific macro that embeds assembly language
into C source code to specify the address of an interrupt handler. vectnum is the interrupt
vector number to be set. The compiler supports the following vectors:
•
•
•
•
•
•
•
RESET
IRQ0
IRQ1
IRQ2
IRQ3
IRQ4
IRQ5
hndlr is the address of the interrupt handler. This function must have the interrupt charac-
ter for proper execution.
Since the interrupt vectors of the Z8 are in ROM they cannot be initialized at run time.
Therefore, the SET_VECTOR macro works by switching to a special segment and placing
the address of the interrupt handler at the proper address. This implementation does not
generate executable code but must be placed within the interrupt handler.
The following code fragment shows a typical use of the SET_VECTOR intrinsic:
#include <Z8.h>
void main(void)
{
SET_VECTOR(RESET,reset); /* setup reset vector */
DI();
/* disable interrupts */
...
/* initialize system */
EI();
/* enable interrupts */
}
sin
Computes the sine of x (measured in radians). A large magnitude argument can yield a
result with little or no significance.
Synopsis
#include <math.h>
double sin(double x);
Returns
The sine value.
UM004407-0104
Z8 User Manual
228
Example
double x=1.24;
double y;
y=sin[x];
sinh
Computes the hyperbolic sine of x. A range error occurs if the magnitude of x is too large.
Synopsis
#include <math.h>
double sinh(double x);
Returns
The hyperbolic sine value.
Example
double x=1.24;
double y;
y=sin(x);
sprintf
The sprintf function is equivalent to printf, except that the argument s specifies an
array into which the generated output is to be written, rather than to a stream. A null character is written at the end of the characters written; it is not counted as part of the returned
sum.
Synopsis
#include <stdio.h>
int sprintf(char *s, char *format, ...);
Returns
The number of characters written in the array, not counting the terminating null character.
Example
int d=51;
char buf [40];
sprint(buf,"COMPASS/%d",d);
UM004407-0104
Z8 User Manual
229
sqrt
Computes the non-negative square root of x. A domain error occurs if the argument is negative.
Synopsis
#include <math.h>
double sqrt(double x);
Returns
The value of the square root.
Example
double x=25.0;
double y;
y=sqrt(x);
srand
Uses the argument as a seed for a new sequence of pseudorandom numbers to be returned
by subsequent calls to rand. If srand is then called with the same seed value, the
sequence of pseudorandom numbers is repeated. If rand is called before any calls to
srand have been made, the same sequence is generated as when srand is first called with
a seed value of 1.
Synopsis
#include <stdlib.h>
void srand(unsigned int seed);
Example
int i;
srand(1001);
i=rand();
sscanf
Reads formatted data from a string.
Synopsis
#include <stdio.h>
int sscanf(char *s, char *format, ...);
UM004407-0104
Z8 User Manual
230
Returns
The value of the macro EOF if an input failure occurs before any conversion. Otherwise,
the sscanf function returns the number of input items assigned, which can be fewer than
provided for, or even zero, in the event of an early conflict between an input character and
the format.
Example
char buf [80];
int i;
sscanf(buf,"&d",&i);
strcat
Appends a copy of the string pointed to by s2 (including the terminating null character) to
the end of the string pointed to by s1. The initial character of s2 overwrites the null character at the end of s1.
Synopsis
#include <string.h>
char *strcat(char *s1, char *s2);
Returns
The value of s1.
Example
char s1[80]="Production";
char s2[]="Languages";
s1=strcat(s1,s2);
strchr
Locates the first occurrence of c (converted to a char) in the string pointed to by s. The terminating null character is considered to be part of the string.
Synopsis
#include <string.h>
char *strchr(char *s, int c);
Returns
A pointer to the located character, or a null pointer if the character does not occur in the
string.
UM004407-0104
Z8 User Manual
231
Example
char *ptr;
ptr=strchr(str,'p');
strcmp
Compares the string pointed to by s1 to the string pointed to by s2.
Synopsis
#include <string.h>
int strcmp(char *s1, char *s2);
Returns
An integer greater than, equal to, or less than zero, according as the string pointed to by s1
is greater than, equal to, or less than the string pointed to by s2.
Example
char s1[]="Production";
char s2[]="Programming";
int res;
res=strcmp(s1,s2);
strcpy
Copies the string pointed to by s2 (including the terminating null character) into the array
pointed to by s1. If copying takes place between objects that overlap, the behavior is undefined.
Synopsis
#include <string.h>
char *strcpy(char *s1, char *s2);
Returns
The value of s1.
Example
char s1[80], *s2;
s2=strcpy(s1,"Production");
UM004407-0104
Z8 User Manual
232
strcspn
Computes the length of the initial segment of the string pointed to by s1 that consists
entirely of characters not from the string pointed to by s2. The terminating null character is
not considered part of s2.
Synopsis
#include <string.h>
size_t strcspn(char *s1, char *s2);
Returns
The length of the segment.
Example
int pos;
char s1[]="xyzabc";
char s2[]="abc";
pos=strcspn(s1,s2);
strlen
Computes the length of the string pointed to by s.
Synopsis
#include <string.h>
size_t strlen(char *s);
Returns
The number of characters that precede the terminating null character.
Example
int i;
i=strlen(s1);
strncat
Appends no more than n characters of the string pointed to by s2 (not including the terminating null character) to the end of the string pointed to by s1. The initial character of s2
overwrites the null character at the end of s1. A terminating null character is always
appended to the result.
UM004407-0104
Z8 User Manual
233
Synopsis
#include <string.h>
char *strncat(char *s1, char *s2, size_t n);
Returns
The value of s1.
Example
char strl[80]="Production";
char str2[]="Languages";
strl=strncat(str1,str2,4);
strncmp
Compares no more than n characters from the string pointed to by s1 to the string pointed
to by s2.
Synopsis
#include <string.h>
int strncmp(char *s1, char *s2, size_t n);
Returns
An integer greater than, equal to, or less than zero, according as the string pointed to by s1
is greater than, equal to, or less than the string pointed to by s2.
Example
char s1[]="Production";
char s2[]="Programming";
int res;
res=strncmp(s1,s2,3);
strncpy
Copies not more than n characters from the string pointed to by s2 to the array pointed to
by s1. If copying takes place between objects that overlap, the behavior is undefined.
If the string pointed to by s2 is shorter than n characters, null characters are appended to
the copy in the array pointed to by s1, until n characters in all have been written.
Synopsis
#include <string.h>
char *strncpy(char *s1, char *s2, size_t n);
UM004407-0104
Z8 User Manual
234
Returns
The value of s1.
Example
char s1[40}="Production";
char s2[]="Languages";
s1=strncpy(s1,s2,4);
strpbrk
Locates the first occurrence in the string pointed to by s1 of any character from the string
pointed to by s2.
Synopsis
#include <string.h>
char *strpbrk(char *s1, char *s2);
Returns
A pointer to the character, or a null pointer if no character from s2 occurs in s1.
Example
char *ptr;
char s2[]="PASS";
ptr=strpbrk(s1,s2);
strrchr
Locates the last occurrence of c (converted to a char) in the string pointed to by s. The terminating null character is considered to be part of the string.
Synopsis
#include <string.h>
char *strrchr(char *s, int c);
Returns
A pointer to the character, or a null pointer if c does not occur in the string.
Example
char *ptr;
char s2[]="PASS";
ptr=strrchr(s1,s2);
UM004407-0104
Z8 User Manual
235
strspn
Finds the first substring from a given character set in a string.
Synopsis
#include <string.h>
size_t strspn(char *s1, char *s2);
Returns
The length of the segment.
Example
char s1[]="cabbage";
char s2[]="abc";
int res,
res=strspn(s1,s2);
strstr
Locates the first occurrence of the string pointed to by s2 in the string pointed to by s1.
Synopsis
#include <string.h>
char *strstr(char *s1, char *s2);
Returns
A pointer to the located string, or a null pointer if the string is not found.
Example
char *ptr;
char s1[]="Production Languages";
char s2[]="Lang";
ptr=strstr(s1,s2);
strtod
Converts the string pointed to by nptr to double representation. The function recognizes an
optional leading sequence of white-space characters (as specified by the isspace function),
then an optional plus or minus sign, then a sequence of digits optionally containing a decimal point, then an optional letter e or E followed by an optionally signed integer, then an
optional floating suffix. If an inappropriate character occurs before the first digit following
the e or E, the exponent is taken to be zero.
UM004407-0104
Z8 User Manual
236
The first inappropriate character ends the conversion. If endptr is not a null pointer, a
pointer to that character is stored in the object endptr points to; if an inappropriate character occurs before any digit, the value of nptr is stored.
The sequence of characters from the first digit or the decimal point (whichever occurs
first) to the character before the first inappropriate character is interpreted as a floating
constant according to the rules of this section, except that if neither an exponent part or a
decimal point appears, a decimal point is assumed to follow the last digit in the string. If a
minus sign appears immediately before the first digit, the value resulting from the conversion is negated.
Synopsis
#include <stdlib.h>
double strtod(char *nptr, char **endptr);
Returns
The converted value, or zero if an inappropriate character occurs before any digit. If the
correct value would cause overflow, plus or minus HUGE_VAL is returned (according to
the sign of the value), and the macro errno acquires the value ERANGE. If the correct
value causes underflow, zero is returned and the macro errno acquires the value
ERANGE.
Example
char *ptr;
char s[]="0.1456";
double res;
res=strtod(s,&ptr);
strtok
A sequence of calls to the strtok function breaks the string pointed to by s1 into a
sequence of tokens, each of which is delimited by a character from the string pointed to by
s2. The first call in the sequence has s1 as its first argument, and is followed by calls with
a null pointer as their first argument. The separator string pointed to by s2 can be different
from call to call.
The first call in the sequence searches s1 for the first character that is not contained in the
current separator string s2. If no such character is found, there are no tokens in s1, and the
strtok function returns a null pointer. If such a character is found, it is the start of the
first token.
The strtok function then searches from there for a character that is contained in the current separator string. If no such character is found, the current token extends to the end of
the string pointed to by s1, and subsequent searches for a token fail. If such a character is
found, it is overwritten by a null character, which terminates the current token. The
UM004407-0104
Z8 User Manual
237
strtok function saves a pointer to the following character, from which the next search for
a token starts.
Each subsequent call, with a null pointer as the value of the first argument, starts searching
from the saved pointer and behaves as described above.
Synopsis
#include <string.h>
char *strtok(char *s1, char *s2);
Returns
A pointer to the first character of a token, or a null pointer if there is no token.
Example
#include <string.h>
static char str[] = "?a???b, , ,#c";
char *t;
t = strtok(str,"?"); /* t points to the token "a" */
t = strtok(NULL,","); /* t points to the token
"??b " */
t = strtok(NULL,"#,"); /* t points to the token "c" */
t = strtok(NULL,"?"); /* t is a null pointer */
strtol
Converts the string pointed to by nptr to long int representation. The function recognizes
an optional leading sequence of white-space characters (as specified by the isspace function), then an optional plus or minus sign, then a sequence of digits and letters, then an
optional integer suffix.
The first inappropriate character ends the conversion. If endptr is not a null pointer, a
pointer to that character is stored in the object endptr points to; if an inappropriate character occurs before the first digit or recognized letter, the value of nptr is stored.
If the value of base is 0, the sequence of characters from the first digit to the character
before the first inappropriate character is interpreted as an integer constant according to
the rules of this section. If a minus sign appears immediately before the first digit, the
value resulting from the conversion is negated.
If the value of base is between 2 and 36, it is used as the base for conversion. Letters from
a (or A) through z (or Z) are ascribed the values 10 to 35; a letter whose value is greater
than or equal to the value of base ends the conversion. Leading zeros after the optional
sign are ignored, and leading 0x or 0X is ignored if the value of base is 16. If a minus sign
appears immediately before the first digit or letter, the value resulting from the conversion
is negated.
UM004407-0104
Z8 User Manual
238
Synopsis
#include <stdlib.h>
long int strtol(char *nptr, char **endptr, int base);
Returns
The converted value, or zero if an inappropriate character occurs before the first digit or
recognized letter. If the correct value would cause overflow, LONG_MAX or
LONG_MIN is returned (according to the sign of the value), and the macro errno acquires
the value ERANGE.
Example
char *ptr;
char s[]="12345";
long int res;
res=strtol(s,&ptr,10);
tan
The tangent of x (measured in radians). A large magnitude argument can yield a result
with little or no significance.
Synopsis
#include <math.h>
double tan(double x);
Returns
The tangent value.
Example
double x=2.22;
double y;
y=tan(x);
tanh
Computes the hyperbolic tangent of x.
Synopsis
#include <math.h>
double tanh(double x);
Returns
The hyperbolic tangent of x.
UM004407-0104
Z8 User Manual
239
Example
double x=2.22;
double y;
y=tanh(x);
tolower
Converts an uppercase letter to the corresponding lowercase letter.
Synopsis
#include <ctype.h>
int tolower(int c);
Returns
If the argument is an uppercase letter, the tolower function returns the corresponding
lowercase letter, if any; otherwise, the argument is returned unchanged.
Example
char c='A';
int i;
i=tolower(c);
toupper
Converts a lowercase letter to the corresponding uppercase letter.
Synopsis
#include <ctype.h>
int toupper(int c);
Returns
If the argument is a lowercase letter, the toupper function returns the corresponding
uppercase letter, if any; otherwise, the argument is returned unchanged.
Example
char c='a';
int i;
i=toupper(c);
va_arg
Expands to an expression that has the type and value of the next argument in the call. The
parameter ap is the same as the va_list ap initialized by va_start. Each invocation of
va_arg modifies ap so that successive arguments are returned in turn. The parameter type
UM004407-0104
Z8 User Manual
240
is a type name such that the type of a pointer to an object that has the specified type can be
obtained simply by fixing a * to type. If type disagrees with the type of the actual next
argument (as promoted, according to the default argument conversions, into int, unsigned
int, or double), the behavior is undefined.
Synopsis
#include <stdarg.h>
type va_arg(va_list ap, type);
Returns
The first invocation of the va_arg macro after that of the va_start macro returns the
value of the argument after that specified by parmN. Successive invocations return the values of the remaining arguments in succession.
Example
The function f1 gathers into an array a list of arguments that are pointers to strings (but not
more than MAXARGS arguments), then passes the array as a single argument to function
f2. The number of pointers is specified by the first argument to f1.
#define MAXARGS 31
va_list ap;
char *array[MAXARGS];
int ptr_no = 0;
if (n_ptrs > MAXARGS)
n_ptrs = MAXARGS;
va_start(ap, n_ptrs);
while (ptr_no < n_ptrs)
array[ptr_no++] = va_arg(ap, char *);
va_end(ap);
f2(n_ptrs, array);
Each call to f1 has in scope the definition of the function of a declaration such as void
f1(int, ...);
va_end
Facilitates a normal return from the function whose variable argument list was referenced
by the expansion of va_start that initialized the va_list ap. The va_end function can
modify ap so that it is no longer usable (without an intervening invocation of va_start).
If the va_end function is not invoked before the return, the behavior is undefined.
Synopsis
#include <stdarg.h>
void va_end(va_list ap);
UM004407-0104
Z8 User Manual
241
Example
#define MAXARGS 31
va_list ap;
int ptr_no = 0;
n_ptrs = MAXARGS;
va_end(ap);
f2(n_ptrs, array);
f1(int, ...);
va_start
Is executed before any access to the unnamed arguments.
The parameter ap points to an object that has type va_list. The parameter parmN is the
identifier of the rightmost parameter in the variable parameter list in the function definition (the one just before the , ...). The va_start macro initializes ap for subsequent use
by va_arg and va_end.
Synopsis
#include <stdarg.h>
void va_start(va_list ap, parmN);
Example
#define MAXARGS 31
va_list ap;
int ptr_no = 0;
n_ptrs = MAXARGS;
UM004407-0104
Z8 User Manual
242
va_end(ap);
f2(n_ptrs, array);
f1(int, ...);
vprintf
Equivalent to printf, with the variable argument list replaced by arg, which has been initialized by the va_start macro (and possibly subsequent va_arg calls). The vprintf
function does not invoke the va_end function.
Synopsis
#include <stdarg.h>
#include <stdio.h>
int vprintf(char *format, va_list arg);
Returns
The number of characters transmitted, or a negative value if an output error occurred.
Example
va_list va;
/* initialize the variable argument va here */
vprintf("%d %d %d",va)
vsprintf
Equivalent to sprintf, with the variable argument list replaced by arg, which has been
initialized by the va_start macro (and possibly subsequent va_arg calls). The
vsprintf function does not invoke the va_end function.
Synopsis
#include <stdarg.h>
#include <stdio.h>
int vsprintf(char *s, char *format, va_list arg);
Returns
The number of characters written in the array, not counting the terminating null character.
Example
va_list va;
char buf[80];
/*initialize the variable argument va here*/
vsprint("%d %d %d",va);
UM004407-0104
Z8 User Manual
243
SETTING C-COMPILER OPTIONS USING #PRAGMAS
Compiler options can be set in the Project Settings dialog box (on the C tab) or by using
the #pragma directives discussed in this section. See page 84. If the #pragma directive is
inserted in your code, it overrides the selections you made in the Project Settings dialog
box.
#pragma alias
Enables alias checking. The compiler assumes that program variables can be aliased. See
“Alias Checking” on page 87. This pragma is the default.
#pragma noalias
Disables alias checking. Before using this pragma, be sure that the program does not use
aliases, either directly or indirectly. An alias occurs when two variables can reference the
same memory location. The following example illustrates an alias:
func()
{
int x,*p;
p = &x;
/* both “x” and “*p” refer to same
location */
.
.
.
}
If both *p and x are used below the assignment, then malignant aliases exist and the
NOALIAS switch must not be used. Otherwise, alias is benign and the NOALIAS switch
can be used.
#pragma cpu <cpu name>
Defines the target processor to the compiler.
#pragma globalcopy
Enables global copy propagation.
#pragma noglobalcopy
Disables global copy propagation.
#pragma globalcse
Enables global common elimination unless local common subexpressions are disabled.
UM004407-0104
Z8 User Manual
244
#pragma noglobalcse
Disables global copy subexpression elimination.
#pragma globaldeadvar
Enables global dead variable removal.
#pragma noglobaldeadvar
Disables global dead variable removal.
#pragma globalfold
Enables global constant folding.
#pragma noglobalfold
Disables global constant folding.
#pragma intrinsics: <state>
Defines whether intrinsic functions are to be expanded to inline code. <state> can be ON
or OFF. This pragma is the default.
#pragma nointrinsics
Disables the INTRINSICS switch.
#pragma nobss
Does not put uninitialized static data in bss segment; instead it puts it in data segment and
initializes it at link time.
#pragma jumpopt
Enables jump optimizations.
#pragma nojumpopt
Disables jump optimizations.
#pragma localcopy
Enables local copy propagation.
#pragma nolocalcopy
Disables local copy propagation.
UM004407-0104
Z8 User Manual
245
#pragma localcse
Enables local common subexpression elimination.
#pragma nolocalcse
Disables local and global common subexpression elimination.
#pragma localfold
Enables local constant folding.
#pragma nolocalfold
Disables local constant folding.
#pragma localopt
Enables local all optimizations.
#pragma nolocalopt
Disables local all optimizations.
#pragma noopt
Disables optimization.
#pragma optlink
Enables optimized linkage calling conventions.
#pragma nooptlink
Disables optimized linkage calling conventions.
#pragma optsize
Optimizes code for size.
#pragma optspeed
Optimizes code for speed.
#pragma peephole
Enables peephole optimizations.
UM004407-0104
Z8 User Manual
246
#pragma nopeephole
Disables peephole optimizations.
#pragma promote
Enables ANSI integral promotions.
#pragma nopromote
Disables ANSI integral promotions.
#pragma sdiopt
Performs span-dependent instruction optimization. This optimization results in branches
generated by the compiler taking the shortest form possible. This pragma is the default.
#pragma nosdiopt
Disables span-dependent instruction optimizations. In the event that assembly language
statements inserted into the assembly file using the #pragma asm preprocessor directive
cause out of range errors in the assembler, use this switch to disconnect it.
#pragma stkck
Performs stack checking.
#pragma nostkck
Does not perform stack checking.
#pragma strict
Checks for conformance to the ANSI standard and its obsolescent features. These include
old style parameter type declarations, empty formal parameter lists, and calling functions
with no prototype in scope. When any of these features are used a warning is flagged. The
compiler requires this switch for proper code generation because it makes use of a static
frame.
#pragma nostrict
Does not flag warnings for obsolete features.
EMBEDDING ASSEMBLY IN C
There are two methods of inserting assembly language within C code. The first uses the
#pragma feature of ANSI C with the following syntax:
#pragma asm “<assembly line>”
UM004407-0104
Z8 User Manual
247
#pragma can be inserted anywhere within the C source file. The contents of
<assembly line> must be legal assembly language syntax. The usual C escape sequences
(such as \n, \t, \r, ...) are properly translated. Currently the compiler does not
process the <assembly line>. Except for escape sequences, it is passed through the compiler verbatim.
The second method of inserting assembly language is using the asm statement. The asm
statement is displayed only within the body of a function and takes the following form:
asm(“<assembly line>”);
The asm statement cannot be within an expression and can be used only within the body of
a function. To insert assembly text anywhere within the assembly file generated by the
compiler, you must use #pragma instead.
The <assembly line> can be any string.
Caution: The compiler does not check the legality of the string. Therefore, exercise extreme care
when using the asm statement because you might get incorrect code. View the code the
compiler generates before inserting asm statements.
As with the #pragma asm form, the compiler does not process the assembly line except
for translating the standard C escape sequences.
C Variables in Embedded Assembly
Assembly embedded within C source code using the asm() statement can now reference
variables by their proper C names. Variable names must be preceded by a backslash (\) to
indicate the beginning of a variable name. The compiler automatically translates these
variable names into the appropriate assembly syntax. For example:
//
// Be sure register variables are enabled!
//
int ia[10];
void test(int x,int y)
{
register int i;
register volatile int *p = ia;
for (i=0;i<3;++i) {
asm(" LD A,@\p+LOOP");
asm(" LD \i,A");
asm(" LD A,\y");
asm(" LD \x,A");
}
}
UM004407-0104
Z8 User Manual
248
The compiler translates the asm() statements into the following:
LD
LD
LD
LD
A,@P0:0+LOOP
D0:0,A
A,.1_test
.0_test,A
If the identifier following the backslash is a variable that is not in scope or has been optimized away, an error message is generated.
Caution: Enable the register variables if you want your embedded assembly to assume that a variable is stored in a register.
Using variable names that, when preceded by a backslash, match a C escape sequence
(\n, \t, \b, and so on) is not translated into the variable's syntax, but rather the ASCII
character of the escape sequence. If you have a variable named n, t, or b then you must
escape the backslash with another backslash:
Using variable names that, for example,
asm(“\tLD A,\\temp\n”);
is translated into:
<tab>LD A,_0temp<newline>
CALLING ASSEMBLY FROM C
Assigned Function Names
Assembly routine names must be preceded with an _ (underscore). When the compiler
generates the assembly file, all function names are prefixed with an underscore. For example, when calling the function myfunc(), the assembly has an entry label:
_myfunc:
Passing Arguments
When passing arguments to the routine, enumerate the arguments from right to left in this
manner: .<argno>_<function name>
For example, using a C prototype of
myfunc(short arga, long argb, short *argc)
the C routine places
argc at .0_myfunc
argb at .1_myfunc
arga at .2_myfunc
Passing arguments in static frames is done by placing the arguments into static locations
of memory. Each argument is given a unique public name derived from the name of the
UM004407-0104
Z8 User Manual
249
function being called. The linker then overlays these frames as much as possible based on
the call graph of the program.
Passing argument in dynamic frames is done by pushing the arguments on the stack in
reverse (right to left) order.
Return Values
When a function returns a value to its caller, it is stored in a register. The following registers are used by the compiler:
r0–r13
register values, and intermediate calculations
r15
small model frame pointer
rr14
large model frame pointer
The C routines expect the values to be located in the registers listed in Table 16.
Table 16. Function Value Locations
Value
Register
char
r0
short
rr0
int
rr0
long
rr0:rr2
float
rr0:rr2
near pointer
r0
far pointer
rr0
For example, if the prototype is
long myfunct(short arga, long argb, short *argc);
then the C routine expects the result in rr0 and rr2 registers for the returned long.
Preserving Registers
The calling C routine preserves all registers it needs; the assembly routine does not need to
preserve any registers. The called routine only needs to preserve rr14 if it is modified.
UM004407-0104
Z8 User Manual
250
Using the .FRAME Directive
It is a good idea to have the assembly routine have its data overlaid with other routines that
cannot be called at the same time. This function is handled by using the .FRAME directive.
The .FRAME directive takes the following form:
.FRAME
<function name>,._<function name>,<space>
Data Alignment
The compiler aligns all data items on a 16-bit word boundary.
TROUBLESHOOTING C PROGRAMS
Review this section to learn the answers to the following questions:
•
•
•
•
•
“How do I speed up the compiler?” on page 250
•
•
•
•
•
•
•
•
“How do I make my C program faster?” on page 252
“How do I call assembly from C?” on page 251
“Why does the compiler generate temporary variables?” on page 251
“How do I make my C program smaller?” on page 252
“Why is my code bigger when I select Optimize for Size than when I select Optimize
for Speed?” on page 252
“How do I create an interrupt handler in C?” on page 252
“Can interrupt handlers take arguments?” on page 253
“What is a register variable?” on page 253
“How do I embed assembly into my C code?” on page 253
“Why does the compiler give incompatible type errors?” on page 254
“Why do floating-point operations give incorrect results?” on page 254
“Why don’t I see codes generated for my C statements?” on page 254
How do I speed up the compiler?
Use the following tips to lower compiler execution times:
1. If you are not using floating-point operations in your program, deselect the Use
Floating Point Library check box on the Project Settings dialog box (C tab, General
category). See “Use Floating Point Library” on page 86.
2. If you do not intend to use the debugger, select None in the Debug Information dropdown list box on the Project Settings dialog box (C tab, General category). See
“Debug Information” on page 85.
UM004407-0104
Z8 User Manual
251
3. Make sure that all DOS windows are minimized.
How do I call assembly from C?
For more information on this feature, see “Calling Assembly from C” on page 248.
Why does the compiler generate temporary variables?
The compiler is forced by the semantics of C to generate temporary variables in some
cases. Usually, these temporary variables are placed in registers. But, if the compiler runs
out of registers to use, it must place them in the static frame of the function they are used
in.
There are two common constructs that require the generation of temporary variables, ternary]=” operations and post increment/decrement.
The ? operator requires a temporary to hold the true and false values. If the temporaries are
causing you problems you must recode:
a = b > c ? d : e;
to
int temp;
if (b > c)
temp = d;
else
temp = e;
a = temp;
The variable temp can be re-used in other expressions.
The second common reason that the compiler generates temporaries is for the post-increment and post-decrement operators. The compiler stores the old value so that it can be
used after certain operations on the data. For example,
a = *p++;
is converted to
temp = p;
p = p + 1;
a = *temp;
The compiler tries to optimize away temp whenever possible. When it is not possible, the
compiler tries to place temp in a register. If there are no registers available, then temp
must be stored in the function's static frame.
Note: Using pre-increment/-decrement wherever possible eliminates the need for temporary
variables.
UM004407-0104
Z8 User Manual
252
How do I make my C program smaller?
Use one of the following tips to make your C programs smaller:
•
The Z8 developer’s environment ANSI C-Compiler has an optimizer which can be
configured to optimize for speed or size. In the Project Settings dialog box (C tab,
Optimizations category), select Minimize Size from the Optimizations drop-down list
box or insert #pragma optsize in your code to generate smaller code. See
“Optimizations Category” on page 89. In some instances, this selection can reduce
your code size by as much as 50%.
•
If you do not need to use floating point operations, deselect the Use Floating Point
Library check box (C tab, General category) on the Project Settings dialog box. See
“Use Floating Point Library” on page 86.
•
Modify or avoid using the run-time library. The C run-time library is supplied as a
time-saver. However, for the sake of generality, the routines in the run-time library
might cover cases that do not apply to you. In this case, consider writing your own
routines or modifying the run-time library routines themselves to discard the excess
code.
Why is my code bigger when I select Optimize for Size than when I
select Optimize for Speed?
When your code is small and has two to three switch statements, select Optimize for
Speed (C tab, Optimizations category) on the Project Settings dialog box to generate
smaller code. See “Optimizations Category” on page 89.
How do I make my C program faster?
Use the following tips to make your programs run faster:
•
In the Project Settings dialog box (C tab, Optimizations category), select Maximize
Speed from the Optimizations drop-down list box or place #pragma optspeed in
your code. See “Optimizations Category” on page 89.
•
Deselect the Alias Checking check box in the Project Settings dialog box (C tab, Code
Generation category). See “Alias Checking” on page 87.
How do I create an interrupt handler in C?
The interrupt keyword is a storage class that applies only to functions. It signifies that
a function is to be an interrupt handler. This keyword causes the compiler to produce code
to preserve the current machine state at the beginning of the function and restore it on exit.
To preserve the current state, the compiler generates code to switch current register banks
and pushes/pops registers.
The SET_VECTOR macro is used to attach a C function, which is an interrupt handler, to an
interrupt vector. Because SET_VECTOR does not generate any code, it can be placed within
UM004407-0104
Z8 User Manual
253
any function of your program where the interrupt handler function is in scope. However,
for clarity, it is best to place the SET_VECTOR macro within the interrupt handler itself. For
example:
#include <Z8.h>
void interrupt int0_handler(void)
{SET_VECTOR(INT0,int0_handler);
/* Body of handler */
}
For the names of interrupt vectors, see “SET_VECTOR” on page 227.
Can interrupt handlers take arguments?
No. Because an interrupt handler is not called from another function, but vectored to by
the hardware, it is not possible to pass arguments to it. If arguments are required, they
must be placed into global static variables. Declaring interrupt handlers in any way other
than void interrupt <name>(void) results in type compatibility errors when expanding the SET_VECTOR macro.
What is a register variable?
A register variable is a variable local to a function that resides in a hardware register. Register variables are indicated by the register storage class. Global or static variables
declared with the register storage class are not stored in registers.
How do I embed assembly into my C code?
There are two ways to embed assembly into your C code. The first method is to use the
asm pragma. For example:
#pragma asm “INCLUDE \”MYINC.INC\””
The contents of the string is inserted into the assembly file generated by the compiler. You
can place multiple lines of assembly in a #pragma asm by separating them with a newline
(\n). For example:
#pragma asm “INCLUDE \”MYINC.INC\”\n”
“INCLUDE \”YOURINC.INC\””
This method can be used to place assembly code anywhere within your program. However, the second method which uses the asm statement must reside within the body of a
function. For example:
void test(void)
{
asm(“MOV
}
R0,#0”);
The compiler knows nothing about the contents of embedded assembly. Therefore,
embedding assembly might cause compiler optimizations to be incorrect. Before inserting
UM004407-0104
Z8 User Manual
254
assembly into your C code, look first at the code generated by the compiler (it resides in
the .src file) to make sure that the embedded code functions correctly.
Why does the compiler give incompatible type errors?
A common source of incompatible type errors are objects or type expressions declared
using the const storage class. In strict ANSI C, the const storage class simply means that
the compiler must not allow the object to be an lvalue. In other words, it is not modifiable.
The developer’s environment compiler places const object in the CODE space. Because
objects placed in ROM require a different access method, the compiler must strictly check
the types of const object. Otherwise, your code compiles, but does not run correctly. For
example:
const char a[10] = {0,1,2,3,4,5,6,7,8,9};
void test(void)
{
char *p1 = a;/* Error */
char const *p2 = a;/* OK */
}
Why do floating-point operations give incorrect results?
The most common reason for floating-point operations giving incorrect results is that the
Use Floating Point Library check box on the Project Settings dialog box (C tab, General
category) is not checked. See “Use Floating Point Library” on page 86. Because relatively
few embedded microcontroller applications require the use of floating point, Z8 developer’s environment uses a version of the run-time library that features all floating-point
routines stubbed out, which saves a significant amount of code. If the Use Floating Point
Library check box is checked, the floating-point routines are linked into your program as
necessary and give the correct results.
Why don’t I see codes generated for my C statements?
The compiler comes with a powerful optimizer that makes your program smaller and/or
faster. It removes inefficiencies or codes that are not used.
ERROR MESSAGES
This section covers the following:
•
•
•
UM004407-0104
“Preprocessor Error Messages” on page 255
“Front-End Error Messages” on page 257
“Code Generator Error Messages” on page 265
Z8 User Manual
255
Preprocessor Error Messages
ERROR (001) Illegal constant expression in directive.
A constant expression made up of constants and macros that evaluate to constants can
be the only operands of an expression used in a preprocessor directive.
ERROR (002) Concatenation at end-of-file. Ignored.
An attempt was made to concatenate lines with a backslash when the line is the last
line of the file.
ERROR (003) Illegal token.
An unrecognizable token or non-ASCII character was encountered.
ERROR (004) Illegal redefinition of macro <name>.
An attempt was made to redefine a macro, and the tokens in the macro definition do
not match those of the previous definition.
ERROR (005) Incorrect number of arguments for macro <name>.
An attempt was made to call a macro, but too few or too many arguments were given.
ERROR (006) Unbalanced parentheses in macro call.
An attempt was made to call a macro with a parenthesis embedded in the argument list
that did not match up.
ERROR (007) Cannot redefine <name> keyword.
An attempt was made to redefine a keyword as a macro.
ERROR (008) Illegal directive.
The syntax of a preprocessor directive is incorrect.
ERROR (009) Illegal "#if" directive syntax.
The syntax of a #if preprocessor directive is incorrect.
ERROR (010) Bad preprocessor file. Aborted.
An unrecognizable source file was given to the compiler.
ERROR (011) Illegal macro call syntax.
An attempt was made to call a macro that does not conform to the syntax rules of the
language.
ERROR (012) Integer constant too large.
An integer constant that has a binary value too large to be stored in 32 bits was
encountered.
UM004407-0104
Z8 User Manual
256
ERROR (013) Identifier <name> is undefined
The syntax of the identifier is incorrect.
ERROR (014) Illegal #include argument.
The argument to a #include directive must be of the form "pathname" or <filename>.
ERROR (015) Macro "<name>" requires arguments.
An attempt was made to call a macro defined to have arguments and was given none.
ERROR (016) Illegal "#define" directive syntax.
The syntax of the #define directive is incorrect.
ERROR (017) Unterminated comment in preprocessor directive.
Within a comment, an end of line was encountered.
ERROR (018) Unterminated quoted string.
Within a quoted string, an end of line was encountered.
ERROR (019) Escape sequence ASCII code too large to fit in char.
The binary value of an escape sequence requires more than 8 bits of storage.
ERROR (020) Character not within radix.
An integer constant was encountered with a character greater than the radix of the
constant.
ERROR (021) More than four characters in string constant.
A string constant was encountered having more than four ASCII characters.
ERROR (022) End of file encountered before end of macro call.
The end of file is reached before right parenthesis of macro call.
ERROR (023) Macro expansion caused line to be too long.
The line needs to be shortened.
ERROR (024) "##" cannot be first or last token in replacement string.
The macro definition cannot have “##” operator in the beginning or end.
ERROR (025) "#" must be followed by an argument name.
In a macro definition, “#” operator must be followed by an argument.
ERROR (026) Illegal "#line" directive syntax.
In #line <linenum> directive, <linenum> must be an integer after macro expansion.
ERROR (027) Cannot undefine macro "name".
The syntax of the macro is incorrect.
UM004407-0104
Z8 User Manual
257
ERROR (028) End-of-file found before "#endif" directive.
#if directive was not terminated with a corresponding #endif directive.
ERROR (029) "#else" not within #if and #endif directives.
#else directive was encountered before a corresponding #if directive.
ERROR (030) Illegal constant expression.
The constant expression in preprocessing directive has invalid type or syntax.
ERROR (031) Illegal macro name <name>.
The macro name does not have a valid identifier syntax.
ERROR (032) Extra "#endif" found.
#endif directive without a corresponding #if directive was found.
ERROR (033) Division by zero encountered.
Divide by zero in constant expression found.
ERROR (034) Floating point constant over/underflow.
In the process of evaluating a floating-point expression, the value became too large to
be stored.
ERROR (035) Concatenated string too long.
Shorten the concatenated string.
ERROR (036) Identifier longer than 32 characters.
Identifiers must be 32 characters or shorter.
ERROR (037) Unsupported CPU "name" in pragma.
An unknown CPU encountered.
ERROR (038) Unsupported or poorly formed pragma.
An unknown #pragma directive encountered.
Front-End Error Messages
ERROR (101) Syntax error.
A syntactically incorrect statement, declaration, or expression was encountered.
ERROR (102) Function "<name>" already declared.
An attempt was made to define two functions with the same name.
ERROR (103) Constant integer expression expected.
A non-integral expression was encountered where only an integral expression can be.
UM004407-0104
Z8 User Manual
258
ERROR (104) Constant expression overflow.
In the process of evaluating a constant expression, value became too large to be stored
in 32 bits.
ERROR (105) Function return type mismatch for "<name>".
A function prototype or function declaration was encountered that has a different
result from a previous declaration.
ERROR (106) Argument type mismatch for argument <name>.
The type of an actual parameter does not match the type of the formal parameter of the
function called.
ERROR (107) Cannot take address of un-subscripted array.
An attempt was made to take the address of an array with no index. The address of the
array is already implicitly calculated.
ERROR (108) Function call argument cannot be void type.
An attempt was made to pass an argument to a function that has type void.
ERROR (109) Identifier "<name>" is not a variable or enumeration constant name.
In a declaration, a reference to an identifier was made that was not a variable name or
an enumeration constant name.
ERROR (110) Cannot return a value from a function returning "void".
An attempt was made to use a function defined as returning void in an expression.
ERROR (111) Expression must be arithmetic, structure, union or pointer type.
The type of an operand to a conditional expression was not arithmetic, structure, union
or pointer type.
ERROR (112) Integer constant too large
Reduce the size of the integer constant.
ERROR (113) Expression not compatible with function return type.
An attempt was made to return a value from function that cannot be promoted to the
type defined by the function declaration.
ERROR (114) Function cannot return value of type array or function.
An attempt was made to return a value of type array or function.
ERROR (115) Structure or union member may not be of function type.
An attempt was made to define a member of structure or union that has type function.
UM004407-0104
Z8 User Manual
259
ERROR (116) Cannot declare a typedef within a structure or union.
An attempt was made to declare a typedef within a structure or union.
ERROR (117) Illegal bit field declaration.
An attempt was made to declare a structure or union member that is a bit field and is
syntactically incorrect.
ERROR (118) Unterminated quoted string
Within a quoted string, an end of line was encountered.
ERROR (119) Escape sequence ASCII code too large to fit in char
The binary value of an escape sequence requires more than 8 bits of storage.
ERROR (120) Character not within radix
An integer constant was encountered with a character greater than the radix of the
constant.
ERROR (121) More than one character in string constant
A string constant was encountered having more than one ASCII character.
ERROR (122) Illegal declaration specifier.
An attempt was made to declare an object with an illegal declaration specifier.
ERROR (123) Only "const" and "volatile" may be specified with a struct, union, enum, or
typedef.
An attempt was made to declare a struct, union, enum, or typedef with a declaration
specifier other than const and volatile.
ERROR (124) Cannot specify both long and short in declaration specifier.
An attempt was made to specify both long and short in the declaration of an object.
ERROR (125) Only "const" and "volatile" may be specified within pointer declarations.
An attempt was made to declare a pointer with a declaration specifier other than const
and volatile.
ERROR (126) Identifier "<name>" already declared within current scope.
An attempt was made to declare two objects of the same name in the same scope.
ERROR (127) Identifier "<name>" not in function argument list, ignored.
An attempt was made to declare an argument that is not in the list of arguments when
using the old style argument declaration syntax.
UM004407-0104
Z8 User Manual
260
ERROR (128) Name of formal parameter not given.
The type of a formal parameter was given in the new style of argument declarations
without giving an identifier name.
ERROR (129) Identifier "<name>" not defined within current scope.
An identifier was encountered that is not defined within the current scope.
ERROR (130) Cannot have more than one default per switch statement.
More than one default statements were found in a single switch statement.
ERROR (131) Label "<name>" is already declared.
An attempt was made to define two labels of the same name in the same scope.
ERROR (132) Label "<name> not declared.
A goto statement was encountered with an undefined label.
ERROR (133) "continue" statement not within loop body.
A continue statement was found outside a body of any loop.
ERROR (134) "break" statement not within switch body or loop body.
A break statement was found outside the body of any loop.
ERROR (135) "case" statement must be within switch body.
A case statement was found outside the body of any switch statement.
ERROR (136) "default" statement must be within switch body.
A default statement was found outside the body of any switch statement.
ERROR (137) Case value <name> already declared.
An attempt was made to declare two cases with the same value.
ERROR (138) Expression is not a pointer.
An attempt was made to dereference value of an expression whose type is not a
pointer.
ERROR (139) Expression is not a function locator.
An attempt was made to use an expression as the address of a function call that does
not have a type pointer to function.
ERROR (140) Expression to left of "." or "->" is not a structure or union.
An attempt was made to use an expression as a structure or union, or a pointer to a
structure or union, whose type was neither a structure or union, or a pointer to a
structure or union.
UM004407-0104
Z8 User Manual
261
ERROR (141) Identifier "<name>" is not a member of <name> structure.
An attempt was made to reference a member of a structure that does not belong to the
structure.
ERROR (142) Object cannot be subscripted.
An attempt was made to use an expression as the address of an array or a pointer that
was not an array or pointer.
ERROR (143) Array subscript must be of integral type.
An attempt was made to subscript an array with a non integral expression.
ERROR (144) Cannot dereference a pointer to "void".
An attempt was made to dereference a pointer to void.
ERROR (145) Cannot compare a pointer to a non-pointer.
An attempt was made to compare a pointer to a non-pointer.
ERROR (146) Pointers to different types may not be compared.
An attempt was made to compare pointers to different types.
ERROR (147) Pointers may not be added.
It is not legal to add two pointers.
ERROR (148) A pointer and a non-integral may not be subtracted.
It is not legal to subtract a non-integral expression from a pointer.
ERROR (149) Pointers to different types may not be subtracted.
It is not legal to subtract two pointers of different types.
ERROR (150) Unexpected end of file encountered.
In the process of parsing the input file, end of file was reached during the evaluation of
an expression, statement, or declaration.
ERROR (151) Unrecoverable error encountered.
The compiler became confused beyond the point of recovery.
ERROR (152) Operand must be a modifiable lvalue.
An attempt was made to assign a value to an expression that was not modifiable.
ERROR (153) Operands are not assignment compatible.
An attempt was made to assign a value whose type cannot be promoted to the type of
the destination.
UM004407-0104
Z8 User Manual
262
ERROR (154) "<name>" must be arithmetic type.
An expression was encountered whose type was not arithmetic where only arithmetic
types are allowed.
ERROR (155) "<name>" must be integral type.
An expression was encountered whose type was not integral where only integral types
are allowed.
ERROR (156) "<name>" must be arithmetic or pointer type.
An expression was encountered whose type was not pointer or arithmetic where only
pointer and arithmetic types are allowed.
ERROR (157) Expression must be an lvalue.
An expression was encountered that is not an lvalue where only an lvalue is allowed.
ERROR (158) Cannot assign to an object of constant type.
An attempt was made to assign a value to an object defined as having constant type.
ERROR (159) Cannot subtract a pointer from an arithmetic expression.
An attempt was made to subtract a pointer from an arithmetic expression.
ERROR (160) An array is not a legal lvalue.
Cannot assign an array to an array.
ERROR (161) Cannot take address of a bit field.
An attempt was made to take the address of a bit field.
ERROR (162) Cannot take address of variable with "register" class.
An attempt was made to take the address of a variable with "register" class.
ERROR (163) Conditional expression operands are not compatible.
One operand of a conditional expression cannot be promoted to the type of the other
operand.
ERROR (164) Casting a non-pointer to a pointer.
An attempt was made to promote a non-pointer to a pointer.
ERROR (165) Type name of cast must be scalar type.
An attempt was made to cast an expression to a non-scalar type.
ERROR (166) Operand to cast must be scalar type.
An attempt was made to cast an expression whose type was not scalar.
UM004407-0104
Z8 User Manual
263
ERROR (167) Expression is not a structure or union.
An expression was encountered whose type was not structure or union where only a
structure or union is allowed.
ERROR (168) Expression is not a pointer to a structure or union.
An attempt was made to dereference a pointer with the arrow operator, and the
expression’s type was not pointer to a structure or union.
ERROR (169) Cannot take size of void, function, or bit field types.
An attempt was made to take the size of an expression whose type is void, function, or
bit field.
ERROR (170) Actual parameter has no corresponding formal parameter.
An attempt was made to call a function whose formal parameter list has fewer
elements than the number of arguments in the call.
ERROR (171) Formal parameter has no corresponding actual parameter.
An attempt was made to call a function whose formal parameter list has more
elements than the number of arguments in the call.
ERROR (172) Argument type is not compatible with formal parameter.
An attempt was made to call a function with an argument whose type is not
compatible with the type of the corresponding formal parameter.
ERROR (173) Identifier "<name>" is not a structure or union tag.
An attempt was made to use the dot operator on an expression whose type was not
structure or union.
ERROR (174) Identifier "<name>" is not a structure tag.
The tag of a declaration of a structure object does not have type structure.
ERROR (175) Identifier "<name>" is not a union tag.
The tag of a declaration of a union object does not have type union.
ERROR (176) Structure or union tag "<name>" is not defined.
The tag of a declaration of a structure or union object is not defined.
ERROR (177) Only one storage class may be given in a declaration.
An attempt was made to give more than one storage class in a declaration.
ERROR (178) Type specifier cannot have both "unsigned" and "signed".
An attempt was made to give both unsigned and signed type specifiers in a
declaration.
UM004407-0104
Z8 User Manual
264
ERROR (179) "unsigned" and "signed" may be used in conjunction only with "int",
"long" or "char".
An attempt was made to use signed or unsigned in conjunction with a type specifier
other than int, long, or char.
ERROR (180) "long" may be used in conjunction only with "int" or "double".
An attempt was made to use long in conjunction with a type specifier other than int or
double.
ERROR (181) Illegal bit field length.
The length of a bit field was outside of the range 0-32.
ERROR (182) Too many initializers for object.
An attempt was made to initialize an object with more elements than the object
contains.
ERROR (183) Static objects can be initialized with constant expressions only.
An attempt was made to initialize a static object with a non-constant expression.
ERROR (184) Array "<name>" has too many initializers.
An attempt was made to initialize an array with more elements than the array contains.
ERROR (185) Structure "<name>" has too many initializers.
An attempt was made to initialize a structure with more elements than the structure
has members.
ERROR (186) Dimension size may not be omitted.
An attempt was made to omit the dimension of an array which is not the rightmost
dimension.
ERROR (187) First dimension of "<name>" may not be omitted.
An attempt was made to omit the first dimension of an array which is not external and
is not initialized.
ERROR (188) Dimension size must be greater than zero.
An attempt was made to declare an array with a dimension size of zero.
ERROR (189) Only "register" storage class is allowed for formal parameter.
An attempt was made to declare a formal parameter with storage class other than
register.
ERROR (190) Cannot take size of array with missing dimension size.
An attempt was made to take the size of an array with an omitted dimension.
UM004407-0104
Z8 User Manual
265
ERROR (191) Identifier "<name>" already declared with different type or linkage.
An attempt was made to declare a tentative declaration with a different type than a
declaration of the same name; or, an attempt was made to declare an object with a
different type from a previous tentative declaration.
ERROR (192) Cannot perform pointer arithmetic on pointer to void.
An attempt was made to perform pointer arithmetic on pointer to void.
ERROR (193) Cannot initialize object with "extern" storage class.
An attempt was made to initialize variable with extern storage class.
ERROR (194) Missing "<name>" detected.
An attempt was made to use a variable without any previous definition or declaration.
ERROR (195) Recursive structure declaration.
A structure member can not be of same type as the structure itself.
ERROR (196) Initializer is not assignment compatible.
The initializer type does not match with the variable being initialized.
ERROR (197) Empty parameter list is an obsolescent feature.
Empty parameter lists are not allowed.
ERROR (198) No function prototype "<name>" in scope.
The function <name> is called without any previous definition or declaration.
ERROR (199) "old style" formal parameter declarations are obsolescent.
Change the parameter declarations.
ERROR (200) Data objects cannot have "io" storage class.
Change the storage class.
ERROR (201) Cannot shift by a fract.
Change the shift statement.
Code Generator Error Messages
ERROR (303) Case value <number> already defined.
If a case value consists of an expression containing a sizeof, its value is not known
until code generation time. Thus, it is possible to have two cases with the same value
not caught by the front end. Review the switch statement closely.
UM004407-0104
Z8 User Manual
266
ERROR (308) Excessive Registers required at line <num> of function <func>.
Excessive Page 0 registers are required at line number <num>. The compiler does not
perform register spilling, so complex expressions that generate this error must be
factored into two or more expressions.
ERROR (309) Interrupt function <name> cannot have arguments.
A function declared as an interrupt function cannot have function arguments.
ERROR (310) Index out of range, truncating index of <num> to 255.
The compiler detected an array access outside of the 0.255 byte range. Use a
temporary variable if you need to access an array element outside of this range.
ERROR (312) Aggregate Copy out of range, truncating copy size of <num> to 255.
The compiler limits structure sizes to 255 bytes. An attempt was made to copy
structures greater than 255 bytes. Use the memcpy library function if structures
greater than 255 bytes are required.
ERROR (313) Bitfield Length exceeds 8 bits.
The compiler only accepts bitfield lengths of 8 bits or less.
UM004407-0104
Z8 User Manual
267
5
Using the Macro Assembler
You use the Macro Assembler to translate Z8 assembly language files with the .asm
extension into relocatable object modules with the .obj extension. After your relocatable
object modules are complete, you convert them into an executable program using the
linker/locator. The Macro Assembler can be configured using the Assembler tab of the
Project Settings dialog box (see “Assembler Tab” on page 96).
The following topics are covered in this chapter:
•
•
•
•
•
•
•
•
•
•
•
•
•
“Address Spaces and Segments” on page 268
“Output Files” on page 270
“Source Language Structure” on page 272
“Expressions” on page 274
“Directives” on page 277
“Conditional Assembly” on page 289
“Macros” on page 292
“Labels” on page 295
“Addressing Modes” on page 296
“Source Language Syntax” on page 296
“Compatibility Issues” on page 300
“Troubleshooting the Assembler” on page 303
“Error Messages” on page 303
Note: For more information about Z8 instructions, see the “Instruction Description and Formats”
section of the Z8 Microcontroller User’s Manual (UM0016).
UM004407-0104
5 Using the Macro Assembler
Z8 User Manual
268
ADDRESS SPACES AND SEGMENTS
You access the memory regions of the Z8 family microcontroller by using segment directives. A segment is a contiguous set of memory locations. All segments are attached to
exactly one memory space. The Z8 Assembler has predefined spaces and segments.
Allocating Processor Memory
All memory locations, whether data or code, must be defined within a segment. There are
two types of segments:
•
Absolute segments
An absolute segment is any segment with a fixed origin. The origin of a segment can
be defined with the ORG directive. All data and code in an absolute segment is located
at the specified physical memory address.
•
Relocatable segments
A relocatable segment is a segment without a specified origin. At link time, linker
commands are used to specify where relocatable segments are to be located within
their space. Relocatable segments can be assigned to different physical memory
locations without re-assembling.
Address Spaces
The memory regions for the Z8 microprocessor are represented by the address spaces
listed in Table 17.
Table 17. Z8 Address Spaces
Space ID
MAU Size
MAX MAUS Per Address
ROM
8 bits
1 (default)
RDATA
8 bits
1
XDATA
8 bits
1
Code and data is allocated to these spaces by using segments attached to the space.
Segments
Segments are used to represent regions of memory. Only one segment is considered active
at any time during the assembly process. A segment must be defined before setting it as
the current segment. A segment is associated with an address space.
UM004407-0104
Z8 User Manual
269
Predefined Segments
For convenience, the segments listed in Table 18 are predefined by the assembler.
Table 18. Predefined Segments
Segment ID
Space
Alignment
Default Origin
near_bss
RDATA
1 byte
Relocatable
far_bss
XDATA
1 byte
Relocatable
near_data
RDATA
1 byte
Relocatable
far_data
ROM
1 byte
Relocatable
rom_text
XDATA
1 byte
Relocatable
code
ROM
1 byte
Relocatable
text
ROM
1 byte
Relocatable
User-Defined Segments
You can define a new segment using the following directives:
DEFINE MYSEG,SPACE=ROM
SEGMENT MYSEG
MYSEG becomes the current segment when the assembler processes the SEGMENT directive, and MYSEG remains the current segment until a new SEGMENT directive appears.
MYSEG can be used as a segment name in the linker command file.
You can define a new segment in RAM using the following directives:
DEFINE MYDATA,SPACE=RAM
SEGMENT MYDATA
The DEFINE directive creates a new segment and attaches it to a space. For more information about using the DEFINE directive, see “DEFINE” on page 282. The SEGMENT directive attaches code and data to a segment. The SEGMENT directive makes that segment the
current segment. Any code or data following the directive resides in the segment until
another SEGMENT directive is encountered. For more information about the SEGMENT
directive, see “SEGMENT” on page 287.
A segment can also be defined with a boundary alignment and/or origin:
•
Alignment
Aligning a segment tells the linker to place all instances of the segment in your
program on the specified boundary.
Note: Although a module can enter and leave a segment many times, each module still has only
one instance of a segment.
UM004407-0104
Z8 User Manual
270
•
Origin
When a segment is defined with an origin, the segment becomes an absolute segment,
and the linker places it at the specified physical address in memory.
Assigning Memory at Link Time
At link time, the linker groups those segments of code and data that have the same name
and places the resulting segment in the address space to which it is attached. However, the
linker handles relocatable segments and absolute segments differently:
•
Relocatable segments
If a segment is relocatable, the linker decides where in the address space to place the
segment.
•
Absolute segments
If a segment is absolute, the linker places the segment at the absolute address
specified as its origin.
Note: At link time, you can redefine segments with the appropriate linker commands.
OUTPUT FILES
The assembler creates the following files and names them the name of the source file but
with a different extension:
•
<source>.lst contains a readable version of the source and object code generated by
the assembler. The assembler creates <source>.lst unless you deselect the Generate
Listing File (.lst) check box in the Assembler tab of the Project Settings dialog box.
See “Generate Listing File (.lst)” on page 97.
•
<source>.obj is an object file in relocatable OMF695 format. The assembler creates
<source>.obj unless you deselect the Generate Object check box in the Assembler
tab of the Project Settings dialog box. See “Generate Object” on page 97.
Caution: Do not use source input files with .lst or .obj extensions. The assembler does not assemble files with these extensions, and therefore the data contained in the files is lost.
Source Listing (.lst) Format
The listing file name is the same as the source file name with a .lst file extension.
Assembly directives allow you to tailor the content and amount of output from the assembler.
Each page of the listing file (.lst) contains the following:
•
•
UM004407-0104
Heading with the assembler version number
Source input file name
Z8 User Manual
271
•
Date and time of assembly
Source lines in the listing file are preceded by the following:
•
•
•
•
•
Include level
Plus sign (+) if the source line contains a macro
Line number
Location of the object code created
Object code
The include level starts at level A and works its way down the alphabet to indicate nested
includes. The format and content of the listing file can be controlled with directives
included in the source file:
•
•
•
•
•
•
NEWPAGE
TITLE
NOLIST
LIST
MACLIST ON/OFF
CONDLIST ON/OFF
Note: Error and warning messages follow the source line containing the error(s). A count of the
errors and warnings detected is included at the end of the listing output file.
The addresses in the assembly listing are relative. To convert the relative addresses into
absolute addresses, use the -relist option for the assembler. For example:
z8asm mfile.src -relist:afile.map
This example uses the information in the .src file (generated by the compiler when the
-keepasm option is used or when the Generate Assembly Source (.src) check box is
selected [see “Listing Files Category” on page 93]) and the .map file to change all of the
relative addresses in the assembly listing into absolute addresses.
Object Code (.obj) File
The object code output file name is the same as the source file name with an .obj extension. This file contains the relocatable object code in OMF695 format and is ready to be
processed by the linker and librarian.
UM004407-0104
Z8 User Manual
272
SOURCE LANGUAGE STRUCTURE
This section describes the form of an assembly source file.
General Structure
A line consists in an assembly source file is either a source line or a comment line. You
should ignore blank lines. Each line of input consists of ASCII characters terminated by a
carriage return. An input line cannot exceed 512 characters.
A backslash (\) at the end of a line is a line continuation. The following line is concatenated onto the end of the line with the backslash, as exemplified in the C programming
language. Place a space or any other character after the backslash, and your code will be
assembled.
Source Line
A source line is composed of an optional label followed by an instruction or a directive. A
source line can contain only a label field.
Comment Line
A semicolon (;) terminates the scanning action of the assembler. Any text following the
semicolon is treated as a comment. A semicolon that appears as the first character causes
the entire line to be treated as comment.
Label Field
If included, the label field must be the first item in a source line. The first character of a
label can be a letter, an underscore _ , a dollar sign ($), a question mark (?), a period (.), or
pound sign (#). Following characters can include letters, digits, underscores, dollar signs
($), question marks (?), periods (.), or pound signs (#). The label can be followed by a
colon (:) that completes the label definition. A label can only be defined once. The maximum label length is 129 characters. See “Labels” on page 295 for more information.
Instruction
An instruction contains one valid assembler instruction that consists of a mnemonic and its
arguments. Use commas to separate the operands. Use a semicolon or carriage return to
terminate the instruction. For more information about Z8 instructions, see the “Instruction
Description and Formats” section of the Z8 Microcontroller User’s Manual (UM0016).
Directive
A directive tells the assembler to perform a specified task. Use a semicolon or carriage
return to terminate the directive. Use spaces or tabs to separate the directive from its operands. See “Directives” on page 277 for more information.
UM004407-0104
Z8 User Manual
273
Case Sensitivity
In the default mode, the assembler treats all symbols as case sensitive. Select the Ignore
Case check box of the Assembler tab in the Project Settings dialog box to invoke the
assembler and ignore the case of user-defined identifiers (see “Ignore Case” on page 97).
Assembler reserved words are not case sensitive.
Assembler Rules
Reserved Words
The following list contains reserved words the assembler uses. You cannot use these
words as symbol names or variable names. Also reserved words are not case sensitive:
ADC
C
C0
C1
C2
C3
DMA
EQ
F
FLAGS
GE
GT
I2C
IMR
IPR
LE
LT
MI
NC
NE
NOV
NZ
OV
P0
P01M
P0AD
P1
P1AD
P2
P2AD
P2M
P3
P3AD
P3M
P4AD
P5AD
P6AD
P7AD
PL
PRE0
PRE1
r0
r10
r11
r12
r13
r14
r15
r2
r3
r4
r5
r6
r7
r8
r9
RESET
RP
rr0
rr10
rr12
rr14
rr2
rr4
rr6
rr8
SIO
SPH
SPI
T0
T1
TIMER0
TIMER1
TIMER2
TIMER3
TMR
TRAP
UART0_RX
UGT
ULE
UART0_TX UART1_RX UART1_TX UGE
ULT
WDT
Z
Note: Additionally, do not use the instruction mnemonics or assembler directives as symbol or
variable names.
Assembler Numeric Representation
Numbers are represented internally as signed 32-bit integers. Floating-point numbers are
represented as double-precision 64-bit numbers and are automatically converted to singleprecision floating-point numbers if required. The assembler detects an expression operand
that is out of range for the intended field and generates appropriate error messages.
UM004407-0104
Z8 User Manual
274
Character Strings
Character strings consist of printable ASCII characters enclosed by double (") or single
(') quotes. A double quote used within a string delimited by double quotes and a single
quote used within a string delimited by single quotes must be preceded by a back slash (\).
A single quoted string consisting of a single character is treated as a character constant.
The assembler does not insert null character (0's) at the end of a text string automatically
unless a 0 is inserted, and a character string cannot be used as an operand. For example:
DB
DB
DB
DB
"STRING" ; a string
'STRING',0 ; C printable string
"STRING\"S" ; embedded quote
'a','b','c' ; character constants
EXPRESSIONS
In most cases, where a single integer or float value can be used as an operand, an expression can also be used. The assembler evaluates expressions in 32-bit signed arithmetic or
64-bit floating-point arithmetic. Logical expressions are bitwise operators.
The assembler detects overflow and division by zero errors. The following sections
describe the syntax of writing an expression.
Arithmetic Operators
<<
Left Shift
>>
Arithmetic Right Shift
**
Exponentiation
*
Multiplication
/
Division
%
Modulus
+
Addition
-
Subtraction
Note: You must put spaces before and after the modulus operator to separate it from the rest of
the expression.
UM004407-0104
Z8 User Manual
275
Relational Operators
For use only in conditional assembly expressions.
==
Equal
!=
Not Equal
>
Greater Than
<
Less Than
>=
Greater Than or Equal
<=
Less Than or Equal
Boolean Operators
&
Bitwise AND
|
Bitwise inclusive OR
^
Bitwise exclusive XOR
~
Complement
!
Boolean NOT
HIGH and LOW Operators
The HIGH and LOW operators can be used to extract specific bytes from an integer
expression. The LOW operator extracts the byte starting at bit 0 of the expression, while
the HIGH operator extracts the byte starting at bit 8 of the expression.
HIGH and LOW can also be used to extract portions of a floating-point value.
For example:
# LOW (X) ; 8 least significant bits of X
# HIGH (X) ; 8 most significant bits of X
Decimal Numbers
Decimal numbers are signed 32-bit integers consisting of the characters 0–9 inclusive
between -2147483648 and 2147483647. An underscore (_) can be used to separate digits for readability; the assembler ignores it. Positive numbers are indicated by the absence
of a sign. Negative numbers are indicated by a minus sign (-) preceding the number. For
example:
1234 ; decimal
-123_456 ; negative decimal
12E-45 ; decimal float
UM004407-0104
Z8 User Manual
276
-123.456 ; decimal float
123.45E6 ; decimal float
Hexadecimal Numbers
Hexadecimal numbers are signed 32-bit integers ending with the h or H suffix, and consisting of the characters 0–9 and A–F. A hexadecimal number can have 1 to 8 characters. Positive numbers are indicated by the absence of a sign. Negative numbers are indicated by a
minus sign (-) preceding the number. For example:
ABCDEFFFH ; hexadecimal
%ABCDEFFF ; hexadecimal
-0FFFFh ; negative hexadecimal
Binary Numbers
Binary numbers are signed 32-bit integers ending with the character b or B and consisting
of the characters 0 and 1. A binary number can have 32 characters. Positive numbers are
indicated by the absence of a sign. Negative numbers are indicated by a minus sign (-)
preceding the number. For example:
-0101b ; negative binary number
Octal Numbers
Octal numbers are signed 32-bit integers ending with the character o or O, and consisting
of the characters 0–7. An octal number can have 1 to 11 characters. Positive numbers are
indicated by the absence of a sign. Negative numbers are indicated by a minus sign (-)
preceding the number. For example:
1234o ; octal number
-1234o ; negative octal number
Floating-Point Numbers
Floating-point numbers are 64-bit IEEE standard double-precision values. Hexadecimal
and decimal floating-point numbers are supported. Only the +, -, *, and / operators are
allowed in expressions involving floating-point values. For example:
1234.567 E -2 ; decimal
$ FFFF.FFF ^ + 1 ; hexadecimal
Character Constants
A single printable ASCII character enclosed by single quotes (') can be used to represent
an ASCII value. This value can be used as an operand value. For example:
'A' ; ASCII code for "A"
'3' ; ASCII code for "3"
UM004407-0104
Z8 User Manual
277
Operator Precedence
Table 19 shows the operator precedence in descending order, with operators of equal precedence on the same line. Operators of equal precedence are evaluated left to right. Parentheses can be used to alter the order of evaluation.
Table 19. Operator Precedence
Level 1
()
Level 2
~
unary- !
high low
Level 3
**
*
/
%
Level 4
+
-
&
|
^
>>
Level 5
<
>
<=
>=
==
!=
<<
DIRECTIVES
Directives control the assembly process by providing the assembler with commands and
information. These directives are instructions to the assembler itself and are not part of the
microprocessor instruction set. The following sections provide details for each of the supported assembler directives. For a list of compatible directives, see Table 21, “Z8 Directive Compatibility,” on page 300.
ALIGN
Forces the object following to be aligned on a mau boundary that is a multiple of <value>.
Synonym
.align
Syntax
<align_directive> = > ALIGN <value>
Example
ALIGN 2
DW EVEN_LABEL
.COMMENT
The .COMMENT assembler directive classifies a stream of characters as a comment.
The .COMMENT assembler directive causes the assembler to treat an arbitrary stream
of characters as a comment. The delimiter can be any printable ASCII character. The
UM004407-0104
Z8 User Manual
278
assembler treats as comments all text between the initial and final delimiter, as well as all
text on the same line as the final delimiter.
You must not use a label on this directive.
Syntax
.COMMENT delimiter [ text ] delimiter
Example
.COMMENT $
This text is a comment, delimited by a dollar sign, and spanning multiple source lines. The
dollar sign ($) is a deliminator that marks the line as the end of the comment block.
CPU
Defines to the assembler which member of the Z8 family is targeted. From this directive,
the assembler can determine which instructions are legal as well as the locations of the
interrupt vectors within the CODE space.
If you use a predefined symbol in your code, the symbol is already defined. For example:
IFDEF EZ80190
Instead, use the following code:
_EZ80190 EQU 1
IFDEF _EZ80190
Note: The CPU directive is used to determine the physical location of the interrupt vectors.
Syntax
<cpu_definition> = > CPU = <cpu_name>
Example
CPU = X8601
Data Directives
Data directives allow you to reserve space for specified types of data.
Syntax
<data directive> = > <type> <value>
<type> => DB
=> DD
=> DF
=> DL
UM004407-0104
Z8 User Manual
279
=> DW
<value_list> => <value>
=> <value_list>,<value>
<value> => <expression>|<string_const>
BFRACT and UBFRACT Declaration Type
Syntax
BFRACT
signed fractional (8 bits)
UBFRACT
unsigned fractional (8 bits)
Examples
BFRACT [3]0.1, [2]0.2 ;
;
;
;
UBFRACT [50]0.1,[50]0.2
Reserve space for five 8 bit
signed fractional numbers.
Initialize first 3 with 0.1,
last 2 with a 0.2.
; Reserve space for 100 8 bit
; unsigned fractional numbers.
; Initialize first 50 with a
; 0.1, second 50 with a 0.2
BFRACT 0.5 ; Reserve space for one 8 bit
; signed, fractional number
; and initialize it to 0.5.
FRACT and UFRACT Declaration Type
Syntax
FRACT
signed fractional (8 bits)
UFRACT
unsigned fractional (8 bits)
Examples
FRACT [3]0.1, [2]0.2 ;
;
;
;
UFRACT [50]0.1,[50]0.2
Reserve space for five 16 bit
signed fractional numbers.
Initialize first 3 with 0.1,
last 2 with a 0.2.
; Reserve space for 100 16 bit
; unsigned fractional numbers.
; Initialize first 50 with a
; 0.1, second 50 with a 0.2
FRACT 0.5 ; Reserve space for one 16 bit
; signed, fractional number
; and initialize it to 0.5.
UM004407-0104
Z8 User Manual
280
BLKB Declaration Type
Syntax
BLKB
bytes data (8 bits) [, <init_value>]
Examples
BLKB 16 ; Allocate 16 uninitialized bytes.
BLKB 16, -1 ; Allocate 16 bytes and initialize them to -1.
BLKL Declaration Type
Syntax
BLKL
Examples
BLKL 16 ; Allocate 16 uninitialized longs.
BLKL 16, -1 ; Allocate 16 longs and initialize them to -1.
BLKP Declaration Type
Syntax
BLKP
Examples
BLKP 16 ; Allocate 16 uninitialized longs.
BLKP 16, -1 ; Allocate 16 longs and initialize them to -1.
BLKW Declaration Type
Syntax
BLKW
Examples
BLKW 16 ; Allocate 16 uninitialized words.
BLKW 16, -1 ; Allocate 16 words and initialize them to -1.
DB Declaration Type
Synonyms
.byte, .ascii, DEFB, FCB, STRING, .STRING, byte
UM004407-0104
Z8 User Manual
281
Syntax
DB
byte data (8 bits)
Examples
DB "Hello World" ; Reserve and initialize 11 bytes.
DB "Hello" ; Reserve 12 bytes. Initialize 6.
DB 1,2 ; Reserve 2 bytes. Initialize the
; first word with a 1 and the second with a 2.
DB %12 ; Reserve 1 byte. Initialize it with ; %12.
Note: There is no trailing null for the DB declaration type.
DD Declaration Type
Synonym
.double
Syntax
DD
double signed fractional (32 bits)
Examples
DD 0.1,0.2 ; Reserve space for 2 double word signed fractional
; numbers. Initialize the first with a 0.1 and
; the last with a 0.2.
DD 0.5 ; Reserve space for 1 double word signed fractional
; number and initialize it to 0.5.
DF Declaration Type
Synonym
.float
Syntax
DF
word signed fractional (16 bits)
Examples
DF 0.1,0.2 ; Reserve space for 2 word signed
; fractional numbers. Initialize
; first with a 0.1 and last with a 0.2.
DF .5 ; Reserve space for 1 word signed
; fractional number and initialize it to 0.5.
UM004407-0104
Z8 User Manual
282
DL Declaration Type
Synonyms
.long, long
Syntax
DL long (32 bits)
Examples
DL 1,2 ; Reserve 2 long words. Initialize the
; first with a 1 and last with a 2.
DL %12345678 ; Reserve space for 1 long word and
; initialize it to %12345678.
DW Declaration Type
Synonyms
.word, word, .int
Syntax
DW
word data (16 bits)
Examples
DW "Hello World" ; Reserve and initialize 11 words.
DW "Hello" ; Reserve 12 words, initialize 6.
DW 1,2 ; Reserve 2 words. Initialize the
; first word with a 1 and the second with a 2.
DW %1234 ; Reserve 1 word and initialize it with %1234.
Note: There is no trailing null for the DW declaration type. Each letter gets 16 bits with the upper
8 bits zero.
DEFINE
Defines a segment with its associated address space, alignment, and origin. You must
define a segment before you can use it, unless it is a predefined segment. If a clause is not
given, use the default for that definition. For more information on the SEGMENT directive,
see “SEGMENT” on page 287; for a list of predefined segments, see “Predefined Segments” on page 269
Synonym
.define
UM004407-0104
Z8 User Manual
283
Syntax
<segment_definition> =>
DEFINE<ident>[<space_clause>][align_clause>][<org_clause>]
Examples
DEFINE near_code ; Uses the defaults of the current
; space, byte alignment and
; relocatable.
DEFINE irq_table,ORG=%FFF8 ; Uses current space byte alignment and
; absolute starting address at
; memory location %FFF8.
ALIGN Clause
Allows you to select the alignment boundary for a segment. The linker places modules in
this segment on the defined boundary. The boundary is a multiple of the MAU defined for
the space identifier. The multiple must be a power of two (1, 2, 4, 8, and so on).
Syntax
<align_clause> => ,ALIGN = <int_const>
Example
DEFINE far_data,SPACE = FAR_RAM,ALIGN = 2
; Aligns on a half-word boundary, relocatable.
ORG Clause
Allows you to specify where the segment is to be located, making the segment an absolute
segment. The linker places the segment at the memory location specified by the ORG. The
default is no ORG, and thus the segment is relocatable.
Syntax
<align_clause> => ,ALIGN = <int_const>
Example
DEFINE near_code,ORG = %FFF8
; Uses NEAR_ROM, word alignment, and absolute starting
; address at memory location %FFF8.
SPACE Clause
A SPACE clause defines the address space in which the segment resides. The linker groups
together segments with the same space identification. See Table 17, “Z8 Address Spaces,”
on page 268 for available spaces.
UM004407-0104
Z8 User Manual
284
Syntax
<space_clause> => ,SPACE = <indent>
Example
DEFINE far_data,SPACE = FAR_RAM,ALIGN = 2
; Aligns on a half-word boundary, relocatable.
DS
Defines storage locations that do not need to be initialized.
Synonym
.block
Syntax
<define_storage> => DS <value>
Example
NAME DS 10 ; Reserve 10 bytes of storage.
END
Informs the assembler of the end of the source input file. If the operand field is present, it
defines the start address of the program. During the linking process, only one module can
have a start address; otherwise, an error results. The END directive is optional for those
modules that do not need a start address.
Note: Any text found after an END directive is ignored.
Synonym
.end
Syntax
<end_directive> => END[<expression>]
Example
END start ; Use the value of start as the program start address.
UM004407-0104
Z8 User Manual
285
EQU
Assigns symbolic names to numeric or string values. Any name used to define an equate
must not have been previously defined. Other equates and label symbols are allowed in the
expression, provided they are previously defined. Labels are not allowed in the expression.
Caution: You cannot export EQU using the XDEF directive or import using the XREF directive.
Synonyms
.equ, .EQU, EQUAL
Syntax
<label> EQU <expression>
Examples
pi EQU 3.141 ; set to the value of pi
area EQU pi*7*7 ; area of a circle
reg EQU rr4 ; symbolic name of a register
INCLUDE
Allows the insertion of source code from another file into the current source file during
assembly. The included file is assembled into the current source file immediately after the
directive. When the EOF (End of File) of the included file is reached, the assembly
resumes on the line after the INCLUDE directive.
The file to include is named in the string constant after the INCLUDE directive. The file
name can contain a path. If the file does not exist, an error results and the assembly is
aborted. A recursive INCLUDE also results in an error.
INCLUDE files are contained in the listing (.lst) file unless a NOLIST directive is active.
Synonyms
.include, .copy
Syntax
<include_directive> => INCLUDE[<string_const>]
Example
INCLUDE "calc.h" ; include calc header file
INCLUDE "\test\calc.h" ; contains a path name
INCLUDE calc.h ; ERROR, use string constant
UM004407-0104
Z8 User Manual
286
LIST
Instructs the assembler to send output to the listing file. This mode stays in effect until a
NOLIST directive is encountered. No operand field is allowed. This mode is the default
mode.
Synonyms
.list, .LIST
Syntax
<list_directive> => LIST
Example
LIST
NOLIST
NEWPAGE
Causes the assembler to start a new page in the output listing. This directive has no effect
if NOLIST is active. No operand is allowed.
Synonyms
.page, PAGE
Syntax
<newpage_directive> => NEWPAGE
Example
NEWPAGE
NOLIST
Turns off the generation of the listing file. This mode remains in effect until a LIST directive is encountered. No operand is allowed.
Synonym
.NOLIST
Syntax
<nolist_directive> => NOLIST
UM004407-0104
Z8 User Manual
287
Example
LIST
NOLIST
ORG
Resets the assembler's internal program counter to the integer constant following the ORG
and causes absolute code/data to be generated.
The ORG directive must be followed by an integer constant.
Synonyms
ORIGIN, .org
Syntax
<org_directive> => ORG <int_const>
Examples
ORG %1000 ; generate absolute code at %1000
ORG LOOP ; ERROR, use an integer constant
Note: If the ORG directive is used within a relocatable segment, that segment becomes an absolute
segment, with 0 as the base physical address of the segment. It is recommended that
segments requiring the use of an ORG be declared as absolute segments.
SEGMENT
Specifies entry into a previously defined segment.
The SEGMENT directive must be followed by the segment identifier. The default segment is
used until the assembler encounters a SEGMENT directive. The internal assembler program
counter is reset to the previous program counter of the segment when a SEGMENT directive
is encountered. See Table 18, “Predefined Segments,” on page 269 for the names of predefined segments.
Synonyms
.section, SECTION
Syntax
<segment_directive> => SEGMENT <ident>
Example
SEGMENT code ; predefined segment
DEFINE data ; user-defined
UM004407-0104
Z8 User Manual
288
TITLE
Causes a user-defined TITLE to be displayed in the listing file. The new title remains in
effect until the next TITLE directive. The operand must be a string constant.
Synonym
.title
Syntax
<title_directive> => TITLE <string_const>
Example
TITLE "My Title"
VECTOR
Initializes an interrupt or reset vector to a program address. <vector name> must be
IRQ0...IRQ5 or RESET and specifies which vector is being specified. If RESET is
used, the assembler inserts a JP instruction to <expression> at the proper reset address.
<expression> is the address, usually a label, of the program code to handle the interrupt or
reset.
Note: If no reset vector is defined within the program, the linker generates a warning messages.
The CPU directive is used to determine the physical location of the interrupt vectors.
Syntax
<vector_directive> => VECTOR <vector name> = <expression>
Example
VECTOR WDT = irq0_handler
VECTOR TRAP = irq1_handler
XDEF
Defines a list of labels in the current module as an external symbol that are to be made
publicly visible to other modules at link time. The operands must be labels that are defined
somewhere in the assembly file.
Synonyms
.global, GLOBAL, .GLOBAL, .public, .def, public
UM004407-0104
Z8 User Manual
289
Syntax
<xdef_directive> => XDEF <ident list>
Example
XDEF label
XDEF label1,label2,label3
XREF
Specifies that a list of labels in the operand field are defined in another module. The reference is resolved by the linker. The labels must not be defined in the current module.
Synonyms
.extern, EXTERN, EXTERNAL, .ref
Syntax
<xref_directive> => XREF <ident list>
Example
XREF label
XREF label1,label2,label3
CONDITIONAL ASSEMBLY
Conditional assembly is used to control the assembly of blocks of code. Entire blocks of
code can be enabled or disabled using conditional assembly directives.
The following conditional assembly directives are allowed:
•
•
•
•
IF
IFDEF
IFSAME
IFMA
Any symbol used in a conditional directive must be previously defined by an EQU or VAR
directive. Relational operators can be used in the expression. Relational expressions evaluate to 1 if true, and 0 if false.
If a condition is true, the code body is processed. Otherwise, the code body after an ELSE
is processed, if included.
The ELIF directive allows a case-like structure to be implemented.
Note: Conditional assembly can be nested.
UM004407-0104
Z8 User Manual
290
Conditional Assembly Directives
IF
Evaluates a Boolean expression. If the expression evaluates to 0, the result is false; otherwise, the result is true.
Synonyms
.if, .IF, IFN, IFNZ, COND, IFTRUE, IFNFALSE, .$IF, .$if
Syntax
IF [<cond_expression> <code_body>]
[ELIF <cond_expression> <code_body>]
[ELSE <code_body>]
ENDIF
Example
IF XYZ ; process code body if XYZ is not 0
.
.
.
<Code Body>
.
.
ENDIF
IF XYZ !=3 ; code body 1 if XYZ is not 3
.
.
.
<Code Body 1>
.
.
.
ELIF ABC ; XYZ=3 and ABC is not 0,
.
.
.
<Code Body 2>
.
.
.
ELSE ; otherwise code body 3
.
.
.
<Code Body 3>
UM004407-0104
Z8 User Manual
291
.
.
.
ENDIF
IFDEF
Checks for label definition. Only a single label can be used with this conditional. If the
label is defined, the result is true; otherwise, the result if false.
Syntax
IFDEF <label>
<code_body>
[ELSE
<code_body>]
ENDIF
Example
IFDEF XYZ ; process code body if XYZ is
.
.
.
<Code Body>
.
.
.
ENDIF
IFSAME
Checks to see if two string constants are the same. If the strings are the same, the result is
true; otherwise, the result is false. If the strings are not enclosed by quotes, the comma is
used as the separator.
Syntax
IFSAME <string_const> , <string_const>
<code_body>
[ELSE
<code_body>]
ENDIF
IFMA
Used only within a macro, this directive checks to determine if a macro argument has been
defined. If the argument is defined, the result is true. Otherwise, the result is false. If
UM004407-0104
Z8 User Manual
292
<arg_number> is 0, the result is TRUE if no arguments were provided; otherwise, the
result is FALSE.
Syntax
IFMA <arg_number>
<code_body>
[ELSE
<code_body>]
ENDIF
MACROS
Macros allow a sequence of assembly source lines to be represented by a single assembler
symbol. In addition, arguments can be supplied to the macro in order to specify or alter the
assembler source lines generated once the macro is expanded. The following sections
describe how to define and invoke macros.
MACRO Definition
A macro definition must precede the use of the macro. The macro name must be the same
for both the definition and the ENDMACRO line. The argument list contains the formal arguments that are substituted with actual arguments when the macro is expanded.
During the invocation of the macro, a token substitution is performed, replacing the formal
arguments with the actual arguments.
Syntax
<macroname>[:]MACRO[<arg>(,<arg>)...]
<macro_body>
ENDMAC[RO]<macroname>
Example
store: MACRO reg1,reg2,reg3
ADD reg1,reg2
MOV reg3,reg1
ENDMAC store
Macro Invocation
A macro is invoked by specifying the macro name, and following the name with the
desired arguments. Use commas to separate the arguments.
Syntax
<macroname>[<arg>[(,<arg>)]...]
UM004407-0104
Z8 User Manual
293
Example
store R1,R2,R3
This macro invocation causes registers R1 and R2 to be added and the result stored in register R3.
Local Macro Labels
Local macro labels allow labels to be used within multiple macro expansions without
duplication. When used within the body of a macro, symbols preceded by two dollar signs
($$) are considered local to the scope of the macro and therefore are guaranteed to be
unique. The two dollars signs are replaced by an underscore followed by a macro invocation number.
Syntax
$$ <label>
Example
LJMP: MACRO cc,label
JR cc,$$lab
JP label
$$lab:
ENDMAC
Optional Macro Arguments
A macro can be defined to handle omitted arguments using the IFMA (if macro argument)
conditional directive within the macro. The conditional directive can be used to detect if
an argument was supplied with the invocation.
Example
MISSING_ARG: MACRO ARG0,ARG1,ARG2
IFMA 1
LD ARG0,ARG1
ELSE
LD ARG0,ARG2
ENDIF
ENDMACRO MISSING_ARG
Invocation
MISSING_ARG R1, ,@R2 ; missing second arg
Result
MOV R1,@R2
UM004407-0104
Z8 User Manual
294
Note: IFMA refers to argument numbers that are zero based (that is, the first argument is
numbered zero).
Exiting a Macro
The MACEXIT directive is used to immediately exit a macro. No further processing is performed. However, the assembler checks for proper if-then conditional directives. A
MACEXIT directive is normally used to terminate a recursive macro.
The following example is a recursive macro that demonstrates the use of MAXEXIT in
order to terminate the macro.
Example
RECURS_MAC: MACRO ARG1,ARG2
IFMA 0
MACEXIT
ELSE
RECURS_MAC ARG2
DB ARG1
ENDIF
ENDMACRO RECURS_MAC
Delimiting Macro Arguments
Macro arguments can be delimited by using the current macro delimiter characters defined
using the MACDELIM directive. The delimiters can be used to include commas and spaces
that are not normally allowed as part of an argument. The default delimiters are brackets {
}, but braces [ ] and parentheses ( ) are also allowed.
Example
BRA: MACRO ARG1
JP ARG1
ENDMAC LJMP
Invocation
BRA {dummy,X}
Result
JP dummy,X
UM004407-0104
Z8 User Manual
295
LABELS
Labels are considered symbolic representations of memory locations and can be used to
reference that memory location within an expression. See “Source Language Structure” on
page 272 for the form of a legal label.
The following sections describe labels.
Local Labels
Any label beginning with a dollar sign ($) or ending with a question mark (?) is considered to be a local label. The scope of a local label ends when a SCOPE directive is encountered, thus allowing the label name to be reused. A local label cannot be imported or
exported.
Example
$LOOP:
LAB?:
$LOOP:
LAB?:
JP $LOOP
JP LAB?
SCOPE
JP $LOOP
JP LAB?
;
;
;
;
;
Infinite branch to $LOOP
Infinite branch to LAB?
New local label scope
Reuse $LOOP
Reuse LAB?
Importing and Exporting Labels
Labels can be imported from other modules using the EXTERN or XREF directive. A space
can be provided in the directive to indicate the label's location. Otherwise, the space of the
current segment is used as the location of the label.
Labels can be exported to other modules by use of the PUBLIC or XDEF directive.
Label Spaces
The assembler makes use of a label's space when checking the validity of instruction operands. Certain instruction operands require that a label be located in a specific space, since
that instruction can only operate on data located in that space. A label is assigned to a
space by one of the following methods:
•
•
•
The space of the segment in which the label is defined.
The space provided in the EXTERN or XREF directive.
If no space is provided with the EXTERN or XREF directive, the space of the segment
where the EXTERN directive was encountered is used as the location of the label.
Label Checks
The assembler performs location checks when a label is used as an operand, including forward referenced labels. Thus, when a label is not located in the proper space is used as an
operand, the assembler flags a warning.
UM004407-0104
Z8 User Manual
296
Example
SEGMENT data_default
EXTERN label1:ROM ; Label1 is located in ROM
EXTERN label2 ; Label2 is located in DATA space
LOAD label2 ; Valid use of page0 label
LOAD label1 ; Generates assembler warning, cannot load from ROM
ADDRESSING MODES
This section discusses the syntax of the addressing modes supported by the Z8 Macro
Assembler.
Table 20. Addressing Modes
Symbolic Name Syntax
Description
<cc>
See “Conditional Assembly” on page 289.
<r>
rn
Working register.
<R>
rn
Working register <const exp> or register.
<RR>
<const exp>
Register pair rrn or working register pair.
<Ir>
@rn
Indirect working register.
<IR>
@<const exp>
Indirect register @rn or indirect working register.
<Irr>
@rrn
Indirect working register pair.
<IRR>
@<const exp>
Indirect register pair or @rn indirect working register pair.
<X>
<const exp> (rn) Indexed.
<DA>
<const exp>
Direct address (0..65535).
<RA>
<const exp>
Relative address (-128..+ 127).
<IM>
# <const exp>
Immediate constant (0..255).
SOURCE LANGUAGE SYNTAX
The syntax description that follows is given to outline the general assembler syntax. It
does not define assembly language instructions.
<source_line>
UM004407-0104
=>
=>
=>
=>
=>
<if_statement>
[<Label_field>]<instruction_field><EOL>
[<Label_field>]<directive_field><EOL>
<Label_field><EOL>
<EOL>
Z8 User Manual
297
<if_statement>
=>
=>
=>
<if_section>
[<else_statement>]
ENDIF
<if_section>
=>
<if_conditional>
<code-body>
<if_conditional>
=>
IF<cond_expression>|
IFDEF<ident>|
IFSAME<string_const>,<string_const>|
IFMA<int_const>
<else_statement>
=>
ELSE <code_body>|
ELIF<cond_expression>
<code_body>
[<else_statement>]
<cond_expression>
=>
<expression>|
<expression><relop><expression>
<relop>
=>
== | < | > | <= | => | !=
<code_body>
=>
<source_line>@
<label_field>
=>
<ident>:
<instruction_field>
=>
<mnemonic>[<operand>]@
<directive_field>
=>
<directive>
<mnemonic>
=>
valid instruction mnemonic
<operand>
=>
=>
<addressing_mode>
<expression>
<addressing_mode>
=>
valid instruction addressing mode
UM004407-0104
Z8 User Manual
298
<directive>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
=>
ALIGN<int_const>
<array_definition>
CONDLIST(ON|OFF)
END[<expression>]
<ident>EQU<expression>
ERROR<string_const>
EXIT<string_const>
.FCALL<ident>
FILE<string_const>
.FRAME<ident>,<ident>,<space>
GLOBALS (ON|OFF)
INCLUDE<string_const>
LIST (ON|OFF)
<macro_def>
<macro_invoc>
MACDELIM<char_const>
MACLIST (ON|OFF)
NEWPAGE
NOLIST
ORG<int_const>
PL<int_const>
PW<int_const>
<public_definition>
<scalar_definition>
SCOPE
<segment_definition>
SEGMENT<ident>
SUBTITLE<string_const>
SYNTAX=<target_microprocessor>
TITLE<string_const>
<ident>VAR<expression>
WARNING<string_const>
<array_definition>
=>
=>
<type>'['<elements>']'
[<initvalue>(,<initvalue>)@]
<type>
=>
=>
=>
DB
DL
DW
<elements>
=>
[<int_const>]
<initvalue>
=>
['['<instances>']']<value>
<instances>
=>
<int_const>
<value>
=>
<expression>|<string_const>
UM004407-0104
Z8 User Manual
299
<expression>
=>
=>
=>
=>
=>
=>
=>
=>
=>
'('<expression>')'
<expression><binary_op><expression>
<unary_op><expression>
<int_const>
<float_const>
<label>
HIGH<expression>
LOW<expression>
OFFSET<expression>
<binary_op>
=>
=>
=>
=>
=>
=>
=>
=>
=>
+
*
/
>>
<<
&
|
^
<i>
=>
=>
=>
~
!
<int_const>
=>
=>
=>
=>
digit(digit|'_')@
hexdigit(hexdigit|'_')@H
bindigit(bindigit|'_')@B
<char_const>
<char_const>
=>
'any'
<float_const>
=>
<decfloat>
<decfloat>
=>
<float_frac>|<float_power>
<float_frac>
=>
<float_const>[<exp_part>]
<frac_const>
=>
digit|'_') . (digit|'_')@
<exp_part>
=>
E['+'|-]digit+
<float_power>
=>
digit(digit|'_')@<exp_part>
<label>
=>
<ident>
<string_const>
=>
"('\"'|any)@"
<ident>
=>
(letter|'_')(letter|'_'|digit|'.')@
<ident_list>
=>
<ident>(,<ident>)@
<macro_def>
=>
<ident>MACRO[<arg>(<arg>)]
<code_body>
ENDMAC[RO]<macname>
UM004407-0104
Z8 User Manual
300
<macro_invoc>
=>
<macname>[<arg>](,<arg>)]
<arg>
=>
macro argument
<public_definition>
=>
PUBLIC<ident list>
EXTERN<ident list>
<scalar_definition>
=>
<type>[<value>]
<segment_definition>
=>
DEFINE<ident>[<space_clause>]
[<align_clause>][<org_clause>]
<space_clause>
=>
,SPACE=<space>
<align_clause>
=>
,ALIGN=<int_const>
<org_clause>
=>
,ORG=<int_const>
<space>
=>
(RDATA|XDATA|ROM)
COMPATIBILITY ISSUES
Table 21 shows the equivalences between Z8 directives and those of other assemblers that
are also supported by the Z8 assembler. ZMASM directives that are compatible with Z8
directives are also listed. The Z8 assembler directives in the left column are the preferred
directives, but the assembler also accepts any of the directives in the right column.
Table 21. Z8 Directive Compatibility
Z8 Assembler
Compatible With
ALIGN
.align
ASCII
.ascii
ASCIZ
.asciz
ASECT
.ASECT
ASG
.ASG
ASSUME
.ASSUME
BES
.bes
BREAK
.$BREAK,.$break
BSS
.bss
CHIP
chip, .cpu
CONTINUE
.$CONTINUE, .$continue
DATA
.data
DB
.byte, .ascii, DEFB, FCB, STRING, .STRING, byte
UM004407-0104
Z8 User Manual
301
Table 21. Z8 Directive Compatibility (Continued)
Z8 Assembler
Compatible With
DD
.double
DEFINE
.define
DF
.float
DL
.long, long
DR
<none>
DS
.block
DW
.word, word, .int
DW24
.word24, .trio, .DW24
ELIF
.ELIF, .ELSEIF, ELSEIF, .$ELSEIF, .$elseif
ELSE
.ELSE, .$ELSE, .$else
END
.end
ENDIF
.endif, .ENDIF, ENDC, .$ENDIF, .$endif
ENDMAC
.endm, ENDMACRO, .ENDMACRO, .ENDMAC, ENDM, .ENDM, MACEND,
.MACEND
ENDSTRUCT
.ENDSTRUCT
ERROR
.emsg
EQU
.equ, .EQU, EQUAL
EVAL
.EVAL
FCALL
.FCALL
FILE
.file
FRAME
.FRAME
GREG
GREGISTER
IF
.if, .IF, IFN, IFNZ, COND, IFTRUE, IFNFALSE, .$IF, .$if
INCLUDE
.include, .copy
LIST
.list <on> or <off>, .LIST
MACCNTR
<none>
MACEXIT
<none>
MACLIST
<none>
MACNOTE
.mmsg
MACRO
.macro, .MACRO
UM004407-0104
Z8 User Manual
302
Z8 Assembler
Compatible With
MLIST
<none>
MNOLIST
<none>
NEWBLOCK
.NEWBLOCK
NEWPAGE
.page [<len>] [<width>], PAGE
NIF
IFZ, IFE, IFFALSE, IFNTRUE
NOLIST
.NOLIST
NOSAME
IFDIFF, IFNSAME
ORG
.org, ORIGIN
PAGELENGTH
PL
PAGEWIDTH
PW
PE
V
P0
NV
POPSEG
<none>
PRINT
<none>
PT
<none>
PUSHSEG
<none>
REPEAT
.$REPEAT, .$repeat
SAME
IFNDIFF, IFSAME
SBLOCK
.SBLOCK
SCOPE
<none>
SEGMENT
.section, SECTION
STRUCT
.STRUCT
TAG
.TAG
TEXT
.text
TITLE
.title
UNTIL
.$UNTIL, .until
VAR
.VAR, SET, .SET
VECTOR
<none>
WARNING
.wmsg, MESSAGE
UM004407-0104
Z8 User Manual
303
Z8 Assembler
Compatible With
WEND
.$WEND, .$wend
WHILE
.$WHILE, .$while
XDEF
.global, GLOBAL, .GLOBAL, .public, .def, public
XREF
EXTERN, EXTERNAL, .extern, .ref
ZIGNORE
<none>
ZSECT
.sect
ZUSECT
.USECT
TROUBLESHOOTING THE ASSEMBLER
There are several instructions that you must be careful about when you use them. For
example, you can run into problems with instructions that have implicit registers (such as
DJNZ, LDI, LDIR, LDD, LDDR, and CPI CPIR).
Arithmetic instructions on register pairs (like DEC BC) do not set the condition codes;
however, single-register instructions (like DEC B or DEC C) do set the condition codes.
Be careful with handling register pairs in ADL mode since the highest-order byte is not
directly accessible.
ERROR MESSAGES
This section covers error messages for the assembler.
ERROR (99) General purpose switch error.
There was an illegal or improperly formed command line option.
ERROR (400) Symbol already defined.
The symbol has been previously defined.
ERROR (401) Syntax error.
General-purpose error when the assembler recognizes only part of a source line. The
assembler might generate multiple syntax errors per source line.
ERROR (402) Symbol XREF'd and XDEF'd.
Label previously marked as externally defined or referenced. This error occurs when
an attempt is made to both XREF and XDEF a label.
ERROR (403) Symbol not a segment.
The segment has not been previously defined or is defined as some other symbol type.
UM004407-0104
Z8 User Manual
304
ERROR (404) Illegal EQU.
The name used to define an equate has been previously defined or equates and label
symbols in an equate expression have not been previously defined.
ERROR (405) Label not defined.
The label has not been defined, either by an XREF or a label definition.
ERROR (406) Illegal use of XREF's symbol.
XDEF defines a list of labels in the current module as an external symbol that are to be
made publicly visible to other modules at link time; XREF specifies that a list of
labels in the operand field are defined in another module.
ERROR (407) Illegal constant expression.
The constant expression is not valid in this particular context. This error normally
occurs when an expression requires a constant value that does not contain labels.
ERROR (408) Memory allocation error.
Not enough memory is available in the specified memory range.
ERROR (409) Illegal .elif directive.
There is no matching .if for the .elif directive.
ERROR (410) Illegal .else directive.
There is no matching .if for the .else directive.
ERROR (411) Illegal .endif directive.
There is no matching .if for the .endif directive.
ERROR (412) EOF encountered within an .if
End-of-file encountered within a conditional directive.
ERROR (413) Illegal floating point expression.
An illegal value was found in a floating-point expression. This error is normally
caused by the use of labels in the expression.
ERROR (414) Illegal floating point initializer in scalar directive.
You cannot use floating-point values in scalar storage directives.
ERROR (415) Illegal relocatable initialization in float directive.
You cannot use relocatable labels in a float storage directive.
ERROR (416) Unsupported/illegal directives.
General-purpose error when the assembler recognizes only part of a source line. The
assembler might generate multiple errors for the directive.
UM004407-0104
Z8 User Manual
305
ERROR (417) Unterminated quoted string.
You must terminate a string with a double quote.
ERROR (418) Illegal symbol name.
There are illegal characters in a symbol name.
ERROR (419) Unrecognized token.
The assembler has encountered illegal/unknown character(s).
ERROR (420) Constant expression overflow.
A constant expression exceeded the range of –2147483648 to 2147483648.
ERROR (421) Division by zero.
The divisor equals zero in an expression.
ERROR (422) Address space not defined.
The address space is not one of the defined spaces.
ERROR (423) File not found.
The file cannot be found in the specified path, or, if no path is specified, the file cannot
be located in the current directory.
ERROR (424) XREF or XDEF label in const exp.
You cannot use an XREF or XDEF label in an EQU directive.
ERROR (425) EOF found in macro definition
End of file encountered before ENDMAC(RO) reached.
ERROR (426) MACRO/ENDMACRO name mismatch.
The declared MACRO name does not match the ENDMAC(RO) name.
ERROR (427) Invalid MACRO arguments.
The argument is not valid in this particular instance.
ERROR (428) Nesting same segment.
You cannot nest a segment within a segment of the same name.
ERROR (429) Macro call depth too deep.
You cannot exceed a macro call depth of 25.
ERROR (430) Illegal ENDMACRO found.
No macro definition for the ENDMAC(RO) encountered.
ERROR (431) Recursive macro call.
Macro calls cannot be recursive.
UM004407-0104
Z8 User Manual
306
ERROR (432) Recursive include file.
Include directives cannot be recursive.
ERROR (433) ORG to bad address.
The ORG clause specifies an invalid address for the segment.
ERROR (434) Symbol name too long.
The maximum symbol length (33 characters) has been exceeded.
ERROR (435) Operand out-of-range error.
The assembler detects an expression operand that is out of range for the intended field
and generates appropriate error messages.
ERROR (436) Relative branch to XREF label.
Do not use the JP instruction with XREF.
ERROR (437) Invalid array index.
A negative number or zero has been used for an array instance index. You must use
positive numbers.
ERROR (438) Label in improper space.
Instruction requires label argument to be located in certain address space. The most
common error is to have a code label when a data label is needed or vice versa.
ERROR (439) Vector not recognized.
The vector name must be IRQ0, IRQ1, IRQ2, IRQ3, IRQ4, IRQ5, or RESET
ERROR (442) Missing delay slot instruction.
Add a delay slot instruction such as BRANCH or LD.
ERROR (444) Too many initializers.
Initializers for array data allocation exceeds array element size.
ERROR (445) Missing .$endif at EOF.
There is no matching .$endif for the .$if directive.
ERROR (446) Missing .$wend at EOF.
There is no .$wend directive.
ERROR (447) Missing .$repeat at EOF.
There is no matching .$repeat for the .$while directive.
ERROR (448) Segment stack overflow.
Do not allocate returned structures on the stack.
UM004407-0104
Z8 User Manual
307
ERROR (450) Floating point precision error.
The floating-point value cannot be represented to the precision given. The value is
rounded to fit within the allowed precision.
ERROR (451) Floating point over/under flow.
The floating-point value cannot be represented.
ERROR (452) General floating point error.
The assembler detects an expression operand that is out of range for the intended field
and generates appropriate error messages.
ERROR (453) Fractional number too big/small.
The fractional number cannot be represented.
ERROR (461) Unexpected end-of-file in comment.
End-of-file encountered in a multi-line comment
ERROR (462) Macro redefinition.
The macro has been redefined.
ERROR (464) Obsolete feature encountered.
An obsolete feature was encountered.
ERROR (470) Missing token error.
A token needs to be added.
ERROR (475) User error.
General-purpose error.
ERROR (476) User warning.
General-purpose warning.
ERROR (480) Relist map file error.
A map file will not be generated.
ERROR (481) Relist file not found error.
The map file cannot be found in the specified path, or, if no path is specified, the map
file cannot be located in the current directory.
ERROR (482) Relist symbol not found.
Any symbol used in a conditional directive must be previously defined by an EQU or
VAR directive.
ERROR (483) Relist aborted.
A map file will not be generated.
UM004407-0104
Z8 User Manual
308
ERROR (490) Stall or hazard conflict found.
A stall or hazard conflict was encountered.
UM004407-0104
Z8 User Manual
309
6
Using the Linker/Locator
The Z8 developer’s environment linker/locator creates a single executable file from a set
of object modules and object libraries. It acts as a linker by linking together object modules and resolving external references to public symbols. It also acts as a locator because it
allows you to specify where code and data is stored in the target processor at run time.
This chapter describes the following:
•
•
•
•
Linker commands (starting on page 310)
Linker expressions (starting on page 327)
Troubleshooting the linker (starting on page 334)
Linker/locator warning messages (starting on page 335)
The following six major types of objects are manipulated during the linking process:
•
Modules
Modules are created by assembling a file with the assembler or compiling a file with
the compiler.
•
Libraries
Object libraries are collections of object modules created by the Librarian. Segments,
address spaces, groups, and copy segments are defined in the following sections.
•
Segments
Segments are named logical partitions of data or code that form a continuous block of
memory. Segments with the same name residing in different modules are concatenated
together at link time. Segments are assigned to an address space and can be relocatable
or absolute. Relocatable segments can be randomly allocated by the linker while
absolute segments are assigned a physical address within its address space. See
“Segments” on page 268 for more information about using predefined segments,
defining new segments, and attaching code and data to segments.
UM004407-0104
6 Using the Linker/Locator
Z8 User Manual
310
The memory range for the default segments depend on the particular Z8 family
member. The segments are described on the Target tab in the Project Settings dialog
box (see page 106).
•
Address spaces
Address spaces correspond to either a physical or logical block of memory on the
target processor. For example, a Harvard architecture that physically divides memory
into program and data stores would have two physical blocks—each with its own set
of addresses. If there were read-only parts of each physical block, there might be
CODE and ROM to name the program store and DROM and DATA to name the data
store. Logical address spaces are often used to divide a large contiguous block of
memory in order to separate data and code on a RAM-based system. In this case, the
address spaces partition the physical memory into two logical address spaces. For
more information about address spaces, see “Address Spaces” on page 268.
•
Groups
Groups are collections of logical address spaces. They are typically used for
convenience of locating a set of address spaces.
•
Copy segments
Copy segments are segments of initialized data that are re-assigned to another address
space (the copy segment) by the linker. A startup routine typically moves data from
the copy segment into the original address space to initialize data before invoking a
program.
Note: By default, allocation for a given memory group, address space, or segment starts at the
lowest defined address for that memory group, address space, or segment. If you explicitly
define an assignment within that memory space, allocation for that space begins at that
defined point and then occupies subsequent memory locations. For more information, see
“BASE OF Versus LOWADDR OF” on page 329.
LINKER COMMANDS
The linker is automatically invoked when you click the Build button or Rebuild All button
on the Build toolbar to your project. The linker executes controls found in a predetermined
link control file. A link control file is generated automatically by the Z8 developer’s environment if you select the Create New button on the Project Settings dialog box (see
page 102). By selecting the Use Existing button, you can modify how the linker links/
loads your application by using a set of options and commands in a scripting file. This section describes the commands of a link control file:
•
•
•
UM004407-0104
“<outputfile>=<module list>” on page 311
“CHANGE” on page 312
“COLOR” on page 313
Z8 User Manual
311
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
“COPY” on page 313
“DEBUG” on page 314
“DEFINE” on page 315
“FORMAT” on page 315
“GROUP” on page 315
“HEADING” on page 316
“LOCATE” on page 316
“MAP” on page 316
“MAXHEXLEN” on page 322
“MAXLENGTH” on page 322
“NOCOLOR” on page 322
“NODEBUG” on page 323
“NOMAP” on page 323
“NOWARN” on page 323
“ORDER” on page 323
“RANGE” on page 324
“SEARCHPATH” on page 324
“SORT” on page 325
“SPLITTABLE” on page 325
“UNRESOLVED IS FATAL” on page 326
“WARN” on page 326
“WARNING IS FATAL” on page 326
“WARNOVERLAP” on page 327
Notes: Only the <outputfile>=<module list> and the FORMAT commands are required. All
commands and operators are not case sensitive.
<outputfile>=<module list>
This command defines the executable file, object modules, and libraries involved in the
linking process. The default extension is .lod as specified by the FORMAT option (see
page 315).
<module list> is a list of object module or library path names to be linked together to create the output file.
UM004407-0104
Z8 User Manual
312
Example
c:\ZDSII_Z8_4.4.0\sample=c:\ZDSII_Z8_4.4.0\rtl\start.obj,adjust.obj, \
c:\ZDSII_Z8_4.4.0\rtl\helpers.lib
Note: In the preceding example, the \ (backslash) at the end of the first line allows the <module
list> to extend over several lines.
CHANGE
The CHANGE command is used to rename a group, address space, or segment. The CHANGE
command can also be used to move an address space to another group or to move a segment to another address space.
Syntax
CHANGE <name> = <newname>
<name> can be a group, address space, or segment.
<newname> is the new name to be used in renaming a group, address space, or segment;
the name of the group where an address space is to be moved; or the name of the address
space where a segment is to be moved.
Examples
Note: See also the examples for the COPY command (page 313).
To change the name of a segment (for example, strseg) to another segment name (for
example, codeseg), use the following command:
CHANGE strseg=codeseg
To move a segment (for example, codeseg) to a different address space (for example,
RAM), use the following command:
CHANGE codeseg=RAM
To not allocate a segment (for example, dataseg), use the following command:
CHANGE dataseg=NULL
Note: The linker recognizes the special space NULL. NULL is not one of the spaces that an object
file or library contains in it. If a segment is copied to NULL as a command to the linker, the
segment is deleted from the linking process. This can be useful if you need to link only part
of an executable or not write out a particular part of the executable. The predefined space
NULL can also be used to prevent initialization of data while reserving the segment in the
original space.
UM004407-0104
Z8 User Manual
313
COLOR
The COLOR command causes the linker to calculate memory overlays for segments
through graph coloring. The default setting is -COLOR. -NOCOLOR suppresses graph
coloring.
You can use the COLOR command to organize your overlays by building a tree representing
the sequence of overlays (for example, segment A is replaced by overlays C and D) and
then using a compiler technique called graph coloring to determine how to group the segments.
Syntax
[-]COLOR
COPY
The COPY command is used to make a copy of a segment into a specified address space.
This is most often used to make a copy of initialized RAM in ROM so that it can be initialized at run time.
Syntax
COPY <segment> <name>[at<expression>]
<segment> can only be a segment.
<name> can only be an address space.
Examples
To make a copy of a code segment in ROM, use the following procedure:
1. In the assembly code, define a code segment (for example, codeseg) to be a segment
located in RAM. This is the run-time location of codeseg.
2. Use the following linker command:
COPY codeseg ROM
The linker places the actual contents associated with codeseg in ROM (the load time
location) and associates RAM (the run-time location) addressed with labels in
codeseg.
Note: You need to copy the codeseg contents from ROM to RAM at run time as part of the
startup routine. You can use the COPY BASE OF and COPY TOP OF linker expressions to
get the base address and top address of the contents in ROM. You can use the BASE OF
and TOP OF linker expressions to get the base address and top address of codeseg.
UM004407-0104
Z8 User Manual
314
To copy segments to RAM, use the following procedure:
1. In the assembly code, define the segments (for example, strseg, text, and
codeseg) to be segments located in RAM. This is the run-time location of the
segments.
2. Use the following linker commands:
CHANGE strseg=codeseg
CHANGE text=codeseg
COPY codeseg RAM
The linker renames strseg and text as codeseg and performs linking as described
in the previous example. You need to write only one loop to perform the copy from
ROM to RAM at run time, instead of three (one loop each for strseg, text, and
codeseg).
To allocate a string segment in ROM but not generate the initialization:
1. In the assembly code, define the string segment (for example, strsect) to be a
segment located in ROM.
2. Use the following linker command:
COPY strsect NULL
The linker associates all the labels in strsect with an address in ROM and does not
generate any loadable data for strsect. This is useful when ROM is already
programmed separately, and the address information is needed for linking and
debugging.
Notes: The linker recognizes the special space NULL. NULL is not one of the spaces that an object
file or library contains in it. If a segment is copied to NULL as a command to the linker, the
segment is deleted from the linking process. This can be useful if you need to link only
part of an executable or not write out a particular part of the executable. The predefined
space NULL can also be used to prevent initialization of data while reserving the segment
in the original space.
Refer to “Linker Expressions” on page 327 for the format to write an expression.
DEBUG
The DEBUG command causes the linker to generate debug information for the debugger.
This option is applicable only if the executable file is IEEE 695.
Syntax
-DEBUG
UM004407-0104
Z8 User Manual
315
DEFINE
The DEFINE command creates a user-defined public symbol at link time. This command is
used to resolve external references (XREF) used in assemble time.
Syntax
DEFINE <symbol name> = <expression>
<symbol name> is the name assigned to the public symbol.
<expression> is the value assigned to the public symbol.
Example
DEFINE copy_size = copy top of data_seg - copy base of data_seg
Note: Refer to “Linker Expressions” on page 327 for the format to write an expression.
FORMAT
The FORMAT command sets the executable file of the linker according to the following
table.
File Type
Option
File Extension
SREC
.srec
IEEE 695 format
OMF695
.lod
Intel 16-bit Hex
INTEL
.hex
INTEL32
.hex
Motorola S-records
Intel 32-bit
The default setting is IEEE 695.
Syntax
[-]FORMAT=<type>
Example
FORMAT = SREC
GROUP
The GROUP command provides a method of collecting multiple address spaces into a
single manageable entity.
Syntax
GROUP <groupname> = <name>[,<name>]
UM004407-0104
Z8 User Manual
316
<groupname> can only be a group.
<name> can only be an address space.
HEADING
The HEADING command enables or disables the form feed (\f) characters in the map file
output.
Syntax
-[NO]heading
LOCATE
The LOCATE command specifies the address where a group, address space, or segment is
to be located. If multiple locates are specified for the same space, the last specification
takes precedence. A warning is flagged on a LOCATE of an absolute segment.
Note: The LOCATE of a segment overrides the LOCATE of an address space. A LOCATE does not
override an absolute segment.
Syntax
LOCATE <name> AT <expression>
<expression> is the address to begin loading.
Example
LOCATE ROM AT $10000
MAP
The MAP command causes the linker to create a link map file. The link map file contains
the location of address spaces, segments, and symbols. The default is to create a link map
file. NOMAP suppresses the generation of a link map file.
In the link map file, the C prefix indicates Code, and the D prefix indicates Data.
Syntax
-MAP = [<mapfile>]
mapfile has the same name as the executable file with the .map extension unless an
optional <mapfile> is specified.
UM004407-0104
Z8 User Manual
317
Example
MAP = myfile.map
Link Map File
A sample map file is shown in this section. The map file is partitioned into labeled sections. Comments have been added to briefly describe each labeled section.
Zilog Linkage Editor.
LINK MAP:
Version 1.00
16-Feb-96
11:57:30
Page:
1
;summarizes the link, specifies the link
;date, the target microcontroller, and the names
;and types of the linked files.
Date:
Fri Feb 16 11:57:30 1996
Processor: Z89C00
Files:
[Object ] c00.o
COMMAND LIST:
;lists the command and options that are in effect.
;Options from the linker command line, as well as
;commands and options read from linker command files
;appear in this section of the link map.
-oc00 -mc00 c00.o
_Zilog Linkage Editor.
Version 1.00
SPACE ALLOCATION:
Space
-------------------------------ROM
RAM0
RAM1
CONTROL SECTIONS WITHIN SPACE:
ROM
-------------------------------$Vector
abscs
atext
code
text
UM004407-0104
16-Feb-96
11:57:30
Page:
2
;specifies the address space allocation.
Base
-------00000000
00000000
00000100
Top
Span
-------- -------00000FFF
1000h
00000011
12h
00000119
1Ah
;enumerates the control sections allocated
;within each address space.
Type
----------absolute
absolute
relocatable
relocatable
relocatable
Base
-------00000FFC
00000800
00000000
0000005C
00000740
Top
-------00000FFF
0000082C
0000005B
0000073F
000007A7
Span
---4h
2Dh
5Ch
6E4h
68h
Z8 User Manual
318
RAM0
-------------------------------absb0
b0ram
bank0_bss
Type
----------absolute
relocatable
relocatable
Base
-------00000082
00000000
00000001
Top
-------00000081
00000000
00000011
Span
---0h
1h
11h
RAM1
-------------------------------absb1
b1ram
Type
----------absolute
relocatable
Base
-------00000181
00000100
Top
-------00000180
00000119
Span
---0h
1Ah
Version 1.00
CONTROL SECTIONS WITHIN MODULES:
16-Feb-96
11:57:30
Page: 3
;enumerates the control sections from each
;input object module.
Module: c00.s (File: c00.o) Fri Feb 16 11:57:15 1996
Control
Control
Control
Control
Control
Control
Control
Control
Control
Control
Name
Base
Top
-------------------------------- -------- ------section: $Vector
00000FFC
section: abscs
00000800
section: atext
00000000
section: code
0000005C
section: text
00000740
section: absb0
00000082
section: b0ram
00000000
section: bank0_bss
00000001
section: absb1
00000181
section: b1ram
00000100
Version 1.00
16-Feb-96
EXTERNAL DEFINITIONS BY ADDRESS:
Symbol
-------------------------------.textlab
begin
codelab
UM004407-0104
Size
----00000FFF
0000082C
0000005B
0000073F
000007A7
00000082
00000000
00000011
00000181
00000119
11:57:30
Page:
4
45
92
1764
104
0
1
17
0
26
4
;lists the global symbols,
;sorted by address.
Address
-------00000001
00000069
0000006A
Module
----------c00.s
c00.s
c00.s
Control Section
--------------atext
code
code
Z8 User Manual
319
firloop
p0label
abslabel
addlabel
andlabel
calllabel
cplabel
declabel
inclabel
jplabel
ldlabel
mldlabel
mpyalabel
mpyslabel
neglabel
orlabel
poplabel
pushlabel
rllabel
rrlabel
slllabel
sralabel
sublabel
label1
label2
textlab
here
abslab
bs0lab1
bs0label
ab0lab0
bs1lab1
bs1lab0
bs1label
ab1lab0
0000006A
0000006F
00000070
00000083
000000E1
00000117
000001C4
000001FA
0000020D
00000220
000002D2
000004C4
000004ED
00000515
0000053D
00000551
0000057B
000005EE
00000687
0000069A
000006AF
000006C3
000006D6
0000072E
00000738
0000075C
0000075E
00001009
00000000
00000011
00000103
00000100
00000109
00000119
00000301
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
text
text
abscs
b0ram
bank0_bss
absb0
b1ram
b1ram
b1ram
absb1
38 External symbols.
Version 1.00
EXTERNAL DEFINITIONS BY NAME:
16-Feb-96
11:57:30
Page:
5
;lists the global symbols,
;sorted by symbol name.
Symbol
Address Module
Control Section
-------------------------------- ------- --------------------.textlab
00000001 c00.s
atext
UM004407-0104
Z8 User Manual
320
ab0lab0
ab1lab0
abslab
abslabel
addlabel
andlabel
begin
bs0lab1
bs0label
bs1lab0
bs1lab1
bs1label
calllabel
codelab
cplabel
declabel
firloop
here
inclabel
jplabel
label1
label2
ldlabel
mldlabel
mpyalabel
mpyslabel
neglabel
orlabel
p0label
poplabel
pushlabel
rllabel
rrlabel
slllabel
sralabel
sublabel
textlab
00000103
00000301
00001009
00000070
00000083
000000E1
00000069
00000000
00000011
00000109
00000100
00000119
00000117
0000006A
000001C4
000001FA
0000006A
0000075E
0000020D
00000220
0000072E
00000738
000002D2
000004C4
000004ED
00000515
0000053D
00000551
0000006F
0000057B
000005EE
00000687
0000069A
000006AF
000006C3
000006D6
0000075C
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
absb0
absb1
abscs
code
code
code
code
b0ram
bank0_bss
b1ram
b1ram
b1ram
code
code
code
code
code
text
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
code
text
38 External symbols.
SYMBOL CROSS REFERENCE:
Symbol
UM004407-0104
Version 1.00
16-Feb-96
11:57:30
Page:
6
;lists a cross reference concordance of
;global symbols.
Module
Use
Z8 User Manual
321
-------------------------------.textlab
ab0lab0
ab1lab0
abslab
abslabel
addlabel
andlabel
begin
bs0lab1
bs0label
bs1lab0
bs1lab1
bs1label
calllabel
codelab
cplabel
declabel
firloop
here
inclabel
jplabel
label1
label2
ldlabel
mldlabel
mpyalabel
mpyslabel
neglabel
orlabel
p0label
poplabel
pushlabel
rllabel
rrlabel
slllabel
sralabel
sublabel
textlab
ENTRY POINT:
----------c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
c00.s
---------Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
Definition
;specifies the program entry point.
0069 Set from module 'c00.s'.
END OF LINK MAP:
;summarizes the status of the link. The
;number of error and warning messages are
;recorded in this section.
0 Warnings
UM004407-0104
Z8 User Manual
322
0 Errors
MAXHEXLEN
The MAXHEXLEN command causes the linker to fix the maximum data record size for the
Intel hex output. The default is 64 bytes.
Syntax
[-]MAXHEXLEN < IS | = >
< 16 | 32 | 64 | 128 | 255 >
Examples
-maxhexlen=16
or
MAXHEXLEN IS 16
MAXLENGTH
The MAXLENGTH command causes a warning message to be issued if a group, address
space, or segment is longer than the specified size. The RANGE command sets address
boundaries. The MAXLENGTH command allows further control of these boundaries.
Syntax
MAXLENGTH <name> <expression>
<expression> is the maximum size.
Example
MAXLENGTH CODE $FF
NOCOLOR
The NOCOLOR command suppresses graph coloring for memory overlays. The default
setting is COLOR.
Syntax
[-]NOCOLOR
UM004407-0104
Z8 User Manual
323
NODEBUG
The NODEBUG command suppresses the linker from generating debug information. This
option is applicable only if the executable file is IEEE 695.
Syntax
[-]NODEBUG
NOMAP
The NOMAP command suppresses generation of a link map file. The default is to generate a
link map file.
Syntax
[-]NOMAP
NOWARN
The NOWARN command suppresses warning messages. The default is to generate warning
messages.
Syntax
[-]NOWARN
ORDER
The ORDER command establishes a linking sequence and sets up a dynamic RANGE for
contiguously mapped address spaces. The base of the RANGE of each consecutive address
space is set to the top of its predecessor.
Syntax
ORDER <name>[,<name-list>]
<name> can be a group, address space, or segment. <name-list> is a comma-separated list
of other groups, address spaces, or segments. However, a RANGE is established only for an
address space.
Example
ORDER DATA,TEXT
In this example, all address spaces associated with DATA are located before (that is, at
lower addresses than) address spaces associated with TEXT.
UM004407-0104
Z8 User Manual
324
RANGE
The RANGE command sets the lower and upper bounds of a group, address space, or segment. If an address falls outside of the specified RANGE, the system displays a message.
Note: You must use white space to separate the colon from the RANGE command operands.
Syntax
RANGE <name><expression> : <expression>[,<expression> : <expression>...]
<name> can be a group, address space, or segment. The first <expression> marks the
lower boundary for a specified address RANGE. The second <expression> marks the upper
boundary for a specified address RANGE.
Example
RANGE CODE $100 : $1FF,$300 : $3FF
If a RANGE is specified for a segment, this range must be within any RANGE specified by
that segment’s address space.
SEARCHPATH
The SEARCHPATH command establishes an additional search path to be specified in locating files. The search order is as follows.
1. Current directory
2. Environment path
3. Search path
Syntax
SEARCHPATH ="<path>"
Example
SEARCHPATH="C:\ZDSII_Z8_4.4.0\rtl"
Notes: The environment path is set by the DOS command: SET Z8=<path>.
This command is placed in the AUTOEXEC.BAT file when you install Z8
developer’s environment.
UM004407-0104
Z8 User Manual
325
SEQUENCE
The SEQUENCE command forces the linker to allocate a group, address space, or segment
in the order specified.
Syntax
SEQUENCE <name>(,<name>)@
<name> is either a group, address space, or segment.
Example
SEQUENCE code,rdata
Note: If the sequenced segments do not all receive space allocation in the first pass through the
available address ranges, then the sequence of segments is not maintained.
SORT
The SORT command sorts the external symbol listing in the map file by name or address
order. The default is to sort in ascending order by name.
Syntax
[-]SORT
<ADDRESS | NAME> [IS | =] <ASCENDING | UP | DESCENDING | DOWN>
NAME indicates sorting by symbol name.
ADDRESS indicates sorting by symbol address.
Examples
The following examples show how to sort the symbol listing by the address in ascending
order:
SORT ADDRESS ASCENDING
or
-SORT ADDRESS = UP
SPLITTABLE
The SPLITTABLE command allows (but does not force) the linker to split a segment into
noncontiguous pieces to fit into available memory slots. Splitting segments can be helpful
in reducing the overall memory requirements of the project. However, problems can arise
if a noncontiguous segment is copied from one space to another using the COPY command.
The linker issues a warning if it is asked to COPY any noncontiguous segment.
If SPLITTABLE is not specified for a given segment, the linker allocates the entire segment contiguously.
UM004407-0104
Z8 User Manual
326
Syntax
SPLITTABLE segment_list
Example
SPLITTABLE DATA, TEXT
UNRESOLVED IS FATAL
The UNRESOLVED IS FATAL command causes the linker to treat “undefined external
symbol” warnings as fatal errors. The linker quits generating output files immediately if
the linker cannot resolve any undefined symbol. By default, the linker proceeds with generating output files if there are any undefined symbols.
Syntax
[-] < UNRESOLVED > < IS | = > <FATAL>
Examples
-unresolved=fatal
or
UNRESOLVED IS FATAL
WARN
The WARN command specifies that warning messages are to be generated. An optional
warning file can be specified to redirect messages. The default setting is to generate warning messages on the screen and in the map file.
Syntax
[-]WARN = [<warn filename>]
Example
-WARN=warnfile.txt
WARNING IS FATAL
The WARNING IS FATAL command causes the linker to treat all warning messages as
fatal errors. The linker does not generate output file(s) if there are any warnings while
linking. By default, the linker proceeds with generating output files even if there are warnings.
Syntax
[-]< WARNING | WARN> < IS | = > <FATAL>
UM004407-0104
Z8 User Manual
327
Examples
-warn=fatal
or
WARNING IS FATAL
WARNOVERLAP
The WARNOVERLAP command enables or disables the warnings when overlap occurs while
binding segments. The default is to display the warnings whenever a segment gets overlapped.
Syntax
-[NO]warnoverlap
LINKER EXPRESSIONS
This section describes the operators and their operands that form legal linker expressions:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
UM004407-0104
“+ (Add)” on page 328
“& (And)” on page 328
“BASE OF” on page 328
“COPY BASE” on page 329
“COPY TOP” on page 330
“/ (Divide)” on page 330
“FREEMEM” on page 330
“HIGHADDR” on page 330
“LENGTH” on page 330
“LOWADDR” on page 331
“* (Multiply)” on page 332
“Decimal Numeric Values” on page 332
“Hexadecimal Numeric Values” on page 332
“| (Or)” on page 332
“<< (Shift Left)” on page 332
“>> (Shift Right)” on page 333
“- (Subtract)” on page 333
“TOP OF” on page 333
Z8 User Manual
328
•
•
“^ (Bitwise Exclusive Or)” on page 333
“~ (Not)” on page 333
The following note applies to many of the <expression> commands discussed in this section.
Note: To use BASE, TOP, COPY BASE, COPY TOP, LOWADDR, HIGHADDR, LENGTH, and
FREEMEM <expression> commands, you must have completed the calculations on the
expression. This is done using the SEQUENCE and ORDER commands. Do not use an
expression of the segment or space itself to locate the object in question.
Examples
/* Correct example using segments */
SEQUENCE seg2, seg1
/* Calculate seg2 before seg1 */
LOCATE seg1 AT TOP OF seg2 + 1
/* Do not do this: cannot use expression of seg1 to locate seg1 */
LOCATE seg1 AT (TOP OF seg2 - LENGTH OF seg1)
+ (Add)
The + (Add) operator is used to perform addition of two expressions.
Syntax
<expression> + <expression>
& (And)
The & (And) operator is used to perform a bitwise & of two expressions.
Syntax
<expression> & <expression>
BASE OF
The BASE OF operator provides the lowest used address of a group, address space, or segment, excluding any segment copies when <name> is a segment. The value of BASE OF
is treated as an expression value.
Syntax
BASE OF <name>
UM004407-0104
Z8 User Manual
329
BASE OF Versus LOWADDR OF
By default, allocation for a given memory group, address space, or segment starts at the
defined point and then occupies subsequent memory locations; the explicit allocation
becomes the default BASE OF value. BASE OF <name> gives the lowest allocated
address in the space; LOWADDR OF <name> gives the lowest physical address in the
space.
For example:
RANGE
RANGE
RANGE
RANGE
RANGE
RANGE
EXTIO $0 : $FFFF
INTIO $0 : $FF
ROM $0 : $1FFFF
RAM $5000 : $1FFFF
s_checksum $0 : $FFFF
s_nvrblock $5000 : $1FFFF
/* RAM
LOCATE
LOCATE
LOCATE
DEFINE
DEFINE
allocation */
s_uninit_data at $5000
BSS at (TOP OF s_uninit_data)+1
s_nvrblock at $FE00
__low_data = BASE OF s_uninit_data
__copy_code_to_ram = 0
Using
LOCATE s_uninit_data at $5000
or
LOCATE s_uninit_data at LOWADDR OF RAM
gives the same address (the lowest possible address) when RANGE RAM $5000:$1FFFF.
If
is changed to
LOCATE s_uninit_data at BASE OF RAM
the lowest used address is $FE00 (because LOCATE s_nvrblock at $FE00 and
s_nvrblock is in RAM).
COPY BASE
The COPY BASE operator provides the lowest used address of a copy segment, group, or
address space. The value of COPY BASE is treated as an expression value.
Syntax
COPY BASE OF <name>
UM004407-0104
Z8 User Manual
330
<name> can be either a group, address space, or segment.
COPY TOP
The COPY TOP operator provides the highest used address of a copy segment, group, or
address space. The value of COPY TOP is treated as an expression value.
Syntax
COPY TOP OF <name>
/ (Divide)
The / (Divide) operator is used to perform division.
Syntax
<expression> / <expression>
FREEMEM
The FREEMEM operator provides the lowest address of unallocated memory of a group,
address space, or segment. The value of FREEMEM is treated as an expression value.
Syntax
FREEMEM OF <name>
HIGHADDR
The HIGHADDR operator provides the highest possible address of a group, address
space, or segment. The value of HIGHADDR is treated as an expression value.
Syntax
HIGHADDR OF <name>
LENGTH
The LENGTH operator provides the length of a group, address space, or segment. The
value of LENGTH is treated as an expression value.
Syntax
LENGTH OF <name>
UM004407-0104
Z8 User Manual
331
LOWADDR
The LOWADDR operator provides the lowest possible address of a group, address space,
or segment. The value of LOWADDR is treated as an expression value.
Syntax
LOWADDR OF <name>
BASE OF Versus LOWADDR OF
By default, allocation for a given memory group, address space, or segment starts at the
defined point and then occupies subsequent memory locations; the explicit allocation
becomes the default BASE OF value. BASE OF <name> gives the lowest allocated
address in the space; LOWADDR OF <name> gives the lowest physical address in the
space.
For example:
RANGE
RANGE
RANGE
RANGE
RANGE
RANGE
/* RAM
LOCATE
LOCATE
LOCATE
DEFINE
DEFINE
EXTIO $0 : $FFFF
INTIO $0 : $FF
ROM $0 : $1FFFF
RAM $5000 : $1FFFF
s_checksum $0 : $FFFF
s_nvrblock $5000 : $1FFFF
allocation */
s_uninit_data at $5000
BSS at (TOP OF s_uninit_data)+1
s_nvrblock at $FE00
__low_data = BASE OF s_uninit_data
__copy_code_to_ram = 0
Using
or
LOCATE s_uninit_data at LOWADDR OF RAM
gives the same address (the lowest possible address) when RANGE RAM $5000:$1FFFF.
If
is changed to
UM004407-0104
Z8 User Manual
332
LOCATE s_uninit_data at BASE OF RAM
the lowest used address is $FE00 (because LOCATE s_nvrblock at $FE00 and
s_nvrblock is in RAM).
* (Multiply)
The * (Multiply) operator is used to multiply two expressions.
Syntax
<expression> * <expression>
Decimal Numeric Values
Decimal numeric constant values can be used as an expression or part of an expression.
Digits are collections of numeric digits from 0 to 9.
Syntax
<digits>
Hexadecimal Numeric Values
Hexadecimal numeric constant values can be used as an expression or part of an expression. Hex digits are collections of numeric digits from 0 to 9 or A to F.
Syntax
<hexdigits>
| (Or)
The | (Or) operator is used to perform a bitwise inclusive | (Or) of two expressions.
Syntax
<expression> | <expression>
<< (Shift Left)
The << (Shift Left) operator is used to perform a left shift. The first expression to the left
of << is the value to be shifted. The second expression is the number of bits to the left the
value is to be shifted.
Syntax
<expression> << <expression>
UM004407-0104
Z8 User Manual
333
>> (Shift Right)
The >> (Shift Right) operator is used to perform a right shift. The first expression to the
left of >> is the value to be shifted. The second expression is the number of bits to the right
the value is to be shifted.
Syntax
<expression> >> <expression>
- (Subtract)
The - (Subtract) operator is used to subtract one expression from another.
Syntax
<expression> - <expression>
TOP OF
The TOP OF operator provides the highest allocated address of a group, address space, or
segment, excluding any segment copies when <name> is a segment. The value of TOP OF
is treated as an expression value.
Syntax
TOP OF <name>
If you declare a segment to begin at TOP OF another segment, the two segments share one
memory location. TOP OF give the address of the last used memory location in a segment,
not the address of the next available memory location. For example,
LOCATE segment2 at TOP OF segment1
starts segment2 at the address of the last used location of segment1. To avoid both segments sharing one memory location, use the following syntax:
LOCATE segment2 at (TOP OF segment1) + 1
^ (Bitwise Exclusive Or)
The ^ operator is used to perform a bitwise exclusive OR on two expressions.
Syntax
<expression> ^ <expression>
~ (Not)
The ~ (Not) operator is used to perform a one’s complement of an expression.
UM004407-0104
Z8 User Manual
334
Syntax
~ <expression>
TROUBLESHOOTING THE LINKER
Review these questions to learn more about common situations you might encounter when
using the assembler:
•
•
•
•
•
•
“How do I speed up the linker?” on page 334
“How do I generate debug information without generating code?” on page 334
“How much memory is my program using?” on page 334
“How do I create a hex file?” on page 335
“How do I determine the size of my actual hex code?” on page 335
“How do I get my program to start from reset with the interrupts disabled?” on
page 335
How do I speed up the linker?
Use the following tips to lower linker execution times:
•
If you do not need a link map file, deselect the Generate Map File check box in the
Project Settings dialog box (Linker tab, General category). See “Generate Map File”
on page 100.
•
Make sure that all DOS windows are minimized.
How do I generate debug information without generating code?
Use the COPY or CHANGE command in the linker to copy or change a segment to the
predefined NULL space. If you copy the segment to the NULL space, the region is still
allocated but no data is written for it. If you change the segment to the NULL space, the
region is not allocated at all.
The following examples are of commands in the link control file:
COPY
CHANGE
myseg
NULL
myseg = NULL
How much memory is my program using?
Unless the Generate Map File check box is unchecked in the Project Settings dialog box
(Linker tab, General category), the linker creates a link map file each time it is run. The
link map file name is the same as your executable file with the .map extension and resides
in the same directory as your project file. The link map has a wealth of information about
the memory requirements of your program. Views of memory usage from the space,
UM004407-0104
Z8 User Manual
335
segment, and module perspective are given as are the names and locations of all public
symbols. See “Generate Map File” on page 100 and “MAP” on page 316.
How do I create a hex file?
Select Intel Hex Records from the Executable Format drop-down list box in the Project
Settings dialog box (Linker tab, “Output Category” on page 112).
How do I determine the size of my actual hex code?
Refer to the map file. Unless the Generate Map File check box is unchecked in the Project
Settings dialog box (Linker tab, “General Category” on page 107), the linker creates a link
map file each time it is run. The link map file name is the same as your executable file
with the .map extension and resides in the same directory as your project file.
How do I get my program to start from reset with the interrupts disabled?
The startup module source code is supplied with ZDS II and is found in the
ZILOGINSTALL\src\rtl\common directory and is titled startupl.asm for the large
model and startups.asm for the small model. Edit this source code to turn off the interrupts, add the modified startup module source file to your project, and select the Included
in Project button in the Project Settings dialog box (Linker tab, “Input Category” on
page 108).
WARNING MESSAGES
This section covers warning messages for the linker/locator.
WARNING (0) <address range information>.
The specified address range is invalid.
WARNING (1) Library backup file not defined.
The library backup file was not specified. Check for correct spelling and case
sensitivity.
WARNING (2) Library block size error <name>.
The library block <name> is longer than the specified size.
WARNING (3) File <name> is not the current file.
The file specified by <name> is not in the current search path.
WARNING (4) Execution status of <name> module is not 0 - Success.
The execution status of the module specified by <name> exhibits a warning or error
status possibly set by the assembler or librarian.
UM004407-0104
Z8 User Manual
336
WARNING (5) User interrupt.
A function declared as an interrupt function cannot have function arguments.
WARNING (6) Library file <name> is a module and not a library.
The file <name> was defined as a module instead of a library.
WARNING (7) Library module <name> was not found.
The library module <name> was not in the specified search path.
WARNING (8) Module <name> size is < 0.
The module <name> size must be a positive number.
WARNING (9) Help file <name> not found.
The help file was not in the specified search path.
WARNING (10) Module <name> not found.
The module <name> was not in the specified search path.
WARNING (11) Variable <name> is already defined.
Define each variable once.
WARNING (12) W variable <name>.
The W variable <name> has not been defined.
WARNING (13) Variable <name> is not defined.
The variable <name> has not been defined.
WARNING (14) Flag error
An error was encountered.
UM004407-0104
Z8 User Manual
337
A
ANSI C Language
This appendix describes the ANSI C language supported by the Z8 developer’s environment ANSI C-Compiler. The following topics are covered:
•
•
•
•
•
•
•
•
•
•
UM004407-0104
“Conventions” on page 338
“Character Sets” on page 338
“Tokens” on page 339
“Comments” on page 353
“Conversions” on page 353
“Sequence Points” on page 357
“Expressions” on page 357
“Declarations” on page 377
“Statements” on page 393
“External Definitions” on page 400
A ANSI C Language
Z8 User Manual
338
CONVENTIONS
A colon (:) following a nonterminal introduces its definition.
Alternative definitions are listed on separate lines, except when prefaced by the words
“one of.”
An optional symbol is indicated by the subscript opt so that { expression opt } indicates
an optional expression enclosed in braces.
CHARACTER SETS
The compiler supports two character sets: the ASCII character set and trigraphs used to
generate ASCII characters that some terminals do not support.
In a character constant or string literal, characters in the execution set are represented by
corresponding characters in the source character set or by escape sequences consisting of
the backslash (\) followed by one or more characters. A representation with all bits set to
0, called the null character, exists in the execution character set, and is used to terminate
string literals.
The characters in Table 22 are in the source and execution character sets.
Table 22. Character Sets
Description
Characters
The 52 uppercase and lowercase letters of the English a b c d e
alphabet.
o p q r s
A B C D
O P Q R
f g h i j k l m n
t u v w x y z
E F G H I J K L M N
S T U V W X Y Z
The 10 decimal digits.
0 1 2 3 4 5 6 7 8 9
29 graphic characters.
! ‘‘ # % & ' ( ) * + , - . / :
; <<= >> ? [ \ ] ^ _ { | } ~
The space character, and control characters
representing horizontal tab, vertical tab, and form feed.
In source files, a standard character sequence indicates the end of each line of text. This
standard treats such an end-of-line indicator as if it were a single new-line character. In the
execution character set, a control character represents the new line.
If the compiler encounters any other characters in a source file (except in a preprocessing
token, a character constant, a string literal, or a comment), the behavior is undefined.
All occurrences in a source file of the following sequences of three characters (called trigraph sequences) listed in Table 23 are replaced with the corresponding single character.
UM004407-0104
A ANSI C Language
Z8 User Manual
339
Table 23. Trigraph Sequences
Trigraph Sequence
Character
??=
#
??(
[
??/
\
??)
]
??’
^
??<<
{
??!
|
??>>
}
??-
~
No other trigraph sequences exist. The compiler does not change ? characters that do not
begin one of the listed trigraphs. For example:
printf("What???/n");
becomes
printf("What?\n");
(after replacement of the trigraph sequence ??/)
TOKENS
A token is the minimal lexical element of the language and can consist of any keyword,
identifier, or constant separated by white space from any otherwise adjacent keyword,
identifier, or constant. Tokens fall into the following categories:
•
•
•
•
•
•
UM004407-0104
keywords (described on page 340)
identifiers (described on page 341)
constants (described on page 346)
string literals (described on page 351)
operators (described on page 352)
punctuators (described on page 352)
A ANSI C Language
Z8 User Manual
340
Syntax
token:
keyword
identifier
constant
string-literal
operator
punctuator
The compiler ignores white space, such as space characters, horizontal tabs, new-line
characters, vertical tabs, form feeds, and comments (described on page 353), except as it
separates tokens.
When parsing an input string, the compiler considers the next token to be the longest
sequence of characters that can constitute a token.
Note: An identifier or a constant constitutes a single token. White space must not appear between
the characters that constitute the tokens in the syntax descriptions in this section.
Keywords
The following tokens, constructed of lower-case letters, are reserved for use as keywords
and must not be used otherwise.
keyword: one of
auto (see page 378)
bit*
break (see page 399)
case (see page 396)
char (see page 379)
const (see page 379)
continue (see page 399)
default (see page 396)
do (see page 397)
double (see page 345)
else (see page 396)
enum (see page 383)
extern (see page 378)
far*
float (see page 345)
for (see page 397)
fract* (see page 379)
goto (see page 398)
if (see page 396)
int (see page 379)
interrupt*
long (see page 379)
near*
reentrant*
register (see page 378)
return (see page 399)
short (see page 379)
signed (see page 344)
sizeof (see page 365)
static (see page 378)
struct (see page 380)
switch (see page 396)
typedef (see page 390)
union (see page 380)
unsigned (see page 379)
void (see page 379)
volatile (see page 379)
while (see page 397)
* Language extension for embedded application.
UM004407-0104
A ANSI C Language
Z8 User Manual
341
Identifiers
An identifier is a sequence of nondigit characters (including the underscore _ and the lowercase and uppercase letters) and digits. The first character must not be a digit.
Syntax
identifier:
nondigit
identifier nondigit
identifier digit
nondigit: one of
abcdefghijklm
nopqrstuvwxyz
ABCDEFGHIJKLM
NOPQRSTUVWXYZ
digit: one of
0123456789
Constraints
An identifier must not consist of the same sequence of characters as a keyword. No specific limit exists on the maximum length of an identifier.
Semantics
An identifier denotes one of the following:
•
•
•
•
•
•
function
object
tag or a member of a structure, union, or enumeration
typedef name
label name
macro name
Macro names are not considered further here, because the compiler replaces macro
names with their corresponding token sequences before the semantic phase of program
translation.
UM004407-0104
A ANSI C Language
Z8 User Manual
342
Scopes of Identifiers
An identifier is visible (that is, can be used) only within a region of program text called its
scope. Four kinds of scopes exist.
•
•
•
•
function
file
block
function prototype
A function prototype is a declaration of a function that declares the types of its parameters.
A label name is the only kind of identifier that has function scope. It can be used (in a
goto statement) anywhere in the function in which it appears and is declared implicitly by
its syntactic appearance (followed by a colon and a statement). Label names must be
unique within a function.
The compiler determines the scope of all other identifiers by the placement of their declarations.
•
If the declaration appears outside any block, the identifier has file scope, which
extends from the completion of its declarator to the end of the source file, including all
source files included by preprocessing directives.
•
If the declaration appears within a block or in the list of parameter identifiers in a
function definition, the identifier has block scope, which extends from the completion
of the declarator to the } that closes the associated block.
•
If an outer declaration of a lexically identical identifier exists, the compiler “hides” the
identifier until it encounters the } that closes the block.
•
If the declaration appears within the list of parameters in a function prototype, the
identifier has function prototype scope, which extends from the completion of the
declaration of the parameter to the end of the function declarator.
Linkages of Identifiers
Two lexically identical identifiers declared in different scopes can refer to the same function or object through a process called linkage. Three kinds of linkage exist: external,
internal, and none.
External Linkage
In the set of source files and libraries that constitute an entire program, every instance of a
particular identifier with external linkage denotes the same function or object. If the declarations in two source files or in disjoint scopes within one source file differ, the behavior is
undefined.
UM004407-0104
A ANSI C Language
Z8 User Manual
343
If its first lexical declaration with file scope in the source does not contain the keyword
static, an identifier of a function or object declared with file scope has external linkage.
If the declaration of a function or object contains the keyword extern, the identifier has
the same linkage as any previous declaration of the identifier with file scope. If no previous declaration exists, the identifier has external linkage.
If an identifier declared with external linkage is used in an expression, the entire program
must hold exactly one external definition for the identifier (a declaration that has external
linkage and for which storage is allocated). If an identifier declared with external linkage
is not used in an expression, the identifier needs no external definition.
Internal Linkage
Within one source file, each instance of an identifier with internal linkage denotes the
same function or object.
If its first lexical declaration with file scope in the source contains the keyword static,
an identifier of a function or object declared with file scope has internal linkage.
No Linkage
Identifiers with no linkage denote unique entities.
An identifier that declares anything other than a function or an object has no linkage. An
identifier declared as a function parameter has no linkage.
Except for a declaration of a function, an identifier declared within a block without the
keyword extern must have only one declaration in the same scope. Such an identifier has
no linkage.
Name Spaces of Identifiers
If more than one declaration of a particular identifier is visible at any point in a source file,
the syntactic context might clarify uses that refer to different entities. Because of these
cases, separate name spaces exist for various categories of identifiers.
•
•
The label names (clarified by the syntax of the label declaration and use).
•
The members of structures or unions. Each structure or union has a separate name
space for its member, clarified by the type of the expression used to access the
member through the . or -> operator.
•
All other identifiers, called ordinary identifiers (declared in ordinary declarators or as
enumeration constants).
UM004407-0104
The tags of structures, unions, and enumerations. Although they are clarified by the
preceding struct, union, or enum keyword, tags share the same name space.
A ANSI C Language
Z8 User Manual
344
Storage Durations of Objects
An object has storage duration that determines its lifetime. There are two storage durations:
•
•
static
automatic
An object declared with static storage duration is created and initialized only once, theoretically when the program begins execution. It exists and retains its value, unless explicitly modified, throughout the execution of the entire program.
A new instance of an object declared with automatic storage duration is created on each
normal entry into the block in which it is declared or on a jump to a label in the block or in
an enclosed block. If an initialization is specified, it is performed on each normal entry,
but not if the block ends in any of the following three ways:
•
•
•
reaching the terminating }
jumping to an enclosing block
executing a break or return statement
Types
An identifier's type determines its permitted use. If the identifier designates an object, the
type is characterized by the set of values that such an object might contain. The meaning
of the value of an object is determined by the types of the identifiers in an expression used
to access it.
Characters, integers, and floating-point numbers are collectively called the basic types.
An object declared as a character (char) is large enough to store any member of the
required source character set. If such a character is stored in a char object, its value is
non-negative.
Signed Integer Types
Signed integers fall into the following four types:
•
•
•
•
signed char
short int
int
long int
A signed char occupies the same amount of storage as a “plain” char. The natural size
of a “plain” int is suggested by the architecture of the execution environment: the size
must be large enough to contain any value in the range INT_MIN to INT_MAX as defined
in the header <limits.h>). The other types are provided to meet special needs.
UM004407-0104
A ANSI C Language
Z8 User Manual
345
The set of values of each signed integral type is a subset of the values of the next type in
the list. Even if the implementation defines two or more types of integers to have the same
set of values, they are nevertheless different types.
For signed char, short int, and each type of int, a corresponding unsigned integer
type exists, declared with the keyword unsigned, that uses the same amount of storage,
including sign information. The set of non-negative values of a signed type is a subset of
its corresponding unsigned type. A computation involving unsigned objects can never
overflow, because a result that does not fit in an object of that size is reduced by modulo of
the largest unsigned number that can be represented plus one.
Enumerated Types
The enumerated types are enumeration and void. An enumeration comprises a set of
named integer constant values. The void type specifies an empty set of values; no object
can have type void.
Any number of derived types can be constructed from the following basic and enumerated
types:
•
•
arrays comprising a contiguously allocated set of members of any one type of object
structures comprising a sequentially allocated set of named members of various types
of objects
•
•
unions comprising an overlapping set of named members of various types of objects
•
pointers to functions, to objects of any type, and to void
functions that accept arguments of various types and return a value of any one type of
object except an array
You can apply these methods of constructing derived types recursively.
Integral Types
Types char and int (of all sizes), both signed and unsigned, and enumerations are collectively called integral types. The values of integral types must be interpreted in a pure
binary numeration system.
Floating Types
Types float, double, and long double are collectively called floating types. The
representations of floating types are unspecified.
Miscellaneous Types
Integral and floating types are collectively called arithmetic types. Arithmetic types and
pointers are collectively called scalar types. Arrays and structures are collectively called
aggregate types.
UM004407-0104
A ANSI C Language
Z8 User Manual
346
The type of a function comprises the type of the value returned, the number and types of
the parameters (if specified), and whether a variable number of arguments is permitted.
Constants
Syntax
constant:
floating-constant
integer-constant
enumeration-constant
character-constant
floating-constant:
fractional-constant exponent-part opt floating-suffix opt
digit-sequence exponent-part floating-suffix opt
fractional-constant:
digit-sequence opt . digit-sequence
digit-sequence .
exponent-part:
e sign opt
digit-sequence
E sign opt digit-sequence
sign: one of
+digit-sequence:
digit
digit-sequence digit
floating-suffix: one of
flFL
Constraint
The value of a constant must be representable in the storage appropriate for its type in the
execution environment.
Semantics
Each constant has a type, determined by its form and value.
UM004407-0104
A ANSI C Language
Z8 User Manual
347
Integer Constants
An integer constant begins with a digit, but has no decimal point or exponent part. It might
have a prefix that specifies its base and a suffix that specifies its type.
Syntax
integer-constant:
decimal-constant integer-suffix opt
octal-constant integer-suffix opt
hexadecimal-constant integer-suffix opt
decimal-constant:
nonzero-digit
decimal-constant digit
octal-constant:
0
octal-constant octal-digit
hexadecimal-constant:
0x hexadecimal-digit
0X hexadecimal-digit
hexadecimal-constant hexadecimal-digit
nonzero-digit: one of
123456789
octal-digit: one of
01234567
hexadecimal-digit: one of
0123456789
abcdef
ABCDEF
integer-suffix:
unsigned-suffix long-suffix opt
long-suffix unsigned-suffix opt
UM004407-0104
A ANSI C Language
Z8 User Manual
348
unsigned-suffix: one of
u U
long-suffix: one of
l L
Semantics
The lexically first digit is the most significant.
The type of an integer constant is the first of the corresponding list in which its values can
be represented:
•
•
Unsuffixed decimal: int, long int, unsigned long int
Unsuffixed octal or hexadecimal: int, unsigned int, long int, unsigned long
int
•
•
•
Suffixed by the letter u or U: unsigned int, unsigned long int
Suffixed by the letter l or L: long int, unsigned long int
Suffixed by both the letters u or U and l or L: unsigned long int
Enumeration Constants
Syntax
enumeration-constant:
identifier
Semantics
An identifier declared as an enumeration constant has type int.
Character Constants
A character constant is a sequence of one or more characters enclosed in single quotes, as
in 'x' or 'ab'. A wide character constant is the same, except prefixed by the letter L. With a
few exceptions detailed later, the characters are any characters in the source character set.
UM004407-0104
A ANSI C Language
Z8 User Manual
349
The single quote (’), the double quote ("), the question mark (?), the backslash (\), and
arbitrary integral values are representable according to the following table of escape
sequences:
Character
Escape Sequence
single-quote (')
\'
double-quote (")
\"
question-mark (?)
\?
backslash (\)
\\
octal integer
\o \oo \ooo
hexadecimal integer
\xh \xhh \xhhh
alert
\a
backspace
\b
form feed
\f
new line
\n
carriage return
\r
horizontal tab
\t
vertical tab
\v
The double quote (") and question mark (?) are representable by themselves or by the
escape sequences \" and (\?) respectively, but the single quote (') must be represented by
the escape sequence (\'). The octal digits that follow the backslash in the escape
sequences \o, \oo, and \ooo are taken to be part of the construction of a single character.
The numerical value of the octal integer so formed specifies the value of the character.
The hexadecimal digits that follow the backslash and the letter x in the escape sequences
\xh, \xhh, and \xhhh are taken to be part of the construction of a single character. The
numerical value of the hexadecimal integer so formed specifies the value of the character.
\a (alert) produces an audible or visible alert. The active position is not changed.
\b (backspace) moves the active position to the position of the previous character. If the
active position is at the initial position of a line, the behavior is unspecified.
\f (form feed) moves the active position to the initial position at the start of the next logi-
cal page.
\n (new line) moves the active position to the initial position of the next line.
\r (carriage return) moves the active position to the initial position of the current line.
UM004407-0104
A ANSI C Language
Z8 User Manual
350
\t (horizontal tab) moves the active position to the next horizontal tabulation position on
the current line. If the active position is at or past the last defined horizontal tabulation
position, the behavior is unspecified.
\v (vertical tab) moves the active position to the initial position of the next vertical tabula-
tion position. If the active position is at or past the defined vertical tabulation position, the
behavior is unspecified.
If an escape sequence other than one of these is encountered, the behavior is undetermined.
Syntax
character-constant:
L opt 'c-char-sequence'
c-char-sequence:
c-char
c-char-sequence c-char
c-char:
any character in the source character set except
the single-quote ('), backslash (\), or new-line character
escape-sequence
escape-sequence: one of
\'
\"
\?
\o
\oo
\ooo
\xh
\xhh
\xhhh
\a
\b
\f
\\
\n
\r
\t
\v
Semantics
A character constant has type int. The value of a character constant containing a character that maps into a character in the execution character set, is the numerical value of the
representation of the mapped character interpreted as an integer. The value of a character
constant containing more than one character, or containing a character or escape sequence
not represented in the execution character set, is flagged as an error.
A wide character constant has type wchar_t, an integral type defined in <stddef.h>.
The value of a wide character constant containing a single multibyte character that maps
into a member of the extended execution character set, is the wide character (code)
corresponding to that multibyte character.
UM004407-0104
A ANSI C Language
Z8 User Manual
351
Example
The construction \0 represents the null character.
String Literals
A string literal is a sequence of zero or more characters enclosed in double-quotes, as in
"xyz".
The same considerations apply to each element to a sequence in a character string literal or
a wide string literal as if it were an integer character constant or a wide character constant,
except that the single-quote (') is representable by itself or by the escape sequence (\'), but
the double-quote (") must be represented by the escape sequence \"; in addition, the user
can use the same escape sequences as described for character constants.
Syntax
string-literal:
L opt "s-char-sequence opt "
s-char-sequence:
s-char
s-char-sequence s-char
s-char:
any member of the source character set except
the double-quote ("), backslash (\), or new-line character
escape-sequence
Semantics
A string literal is a character array with static storage duration. The compiler initializes the
literal with the given characters; it concatenates string literals that are adjacent tokens into
a single string literal, then appends a null character.
A character string literal is a character array that the compiler initializes with the individual bytes of the multibyte character sequence.
A wide string literal is an array of type wchar_t. The compiler initializes this literal with
the sequence of wide characters corresponding to the multibyte character sequence.
Identical string literals need not be distinct. If the program attempts to modify a string literal, the behavior is undefined.
UM004407-0104
A ANSI C Language
Z8 User Manual
352
Operators
Syntax
operator: one of
[ ] ( ) . ->>
++ -- & * + - ~ ! sizeof
/ % << >> < > <= >= == != ^ | & &||
? :
= *= /= %= += -= <<= >>= &= ^= |=
, # ##
Constraints
The operators [ ], ( ), and ? : must occur in pairs, possibly separated by expressions. The
operators # and ## can occur in macro-defining preprocessor directives only.
Semantics
An operator performs an operation that yields an evaluation, or a value. An operand is an
entity on which an operator acts.
Punctuators
Syntax
punctuator: one of
[ ]
( )
{ }
*
,
:
=
;
...
#
Constraints
The punctuators [ ], ( ), and { } must occur in pairs, possibly separated by expressions,
declarations, or statements. The punctuator # can occur in preprocessor directives only.
Semantics
A punctuator is a symbol that has independent syntactic significance but does not specify
an operation to be performed that yields a value. Depending on context, the same symbol
can also represent an operator or part of an operator.
UM004407-0104
A ANSI C Language
Z8 User Manual
353
COMMENTS
The characters /* introduce a comment except in the following cases:
•
•
•
•
•
within a character constant
within a string literal
within the quoted argument to a #include or #line preprocessing directive
within the arguments to a #error or #pragma preprocessing directive
within a comment
The compiler examines contents of a comment only to find the characters */ that terminate
it. The new style of comment is also supported. These comments begin with // and are terminated by a new line.
CONVERSIONS
Several operators can convert operand values from one type to another. This section specifies the result required from such an implicit conversion. The following conversions are
discussed:
•
•
•
•
•
•
•
•
“Characters and Integers” on page 353
“Signed and Unsigned Integers” on page 354
“Floating and Integral” on page 354
“Usual Arithmetic Conversions” on page 354
“Lvalues and Function Designators” on page 355
“Void” on page 356
“Pointers” on page 356
“const and volatile” on page 356
Conversion of an operand to the same type causes no change.
Arithmetic Types
Characters and Integers
A char, a short int, or an int bit-field, or their signed or unsigned varieties, can be
used in an expression wherever an int or unsigned int can be used. In all cases the value
is converted to an int if an int can represent all values of the original type; otherwise, it
is converted to an unsigned int. These are called the integral promotions.
The integral promotions preserve the value, including its sign. As discussed earlier,
“plain” char is treated as signed.
UM004407-0104
A ANSI C Language
Z8 User Manual
354
When an integer is demoted to a shorter unsigned integer or unsigned int bit-field or
unsigned char, the result is the remainder modulo the largest unsigned number that can be
represented plus one. When an integer is demoted to a shorter signed integer or int bitfield or signed char, the least significant bits of the integer are used.
Signed and Unsigned Integers
The following types are equivalent:
signed int = int
signed short int = short int
signed long int = long int
When an unsigned integer is promoted to a longer integer, its value is unchanged.
When a positive signed integer is converted to an unsigned integer of equal or greater
length, its value is unchanged. Otherwise, if the unsigned integer is longer, the signed
integer is first promoted to a signed integer of the same length as the unsigned integer,
then converted to unsigned by adding to it the largest number that can be represented in
the unsigned integer plus one.
Floating and Integral
When a value of floating type is converted to integral type, the fractional part is discarded.
If the value of the integral part cannot be represented in the space provided, the behavior is
undefined.
When a value of integral type is converted to floating type, some loss of precision occurs
if the destination lacks sufficient precision.
Usual Arithmetic Conversions
Many binary operators that expect operands of arithmetic type cause conversions and
yield result types in a similar way. The purpose is to yield a common type, which is also
the type of the result.
This pattern is called the usual arithmetic conversions.
•
First, if either operand has type unsigned long int, the other operand is converted
to unsigned long int.
•
Otherwise, if either operand has type long int, the other operand is converted to
long int.
•
Otherwise, the integral promotions are performed. Then, if either operand has type
unsigned int, the other operand is converted to unsigned int.
•
Otherwise, both operands have type int.
Operands can be converted to other types, provided neither range nor precision is lost; if
so, the type of the result is not change.
UM004407-0104
A ANSI C Language
Z8 User Manual
355
Other Operands
Lvalues and Function Designators
An lvalue is an expression (with an object type or an incomplete type other than void)
that identifies an object. The type of an object is determined by the lvalue used to identify the object.
A modifiable lvalue is an lvalue that does not have any of the following:
•
•
•
array type
an incomplete type
a const-qualified type
In addition, if it is a structure or union, the lvalue does not have any member (including,
recursively, any member of all contained structures or unions) with a const-qualified
type.
An lvalue that is not an array is converted to the value stored in the designated object
and is no longer an lvalue, except when it is the operand of any of the following:
•
•
•
•
•
the sizeof operator
the unary & operator
the ++ operator
the -- operator
the left operand of the . operator or an assignment operator
If the lvalue has qualified type, the value has the unqualified version of the type of the
lvalue; otherwise, the value has the type of the lvalue. If the lvalue has an incomplete type and does not have array type, the behavior is undefined.
If the lvalue is an array of a certain type, the compiler converts it to a pointer of that type
that points to the initial element of the array type and is not an lvalue. Exceptions occur
if the lvalue is one of the following:
•
•
•
the operand of the sizeof operator or the unary & operator
a character string literal that initializes an array of character type
a wide string literal that initializes an array with element type compatible with
wchar_t
A function designator is an expression that has function type. A function designator that
returns a type is converted to a pointer to a function returning that type, except when it is
the operand of the sizeof operator or the unary & operator.
UM004407-0104
A ANSI C Language
Z8 User Manual
356
Void
The (nonexistent) value of a void expression is not used in any way. Implicit or explicit
conversions must not be applied to such an expression.
Pointers
A pointer to void can be converted to a pointer to an object of any type. A pointer to an
object of any type can be converted to a pointer to void and back again; the result is equal
to the original pointer.
An integral constant expression with the value 0 or such an expression cast to type void *
is called a null pointer constant. If a null pointer constant is assigned to or compared for
equality to a pointer, the constant is converted to a pointer of that type. Such a pointer,
called a null pointer, does not point to any object or function.
const and volatile
The properties associated with the const type specifier are meaningful only for expressions that are lvalues.
An expression that has a type declared with the const type specifier is not a modifiable
lvalue.
An expression that has a type not declared with the const type specifier acquires the
const attribute if converted to a type declared with the const type specifier.
An expression declared to be a pointer to a type without the const attribute can be
assigned to a pointer to a type with the const attribute. This pointer does not modify the
object.
Except by an explicit cast, an expression declared to be a pointer to a type with the const
attribute is not assigned to a pointer to a type without the const attribute. If you attempt
to modify an object that has a type declared with the const type specifier by means of an
lvalue that has a type not declared with the const type specifier, the behavior is undefined.
An object declared with the volatile type specifier can be modified in ways unknown to
the compiler or have other unknown side effects. Therefore, the compiler evaluates any
expression referring to such an object strictly according to the sequence rules of the
abstract machine. Furthermore, at every sequence point the value of the object in storage
agrees with that prescribed by the abstract machine, except as modified by the unknown
factors mentioned previously.
An expression declared to be a pointer to a type without the volatile attribute can be
assigned to a pointer to a type with the volatile attribute. In this case, the compiler
obeys the rules for volatile objects when the volatile pointer refers to the object.
Except by an explicit cast, an expression declared to be a pointer to a type with the
volatile attribute is not assigned to a pointer to a type without the const attribute. If
UM004407-0104
A ANSI C Language
Z8 User Manual
357
the user attempts to modify an object declared to be a type with the const type specifier
by means of an lvalue that has a type not declared with the const type specifier, the
If an aggregate object type is declared with the const or volatile type specifier, the
type of each member of the aggregate is implicitly declared with that specifier. For example:
An object declared
extern volatile const real_time_clock;
can be modified by hardware, but cannot be assigned to, incremented, or decremented.
SEQUENCE POINTS
This section lists the sequence points as defined by the ANSI C standard. Sequence points
are points in the execution sequence at which all side effects of previous evaluations are
complete and no side effects of subsequent evaluations have taken place.
The following is the list of sequence points:
•
The call to a function, after the arguments have been evaluated (See “Function Calls”
on page 361.)
•
•
•
•
•
The logical AND operator && (See “Logical AND Operator (&&)” on page 372.)
The logical OR operator || (See “Logical OR Operator (||)” on page 373.)
The conditional operator ? (See “Conditional Operator (?:)” on page 373.)
The comma operator , (See “Comma Operator” on page 375.)
Completion of the evaluation of a full expression:
– an initializer of an object that has automatic storage duration (See “Initialization”
on page 391.)
– the expression statement (See “Expression and Null Statements” on page 395.)
– the controlling expression of a selection statement such as if or switch (See
“Selection Statements” on page 396.)
– the controlling expression of an iteration statement such as while, do, or for
(See “Iteration Statements” on page 397.)
EXPRESSIONS
An expression is a sequence of operators and operands that specifies how to compute a
value, how to generate side effects, or both. There are primary expressions (see page 359)
and constant expressions (see page 376). Operators can include any of the following:
•
•
UM004407-0104
“Postfix Operators” on page 360
“Postfix Increment and Decrement Operators” on page 363
A ANSI C Language
Z8 User Manual
358
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
“Unary Operators” on page 363
“Prefix Increment and Decrement Operators” on page 364
“Address and Indirection Operators” on page 364
“Unary Arithmetic Operators” on page 364
“Sizeof Operator” on page 365
“Cast Operators” on page 366
“Multiplicative Operators” on page 367
“Additive Operators” on page 368
“Bitwise Shift Operators” on page 369
“Relational Operators” on page 370
“Equality Operator” on page 370
“Bitwise AND Operator (&)” on page 371
“Bitwise Exclusive OR Operator (^)” on page 371
“Bitwise Inclusive OR Operator (|)” on page 372
“Logical AND Operator (&&)” on page 372
“Logical OR Operator (||)” on page 373
“Conditional Operator (?:)” on page 373
“Assignment Operators” on page 374
“Comma Operator” on page 375
The order of evaluation is unspecified except for the following:
•
•
•
•
•
•
function-call operator ( ( ) )
unary plus operator ( + )
logical AND operator ( && )
logical OR operator ( || )
conditional operator ( ?: )
comma operator ( , )
The compiler can evaluate subexpressions in any order, even if the subexpressions produce side effects. The order in which side effects take place is unspecified.
An expression involving more than one occurrence of the same communitive and associative binary operator (*, +, &, ^, |) can be regrouped arbitrarily, even in the presence of
UM004407-0104
A ANSI C Language
Z8 User Manual
359
parentheses, provided that this regrouping does not change the types of the operands or of
the results. Two ways exist to force a particular grouping of operations:
•
•
by explicitly assigning the value of the expression to group to an object
by preceding the grouping parentheses with a unary plus operator
Some operators, such as the unary operator ~ and the binary or bitwise operators (<<, >>,
&, ^, and |), have operands with integral type.
If an exception occurs during the evaluation of an expression (that is, if the result is not
mathematically defined or not representable), the behavior is undefined.
Primary Expressions
Syntax
primary-expression:
identifier
constant
string-literal
( expression )
Semantics
An identifier is a primary expression if it is an lvalue declared as designating an object
or a function locator designating a function.
A constant is a primary expression. Its type depends on its form, as detailed in “Constants”
on page 346.
A string literal is a primary expression. It is an lvalue of an array of char, as detailed in
“String Literals” on page 351.
A parenthesized expression is a primary expression. Its type and value are identical to
those of the unadorned expression. It is an lvalue if the unadorned expression is an
lvalue, or a function locator if the unadorned expression is a function locator.
UM004407-0104
A ANSI C Language
Z8 User Manual
360
Postfix Operators
Syntax
postfix-expression:
primary-expression
postfix-expression [ expression ]
postfix-expression ( argument-expression-list opt )
postfix-expression . identifier
postfix-expression -> identifier
postfix-expression ++
postfix-expression -argument-expression-list:
assignment-expression
argument-expression-list , assignment-expression
Array Subscripting
Constraints
One of the expressions is a pointer to type. The other expression has integral type. The
result is of type.
Semantics
A postfix expression followed by an expression in square brackets [] is a subscripted designation of a member of an array object.
For instance, E1 is identical to (*(E1+(E2))). Because of the conversion rules that apply to
the binary + operator, if E1 is an array object and E2 is an integer, E1 [E2] designates the
E2-th member of E1 (counting from zero).
Successive subscript operators designate members of a multidimensional array object. If E
is an n-dimensional array with dimensions i x j x ... x k, then E (used as other than an
lvalue) is converted to a pointer to an (n-1)-dimensional array with dimensions j x ... x k. If
the unary * operator is applied to this pointer explicitly, or implicitly as a result of subscripting, the result is the pointed-to (n-1)-dimensional array, which itself is converted into
a pointer if used as other than lvalue. Therefore, arrays are stored in row-major order: the
last subscript varies fastest.
UM004407-0104
A ANSI C Language
Z8 User Manual
361
Example
Consider the array object defined by the following declaration:
int x[3] [5];
Here, x is a 3x5 array of ints; more precisely, x is an array of three member objects, each
of which is an array of five ints. In the expression x [i], which is equivalent to (*(x+(i))),
•
•
x is converted to a pointer to the initial array of five ints.
•
The compiler adds the results and applies indirection to yield an array of five ints.
i is adjusted according to the type of x, which conceptually entails multiplying i by the
size of the object to which the pointer points: an array of five int objects.
When used in the expression x[i][j], that in turn is converted to a pointer to the first of the
ints, so x[i][j] yields an int.
Function Calls
Constraints
A function does not return a value of an array or function.
If a function prototype declarator is in scope, the number of arguments shall agree with the
number of formal parameters. The types shall be such that each formal parameter can be
assigned the value of the corresponding argument.
Semantics
A postfix expression followed by parentheses ( ) contains a possibly empty, comma-separated list of expressions. The list of expressions specifies the arguments to the function.
The postfix expression denotes the function called, and is declared as a pointer to a function returning type (which can be the result of converting a function locator). The result is
of type.
If no declaration is in scope for an identifier used as the first expression in a function call,
the identifier is implicitly declared exactly as if, in the innermost block containing the
function call, the declaration
extern int identifier( );
appeared. This function has external linkage and no information about its parameters, and
returns an int.
An argument can be any expression other than a void expression. In preparing for the call
to a function, each argument is evaluated, and each formal parameter is assigned the value
of the corresponding argument. An argument or a formal parameter that has an array or
function type is converted to a pointer.
If no function prototype declarator is in scope, the integral promotions are performed
and arguments that have type float are promoted to double. These are called the default
UM004407-0104
A ANSI C Language
Z8 User Manual
362
argument conversions. If the number of arguments or their types after conversion do not
agree with those of the formal parameters, the behavior is undefined.
If a function prototype declarator is in scope, the arguments are compared with the formal
parameters and are converted accordingly. The ellipsis notation (,...) in a function prototype declarator stops argument type checking and conversion stop after the last declared
formal parameter. The default argument conversions are performed on unchecked arguments.
No other conversions are performed automatically. In particular, the number and types of
arguments are not compared with those of the formal parameters in a function definition
that does not include a function prototype declarator.
The order of evaluation of arguments and of subexpressions within arguments is unspecified, but the call itself is a sequence point before which all side effects are completed.
Recursive function calls are permitted, both directly and indirectly through any chain of
other functions.
Structure and Union Members
Constraints
The first operand of the . operator has a structure or union type, and the second operand
names a member of that type.
The first operand of the -> operator is a pointer to a structure or union. The second operand names a member of the type pointed to.
Semantics
A postfix expression followed by a dot (.) and an identifier designates a member of a
structure or union entity. The value is that of the named member, and is an lvalue unless
the first expression is the value returned by a function call.
A postfix expression followed by an arrow -> and an identifier designates a member of a
structure or union object. The value is that of the named member of the object to which the
first expression points. This value is an lvalue.
With one exception, if a member of a union is inspected when the value of the object has
been assigned using a different member, the behavior is indeterminate. One special guarantee is made in order to simplify the use of unions; if a union contains several structures
that share a common initial sequence, and if the union object currently contains one of
these structures, you can inspect the common initial part of any of them.
Example
The following is a valid fragment
union {
struct {
UM004407-0104
A ANSI C Language
Z8 User Manual
363
int type;
} n;
struct {
int type;
int intnode;
} ni;
struct {
int type;
long longnode;
} nf;
} u;
u.nf.type = 1;
u.nf.longnode = 3;
/*...*/
if (u.n.type == 1)
/*...*/
Postfix Increment and Decrement Operators
Constraints
The operand of the postfix increment or decrement operator has scalar type and is a modifiable lvalue.
Semantics
The result of the postfix ++ operator is the value of the operand. After noting the result,
the compiler increments (adds 1 to) the value of the operand. See “Additive Operators” on
page 368 and “Compound Assignment” on page 375 for information on types and conversions and the effects of operations on pointers. The side effect of updating the stored value
of the operand can be delayed until the next sequence point is reached.
The postfix -- operator is analogous to the postfix ++ operator, except that the compiler
decrements (subtracts 1 from) the value of the operand.
Unary Operators
Syntax
unary-expression:
postfix-expression
++ unary-expression
-- unary-expression
unary-operator cast-expression
sizeof unary-expression
UM004407-0104
A ANSI C Language
Z8 User Manual
364
sizeof ( type-name )
unary-operator: one of
&
*
+
-
~
!
Prefix Increment and Decrement Operators
Constraints
The operand of the prefix increment or decrement operator has scalar type and is a modifiable lvalue.
Semantics
The compiler increments the value of the operand of the prefix ++ operator and stores the
incremented value before using the value. The expression ++E is equivalent to (E+=1).
See “Additive Operators” on page 368 and “Compound Assignment” on page 375 for
information on types and conversions and the effects of operations on pointers.
The prefix -- operator is analogous to the prefix ++ operator, except that the compiler decrements (subtracts 1 from) the value.
Address and Indirection Operators
Constraints
The operand of the unary & operator is either a function locator or an lvalue that designates an object other than a bit-field of an object declared with the register storage-class
specifier.
The operand of the unary * operator has pointer type, other than pointer to void.
Semantics
The result of the unary & (address-of) operator is a pointer to the object designated by its
operand. If the operand has type, the result is a pointer to type.
The unary * operator denotes indirection. If the operand points to a function, the result is a
function locator; if it points to an object, the result is an lvalue designating the object. If
the operand is a pointer to type, the result is of that type. If an invalid value is assigned to
the pointer, the behavior of the unary * operator is undefined.
Unary Arithmetic Operators
Constraints
The operand of the unary + and unary - operator has arithmetic type. The operand of the
~ operator has integral type. The operand of the ! operator has scalar type.
UM004407-0104
A ANSI C Language
Z8 User Manual
365
Semantics
The result of the + operator is the value of its operand. The compiler performs integral
promotion on the operand, and the result has the promoted type. Except that it inhibits
regrouping of subexpressions of E with subexpressions outside of E, the expression +E is
equivalent to (0+E).
The result of the unary - operator is the negative of its operand. The integral promotion is
performed on the operand, and the result has the promoted type. The expression -E is
equivalent to (0-E).
The result of the ~ operator is the bit-wise complement of its operand. In other words, each
bit in the result is set if, and only if, the corresponding bit in the converted operand is not
set. The integral promotion is performed on the operand, and the result has the promoted
type.
The expression ~E is equivalent to (ULONG_MAX-E) if E has type unsigned long, or to
(UINT_MAX-E) if E has any other unsigned type. (The constants ULONG_MAX and
UINT_MAX are defined in the header <limits.h>.)
The result of the logical negation operator ! is 0 if the value of its operand is nonzero, or 1
if the value of its operand is 0. The result has type int. The expression !E is equivalent to
(0==E).
Sizeof Operator
Constraints
The sizeof operator can not be applied to an expression that has type function, bit-field,
or void, or to the parenthesized name of the type of such an expression.
Semantics
The sizeof operator yields the size (in bytes) of its operand, which can be an expression
or the parenthesized name of a type.
•
When applied to an operand that has type char, unsigned char, or signed char,
the result is 1.
•
When applied to an operand that has array type, the result is the total number of bytes
in the array.
•
When applied to an operand that has structure or union type, the result is the total
number of bytes in such an object considered as a member of an array, including
whatever internal and trailing padding might be needed to align each member in such
an array properly.
The size is determined from the type of the operand, which is not itself evaluated. The
result is an integer constant. The size of the result is determined by the code generator, and
UM004407-0104
A ANSI C Language
Z8 User Manual
366
its type (an unsigned integral type) is size_t. size_t is defined in the <stddef.h>
header.
Examples
A principal use of the sizeof operator is in communication with routines such as storage
allocators and I/O systems. A storage-allocation function might accept a size (in bytes) of
an object to allocate and return a pointer to void. For example:
extern void *alloc(size_t);
double *dp = alloc(sizeof *dp);
The alloc function ensures that its return value is aligned suitably for conversion to a
pointer to double.
Another use of the sizeof operator is to compute the number of members in an array:
sizeof (array) / sizeof (array[0])
Cast Operators
Syntax
cast-expression:
unary-expression
( type-name ) cast-expression
Constraints
If the type name specifies void type, the operand can be any expression other than a void
expression. Otherwise, the type name specifies scalar type and the operand has scalar type.
Semantics
Preceding an expression by a parenthesized type name converts the value of the expression to the named type. This construction is called a cast. A cast that specifies an implicit
conversion or no conversion has no effect on the type or value of an expression.
Conversions involving pointers (other than from a pointer to void or from a pointer to an
object) can be specified by an explicit cast.
•
A pointer can be converted to an integer. If the space provided is not long enough, the
•
•
An arbitrary integer can be converted to a pointer.
UM004407-0104
A pointer to an object of one type can be converted to a pointer to an object of another
type. The resulting pointer might not be valid if it is improperly aligned for the type of
object pointed to. However, a pointer to an object of a given alignment can be
converted to a pointer to an object of a less strict alignment and back again; the result
A ANSI C Language
Z8 User Manual
367
compares equal to the original pointer. (An object that has type char has the least strict
alignment.)
•
A pointer to a function of one type can be converted to a pointer to a function of
another type and back again; the result compares equal to the original pointer. If a
converted pointer is used to call a function of other than the original type, the behavior
is undefined.
Multiplicative Operators
Syntax
multiplicative-expression:
cast-expression
multiplicative-expression * cast-expression
multiplicative-expression / cast-expression
multiplicative-expression % cast-expression
Constraints
Each operand has arithmetic type. The operands of the % operator have integral type.
Semantics
The compiler performs the usual arithmetic conversions on the operands.
The result of the binary * operator is the product of the operands. The binary * operator is
communitive and associative, and expressions involving several multiplications at the
same level can be regrouped.
The result of the / operator is the quotient of the operands.
The result of the % (modulo) operator is the remainder from the division of the first operand by the second.
When integers are divided and the division is inexact, if both operands are positive the
result of the / operator is the largest integer less than the true quotient and the result of the
% operator is positive. If either operand is negative, the result of the / operator is the largest integer less than the true quotient.
Example
The expression (a/b)*b + a%b equals a (if b is not 0).
UM004407-0104
A ANSI C Language
Z8 User Manual
368
Additive Operators
Syntax
additive-expression:
multiplicative-expression
additive-expression + multiplicative-expression
additive-expression - multiplicative-expression
Constraints
Both of the operands can have arithmetic type. Additional type possibilities for each operator involve pointer operands: one operand can be a pointer to an object and the other an
expression that has integral type. (Incrementing or decrementing is equivalent to adding or
subtracting 1.) You can subtract two pointers to objects that have the same type.
Semantics
If both operands have arithmetic type, the compiler performs the usual arithmetic conversions.
The result of the binary + operator is the sum of the operands. The binary + operator is
communitive and associative, and expressions involving several additions at the same
level can be regrouped.
The result of the binary - operator is the difference of the operands.
When an expression that has integral type is added to or subtracted from a pointer, the
integral value is first multiplied by the size of the object pointed to. The result is a pointer
of the same type as the original pointer. If the original pointer points to a member of an
array object, and the array object is large enough, the result points to another member of
the same array object, approximately offset from the original member.
For instance, if P points to a member of an array object, the expression P+1 points to the
next member of the array object. If the result is used as the operand of a unary * operator,
the behavior is undefined unless both the pointer operand and the result points to a member of the same array object.
When two pointers to members of the same array object are subtracted, the difference is
divided by the size of a member. The result represents the difference of the subscripts of
the two array members. The type of the result is a signed integral type, ptrdiff_t, defined in
the <stddef.h> header. As with any other arithmetic overflow, if the result does not fit in
the space provided, the behavior is undefined.
If two pointers that do not point to members of the same array object are subtracted, the
behavior is undefined. However, if P points to the last member of the same array object,
the expression (P+1) P has the value 1, even though P+1 does not point to a member of the
same array object as P.
UM004407-0104
A ANSI C Language
Z8 User Manual
369
Example
The compiler can compute the expression a + (b + c) as (a + b) + c. This feature allows the compiler to sum a and b during program translation if they are constant
expressions. However, this regrouping might lead to overflow or loss of precision. One
way to force the grouping is to write the expression as a + + (b + c), where white
space is required between the first two plus signs.
Bitwise Shift Operators
Syntax
shift-expression:
additive-expression
shift-expression << additive-expression
shift-expression >> additive-expression
Constraints
Each of the operands has integral type.
Semantics
The compiler performs integral promotions on each of the operands. Then the right operand is converted to int; the type of the result is that of the promoted left operand. If the
value of the right operand is negative or is greater than or equal to the width in bits of the
promoted left operand, the behavior is undefined.
The result of E1 << E2 is E1 left-shifted E2 bit positions; vacated bits are filled with
zeros. If E1 has an unsigned type, the value of the result is
(E1 * 2<B^>E2) - modulo(ULONG_MAX + 1)
if E1 has type unsigned long, or
(E1 * 2<B^>E2) - modulo(UINT_MAX + 1)
otherwise.
The constants ULONG_MAX and UINT_MAX are defined in the header <limits.h>.
The result of E1 >> E2 is E1 right-shifted E2 bit positions. If E1 has a signed type, an
arithmetic shift is performed. If E1 has an unsigned type, the right shift is logical; the
value of the result is the integral part of the quotient of E1 divided by (2 raised to the
power of E2).
UM004407-0104
A ANSI C Language
Z8 User Manual
370
Relational Operators
Syntax
relational-expression:
shift-expression
relational-expression < shift-expression
relational-expression > shift-expression
relational-expression <= shift-expression
relational-expression >= shift-expression
Constraints
Both of the operands can have arithmetic type, or both can be pointers to objects that have
the same type.
Semantics
If both of the operands have arithmetic type, the compiler performs the usual arithmetic
conversions.
When two pointers are compared, the result depends on the relative locations in the
address space of the objects pointed to; pointers are compared as if they were unsigned
integers of the appropriate length. If the objects pointed to are not members of the same
aggregate object, the pointer expression P=1 is greater than P, even though P+1 does not
point to a member of the same array object as P.
Each of the operators < (less than), > (greater than), <= (less than or equal to), and >=
(greater than or equal to) yield 1 if the specified relation is true and 0 if it is false. The
result has type int.
Equality Operator
Syntax
equality-expression:
relational-expression
equality-expression == relational-expression
equality-expression != relational-expression
Constraints
Both of the operands can have arithmetic type, or both can be pointers that have the same
type. In addition, one can be an object pointer and the other a pointer to void, or one can
be a pointer and the other a null pointer constant.
UM004407-0104
A ANSI C Language
Z8 User Manual
371
Semantics
The == (equal to) and the != (not equal to) operators are analogous to the relational operators except for their precedence.
If two pointers to objects or functions compare equal, they point to the same object or
function, respectively. If one of the operands is a pointer to an object and the other has
type pointer to void, the object pointer is converted to that type.
Bitwise AND Operator (&)
Syntax
AND-expression:
equality-expression
AND-expression & equality-expression
Constraints
Each of the operands has integral type.
Semantics
The result of the binary & operator is the bitwise AND of the operands: each bit in the
result is set if, and only if, each of the corresponding bits in the converted operands is set.
The binary & operator is communitive and associative, and an expression involving several binary & operations at the same level can be regrouped.
Bitwise Exclusive OR Operator (^)
Syntax
exclusive-OR-expression:
AND-expression
exclusive-OR-expression ^AND-expression
Constraints
Each operand has integral type.
Semantics
The result of the ^ operator is the bitwise exclusive OR of the operands: each bit in the
result is set if, and only if, exactly one of the corresponding bits in the converted operands
UM004407-0104
A ANSI C Language
Z8 User Manual
372
is set. The ^ operator is communitive and associative, and an expression involving several
^ operations at the same level can be regrouped.
Bitwise Inclusive OR Operator (|)
Syntax
inclusive-OR-expression:
exclusive-OR-expression
inclusive-OR-expression | exclusive-OR-expression
Constraints
Each operand has integral type.
Semantics
The result of the | operator is the bitwise inclusive OR of the operands: each bit in the
result is set if, and only if, at least one of the corresponding bits in the converted operands
is set. The | operator is communitive and associative, and an expression involving several |
operations at the same level can be regrouped.
Logical AND Operator (&&)
Syntax
logical-AND-expression:
inclusive-OR-expression
logical-AND-expression && inclusive-OR-expression
Constraints
Each operand has scalar type.
Semantics
The && operator yields 1 if both of its operands evaluate to nonzero, or 0 otherwise. The
Unlike the bitwise binary & operator, the && operator guarantees left-to-right evaluation
and is a sequence point. If the value of the first operand is 0, the second operand is not
evaluated.
UM004407-0104
A ANSI C Language
Z8 User Manual
373
Logical OR Operator (||)
Syntax
logical-OR-expression:
logical-AND-expression
logical-OR-expression || logical-AND-expression
Constraints
Each operand has scalar type.
Semantics
The || operator yields 1 if either of its operands evaluates to nonzero, or 0 otherwise. The
Unlike the bitwise | operator, the || operator guarantees left-to-right evaluation and is a
sequence point. If the value of the first operand is nonzero, the second operand is not
evaluated.
Conditional Operator (?:)
Syntax
conditional-expression:
logical-OR-expression
logical-OR-expression ? expression : conditional-expression
Constraints
The first operand has scalar type. The second and third operands can be any of the following:
•
•
•
•
•
Both arithmetic type
Both structure, union, or pointer type
Both void expressions
One object pointer and one pointer to void
One pointer and one null pointer constant
Semantics
The ?: operator is a sequence point. It evaluates the first operand. If its value is nonzero the
result is the value of the second operand. Otherwise, the result is the value of the third
operand. The types of the operands determine the result.
UM004407-0104
A ANSI C Language
Z8 User Manual
374
If both the second and third operands have arithmetic type, the usual arithmetic conversions are performed to bring them to a common type. The result has that type.
•
•
•
If both the operands have structure, union, or pointer type, the result has that type.
•
If one operand is a pointer and the other operand a null pointer constant, the result has
the type of the pointer.
If both the operands are void expressions, the result is a void expression.
If one of the operands is a pointer to void, the other operand is converted to that type
and the result has that type.
Assignment Operators
Syntax
assignment-expression:
conditional-expression
unary-expression assignment-operator assignment-expression
assignment-operator: one of
=
*=
/=
%=
+=
-=
<<=
>>=
&=
^=
|=
Constraints
An assignment operator has a modifiable lvalue as its left operand.
Semantics
An assignment operator stores a value in the object designated by the left operand. An
assignment expression has the type of the left operand and the value of the left operand
after the assignment, but is not an lvalue. The compiler stores the value of the assignment
expression before using the value.
The order of evaluation of the operands is unspecified.
Simple Assignment
Constraints
Both the operands have arithmetic type or the same structure, union, or pointer type. In
addition, if the left operand is a pointer, either operand can be a pointer to void, or the right
operand can be a null pointer constant.
UM004407-0104
A ANSI C Language
Z8 User Manual
375
Semantics
In the simple assignment with =, the value of the right operand is converted to the type of
the left operand and replaces the value of the object designated by the left operand.
If an object is assigned to another object that overlaps in storage with any part of the object
being assigned, the behavior is undefined.
Example
In the program fragment
int f(void) ;
char c ;
/*...*/
/*...*/ ((c = f()) == -1) /*...*/
the int value returned by the function can be truncated when stored in the char, and then
converted back to int width before the comparison. In an implementation in which
“plain” char behaves the same as unsigned char, the result of the conversion cannot be
negative, so the operands of the comparison can never compare equal. Therefore, for full
portability, you must declare the variable c as int.
Compound Assignment
Constraints
Each operand has arithmetic type consistent with those allowed by the corresponding
binary operator; in addition, for += and -= only, the left operand can be a pointer, in which
case the right operand has integral type.
Semantics
A compound assignment of the form E1 op = E2 differs from the simple assignment
expression E1 = E1 op (E2) only in that the lvalue E1 is evaluated only once.
Comma Operator
Syntax
expression:
expression , assignment-expression
Semantics
The comma operator is a sequence point. The compiler first evaluates the left operand of a
comma operator as a void expression. Then it evaluates the right operand; the result has
its type and value.
UM004407-0104
A ANSI C Language
Z8 User Manual
376
Example
As indicated by the syntax, in contexts where a comma is a punctuator (in lists of argument to functions and lists of initializers), the comma operator as described in this section
appears only in parentheses. Consider the following function call:
f(a, (t=3, t+2), c)
The function has three arguments, the second of which has the value 5.
Constant Expressions
Syntax
constant-expression:
conditional-expression
Constraints
The compiler does not evaluate these operators in any constant expression:
•
•
•
•
a function-call operator ( )
an increment or decrement operator (++ or --)
an assignment operator
a comma operator (,)
An integral constant expression involves only integer, enumeration, and character constants and casts to integral types. The compiler does not evaluate the following:
•
•
•
•
array-subscripting operators ([])
member-access operators (. and -)
the address-of (&) and indirection (*) unary operators
arbitrary casts for integral constant expressions
Further restrictions that apply to the integral constant expressions used in preprocessing
conditional-inclusion directives are discussed later.
For constant expressions in initializers, in addition to integral constant expressions, floating constants and arbitrary casts can be used. Lvalues of objects that have static storage
duration or function identifiers can also specify addresses, either explicitly with the unary
& operator or implicitly for unsubscribed array identifiers or function identifiers.
Semantics
An expression that evaluates to a constant is required in several contexts. To specify the
size of a bit-field member of a structure, the value of an enumeration constant, the size of
an array, or the value of a case constant, the expression is an integral constant expression.
UM004407-0104
A ANSI C Language
Z8 User Manual
377
More latitude is permitted for initializers. If the expression is evaluated in the translation
environment, the arithmetic precision and range are at least as great as if the expression
were being evaluated in the execution environment.
DECLARATIONS
This section describes the following:
•
•
•
•
•
•
•
•
“Storage-Class Specifiers” on page 378
“Type Specifiers” on page 379
“Structure and Union Specifiers” on page 380
“Enumeration Specifiers” on page 383
“Declarators” on page 384
“Type Names” on page 389
“Type Definitions and Type Equivalence” on page 390
“Initialization” on page 391
Syntax
declaration:
declaration-specifiers init-declarator-list opt ;
declaration-specifiers:
storage-class-specifier declaration-specifiersopt
type specifier declaration-specifiers opt
init-declarator-list:
init-declarator
init-declarator-list , init-declarator
init-declarator:
declarator
declarator = initializer
Constraints
A declaration declares at least a declarator, a tag, or the members of an enumeration.
UM004407-0104
A ANSI C Language
Z8 User Manual
378
Semantics
A declaration specifies the interpretation and attributes of a set of identifiers. A declaration that also causes storage to be reserved for an object or function named by an identifier
is a definition.
The declaration specifiers consist of a sequence of specifiers that indicate the scope, storage duration, and type of the entities that the declarators denote. The init-declarator-list is
a comma-separated sequence of declarators, each of which can have an initializer. The
declarators contain the identifiers (if any) being declared.
Storage-Class Specifiers
Syntax
storage-class specifier:
typedef
extern
static
auto
register
Constraints
You can declare one storage-class specifier at most.
Semantics
The typedef specifier is called a “storage-class specifier'' for syntactic convenience only.
See “Type Definitions and Type Equivalence” on page 390 for more information. The
meanings of the various scopes and storage durations are discussed in “Scopes of Identifiers” on page 342 and in “Storage Durations of Objects” on page 344.
A declaration with storage-class specifier extern indicates that, if the identifier declared is
referred to, then somewhere in the set of source files that constitutes the entire program, an
external object definition for the given identifier (a definition with file scope) exists. If the
declaration with storage-class specifier extern occurs outside a function, the identifier is
declared with file scope and external linkage, and can itself serve as the required definition
as discussed later.
A declaration of an object with storage-class specifier static, auto, or register also
serves as a definition, as it causes an appropriate amount of storage to be reserved. The
storage-class specifier static specifies static storage duration; the storage-class specifiers
auto and register specify automatic storage duration.
UM004407-0104
A ANSI C Language
Z8 User Manual
379
A declaration with storage-class specifier register is an auto declaration, with a suggestion that the objects declared be stored in fast-access machine registers if possible. The
types of objects that are stored in such registers and the number of such declarations in
each block that are effective are described in “Operators” on page 352.
The following rules apply to a declaration without a storage-class specifier:
•
•
•
For a function, the meaning is the same as if the storage-class specifier were extern.
For an object declared inside a function or among its formal para-meters, the meaning
is the same as if the storage-class specifier were auto.
For an object declared outside a function, the declaration is an external object
definition.
Type Specifiers
Syntax
type-specifier:
char
short
int
long
signed
unsigned
const
volatile
void
fract
struct-or-union-specifier
enum-specifier
typedef-name
Note: float and double are not defined in Z8. fract is a nonstandard language extension.
Constraints
One of the keywords long or short can be specified in conjunction with int; the meaning is the same if the keyword int is not mentioned.
The keywords signed or unsigned can be specified alone (in which case the presence of
int is implied), or in conjunction with int or its short or long varieties, or with char.
UM004407-0104
A ANSI C Language
Z8 User Manual
380
The keyword long can be specified in conjunction with double.
The keywords const and volatile can be specified alone (in which case the presence
of int is implied), or in conjunction with other types of specifiers.
Only const and volatile can be specified in conjunction with a structure, union, or
enumeration specifier, or with a typedef name.
Otherwise, at most one type specifier can be given in a declaration.
Semantics
The characteristics of the const and volatile type modifiers are discussed in “Other
Operands” on page 355. Specifiers for structures, unions, and enumerations are discussed
in “Structure and Union Specifiers” on page 380. Declarations of typedef names are discussed in “Type Definitions and Type Equivalence” on page 390. The characteristics of
the other types are discussed in “Types” on page 344.
If no type specifiers exist in a declaration, the type is taken to be int.
Structure and Union Specifiers
Syntax
struct-or-union-specifier:
struct-or-union identifier opt { struct-declaration-list }
struct-or-union identifier
struct-or-union:
struct
union
struct-declaration-list:
struct-declaration
struct-declaration-list struct-declaration
struct-declaration:
type-specifier-list struct-declarator-list ;
type-specifier-list:
type-specifier
type-specifier-list type-specifier
struct-declarator-list:
struct-declarator
UM004407-0104
A ANSI C Language
Z8 User Manual
381
struct-declarator-list , struct-declarator
struct-declarator:
declarator
declarator opt : constant-expression
Constraints
A structure or union does not contain an instance of itself, but can contain a pointer to an
instance of itself.
The constant expression that specifies the width of a bit-field has integral type and nonnegative value. The width of a bit-field does not declare more storage than an ordinary
object of the same type.
Semantics
As discussed in “Types” on page 344, a structure is a type consisting of an ordered
sequence of named members, and a union is a type consisting of an overlapping sequence
of named members. A union is similar to a structure whose members overlap and whose
size is sufficient to contain the largest of its members. At most one of the members can be
stored in a union object at any time.
Structure and union specifiers have the same form.
The presence of a struct-declaration-list in a struct-or-union-specifier declares a new type.
The struct-declaration-list is a sequence of declarations for the members of the structure
or union.
A member of a structure or union can have any previously declared type of an object,
except the type being declared. In addition, a member can be declared to consist of a specified number of bits, including a sign bit, if any. Such a member is called a bit-field; its
width is preceded by a colon.
A bit-field can have type int, unsigned int, or signed int. The compiler treats the
high-order bit position of a “plain” int bit-field as a sign bit.
The compiler can allocate any bit-field small enough to fit in an int. If enough space
remains, a bit-field that follows another bit-field is packed into adjacent bits of the same
int. If insufficient space remains, a bit-field that does not fit is put into the next int.The
order of allocation of bit-fields within an int is high-order to low-order.
A bit-field declaration with no declarator, but only a colon and a width, indicates an
unnamed bit-field. As a special case of this, a bit-field with a width of 0 indicates that no
further bit-field is to be packed into the unit in which the previous bit-field, if any, was
placed.
Each non-bit-field member of a structure or union object is aligned as described in “Type
Definitions and Type Equivalence” on page 390.
UM004407-0104
A ANSI C Language
Z8 User Manual
382
Within a structure object, the bit-field members and the units in which bit-fields reside
have addresses that increase in the order in which they are declared. A pointer to a structure object, suitably cast, points to its initial member or, if it is a bit-field, to the unit in
which it resides. There might therefore be unnamed holes within or at the end of a structure, but not at its beginning, nor more than necessary to achieve the appropriate alignment.
A pointer to a union object, suitably cast, points to each of its members, or if a member is
a bit-field, to the unit in which it resides.
Structure and Union Tags
A complete structure or union specifier of the form
struct-or-union identifier { struct-declaration-list }
declares the identifier to be the tag of the structure or union specified by the list. A subsequent declaration in the same scope can then use the tag, but the bracketed declaration list
is omitted.
An incomplete structure or union specifier of the form
struct-or-union identifier
declares a tag that can be used only when the size of an object of the specified type is not
needed, as follows:
•
•
when a typedef name is declared to be a synonym for a structure or union
when a pointer to or a function returning a structure or union is being declared
The specification must be complete before such a function is called or defined. Another
declaration of the tag in the same scope (but not in an enclosed block, which can declare a
new type known only within that block) can give the complete specification. A vacuous
structure or union specifier of the form
struct-or-union identifier ;
supersedes any prior declaration in an enclosing scope.
Examples
This mechanism allows you to declare a self-referential structure, as in the following
example:
struct tnode {
char tword [20];
int count;
struct tnode *left;
struct tnode *right;
};
UM004407-0104
A ANSI C Language
Z8 User Manual
383
This code segment declares a structure that contains an array of 20 characters, an integer,
and two pointers to objects of the same type. Once this structure is declared, the following
declaration
struct tnode s, *sp;
defines s to be the object of the given type and sp to be a pointer to an object of the given
type. With these declarations,
•
•
•
sp-count refers to the count member of the object to which sp points
s.left refers to the left struct tnode pointer of s
s.right-tword[0] refers to the initial character of the tword member of the right struct
tnode pointed to from s
The following illustrates the use of prior declaration of a tag to declare a pair of mutuallyreferential structures:
struct s1 { struct s2 *s2p; /*...*/ }; /* D1 */
struct s2 { struct s1 *s1p; /*...*/ }; /* D2 */
These declarations specify a pair of structures that contain pointers to each other. If s2
were already declared as a tag in an enclosing scope, the declaration D1 refers to it, not to
the tag s2 declared in D2. To eliminate this context sensitivity, the vacuous declaration
struct s2;
can be inserted ahead of D1. This declares a new tag s2 in the inner scope; the declaration
D2 then completes the declaration of the new type.
Enumeration Specifiers
Syntax
enum-specifier:
enum identifier opt { enumerator-list }
enum identifier
enumerator-list:
enumerator
enumerator-list , enumerator
enumerator:
enumeration-constant
enumeration-constant = constant-expression
UM004407-0104
A ANSI C Language
Z8 User Manual
384
Semantics
The identifiers in an enumerator list are declared as constants of type int and can appear
wherever constants are permitted. If the first enumerator has no =, the values of the corresponding constants begin at 0 and increase by 1 in the order in which they are declared,
until an enumerator with = appears. An enumerator with = gives the associated enumeration constant the value indicated; subsequent enumeration constants with no = continue
the progression from the earlier ascribed value (and can duplicate other values in the same
enumeration).
The scope of an enumeration constant begins after its declaration and ends with the scope
of the enumeration of which it is a member. The identifiers of enumeration constants in the
same scope shall all be distinct from each other and from other identifiers declared in ordinary declarators.
The role of the identifier in the enum-specifier is analogous to that of the tag in a struct-orunion-specifier: it names a particular enumeration.
An object that has an enumeration type behaves like an int in an expression. The compiler can use the set of values in the enumeration to determine whether to allocate less
storage than an int.
Example
enum hue { chartreuse, burgundy, claret=20, winedark };
/*...*/
enum hue col, *cp;
/*...*/
col = claret;
cp = &col;
/*...*/
/*...*/ (*cp != burgundy) /*...*/
makes hue the tag of an enumeration, and then declares col as an object that has that type
and cp as a pointer to an object that has that type. The enumerated values are in the set
{ 0, 1, 20, 21 }.
Declarators
Syntax
declarator:
pointer opt direct-declarator
direct-declarator:
identifier
( declarator )
UM004407-0104
A ANSI C Language
Z8 User Manual
385
direct-declarator [ constant-expression opt ]
direct-declarator (parameter-type-list )
direct-declarator ( identifier-list opt )
pointer:
* type-specifier-list opt
* type-specifier-list opt pointer
parameter-type-list:
parameter-list
parameter-list , ...
parameter-list:
parameter-declaration
parameter-list , parameter-declaration
parameter-declaration:
declaration-specifiers declarator
type-name
identifier-list:
identifier
identifier-list , identifier
Semantics
Each declarator declares one identifier, and asserts that when a construction of the same
form as the declarator appears in an expression, it yields an entity of the indicated scope,
storage duration, and type.
If an unadorned identifier appears as a declarator, it has the type indicated by the type
specifiers heading the declaration.
A declarator in parentheses is identical to the unadorned declarator, but the binding of
complex declarators can be altered by parentheses.
In the following subsections, consider a declaration
T D1
where T is a type specifier (such as int) and D1 is a declarator. Suppose this declaration
makes the identifier have type type-specifier T, where the type-specifier is empty if D1 is
just a plain identifier (so that the type of x in int x is just int).
UM004407-0104
A ANSI C Language
Z8 User Manual
386
Pointer Declarators
Constraints
Only const and volatile can appear in the list of type specifiers.
Semantics
If D1 has the form
* type-specifier-list opt D
the contained identifier is a type-specifier pointer to T. If the type specifier list includes
const, the identifier is a constant pointer. If the type specifier list includes volatile, the
identifier is a volatile pointer.
Examples
The following pair of declarations demonstrates the difference between a variable pointer
to a constant value and a constant pointer to a variable value:
const int *ptr_to_constant;
int *const constant_ptr;
The contents of the array pointed to by ptr_to_constant must not be modified, but
ptr_to_constant itself can be changed to point to another const int. Similarly, the contents of the array pointed to by constant_ptr can be modified, but constant_ptr itself
always points to the same location.
The declaration of the constant pointer constant_ptr can be clarified by including a definition for a pointer to int.
typedef int *int_ptr;
const int_ptr constant_ptr;
Array Declarators
Constraints
The constant expression that specifies the size of an array has integral type and value
greater than zero. It is present, except that the first size can be omitted when an array is
being declared as a formal parameter of a function, or when the array declaration has
storage-class specifier extern and the definition that actually allocates storage is given
elsewhere. It can also be omitted when the declarator is followed by initialization; in this
case, the size is determined by the number of initializers supplied.
Semantics
If D1 has the form
D [constant-expression opt ]
UM004407-0104
A ANSI C Language
Z8 User Manual
387
the contained identifier is an array of type-specifier with T elements. When several array
of specifications are adjacent, a multi-dimensional array is declared.
Two declarations of an array with file scope, one of which has a missing first constant
expression and the other of which has a specified size, are compatible; the size of the array
is known from the completion of the declarator that specifies the size to the end of the
source file.
Examples
long fa [11], *afp[17];
declares an array of long numbers and an array of pointers to long numbers.
There are distinctions between the following declarations:
extern int *x;
extern int y[];
The first declares x to be a pointer to int; the second declares y to be an array of int of
unspecified size, the storage for which is defined elsewhere.
Function Declarators (Including Prototypes)
Constraints
All declarators of a particular function must agree in the type returned.
Semantics
If D1 has the form
D(parameter-type-list)
or
D(identifier-list opt )
the contained identifier is a type-specifier function returning T.
A parameter type list declares the types of, and optional identifiers for, the formal parameters of the function. If the list terminates with an ellipsis (, ...), no information about the
number of types of the parameters after the comma is supplied.
In a declaration that is a function definition, identifiers are present for every parameter.
The only storage-class specifier allowed is register, which suggests that the corresponding
parameter be stored in a machine register if possible. If the list is empty, the function has
no parameters.
In a declaration that is not a function, any identifier declared in the list has function prototype scope, which extends to the end of the declaration. The only storage-class specifier
allowed is register, which is ignored. The special case of void as the only item in the list
specifies that the function has no parameters.
UM004407-0104
A ANSI C Language
Z8 User Manual
388
The definition and every prototype of a function shall agree in the number and types of the
parameters and in the use of the ellipsis terminator. The parameter type checking includes
agreement on the number of dimensions of arrays and on the bounds for each dimension
except the first. Function declarators with empty lists can also appear.
An identifier list declares only the identifiers of the formal parameters of the function. If
the list is empty in a function declaration that is not part of a function definition, no information about the number or types of the parameters is supplied. If the list is empty in a
function declaration that is part of a function definition, the function has no parameters.
Examples
The declaration
static int f(void), *fip(), (*pfi) ();
declares a function f with no parameters returning an int, a function fip with no parameter-type information returning a pointer to an int, and a pointer pfi to a function with no
parameter-type information returning an int. It is especially useful to compare the last
two.
The binding of *fip( ) is *(fip( )), so that the declaration suggests, and the same
construction in an expression requires, the calling of a function fip, and then using indirection through the pointer result to yield an int. In the declarator (*pfi)( ), the extra
parentheses are necessary to indicate that indirection through a pointer to a function yields
a function locator, which is then used to call the function; it returns an int.
The identifiers of the functions f and fip are declared as having file scope (not program
scope) and internal linkage. The pointer pfi is declared as having file scope and internal
linkage if the declaration is outside of any function, block scope and no linkage if the declaration is inside a function.
Here are two more intricate examples.
int (*apfi[])(int *x, int *y);
declares an array apfi of pointers to functions returning int. Each of these functions has
two parameters that are pointers to int. The identifiers x and y are declared for descriptive
purposes only and go out of scope at the end of the declaration apfi. The declaration
int (*fpfi(int (*)(long), int))(int, ...);
declares a function fpfi that returns a pointer to a function returning an int. The function fpfi has two parameters; a pointer to a function returning an int (with one parameter
of type long), and an int. The pointer returned by fpfi points to a function that has at least
one parameter, which has type int.
UM004407-0104
A ANSI C Language
Z8 User Manual
389
Type Names
Syntax
type-name:
type-specifier-list abstract-declarator opt
abstract-declarator:
pointer
pointer opt direct-abstract-declarator
direct-abstract-declarator:
( abstract-declarator )
direct-abstract-declarator opt [ constant-expression opt ]
direct-abstract-declarator opt ( parameter-type-list opt )
Semantics
You might need to specify a type in several situations. Examples include specifying the
following:
•
•
•
A type conversion with cast (See “Multiplicative Operators” on page 367.)
The type of the operand of the sizeof operator (See “Sizeof Operator” on page 365.)
The type of a formal parameter in a function declarator (See “Function Declarators
(Including Prototypes)” on page 387.)
You can specify a type with a type name, which is syntactically a declaration for an object
of that type that omits the identifier of the object.
Examples
Declaration
Type
int
int
int *
Pointer to int
int *[3]
Array of three pointers to int
int (*) [3]
Pointer to an array of three ints
int *( )
Function with no parameter type information returning a pointer
to int
int (*)(void)
Pointer to a function with no parameters returning an int
int (*const [])(unsigned int, ...) Array of an unspecified number of constant pointers to
functions, each with one parameter that has type unsigned
int and an unspecified number of other parameters, returning
an int.
UM004407-0104
A ANSI C Language
Z8 User Manual
390
Type Definitions and Type Equivalence
Syntax
typedef-name:
identifier
Semantics
With the scope of a declaration whose storage-class specifier is typedef, each identifier
declared becomes equivalent to a type specifier naming the type associated with the identifier as described in “Declarators” on page 384.
A typedef declaration does not introduce a brand-new type, but a synonym for a type
that can be specified in another way. Two types are the same if they have the same ordered
set of type specifiers and abstract declarators, either directly or through typedefs. Two
structures or unions are different if they have no names or different names, taking tags and
typedef synonyms into account, even if their members are identical.
A typedef name shares the same name space as other identifiers declared in ordinary
declarators. It can be redeclared in an inner block, but the type cannot be omitted in the
inner declaration.
Examples
After
typedef int MILES, KLICKSP();
typedef struct { double re, im; } complex;
the constructions
MILES distance;
extern KLICKSP *metricp;
complex x;
complex z, *zp;
are all valid declarations. The type of distance is int, that of metricp is “pointer to function with no parameter-type information returning int,” and that of x and z is the specified structure; zp is a pointer to such a structure. The object distance is considered to have
exactly the same type as any other int object.
After the declarations
typedef struct s1 { int x; } t1, *tp1;
typedef struct s2 { int x; } t2, *tp2;
type t1 and the type pointed to by tp1 are equivalent to each other and to the type
struct s1, but different from the types struct s2 and t2, the type pointed to by tp2,
and type int.
UM004407-0104
A ANSI C Language
Z8 User Manual
391
Initialization
Syntax
initializer:
{ initializer-list }
{ initializer-list , }
initializer-list:
initializer
initializer-list , initializer
Semantics
Any declaration that defines an object can include an initializer that specifies its initial
value. The initializers in a declaration list are evaluated in the order they appear in the
source file.
For a union object, the initializer initializes the member that appears first in the declaration list of the union type.
An object that has static storage duration can be initialized by constant expressions
only. If such an object is not initialized explicitly, it is initialized implicitly as if every
member that has arithmetic type were assigned 0 and every member that has pointer type
were assigned a null pointer constant.
Except as noted for aggregates, an object that has automatic storage duration can be
initialized by arbitrary expressions involving constants, previously declared identifiers,
function calls, and assignments. Such an object is not initialized implicitly; if the value is
used before one is assigned, the behavior is undefined.
If the declared object is a scalar, the initializer is a single expression, optionally in braces.
The initial value of the object is that of the expression; the same conversions as for assignment are performed.
Initialization of Aggregate Objects
If the declared object is a structure object that has automatic storage duration, the initializer can be a single expression that has the same type. The initial value of the object is that
of the expression.
If the declared object is an array of chars, the initializer can be a string literal. Successive
characters of the string literal (including the terminating null character if there is room or
if no size for the array is specified) initialize the members of the array.
UM004407-0104
A ANSI C Language
Z8 User Manual
392
Otherwise, the initializer is a brace-enclosed list of initializers for the members of the
aggregate, written in increasing subscript or member order. All expressions in such a list
are constant expressions.
If the aggregate contains members that are aggregates, these rules apply recursively to the
subaggregates. If the initializer of a subaggregate begins with a left brace, the succeeding
initializers initialize the members of the subaggregate. Otherwise, only enough initializers
from the list are taken to account for the members of the first subaggregate; any remaining
initializers are left to initialize the next member of the subaggregate of which the current
aggregate is a part.
No more initializers exist in a list than there are members of an aggregate. If fewer initializers exist in a list than there are members of an aggregate, the remainder of the aggregate
is initialized as if it had storage duration.
Examples
The declaration
int x[] = { 1, 3, 5 };
defines and initializes x as a one-dimensional array object that has three members, since
no size was specified and three initializers exist.
int y[4] [3] = {
{ 1, 3, 5 },
{ 2, 4, 6 },
{ 3, 5, 7 },
};
is a definition with a fully bracketed initialization: 1, 3, and 5 initialize the first row of the
array object y[0], namely y[0][0], y[0][2]. Likewise the next two lines initialize y[1] and
y[2]. The initializer ends early, so y[3] is initialized with zeros. The following code
achieves the same effect:
int y[4] [3] = {
1, 3, 5, 2, 4, 6, 3, 5, 7
};
The initializer for y[0] does not begin with a left brace, so three items from the list are
used. Likewise the next three are taken successively for y[1] and y[2]. Also,
int z[4] [3] = {
{ 1 }, { 2 }, { 3 }, { 4 }
};
initializes the first column of z as specified and initializes the rest with zeros.
struct { int a[3], b; } w[] = { { 1 }, 2 };
is a definition with a partly bracketed initialization, which is not recommended programming practice. It defines an array with two member structures: w[0] .a[0] is 1 and w[1]
.a[0] is 2. All the other elements are zero.
UM004407-0104
A ANSI C Language
Z8 User Manual
393
Finally, the declaration
char s[] = "abc", t[3] = "abc";
defines character array objects s and t whose members are initialized with string literals.
This declaration is identical to
char s[] = {‘a', ‘b', ‘c', ‘\0' },
t[] = { ‘a', ‘b', ‘c' };
The contents of the arrays are modifiable. However, the declaration
char *p = "abc";
defines a character pointer p that is initialized to point to a character array object whose
members are initialized with a string literal. If an attempt is made to use p to modify the
contents of the array, the behavior is undefined.
STATEMENTS
The following types of statements are described in this section:
•
•
•
•
•
•
“Labeled Statements” on page 394
“Compound Statement (or Block)” on page 394
“Expression and Null Statements” on page 395
“Selection Statements” on page 396
“Iteration Statements” on page 397
“Jump Statements” on page 398
Syntax
statement:
labeled-statement
compound-statement
expression-statement
selection-statement
iteration-statement
jump-statement
Semantics
A statement specifies an action to perform. Except as indicated, statements are executed in
sequence.
UM004407-0104
A ANSI C Language
Z8 User Manual
394
A full expression is an expression that is not part of another expression. Each of the following is a full expression:
•
•
•
•
an initializer of an object that has automatic storage duration
the expression in an expression statement
the controlling expression of an selection statement (if or switch)
the controlling expression of an iteration statement (while, do, or for)
Completion of the evaluation of a full expression is a sequence point.
Labeled Statements
Syntax
labeled-statement:
identifier : statement
case constant-expression : statement
default : statement
Constraints
A named label can be used only as a target of a goto statement. A case or default label can
appear only in a switch statement. The constraints on such labels are discussed in
“Switch Statement” on page 396.
Semantics
Any statement can be preceded by a prefix that declares an identifier as a label name.
Labels in themselves do not alter the flow of control, which continues unimpeded across
them.
Compound Statement (or Block)
Syntax
compound-statement:
{ declaration-list opt statement-list opt }
declaration-list:
declaration
declaration-list declaration
statement-list:
statement
UM004407-0104
A ANSI C Language
Z8 User Manual
395
statement-list statement
Constraints
An object declared extern inside a block is not initialized in the declaration as storage
since it is defined elsewhere.
Semantics
A compound statement (also called a block) allows a set of statements to be grouped into
one syntactic unit, which can have its own set of declarations and initializers (as discussed
in “Storage Durations of Objects” on page 344).
Expression and Null Statements
Syntax
expression-statement:
expression opt ;
Semantics
An expression statement, consisting of an expression followed by a semicolon, is evaluated for its side effects, such as assignments and function calls.
A null statement, consisting of just a semicolon, has no expression and performs no operations.
Examples
If a function call is evaluated as an expression statement for its side effects only, the discarding of its value can be made explicit by converting the expression to a void expression
with a cast:
int p(int);
/*...*/
(void) p(0);
In the program fragment
char *s;
/*...*/
while (*s++ != ‘\0')
;
a null statement supplies an empty loop body to the iteration statement.
A null statement can also carry a label just before the closing } of a compound statement.
while (loop1) {
/*...*/
while (loop2) {
UM004407-0104
A ANSI C Language
Z8 User Manual
396
/*...*/
if (want_out)
goto end_loop1;
/*...*/
}
/*...*/
end_loop1: ;
}
Selection Statements
Syntax
selection-statement:
if ( expression ) statement
if ( expression ) statement else statement
switch ( expression ) statement
Semantics
A selection statement selects among a set of statements depending on the value of a controlling expression.
If Statement
Constraints
The controlling expression of an if statement has scalar type.
Semantics
In both forms, the first substatement is executed if the expression evaluates to nonzero. In
the else form, the second substatement is executed if the expression evaluates to zero. If
the first substatement is reached through a label, the second substatement is not executed.
An else is associated with the lexically immediately preceding else-less if that is in the
same block (but not in the enclosed block).
Switch Statement
Constraints
The controlling expression of a switch statement and the constant expression of each
case label has integral type. No two of the case constants in the same switch statement
can have the same value after conversion. There can be at most one default label in a
switch statement (but any enclosed switch statement can also have a default label).
UM004407-0104
A ANSI C Language
Z8 User Manual
397
Semantics
A switch statement causes control to jump to, into, or past the statement that is the
switch body, depending on the value of a controlling expression and the values of any
case prefixes on or in the switch body. If there are nested switch statements within the
switch body, any default or case labels in them are ignored.
The integral promotions are performed on the controlling expression. The constant expression in each case label is converted to the type of the promoted controlling expression. If
a converted value matches that of the promoted controlling expression, control jumps to
the statement following the matched case prefix. Otherwise, if there is a default label,
control jumps to the labeled statement. If no converted case constant matches and there is
no default label, none of the statements in the switch body are executed.
Iteration Statements
Syntax
iteration-statement:
while ( expression ) statement
do statement while ( expression ) ;
for ( expression opt ; expression opt ; expression opt ) statement
Constraints
The controlling expression of an iteration statement has scalar type.
Semantics
An iteration statement repeatedly executes a statement called the loop body until the controlling expression evaluates to zero.
While Statement
The evaluation of the controlling expression takes place before each execution of the loop
body.
Do Statement
The evaluation of the controlling expression takes place after each execution of the loop
body.
For Statement
Except for the behavior of a continue statement in the loop body, the statement
for (expression-1 ; expression-2 ; expression-3 ) statement
is equivalent to
UM004407-0104
A ANSI C Language
Z8 User Manual
398
expression-1 ;
while (expression-2) {
statement
expression-3 ;
}
Thus, expression-1 specifies initialization for the loop;
expression-2 specifies an evaluation made before each iteration, such that execution of the
loop continues until the expression evaluates to zero; and
expression-3 specifies an operation (such as incrementing) that is performed after each
iteration.
Both expression-1 and expression-3 can be omitted, or can have any type, or can be void
expressions. An omitted expression-2 is replaced by a nonzero constant.
Jump Statements
Syntax
jump-statement:
goto identifier ;
continue ;
break ;
return expression opt ;
Semantics
A jump statement causes an unconditional jump to another place.
Goto Statement
Constraints
The identifier in a goto statement names a label located somewhere in the current function.
Semantics
A goto statement causes an unconditional jump to the named label in the current function.
UM004407-0104
A ANSI C Language
Z8 User Manual
399
Continue Statement
Constraints
A continue statement can appear only in a loop body.
Semantics
A continue statement causes a jump to the loop-continuation portion of the smallest
enclosing iteration statement; that is, to the end of the loop body. More precisely, in each
of the statements
while (/*...*/) {
/*...*/
continue;
/*...*/
contin: ;
}
do {
/*...*/
continue;
/*...*/
contin: ;
} while (/*...*/);
for (/*...*/) {
/*...*/
continue;
/*...*/
contin: ;
}
unless the continue statement shown is in an enclosed iteration statement (in which case
it is interpreted within that statement), it is equivalent to goto contin:. (Following the
contin: is a null statement.)
Break Statement
Constraints
A break statement can appear only in a switch body or loop body.
Semantics
A break statement terminates execution of the smallest enclosing switch or iteration
statement.
Return Statement
Constraints
A return statement with an expression can not appear in a function declared as returning
type void.
Semantics
A return statement terminates execution of the current function and returns control to its
caller. A function can have any number of return statements, with and without expressions.
UM004407-0104
A ANSI C Language
Z8 User Manual
400
If a return statement with an expression is executed, the value of the expression is
returned to the caller. If the expression has a type different from that of the function in
which it appears, it is converted as if it were assigned to an object of that type.
If a return statement without an expression is executed, and the value of the function call
is used by the caller, the behavior is undefined. Reaching the } that terminates a function is
equivalent to executing a return statement without an expression.
EXTERNAL DEFINITIONS
This section covers the following topics:
•
•
“Function Definitions” on page 401
“External Object Definitions” on page 403
Syntax
file:
external-definition
file external-definition
external-definition:
function-definition
declaration
Constraints
If present, the storage-class specifier in an external definition shall be extern (which is
the default and declares external linkage) or static (which declares internal linkage). As
with other declarations, if there are no type specifiers the type shall be taken to be int.
Semantics
The unit of program text is a file, which consists of a sequence of external definitions of
functions and objects (and other declarations, such as type declarations) described as
“external” because they appear outside of any function. The syntax of an external definition is the same as that of a declaration, except that the code for a function (the function
body) appears outside of any other function.
An external definition implicitly declares its identifier to have file scope and static storage duration.
UM004407-0104
A ANSI C Language
Z8 User Manual
401
Function Definitions
Syntax
function-definition:
declaration-specifiers opt declarator function-body
function-body:
declaration-list opt compound-statement
Constraints
As specified only by the declarator portion of a function definition, the first identifier
(which is the name of the function) has type function.
If the declarator is a function prototype declarator, no declaration list can follow. If the
declarator is an identifier list, only the identifiers it names can be declared in the declaration list. An identifier declared as a typedef name shall not be redeclared as a formal
parameter. The only storage-class specifier allowed in the declaration of a formal parameter is register.
Semantics
The declarator in a function definition specifies the name of the function being defined
and lists the identifiers of its formal parameters. If the declarator has the form of a function
prototype declarator, the list also declares the types of all the formal parameters: such a
declarator also serves as a function prototype. If the declarator is an identifier list, the
types of the formal parameters can be declared in a following declaration list. Any formal
parameter whose type is not declared in the declaration list is assumed to have type int.
If a function that accepts a variable number of arguments is defined without the ellipsis
notation in its prototype, the behavior is undefined.
If any formal parameter is declared with a type that is affected by the default argument
conversions, the following rules apply:
•
If a function prototype is in scope when the function is defined, and a call is executed
for which no semantically equivalent function prototype is in scope, the behavior is
undefined.
•
If no function prototype is in scope when the function is defined, and a call is executed
for which a function prototype is in scope that declares other than the appropriate
widened types (according to the default argument conversions), the behavior is
undefined.
•
On entry to the function the value of the argument expression is converted to the type
of the formal parameter, as if by assignment to the formal parameter.
UM004407-0104
A ANSI C Language
Z8 User Manual
402
Because array expressions and function identifiers as arguments are always converted to
pointers before the call, a declaration of a formal parameter as an array of type always is
adjusted to a pointer to type, and a declaration of a formal parameter as a function returning type is always adjusted to a pointer to a function returning type.
Each formal parameter is treated as having automatic storage duration and is an lvalue.
The layout of the storage for formal parameters is unspecified.
Examples
extern int max (int a, int b)
{
return a > b ?
}
a
:
b;
Here extern is the storage-class specifier and int is the type specifier (each of which can
be omitted as those are the defaults); max(int a, int b) is the function declarator; and
{ return
a
>
b
?
a
:
b; }
is the function body. The following equivalent definition uses the identifier-list form for
the parameter declarations:
extern int max(a, b)
int a, b;
{
return a
}
>
b
?
a
:
b;
Here int a, b; is the declaration list for the formal parameters, which can be omitted as
those are the defaults.
The reason for this constraint is so that the type in a function definition cannot be inherited
from a typedef:
typedef int F(void);
/* type F is "function of no arguments returning int" */
F f { /*...*/ }
/* WRONG: implies that f returns a function */
int f(void) { /*...*/ }
/* RIGHT: f has the same type as F */
int g() { /*...*/ }
/* RIGHT: g has the same type as F */
F *f(void) { /*...*/ }
/* f returns a pointer to a function */
F * ((f))(void) { /*...*/ }
/* same: parentheses irrelevant */
int (*fp)(void);
/* fp points to a function that has type F */
F *Fp;
/* Fp points to a function that has type F */
UM004407-0104
A ANSI C Language
Z8 User Manual
403
To pass one function to another, you might say
int f(void);
/*...*/
g(f);
f is declared explicitly in the calling function, as its appearance in the expression g(f) was
not followed by (. Then the definition of g might read
g(int (*funct)(void))
{
/*...*/ (*funct)() /*...*/
}
or, equivalently,
g(int func(void))
{
/*...*/ func() /*...*/
}
External Object Definitions
Constraints
One external definition must exist for each object declared with the storage-class specifier
extern that is referred to in any way.
Semantics
A declaration of an identifier of an object outside of any function that includes an initializer constitutes the definition of the object.
A declaration of an identifier of an object outside of any function without an initializer,
and without a storage-class specifier or with the storage-class specifier static, constitutes a
tentative definition. If a definition is encountered later in the source file, all tentative definitions are taken to be declarations of the same object. If no subsequent definition is
encountered, the first tentative definition is taken to be a definition with initializer equal to
0.
Examples
int i1 = 1; /* definition, external linkage */
static int i2 = 2; /* definition, internal linkage */
extern int i3 = 3; /* definition, external linkage */
int i4; /* tentative definition, external linkage */
static int i5; /* tentative definition, internal linkage */
int i1; /* valid tentative definition, refers to previous */
int i2; /* violates A.3.2.2, linkage disagreement */
int i5; /* violates A.3.2.2, linkage disagreements */
UM004407-0104
A ANSI C Language
Z8 User Manual
404
extern
extern
extern
extern
extern
UM004407-0104
int
int
int
int
int
i1;
i2;
i3;
i4;
i5;
/*
/*
/*
/*
/*
refers
refers
refers
refers
refers
to
to
to
to
to
previous,
previous,
previous,
previous,
previous,
linkage
linkage
linkage
linkage
linkage
is
is
is
is
is
external
internal
external
external
internal
*/
*/
*/
*/
*/
A ANSI C Language
Z8 User Manual
405
B
ANSI C Preprocessing Directives
This appendix describes the ANSI C preprocessor commands supported by the Z8 developer’s environment ANSI C-Compiler. The following topics are covered:
•
•
•
•
•
•
•
•
“Conditional Inclusion” on page 407
“Source File Inclusion” on page 409
“Macro Replacement” on page 410
“Line Control” on page 415
“Error Directive” on page 415
“Pragma Directive” on page 415
“Null Directive” on page 416
“Predefined Macro Names” on page 416
A preprocessing directive consists of a sequence of preprocessing tokens that begins with
a # preprocessing token that is the first character in the source file (after any white space
containing no new-line characters) or that follows white space containing at least one newline character, and ended by the next new-line character.
SYNTAX
preprocessing-file:
group opt
group:
group-part
group group-part
group-part:
pp-tokens opt new-line
if-section
control-line
if-section:
if-group elif-group opt else- group opt endif-line
UM004407-0104
B ANSI C Preprocessing Directives
Z8 User Manual
406
if-group:
# if
constant-expression new-line group opt
# ifdef
identifier new-line group opt
# ifndef
elif-groups:
elif-group
elif-groups elif-group
elif-group:
# elif
else-group:
# else
new-line group opt
endif-line:
# endif
new-line
control-line:
# include
pp-tokens new-line
# define
identifier replacement- list new-line
# define
identifier lparen identifier- list opt ) replacement-list newline
# undef
identifier new-line
# line
pp-tokens new-line
# error
# pragma
#
new-line
lparen:
the left-parenthesis character without preceding white space
UM004407-0104
Z8 User Manual
407
replacement-list:
pp-tokens opt
pp-tokens:
preprocessing-token
pp-tokens preprocessing-token
new-line:
the new-line character
CONSTRAINTS
The only white-space characters that can appear between preprocessing tokens within a
preprocessing directive are space and horizontal-tabs.
SEMANTICS
The implementation can process and skip sections of source files conditionally, include
other source files, and replace macros. These capabilities are called preprocessing,
because conceptually they occur before translation of the resulting translation unit.
The preprocessing tokens within a preprocessing directive are not subject to macro expansion unless otherwise stated.
CONDITIONAL INCLUSION
Constraints
Constant expressions are discussed in “Constant Expressions” on page 376. Additional
restrictions apply to a constant expression that controls conditional inclusion. The expression shall be an integral constant expression that shall not contain a sizeof operator, a
cast, or an enumeration constant. It can contain unary expressions of the form
defined identifier
or
defined ( identifier )
which evaluate to 1 if the identifier is currently defined as a macro name (that is, if it is
predefined or if it has been the subject of a #define preprocessing directive without an
intervening #undef directive). If not, the expression evaluates to 0.
Each preprocessing token that remains after all macro replacements have occurred is in the
lexical form of a token.
UM004407-0104
Z8 User Manual
408
Semantics
Preprocessing directives of the forms
# if
# elif
check whether the controlling constant expression evaluates to nonzero.
Before evaluation, macro invocations in the list of preprocessing tokens that become the
controlling constant expression are replaced (except for those macro names modified by
defined), just as in normal text. The defined operator explicitly appears in the original
list of preprocessing tokens. After all replacements are finished, the resulting preprocessing tokens are converted into tokens. Then, before the controlling constant expression is
evaluated, all remaining identifiers are replaced with OL and each integer constant not
already suffixed with l or L is considered to be additionally suffixed with L. This includes
interpreting character constants, which might involve converting escape sequences into
characters.
Preprocessing directives of the forms
# ifdef
# ifndef
check whether the identifier is or is not currently defined as a macro name. Their conditions are equivalent to #if defined identifier and #if !defined identifier respectively.
Each directive's condition is checked in order. If it evaluates to false (zero), the group that
it controls is skipped. Directives are processed only through the name that determines the
directive in order to keep track of the level of nested conditionals; the rest of the directives'
preprocessing tokens are ignored, as are the other preprocessing tokens in the group. Only
the first group whose control condition evaluates to true (nonzero) is processed. If none of
the conditions evaluates to true, and there is a #else directive, the group controlled by the
#else is processed; lacking a #else directive, all the groups until the #endif are
skipped.
UM004407-0104
Z8 User Manual
409
SOURCE FILE INCLUSION
Constraints
A #include directive identifies a header or source file that the implementation can process.
Semantics
A preprocessing directive of the form
# include <h-char-sequence> new- line
searches a sequence of places for a header identified uniquely by the specified character
sequence between the < and > delimiters, and causes the replacement of that directive by
the entire contents of the header.
# include "q-char-sequence" new-line
causes the replacement of that directive by the entire contents of the source file identified
by the specified character sequence between the " delimiters. The named source file is
searched for. If this search fails, the directive is reprocessed as if it read
# include <h-char-sequence> new- line
with the identical contained character sequence (including > characters, if any) from the
original directive.
# include pp-token new-line
(that does not match one of the two previous forms) is permitted. The preprocessing
tokens after include in the directive are processed just as in normal text. (Each identifier
currently defined as a macro name is replaced by its replacement list of preprocessing
tokens.) The directive resulting after all replacements matches one of the two previous
forms.
A #include preprocessing directive can appear in a source file that has been read
because of a #include directive in another file.
Examples
The most common uses of #include processing directives are as in the following:
#include <stdio.h>
#include "myprog.h"
UM004407-0104
Z8 User Manual
410
The following example illustrates a macro-replaced #include directive:
#if VERSION == 1
#define INCFILE ‘‘vers1.h''
#elif VERSION == 2
#define INCFILE ‘‘vers2.h'' /* and so on */
#else
‘‘versN.h'' #define INCFILE
#endif
#include INCFILE
MACRO REPLACEMENT
Constraint
Two replacement lists are identical if, and only if, the preprocessing tokens in both have
the same number, ordering, spelling, and white-space separation, where all white-space
separations are considered identical.
An identifier currently defined as a macro without use of lparen (an object-like macro)
can be redefined by another #define preprocessing directive provided, that the second
definition is an object-like macro definition and the two replacement lists are identical.
An identifier currently defined as a macro using lparen (a function-like macro) can be
redefined by another #define preprocessing directive provided, that the second definition is a function-like macro definition that has the same number and spelling of parameters, and the two replacement lists are identical.
The number of arguments in an invocation of a function-like macro agrees with the number of parameters in the macro definition, and a ) preprocessing token exists that terminates the invocation.
A parameter identifier in a function-like macro shall be uniquely declared within its scope.
Semantics
The identifier immediately following the define is called the macro name. Any whitespace characters preceding or following the replacement list of preprocessing tokens is not
considered part of the replacement list for either form of macro.
If a # preprocessing token, followed by a name, occurs lexically at the point at which a
preprocessing directive can begin, the name is not subject to macro replacement.
# define identifier replacement-list new-line
defines a function-like macro that causes each subsequent instance of the macro name to
be replaced by the replacement list of preprocessing tokens that constitute the remainder
of the directive.
UM004407-0104
Z8 User Manual
411
# define identifier lparen identifier-list opt ) replacement-list new-line
defines a function-like macro with arguments, similar syntactically to a function call. The
parameters are specified by the optional list of identifiers, whose scope extends from their
declaration in the identifier list until the new-line character that terminates the #define
preprocessing directive. Each subsequent instance of the function-like macro name followed by a ( as the next preprocessing token introduces the sequence of preprocessing
tokens that is replaced by the replacement list in the definition (an invocation of the
macro). The replaced sequence of preprocessing tokens is terminated by the matching )
preprocessing token, skipping intervening matched pairs of left and right parentheses
tokens.
Within the sequence of preprocessing tokens making up an invocation of a function-like
macro, new-line is considered a normal white-space character.
The sequence of preprocessing tokens bounded by the outermost matching parentheses
forms the list of arguments for the function-like macro. The individual arguments within
the list are separated by comma preprocessing tokens, but comma preprocessing tokens
bounded by nested parentheses do not separate arguments. If any argument consists of no
preprocessing tokens, the behavior is undefined. If there are sequences of preprocessing
tokens within the list of arguments that otherwise act as preprocessing directives, the
Argument Substitution
After the arguments for the invocation of a function-like macro have been identified, argument substitution takes place. A parameter in the replacement list, unless preceded by a #
or ## preprocessing token or followed by a ## preprocessing token, is replaced by the corresponding argument after all macros have been expanded. Before being substituted, each
argument's preprocessing tokens are completely macro-replaced as if they formed the rest
of the source file. No other preprocessing tokens are available.
The # Operator
Constraints
Each # preprocessing token in the replacement list for a function-like macro must be followed by a parameter as the next preprocessing token in the replacement list.
Semantics
If, in the replacement list, a parameter is immediately preceded by a # preprocessing
token, both are replaced by a single character string literal preprocessing token that contains the spelling of the preprocessing token sequence for the corresponding argument.
Each occurrence of white space between the argument's preprocessing tokens becomes a
single space character in the character string literal. White space before the first prepro-
UM004407-0104
Z8 User Manual
412
cessing token and after the last preprocessing token comprising the argument is deleted.
Otherwise, the original spelling of each preprocessing token in the argument is retained in
the character string literal.
This process requires special handling for producing the spelling of string literals and
character constants: a \ character is inserted before each " and \ character of a character
constant or string literal (including the delimiting " characters). The order of evaluation of
# operators is unspecified.
The ## Operator
Constraints
A ## preprocessing token does not occur at the beginning or at the end of a replacement
list for either form of macro definition.
Semantics
If, in the replacement list, a parameter is immediately preceded or followed by a ## preprocessing token, the parameter is replaced by the corresponding argument's preprocessing token sequence.
For both object-like and function-like macro invocations, before the replacement list is
reexamined for more macro names to replace, each instance of a ## preprocessing token in
the replacement list (not from an argument) is deleted and the preceding preprocessing
token is concatenated with the following preprocessing token. If the result is not a valid
preprocessing token, the behavior is undefined. The resulting token is available for further
macro replacement. The order of evaluation of ## operators is unspecified.
Rescanning and Further Replacement
After all parameters in the replacement list have been substituted, the resulting preprocessing token sequence is rescanned with the rest of the source file's preprocessing tokens for
more macro names to replace.
If the name of the macro being replaced is found during this scan of the replacement list
(not including the rest of the source file's preprocessing tokens), it is not replaced. Further,
if any nested replacements encounter the name of the macro being replaced, it is not
replaced. These unreplaced macro name preprocessing tokens are no longer available for
further replacement, even if they are later reexamined in contexts in which that macro
name preprocessing token is otherwise replaced.
The resulting completely macro-replaced preprocessing token sequence is not processed
as a preprocessing directive even if it resembles one.
UM004407-0104
Z8 User Manual
413
Scope of Macro Definitions
A macro definition is effective until a #undef directive is read or the end of the file is
reached.
# undef identifier new-line
deletes the macro definition of the specified identifier. The #undef directive is ignored if
the specified identifier is not currently defined as a macro name.
Examples
The simplest use of this facility is to define a ''manifest constant,'' as in
#define TABSIZE 100
int table[TABSIZE];
The following defines a function-like macro whose value is the maximum of its arguments. Advantages include the following:
•
•
working for any compatible types of the arguments
generating in-line code without the overhead of function calling
Disadvantages include the following:
•
•
evaluating one argument a second time (including side effects)
generating more code than a function if invoked several times
#define max(a, b) ((a) > (b) ? (a) : (b))
The parentheses ensure that the arguments and the resulting expression are bound properly.
To illustrate the rules for redefinition and reexamination, the following sequence
#define x 3
#define f(a) f(x * (a))
#undef x
#define x 2
#define g f
#define z z[0]
#define h g(~
#define m(a) a(w)
#define w 0,1
#define t(a) a
f(y+1) + f(f(z)) % t(t(g) (0) +t) (1);
g(x+(3,4)-w) | h 5) & m
(f)^m(m) ;
results in
UM004407-0104
Z8 User Manual
414
f(2 * (y+1)) + f(2 * (f(2 * (z[0])))) % f(2 * (0)) + t(1) ;
f(2 * (2+(3,4)-0,1)) | f(2 * (~ 5)) & f(2 * (0,1))^m(0,1) ;
To illustrate the rules for creating character string literals and concatenating tokens, the
following sequence
#define str(s) # s
#define xstr(s) str(s)
#define debug(s, t) printf(''x'' # s ''= %d, x'' # t ''= %s'', x ## s, x ## t)
#define INCFILE(n) vers ## n /* from previous #include example */
#define glue(a, b) a ## b
define # xglue(a, b) glue(a, b)
#define HIGHLOW ''hello''
#define LOW LOW '', world''
debug(1, 2) ;
fputs(str(strncmp(''abc \ 0d'', ''abc'', '\ 4') /* this goes away */
== 0) str(: @ \n), s) ;
#include xstr(INCFILE(2) .h)
glue(HIGH, LOW) ;
xglue(HIGH, LOW)
results in
printf(''x'' ''1'' ''= %d, x'' ''2'' ''= %s'', x1, x2) ;
fputs(''strncmp(<N>\''abc \ \0d \'', \''abc \'', '\ \4') == 0'' '': @\n'', s) ;
#include ''vers2.h'' (after macro replacement, before file access)
''hello'';
''hello'' '', world''
or after concatenation of the character string literals,
printf(''x1= %d, x2= %s'', x1, x2) ;
fputs(''strncmp(\''abc\ \0d \'', \''abc\'', '\ \4') == 0: @\n'', s) ;
#include ''vers2.h'' (after macro replacement, before file access)
''hello'';
''hello, world''
Space around the # and ## tokens in the macro definition is optional.
And finally, to demonstrate the redefinition rules, the following sequence is valid:
#define OBJ_LIKE (1-1)
#define OBJ_LIKE /* white space */ (1-1) /* other */
#define FTN_LIKE(a) ( a )
#define FTN_LIKE( a ) (
/* note the white space */ \
a /* other items on this line
*/ )
However, the following redefinitions are invalid:
#define
#define
#define
#define
UM004407-0104
OBJ_LIKE (0) /* different token sequence */
OBJ_LIKE (1 - 1) /* different white space */
FTN_LIKE(b) ( a ) /* different parameter usage */
FTN_LIKE(b) ( b ) /* different parameter spelling */
Z8 User Manual
415
LINE CONTROL
Constraints
The string literal, if present, is a character string literal.
Semantics
Lines of code, comment lines, and blank lines are numbered sequentially, starting with 1 at
the first line of the file.
# line
digit-sequence new-line
causes the compiler to behave as if the following sequence of source lines begins with a
source line that has a line number as specified by the digit sequence (interpreted as a decimal integer).
# line
digit-sequence string-literal new- line
sets the line number similarly and changes the presumed name of the source file to be the
characters contained within the character string literal.
# line
pp-tokens new-line
is permitted if it does not match one of the two previous forms. The preprocessing tokens
after # line on the directive are processed just as in normal text (each identifier currently
defined as a macro name is replaced by its replacement list of preprocessing tokens). After
the compiler makes all replacements, the directive that results matches one of the two previous forms and is then processed as appropriate.
ERROR DIRECTIVE
A #error preprocessing directive causes the compiler to produce a diagnostic message
that includes the specified sequence of tokens.
PRAGMA DIRECTIVE
The compiler ignores #pragma preprocessing directives.
UM004407-0104
Z8 User Manual
416
NULL DIRECTIVE
If there is no token between the # and the next new-line character, the directive has no
effect.
PREDEFINED MACRO NAMES
The compiler defines the following names.
__LINE__ The line number of the current source line (a decimal constant).
__FILE__
The presumed name of the source file (a string literal).
__DATE__ The date of translation of the source file (a character string literal of the form ''mm
dd yyyy''), where the names of the months are the same as those generated by the
asctime function, and the first character of the dd is a space character if the value
is less than 10.
__TIME__ The time of translation of the source file (a character string literal of the form
''hh:mm:ss'') as in the time generated by the asctime function).
__STDC__ The decimal constant 1.
The values of the predefined macros (except for __LINE__ and __FILE__) remain constant throughout the translation unit.
None of these macro names, nor the identifier defined, can be the subject of a #define
or a #undef preprocessing directive. All predefined macro names must begin with a leading underscore followed by an uppercase letter or a second underscore.
UM004407-0104
Z8 User Manual
417
C
Shortcut Keys
This appendix lists the shortcut keys for the Z8 developer’s environment. Shortcuts exist
for the File menu, Edit menu (page 417), Project menu (page 418), and Build menu
(page 418).
FILE MENU SHORTCUTS
These are the shortcuts for the options on the File menu.
Option
Shortcut
Description
New File
Ctrl+N
To create a new file in the Edit window.
Open File
Ctrl+O
To display the Open dialog box for you to find the appropriate file.
Save
Ctrl+S
To save the file.
Save All
Ctrl+L
To save all files in the project.
Print
Ctrl+P
To print a file.
EDIT MENU SHORTCUTS
These are the shortcuts for the options on the Edit menu.
Option
Shortcut
Description
Undo
Ctrl+Z
To undo the last command, action you performed.
Redo
Ctrl+Y
To redo the last command, action you performed.
Cut
Ctrl+X
To delete selected text from a file and put it on the clipboard.
Copy
Ctrl+C
To copy selected text from a file and put it on the clipboard.
Paste
Ctrl+V
To paste the current contents of the clipboard into a file.
Delete
Ctrl+D
To remove a file from the current project.
Go to Line Ctrl+G
To jump to a specified line in the current file.
Find
Ctrl+F
F3
To find a specific value in the designated file.
To repeat the previous search.
Replace
Ctrl+H
To replace a specific value to the designated file.
UM004407-0104
C Shortcut Keys
Z8 User Manual
418
PROJECT MENU SHORTCUTS
There is one shortcut for the options on the Project menu.
Option
Shortcut
Description
Settings
Alt+F7
To display the Project Settings dialog box.
BUILD MENU SHORTCUTS
These are the shortcuts for the options on the Build menu.
Option
Shortcut
Description
Build
F7
To build your file and/or project.
Stop Build Ctrl+Break To stop the build of your file and/or project.
These are the shortcuts for the selections on the Debug option (from the Build menu).
Option
Shortcut
Reset
Ctrl+Shift+F5 To reset the debugger.
Stop Debugging
Shift+F5
To stop debugging of your program.
Go
F5
To invoke the debugger (go into Debug mode).
Run to Cursor
Ctrl+F10
To make the debugger run to the line containing the cursor.
Break
Ctrl+F5
To break the program execution.
Step Into
F11
To execute the code one statement at a time.
Step Over
F10
To step to the next statement regardless of whether the current
statement is a call to another function.
Step Out
Shift+F11
To execute the remaining lines in the current function and
return to execute the next statement in the caller function.
Set Next
Instruction
Shift+F10
To set the next instruction at the current line.
UM004407-0104
Description
C Shortcut Keys
Z8 User Manual
419
Glossary
A
ABS. Absolute Value.
A/D. Analog-to-Digital—the conversion of an analog signal, such as a waveform, to a digital signal,
represented by binary data. See ADC.
ADC. Analog-to-Digital Converter—a circuit that converts an analog signal to a digital bit stream. See A/
D.
address space. The physical or logical area of the target system’s memory map. The memory map could
be physically partitioned into ROM to store code, and RAM for data. The memory can also be divided
logically to form separate areas for code and data storage.
ALU. See Arithmetic Logical Unit.
American National Standards Institute (ANSI). The U.S. standards organization that establishes
procedures for the development and coordination of voluntary American National Standards.
analog. From the word analogous, meaning similar to. The signal being transmitted can be represented in
a way similar to the original signal. For example, a telephone signal can be seen on an oscilloscope as a
sine wave similar to the voice signal being carried through the phone line.
analog signal. A signal that exhibits a continuous nature rather than a pulsed or discrete nature.
AND. A bitwise AND instruction.
ANSI. American National Standards Institute.
application program interface (API). A formalized set of software calls and routines that can be
referenced by an application program to access supporting network services.
architecture. Of a computer, the physical configuration, logical structure, formats, protocols, and
operational sequences for processing data, controlling the configuration, and controlling the operations.
Computer architecture may also include word lengths, instruction codes, and the interrelationships among
the main parts of a computer or group of computers.
Arithmetic Logical Unit (ALU). the element that can perform the basic data manipulations in the central
processor. Usually, the ALU can add, subtract, complement, negate, rotate, AND, and OR.
array. 1. An arrangement of elements in one or more dimensions. 2. In a programming language, an
aggregate that consists of data objects with identical attributes, each of which may be uniquely referenced
by subscription.
ASCII. Acronym for American Standard Code for Information Interchange. The standard code used for
information interchange among data processing systems, data communications systems, and associated
equipment in the United States.
UM004407-0104
Glossary
Z8 User Manual
420
ASM. Assembler File.
assembly. 1. The manufacturing process that converts circuits in wafer form into finished packaged parts.
2. A short term for assembly language.
B
baud. A unit of measure of transmission capacity. The speed at which a modem can transmit data. The
number of events or signal changes that occur in one second. Because one event can encode more than one
bit in high-speed digital communications, baud rate and bits per second are not always synonymous,
especially at speeds above 2400 bps.
baud rate. A unit of measure of the number of state changes (from 0 to 1 or 1 to 0) per second on an
asynchronous communications channel.
binary (b). A number system based on 2. A binary digit is a bit.
bit. binary digit—a digit of a binary system. It contains only two possible values: 0 or 1.
block diagram. A diagram of a system, a computer, or a device in which the principal parts are
represented by suitably annotated geometrical figures to show both the basic functions of the parts and
their functional relationships.
buffer. 1. In hardware, a device that restores logic drive signal levels to drive a bus or a large number of
inputs. In software, any memory structure allocated to the temporary storage of data. 2. A routine or
storage medium used to compensate for a difference in rate of flow of data, or time of occurrence of events,
when transferring data from one device to another.
bus. In electronics, a parallel interconnection of the internal units of a system that enables data transfer
and control information. One or more conductors or optical fibers that serve as a common connection for a
group of related devices.
byte (B). A sequence of adjacent bits (usually 8) considered as a unit. A collection of four sequential bits
of memory. Two sequential bytes (8 bits) comprise one word.
C
CALL. This command invokes a subroutine.
CCF. Clear Carry Flag.
character set. A finite set of different characters that is complete for a given purpose. A character set
might include punctuation marks or other symbols.
CIEF. Clear IE Flag.
clock. A specific cycle designed to time events, used to synchronize events in a system.
CLR. Clear.
CMOS. Complementary Metal Oxide Semiconductor. A type of integrated circuit used in processors and
for memory.
compile. 1. To translate a computer program expressed in a high-level language into a program expressed
in a lower level language, such as an intermediate language, assembly language, or a machine language. 2.
UM004407-0104
Glossary
Z8 User Manual
421
To prepare a machine language program from a computer program written in another programming
language by making use of the overall logic structure of the program or by generating more than one
computer instruction for each symbolic statement as well as performing the function of an assembler.
compiler. A computer program for compiling.
COPF. Clear Overflow Protection Flag.
CPU. Abbreviation for Central Processing Unit. 1. The portion of a computer that includes circuits
controlling the interpretation and execution of instructions. 2. The portion of a computer that executes
programmed instructions, performs arithmetic and logical operations on data, and controls input/output
functions.
D
debug. To detect, trace, and eliminate mistakes.
DI. Disable interrupt.
E
EI. Enable interrupt.
emulation. The process of duplicating the characteristics of one product or part using another medium.
For example, an In-Circuit Emulator (ICE) module duplicates the behavior of the chip it emulates, in the
circuit being tested.
emulator. An emulation device.
EOF. End of file—when all records in a file are processed, the computer encounters an end-of-file
condition.
EPROM. Erasable Programmable Read-Only Memory. An EPROM can be erased by exposure to
ultraviolet light.
EQ. A Boolean operator meaning Equal to.
escape sequence. A special escape command is entered as three plus symbols (+++). placing the
modem in command mode, and interrupting user data transmission. However, the escape sequence does
not terminate the data connection. Command mode allows the entering of commands while the connection
is maintained.
F
F. Falling Edge.
Fast Fourier Transform. An algorithm for computing the Fourier transform of a set of discrete data
values. Given a finite set of data points—for example, a periodic sampling taken from a real-world
signal—the FFT expresses the data in terms of its component frequencies. It also solves the essentially
identical inverse problem of reconstructing a signal from the frequency data.
FFT. See Fast Fourier Transform.
UM004407-0104
Glossary
Z8 User Manual
422
filter. A process for removing information content, such as high or low frequencies.
flag. In data transmission or processing, an indicator, such as a signal, symbol, character, or digit, used for
identification. A flag may be a byte, word, mark, group mark, or letter that signals the occurrence of some
condition or event, such as the end of a word, block, or message.
frequency. For a periodic function, the number of cycles or events per unit time.
G
graphical user interface (GUI). 1. A graphics-based user interface that enables users to select files,
programs or commands by pointing to pictorial representations (icons) on the screen, rather than by typing
long, complex commands from a command prompt. 2. The windows and incorporated text displayed on a
computer screen.
groups. Collections of logical address spaces typically used for convenience of locating a set of address
spaces.
GUI. See graphical user interface.
H
h. See hexadecimal.
hardware. The boards, wires, and devices that comprise the physical components of a system.
Hertz. Abbreviated Hz. A measurement of frequency in cycles per second. A hertz is one cycle per
second. A kilohertz (KHz) is one thousand cycles per second. A megahertz (MHz) is one million cycles per
second. A gigahertz (GHz) is a billion cycles per second.
hexadecimal. A base-16 number system. Hex values are often substituted for harder-to-read binary
numbers.
I
ICE. In-Circuit Emulator. A ZiLOG product that supports the application design process.
icon. A small screen image representing a specific element like a document, embedded and linked objects,
or a collection of programs gathered together in a group.
ID. Identifier.
IE. Interrupt Enable.
initialize. To establish start-up parameters, typically involving clearing all of some part of the device’s
memory space.
instruction. Command.
interface (I/F). 1. In a system, a shared boundary, that is, the boundary between two subsystems or two
devices. 2. A shared boundary between two functional units, defined by specific attributes, such as
functional characteristics, common physical interconnection characteristics, and signal characteristics. 3. A
point of communication between two or more processes, persons, or other physical entities.
UM004407-0104
Glossary
Z8 User Manual
423
interleaving. The transmission of pulses from two or more digital sources in time-division sequence over
a single path.
interrupt. A suspension of a process, such as the execution of a computer program, caused by an event
external to that process, and performed in such a way that the process can be resumed. The three types of
interrupts include: internal hardware, external hardware, and software.
I/O. Input/Output. In computers, the part of the system that deals with interfacing to external devices for
input or output, such as keyboards or printers.
IPR. Interrupt Priority Register.
J
JP. Jump.
K
K. Thousands. May indicate 1000 or 1024 to differentiate between decimal and binary values.
Abbreviation for the Latin root kilo.
kHz. See kilohertz.
kilohertz (kHz). A unit of frequency denoting one thousand (103) Hz.
L
LD. Load.
library. A file that contains a collection of object modules that were created by an assembler or directly by
a C compiler.
LSB. Least significant bit.
M
MAC. An acronym for Media Access Control, the method a computer uses to transmit or receive data
across a LAN.
Megahertz (MHz). A unit of frequency denoting one million (106) Hz.
memory. 1. All of the addressable storage space in a processing unit and other internal memory that is
used to execute instructions. 2. The volatile, main storage in computers.
MHz. See Megahertz; also Hertz.
MI. Minus.
MLD. Multiply and Load.
MPYA. Multiply and Add.
UM004407-0104
Glossary
Z8 User Manual
424
MPYS. Multiply and Subtract.
MSB. Most significant bit.
N
n. Number. This letter is used as place holder notation.
NC. No Connection.
NE. Not Equal.
NEG. Negate.
NMI. Nonmaskable interrupt.
NOP. An acronym for No Operation, an instruction whose sole function is to increment the program
counter, but that does not affect any changes to registers or memory.
O
Op Code. Operation Code, a quantity that is altered by a microprocessor’s instruction. Also abbreviated
OPC.
OR. Bitwise OR.
OV. Overflow.
P
PC. Program counter.
pipeline. The act of initiating a bus cycle while another bus cycle is in progress. Thus, the bus can have
multiple bus cycles pending at a time.
POP. Retrieve a value from the stack.
port. The point at which a communications circuit terminates at a network, serial, or parallel interface
card.
power. The rate of transfer or absorption of energy per unit time in a system.
push. To store a value in the stack.
R
RAM. Random-access memory. A memory that can be written to or read at random. The device is usually
volatile, which means the data is lost without power.
random-access memory (RAM). A read/write, nonsequential-access memory used for the storage of
instructions and data.
UM004407-0104
Glossary
Z8 User Manual
425
read-only memory (ROM). A type of memory in which data, under normal conditions, can only be read.
Nonvolatile computer memory that contains instructions that do not require change, such as permanent
parts of an operating system. A computer can read instructions from ROM, but cannot store new data in
ROM. Also called nonerasable storage.
register. A device, accessible to one or more input circuits, that accepts and stores data. A register is most
often used only as a device for temporary storage of data.
ROM. See read-only memory.
RR. Rotate Right.
S
SCF. Set C Flag.
SL. Shift Left.
SLL. Shift Left Logical.
SP. Stack Pointer.
SR. Shift Right.
SRA. Shift Right Arithmetic.
Static. Characteristic of random-access memory that enables it to operate without clocking signals.
SUB. Subtract.
T
tristate. A form of transistor-to-transistor logic in which output stages, or input and output stages, can
assume three states. Two are normal low-impedance 1 and 0 states; the third is a high-impedance state that
allows many tristate devices to time-share bus lines. This industry term is not trademarked, and is available
for ZiLOG use. Do not use 3-state or three-state.
U
ULT. Unsigned Less Than.
W
wait state. A clock cycle during which no instructions are executed because the processor is waiting for
data from memory.
word. Amount of data a processor can hold in its registers and process at one time.
write. To make a permanent or transient recording of data in a storage device or on a data medium.
UM004407-0104
Glossary
Z8 User Manual
426
X
X. 1. Indexed Address. 2. An undefined or indeterminate variable.
XOR. Bitwise exclusive OR.
Z
Z. 1. Zero. 2. Zero Flag.
ZDS. ZiLOG Developer Studio. ZiLOG’s program development environment for Microsoft Windows.
UM004407-0104
Glossary
Z8 User Manual
427
Index
Symbols
- (subtract) 333
"#" must be followed by an argument name 256
"##" cannot be first or last token in replacement
string 256
"else" not within #if and #endif directives 257
#define preprocessing directive 410, 411
#elif preprocessing directive 408
#else preprocessing directive 408
#endif preprocessing directive 408
#error preprocessing directive 415
#if !defined preprocessing directive 408
#if defined preprocessing directive 408
#if preprocessing directive 408
#ifdef preprocessing directive 408
#ifndef preprocessing directive 408
#include 94, 95, 170, 409
#pragma 415
using 243
#pragma alias 87, 243
#pragma asm 246, 253
#pragma cpu 243
#pragma globalcopy 243
#pragma globalcse 243
#pragma globaldeadvar 244
#pragma globalfold 244
#pragma intrinsics 244
#pragma jumpopt 244
#pragma localcopy 244
#pragma localcse 245
#pragma localfold 245
#pragma localopt 245
#pragma noalias 87, 243
#pragma nobss 244
#pragma noglobalcopy 243
#pragma noglobalcse 244
#pragma noglobaldeadvar 244
#pragma noglobalfold 244
#pragma nointrinsics 244
#pragma nojumpopt 244
UM004407-0104
#pragma nolocalcopy 244
#pragma nolocalcse 245
#pragma nolocalfold 245
#pragma nolocalopt 245
#pragma noopt 245
#pragma nooptlink 245
#pragma nopeephole 246
#pragma nopromote 88, 246
#pragma nosdiopt 246
#pragma nostkck 246
#pragma nostrict 246
#pragma optlink 245
#pragma optsize 245
#pragma optspeed 245
#pragma peephole 245
#pragma promote 88, 246
#pragma sdiopt 246
#pragma stkck 246
#pragma strict 246
#undef 413
$$ 293
& (and) 328
* (multiply) 332
*bsearch function 182
*calloc function 182
*gets function 180
*malloc function 182
*memchr function 184
*memcpy function 183
*memmove function 183
*memset function 184
*realloc function 182
*strcat function 183
*strchr function 184
*strcpy function 183
*strncat function 183
*strncpy function 183
*strpbrk function 184
*strrchr function 184
*strstr function 184
Z8 User Manual
428
*strtok function 184
+ (add) 328
.COMMENT directive 277
.FRAME directive, using 250
.hex file extension xxv, 5, 105
.lnk file extension 30
.lod file extension 311
.map file extension xxvi, 100, 316, 334, 335
.srec file extension xxvii, 5, 105
/ (divide) 330
<< (shift left) 332
<assert.h> header 172
<ctype.h> header 173
<errno.h> header 171
<float.h> header 175
<limits.h> header 174
<math.h> header 176
<outputfile>=<module list> command 311
<setjmp.h> header 178
<sio.h> header 184
<stdarg.h> header 179
<stddef.h> header 171
<stdio.h> header 180
<stdlib.h> header 180
<string.h> header 182
<Z8.h> header 185
>> (shift right) 333
?, script file command
for expressions 24
for variables 25
\ (backslash) for variable names 247
\a 349
\b 349
\f 349
\n 349
\r 349
\t 350
\v 350
^ (bitwise exclusive or) 333
_ (underscore) 170
for assembly routine names 248
_DEFFREQ 204
| (or) 332
~ (not) 333
UM004407-0104
A
\a 349
abs function 182, 187
Absolute segments 270, 283
definition 268, 309
locating 316
Absolute value, computing 187, 195, 209
acos function 177, 187
Activate Breakpoints check box 134
Add Directives button 102
add file, script file command 22
Add Files to Project dialog box 81, 82
Add Project Configuration dialog box 118
Adding breakpoints 160
Adding files to a project 9, 81
Additional Linker Directives dialog box 103
Additive operators 368
Address field 123, 125
Address operator 364
Address spaces
allocation order 325
definition 310
grouping 315
linking sequence 323
locating 316
moving 312
renaming 312
setting maximum size 322
setting ranges 324
Z8 268
Addresses
finding 146
viewing 146
Addressing modes in assembly 296
Aggregate objects, initialization 391
Aggregate types 345
Alias checking
disabling 243
enabling 243
Alias Checking check box 87
Alias, defined 243
ALIGN clause 283
ALIGN directive 277
Aligning data 250
Z8 User Manual
429
Allocating space 212
AND keyword 39
ANSI C language, described 337
ANSI C preprocessor commands 405
ANSI C-Compiler
command line options 46
configuring 5
configuring optimizer 89
data alignment 250
description 5
error messages 254
generating temporary variables 251
incompatible type errors 254
increasing code speed 245
lower execution times 250
making programs faster 252
making programs smaller 252
reducing code size 245
running from the command line 43
run-time library 170
sequence points 357
setup 84
speeding up 250
supported preprocessor commands 405
troubleshooting 250
writing C programs 169
ANSI Promotions check box 88
ANSI standards, sensitivity to 88
arc cosine, computing 187
arc sine, computing 188
arc tangent, computing 189
Argument
passing 248
substitution 411
variable 179
Arithmetic conversions 354
Arithmetic operators in assembly 274
Arithmetic types 345, 353
Arm Next Event check box 168
Arrays
declarators 386
definition 345
function 191
subscripting 360
UM004407-0104
Arrow (->), using 362
ASCII values, viewing 151
ASCIZ values, viewing 152
asctime function 416
asin function 177, 188
.asm file extension xxv, 5
asm statement 247
Assembler 267
adding null characters 274
addressing modes 296
arithmetic operators 274
binary numbers 276
Boolean operators 275
case sensitivity 97, 273
character constants 276
character strings 274
configuring 5
decimal numbers 275
description 5
directive compatibility 300
directives 277
error messages 303
expressions 274
floating-point numbers 273, 276
generating listing file (.lst) 270
generating object file 270
hexadecimal numbers 276
numeric representation 273
octal numbers 276
operator precedence 277
options 28
relational operators 275
reserved words 273
setup 96
syntax 296
Assembler tab 96
Assembly language
assigned function names 248
backslash 272
Z8 User Manual
430
binary numbers 276
blank lines 272
calling from C 248
case sensitivity 273
comments 272
data alignment 250
decimal numbers 275
directives 272, 277
embedding in C 193, 194, 227, 246, 247, 253
expressions 274
instructions 272
labels 272, 295
line continuation 272
line definition 272
line length 272
macro expansion 97
octal numbers 276
passing arguments 248
preserving registers 249
reserved words 273
return values 249
routine names 248
source line 272
structure 272
syntax 296
translating 5
assert function 172, 188
<assert.h> header 172
Assigned function names 248
Assignment operators 374
compound 375
simple 374
atan function 177, 189
atan2 function 177, 189
atof function 181, 189
UM004407-0104
atoi function 181, 190
atol function 181, 190
Automatic storage duration, defined 344
Automatically Reload Externally Modified Files
button 129
B
\b 349
backslash for variable names 247
Backslash, used in assembly 272
BASE OF 313, 328
batch, script file command 17, 22
Beginning a project 7
BFRACT directive 279
Binary numbers in assembly 276
Binary operator 367
Bitwise AND operator (&) 371
Bitwise exclusive OR operator (^) 371
Bitwise inclusive OR operator (|) 372
Bitwise shift operators 369
Black Check button 123
Blank Check button 125
BLKB directive 280
BLKL directive 280
BLKP directive 280
BLKW directive 280
Block 395
Blue dots 13, 57, 59, 60, 139, 160
Bookmarks
adding 64
example 65
inserting 64
setting 64
Boolean operators in assembly 275
bp, script file command 23
Branch Optimizations check box 92
Branch optimizations, definition 92
Break button 120, 140, 159
break statement 399
Break When Trace Buffer Is Full check box 167
Breakpoints 161
adding 14, 160
deleting 163
Z8 User Manual
431
disabling 162
enabling 162
finding 162
inserting 14
jumping to 162
making active 162
making inactive 162
moving to 162
removing 163
setting 14
viewing 161
Breakpoints dialog box 79, 161
*bsearch function 182
bsearch function 191
Build button 57
Build menu 112
Build 113
Compile 113
Configurations 117
Debug 113
Break 114
Connect to Target 114
Download Code 114
Go 114
Reset 114
Run to Cursor 114
Set Next Instruction 115
shortcuts 418
Step Into 114
Step Out 115
Step Over 115
Stop Debugging 114
Rebuild All 113
Set Active Configuration 115
shortcuts 418
Stop Build 113
Update All Dependencies 113
Build Output window 65
Build toolbar 56
build, script file command 23
Building a project 113
from the command line 43
Burn button 123, 125
UM004407-0104
C
C
additive operators 368
arithmetic types 353
assignment operators 374
bitwise shift operators 369
calling assembly from 248
cast operators 366
character sets 338
comments 353
conformance to ANSI standard 246
constant expressions 376
constants 346
conventions 338
conversions 353
data alignment 250
declarations 377
declarators 384
embedding assembly in 246
enumeration constants 348
equality operator 370
escape sequences 247, 248
expressions 357
external definitions 400
external object definitions 403
function calls 361
function definitions 401
identifiers 341
increasing code speed 245
initialization 101
integer constants 347
interrupt handler 252
keywords 340
language, described 337
lexical elements 339
macro expansion 94
missing code 254
multiplicative operators 367
operators 352
postfix operators 360
Z8 User Manual
432
preprocessor commands 405
preserving routines 249
primary expressions 359
punctuators 352
return values 249
speeding up 250
statements 393
string literals 351
trigraph sequences 338
type definitions 390
type equivalence 390
type names 389
type specifiers 379
unary operators 363
variables in embedded assembly 247
with embedded assembly 253
writing programs 169
.c file extension xxv, 5
C tab 84
Call frames
dynamic 70, 89
static 70, 88
Call Stack window 153
Call Stack Window button 61
Calling assembly from C 248
*calloc function 182
calloc function 191
cancel all, script file command 23
cancel bp, script file command 24
Cannot initialize object with "extern" storage class
265
Cascade the files 135
Case Sensitive check box 132
Case sensitivity
in assembler 97, 273
in linker 100
C-Compiler
configuring 5
data alignment 250
UM004407-0104
description 5
error messages 254
sensitivity to ANSI standards 88
setup 84
speeding up 250
supported preprocessor commands 405
troubleshooting 250
cd, script file command 24
ceil function 178, 192
CHANGE command 312, 334
Changing object size 222
char *gets 180
char *strcat 183
char *strchr 184
char *strcpy 183
char *strncat 183
char *strncpy 183
char *strpbrk 184
char *strrchr 184
char *strstr 184
char *strtok 184
CHAR_BIT 174
CHAR_MAX 174
CHAR_MIN 174
Character case mapping functions 173
Character constants
in assembly 276
in C 348
Character sets, used by compiler 338
Character string literal, definition 351
Character strings in assembly 274
Character testing functions 173
Character-handling functions 173
Clear button 130
Clock Frequency area 111
Z8 User Manual
433
Clock Speed field 110
Clock window 144, 145
Clock Window button 61
Code
increasing speed 245
reducing size 245
Code line indicators 139
code segment 269
COLOR command 313
Colors, selecting 132
Comma operator 375
Command field 58
Command line
building a project from 43
examples 28
running the assembler from 44
running the compiler from 43, 46
running the librarian from 51
running the linker from 44, 51
running ZDS II from 42
Command Output window 67
Command Processor
description 6
quick tour 17
running the event system from 36, 38
running trace from 40
Command Processor toolbar 58
running the event system from 36, 38
running trace from 40
Command script file
commands 19
example 18
writing 18
Commands
link control file 310
linker 310
running 17
Commands tab 128
Commands to Keep field 130
Comment 353
/* 353
// 353
in assembly language 272
Comment characters, defining 132
UM004407-0104
.COMMENT directive 277
Common initial sequence 362
Common subexpressions
global 92
local 91
Common Subexpressions check box 91, 92
Comparing characters 213, 233
Comparing strings 231, 232
Comparison functions 183
Compatibility of assembly directives 300
Compile/Assemble File button 56
Compiler
character sets supported 338
configuring 5
data alignment 250
description 5
determining identifier scope 342
error messages 254
options 29
preprocessor commands 405
sensitivity to ANSI standards 88
setup 84
speeding up 250
troubleshooting 250
using #pragma 243
Compiling a project 113
Compound statements 394
Computing string length 232
Concatenating strings 230, 232
Concatenation functions 183
Conditional assembly 289
Conditional assembly directives 290
IF 290
Z8 User Manual
434
IFDEF 291
IFMA 291, 293
IFSAME 291
Conditional inclusion 407
Conditional operator (?:) 373
Configurations
adding new 117
setting 115
Configure Emulator Driver button 111
Configure Emulator Driver dialog box 111
Configure New Project dialog box 9, 70
Connect to Target button 57
const 356, 380
Const Variable Placement area 87
Constant
definition 359
in C 346
UINT_MAX 365, 369
ULONG_MAX 365, 369
Constant expressions 376
Constant folding
global 93, 244
local 91, 245
Constant Folding check box 91, 93
continue statement 399
Conventions used for C language 338
Conventions used in manual xxiii
Conversions 353
arithmetic 354
default argument 361
with pointers 366
Converting letter case 239
Converting strings 235, 237
COPY BASE OF command 313
COPY BASE operator 329
Copy button 55
COPY command 313, 334
Copy propagation
global 93, 243
local 91, 244
Copy Propagation check box 91, 93
Copy segments 310
COPY TOP OF command 313
COPY TOP operator 330
UM004407-0104
Copying characters 213, 233
Copying functions 183
Copying strings 231
Copying values 214
cos function 177, 192
caution 170
cosh function 177, 193
cosine, calculating 192
CPU directive 278
CPU Family list box 69, 83
CPU list box 69, 83
CPU selection 15, 16, 84
Create New button 102
Creating a project 7
adding linker directives 102
initializing variables 102
<ctype.h> header 173
Custom button 101, 103
caution 101
Custom field 101, 103
Custom Link Control File dialog box 104
Customer service xxiv
Customer support xxiv
Customize dialog box 126
Commands tab 128, 129
Toolbars tab 126, 127
Cut button 55
D
Data alignment 250
Data directives in assembly 278
DB directive 281
DBL_DIG 175
DBL_MANT_DIG 175
DBL_MAX 175
DBL_MAX_10_EXP 175
DBL_MAX_EXP 175
DBL_MIN 175
DBL_MIN_10_EXP 175
DBL_MIN_EXP 175
DD directive 281
Dead variable removal, global 244
Deallocating space 199
Z8 User Manual
435
DEBUG command 314
Debug configuration 115
Debug Information check box 96
Debug Information list box
Code Generation category 87
General category 85
Debug information, generating 314, 323, 334
Debug mode
description 6
invoking 6, 114
quick tour 12
RUN 13, 138
selecting 108
setting up 12
STEP 13, 138
STOP 13, 138
switching to 137
Debug Output window 65, 139
Debug toolbar 58, 139
Debug windows 80
Debug Windows toolbar 60, 142
Debugger
description 6, 108, 137
invoking 6, 114
options 32
quick tour 12
setting up 12
status bar 13, 138
Debugger script file
commands 19
example 18
writing 18
Debugger tab 108
Options dialog box 133
Decimal numbers in assembly 275
Decimal numeric values 332
Decimal values, viewing 151
Declaration 377
Declarator 384
array 386
function 387
pointer 386
Default argument conversions 361
Default integral promotions 88
UM004407-0104
DEFINE 269, 282, 283, 315
#define preprocessing directive 410, 411
Defines field 98
Definitions
external 400
external object 403
function 401
tentative 403
Delete button 55
Deleting files from a project 10, 68
Developer’s environment
description 3
memory requirements 2
menus 67
quick tour 7
software installation 2
system requirements 2
tool description 3
toolbars 54
DF directive 281
DI 185, 193
Diagnostics function 188
Directives
# line 415
#define 410, 411
#elif 408
#else 408
#endif 408
#error 415
#if 408
#if !defined 408
#if defined 408
#ifdef 408
#ifndef 408
#include 409
#pragma 415
#undef 413
.COMMENT 277
ALIGN 277
BFRACT 279
BLKB 280
BLKL 280
BLKP 280
BLKW 280
Z8 User Manual
436
compatibility 300
CPU 278
data 278
DB 281
DD 281
DEFINE 269, 282, 283
definition 277
DF 281
DL 282
DS 284
DW 282
END 284
ENDMACRO 292
EQU 285
EXTERN 295
FRACT 279
IF 290
IFDEF 291
IFMA 291, 293
IFSAME 291
in assembly 272, 277
INCLUDE 285
LIST 286
MACDELIM 294
MACEXIT 294
MACRO 292
NEWPAGE 286
NOLIST 286
null 416
ORG 287
preprocessing 405
syntax 405
SCOPE 295
SEGMENT 269, 287
TITLE 288
UBFRACT 279
UFRACT 279
VECTOR 288
XDEF 288
XREF 289, 295
Disable All Breakpoints button 141
Disable All button 79, 162
Disable Breakpoint command 163
Disassemble the code 14
UM004407-0104
Disassembled Trace 156, 166
Disassembled trace 155
Disassembly window 14, 154, 155
Disassembly Window button 61
Display Errors/Warnings Only check box 97
Display Warnings check box 98
div function 182, 194
div_t 180
div_t div 182
Division by zero encountered 257
DL directive 282
do statement 397
double acos 177
double asin 177
double atan 177
double atan2 177
double atof 181
double cos 177
double cosh 177
double exp 178
double fabs 178
double floor 178
double fmod 178
double frexp 178
double ldexp 178
double log 178
double log10 178
double modf 178
double pow 178
double sin 177
double sinh 177
double sqrt 178
double strtod 181
double tan 177
double tanh 177
Download Code button 57, 59, 139
Driver
definition 12
selecting 6, 12
Driver list box 109, 110
DS directive 284
DW directive 282
Dynamic call frames 70, 89
Dynamic frames 70, 89
Z8 User Manual
437
Dynamic Frames button 88
E
Edit Breakpoints command 161
Edit menu 75
Breakpoints 79
Clear Trace 80
Copy 76
Cut 76
Delete 76
Event System 80
Find 76
Find in Files 77
Go to Line 76
Paste 76
Redo 76
Replace 78
shortcuts 417
Undo 75
Edit toolbar 56
Edit window 63
code line indicators 139
Editor tab, Options dialog box 130
EDOM 171, 176, 181
EI 185, 194
#elif preprocessing directive 408
#else preprocessing directive 408
Embedding assembly in C 193, 194, 227, 246, 253
C variables 247
Emulator
configuring 16, 163
quick tour 15
setting up 16, 163
supported xxiv
Enable All button 79, 162
Enable Breakpoint command 162
Enable Event System check box 120, 159, 167
Enable/Disable Breakpoint button 58, 141
END directive 284
End of file encountered before end of macro call
256
#endif preprocessing directive 408
UM004407-0104
ENDMACRO directive 292
End-of-file found before #endif directive 257
Enumerated types 345
Enumeration constants in C 348
Enumeration specifiers 383
EQU directive 285
Equality operator 370
ERANGE 171, 176, 181
ERF, definition 200
errno macro 171, 172
<errno.h> header 171
ERROR (001) 255
ERROR (002) 255
ERROR (003) 255
ERROR (004) 255
ERROR (005) 255
ERROR (006) 255
ERROR (007) 255
ERROR (008) 255
ERROR (009) 255
ERROR (010) 255
ERROR (011) 255
ERROR (012) 255
ERROR (013) 256
ERROR (014) 256
ERROR (015) 256
ERROR (016) 256
ERROR (017) 256
ERROR (018) 256
ERROR (019) 256
ERROR (020) 256
ERROR (021) 256
ERROR (022) 256
ERROR (023) 256
ERROR (024) 256
ERROR (025) 256
ERROR (026) 256
ERROR (027) 256
ERROR (028) 257
ERROR (029) 257
ERROR (030) 257
ERROR (031) 257
ERROR (032) 257
ERROR (033) 257
Z8 User Manual
438
ERROR (034) 257
ERROR (035) 257
ERROR (036) 257
ERROR (037) 257
ERROR (038) 257
ERROR (101) 257
ERROR (102) 257
ERROR (103) 257
ERROR (104) 258
ERROR (105) 258
ERROR (106) 258
ERROR (107) 258
ERROR (108) 258
ERROR (109) 258
ERROR (110) 258
ERROR (111) 258
ERROR (112) 258
ERROR (113) 258
ERROR (114) 258
ERROR (115) 258
ERROR (116) 259
ERROR (117) 259
ERROR (118) 259
ERROR (119) 259
ERROR (120) 259
ERROR (121) 259
ERROR (122) 259
ERROR (123) 259
ERROR (124) 259
ERROR (125) 259
ERROR (126) 259
ERROR (127) 259
ERROR (128) 260
ERROR (129) 260
ERROR (130) 260
ERROR (131) 260
ERROR (132) 260
ERROR (133) 260
ERROR (134) 260
ERROR (135) 260
ERROR (136) 260
ERROR (137) 260
ERROR (138) 260
ERROR (139) 260
UM004407-0104
ERROR (140) 260
ERROR (141) 261
ERROR (142) 261
ERROR (143) 261
ERROR (144) 261
ERROR (145) 261
ERROR (146) 261
ERROR (147) 261
ERROR (148) 261
ERROR (149) 261
ERROR (150) 261
ERROR (151) 261
ERROR (152) 261
ERROR (153) 261
ERROR (154) 262
ERROR (155) 262
ERROR (156) 262
ERROR (157) 262
ERROR (158) 262
ERROR (159) 262
ERROR (160) 262
ERROR (161) 262
ERROR (162) 262
ERROR (163) 262
ERROR (164) 262
ERROR (165) 262
ERROR (166) 262
ERROR (167) 263
ERROR (168) 263
ERROR (169) 263
ERROR (170) 263
ERROR (171) 263
ERROR (172) 263
ERROR (173) 263
ERROR (174) 263
ERROR (175) 263
ERROR (176) 263
ERROR (177) 263
ERROR (178) 263
ERROR (179) 264
ERROR (180) 264
ERROR (181) 264
ERROR (182) 264
ERROR (183) 264
Z8 User Manual
439
ERROR (184) 264
ERROR (185) 264
ERROR (186) 264
ERROR (187) 264
ERROR (188) 264
ERROR (189) 264
ERROR (190) 264
ERROR (191) 265
ERROR (192) 265
ERROR (193) 265
ERROR (194) 265
ERROR (195) 265
ERROR (196) 265
ERROR (197) 265
ERROR (198) 265
ERROR (199) 265
ERROR (200) 265
ERROR (201) 265
ERROR (303) 265
ERROR (308) 266
ERROR (309) 266
ERROR (310) 266
ERROR (312) 266
ERROR (313) 266
ERROR (400) 303
ERROR (401) 303
ERROR (402) 303
ERROR (403) 303
ERROR (404) 304
ERROR (405) 304
ERROR (406) 304
ERROR (407) 304
ERROR (408) 304
ERROR (409) 304
ERROR (410) 304
ERROR (411) 304
ERROR (412) 304
ERROR (413) 304
ERROR (414) 304
ERROR (415) 304
ERROR (416) 304
ERROR (417) 305
ERROR (418) 305
ERROR (419) 305
UM004407-0104
ERROR (420) 305
ERROR (421) 305
ERROR (422) 305
ERROR (423) 305
ERROR (424) 305
ERROR (425) 305
ERROR (426) 305
ERROR (427) 305
ERROR (428) 305
ERROR (429) 305
ERROR (430) 305
ERROR (431) 305
ERROR (432) 306
ERROR (433) 306
ERROR (434) 306
ERROR (435) 306
ERROR (436) 306
ERROR (437) 306
ERROR (438) 306
ERROR (439) 306
ERROR (442) 306
ERROR (444) 306
ERROR (445) 306
ERROR (446) 306
ERROR (447) 306
ERROR (448) 306
ERROR (450) 307
ERROR (451) 307
ERROR (452) 307
ERROR (453) 307
ERROR (461) 307
ERROR (462) 307
ERROR (464) 307
ERROR (470) 307
ERROR (475) 307
ERROR (476) 307
ERROR (480) 307
ERROR (481) 307
ERROR (482) 307
ERROR (483) 307
ERROR (490) 308
ERROR (99) 303
Error conditions 177
reporting 171
Z8 User Manual
440
Error directive 415
Error messages
ANSI C-Compiler 254
assembler 303
#error preprocessing directive 415
Escape sequences 349
EVENT keyword 39, 40
Event Position in Buffer button 120, 159
Event system
running from the Command Processor 36, 38
Executable Format list box 105
Executable format, for Linker 105
exit, script file command 25
exp function 178, 195
Expand Macros check box 97
Expand Macros on Error check box 94
exponential 178
Exponential functions 178, 195
Exporting project as make file 112
from the command line 43
Expression statement 395
Expressions
binary numbers 276
decimal numbers 275
definition 357
floating-point numbers 276
HIGH operator 275
in assembly 274
linker 327
LOW operator 275
octal numbers 276
order of evaluation 358
parenthesized 359
primary 359
EXTERN directive 295
External definitions 400
External linkage of identifiers 342
External object definitions 403
UM004407-0104
External references, resolving 315
Extra "#endif" found 257
F
\f 349
fabs function 178, 195
far keyword 71, 86
far_bss segment 269
far_data segment 269
File
adding 9, 81
deleting from a project 10
opening 10
reading 10
viewing 10
File extensions xxv
.asm xxv, 5
.c xxv, 5
.hex xxv, 5, 105
.lib xxv
.lis xxv, 94
.lnk xxv
.lod xxvi, 5, 105, 311
.lst xxvi, 94, 270
.mak xxvi
.map xxvi, 100, 316, 334, 335
.obj xxvi, 5, 270, 271
.pro xxvii, 8
.s xxvii
.src xxvii
.srec xxvii, 5, 105
.wsp xxvii, 72
File menu 67
Close File 69
Close Project 72
Exit 75
New File 68
New Project 69
Open File 68
Open Project 71
Print 73
Print Preview 73
Print Setup 75
Z8 User Manual
441
Recent Files 75
Recent Projects 75
Save 72
Save All 73
Save As 73
Save Project 72
shortcuts 417
File Name field 158, 166
File toolbar 55
File Type drop-down list box 131
File types xxv
Fill Memory dialog box 147
Find dialog box 76, 77
Find field 56
Find in Files 2 Output window 66
Find in Files button 56
Find in Files dialog box 77
Find in Files Output window 66
Finding characters 230, 234
Finding strings 235
Flags check box 168
FLAGS macro 185
<float.h> header 175
Floating types 345
converting to integral 354
Floating-point numbers in assembly 276
Floating-point operations, incorrect results 254
floor function 178, 196
FLT_DIG 175
FLT_MANT_DIG 175
FLT_MAX 175
FLT_MAX_10_EXP 175
FLT_MAX_EXP 175
FLT_MIN 175
FLT_MIN_10_EXP 175
FLT_MIN_EXP 175
FLT_RADIX 175
FLT_ROUND 176
fmod function 178, 196
Font dialog box 133
for statement 397
FORMAT command 315
fprintf function 197
conversion characters 198
UM004407-0104
flag characters 198
FRACT directive 279
.FRAME directive, using 250
Frames
dynamic 70, 89
static 70, 88
free function 182, 199
FREEMEM operator 330
frexp function 178, 200
Full expression 394
Function calls 361
Function declarators 387
Function definitions 401
Function designator, definition 355
Function prototype, definition 342
Function value locations 249
Functions 178
abs 187
acos 187
asctime 416
asin 188
assert 188
assigned names 248
atan 189
atan2 189
atof 189
atoi 190
atol 190
bsearch 191
calloc 191
ceil 192
character case mapping 173
character handling 173
character input 180
character output 180
character testing 173
comparison 183
concatenation 183
copying 183
cos 192
cosh 193
definition 345
detailed descriptions of 186
diagnostics 172
Z8 User Manual
442
div 194
ERF 226
error conditions 177
exp 195
fabs 195
floor 196
fmod 196
formatted input 180
formatted output 180
fprintf 197
free 199
frexp 200
GET_ERF 200
GET_REG 201
getch 202, 204
getchar 203
getche 202
gets 203
hyperbolic 177
init_uart 204
integer arithmetic 182
isalnum 205
isalpha 205
iscntrl 205
isdigit 206
isgraph 206
islower 206
isprint 207
ispunct 207
isspace 207
isupper 208
isxdigit 208
kbhit 208
labs 209
ldexp 209
ldiv 210
library 170
log 210
log10 211
logarithmic 178
longjmp 211
malloc 212
mathematical 177
memchr 212
UM004407-0104
memcmp 213
memcpy 213
memmove 213
memory management 181
memset 214
modf 214
multiplication 209
nearest integer 178
nonlocal jumps 179
nonstandard input 184
nonstandard output 184
pow 215
power 178
printf 215
pseudorandom sequence generation 181
putch 204, 219
putchar 220
puts 220
qsort 221
rand 221
realloc 222
scanf 222
search 182, 184
select_port 204
SET_ERF 226
setjmp 226
sin 227
sinh 228
sorting 182
sprintf 228
sqrt 229
srand 229
sscanf 229
strcat 230
strchr 230
strcmp 231
strcpy 231
strcspn 232
string conversion 181
strlen 232
strncat 232
strncmp 233
strncpy 233
strpbrk 234
Z8 User Manual
443
strrchr 234
strspn 235
strstr 235
strtod 235
strtok 236
strtol 237
tan 238
tanh 238
testing characters 205, 206, 207, 208
tolower 239
toupper 239
trigonometric 177
va_arg 239
va_end 240
va_start 241
vprintf 242
vsprintf 242
Z8 185
G
General tab
Project Settings dialog box 83
Generate Assembly Source (.src) check box 94
Generate Compiler Listing File (.lis) check box 94
Generate Debug Information check box 99
Generate Listing File (.lst) check box 94, 97
Generate Map File check box 100
Generate Object check box 97
Generate Warnings check box 99
GET keyword 42
GET_ERF 185, 200
GET_REG 185, 201
GET_RREG 185, 201
getch function 184, 202, 204
getchar function 180, 203
getche function 184, 202
*gets function 180
gets function 203
Global optimizations
definition 89
setup 92
Go button 57, 140
UM004407-0104
Go to Code button 79, 162
Go to Line Number dialog box 76
go, script file command 26
goto statement 398
GROUP command 315
Groups
definition 310
locating 316
renaming 312
setting ranges 324
H
Headers 171
architecture-specific functions 185
character handling 173
diagnostics 172
error reporting 171
floating point 175
general utilities 180
input 180
limits 174
location 171
mathematics 176
nonlocal jumps 178
nonstandard 171
nonstandard input functions 184
nonstandard output functions 184
output 180
reserved words 170
standard 170
standard definitions 171
string handling 182
variable arguments 179
HEADING command 316
Help menu 135
About 136
Help Topics 135
Online Registration 135
Hex code, size of 335
Z8 User Manual
444
Hex file
creating 335
size of 335
.hex file extension xxv, 5, 105
Hexadecimal Display check box 134
Hexadecimal numbers
in assembly 276
in linker expressions 332
viewing 151
HIGH operator 275
HIGHADDR operator 330
HUGE_VAL macro 176, 181
Hyperbolic cosine, computing 193
Hyperbolic functions 177
Hyperbolic sine, computing 228
Hyperbolic tangent, calculating 238
I
IDE, definition 54
Identifiers
C language 341
definition 341, 359
external linkage 342
internal linkage 343
linkages 342
name spaces 343
no linkage 343
scope 342
types 344
IEEE 695 format 5, 105, 315
#if !defined preprocessing directive 408
#if defined preprocessing directive 408
IF directive 290
#if preprocessing directive 408
if statement 91, 396
IFDEF directive 291
#ifdef preprocessing directive 408
IFMA directive 291, 293
#ifndef preprocessing directive 408
IFSAME directive 291
Ignore Case check box
Assembler tab 97
Linker tab 100
UM004407-0104
Illega l"#line" directive syntax 256
Illegal constant expression 257
Illegal macro name <name> 257
IMR macro 185
INCLUDE directive 285
#include directive 94, 170, 409
Include Path field 98
Included in Project button 101
caution 101
Incompatible type errors 254
Indirection operator 364
init_uart function 184, 204
Initialization 391
of aggregate objects 391
Initializer is not assignment compatible 265
Insert Breakpoint command 160
Insert Spaces button 131
Insert/Remove Breakpoint button 57, 141, 160
Inserting breakpoints 160
Installation 2
Instruction Simulator 6
configuring 109
quick tour 16
setting up 17
Instructions in assembly 272
int abs 182
int atoi 181
int getch 184
int getchar 180
int getche 184
int isalnum 173
int isalpha 173
int iscntrl 173
int isdigit 173
int isgraph 173
int islower 173
int isprint 173
int ispunct 173
int isspace 173
int isupper 173
int isxdigit 173
int kbhit 184
int memcmp function 183
int printf 180
Z8 User Manual
445
int putchar 180
int puts 180
int rand 181
int scanf 180
int setjmp 179
int sprintf 180
int sscanf 180
int strcmp 183
int strncmp 183
int tolower 173
int toupper 173
int vsprintf 180
INT_MAX 174
Integer arithmetic functions 182
Integer constants in C 347
Integers
signed 354
unsigned 354
Integral constant expression 376
Integral promotion, definition 353
Integral promotions
disabling 246
enabling 246
Integral types 345
Intel 16-bit Hex 315
Intel 32-bit 315
Intel Hex Records format 5, 315
Intel Hex16 format 105
Intel Hex32 format 105
Interleave Source and Assembly check box 94
Internal linkage of identifiers 343
Interrupt handler
arguments 253
creating in C 252
interrupt keyword 252
Interrupt-handling macros 185
Interrupts
running program with disabled 335
Intrinsic functions 244
Intrinsics, definition 89
IP Address field 111
IPR macro 186
IRQ macro 185
isalnum function 173, 205
UM004407-0104
isalpha function 173, 205
iscntrl function 173, 205
isdigit function 173, 206
isgraph function 173, 206
islower function 173, 206
isprint function 173, 207
ispunct function 173, 207
isspace function 173, 207
isupper function 173, 208
isxdigit function 173, 208
Iteration statements 397
J
jmp_buf 178
Jump Optimization check box 96
Jump optimizations 244
Jump statements 398
K
kbhit function 184, 208
Keep Tabs button 131
-keepasm 271
Keywords
AND 39
ANSI C language 340
EVENT 39, 40
GET 42
interrupt 252
SET 41
THEN 39
TRACE 41, 42
WHEN 39
L
Labeled statements 394
Labels
assigning to a space 295
exporting 295
importing 295
in assembly language 272, 295
local ($) 295
Z8 User Manual
446
local (?) 295
location checks 295
name 342
labs function 182, 209
Large memory model 71, 86
Large model 71, 86
Largest integer, computing 196
LDBL_DIG 176
LDBL_MANT_DIG 176
LDBL_MAX 176
LDBL_MAX_10_EXP 176
LDBL_MAX_EXP 176
LDBL_MIN 176
LDBL_MIN_10_EXP 176
LDBL_MIN_EXP 176
ldexp function 178, 209
ldiv function 182, 210
ldiv_t 180
ldiv_t ldiv 182
LENGTH operator 330
Lexical elements of C 339
.lib file extension xxv
Librarian
Librarian options 33
Libraries
defining 311
functions 186
object 309
Library file, creating xxv
Library functions 170, 186
<limits.h> header 174
Line continuation in assembly 272
Line control 415
Line number 415
Link control file 310
commands 310
creating 5
customizing 103
Link Control File area 102
Link map file
contents 316
creating 316, 323
generating xxvi, 100
UM004407-0104
Linker
case sensitivity 100
commands 310
configuring 6
creating link map file 316, 323
creating linking sequence 323
defining holes in memory 107
description 5
detailed description 309
expressions 327
file format 315
generating debug information 314, 323, 334
generating warnings 326
memory used 334
objects manipulated during linking 309
options 33
reducing execution times 334
search order 324
speeding up 334
suppressing warnings 323
troubleshooting 334
using directives to initialize variables 102
warning messages 102, 335
Linker commands
<outputfile>=<module list> 311
BASE OF 313
CHANGE 312
COLOR 313
COPY 313
COPY BASE OF 313
COPY TOP OF 313
DEBUG 314
DEFINE 315
FORMAT 315
GROUP 315
HEADING 316
LOCATE 316
MAP 316
MAXHEXLEN 322
MAXLENGTH 322
NOCOLOR 313, 322
NODEBUG 323
Z8 User Manual
447
NOMAP 316, 323
NOWARN 323
ORDER 323
RANGE 324
SEARCHPATH 324
SEQUENCE 325
SORT 325
SPLITTABLE 325
TOP OF 313
UNRESOLVED IS FATAL 326
WARN 326
WARNING IS FATAL 326
WARNOVERLAP 327
Linker directives
adding to new project 102
using to initialize variables 102
Linker expressions
- (subtract) 333
& (and) 328
* (multiply) 332
+ (add) 328
/ (divide) 330
<< (shift left) 332
| (or) 332
~ (not) 333
BASE OF 328
COPY BASE 329
COPY TOP 330
decimal numeric values 332
FREEMEM 330
hexadecimal numeric values 332
HIGHADDR 330
LENGTH 330
LOWADDR 331
TOP OF 333
Linker tab 98
Linker/locator warning messages 335
Linking sequence, creating 323
.lis file extension xxv, 94
.lst file extension 94
list bp, script file command 26
LIST directive 286
UM004407-0104
List Include Files in .lis check box 94
Listing file
assembly 94, 97, 270
compiler xxv, 94
.lnk file extension xxv, 30
Load Debug Information (Current Project) check
box 134
Load File button 122
Load from File dialog box 149
Load Last Project on Startup button 129
Load Memory Files check box 109
Local labels in assembly 295
Local macro label 293
Local optimizations 245
definition 89
setup 90
Locals window 152
Locals Window button 61
LOCATE command 316
Locator
configuring 6
description 5
detailed description 309
warning messages 335
.lod file extension xxvi, 5, 105, 311
log function 178, 210
log, script file command 26
log10 function 178, 211
Logarithm, computing 210, 211
Logarithmic functions 178
Logical AND operator (&&) 372
Logical OR operator (||) 373
long int atol 181
long int labs 182
long int strtol 181
long keyword 380
LONG_MAX 174
LONG_MIN 174
longjmp function 179, 211
Look In list box 158, 166
Loop body, definition 397
Loop Optimizations check box 92
Loop optimizations, definition 92
LOW operator 275
Z8 User Manual
448
LOWADDR operator 331
.lst file extension xxvi, 270
Lvalue 355
M
MACDELIM directive 294
MACEXIT directive 294
Macro Assebler
Macro Assembler 267
binary numbers 276
case sensitivity 97, 273
configuring 5
decimal numbers 275
description 5
directives 277
error messages 303
expressions 274
generating listing file (.lst) 270
generating object file 270
octal numbers 276
reserved words 273
setup 96
syntax 296
MACRO directive 292
Macros 292
characteristics of floating types 175
defining 292, 352
delimiter characters 294
delimiting arguments 294
UM004407-0104
DI 193
diagnostics 172
EI 194
error reporting 171
exiting 294
expanding 94, 97
general utility 181
interrupt handling 185
invocation 292
labels 293
mathematical 176
name 410
optional arguments 293
predefined name 416
__DATE__ 416
__FILE__ 416
__LINE__ 416
__STDC__ 416
__TIME__ 416
replacement 410
scope of definitions 413
SET_VECTOR 227
sizes of integral types 174
special function registers 185
standard definitions 172
string handling 182
Z8 family specific 193, 194, 227
_main has not been defined 104
.mak file extension xxvi
Make file, exporting 112
make, script file command 27
*malloc function 182
malloc function 212
Manage Configurations dialog box 117, 118
Manifest constant, defining 413
MAP command 316
.map file extension xxvi, 100, 316, 334, 335
Map file, generating 100
Mask field 120, 159, 168
<math.h> header 176
Mathematical functions 177
Mathematical macros 176
Max Errors field 86
MAXHEXLEN command 322
Z8 User Manual
449
MAXLENGTH command 322
MB_CUR_MAX macro 181
*memchr function 184
memchr function 212
memcmp function 183, 213
*memcpy function 183
memcpy function 213
*memmove function 183
memmove function 213
Memory
accessing 268
amount used by program 334
defining holes 107
defining locations 268
filling 147
loading to file 148
saving to file 147
Memory group 107
Memory management functions 181
Memory Model list box 86
Memory models
defining 86
large 71, 86
small 71, 86
Memory range
definition 107
syntax 107
Memory requirements 2
Memory window 145
changing values 145
filling memory 147
finding addresses 146
loading to file 148
saving to file 147
viewing addresses 146
Memory Window button 61
*memset function 184
memset function 214
Menu bar 67
Menus
Build 112
Edit 75
File 67
Help 135
UM004407-0104
Project 81
shortcuts 417
Tools 119
View 80
Windows 134
Messages Output window 66
Method area 123, 125
Models
large 71, 86
small 71, 86
modf function 178, 214
Modifiable lvalue 355
Modules
defining 311
definition 309
Motorola S-Records 5, 105, 315
Moving characters 213
Multiplicative operators 367
N
\n 349
Name list box 111
NDEBUG macro 172
near keyword 71, 86
near_bss segment 269
near_data segment 269
Nearest integer functions 178
New button 55
New project
adding files 9, 81
adding linker directives 102
configuring 10
creating 7, 69
debugging 12
deleting files 68
deleting files from 10
initialize variables 102
saving 12
setting up 10
New Project dialog box 8, 69
new project, script file command 27
New toolbar 127
New Toolbar dialog box 127
Z8 User Manual
450
NEWPAGE directive 286
No function prototype <name> in scope 265
NOCOLOR command 313, 322
NODEBUG command 323
NOLIST directive 286
NOMAP command 316, 323
NOWARN command 323
Null character (0) 338, 351
Null directive 416
NULL macro 172, 181, 182
Null pointer 356
Null pointer constant, definition 356
NULL, using 312, 314
NULL-terminated ASCII, viewing 152
Numbers
binary 276
decimal 275
floating point 276
hexadecimal 276
octal 276
O
.obj file extension xxvi, 5, 270, 271
Object code file 271
Object formats
for Linker 105
IEEE 695 5, 105
Intel Hex Records 5
Intel Hex16 105
Intel Hex32 105
Motorola S-Records 5, 105
OMF695 270, 271
Object libraries 309
Object Size group 106
Object sizes 106
Object/Library Modules field
General category 99
Input category 101
Objects, storage duration 344
Octal numbers in assembly 276
offsetof macro 172
OMF695 format 270, 271
Open button 55
UM004407-0104
Open dialog box 68
Open Project dialog box 72
open project, script file command 27
Operator precedence in assembly 277
Operators
- (subtract) 333
# 352, 411
## 352, 412
& (and) 328
* (multiply) 332
+ (add) 328
/ (divide) 330
<< (shift left) 332
[ ] 352
| (or) 332
~ (not) 333
additive 368
difference (binary -) 368
sum (binary +) 368
address of (unary &) 364
arithmetic 274
assignment 374
compound (+=) 375
compound (-=) 375
simple (=) 375
BASE OF 328
bitwise AND (&) 371
bitwise exclusive OR (^) 371
bitwise inclusive OR (|) 372
bitwise shift 369
Boolean 275
cast 366
comma (,) 375
conditional (?:) 352, 373
COPY BASE 329
COPY TOP 330
equality 370
equal to (==) 371
not equal to (!=) 371
FREEMEM 330
function call ( ( ) ) 352
HIGH 275
Z8 User Manual
451
HIGHADDR 330
indirection (unary *) 364, 368
LENGTH 330
list of 352
logical AND (&&) 372
logical OR (||) 373
LOW 275
LOWADDR 331
multiplicative 367
binary (*) 367
modulo (%) 367
quotient (/) 367
postfix 360
postfix decrement (--) 363
postfix increment (++) 363
precedence 277
prefix decrement (--) 364
prefix increment (++) 364
relational 275, 370
greater than (>) 370
greater than or equal to (>=) 370
less than (<) 370
less than or equal to (<=) 370
sizeof 365
TOP OF 333
unary 363
unary arithmetic
- 364
! 364
+ 364
~ 364
Optimizations
code size 245
code speed 245
disabling 245
jump 244
linkage calling conventions 245
local 245
peephole 245, 246
span-dependent instruction 246
Optimizations list box
General category 85
Optimizations category 90, 92
Optimize For buttons 91, 93, 252
UM004407-0104
Optimizer
configuration 89
configuring 5
global optimizations 92
local optimizations 90
setup 85
option, script file command 27
Options 27
assembler 28
compiler 29
debugger 32
general 33
librarian 33
linker 33
target 34
Debugger tab 133, 134
Editor tab 130, 131
General tab 129, 130
ORDER command 323, 328
ORG clause 283
ORG directive 287
OTP Checksum button 123, 125
OTP dialog box 122, 124
Output File field 105
Output File Name field 99
Output Files Directory field 84
Output Window button 56
P
P01M macro 186
P2M macro 186
P3M macro 186
Page Length field 97
Page Width field 97
Parenthesized expression, definition 359
Passing arguments 248
in dynamic frames 249
in static frames 248
Paste button 55
PC, definition 139
Peephole optimizations
definition 91
Z8 User Manual
452
disabling 246
enabling 245
Peephole Optimizations check box 91
Perform Re-List check box 100
Placing breakpoints 160
Pointer declarators 386
Pointers 356
Postfix (--) operator 363
Postfix (++) operator 363
Postfix decrement operator 363
Postfix increment operator 363
Postfix operators 360
pow function 178, 215
caution 170
Power functions 178
#pragma alias 243
#pragma asm 246, 253
#pragma bss 244
#pragma cpu 243
#pragma globalcopy 243
#pragma globalcse 243
#pragma globaldeadvar 244
#pragma globalfold 244
#pragma intrinsics 244
#pragma jumpopt 244
#pragma localcopy 244
#pragma localcse 245
#pragma localfold 245
#pragma localopt 245
#pragma noalias 243
#pragma noglobalcopy 243
#pragma noglobalcse 244
#pragma noglobaldeadvar 244
#pragma noglobalfold 244
#pragma nointrinsics 244
#pragma nojumpopt 244
#pragma nolocalcopy 244
#pragma nolocalcse 245
#pragma nolocalfold 245
#pragma nolocalopt 245
#pragma noopt 245
#pragma nooptlink 245
#pragma nopeephole 246
#pragma nopromote 246
UM004407-0104
#pragma nosdiopt 246
#pragma nostkck 246
#pragma nostrict 246
#pragma optlink 245
#pragma optsize 245
#pragma optspeed 245
#pragma peephole 245
#pragma preprocessing directive 415
#pragma promote 246
#pragma sdiopt 246
#pragma stkck 246
#pragma strict 246
PRE0 macro 186
PRE1 macro 186
Predefined macro names 416
Predefined segments 269
Prefix decrement operators 364
Prefix increment operators 364
Preprocessing
argument substitution 411
conditional inclusion 407
definition 407
directives 405
# line 415
#define 410, 411
#elif 408
#else 408
#endif 408
#error 415
#if 408
#if !defined 408
#if defined 408
#ifdef 408
#ifndef 408
#include 409
#pragma 415
#undef 413
syntax 405
error directive 415
line control 415
macro replacement 410
null directive 416
pragma directive 415
predefined macro names 416
Z8 User Manual
453
redefinition 413
reexamination 413
replacement 412
rescanning 412
source file inclusion 409
tokens
# 411
## 412
( 411
) 410, 411
Preprocessor commands 405
Preprocessor Definitions field 95
Primary expressions 359
Print button 55
Print Preview window 74
print, script file command 34
printf function 180, 215
caution 170
flag characters 218
.pro file extension xxvii, 8
Program Counter check box 120, 159, 168
Programmed Option Bits dialog box 126
Programmer’s editor 4
Programming Option Bits area 122, 124
Project
adding files 9, 81
building 113
compiling 113
configuring 10, 115
creating 7, 69
customized configuration 117
debugging 12
deleting files 10
deleting files from 68
exporting as make file 112
saving 12
setting up 10
Project file, creating 8
Project menu 81
Add Files 81
Export Makefile 112
Remove Selected File(s) 82
Settings 82
UM004407-0104
shortcuts 418
Assembler tab 96
C tab 84
Code Generation category 86, 87
General category 84, 85
Listing Files category 93
Optimizations category 89, 90
Preprocessor category 94, 95
Debugger tab 108
Emulator Driver 110
Simulator driver 109
General tab 83, 117
Linker tab 98
General category 98, 99
Input category 100, 101
Output category 104, 105
Target tab 106
Project Type list box 69
Project Workspace window 62
Prototypes 387
Pseudorandom button 123, 125
Pseudorandom sequence generation 181, 221, 229
ptrdiff_t 172
Public symbols, creating 315
Punctuator 352
( ) 352
[ ] 352
{ } 352
definition 352
putch function 184, 204, 219
putchar function 180, 220
puts function 180, 220
pwd, script file command 34
Q
qsort function 182, 221
Quick tour
Command Processor 17
debugger 12
developer’s environment 7
emulator 15
Z8 User Manual
454
quit, script file command 34
Quotient, computing 194, 210
R
\r 349
Ram Checksum button 122, 124
rand function 181, 221
RAND_MAX macro 181
RANGE command 324
Range error, generating 107
Raw trace 155, 157, 166
RDATA 268
RData
minimizing use of 108, 216
Read button 125
Read Options button 125
Reading input 222
Readme.txt, location of xxiii
*realloc function 182
realloc function 222
Rebuild All button 57
rebuild, script file command 35
rebuildall, script file command 35
Recursion
allowing 70, 89
preventing 70, 88
Recursive structure declaration 265
Red octagon 139, 161
Redefinition 413
Reentrancy 170
and dynamic frames 70, 89
and static frames 70, 88
reentrant keyword 70, 88
Reexamination 413
Register Address check box 168
Register Data check box 168
Register variable 253
Registers
changing values 143
preserving 249
variable 253
Registers window 143
Registers Window button 60
UM004407-0104
Relational operators 370
Relational operators in assembly 275
Release configuration 115
-relist 271
Relist target 100
Relocatable object module 5
Relocatable segments 268, 270, 309
Remainder, computing 196
remdouble ceil 178
Remove All Breakpoints button 58, 141
Remove All button 79, 163
Remove Breakpoint command 163
Remove button 79, 163
Replace dialog box 78
Replacement 412
Rescanning 412
Reserved words
ANSI C language 340
in assembly 273
in headers 170
Reset button 57, 140
Reset to Symbol ’main’ (Where Applicable) check
box 133
reset, script file command 35
return statement 399
Return values 249
Right-click menus
Call Stack window 153
Disassembly window 154
in Build Output window 65, 66, 67
in Edit window 63, 64
in Project Workspace window 62
Locals window 152
Programmed Option Bits dialog box 126
Trace window 155
Watch window 150, 151
ROM 268
rom_text segment 269
Routine names in assembly 248
RP macro 185
Run Command button 58
Run to Cursor button 140
Run-time library 104, 170
formatting 170
Z8 User Manual
455
functions 186
large routines 170
nonstandard headers 171
selecting 105
sio.c 217, 219, 220
standard headers 170
using functions 170
using headers 170
S
.s file extension xxvii
.src file extension xxvii
Sample program 7
Save All button 55
Save As dialog box 73, 112
Save button 55
Save Files Before Build button 129
Save Project Before Start of Debug Session check
box 133
Save to File dialog box 148
Save Trace Data File dialog box 158, 166
Save/Restore Project Workspace button 130
Saving a project 12
Scalar types 345
scanf function 180, 222
SCHAR_MAX 174
SCHAR_MIN 174
Scope
definition 342
of macro definitions 413
types of 342
SCOPE directive 295
Script file
commands 19
definition 18
example 18
writing 18
Search functions 184, 191
Searching functions 182
SEARCHPATH command 324
SEGMENT directive 269, 287
Segments 268, 309
UM004407-0104
absolute 268, 270, 283, 309
address space 283
alignment 269, 283
attaching code 269
attaching data 269
copy 310
copying 313
creating 269
defining 282
graph coloring 313, 322
locating 283, 316
moving 312
origin 270
predefined 269
relocatable 268, 270, 309
renaming 312
setting ranges 324
splitting 325
types 268
user defined 269
Select Active Configuration list box 56, 116
Select Configuration dialog box 116
Select Configurations dialog box 115
select_port function 204
Selection statements 396
SEQUENCE command 325, 328
Sequence points, list 357
Sequential button 123, 125
Serial Number field 125
Serial Number Size area 123, 125
SET keyword 41
Set Next Instruction button 141
SET_ERF 185, 226
SET_REG 185
SET_RREG macro 185
SET_VECTOR 185, 227, 252
setjmp function 179, 226
<setjmp.h> header 178
Setting breakpoints 160
SFR, definition 143, 185
Shortcut keys 417
Z8 User Manual
456
Show DataTips Pop-Up Information check box 133
Show Tabs check box 131
Show the Full Path in the Document Window’s Title Bar button 130
SHRT_MAX 174
SHRT_MIN 174
Signed integer types 344
signed integers 354
signed keyword 379
Simulator
configuring 109
selecting 6
setting up 17
Simulator Throttle 109
choosing speed of 17
recommended setting 109
sin function 177, 227
caution 170
Sine, computing 227
sinh function 177, 228
sio.c run-time library 217, 219, 220
<sio.h> header 184
size_t 172, 180, 182
size_t strcspn 184
size_t strlen 184
size_t strspn 184
sizeof operator 365
Small memory model 71, 86
Small model 71, 86
Small model, routines to avoid using 170
Smallest integer, computing 192
Software installation 2
SORT command 325
Sorting arrays 221
Sorting functions 182
Source file inclusion 409
Source line
contents 272
definition 272
labels 272, 295
SPACE clause 283
Span-dependent instruction optimization
disabling 246
enabling 246
UM004407-0104
Span-Dependent Instructions check box 92
Span-dependent instructions, definition 92
Special function register macros 185
Special function registers
changing values 144
location 143
Special Function Registers window 143, 144
Special Function Registers Window button 60
Specifiers, storage class 378
SPL macro 185
SPLITTABLE command 325
sprintf function 180, 228
sqrt function 178, 229
Square root, calculating 229
srand function 181, 229
.srec file extension xxvii, 5, 105
sscanf function 180, 229
Stack checking
disabling 246
enabling 246
Standard button 101
Standard field 95
Starting a project 7
Startup Model area 101
Startup module
customizing 101
standard 101
Statements 393
block 394
break 399
compound 394
continue 399
defined 393
do 397
expression 395
for 397
goto 398
if 396
iteration 397
jump 398
labeled 394
null 395
return 399
selection 396
Z8 User Manual
457
switch 396
while 397
Static call frames 70, 88
Static frames 70, 88
Static Frames button 88
Static library, creating 69
Static storage duration, defined 344
Status bar 13, 138
<stdarg.h> header 179
<stddef.h> header 171
<stdio.h> header 180
<stdlib.h> header 180
Step Into button 140
Step Out button 141
Step Over button 140
step, script file command 35
stepin, script file command 35
stepout, script file command 35
Stop Build button 57
Stop Command button 58
Stop Debugging button 140
stop, script file command 36
Storage duration for objects 344
Storage-class specifiers 378
*strcat function 183
strcat function 230
caution 170
*strchr function 184
strchr function 230
strcmp function 183, 231
*strcpy function 183
strcpy function 231
strcspn function 184, 232
Strict ANSI Conformance check box 88
String comparison 231, 232
String conversion functions 181, 189, 190, 235,
237
String literal 414, 415
character 351
definition 351, 359
in C 351
wide 351
<string.h> header 182
UM004407-0104
String-handling functions 182
strlen function 184, 232
*strncat function 183
strncat function 232
strncmp function 183, 233
*strncpy function 183
strncpy function 233
*strpbrk function 184
strpbrk function 234
*strrchr function 184
strrchr function 234
strspn function 184, 235
*strstr function 184
strstr function 235
strtod function 181, 235
*strtok function 184
strtok function 236
caution 170
strtol function 181, 237
Structure identifier 382
Structure type 362
Structure, definition 345
Subexpression elimination
global 243, 244, 245
local 245
Subscripting arrays 360
Supported emulators xxiv
Supported ZiLOG parts xxiv
Switch statement 396
Symbol Cross-Reference check box 100
Symbols window 153
Symbols Window button 61
Symbols, public 315
Syntax Coloring dialog box 132
System requirements 2
T
\t 350
T0 macro 186
T1 macro 186
Tab Size field 131
Tag, to identify structure or union 382
tan function 177, 238
Z8 User Manual
458
caution 170
Tangent, calculating 238
tanh function 177, 238
Target platform, selecting 108
Target tab 106
Target, defining 243
TCP Port field 111
Technical service xxiv
Technical support xxiv
Tentative definition 403
text segment 269
THEN keyword 39
Tile the files 135
TITLE directive 288
Tokens
categories 339
definition 339
tolower function 173, 239
Toolbars 54
Build 56
creating 127
Debug 58, 139
Debug Windows 60, 142
Edit 56
File 55
selecting 119
Toolbars tab 126
Tools menu 119
Customize 126
Options 129
OTP Programming 121
Trace and Event System 119
TOP OF 333
TOP OF command 313
toupper function 173, 239
Trace
disassembled 155, 156, 166
raw 155, 157, 166
running from the Command Processor 40
unfiltered 155, 156, 165
Trace and Event System dialog box 120, 159, 167
TRACE keyword 41, 42
Trace window 155
UM004407-0104
Trace Window button 61
Trigger In check box 120, 159
Trigonometric functions 177
Trigraph sequences 338
Troubleshooting
compiler 250
linker 334
Tutorials
debugger 12
developer’s environment 7
emulator 15
Type list box 90, 92
Type specifiers 379
type va_arg 179
typedef 390
Types
arithmetic 354
char 353
const 356
definitions 390
equivalence 390
int 353
names 389
null pointer 356
short int 353
structure 362
union 362
void 356
volatile 356
when to specify 389
U
UART1, using 204, 217, 219, 220
UBFRACT directive 279
UCHAR_MAX 174
UFRACT directive 279
UINT_MAX 174
UINT_MAX constant 365, 369
ULONG_MAX 174
ULONG_MAX constant 365, 369
Unary arithmetic operators 364
Z8 User Manual
459
Unary operators 363
#undef 413
Underscore 170
Unfiltered trace 155, 156, 165
Uninitialized static data, placement of 244
Union identifier 382
Union type 362
Union, definition 345
UNRESOLVED IS FATAL command 326
unsigned integers 354
unsigned keyword 379
Unsupported or poorly formed pragma 257
Use C Runtime Library button
Use C Runtime Library check box 105
Use Existing button 104
Use Existing field 104
Use Floating Point Library check box 86
Use Intrinsics check box 89
Use Register Variables check box 89
Use Syntax Coloring check box 132
User field 95
User-defined segments 269
USHRT_MAX 174
void *bsearch 182
void *calloc 182
void *malloc 182
void *memchr 184
void *memcpy 183
void *memmove 183
void *memset 184
void *realloc 182
void assert 172
void expression 356
void free 182
void init_uart 184
void longjmp 179
void putch 184
void qsort 182
void srand 181
void va_end 179
void va_start 179
volatile keyword 380
volatile type 356
Voltage list box 16, 111, 164
Voltage, choosing 16, 111, 164
vprintf function 242
vsprintf function 180, 242
V
W
\v 350
va_arg function 179, 239
va_end function 179, 240
va_list 179
va_start function 179, 241
Values, return 249
Variable arguments 179
Variables
register 253
temporary 251
VECTOR directive 288
Verigy button 126
View menu 80
Debug Windows 80
Output 81
Status Bar 81
Workspace 81
wait bp, script file command 36
wait, script file command 36
WARN command 326
WARNING (0) 335
WARNING (1) 335
WARNING (10) 336
WARNING (11) 336
WARNING (12) 336
WARNING (13) 336
WARNING (14) 336
WARNING (2) 335
WARNING (3) 335
WARNING (4) 335
WARNING (5) 336
WARNING (6) 336
WARNING (7) 336
WARNING (724) 104
UM004407-0104
Z8 User Manual
460
WARNING (8) 336
WARNING (9) 336
WARNING IS FATAL command 326
Warning messages
generating 326
linker/locator 335
suppressing 323
WARNOVERLAP command 327
Watch Compilation Process list box 85
Watch window 150
adding new variables 150
changing values 151
removing expressions 151
viewing ASCII values 151
viewing ASCIZ values 152
viewing decimal values 151
viewing hexadecimal values 151
viewing NULL-terminated ASCII 152
Watch Window button 61
wchar_t 172, 180
WHEN keyword 39
while statement 397
White octagon 139
White space, definition 340
Wide string literal, definition 351
Windows menu 134
Arrange Icons 135
Cascade 135
Close 135
Close All 135
New Window 135
Tile 135
Workspace Window button 56
Write Memory Files check box 110
Writing characters 219, 220
Writing output 197, 215, 228
Writing strings 220
.wsp file extension xxvii, 72
X
XDATA 268
XDEF directive 288
XREF directive 289, 295
UM004407-0104
Y
Yellow arrow 139
Yellow arrow on red octagon 139
Z
Z8 address spaces 268
Z8 developer’s environment
description 3
memory requirements 2
menus 67
quick tour 7
software installation 2
system requirements 2
tool description 3
toolbars 54
Z8 Emulator, setting up 16, 163
Z8 family specific macros 193, 194, 227
Z8 functions 185
Z8 IDE window, figure 54
Z8 Simulator, setting up 17
Z8 UART, initializing 204
<Z8.h> header 185
ZDS
definition xxiv
latest released version xxiv
ZDS II
ZiLOG parts, supported xxiv
ZiLOG web site URL xxiv
ZMASM compatibility 300

ZiLOG Developer Studio II-

Transcription

Similar documents

Casa Di Lusso Floor Plans / Elevation.indd

Change is the new norm

The control room of Deutsche Welle

Alejandro Press Kit

Studio, Boezemstraat in Rotterdam (Crooswijk)

PDF - Creative Sound Studios

December 00/January 01

Launch Control XL FL Studio Guide.indd

footnotes

Objective Strengths and Interests Experience Justin Petersen