Systems Manual

PC Development System for the
Sega Saturn
Psy-QTM from Psygnosis Ltd

PSY-Q TOOLS END USER LICENSE AGREEMENT BETWEEN THE “LICENSEE” AND SNSYSTEMS LTD AND PSYGNOSIS LTD “LICENSOR”
LICENSE: SN Systems Ltd (SN Systems) and Psygnosis Ltd (Psygnosis) hereby grant the Licensee a
non-transferable, non-exclusive right to use the Licensor’s software product known as Psy-Q Tools on any
single computer, provided that the Software is in use on only one computer at a time in return for the
license fee.
USE OF THE SYSTEM: You may use the Software and associated User Documentation on any single
computer fitted with Psy-Q Cartridge Hardware or Sony Hardware provided by Sony ComputerEntertainment. You may also copy the Software for archival purposes, provided that any copy contains all
the proprietary notices for the original Software.
You may not:Permit other individuals to use the Software except under the terms listed above;
Modify, translate, reverse engineer, decompile, disassemble (except to the extent applicable laws
specifically prohibit such restriction) or create derivative works based on the Software;
Copy the Software (except for backup purposes);Rent, lease, transfer or otherwise transfer rights to the Software;
Remove any proprietary notices or labels on the Software
TITLE: Title, ownership rights and intellectual property rights in and to the software shall remain in SN
Systems Ltd and Psygnosis Ltd.
COPYRIGHT: The Software is owned by the Licensor. The Licensee may not copy the manual (s) or
any other written materials accompanying the Software.
LIMITED WARRANTY: The Licensor warrants that the Software will perform substantially inaccordance with the accompanying manual (s) for a period of 30 days from the date of receipt PROVIDED
that the failure of the Software has not resulted from accident, abuse or misapplication.
CUSTOMER REMEDIES: The Licensor’s entire liability and the Licensee’s exclusive remedy shall at
the Licensor’s option, either be:(1) return of the license fee paid or(2) repair or replacement of the Software that does not meet the Licensor’s Limited Warranty outlined
above.
DISCLAIMER OF WARRANTY: THE SOFTWARE, ACCOMPANYING MANUAL (S) AND
ANY SUPPORT FROM SN SYSTEMS ARE PROVIDED “AS IS” AND WITHOUT ANY OTHER
EXPRESSED OR IMPLIED WARRANTY, INCLUDING BUT NOT LIMITED TO ANYIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULARPURPOSE. IN NO EVENT WILL SN SYSTEMS BE LIABLE FOR ANY DAMAGES,INCLUDING LOST PROFITS, LOST SAVINGS OR OTHER INCIDENTAL OR
CONSEQUENTIAL DAMAGES, EVEN IF SN SYSTEMS IS ADVISED OF THE POSSIBILITYOF SUCH DAMAGES OR FOR ANY CLAIM BY YOU OR ANY THIRD PARTY. THISDISCLAIMER OF WARRANTY CONSTITUTES AN ESSENTIAL PART OF THE
AGREEMENT.
SN Systems’ liability under this Agreement whether in contract, tort (including negligence) or otherwise
shall be limited to the Fee paid by the Licensee.
TERMINATION: This license will terminate automatically if you fail to comply with the limitations
described above or if after thirty (30) days written notice to SN Systems, you terminate it. On termination
you must destroy all copies of the Software, in whole or in part, in any form and cease all use of the
Software.

Please note that as the Psy-Q System software is constantly being updated, it is quite likelythat this manual may contain some inaccurate or out-of-date references and some features of
newly updated software may not be fully covered.
For this reason, if you experience any difficulties with this documentation, updates areavailable for download via the SN Systems BBS.
We recommend that you make regular use of this service and quickly take advantage of any
new features added to the Psy-Q System software, report or download ‘bug’ reports, gain
answers to questions that may be causing you difficulty and keep up-to-date on news
concerning the development industry.
If you experience any difficulties, please do not hesitate to contact our Technical Support at
SN Systems:
Tel:
Fax:

+44 (0)117 929 9733
+44 (0)117 929 9251

This device complies with part 15 of FCC Rules. Operation is subject to the following two
conditions:1) This device may not cause harmful interference2) This device must accept any interference that may be received, including interference that
may cause undesired operation.
 1996 SN Systems Software Ltd. All rights reserved.

PC SaturnContents
Introduction ...................................................................................................................................i
About Psy-Q ........................................................................................................................ ii
Psy-Q for Sega Saturn......................................................................................................... iii
Psy-Q Issue Information...................................................................................................... iv
Acknowledgements ............................................................................................................. vi
Psy-Q Installation ......................................................................................................................1-1
Installation Check List.......................................................................................................1-2
Installing the PC Interface .................................................................................................1-3
Installing the PC Software.................................................................................................1-7
PSYBIOS.COM................................................................................................................1-8
Installing the Target Interface..........................................................................................1-10
RUN.EXE - program downloader ...................................................................................1-14
Running with Brief ..........................................................................................................1-15
Installing the Windows ’95 Debugger..............................................................................1-18
The ASM68K and ASMSH Assemblers....................................................................................2-1
Assembler Command Line.................................................................................................2-2
Assembly Errors................................................................................................................2-5
The ASSH Assembler........................................................................................................2-6
Assembler Command Line.................................................................................................2-7
ASMSH Specific Features .................................................................................................2-8
Syntax of Assembler Statements................................................................................................3-1
Format of Statements ........................................................................................................3-2
Format of Names and Labels .............................................................................................3-3
Format of Constants..........................................................................................................3-4
Special Constants ..............................................................................................................3-5
Assembler Functions .........................................................................................................3-7
Special Functions ..............................................................................................................3-8
Assembler Operators .........................................................................................................3-9
RADIX ...........................................................................................................................3-11
ALIAS and DISABLE ....................................................................................................3-12
General Assembler Directives....................................................................................................4-1
Assignment Directives................................................................................................................4-2
EQU .................................................................................................................................4-3
SET ..................................................................................................................................4-4
EQUS ...............................................................................................................................4-5
EQUR...............................................................................................................................4-7
REG..................................................................................................................................4-8
RS.....................................................................................................................................4-9
RSSET............................................................................................................................4-10
RSRESET.......................................................................................................................4-11

Psy-Q Development System

Data Definition.........................................................................................................................4-12
DC..................................................................................................................................4-13
DCB ...............................................................................................................................4-14
DS ..................................................................................................................................4-15
HEX ...............................................................................................................................4-16
DATASIZE and DATA...................................................................................................4-17
IEEE32 and IEEE64 .......................................................................................................4-17
Controlling Program Execution ..............................................................................................4-18
ORG ...............................................................................................................................4-19
EVEN .............................................................................................................................4-20
CNOP .............................................................................................................................4-21
OBJ and OBJEND ..........................................................................................................4-22
Include Files .............................................................................................................................4-23
INCLUDE ......................................................................................................................4-24
INCBIN ..........................................................................................................................4-26
REF ................................................................................................................................4-27
DEF ................................................................................................................................4-28
Controlling Assembly...............................................................................................................4-29
END ...............................................................................................................................4-30
IF, ELSE, ELSEIF, ENDIF, ENDC ................................................................................4-30
CASE and ENDCASE ....................................................................................................4-32
REPT, ENDR .................................................................................................................4-33
WHILE, ENDW .............................................................................................................4-34
DO, UNTIL ....................................................................................................................4-35
Target-related Directives .........................................................................................................4-36
REGS .............................................................................................................................4-37
UNIT ..............................................................................................................................4-37
Macros........................................................................................................................................5-1
MACRO, ENDM, MEXIT................................................................................................5-2
Macro Parameters .............................................................................................................5-3
Special Parameters ............................................................................................................5-5
SHIFT, NARG..................................................................................................................5-7
MACROS .........................................................................................................................5-8
PUSHP, POPP ..................................................................................................................5-9
PURGE...........................................................................................................................5-10
TYPE..............................................................................................................................5-11
String Manipulation Functions .................................................................................................6-1
STRLEN...........................................................................................................................6-2
STRCMP ..........................................................................................................................6-3
INSTR ..............................................................................................................................6-4
SUBSTR...........................................................................................................................6-5

Psy-Q Development System

Local Labels ...............................................................................................................................7-1
Syntax and Scope..............................................................................................................7-2
MODULE and MODEND.................................................................................................7-4
LOCAL.............................................................................................................................7-5
Structuring the Program ...........................................................................................................8-1
GROUP ............................................................................................................................8-2
SECTION .........................................................................................................................8-4
PUSHS and POPS.............................................................................................................8-6
SECT and OFFSET ..........................................................................................................8-7
Options, Listings and Errors .....................................................................................................9-1
OPT ..................................................................................................................................9-2
Assembler Options ............................................................................................................9-3
Option Descriptions ..........................................................................................................9-4
PUSHO and POPO ...........................................................................................................9-6
LIST and NOLIST ............................................................................................................9-6
INFORM and FAIL...........................................................................................................9-8
XDEF, XREF and PUBLIC ..............................................................................................9-9
GLOBAL........................................................................................................................9-10
Adapter Firmware ...................................................................................................................10-1
The ‘C’ Library Functions ...............................................................................................10-2
The Pollhost Macro.........................................................................................................10-3
The PCinit Function ........................................................................................................10-4
The PCopen Function......................................................................................................10-5
The PClseek Function .....................................................................................................10-6
The PCread Function.......................................................................................................10-7
The PCwrite Function .....................................................................................................10-8
The PCclose Function .....................................................................................................10-9
The PCcreat Function....................................................................................................10-10
Assembly Language Facilities ........................................................................................10-11
Fileserver Functions ......................................................................................................10-12
The DBUGSAT Debugger ......................................................................................................11-1
Debugger Command Line................................................................................................11-2
Configuration Files..........................................................................................................11-4
Activity Windows............................................................................................................11-5
Additional Debugger Features .......................................................................................11-11
Using Debugger Windows.............................................................................................11-12
Keyboard Options .........................................................................................................11-15
Menu Options ...............................................................................................................11-20
Multiple Units ...............................................................................................................11-21
The Link Software ........................................................................................................11-22
Debugging Your Program Using Psy-Q.........................................................................11-23

Psy-Q Development System

The PSYLINK Linker..............................................................................................................12-1
PSYLINK Command Line...............................................................................................12-2
Linker Command Files ....................................................................................................12-4
GLOBAL........................................................................................................................12-5
XDEF, XREF and PUBLIC ............................................................................................12-6
The PSYLIB Librarian............................................................................................................13-1
PSYLIB Command Line..................................................................................................13-2
The CCSH Build Utility...........................................................................................................14-1
CCSH Command Line.....................................................................................................14-2
Source Files ....................................................................................................................14-4
The PSYMAKE Utility ............................................................................................................15-1
PSYMAKE Command Line.............................................................................................15-2
Contents of the Makefile .................................................................................................15-3
The PSY-Q DEBUGGER for WINDOWS 95.........................................................................16-1
Introduction ......................................................................................................................16-1
On-line Help Available For The Debugger .........................................................................16-3
Installing The Debugger ....................................................................................................16-4
Directory Structure............................................................................................................16-4
Obtaining Releases And Patches ........................................................................................16-5
Mailing Lists......................................................................................................................16-5
Beta Test Scheme..............................................................................................................16-6
Installing A Full Release ....................................................................................................16-7
Upgrading Your System ....................................................................................................16-8
Configuring Your Dex Boards...........................................................................................16-9
Configuring Your SCSI Card...........................................................................................16-10
Testing The Installation ...................................................................................................16-11
Launching The Debugger ................................................................................................16-13
The Psy-Q File Server .....................................................................................................16-14
Launching The File Server Without The Debugger ..........................................................16-16
Connecting The Target and Unit......................................................................................16-17
Psy-Q Projects.................................................................................................................16-19
Adding Files To The List Of Project Files ........................................................................16-20
Changing The Order Of Files In The File List ..................................................................16-21
Saving Your Project ........................................................................................................16-25
Re-opening A Project ......................................................................................................16-25
Saving A Project Under A New Name .............................................................................16-26
Restoring A Project .........................................................................................................16-26
Opening An Existing Project............................................................................................16-27
Manually Loading Files Into A Project.............................................................................16-28
The Psy-Q Debugger Productivity Features .....................................................................16-29
Psy-Q Views ...................................................................................................................16-31
Creating A Psy-Q View ...................................................................................................16-32
Cycling between Views....................................................................................................16-33
Saving Your Views .........................................................................................................16-34

Psy-Q Development System

Naming A View...............................................................................................................16-34
Changing Colour Schemes In Views ................................................................................16-35
Working With Panes........................................................................................................16-37
Splitting Panes.................................................................................................................16-37
Changing Pane Sizes........................................................................................................16-38
Deleting A Pane ..............................................................................................................16-38
Changing Fonts In Panes .................................................................................................16-39
Scrolling Within A Pane ..................................................................................................16-40
Selecting A Pane Type.....................................................................................................16-41
Memory Pane ..................................................................................................................16-42
Registers Pane.................................................................................................................16-44
Disassembly Pane ............................................................................................................16-45
Source Pane ....................................................................................................................16-47
Local Pane ......................................................................................................................16-49
Watch Pane .....................................................................................................................16-51
C Type Expressions In Watch Pane .................................................................................16-53
Assigning Variables .........................................................................................................16-54
Expanding Or Collapsing A Variable ...............................................................................16-55
Traversing An Index........................................................................................................16-56
Adding A Watch..............................................................................................................16-57
Additional Features When Entering Expressions ..............................................................16-58
Editing A Watch..............................................................................................................16-61
Deleting A Watch............................................................................................................16-62
Clearing All Watches .......................................................................................................16-62
Debugging Your Program ...............................................................................................16-63
Specifying The Continual Update Rate ............................................................................16-63
Setting Breakpoints .........................................................................................................16-64
Editing Breakpoints .........................................................................................................16-65
Stepping Into A Subroutine .............................................................................................16-67
Stepping Over A Subroutine............................................................................................16-68
Running To The Current Cursor Position.........................................................................16-69
Running Programs...........................................................................................................16-70
Stopping A Program Running..........................................................................................16-70
Moving The Program Counter.........................................................................................16-71
Moving The Caret To The PC .........................................................................................16-72
Moving To A Known Address Or Label ..........................................................................16-73
Expression Evaluation Features .......................................................................................16-75
Anchoring Panes To The PC............................................................................................16-77
Anchoring Memory Panes................................................................................................16-78
Identifying Changed Information .....................................................................................16-79
Closing The Debugger Without Saving Your Changes.....................................................16-79
Closing The Debugger And Saving Your Changes ...........................................................16-80
APPENDICES
Appendix A - Error Messages ..................................................................................................A-1
Assembler Error Messages ............................................................................................... A-2
Psylink Error Messages .................................................................................................. A-14
Psylib Error Messages .................................................................................................... A-19

Psy-Q Development System

Introduction
Psy-Q for the Sega Saturn is a fast PC based cross development system forproducing and testing mixed C and/or assembler programs for the Sega Saturngames console.

This version of Psy-Q features:• High performance Psy-Q SCSI interface card for host PC.
• Compact Saturn adapter cartridge, including extensive firmware stored in battery
backed SRAM.
• All the software you need:• Two RISC SH2 assemblers compatible with standard C compilers including
the popular Freeware Gnu-C.
• Fast 68000 assembler with numerous directives.
• High Speed Linker and Librarian, with extensive link-time options.
• Powerful Source Level Debugger, allowing the programmer to step, trace andset breakpoints directly in the source code.

Additional hardware required:• Host 386/486/Pentium PC with hard disk drive, at least 1 Megabyte of memory and
1 free 16 bit ISA slot.
• Sega Saturn. This can be either a ‘Small Programming Box’ or an ordinary
production Saturn from your local retailer.

Psy-Q Development System

About Psy-Q•

Psy-Q has been developed by Psygnosis and SN Systems, with many years ofexperience of development software and developers' needs. Psy-Q represents thenext generation of development systems, backed up by a commitment tocontinual enhancement, development and technical support.

•

Psy-Q includes 3 industry-standard Assemblers, a Linker and a Debugger. The
Assembler are extremely fast, and fully compatible with other populardevelopment systems. The Debugger offers an additional easy-to-use interface,with full support for mouse and pop-down menus, and works in any DOS text
screen resolution or Windows.

•

Psy-Q offers Source Level Debugging. This allows you to step, trace, set
breakpoints, etc. in your original C or Assembler source code. The system
automatically, and invisibly, handles multiple text files.

•

Psy-Q has 'C' compiler support built in. The Linker can link directly to standard
COFF object files, as produced by the popular Sierra C compiler and manyothers.

•Psy-Q provides a high-speed genuine SCSI parallel link between Host PC andtarget system, with a data transfer rate of over 1 Megabytes per second. The
system supports up to 7 connected target devices, and cable lengths of over 6
metres.

•Psy-Q's Assemblers and Linker make full use of extended or expanded memory,on PC compatibles with more than 640K of RAM.

Psy-Q Development SystemPsy-Q for Sega Saturn
The target interface is a very compact cartridge, that plugs into the cartridge slot of
any ordinary, unmodified Sega Saturn, or ‘Small Programming Box’.
Adapter firmware provides diagnostics and self-test facilities, and is stored onbattery-backed SRAM to allow for future firmware updates. Also included areassorted functions for useful run-time control of the development environment, as
well as extensive fileserver facilities, to allow the target to manipulate files on thehost PC.

Psy-Q Development SystemPsy-Q Issue Information
Psy-Q development systems are available for a variety of other platforms:
•
•
•
•
•
•

SEGA 32X
SONY Playstation
SEGA MegaDrive/Genesis
SEGA Mega-CD
Nintendo Super NES
Commodore Amiga 1200 and 600

Saturn Development Software
The software for the Saturn comes on three 3½“ HD disks. Disk 1 contains all the
Psy-Q System software, including the SH2 and 68000 Assemblers, Debugger etc.
Disk 2 contains an archive of the ‘Freeware’ SH GNU C compiler. Please note that a
number of Saturn specific Libraries are provided by Sega and can be found on the
Sega DTS CD and other Sega sources. Disk 3 contains the accompanying
Documentation for the compiler.
Contents of Disk 1:
PSYBIOS.COM
SAT2xx.CPE
ASMSH.EXE
ASSH.EXE
ASM68K.EXE
AS68K.EXE
RUN.EXEINITSERV.COM
DBUGSAT.EXE
CCSH.EXE
CC68K.EXE
KANJI.COMPSYLINK.EXE
PSYLIB.EXE
PSYMAKE.COM
BV.EXE
PSYQ.CB
PSYQ.CM
PSYQ.INI

TSR BIOS extensions for PC host for use with Psy-Q
Downloader v2.xx software for Adapter Interface
Hitachi SH series assembler for assembly programmers
Hitachi SH series assembler for C compiler output
68000 assembler for assembly programmers
68000 assembler for C compiler output
Standalone Executable/Binary downloader
Re-initialises PSYBIOS file server functions
SH2 and 68000 Debugger for Saturn system
Psy-Q Build Utility for SH2 C
Psy-Q Build Utility for 68000 C
Used by CCSH and CC68K when source contains kanji text
Psy-Q Linker
Psy-Q Librarian
Psy-Q Make Utility
Program to set VGA text screen to display more lines
Source for Brief Macro extensions
Compiled Brief Macro extensions
Path details for compiler installation

Psy-Q Development System

Contents of Disk 2:
GNUSH.ZIP
COPYING

ZIP Archive of GNU’s C Compiler‘GNU General Public Licence Terms and Conditions’Contents of Disk 3:
README.TX1
README.TXT
RUNME.BATCOPYINGCOPYING.LIB
GZIP.EXE
GCC.
CPP.
INFO.EXE

Text file on getting pre-processor version number
Text file on installing GNU Documentation
GNU Documentation installation batch file
‘GNU Public Licence Terms and Conditions’‘GNU General Public Licence Terms and Conditions’
GNU ZIP Decompressor program for GNUSH.ZIP file
GNU Documentation files
GNU Documentation files
GNU Info program

Psy-Q Development System

Acknowledgements
Psy-Q

The Psy-Q Development platform has been designed and produced by SN Systems
Limited, on behalf of Psygnosis Limited.
'Psy-Q' is a trademark of Psygnosis Ltd

DOS and Windows
Microsoft, MS, MS-DOS are registered trademarks of Microsoft Corporation;
Windows is a trademark of Microsoft Corporation.

IBM

IBM is a trademark of International Business Machines

Brief

Brief is a trademark of Borland International.

Sega

Sega Saturn, Sega 32X, Sega Genesis/MegaDrive, Sega-CD, Mega-CD, are all
trademarks of Sega Enterprises Ltd.

Psy-Q Development System

CHAPTER 1

Psy-Q Installation
The Psy-Q development system consists of the following physical components:•••••

PC Board
Target Interface
Connecting Cable
PC driver and Bios extensions
Psy-Q executable files

Installation is, therefore, a relatively straightforward procedure, and is described inthis chapter under the following headings:
•
•
•
•
•
•

Installation Check List
Installing the PC Interface
Installing the PC Software
PSYBIOSInstalling the Target Interface
Firmware Diagnostics

Psy-Q Development System

Installation Check List•

Check the configuration of the Psy-Q PC board and install in the host PC - seelater in this chapter for full installation details.

•

Check configuration of the Psy-Q Target Adapter and install in the target console
or machine - see later in this chapter for full installation details.

•

Connect the supplied cable from the PC to the target machine.

•

Load the PC board driver by typing, typically:
PSYBIOS /a308 /d7 /i15
See later in this chapter for full details of PSYBIOS.COM.

•

Copy the runtime Psy-Q executable files to a directory on your PC - see the Issue
List, in the Introduction, for the programs supplied with this version of Psy-Q.
Also edit the PATH variable in autoexec.bat.

•

Switch on the target console.

•

Run the program RUN.EXE, without parameters, to verify the link to the target
adapter - see chapter 2 for details of the RUN downloader program.

•

If RUN correctly identifies the target, the Psy-Q system is now ready to be used,
to assemble, download and debug programs.

Psy-Q Development System

Installing the PC Interface
The Psy-Q PC Interface board should be fitted in to an empty 16 bit slot in the hostPC. The host must be an IBM PC-AT or compatible, running under MSDOS 3.1 or
better.
If no 16 bit slot is available, the board will also fit into an 8 bit slot. However, thiscauses some degradation in speed.
Prior to fitting, the 3 banks of dip switches should be checked and configured as
required. It is likely, however, that the factory setting will suffice. They are described
below.

50 PinHigh
Density
SCSI
Connector

SCSI
ControllOn
Dip12345678

On
Dip
12345678

On
Dip
12345678

2 Active
Termination
Resistors

The Psy-Q PC Interface Board
CAUTION: This board is sensitive to static electricity; hold by the metal support
bracket when handling.

Psy-Q Development System

DIP SWITCHESThe PC card is configured by altering the three dip switch banks on the card. These
switches alter:DMA
IRQSCSI Termination PowerIO Address
SCSI ID for the card (normally on ID 7)

FUNCTION
DMA 7
DMA 6
DMA 5
IRQ 15
IRQ 12
IRQ 11
IRQ 10
IRQ 7
IRQ 5
Not UsedSCSI Termination PowerIO Address - A3 - A8
Card SCSI ID

DMA

DEFAULTOn, OnOff, Off
Off, Off
On
Off
Off
Off
Off
Off
Off, OffOn
Off, On, On, On, On, Off
On, On, On

DMA channels 5, 6, and 7 are available on the PC card. They are selected byswitching the pairs of dip switches adjacent to DMA request (DRQ) and DMA
acknowledge (DACK).
Both switches must be set to the same channel.
All DMA dip switches set to off will turn off DMA.
The default setting is 7.

Psy-Q Development System

IRQ

The PC card offers the following IRQ levels:
15, 12, 11, 10, 7, 5.
Select the required level by switching the adjacent dip switch.
You must only select one IRQ level.
The default setting is 15.

SCSI Termination PowerThe SCSI Termination Power switch determines whether SCSI termination is
supplied on the card.
The default setting is On. This must not be changed.

IO Address

The card offers a very large range of IO addresses from 20016 to 3f816 in incrementsof 8. The address is changed by altering the 6 dip switches labelled A3 to A8.
A8 is the most significant bit, and A3 is the least.
An address line is selected by switching it to Off.
The default setting is 308.

Psy-Q Development System

Some examples are shown in the following table:

240
2A0
300
308
310
318
380
388
390
3E0

A8
On
On
Off
Off
Off
Off
Off
Off
Off
Off

A7
On
Off
On
On
On
On
Off
Off
Off
Off

A6
Off
On
On
On
On
On
On
On
On
Off

A5
On
Off
On
On
On
On
On
On
On
Off

A4
On
On
On
On
Off
Off
On
On
Off
On

A3
On
On
On
Off
On
Off
On
Off
On
On

Note: The following addresses must not be used: 2F8 COM2,
378 Printer,
3F8 COM1,
3F0 Various.

SCSI ID

The last three switches alter the SCSI ID of the card.
The default setting is 7. Do not change this setting.

The default settings have been chosen so that the possibility of contention with otherinternal boards is minimised. Nevertheless, care should be taken that settings on
the Psy-Q board do not conflict with any other card in the system.

Psy-Q Development System

Installing the PC Software
The Psy-Q issue Disk 1 contains programs to perform the following functions:
•
•
•
•
•
•

Assembling
Linking
Debugging
PC Driving
Other target specific Bios Extensions
Windows accessories

Installing Development Software
To install the Psy-Q development programs onto the host PC, carry out the following
procedure:
•
•
•
•
•

create a new directory on the hard disk i.e. C:\PSYQ;
copy the contents of the issue disk to the new directory;
add the Psy-Q directory to the PATH variable in the AUTOEXEC.BAT;
add a line in the AUTOEXEC.BAT to automatically load PSYBIOS.COM;
add a line in the AUTOEXEC.BAT to create an environment variable"PSYQ_PATH", specifying the directory for Psy-Q files, e.g.:
set PSYQ_PATH = C:\PSYQ

Note: After you have made changes to your AUTOEXEC.BAT file you will need to
re-boot your PC to enable these changes to take effect.

Psy-Q Development System

PSYBIOS.COM
Description

PSYBIOS.COM is a TSR program, which acts as a driver for the Psy-Q interface
board, installed in the host PC.

SyntaxPSYBIOS[switches]

where each switch is preceded by a forward slash ( / ) and separated by spaces.
Switches/acard address/bbuffer size/cwindow n/dchannel/i

intnum/lfilename

/s

id

/8

Set card address:
200 - 3f8
Specify file transfer buffer size:
2 to 32 (in kilobytes)
Report all CD access to debugger message
window nSpecify DMA channel:
5, 6, 7; 0 = off
Specify IRQ number:
5, 7, 10, 11, 12, 15; 0 = off
Specify Fileserver log file; All fileserver
functions will be recorded in the specified
file.
Overide PC Interface SCSI ID jumper
setting: 0 to 7
Run in 8 bit slot mode

Psy-Q Development System

Remarks
•
•

•
•
•

ExamplesNormally, PSYBIOS.COM is loaded in the AUTOEXEC.BAT; it can safely beloaded high to free conventional memory.
If PSYBIOS is run again, with no options, the current image will be removed
from memory. This is useful if you wish to change the options without rebooting
the PC.
If the DMA number is not specified, the BIOS will work without DMA; however,it will be slower.
The BIOS can drive the interface in 8 bit mode; however, this is the slowest modeof operating the interface.
The buffer size option (/b) sets the size of the buffer used when the target
machine accesses files on PC. A larger buffer will increase the speed of theseaccesses; however, more PC memory will be consumed. The default is a 1 K
buffer.

PSYBIOS /a308 /d7 /i15
Start the driver using the typical settings of:Card address 308
DMA channel 7
Interrupt vector 15

Note: If you are using Windows ‘95, DO NOT install PSYBIOS from your
AUTOEXEC.BAT. Only install it from DOS.

Psy-Q Development System

Installing the Target Interface

WARNING: Never insert or remove the Psy-Q Target Interface when the target isswitched on. Doing so can permanently damage the Interface.

Installation
The Target Interface may be used with either in a retail Sega Saturn, or in a ‘Small
Programming Box’. Installation should be as follows:
In the case where you are using a retail Saturn, the Interface should be inserted into
the cartridge slot in exactly the same way as a game cartridge would be. The curved
side of the Interface displaying the Psy-Q logo should be facing the front of theSaturn.

Psy-Q Development SystemIf you are using a ‘Programming Box’, then you should install the Interface in asimilar manner, with the curved side facing the front of the unit.
The SCSI cable should be plugged into the Target Interface and also the host PC
SCSI Interface.
You are now ready to turn the target on and test the Target Interface.

Firmware Select
The ROM on the target interface only contains a simple downloader which is notsuitable for developing programs. Its only purpose is to install new versions of thedownloader software into the battery backed RAM of the interface.
When a new version of the downloader is installed, a checksum is calculated andstored for future reference. As the system starts up it will calculate the checksumfrom the installed downloader. If this new checksum matches the old checksum
stored, it will use the installed downloader. If the checksum does not match, if thedownloader has become corrupt for instance, then the simple downloader in the
ROM used. This will enable you to download the latest version of the downloader.
It is possible that the downloader stored in the battery backed RAM may becorrupted in such a way that the checksum matches the new calculated value. This
could cause the downloader to crash, preventing a new downloader being installedover it. In the unlikely event of this happening you should:
Power up your Sega Saturn.
Wait till after both the Sega Saturn and Segas logo have gone.
As the Psy-Q logo ‘mosaic effect’ starts, press RESET on the Saturn. This will flush
the corrupted downloader, allowing a new downloader to be installed.

Psy-Q Development System

Downloader Installation
If you have correctly connected the target interface to your Psy-Q PC SCSI card,
once you have installed the Psy-Q software you should be able to confirm
communication with the PC by executing the Psy-Q RUN program (with noparameters).
You must also have installed PSYBIOS correctly before you can execute the RUN
program. RUN will establish a connection to the target system and display the ID
code of the interface firmware. If no downloaders have been installed, a message
should appear something like:RUN.EXE Executable/Binary file downloader version 2.30
Copyright (c) 1992,93,94 S N Systems Ltd.
Target 0 is SH2 - SATMSTR1.01
No file to process
Before you start development, you will need to install the full downloader provided
on the Issue Diskette. This file is called SATxxx.cpe, where the xxx denotes thecurrent version number. This downloader is installed into the adapter by using the
RUN command.
For example:
RUN SAT201.CPE
The downloader will be kept battery backed in memory until another version of thedownloader is installed. To check everything worked properly, just execute RUN
again. It should report the correct version of the new downloader just installed.
Assuming this all works correctly then your installation is complete and you canproceed to experiment with Sega Saturn software development...

Psy-Q Development System

Firmware Diagnostics
The adapter always performs a few simple diagnostic checks at power up and if any
problems are detected it will print the result to the console’s screen.
If the console is reset (or switched on) with the joypad START button held downthen the adapter firmware will print to the screen to report on it's current
configuration and the results of some more extensive self-tests.

Psy-Q Development System

RUN.EXE - program downloader
Description

This program downloads runnable object code to the target machine.

SyntaxRUN [switches] file name [[switches] filename...]where switches are preceded by a minus sign (-).
Switches
-h
-t#
-u#
-w##

halt target - that is, download but do not run.
use target SCSI ID number # - always 0 for the Saturn.
use target unit number # (0 - Master SH2, 1 - Slave SH2, 2 - 68000).
retry for ## seconds if target does not respond.

Remarks•

If run is executed without any runtime parameters, the program will simply
attempt to communicate with the target adapter hardware. If successful, rundisplays the target identification; if the attempt fails, an appropriate error message
is displayed.

••

The file to be downloaded may contain:
an executable image, output by the development system, in .cpe format. Up to 8
cpe files may be specified;a raw binary image of a cartridge.

••

For an executable file, execution will begin as indicated in the source code; for abinary ROM image, execution will begin as if the target machine had been resetwith a cartridge in place.

•

Multiple executable files may be specified. However, only the last executableaddress will apply - specified files are read from left to right.

Psy-Q Development System

Running with Brief
Most programmers prefer to develop programs completely within a single, enabling
environment. Future versions of Psy-Q will provide a self-contained superstructurewith a built-in editor, tailored to the requirements of the assembly and debug subsystems. For the time being however, it is recommended that programmers seeking
such facilities should use Borland's Brief text editor, which is already supported by
Psy-Q.

Installation in Brief
In order to use Brief with Psy-Q, you will need to make a few changes to your
AUTOEXEC.BAT file after you have installed Brief:
Set the BCxxx environment variables. These variables take the file extension of asource file to tell Brief how to Assemble or Compile the file. For example:
set bc68k="asm68k /i /w /d /zd %%s,t0:,%%s,,"
set bcs="asmsh /i /w /d /zd %%s,t0:,%%s,,"
set bcc="ccsh -v -g -Xo$80010000 %%s.c -o%%s.cpe,%%s.sym" **These will Assemble .68k source file with ASM68k, .S source files with theASM68k assembler (see chapter 2), and Compile .C source files with CCSH (seeThe Build Utility chapter).
Set the BFLAGS environment variable, with -mPSYQ appended, to force the Psy-Q
macro file to be loaded on start-up. For example:
set bflags=-ai60Mk2u300p -mrestore -Dega -D101key -mPSQ

The variable may look different depending on how Brief was set up.
Finally, copy the file PSYQ.CM, containing macros, into the \BRIEF\MACROS
directory, or create it from source file PSYQ.CB;

Psy-Q Development System

Note: The standard Brief feature of using Alt-F10 to compile the current file as
instructed by the BCxxx environment variable still works as normal.
However, if you take the time to write a simple make file for each of yourprojects you will find the additional Psy-Q keystrokes much more convenientand powerful.
The Psy-Q brief macros:Ctrl-G
Ctrl-F
Ctrl-W
Ctrl-V
Ctrl-F9
Ctrl-F10
Alt-F9F9Goto label (locate definition of label under the cursor in loaded source
files)
Return from label (undo the above operation)
Write out all changed files
Evaluate expression under cursor using values from symbol file(s)Select make file for current project
Make program and enter debugger
Make program and start it runningEnter the Debugger

If you wish to change any of these key assignments then change to your
\BRIEF\MACROS directory and edit the file PSYQ.CB. Near the top of this file
you will see where the keys are assigned to the various functions and it should beeasy to change the key names and re-compile the macro by pressing Alt-F10.
Note: If you re-assign any of the Brief standard key assignments then you may lose
access to that original Brief function.
Ctrl-F9 allows you to select which make file you wish to use. By default, Psy-Q will
use the file in your current directory called MAKEFILE.MAK. If you do not wish
to use this file then use Ctrl-F9 to select the preferred make file.
Ctrl-F10, Alt-F9 and F9 work by calling the PSYMAKE program with a suitableparameter to select which operation to perform. Your Psy-Q disk includes a simple
make file called MAKEFILE.MAK as an example. If you edit this file you will seethat it defines how to do one of three operations:•••

Assemble and Run.
Assemble but don't Run.
Enter Debugger.

Psy-Q Development System

It should be easy for you to adapt this file to your needs. If you are doing one simple
assembly then all you will have to change is the name of the file that is assembled andadd any other command line options you require.
It does not matter which of your source files you are in when you press one of the
make/debug keys - the make file will specify the commands to the assembler anddebugger.

Psy-Q Development System

Installing the Windows ’95 Debugger
Installation Instructions
Note: You will need to know your Psy-Q SCSI card hardware resource settings tocomplete installation.
Note: The Compiler, Assemblers and Linkers must have been previously installed
within DOS.
Note: Do not install PSYBIOS.COM as this and RUN will not be needed with theWindows ‘95 Debugger.

Installing Automatically from Floppy Disk
Ensure there is at least 1.5mb free on your C drive and in addition, 2.5Mb free on thedrive where you will be installing your software.
1.
2.
3.
4.
5.
6.
7.
8.

Read setup.txt.
Run the program setup.exe by double-clicking on it using an explorer window.
Select ‘Yes’ to start the installation.
Setup will unzip and launch the Psy-Q for Windows ’95 setup program(pqsetup.exe). On-line help is available throughout the installation process.
If this is the first installation of the Debugger, confirm the specified licenceconditions.
Specify or confirm the directory in which you wish to install the Debugger.
Depending on the type of installation, specify the settings for the DE Board or
SCSI card.
After installation is complete, close pqsetup and setup will delete the temporary
files it installed on your hard disk.

Installing Manually
1. Unzip the file pp100zip into a temporary directory.
2. Run the program pqsetup.exe.
3. Select psxp_1.pqp and continue with the installation.

Psy-Q Development System

Additional Notes for Beta Testers•

If you are a beta tester of the Windows ’95 software, you do not need to install
this version of the Debugger. Instead, use the latest version available from SN
Systems. Contact John@snsys.com for more information.

•

If you have installed a beta version of the Debugger prior to Release 6 and wish
to install this version, you must run the program PsyClean.exe to remove unused
DLLs from your System directory.

Psy-Q Development System

CHAPTER 2

The ASM68K and ASMSH Assemblers
The ASM68K and ASMSH assemblers can assemble source code at over 1 million
lines per minute. Executable image or binary object code can be downloaded by the
Assembler itself, to run in the target machine immediately, or later, by the RUN
utility.
This chapter discusses how to run an assembly session, under the following headings:••

Assembler Command Line
Assembler and Target Errors

Psy-Q Development System

Assembler Command Line
During the normal development cycle, ASM68K and ASMSH may be:•••

run in stand alone mode
launched from an editing environment such as Brief - see later in this chapter
invoked as part of the Make utility - see The Psymake Utility chapter.

When the Assemblers are run independently, the command line takes the following
form; each component of the line is then described:

Syntax

ASM68K or ASMSH /switchlist source,object,symbols,listings,tempdataor
ASM68K or ASMSH @commandfile

If the first character on the command line is an @ sign, the string following it signifies
a Psy-Q command file containing a list of Assembler commands.

Switches

The assembly is controlled by inclusion of a set of switches, each preceded by aforward slash (/). The /o switch introduces a string of assembler options; these canalso be defined in the source code, using an OPT directive. Assembler options aredescribed in detail in chapter 9, the available switches are listed below:/cProduce list of code in unsuccessful conditions/d

Set Debug mode - if the object code is sent to the target
machine, do not start it.

/e
/g

n=x

Assigns the value x to the symbol n.
Non-global symbols will be output directly to the linker
object file.

Psy-Q Development System

/jpathname

Nominate a search path for INCLUDE files.

/kPermits the inclusion of pre-defined foreign conditionals,
such as IFND - see also MACROS, chapter 5.

/lOutput a file for the Psylink Linker.

/mExpand all macros encountered.

/ooptions

Specify Assembler options - see chapter 9 fora full description of the available options.

/p

Output pure binary object code, instead of an executable
image in .cpe format - see also RUN.EXE, chapter 2.

/ps

Output ASCII representation of binary file in Motorolas-record format/w

Output EQUATE statements to the Psylink file.

/z

Output line numbers to the Psylink file.

/zd

Generate source level Debug information.

Source

The file containing the source code; if an extension is not specified, the default is .68k
or .s. If this parameter is omitted, the Assembler outputs help in the form of a list ofswitches.

Object

The destination to which object code is written, either a file or target machine. If theobject code is to be sent directly to the target machine, specify a name of Tn:, wheren signifies the SCSI device number of the target . If this parameter is omitted, object
code will not be produced.

Symbols

The file to which symbol information is written, for use by the Debugger.

Listings

The file to contain listings generated by assembly.

Tempdata

This parameter nominates a file to be placed on the RAM disk for faster access. If
the name is omitted, the default is asm.tmp; note that the temporary file is always
deleted after assembly is complete.

Psy-Q Development System

Remarks•

If any of the above parameters are omitted, the dividing comma must still be
included on the command line, unless it follows the last parameter.

•

The Assembler run may be prematurely terminated by any of the following
methods:
Pressing Control-C
Pressing Control-Break (recognised more quickly because it does not requirea DOS operation to spot it)
Pressing Esc•

ExamplesThe Assembler checks for an environment variable called ASM68K or ASMSH.
This can contain default options, switches and file specifications, (in the form of acommand line), including terminating commas for unspecified parameters.
Defaults can be overridden in the runtime command line.

asmsh /zd /o ae+,w- scode,t0:,scode.sym
This command will initiate the assembly of the SH2 source code contained in a filecalled scode.s, with the following active options:
•
•
•
•
•
•

source level debug information to be generated
automatic even enabled
warning messages to be suppressed
the resultant object code to be transferred directly to the target machine, SCSI
device 0
symbol information to be output to a file called scode.sym
assembly listing to be suppressed

ASMSH @game.pcf
will recognise the preceding @ sign and take its command line from a Psy-Q
command file called GAME.PCF.

Psy-Q Development System

Assembly Errors
During the assembly process, errors may be generated as follows:
By the assembler itself, as it encounters error conditions in the source code.

Remarks
Appendix A gives a full list of Assembler error messages.
plus
Abort, Retry or Bus Reset

Psy-Q Development System

The ASSH Assembler
ASSH is not intended for assembling hand-written assembly code but ASMSH waswritten for this purpose and provides a number of powerful macro facilities forconvenient assembly programming. It is intended for developing assembly language
modules or complete projects in assembly language. For small amounts of assembly
language within your C program you can use the C inline function asm("") which
will pass its parameters directly into the output file for ASSH to assemble.
ASSH is an SH2 assembler and primarily used for processing the assembly syntax
produced by 'C' compilers; this assembler is constrained by C compiler output syntax
and so supports only those features it requires.

Psy-Q Development System

Assembler Command Line
SyntaxASMSH /switchlist source,object,symbols,listings,tempdata
or
ASMSH @commandfile

If the first character on the command line is an @ sign, the string following it signifies
a Psy-Q command file containing a list of Assembler commands.

Switches

See the ASM68K assembler (above) for a full list of the available command line
switches.

Note: The ASSH assembler is invoked primarily by the CCSH build utility, and will
not usually be called from the command line.

Psy-Q Development System

ASMSH Specific Features
For details of SH series assembler opcodes you should refer to the official Sega
documentation. These Psy-Q assemblers have pseudo-ops which are largely similar to
those of the Psy-Q 68000 assembler. All Data definition directives are the same as forthe 68000 (e.g. DC.size, DS.size, DCB.size, RS.size; where size is either .b, .w, or.l).
Additional features of ASMSH which are specific to this version include:• Default data size of an instruction is longword (32 bits). So beware:mov@r1+,r2; this instruction moves a longword into r2,; not a word.

• The SH does not have an op-code for immediate subtraction. However the
ASMSH assembler will allow you to use such an instruction and will instead
generate and immediate add with a negative quantity:sub#1,r1;generates opcode for add #-1,r1• Instructions that have only one legal size may have that size specified:add.l r1,r2• Immediate operands in the range 128 to 255 are allowed with a warning sincethese will be sign extended when loaded. e.g.
mov#200,r1;will give a warning.

This could be changed so that if you use .b or .w as the instruction size, then you
will only get an error if the operand doesn’t fit in the specified size.
• You can use the following pseudo-ops from the Hitachi assembler:.equ.org.align.arepeat.aendr.end• Instructions with PC relative operands check the alignment of their operands.
• The assembler checks that you do not put an illegal instruction in a delay slot.

Psy-Q Development System• The assembler correctly calculates the relative value when an instruction with a PC
relative operand is used in a delay slot, e.g.
bra fred
mova z1,r0
The offset in the MOVA instruction is not the same when it is in a delay slot.
This value cannot be calculated for indirect jumps through registers since theassembler does not know the destination of the jump. e.g. the following instruction
sequence will cause an error :jmp @r0mova z1,r0• The assembler allows the index address mode operands to appear in either order,
eg:and #15,@(r0,gbr)
and #15,@(gbr,r0)This also works for pc relative, with displacement, etc.
• Since the SH cpu cannot reference immediate data bigger than 1 byte, theassembler supports ‘literal pooling’ so you can access 16 and 32 bit constants.
This is usually indicated by the ‘=‘ prefix on a constant. If the data is greater than
1 byte it will be put in a literal table further on in the code. Otherwise it will beincorporated in the instruction as an immediate value. For compatibility, the prefix‘##’ can also be used to indicate a literal pool entry.
If you want to specify that the value must only be an immediate, then you can use
the ‘#’ prefix. If the data is larger than 1 byte, then an error will occur duringassembly.
Also for compatibility, if the #+ assembler option is specified in an OPT statementon the command line (with the /o command line switch), then the functions of the‘#’ and ‘##’ prefixes are reversed. So that a ‘#’ is used to signify a literal, and ‘##’is used to indicate an immediate value.
Literal constants are collected into a number of literal tables, and the assembler
generates PC relative load instructions to fetch the data from these tables. To
allow this you need to use the LITTAB pseudo-op to insert a literal pool atvarious points in your code. The best place for this is after an unconditional branchor jump.
Note that this table must come after the constant reference because the offset on
PC relative instructions are unsigned. e.g:-

Psy-Q Development Systemclearscr

modulemov.l=AutoFill,r1

mov.l=FBcont,r2

mov.l=$100,r8

mov.l=$ff,r4

mov.l
mov
mov.l

=$ff00/$100,r7
r8,r3=$8000,r5

mov
mov.w
mov
mov.w
mov
mov.w
add.l

r4,r0
r0,@(0,r1)
r3,r0
r0,@(2,r1)
r5,r0
r0,@(4,r1)
r8,r3

mov.w
tst
bf
dt
bf
rts
nop
littab@r2,r0
#2,r0
@1
r7
@0

;all these literals;be pooled;and this code will
;generate;pc rel load
instructions;to reference theliteral table

will

@0

@1

;Size
;Address;Data;literal table
will be built
heremodendYou can also use the keyword LITS as an alternative to
LITTAB.
• You can write most addressing modes in a 68000 style,eg:mov r0,@r1→
mov @(8,r1),r0 →mov r0,(r1)mov 8(r1),r0

etc.
• You can use MOVE as an alternative to MOV, e.g:mov.w r1,@r2•→

move.w r1,@r2

You can omit the ‘/’ in the compare instructions,e.g.:cmp/eq r1,r2→

cmpeq r1,r2

Psy-Q Development System

CHAPTER 3

Syntax of Assembler Statements
In order to control the running of an Assembler, source code traditionally contains a
number of additional statements and functions. These allow the programmer to direct
the flow and operation of the Assembler as each section of code is analysed andtranslated into a machine-readable format. Normally, the format of Assembler
statements will mirror the format of the host language, and the Assemblers follow thisconvention.
This chapter discusses the presentation and syntax of Assembler statements, as
follows:
•
•
•
•
•
•
•

Format of Statements
Format of Names and Labels
Constants
FunctionsOperators
RADIX
ALIAS and DISABLE

Psy-Q Development System

Format of Statements
Assembler statements are formatted as follows:
Name or Label

Directive

Operand

The following syntactical rules apply:•

Individual fields are delimited by spaces or tabs.

•

Overlong lines can be split by adding an ampersand (&); the next line is thentaken as a continuation.

•Lines with an equals (=) sign as the first character are considered to be the case
options of a CASE statement - see Flow Control, chapter 4.

•

Comment Lines:• comments normally follow the operand, and start with a semicolon (;).
• lines which consist of space or tab characters are treated as comments.
• a complete line containing characters other than space or tabs is treated as
a comment, if it starts with a semicolon or asterisk.

Psy-Q Development System

Format of Names and Labels
Names and Labels consist of standard alpha-numeric symbols, including upper-caseletters, lower-case letters and numeric digits:
A to Z, a to z, 0 to 9
In addition, the following characters can occur:
Colon (:)

Can be used at the end of a name or label when defined, but notwhen referenced.

Question Mark (?), Underscore (_), Dot (.)
These three characters are often used to improve the overallreadability
AT sign @Indicates the start of a local label - see chapter 7. Note
that, by using the Assembler option /ln, the local label symbol canbe changed to a character other than @.

The following usage rules apply throughout:•

Numeric digits and Question Marks must not be the first character of a name.

•Labels normally start in column 1. However, if they start elsewhere, there must be
no characters preceding the name, except space or tab, and the last charactermust be a colon.

•

If a problem in interpretation is caused by the inclusion of a non-alphanumericcharacter in a Name or Label, that character can be replaced by a backslash, orthe entire Name or Label surrounded by brackets.

Psy-Q Development System

Format of Constants
The Assemblers support the following constant types:
Character Constants
A character string enclosed in quote marks is a character constant and is evaluated as
its ASCII value. Character constants may contain up to 4 characters, to give a 32 bit
value. Thus:
"A"
= 65
"AB"
= (65*256)+ 66"ABC" = (65*65536)+ (66*256) + 67
"ABCD" = (65*16777216)+ (66*65536) + (67*256) + 68

= 65
= 16706= 4276803= 1094861636

Integer Constants
Integer constants are normally evaluated as decimal, the default base, unless one of
the following pertains:•

the RADIX directive changes the base - see chapter 3.

•$, as the first character of an integer, signifies a Hex number; % signifies a Binary
number.

•If a character is preceded by a backslash and up arrow (\^), the corresponding
control character is substituted.

•

The AN Assembler option allows numbers to be defined as Intel and Zilog
integers. That is, the number must start with a numeric character and end with
one of:
D for Decimal; H for Hexadecimal; B for Binary

Psy-Q Development System

Special Constants
The following pre-defined constants are available in the Assemblers.

Remarks_year_month_day_weekday_hours_minutes_seconds

As a two digit number, e.g. 95
1 = January; 12 = December
1 = 1st day of month0 = Sunday; 6 = Saturday
00 - 2300 - 59
00 - 59*@

Contains the current value of the Location Counter.
Contains the actual PC value at which the current value will be
stored - see below.

nargContains the number of parameters in the current macro argument see chapter 5 for further details.

__rsContains the current value of RS Counter - see chapter 4 forfurther details.

_filenameA pre-defined string containing the name of the primary fileundergoing assembly.

Time and Date Constants:
Time and Date constants are set to the start of assembly; they are not updated during
the assembly process.

Example

RunTimedc.b "\#_hours:\#_minutes:&\#_seconds"

this expands to the form hh:mm:ss, as follows
RunTimeNotedc.b "21:08:49"

This example uses the special macro parameter, \#, which is described in chapter 5.

Psy-Q Development System

Location Counter constants:
The current value of the program pointer can be used as a constant. To substitute thevalue of the location counter at the current position, an asterisk (*) is used:
Firstbss

sectionequ

Bss,g_bss*

Since * gives the address of the start of the line,
org
dc.l

$100
*,*,*

defines $100 three times.
An @, when used on its own as a constant, substitutes the value of the location
counter, pointing to an address at which the current value will be stored.
org
dc.l

$100
@,@,@

defines $100,$104,$108.

Psy-Q Development System

Assembler Functions
The Assemblers offer many functions to ease the programmer's task. These are listed
below, together with the page number for a more detailed explanation of their usage.
In addition, there is a group of specialised functions, which are described on thefollowing pages.

Name

ActionPagedef(a)
ref(a)

Returns true if a has been defined
Returns true if a has been referenced

4-28
4-27

type(a)Returns the data type of a5-11

sqrt(a)Returns the square root of astrlen(text)
strcmp(texta,textb)
instr([start,]txa,txb)

Returns the length of string in characters
Returns true if strings match
Locate substring a in string b

6-2
6-3
6-4

sect(a)offset(a)sectoff(a)group(a)groupoff(a)Returns the base address of section a
Returns the offset into section a
Equivalent to offset
Returns the base address of group a
Returns the offset into group a

8-7
8-7
8-7
8-2
8-2

Psy-Q Development System

Special Functions
filesize("filename")
Returns the length of a specified file, or -1 if it does not exist.
groupsize(X) Returns the current (not final) size of group X.
grouporg(X) returns the ORG address of group X or the group in which X is defined if X is asymbol or section name.
groupend(X) Returns the end address of group X.
sectend(X)Returns the end address of section X.

sectsize(X)Returns the current (not final) size of section X.

alignment(X) Gives the alignment of previously defined symbol X. This value depends upon thebase alignment of the section in which X is defined, as follows:
Word aligned - value in range 0 -3
Halford aligned- value in range 0 -1
Byte aligned - value always 0

Psy-Q Development System

Assembler Operators
The Assemblers make use of the following expression operators:
Symbol

Type

Usage

Action()+-Primary
Unary
Unary

(a)
+a
-a

Brackets of Parenthesis
a is positivea is negative (see Note1)

=
+
*
/
%

BinaryBinaryBinaryBinaryBinaryBinary

a=b
a+b
a-b
a*b
a/b
a%b

Assign or equate b to a
Increment a by b
Decrement a by b
Multiply a by b
Divide a by b, giving the quotient
Divide a by b, giving the modulus<<>>

BinaryBinarya<<ba>>bShift a to the left, b times
Shift a to the right, b times

~
&
^
!
|

Unary
BinaryBinaryBinaryBinary

~a
a&b
a^b
a!b
a|b

Logical compliment or NOT a
a is logically ANDed by b
a is exclusively ORed by b
a is inclusively ORed by b
Acts the same as a!b

<>
<
>
<=
>=

BinaryBinaryBinaryBinaryBinary

a<>b
a<b
a>b
a<=b
a>=b

a is unequal to b
a is less than b
a is greater than b
a is less than or equals b
a is greater than or equals b

Note1

Since the Assemblers will evaluate 32-bit expressions, the negation bit is
Bit 31. Therefore, $FFFFFF and $FFFFFFF are positive hex numbers; $FFFFFFFF isa negative number

Note2

If a comparison evaluates as true, the result is returned as -1; if it evaluates as
false, the result is returned as 0.

Psy-Q Development System

Hierarchy of Operators
Expressions in the Assemblers are evaluated using the following precedence rules:•

Parentheses form the primary level of hierarchy and force precedence - theircontents are performed first;
Without the aid of parentheses, operators are performed in the order dictated by
the hierarchy table;
Operators with similar precedence are performed in the direction of theirassociativity - normally, from left to right, except unary operators.

••

Operator()+ , -, ~<<, >>&, !, ^*, /, %+, >, <, <=, >==, <>Direction

←
→
→
→
→
→
→
→

Description
Primary
Unary
Shift
LogicalMultiplicative
Additive
Relational
Equality

Psy-Q Development System

11

RADIX
Description

The Assemblers default to a base of 10 for integers. This may be changed bypreceding individual numbers with the characters % or $, to change the base for that
integer to binary or hex. Alternatively, the RADIX directive can be used to change
the default base.

SyntaxRADIX

newbaseRemarks

Examples•Acceptable values for the new base are in the range of 2 to 16.

•

Whatever the current default, the operand of the RADIX directive is evaluated toa decimal base.

•

The AN assembler option (see chapter 9) will not be put into effect if the default
RADIX is greater than 10, since the signifiers B and D are used as digits inhexadecimal notation.

radix

8

sets the default base to OCTAL.

Psy-Q Development System

ALIAS and DISABLE
Description

These directives allow the programmer to avoid a conflict between the reserved
system names of constants and functions and the programmer's own symbols.
Symbols can be renamed by the ALIAS directive and the original names
DISABLE'd, rendering them usable by the programmer.

SyntaxnewnameRemarks

Symbolic names currently known to the Assemblers may be ALIASed andDISABLEd. However, these directives must not be used to disable Assembler
directives.

Examples_Offset_OffsetoffsetALIAS
DISABLE

alias
disable
...
dc.w
dc.w

name
name

offsetoffset_Offset(Lab)*-pointer

Psy-Q Development System

CHAPTER 4

General Assembler Directives
The Assemblers provide a variety of functions and directives to control assembly of
the source code and its layout in the target machine.
This chapter documents the Assembler directives which allow the programmer tocontrol the processes of assembly, grouped as follows:
•
•
•
•
•
•

Assignment Directives
Data Definition
Controlling Program Execution
Include Files
Controlling Assembly
Target-related Directives

Psy-Q Development System

Assignment Directives
The directives in this section are used to assign a value to a symbolic name. The value
may be a constant, variable or string.
•
•
•
•
•
•
•
•

EQU
SET (and =)
EQUS
EQUR
REG
RS
RSSET
RSRESET

Psy-Q Development System

EQU
Description

Assigns the result of the expression, as a constant value, to the preceding symbolic
name.

Syntaxsymbol name EQU expression

See Also

SET, EQUS

Remarks•

The Assembler allows the assigned expression to contain forward references. If
an EQU cannot be evaluated as it is currently defined, the expression will besaved and substituted in any future references to the equate (see Note below).

•

It is possible to include an equate at assembly time, on the Assembler commandline. This is useful for specifying major options of conditional assembly, such as
test mode - see Assembler switches, chapter 2.

•

Assigning a value to a symbol with EQU is absolute; an attempt at secondary
assignment will produce an error. However, it is permissible to re-assign thecurrent value to an existing symbol; typically, this occurs when subsidiary code
redefines constants already used by the master segment.

ExamplesLengthWidth
Depth
VolumeDmaHigh
DmaMid

equ
equ
equ
equ
equ
equ

4
8
12
Length*Width*Depth$ffff8609
DmaHigh+2

Note

List

equ

Lastentry-Firstentry

if Firstentry, Lastentry not yet defined, then:dc.l

List+2will be treated asdc.l(Lastentry-Firstentry)+2

the equated expression is implicitly bracketed.

Psy-Q Development System

SET
Description

Assigns the result of the expression, as a variable, to the preceding symbolic name.

Syntaxsymbol name SET
symbol name =See Also

EQU

expression
expression

Remarks

Examples•SET and equals (=) are interchangeable•

Values assigned by a SET directive may be re-assigned at any time.

•

The Assembler does not allow the assigned expression in a SET directive tocontain forward references. If a SET cannot be evaluated as it is currently
defined, an error is generated.

•

If the symbol itself is used before it is defined, a warning is generated, and it isassigned the value determined by the preliminary pass of the Assembler.

•

The symbol in a SET directive does not assume the type of the operand. It is,therefore, better suited to setting local values, such as in macros, rather than incode with a relative start position, such as a SECTION construct, which may
cause an error - see Examples.

Loopcount
GrandTotal
xdim

set
=
set

0
SubTotalA+SubTotalB
Bsize<<SC

cbb
lc

macro
=
rept
substr
dc.b
=
endr
endm

string0
strlen(\string)lc+1,lc+1,\string'\cc'^($A5+lc)
lc+1

cc
lc

Psy-Q Development System

EQUS
Description

Assigns a text or string variable to a symbol.

Syntaxsymbol name EQUS "text"
symbol name EQUS 'text'
symbol name EQUS symbol nameSee Also

EQU, SET

Remarks

Examples•Textual operands are delimited by double or single quotes. If it is required toinclude a double quote in the text string, delimit with single quotes or two double
quotes; similarly, to include a single quote in the text, delimit with double quotes
or two single quotes - see examples below.

•

If delimiters are omitted, the Assembler assumes the operand to be the symbolname of a previously defined string variable, the value of which is assigned to the
new symbol name.

•

Point brackets, { and }, are special delimiters used in Macros - see MACRO
directive specification, chapter 5.

•

Symbols equated with the EQUS directive can appear at any point in the code,
including as part of another text string. If there is the possibility of confusion withthe surrounding text, a backslash (\) may be used before the symbol name, and, if
necessary, after it, to ensure the expression is expanded correctly - see examples
below.

Programequs "Psy-Q v 1.2"

Qtex

equs "What's the score?"dc.b "Remember to assemble &\_filename",0Psy-Q Development Systemzequs "123"...
dc.l z+4

converts to
dc.l 123+4
whereas the following expression needs backslashes to be expanded correctly:
dc.l number\z\aconverts to
dc.l number123aSAequs 'StartAddress'...
dc.l \SA\4converts to
dc.l StartAddress4

Note

To include single quotes in a string delimited by single quotes, either change thedelimiters to double quotes, or double-up the internal single quote. Similarly, this
syntax applies to double quotes, as follows:

Sinquote
Sinquot2

equs 'What''s the point?'
equs "What's the point?"

Doubquote equs "Say ""Hello"" and go"
Doubquote equs 'Say "Hello" and go'

Psy-Q Development System

EQUR
Description

Defines a symbol as an alternative for a data register or an address register.

Syntaxsymbol name EQUR register nameSee Also

REG

Remarks•

The major use of the EQUR directive is to improve the overall readability of thesource code.

•

In order that the Assembler can evaluate the expression correctly, dots are notallowed as part of the symbol name of a EQUR (see example below).

Examplescmp.b

RGBinds(a2,d1.w),d0

This could be re-written using EQUR's, as follows:
Red
Green
Blue

equr
equr
equr
...
cmp.b

a2
d1
d0
RGBinds(Red,Green.w),Blue

Since dots are not allowed in EQUR names, the Assembler can correctly interpret
Green.w as the low word of (d1).

Psy-Q Development System

REG
Description

Defines a symbol as an alternative for a list of data registers or address registers.

Syntaxsymbol name REG list

See Also

EQUR

Remarks

Examples•As with EQUR, the main purpose of the REG directive is to improve the overallreadability of the code.

•

Likewise, dots are not permitted in the symbol name of a REG.

Windsetreg...

d0-d7/a1-a2

lea
movem.w
movem.w
leabsr

camwind\w,a0(a0),Windset
Windset,minx\w
camcliplist,a3
setcliplist

Psy-Q Development System

RS
Description

Assigns the value of the __RS variable to the symbol, and advances the rs counter by
the number of bytes, words or long words, specified in count.

Syntaxsymbol name RS.size
where .size is .b
.w
.l

count

byte
word
long word(if .size is not specified, .w is assumed)

See Also

RSSET, RSRESET

Remarks•

This directive, together with the following two associated directives, operate on
or with the Assembler variable, __RS, which contains the current offset.

•

When the Automatic Even assembler option (/AE) is in force, RS directives forword and long word ensure that the __RS variable is aligned to the next wordboundary.

ExamplesrsresetIcon_noDropcode
ActcodeActname
Objpos

rs.b
rs.w
rs.w
rs.b
rs.l

1
1
1
10
1

Artlenrs.b

0After each of the first five RS equates, the __RS pointer is advanced; the values foreach equate are as follows:

Psy-Q Development System

Icon_no
Dropcode
ActcodeActname
ObjposArtlen

0
1
4
6
16
20

(set to zero by RSRESET)(Automatic Even set, advances the pointer to even boundary)

The last rs.b does not advance the __RS pointer, since a count of zero is equivalent
to an EQUATE to the __RS variable.

RSSET
Description

SyntaxAssigns the specified value to __RS variable.

RSSET

value

See Also

RS, RSRESET

Remarks

This directive is normally used when the offsets are to start at a value other than zero.

ExamplesSee the RS directive

Psy-Q Development System

RSRESET
Description

Sets the __RS variable to zero.

SyntaxSee Also

RSRESET[value]RS, RSSET

Remarks

Examples•Using this directive is the normal way to initialise the __RS counter at the start ofa new data structure.

•

The optional parameter is provided for compatibility with other assemblers; if
present, RSRESET behaves like the RESET directive.

See the RS directive

Psy-Q Development System

Data Definition
The directives in this section are used to define data and reserve space.
•
•
•
•
•
•
•
•

DC
DCB
DS
HEX
DATA
DATASIZEIEEE32
IEEE64

Psy-Q Development System

DC
Description

This directive evaluates the expressions in the operand field, and assigns the results tothe preceding symbol, in the format specified by the .size parameter. Argument
expressions may be numeric values, strings or symbols.

Syntaxsymbol name DC.size

expression,..,expression

where .size is .b
.w
.l

byte
word
long word(if .size is not specified, .w is assumed)

See Also

DCB

Remarks•

Textual operands are delimited by double or single quotes. If it is required toinclude a double quote in the text string, delimit with single quotes or two double
quotes; similarly, to include a single quote in the text, delimit with double quotes
or two single quotes - see examples below. If delimiters are omitted, theAssembler assumes the operand to be the symbol name of a previously defined
string variable, the value of which is assigned to the new symbol name.

•

When the Automatic Even assembler option (/AE) is in force, DC directives forword and long word ensure that the program counter is aligned to the next wordboundary.

ExamplesHexvals
CoordsPointers
ErrorMes

Notes

If the Assembler encounters a parameter that is out-of-range, an error is flagged; thefollowing statements will produce errors:

dc.w
dc.w
dc.l
dc.b

dc.b
dc.b
dc.w
dc.w

$80d,$a08,0,$80d,0-15,46
StartMarker,EndMarker"File Error",0

257
-129
66000
-33000Psy-Q Development System

DCB
Description

This directive generates a block of memory, of the specified length, containing thespecified value.

Syntax

DCB.size
where .size is .b.w.llength,value

byte
word
long word(if .size is not specified, .w is assumed)

See Also

DC

Remarks

When the Automatic Even assembler option (/AE) is in force, DCB directives forword and long word ensure that the program counter is aligned to the next wordboundary.

Examples

dcb.b

256,$7F

generates 256 bytes containing $7F.
dcb.w

64,$FF

generates 64 words containing $FF.

Psy-Q Development System

DS
Description

Allocates memory to the symbol, of the specified length, and initialises it to zero.

Syntaxsymbol name DS.size
where .size is .b.w.llengthbyte
wordlong word(if .size is not specified, .w is assumed)

See Also

DC, DCB

Remarks

Examples•When the Automatic Even assembler option (/AE) is in force, DS directives forword and long word ensure that the program counter is aligned to the next wordboundary.

•

If this directive is used to allocate memory in a Group/Section with the BSS
attribute, the reserved area will not be initialised - see Groups and Sections,chapter 8.

List

ds.w

64

reserves an area 64 words long, and sets it to zero.
Bufferds.b1024

reserves a 1k bytes area, and sets it to zero.

Psy-Q Development System

HEX
Description

This directive takes a list of unsigned hex nibble pairs as an argument, which areconcatenated to give bytes. It is intended as a quick way of inputting small hex
expressions.

Syntaxsymbol name HEX hexlist

See Also

INCBIN

Remarks

Data stored as HEX is difficult to read, less memory-efficient and causes more workfor the Assembler. Therefore, it is suggested that the HEX statement is used forcomparatively minor data definitions only. To load larger quantities of data, it isrecommended that the data is stored in a file, to be INCLUDEd as a binary file atruntime - see Include Files, chapter 5.

ExamplesHexStrhex

100204FF0128

is another way of writing
HexStrdc.b$10,$02,$04,$FF,$01,$28

Psy-Q Development System

DATASIZE and DATA
Description

SyntaxTogether, these directives allow the programmer to define values between 1 and 256
bytes long (8 to 2048 bits). The size of the DATA items must first be defined by a
DATASIZE directive.

DATASIZE size
DATA
value, value
where value is a numeric string, in hex or decimal, optionally preceded by a minus
sign.

See Also

IEEE32, IEEE64

Remarks

If a value specified in the DATA directive converts to a value greater than can beheld in size specified by DATASIZE, the Assembler flags an error.

Examplesdatasize
...
data
data

8
$123456789ABCDEF0-1,$FFFFFFFFFFFF

IEEE32 and IEEE64
Description

SyntaxSee Also

ExamplesThese directives allow 32 and 64 bit floating point numbers to be defined in IEEE
format.

IEEE32
IEEE64

fp.valuefp.value

DATA, DATASIZE

ieee32

1.23,34e10

ieee64123456.7654321e-2

Psy-Q Development System

Controlling Program Execution
The directives in this section are used to alter the state of the program counter andcontrol the execution of the Assembler.
•
•
•
•
•

ORG
EVEN
CNOP
OBJ
OBJEND

Psy-Q Development System

ORG
Description

The ORG directive informs the Assembler of the location of the code in the target
machine.

SyntaxORG address[,parameter]where address is a previously-defined symbol, or a hex or decimal value, optionallypreceded by a question mark (?) and followed by a (target-specific) numericparameter.

See Also

OBJ, OBJEND, GROUP, SECTION

Remarks•

If a link file is output, the ORG directive must not be used - see Groups andSections, chapter 8.

•

If the program contains SECTIONs, a single ORG is allowed, and it must
precede all SECTION directives. If the program does not utilise the SECTION
construct, it may contain multiple ORG's.

•

The ORG operand can be preceded by a question mark, to indicates the amountof RAM required by the program. However, the ORG ? function only works on
machines with operating systems to allocate the memory; for instance, it will
work on the Amiga but not the Sega Mega Drive.

ExamplesBegin

Programorg
move.w$100sr,-(A7)

equ
...
org

$4000
ProgramPsy-Q Development System

EVEN
Description

This directive aligns the program counter to the next word boundary.

SyntaxSee Also

EVEN

CNOP

Remarks

Examples•There is a related assembler option, AE - Automatic Even. If set, the word andlong word forms of several directives, such as DC, DCB, DS, and _RS, will force
the program counter onto the next word boundary before they are executed.

•

In code containing SECTIONs, the Assembler does not allow the program
counter to be reset to a size boundary greater than the alignment already set forthat section. Therefore, a EVEN statement, is not allowed in a section that isbyte-aligned.

Ind1
Ind2
Ind3
InArea

dc.b
dc.b
dc.b
even
ds.b

0
0
0
Inlengthforces InArea onto a word boundary.

Psy-Q Development System

CNOP
Description

Resets the program counter to a specified offset from the specified size boundary.

SyntaxCNOP

offset,size boundary

See Also

EVEN

Remarks

As with the EVEN directive, in code containing SECTIONs, the Assembler does notallow the program counter to be reset to a size boundary greater than the alignment
already set for that section. Therefore, a CNOP statement, with a size boundary of 2,
is not allowed in a section that is byte-aligned.

Examplessection.l prime
Firstoff =512Firstsize =
2
...
cnop
Firstoff,Firstsize
sets the program counter to 512 bytes above the next word boundary.
Note that:
cnop

0,2

performs as an EVEN statement.

Psy-Q Development System

OBJ and OBJEND
Description

OBJ forces the code following it to be assembled as if it were at the specified
address, although it will still appear following on from the previous code.
OBJEND terminates this process and returns to the ORG'd address value.

SyntaxOBJ

address

OBJEND

See Also

ORG

Remarks

Examples•The OBJ - OBJEND construct is useful for code that must be assembled at one
address (for instance, in a ROM cartridge), but will be run at a different address,
after being copied there.

•

Code blocks delimited by OBJ - OBJEND cannot be nested.

org
dc.l
dc.l

$100
*
*

obj
dc.l
dc.l

$200
*
*

objend
dc.l
dc.l

*
*

The above code will generate the following sequence of longwords, starting ataddress $100:
$100
$104
$200
$204
$110
$114

Psy-Q Development System

Include Files
The source code for most non-trivial programs is too large to be handled as a single
file. It is normal for a program to be constructed of subsidiary files, which are called
together during the assembly process.
The directives in this section are used to collect together the separate source files andcontrol their usage; also discussed are operators to aid the control of code to beassembled from INCLUDEd files.

•
•
•
•

INCLUDEINCBINDEF
REF

Psy-Q Development System

INCLUDE
Description

Informs the Assembler to draw in and process another source file, before resuming
the processing of the current file.

SyntaxINCLUDEfilename

where filename is the name of the source file to be processed, including drive andpath identifiers - see Note. The filename may be surrounded by quotes, but they willbe ignored.

See Also

INCBIN

Remarks
Traditionally, there will be one main file of source code, which contains INCLUDE'sfor all the other files.
INCLUDEd files can be nested.
The /j switch can be used to specify a search path for INCLUDEd files - see
Assembler Options, chapter 10.

ExamplesA typical start to a program may be:
sectioncodestart jmp

short1entrypoint

dc.b
dc.b
dc.w

_hours,_minutes_day,_month_year

includevars1.68k

sectionshort2

includevars2.68k

sectioncode

includeincludegraph1.68k
graph2.68k

Psy-Q Development System

include
includeincludemaths.68k
trees.68k
tactics.68k

entrypoint move.w#$2700,sr
lea
stacktop,sp
or include d:/source/levels.asm
Note: Since a path name contains backslashes, the text in the operand of an
INCLUDE statement may be confused with the usage of text previously
defined by an EQUS directive. To avoid this, a second backslash may be usedor the backslash may be replaced by a forward slash (solidus).
Thus,
included:\source\levels.asm

may be re-written as:
included:\\source\levels.asm

or:included:/source/levels.asm

Psy-Q Development System

INCBIN
Description

Informs the Assembler to draw in and process binary data held in another source file,
before resuming the processing of the current file.

Syntaxsymbol••See Also

INCBIN

filename[,start,length]

filename is the name of the source file to be processed, including drive and path
identifiers - see Note1. Optionally, the filename may be surrounded by quotes,
which will be ignored;
start, length are optional values, allowing selected portions of the specified file to
be included - see Note2.

INCLUDE, HEX

Remarks•

This directive allows quantities of binary data to be maintained in a separate fileand pulled into the main program at assembly time; typically, such data might becharacter movement strings, or location co-ordinates. The Assembler is passed no
information concerning the type and layout of the incoming data. Therefore,labelling and modifying the INCBINed data are the responsibility by the
programmer.

•

The /j switch can be used to specify a search path for INCLUDEd files - see
Assembler Options, chapter 3.

ExamplesCharmove

Note1

Since a path name contains backslashes, the text in the operand of an INCBIN
statement may be confused with the usage of text previously defined by an EQUS
directive. To avoid this, a second backslash may be used, or the backslash may bereplaced by a forward slash (solidus).

incbin"d:\source\charmov.bin"Thus,included:\source\charmov.bin

may be re-written as
included:\\source\\charmov.bin

included:/source/charmov.bin

orPsy-Q Development System

Note2The nominated file may be accessed selectively, by specifying a position in the file,from which to start reading, and a length. Note that:•••

if start is omitted, the INCBIN commences at the beginning of the file;
if the length is omitted, the INCBIN continues to the end of the file;
if both start and length are omitted, the entire file is INCBINed.

REF
Description

REF is a special operator, to allow the programmer to determine which segments ofcode are to be INCLUDEd.

Syntax[~]REF(symbol)
The optional preceding tilde (~) is synonymous with NOT.

Remarks

REF is true if a reference has previously been encountered for the symbol in thebrackets.

ExamplesLinks

ifmove.w
...
rts
endif

ref(Links)
d0,-2(a0)

The Links routine will be assembled if a reference to it has already been encountered.

Psy-Q Development System

DEF
Description

Like the REF operator, DEF is a special function. It allows the programmer todetermine which segments of code have already been INCLUDEd.

Syntax[~]DEF(symbol)
The optional preceding tilde (~) is synonymous with NOT.

Remarks

DEF is true if the symbol in the brackets has previously been defined.

Examplesloadadrexecadrrelocadr

if
equ
equ
equ
endc

~def(loadadr)
$1000
$1000
$80000-$300

The address equates will be assembled if load_addr has not already been defined.

Psy-Q Development System

Controlling Assembly
The following directives give instructions to the Assemblers, during the assembly
process. They allow the programmer to select and repeat sections of code:
•
•
•
•
•
•
•
•
•
•
•
•
•

END
IF
ELSE
ELSEIFENDIF
CASE
ENDCASE
REPT
ENDR
WHILE
ENDW
DO
UNTIL

Psy-Q Development System

END
Description

The END directive informs the Assembler to cease its assembly of the source code.

SyntaxSee Also

END [address]

REGS

Remarks

Example•The inclusion of this directive is mostly cosmetic, since the Assembler will cease
processing when the input source code is exhausted.

•

The optional parameter specifies an initial address for the program. See also the
REGS statement, in the section - Target-Related Directives, chapter 5.

startrelmove.w
lea
...
jmp
end

#$2700,sr$100000-4,sp
progad\w

IF, ELSE, ELSEIF, ENDIF, ENDC
Description

These conditional directives allow the programmer to select code for assembly.

SyntaxSee Also

IF
ELSE
ELSEIF
ENDIF
ENDC[~]expression[~]expression

CASE

Psy-Q Development System

Remarks•

The ENDC and ENDIF directives are interchangeable.

•

If the ELSEIF directive is used without a following expression, it acts the sameas an ELSE directive.

•

The optional tilde, preceding the operand expression, is synonymous with NOT.
Its use normally necessitates the prudent use of brackets to preserve the sense of
expression.

Examplessec_dirifequSega-MD2

sec_dir

elseifequ

Sega-CD
1

else
equ
endif

3

sec_dir

round

round

movopttempstr
num

if
macro
add.l
endm

~usesquare\1,\2

elseif
macro
endm
endc

macro
substrif
substr
if
moveq
else
move.w
endif
else
fail
endif
endm

parm,dest
1,1,'\parm'strcmp('#','\tempstr')
2,,'\parm'((\num)>-127)&((\num)<128)#(\num),\dest#(\num),\destPsy-Q Development System

CASE and ENDCASE
Description

The CASE directive is used to select code in a multiple-choice situation. The CASE
argument defines the expression to be evaluated; if the argument(s) after the equals
sign are true, the code that follows is assembled. The equals-question mark case is
selected if no previous case is true.

SyntaxCASE=expression[,expression]=?
ENDCASE

See Also

IF conditionals

Remarks

In the absence of a equals-question mark (=?) case, if the existing cases are
unsuccessful, the case-defined code is not assembled.

ExamplesThe following is an alternative for the example listed under the IF directive - seechapter 5.
Targetequ...

expression

Sega-MDcase Target=Sega-MD
sec_direqu

2=Sega-CD
sec_direqu1=?
sec_dirdc.b "New Version",0equ 3
endcasePsy-Q Development System

REPT, ENDR
Description

These directives allow the programmer to repeat the code between the REPT and
ENDR statements. The number of repetitions is determined by the value of count.

Syntax

REPT
...
ENDR

See Also

DO, WHILE

Remarks

When used in a Macro, REPT is frequently associated with the NARG function.

Examples

cbb
lc
cc
lc

count

rept
dc.w
endr

12
0,0,0,0

macro
=
rept
substr
dc.b
=
endr
endm

string0
strlen(\string)lc+1,lc+1,\string"\cc"^($A5+lc)
lc+1

Psy-Q Development System

WHILE, ENDW
Description

These directives allow the programmer to repeat the code between the WHILE and
ENDW statements, as long as the expression in the operand holds true.

Syntax

WHILE
...
ENDW

expression

See Also

REPT, DO

Remarks

Currently, any string equate substitutions in the WHILE expression take place once
only, when the WHILE loop is first encountered - see Note below for theramifications of this.

Examples

MultP
Indic

Indic

Note

equ
...
=
while
move.w
...
=
endw

16
MultP
Indic>1term(a0),d0
Indic-1

Because string equates are only evaluated at the start of the WHILE loop, thefollowing will not work:
s
s

equs
while
dc.b
equs
endw

"x"
strlen("\s") < 4"\s",0"\s\x"

Psy-Q Development System

To avoid this, set a variable each time round the loop to indicate that looping should
continue:sloopingslooping

equs
=
while
dc.b
equs
=
endw

"x"
-1
looping"\s",0"\s\x"
strlen("\s") < 4

DO, UNTIL
Description

These directives allow the programmer to repeat the code between the DO and
UNTIL statements, until the specified expression becomes true.

SyntaxDO...
UNTIL expression

See Also

REPT, WHILE

Remarks

Unlike the WHILE directive, string equates in an UNTIL expression will be reevaluated each time round the loop.

Examples

MultP
Indic

Indic

equ
...
=
do
move.w
...
=
until

16
MultP
term(a0),d0
Indic-1
Indic<=1

Psy-Q Development System

Target-related Directives
The following directives allow the programmer to specify certain initial parameters in
the target machine:
•
•

REGS
UNIT

Psy-Q Development System

REGS
Description

If a CPE file is produced, or object code output is directed to the target, the REGS
directive specifies the contents of the registers, at the start of code execution.

Syntax

REGS

regcode=expression[,regcode=expression]

where regcode is the mnemonic name of a register, such as SR, PC.

Remarks

ExampleFor relocatable code, which is specific to the target, or pure binary code, thisdirective is not available.

regs

pc=__SN_ENTRY_POINT

Register assigns can be declared on one line, separated by commas. Remember to use
specific mnemonics for registers, e.g. for the 68000, USP for the user stack and SSP
for the supervisor stack.

UNIT
Description

SyntaxRemarks

ExamplesThe UNIT directive allows the destination unit in a multi-processor target to be
specified, such as the Main CPU and Sub-CPU in Sega Mega-CD.

UNIT

unitnumber

Only one UNIT directive may be included; if there is no UNIT directive, a unit
number of 0 is assumed.

unit

1

Psy-Q Development System

CHAPTER 5

MacrosThe Assemblers provide extensive macro facilities; these allow the programmer toassign names to complete code sequences. They may then be used in the main
program like existing assembler directives.
This chapter discusses the following topics, directives and functions:
•
•
•
•
•
•
•
•

MACRO, ENDM
MEXIT
Macro Parameters
SHIFT, NARG
MACROSPUSHP, POPP
PURGE
TYPE

Psy-Q Development System

MACRO, ENDM, MEXIT
Description

A macro consists of the source lines and parameter place markers between the
MACRO directive and the ENDM. The label field is the symbolic name by which themacro is invoked; the operand allows the entry of a string of parameter data names.
When the assembler encounters a directive consisting of the label and optionalparameters, the source lines are pulled into the main program and expanded bysubstituting the place markers with the invocation parameters. The expansion of themacro is stopped immediately if the assembler encounters a MEXIT directive.

SyntaxLabel

See Also

MACROS

MACRO
...
MEXIT
...
ENDM

[symbol,..symbol]

Remarks

Examples•Note that the invocation parameter string effectively starts at the character after
the macro name, that is, the dot (.) character. Text strings, as well as .b, .w and .l
are permissible parameters - see Parameters below.

•

Control structures within macros must be complete. Structures started in themacro must finish before the ENDM; similarly, a structure started externally mustnot be terminated within the macro. To imitate a simple control structurefrom another assembler, a short macro might be used - see MACROS below.

remove

Form

macro
dc.w
endm

macro
if
dc.w
else
dc.w
endif
endm

-2,0,0strcmp('\1','0')0\1-FormBase

Psy-Q Development System

Macro Parameters
Parameters

ExampleMacro parameters obey the following rules:•

The parameters listed on the macro invocation line may appear at any point in thecode declared between the MACRO and ENDM statements. Each parameter isintroduced by a backslash (\); where this may be confused with text from an
EQUS, a backslash may also follow the parameter.

•

Up to thirty two different parameters are allowed, numbered \0 to \31. \0 is a
special parameter which gives the contents of the size field of the macro directive
when it was invoked, that is, the text after the point symbol (.) This includes not
only .b, .h or .w, but also any text:

zed

macro
\0
endm
...
zed.nopwill generate a NOP instruction.
Instead of the \0 to \31 format, parameters can be given symbolic names, by their
inclusion as operands to the MACRO directive. The preceding backslash (\) is notmandatory; however, if there is the possibility of confusion with the surrounding text,
a backslash may be used before and after the symbol name to ensure the expression is
expanded correctly:

ExamplePosition

macro
dc.w
endm

A,B,C,Pos,Time\Time*(\A*\Pos+\B*\Pos+\C*\Pos)

Surrounding the operand of an invoked macro with greater than and less than signs(<...>), allows the use of comma and space characters. This does not apply to
Assemblers which use angle brackets as address mode specifiers; in these instances,
backward single quote is used.

Psy-Q Development System

Example

Credits•

Example

macro
dc.w
dc.b
dc.b
even
endm
...
Credits

\1,\2
\3
0

11,10,<Psy-Q, from Psygnosis>

Continuation Lines - when invoking a macro, it is possible that the parameter list
will become overlong. As with any directive statement, the line can be terminatedby an ampersand (&) and continued on the next line to improve readability.

chstr

cheatstr

macro
rept
dc.b
shift
endr
dc.b
even
endm
...
chstr

narg
k_\1
0

i,c,a,n,b,a,r,e,l,y,&s,t,a,n,d,i,t

Psy-Q Development System

Special Parameters
There are a number of special parameter formats available in macros, as follows:

Converting Integers to Text
The parameters \# and \$ replace the decimal (#) or hex ($) value of the symbol
following them, with their character representation. Commonly, this technique is used
to access Run Date and Time:

Example
RunTime

org
dc.b

$1006
"\#_hours:\#_minutes:&\#_seconds"

this expands to the form hh:mm:ss, as follows
RunTimedc.b"21:08:49"

Generating Unique Labels
The parameter \@ can be used as the last characters of a label name in a macro.
When the macro is invoked, this will be expanded to an underscore followed by adecimal number; this number is increased on each subsequent invocation to give aunique label.

ExampleSlots

next\@
dun\@

macro
moveq
move.1
beq.s
addq.w
bgt.s
move.w
endm
...
Slots

#0,d0
r1,\1
dun@
#1, d0d0,2freeob1,numslot1w

Each time the Slots macro is used, new labels in the form next_001 and dun_001 will
be generated.

Psy-Q Development System

Entire Parameter
If the special parameter \_ (backslash underscore) is encountered in a macro, it isexpanded to the complete argument specified on the macro invocation statement.

Examples

All

macro
dc.b
endm
...
All

\_
1,2,3,4will generatedb

1,2,3,4Control Characters
The parameter \^x, where x denotes a control character, will generate the specified
control character.

Using the Macro Label
The label heading the invocation line can be used in the macro, by specifying the firstname in the symbol list of the MACRO directive to be an asterisk (*), andsubstituting \* for the label itself. However, the resultant label is not defined at thecurrent program location. Therefore, the label remains undefined unless the
programmer gives it a value.

Extended Parameters
The Assembler accepts a set of elements, enclosed in curly brackets ({}), to bepassed to a macro parameter. The NARG function and SHIFT directive can then be
used to handle the list:

Example

cmd
cc

macro
equs
rept
\cc
shift
endr
endm

{\1}
narg(cc)cc

Psy-Q Development System

SHIFT, NARG
Description

These directives cater for a macro having a variable parameter list as its operand. The
NARG symbol is the number of arguments on the macro invocation line; the SHIFT
directive shifts all the arguments one place to the left, losing the leftmost argument.

Syntaxdirective

NARG
...
SHIFT

where NARG is a reserved, predefined symbol.

See Also

Extended Parameters

Examplesroutes

macro
rept
if
dc.w
else
dc.w
endif
shift
endr
endm
...
routesnarg
strcmp('\1','0')0\1-routebase

0,gosouth_1

This example goes through the list of parameters given to the macro and defines ahalf word of $0000 if the argument is zero or a 16 bit offset into the ‘routebase’ tableof the given label.

Psy-Q Development System

MACROS
Description

The MACROS directive allows the entry of a single line of code as a macro, with noassociated ENDM directive. The single line of code can be a control structure
directive.

SyntaxLabel

See Also

MACRO

Remarks

The MACROS directive may be used to stand in for a single, complex code line.
Often, the short macro allows the programmer to synthesise a directive from anotherassembler. Including the /k option on the command line will cause several macros
emulating foreign directives to be generated.

MACROS[symbol,..symbol]

Examplesif0
macros
bsr
boom1
else
boom
macrosmove.w#blowup-tactbase,&slot_tactic(1)
endif
boom

Psy-Q Development System

PUSHP, POPP
Description

These directives allow text to be pushed into, and then popped from, a string
variable.

Syntax

PUSHP
POPP

stringstringRemarks

There is no requirement for the PUSH and corresponding POPP directives to appear
in the same macro.

Examples

ifhid

ifnot

macro
dc.w
dc.w
pushp
dc.w
endm
...
macro
popp
goto
pushp

ibvis
1
@
@-2-*

lab
@
@

lab
endm
This means the user does not have to specify stksize when using freeframe. The user
must ensure that calls to makeframe and freeframe are balanced.

Psy-Q Development System

PURGE
Description

The PURGE directive removes an expanded macro from the internal tables andreleases the memory it occupied.

Syntax

PURGE

macroname

Remarks

It you need to redefine a macro, it is not necessary to purge it first as this is done by
the Assembler.

Examples

HugeM

macro
dc.w
dc.w
...
dc.w
endm
HugeM
...

\1
\2
\31
para1,103,faultlevel,&
40,50,para31

purge

HugeM

Psy-Q Development System

TYPE
Description

TYPE is a function used to provide information about a symbol. It is frequently usedwith a macro to determine the nature of its parameters. The value is returned as aword; the meanings of the bit settings are given below.

SyntaxTYPE(symbol)

The reply word can be interpreted as follows:
Bit 0
Bit 1
Bit 2
Bit 3
Bit 4
Bit 5
Bit 6
Bit 7
Bit 8
Bit 9
Bit 10
Bit 11
Bit 12
Bit 13
Bit 14
Bit 15

Symbol has an absolute value
Symbol is relative to the start of the Section
Symbol was defined using SET
Symbol is a Macro
Symbol is a String Equate (EQUS)
Symbol was defined using EQU
Symbol appeared in an XREF statement
Symbol appeared in an XDEF statement
Symbol is a Function
Symbol is a Group Name
Symbol is a Macro parameter
Symbol is a short Macro (MACROS)
Symbol is a Section Name
Symbol is Absolute Word Addressable
Symbol is a Register Equate (EQUR)
Symbol is a Register List Equate (REG)

Psy-Q Development System

CHAPTER 6

String Manipulation Functions
To enhance the Macro structure, the Assemblers include powerful functions for string
manipulation. These enable the programmer to compare strings, examine text andprepare subsets.
This chapter covers the following string handling functions and directive:••••

STRLENSTRCMPINSTR
SUBSTR

Psy-Q Development System

STRLEN
Description

A function which returns the length of the text specified in the brackets.

SyntaxSTRLEN(string)See Also

STRCMP

Remarks

The STRLEN function is available at any point in the operand.

ExamplesNummovmacro
rept
move.1
endr
endm
...
Nummovstrlen(\1)(a1)+, (a0)+12345

The number of characters in the string is used as the extent of the loop.

Psy-Q Development System

STRCMP
Description

A function which compares two text strings in the brackets, and returns true if they
match, otherwise it returns false.

SyntaxSTRCMP(string1,string2)

See Also

STRLEN

Remarks

When comparing two text strings, the STRCMP function starts numbering thecharacters in the target texts from one.

Examples

Vers

equ
...
if
move.welse
if
move.welse
if
move.w
endif
endif
endif

"Acs"
strcmp("\Vers","Sales")Sa1ind, d0
strcmp("\Vers","Acs")
AcInd,d0
strcmp("\Vers","Test")
TstInd, d0

Psy-Q Development System

INSTR
Description

This function searches a text string for a specified sub-string. If the string does notcontain the sub-string, the result of zero is returned; if the sub-string is present, theresult is the location of the sub-string from the start of the target text. It is also
possible to specify an alternate start point within the string via an optional parameter.

SyntaxSee Also

SUBSTR

Examples

Mess

Note

INSTR

([start,]string, sub-string)

equs
...
if
move.welse
move.w
endif"Demo for Sales Dept"
instr("\Mess","Sales")
Sa1Ind, d0
AcInd, d0

When returning the offset of a located sub-string, the INSTR function starts
numbering the characters in the target text from one.

Psy-Q Development System

SUBSTR
Description

This directive assigns a value to a symbol; the value is a sub-string of a previously
specified text string, defined by the start and end parameters. The start and end
parameters will default to the start and end of the string, if omitted.

SyntaxsymbolSee Also

INSTR, EQUS

Remarks

When assigning a sub-string to a symbol, the SUBSTR directive starts numbering thecharacters in the source text from one.

ExamplesMessage
Part1
Part2
Part3
Part4

SUBSTRequs
substrsubstrsubstrsubstr[start],[end],string"A short Sample String"
9,14,"\Message"
16,,"\Message",7,"\Message",,"\Message"

where Part1 equals Sample
Part2 equals String
Part3 equals A short
The last statement is equivalent to an EQUS assigning the whole of the original
string to Part4.

Psy-Q Development SystemPsy-Q Development System

CHAPTER 7

Local Labels
As a program develops, finding label names that are both unique and definitive
becomes increasingly difficult. Local Labels ease this situation by allowing
meaningful label names to be re-used.
This chapter covers the following topics and directives:•••

Local Label Syntax and Scope
MODULE and MODEND
LOCALPsy-Q Development System

Syntax and Scope
Syntax

Scope

Examples•Local Labels are preceded by a local label signifier. By default, this is an @ sign;
however, any other character may declared by using the l option in an OPT
directive or on the Assembler command line - see Assembler Options chapter 3.

•

Local label names follow the general label rules, as specified in chapter 4.

•

Local labels are not de-scoped by the expansion of a macro.

The region of code within which a Local Label is effective is called its Scope. Outside
this area, the label name can be re-used. There are three methods of defining thescope of a Local Label:•

The scope of a local label is implicitly defined between two non-local labels.
Setting a variable, defining an equate or RS value does not de-scope current local
labels, unless the d option has been used in an OPT directive or on the Assembler
command line - see Assembler Options, chapter 10.

•

The scope of a Local Label can also, and more normally, be defined by the
directives MODULE and MODEND - see chapter 8.

•

To define labels (or any other symbol type) for local use in a macro, the LOCAL
directive can be used - see chapter 8.

plot2

@chk1

SetX
@ret
plot3
@ret

move.b
...
cmp.w
bge.s

comp\w,d3

add.w
bra.s
cmp.w
...
jsr
move.wset
rts
movem.w...
rts#168,d3@ret#83,d3#-84,d3@chk1

lcolourd3,d0
x+1
d6-d7,-(sp)Psy-Q Development System

The code above shows a typical use for Local Labels, as "place markers" within aself-contained sub-routine. The scope is defined by the non-local labels, Plot2 andPlot3; the SET statement does not de-scope the routine. The labels @chk1 and @ret
are re-usable.

plot2

move.b
moveq
cmp.w
bge.s

comp\w,d3
chrbit-1,d2#-84,d3
@chk1

add.w
bra.s

#168,d3
setplot

@chk1

cmp.w
move.w#83,d3d3,d0

setplot

set
...
dbra

x+1
d2,@chk1

In the example, the final branch will cause an error, since it is outside the scope of@chk1.

Psy-Q Development System

MODULE and MODEND
Description

Code occurring after a MODULE statement, and up to and including the MODEND
statement, is considered to be a module. Local labels defined in a module can be reused, but cannot be referenced outside the module's scope. A Local label definedelsewhere cannot be referenced within the current module.

SyntaxSee Also

MODULE...
...
MODEND
LOCAL

Remarks

Examples•Modules can be nested.

•

The MODULE statement itself is effectively a non-local label and will de-scope
any currently active default scoping.

•

Macros can contain modules or be contained in a module. A local label occurringin a module, can be referred to by a macro residing anywhere within the module.
A module contained within a macro can effectively provide labels local to thatmacro.

Strat

@Lab1

@SetTact@Lab1

module
moveq
bra
...
subq.w
beq.s
...
rts
modulemove.w...
move.l...
move.lbgt.s
rts
modendmodend#1,d0@Lab1#1,count(a0)@SetTact#Tactic2(a0)a1,-(sp)(a1),d0@Lab1

Psy-Q Development System

LOCAL
Description

The LOCAL directive is used to declare a set of macro-specific labels.

SyntaxSee Also

LOCAL

symbol,..,symbol

MODULE

Remarks

Examples•The scope of symbols declared using the LOCAL directive is restricted to thehost macro.

•

The LOCAL directive does not force a type on the symbol set that makes up its
operand. In practice, therefore, such symbols can be used as equates, string
equates or any other type, as well as labels.

doorpos

macro
local
bsr.s
bsr

m_door1,m_door2,doorw
doorw
doorw

m_door1
m_door2equequdoor_start*\1
door_fin*\2

doorw

movem.w
move.w
move.w
move.w(a3)+,d0-d2(a4),d3
6(a4),d412(a4),d5

endm

Psy-Q Development System

CHAPTER 8

Structuring the Program
Normally, the organisation of the memory of the target machine does not match thelayout of the source files. The Assemblers however, use Groups and Sections tocreate a structured target memory and relocatable program sections.
This chapter covers the following topics and directives:••••

SECTIONGROUPPUSHS and POPS
SECT and OFFSET

Psy-Q Development System

GROUP
Description

This directive declares a group with up to seven group attributes.

SyntaxGroupName

GROUP[Attribute,..Attribute]where an attribute is one of the following - see below for descriptions:
WORD
BSS
ORG(address)
FILE(filename)
OBJ(address)
SIZE(size)
OVER(GroupName)
See Also

SECTION

Remarks

Group Attributes are interpreted as follows:
WORD - the group may be accessed using absolute word addressing. Note that thiswill only have an effect if the ow+ parameter has been used to allow optimisation to
occur.

ExampleGroup1

group

word

BSS - no initialised data to be declared in this group.
ExampleGroup1group

bss

ORG - sets the ORG address of the group, without reference to the other groupaddresses. If this attribute is omitted, the group will be placed in memory, following
on from the end of the previous group.

Psy-Q Development System

Example
G1
G2
G3

org
group
group
group

$100
org($400)

will place the groups in the sequence G1,G2,G3

FILE - outputs a group, such as an overlay, to a its own binary file; other groups will
be output to the declared file.
ExampleGroup1

grouporg($400),file("charov.bin")

OBJ - sets the group's OBJ address. Code is assembled as if it is running at the OBJ
address but is placed at the group's ORG address. If no address is specified then the
OBJ value is the same as the group's ORG address.
ExamplesGroup1

grouporg($400),obj($1000)

Group2

grouporg($800),obj()

SIZE - specifies the maximum allowable size of the group. If the size exceeds the
specified size, the assembler reports an error.
ExampleGroup1groupsize(32768)

OVER - overlays this group on the specified group. Code at the start of the second
group is assembled at the same address as the start of the first group. The largest of
the overlayed groups' sizes is used as the size of each group.
Note: It is necessary to use the FILE attribute to force different overlays to be
written to different output files.
ExampleGroup2groupover(Group1)

Psy-Q Development System

SECTION
Description

This directive declares a logical code section.

SyntaxSECTION.size SectionName[,Group]
SectionName SECTION.size [Attribute,..Attribute]
The second format is a special case, designed to allow definition of a section withgroup attributes - see below for a description.

See Also

GROUP

Remarks

Example•Unless the section has been previously assigned, the section will be placed in an
unnamed default group, if the GROUP name is omitted•

It is possible to define a section with group attributes. The assembler willautomatically create a group with the section name preceded by a tilde (~) andplace the section in it.

Sect1

sectionbss

defines Sect1, with the BSS attribute, in a group called ~Sect1.
•

The size parameter can be .b, .w or .l; if the parameter is omitted, the default size
is word. When a size is specified on a section directive, alignment to that size isforced at that point. The start of the section is aligned on a boundary based on
the largest size on any of the entries to that section - in all modules in the case of
linked code.
Note: If a section is sized as byte, the EVEN directive is not allowed in thesection. Furthermore, the CNOP directive cannot be used to re-align the
Program Counter to a value greater than the alignment of the host section- see chapter 5.

Psy-Q Development System•If sections are used to structure application code, only a single ORG directive
can be used; this must precede all section definitions. Groups and Sections may
have ORG attributes to position them.
No ORG directives or attributes are permitted when producing linkable output.
Within a group, sections are ordered in the sequence that the Linker encounters
the section definitions.

ExamplesThe following example shows the use of Groups and Sections to impose a structureon the target memory:
•
•
•
•
•

preliminary version checks and includes;group declarations;a section of variables, at the start of the program, to take advantage of absoluteaddressing modes;
a section of application code;a section of unitialised data.

opt

c-,ow+,oz+,v+

equ

0

includeincludeinclude"miscmac.obj""rooms.obj""output.obj"

numvecs

org
equ
regs

$100
$100>>2
pc=progstart

amiga

if
equ
endif

~def(amiga)
1

ntsc

if
equ
endif

~def(ntsc)
1

version; 0 => full version; 1 => demo version; 2 => test version

Psy-Q Development System

g_short
g_codeg_bss

firstbss

group
group
group

word

sectionsectionsectionsectionsectionshort1,g_short
short2,g_short
shortcode,g_shortcode,g_code
bss,g_bss

equ

*

bss

PUSHS and POPS
Description

These directives allow the programmer to open a new, temporary section, then returnto the original section. PUSHS saves the current section, POPS restores it.

SyntaxPUSHS
POPS

Examplesplotcomp

passdlmove.w
move.w
bsr.s
move.w
move.w
addq.w
...
equ
pushs

d0,-(sp)d2,-(sp)
pcomp(sp)+,d2(sp)+,d0#1,d2

section
dc.l
lea
cmp.w
blo.s
...
pops

dolight
passdlnrg_len(a2),a2#endnrg,a2@1*This example shows PUSHS and POPS being used to pass system information
between sections, in the form of the location counter.

Psy-Q Development System

SECT and OFFSET
Description

The SECT function returns the address of the section in which the symbol in thebrackets is defined. The OFFSET function returns the offset value from the
beginning of the section.

SyntaxSECT(expression)

OFFSET(expression)

Remarks

Examples•If a link is being performed, the SECT function is evaluated when it is linked; if
there is no link, it will be evaluated when the second pass has finished.

•

Likewise, if a link is being performed, the OFFSET function is evaluated when it
is linked; however, if there is no link, the OFFSET will be evaluated during thefirst pass.

dc.w
dc.w
dc.w

sect(Table1)
sect(Table2)
offset(*)

Psy-Q Development System

CHAPTER 9

Options, Listings and Errors
This chapter completes the discussion of the Assemblers and their facilities. It covers
methods of determining run-time Assembler options, producing listings and errorhandling, as well as passing information to the Linker:
•
•
•
•
•
•
•
•

OPT
Assembler Options
PUSHO and POPO
LIST and NOLISTINFORMFAIL
XREF, XDEF and PUBLIC
GLOBAL

Psy-Q Development System

OPT
Description

This directive allows Assembler options to be enabled or disabled in the application
code. See ‘Assembler Options’ below for a full listing.

SyntaxSee Also

OPT option,..option

PUSHO, POPO

Remarks•

An option is turned on and off by the character following the option code:+ (plus sign) = ON
- (minus sign) = OFF•

ExamplesOptions may also be enabled or disabled by using the /O switch on the Assembler
command line - see Command Line Syntax, chapter 2.

opt

an+,l:+,e-

opt

oaq+,osq+,ow+

Psy-Q Development System

Assembler Options
The following reference list shows the default settings for the various options andoptimisations available during assembly. More detailed descriptions are given below.
OptionDescription

Default

AE
AN
C
D
E
Lx
S
V
W
WS
X
#

Enable Automatic Even Mode
Enable Alternate Numeric mode
Activate/ Suppress Case sensitivity
Allow EQU or SET to descope local labels
Print lines containing errors
Substitute x for Local Label signifier
Handle equated names as labels
Write Local Labels to symbol file
Print warning messages
Operands may contain white space
Assume XREFs in defined section
Use # for literals and ## for immediates (SH2 only)

On
Off
Off
Off
On
Off
Off
Off
On
Off
Off
Off

Optimise to PC relative addressing
Optimise short branches
Optimise absolute long addressing
Optimise zero displacements
Optimise adds to quick form
Optimise subtract to quick form
Optimise move to quick form

Off
Off
Off
Off
Off
Off
Off

68000 only:
OP
OS
OW
OZ
OAQ
OSQ
OMQ

Note: 68000 Assembler optimisation options are not valid for forward references.

Psy-Q Development System

Option Descriptions
AE - Automatic Even
When using the word and long word forms of DC, DCB, DS and RS, enabling thisoption forces the program counter to the following word boundary prior to
execution. The default setting for this option is AE+.
AN - Alternate Numeric
The default setting for this option is AN- but setting it to AN+ allows the inclusion ofnumeric constants in Zilog or lntel format, i.e. followed by H, D or B to signify Hex,
Decimal or Binary. See also the section on the RADIX directive - chapter 3.
C - Case Sensitivity
When this option is set to C+, the case of the letters in a label's name is significant;for instance, SHOWSTATS, ShowStats and showstats would all be legal. The
default setting is C-.
D - Descope Local Labels
The default setting for this option is D- but if it is set to D+, local labels will be
descoped if an EQU or SET directive is encountered.
E - Error Text Printing
If this option is enabled, the text of the line which caused an Assembler error will be
printed together with the host file name and line number. The default setting for thisoption is E+.
L- Local Label Signifier
Local labels are signified by a preceding AT sign ( @ ). This option allows the use of
the character following the option letter as the signifier. Thus, L: would change thelocal label character to a colon (:). L+ and L- are special formats that toggle thecharacter between a dot (+) and an @ sign (-). The default setting is L-.
W - Print warning messages
When this option is set to the default setting of W+, the Assembler will identify
various instances where a warning message would be printed but assembly willcontinue. Disabling the W option will suppress the reporting of warning messages.
WS - Allow white spaces
The default setting for this option is WS- but if it is set to WS+, operands may
contain white spaces. Thus, the statement:
dc.l

1 + 2

defines a longword of value 1 with WS set Off, and a longword of value 3 with WS
set to On.

Psy-Q Development System

X - XREFs in defined section
The default setting for this option is X- but if it is set to X+, XREFs are assumed to
be in the section in which they are defined. This allows optimisation to absolute word
addressing to be performed provided that the section is defined with the WORD
attribute or is in a Group with the WORD attribute.
# - Use # for literals (SH2 only)
The default setting for this option is #- but if it is set to #+, # is used to indicate aliteral pool instead of the default = with the SH2 Assembler. As a result, the ##characters have to be used in front of immediate values.
OP - Optimise PC Relative
Switches to PC relative addressing from absolute long addressing if this is permissible
in the current code context.
OS - Optimise Short Branch Optimisation
Backwards relative branches will use the short form if this is permissible in thecurrent code context.
OW - Optimise Absolute Long Addressing
If the absolute long addressing mode is used but the address will only occupy a word,
the Assembler will switch to the short form.
If a size is specified no optimisation will take place, thus:
move.wd0(fred) .1

will be left as absolute long.
OZ - Optimise Zero Displacements
If the address register is used with a zero displacement, the Assembler will switch tothe address register indirect mode.
OAQ, OSQ and OMQ - Optimise to Quick Forms
When these options are enabled, provided that it is permissible in the current code
context, all ADD, SUB and MOVE instructions are coded as quick forms.

Psy-Q Development System

PUSHO and POPO
Description

The PUSHO directive saves the current state of all the assembler options; POPO
restores the options to their previous state. They are used to make a temporary
alteration to the state of one or more options.

SyntaxPUSHOPOPO

See Also

OPT

ExamplesSetAlts
SETALTS

pusho
opt

ws+, c+=dc.w

height * time
256 * SetAlts

popo

LIST and NOLIST
Description

SyntaxThe NOLIST directive turns off listing generation; the LIST directive turns on thelisting.

NOLIST
LIST

indicator

where indicator is a plus sign (+) or a minus sign (-).

Psy-Q Development System

Remarks•

If a list file is nominated, either by its inclusion on the Assembler command line,
or in the Assembler’s environment variable, a listing will be produced during thefirst pass.

•

The Assembler maintains a current listing status variable, which is originally set
to zero. List output is only generated when this variable is zero or positive. The
listing directives affect the listing variable as follows:••••

ExamplesNote

NOLIST sets it to -1;
LIST, with no parameter, zeroises it;
LIST + adds 1;
LIST - subtracts 1.

Directive

Status Listing produced?

nolistlist list
list list list +list +

-1
-2
0
-1
-2
-1
0

no
no
yes
no
no
no
yes

In the following circumstances, the Assembler automatically suppresses production oflistings:•

during macro expansion;•for unassembled code because of a failed conditional.

These actions can be overridden by:•including the /M option on the Assembler command line to list expanding
macros;•including the /C option on the Assembler command line to list conditionallyignored code - see Command Line Syntax, chapter 2.

Psy-Q Development System

INFORM and FAIL
Description

The INFORM directive displays an error message contained in text which may
optionally contain parameters to be substituted by the contents of expressions after
evaluation. Further Assembler action is based upon the state of severity. The FAIL
directive is a pre-defined statement, included for compatibility with other Assemblers.
It generates an “Assembly Failed” message and halts assembly.

SyntaxINFORM

severity,text[,expressions]

FAIL

Remarks•

These directives allow the programmer to display an appropriate message if anerror condition is encountered which the Assembler does not recognise.

•

Severity is in the range 0 to 3, with the following effects:
0 : the Assembler simply displays the text;
1 : the Assembler displays the text and issues a warning;
2 : the Assembler displays the text and raises an error;
3 : the Assembler displays the text, raises a fatal error and halts the assembly.

•

ExamplesText may contain the parameters %d, %h and %s. They will be substituted by
the decimal, hex or string values of the following expressions.

TableSize equ
MaxTable equ
ifinforminformendif

TableEnd-TableStart
512
TableSize>MaxTable
0,"Table starts at %h and&is %h bytes long",&
TableStart,TableSize
3,"Table Limit Violation"

Psy-Q Development System

XDEF, XREF and PUBLIC
Description

If several sub-programs are being linked, use XDEF, XREF and PUBLIC to refer tosymbols in a sub-program which are defined in another sub-program.

SyntaxXDEF
XREF.size

symbol[,symbol]
symbol[,symbol]

PUBLICPUBLICon
off

Remarks

Examples•In the sub-program where symbols are initially defined, the XDEF directive isused to declare them as externals.

•

In the sub-program which refers the symbols, the XREF directive is used toindicate that the symbols are in a another sub-program.

•

The Assembler does not completely evaluate an expression containing an
XREFed symbol; however, resolution will be effected by the linker.

•

The PUBLIC directive allows the programmer to declare a number of symbols as
externals. With a parameter of on, it tells the Assembler that all further symbols
should be automatically XDEFed, until a PUBLIC off is encountered.

Specifying a size of .w on the XREF directive indicates that the symbol can beaccessed using absolute word addressing.
Sub-program A contains the following declarations :xdef
Scores,Scorers...
The corresponding declarations in sub-program B are:OriginForce
Rebound

xdef
xref
...

PointsTable
Scores,Scorers

public=dhdhpublicon
MainCharspeed*origin
45*angle
off

Psy-Q Development System

GLOBAL
Description

The GLOBAL directive allows a symbol to be defined which will be treated as either
an XDEF or an XREF. If a symbol is defined as GLOBAL and is later defined as alabel, it will be treated as an XDEF. If the symbol is never defined, it will be treatedas an XREF.

Syntax

GLOBALsymbol[,symbol]

See Also

XREF, XDEF, PUBLIC

Remarks

This is useful in header files because it allows all separately assembled sub-programs
to share one header file, defining all global symbols. Any of these symbols later
defined in a sub-program will be XDEFed, the others will be treated as XREFs.

Psy-Q Development SystemPsy-Q Development System

C H A P T E R 10

Adapter Firmware
Debugger stub services include fileserver functions which allow the Saturn to accessfiles on the host machine’s hard disk as well as some specific Debugger functions.
These fileserver functions are also accessible as ‘C’ callable functions and the pollhost
function as a ‘C’ macro, provided by the default library LIBSN.LIB.
These facilities are discussed in the following two sections:••‘C’ Library Functions
Assembly Language Facilities

Psy-Q Development System

The ‘C’ Library Functions
The following are provided by LIBSN.LIB and declared in LIBSN.H. The majority
are fileserver functions but there is also one macro to provide feedback for the
Debugger.
pollhost
PCinitPCopenPClseek
PCreadPCwritePCclosePsy-Q Development System

The Pollhost Macro
Description
This causes the target box to poll the host PC, allowing access to the target memory
when it is running, i.e. not single stepping.
These periodic calls enable the Debugger to display and edit memory and allow
intervention to stop/step/trace the target program.
Syntaxpollhost is defined as a macro:#definepollhost()

asm(“trapa #33”)/* Ox0400 */so its syntax is obvious:
pollhost()

Remarks
A macro is used so the call is inline; this preserves the variable scope.
This macro should be included in the user source code for the Debugger to operatecorrectly. It is responsible for transferring data to the host Debugger, so should be
put in the main loop or the vertical blank interrupt of the program to be debugged.
This call takes time to transfer the data; if however, updates are turned off or the
Debugger is exited, the call will return immediately.
A suitable Poll rate would be 25 to 100 times a second. The poll call may sensibly beplaced in the program's main loop or in the VBL interrupt handler. The Poll call takes
very little time if the host is not requesting or sending any data. If the host requests
access to the target memory then the call will take a little longer.

Note: Poll host is not necessary for NMI modified Saturns, including Saturn CDEmulators.

Psy-Q Development System

The PCinit Function
Description
This function re-initialises the host filing system, closes open files etc…

Prototype
int

PCinit (void)

passed:return:void
error code (0 if no error)

Psy-Q Development System

The PCopen Function
Description
This function opens a file on the host machine.

Prototype
int

PCopen (char *name, int flags, int perms)

passed:PC file pathname
open mode (0=read access, 1=write access, 2=read/write access)permission flags this should be set to 0

return: file-handle or -1 if error

Psy-Q Development System

The PClseek Function
Description
This function seeks the file pointer to the specified position in the file.

Prototype
int

PClseek (int fd, int offset, int mode)

passed: file-handle
seek offset
seek mode(mode 0=rel to start, mode 1=rel to current fp,
mode 2=rel to end)
return: absolute value of new file pointer position

Remarks
To find the length of a file which is to be read into memory, perform:
Len = PClseek( fd, 0, 2);This will set Len to the length of the file and can then be passed to PCread().

Psy-Q Development System

The PCread Function
Description
This function reads a specified number of bytes from a file on the host machine.

Prototype
int

PCread (int fd, char *buff, int len)passed: file-handle
buffer address
count
return: count of number of bytes actually read

Remarks
Unlike the assembler function this returns a full 32 bit count.
PCread should not be passed extreme values of count, as could be achieved on a
UNIX system, as this will cause the full amount specified to be transferred i.e. notjust to the end of the file.
To find the length of a file and read it into memory, perform:
Len = PClseek( fd, 0,2);
PClseek( fd, 0,0);
Num = PCread( fd, buff, Len);

Note: You must PClseek back to the beginning of the file before you try to readfrom it.

Psy-Q Development System

The PCwrite Function
Description
This function writes the specified number of bytes to a file on the host.

Prototype
int

PCwrite (int fd, char *buff, int len)passed: file-handle
buffer address
count
return: count of number of bytes actually written

Remarks
Unlike the assembler function this provides for a full 32 bit count.

Psy-Q Development System

The PCclose Function
Description
This function closes an open file on the host.

Prototype
int

PCclose (int fd)

passed: file-handle
return: negative if error

Psy-Q Development System

The PCcreat Function
Description
This function creates a new file on the host.

Prototype
int

PCcreat (char *name, int perms)

passed: PC file pathname, permission flags
return: file-handle or -1 if error

Psy-Q Development System

Assembly Language Facilities
The adapter firmware provides some useful functions which can be accessed from theSH2 cpus via TrapA calls. These functions allow user software to interact with theadapter downloader firmware and to change the configuration of the adapter
firmware.
Also, there are a few duplicate functions accessed via the 68000 LineA interface, thatis, 68000 instructions with opcodes $Axxx. In most cases, the default configurationis adequate and programmers will mainly be interested in the Poll Host calls (TrapA#$21 and dc.w $A000).

TrapA calls

The following functions are currently supported on the SH2s:-

TrapA #$21 - Poll the Host PC.

TrapA #$22 - Soft Re-Entry to firmware downloader program.
This has the effect of stopping execution of the user program at the next instruction
after the TrapA. Control is returned to the adapter downloader firmware which will
sit idle, awaiting commands from the host. This allows insertion of temporary pause
points so that results can be examined in the Debugger; simply pressing the run
button allows the program to continue from that point.

Opcodes

The following functions are currently supported on the 68000:-

Opcode $A000 - Poll the Host PC.
Opcode $A003 - Soft Re-Entry to firmware downloader program.

Psy-Q Development System

Fileserver Functions
The target adapter also contains software to provide fileserver functions. These areaccessed via TrapA #$23 on the Master SH2. Note that most functions return -1 in
r0 when a failure occurs. A standard error code can be fetched by calling TrapA #$23
with r0 still containing -1. The file error code will be returned in r0.

TrapA #$23 calls

The following functions are supported on the Master SH2:-

Initialise remote filing system:
This function resets the disk system of the host ready for a new session. All remoteopened files are closed.
Passed:r0.l

0Passed:

r0.l
r4.l
r5.l

1
Pointer to filename string (null terminated)
File mode (0=Normal)

Returns:r0.lFile handle (-1 if failure)

Passed:

r0.l
r4.l
r5.l

2
Pointer to filename string (null terminated)
File mode (0=ReadOnly, 1=WriteOnly, 2=Read/Write)

Returns:r0.lFile handle (-1 if failure)

Passed:

r0.l
r4.l

3
File handle

Returns:r0.l-1 if failure

Create file:

Open file:

Close File:

Psy-Q Development System

Read bytes from file to memory:
Passed:

r0.l
r4.l
r5.l
r6.l

4
File handle
Address of memory buffer
No of bytes to be read from file

Returns:r0.l

No of bytes actually read (-1=failure, 0=end of file)

Write bytes from memory to file:
Passed:

r0.l
r4.l
r5.l
r6.l

5
File handle
Address of memory buffer
No of bytes to written from buffer

Returns:r0.l

No of bytes actually written (-1 if failure)

Move File Pointer (seek):
Passed:

r0.l
r4.l
r5.l
r6.l

6
File Handle
OffsetSeek Mode

Returns:r0.l

New Absolute File Position (-1 if failure)If r6.l =0 then seek is relative to start of file;If r6.l =1 then seek is relative to current file pointer;If r6.l =2 then seek is backwards from the end of the file.

Get File Error Code:
Passed:r0.l-1Returns:r0.lFile Error CodeThe file error codes returned match the C standard error codes defined in the<errno.h> header.

Psy-Q Development System

C H A P T E R 11

The DBUGSAT Debugger
DBUGSAT is a full source level Debugger, as well as a traditional symbolic
Debugger. This allows source code to be viewed, run and traced, stepped-over,breakpoints set and cleared.
The original symbolic debug facilities are all still available. A source level display willrevert to a symbolic disassembly, when no source level information is available.
The following Debugger topics are discussed in this chapter:
•
•
•
•
•

Command Line Syntax
Configuration
Activity Windows
Debugger Options
Menu and Keyboard Usage

At the end of the chapter a short ‘tour’ of the Debugger provides a guide to its mostimportant features; use this in conjunction with the included sample C program.

Psy-Q Development System

Debugger Command Line
SyntaxDBUGSAT [switches] [filename [filename...]]DBUGSAT ?
displays a help message.

Remarks

Filename specifies the name of a file containing symbols, produced by using the /zd
option during assembly. If no extension is shown, a default extension of .SYM will
be added. Multiple filenames are allowed and must be separated by a space - thesymbol files will then be loaded in the order specified.

Switches/c-Turn case sensitivity OFF (+ for ON)/dDisable automatic run-to-main at C program start-up.

/efile[,file,file]

Load target machine with CPE file(s).

/f$xxxxxxxx

Find line number and file for address $xxxxxxxx.

/hHalt target machine when Debugger starts.

/i###

Specify update interval (in 1/18ths sec).

/m#

Sets the Debugger mouse sensitivity;# is a number between 1 to 4 - default is 3.
DBUGSAT drives the mouse itself. This overcomes someshortcomings exhibited by the Microsoft Mouse driver,particularly in 132 column mode.

/m+

Use the current system mouse driver; later versions of theMicrosoft drivers (8 upwards) allow the mouse to be used ina DOS window.

/m-

Revert to DBUGSAT mouse driver.

Psy-Q Development System

/r##Specify data screen rows in video bios.

/R

Use alternative mnemonics in register window.

/sfileOverride default configuration filename.

/t#

Set target SCSI device number (override default setting).

/u-Turn continual update mode OFF (+ for ON).

/vexprtext

Evaluate expression text and put result to standard output
device.

/&expr,.. expr

List of parameter expressions, separated by commas.

Remarks•

Source level mode can be used if a suitable Symbol File is specified on thecommand line. This file contains symbols and additional source level information
produced by the /zd option in the Assembler - see chapter 2.. See chapter 11 - formore about source level debugging.

•

Expressions passed to the Debugger using the /& switch can be referred to frominside the Debugger in the form &0, &1, etc., where 0 means the first expression
on the command line, 1 means the second etc.

Psy-Q Development System

Configuration Files
When DBUGSAT is loaded, it accesses a Configuration File, containing information
about the current Debugger environment. The current configuration can be saved at
any time during an active Debugger session. The default filename can be overriddenwith an option on the command line (/s) or at run-time, so that the most frequently
used configurations are always readily available.

Configuration File Names•

The normal Configuration File name is DBUGSAT.C##, where the first number
is the target SCSI ID number, and the second number is the virtual screen.
Typically, therefore, the configuration loaded at start-up is DBUGSAT.C00.

•

If that file is not located the Debugger will look for a suitable defaults file; thecurrent directory will be searched for a default filename built from the target
name string. This will typically be DBUGSAT.CFG.

Contents of Configuration File
A Configuration File can include the following information:
•
•
•
•
•
•
•
•
•

Read Memory Ranges;
Write Memory Ranges;
Video type and usage;
Label Level;
Colour and Mono attributes;
Default Tab Settings for various filetypes;
Window Type and Display position;
Breakpoints;
History details.

Psy-Q Development System

Activity Windows
The Debugger display consists of one or more activity windows. The number ofwindows, the contents of each window and the window size, can all be specified at
run-time. The default display consists of two windows; the upper one normallycontains a display of the registers, the lower window shows the disassembly of thetarget program code.
The Debugger can run up to 10 virtual screens; each screen has its own configuration
file - see chapter 11. Alternate screens can be accessed by pressing Alt-n, where n is
the screen number 0 - 9 and 0 means screen 10.

The Debugger Display, with Register and Disassembly Windows

Psy-Q Development System

Window Types
The Register window provides a complete view of the selected processor's registers.
Register contents can be changed by:••

Typing directly at the current cursor location orEntering an expression by pressing the ENTER key to display an Expression
Input window.

The Disassembly window shows the contents of the target memory as disassembled
code. If a Symbol File has been loaded into the Debugger, symbol names aresubstituted as appropriate. Breakpoints (optionally with conditions and counts) canbe added to any line and the code run, traced or stepped.

The Debugger, with display in Register and Hex Mode

Psy-Q Development SystemIf the PC of the target machine is pointing at a line in the current disassembly display,
it is indicated by a greater than sign (>). If a line contains a breakpoint, that line isdisplayed in a different colour; the breakpoint count and expression details are shownat the end of the line.
The Hex window displays memory in hexadecimal, either in byte, word or long wordform. Like the Register window, the contents can be changed by any of the following
methods:•••

Typing directly at the current cursor location
Entering an expression for evaluation by pressing the ENTER key to display an
Expression Input window
Pressing + or - to increment or decrement the value at the cursor position

The Debugger, with Source, Variable and Watch display

Psy-Q Development System

The Watch and Variable windows allow variables, tables and code locations to bemonitored as your program is running.
The Variable window automatically tracks the scope of your C program. As you
trace though your program and the variable scope changes, this window will always
display the current local variables. The up and down arrow keys and pg-up and pgdown allow you to scroll the window to see all your variables.
The Watch window performs a similar function for user specified expressions and istypically used to display global variable data. You can enter all your global variablesin this window by pressing Alt-G. Specific C or Assembler expressions (global andlocal) can be entered at the cursor position by pressing INSert. Conversely, entries
can be deleted using DELete. All entries in a Watch window are saved when you exit
and restored the next time you run the Debugger.
In both the Var and Watch windows pointers and arrays can be de-referenced andstructures, unions and enums can be opened up for closer examination, by placing the
cursor over the relevant entry and pressing '+' from the numeric keypad. They can be
subsequently closed by pressing '-'. This will even work for local register structures
within unions within structures etc.
The Text or File window allows a text file to be viewed directly. Within a Filewindow you can change to a different text file by pressing ENTER. The Debugger
will then request the name of the new file to load.
The Source Level window is an extension of the File window. Most source level key
commands are the same as for a Disassembly window.
To enter source mode, tell the File window to display program source at a particularaddress. The easiest way to do this is to hit the TAB key. As in a Disassembly
window this causes the window to locate to the current program counter address; if
the Debugger has source level information for that part of your program it will
display corresponding source code.
Alternatively you can enter source mode by typing Alt-G (for Goto location) andthen entering the address you wish to locate to (any expression or Assembly languagelabel name or a C function name - such as main will do fine).
Note that in Source mode, line numbers are added to the left side of the window
display and the PC line is indicated with a '>' after the line number, similar to a
Disassembly window.
If you wish to view text which is truncated off the right side of the window then thewindow can be scrolled to the left and right using the left and right cursor keys.

Psy-Q Development System

You can step, trace, run to cursor and set breakpoints in the source code in much thesame way as a for Disassembly window. The cursor in the currently active text
window will track the PC during a trace. Note, however, that unlike tracing in a
Disassembly window, a trace at Source Level may trace more than one instruction as
it will trace the entire source line, which, if it is a macro or a 'C' source line, maycorrespond to the execution of one or more instructions. Similarly F8 (Stepover) will
step-over the entire source line, which could be equivalent to stepping over several
subroutine calls.
If you are unsure of how a Source Level operation will behave, a Disassembly
window can be viewed at the same time to determine how the operations correspondto actual processor instructions. If you attempt to step into a C function or Assembly
language subroutine for which the Debugger does not have any source level
information then the Debugger will attempt to perform a step-over operation instead.
If this is not possible (e.g. if the code without source level information is jumped torather than called), then the window display will switch to Disassembly mode. The
trace can be continued and when the PC returns to a region for which there is Source
information, the window will switch back to the Text display.
In order to use any of the Source Level features you must have the necessary extra
debugging information in your Symbol File(s). If it is not present then the Debugger
will be unable to switch to Source mode and Source Level operations will produce
appropriate error messages. This information is added to the Symbol Files by the Ccompiler if you add the -g switch to your CCSAT command line or by the Assembler
if you specify the /zd switch on the ASMSAT command line.
The Symbol File normally contains the full original pathnames of all files used to build
your project. When Source Level debugging the Debugger will attempt to load thosefiles from the same locations. In some cases this may not be convenient e.g. if part ofthe project was built by another developer on a different PC or on a network drive;
even if you have a copy of the appropriate Source Files you may not have them at thesame location.
To get around this you can provide the Debugger with a search patch for Source
Files. To do this just select a Source File window and type Alt-P. You will beprompted to enter a normal DOS search path. This search path can contain many
entries and be as long as you wish.
e.g.
c:\;c:\temp\myfiles;c:\gnumips\src\common

Psy-Q Development System

The Debugger will first look for the file in the directory specified in the Symbol File(determined when the project was built). If it cannot locate the file at the original
location then it will search for it by name at the following locations:c:\filename.sym
c:\temp\myfiles\filename.sym
c:\gnumips\src\common\filename.sym
The first filename match located will be assumed to be the correct Source File.
The search path will be saved in the Debugger Configuration File when you exit the
Debugger. To remove an existing search path just specify a blank search path string.

Psy-Q Development System

Additional Debugger Features
Automatic Overlay Support allows the Debugger to dynamically track overlays as
they are loaded into your program and work with the Source Files and variables
specific to that overlay. This requires no modification to your Source Code at all.
You only need to tell the Linker which files will overlay in memory. Any number ofconcurrent overlays are supported over multiple memory areas. A simple overlay is
included with the Psy-Q software.
Big Text Screens allow you to view as much information as possible by working in ahigher text resolution. This is achieved by putting the text screen in the required
resolution before running the Debugger. At least 80x50 is recommended but the
Debugger will happily work in higher text resolutions up to 132x66. Most modern
VGA cards are capable of 132 column text modes and come with a utility to set such
resolutions. Psy-Q also includes the BV.EXE program which will take any screenmode and adapt it to 30, 32, 60 or 64 lines. Use the /r50 debugger command line
switch if you prefer to edit at 80-25 but debug at 80x50.
Multiple Text Screens are available when a single 132x64 screen is not enough todisplay all your debug information. Up to 10 virtual screens can be used; switch
between them by pressing Alt-n (where n is a digit 1,2,3,4,..0). The configuration ateach screen is saved when you switch and restored when you switch back; these
configurations are also saved when you exit the Debugger.
Name Completion is provided by all prompts where C or Assembler labels areentered. Type the first few letters of the name and press Ctrl-N. If the required label
does not appear, repeat Ctrl-N to ‘toggle’ through the alternatives. This facility also
works for a name in the middle of an expression.
Prompt Histories are provided to allow you to select from your history of priorentries. This information is saved when you exit the Debugger and restored for yournext debugging session.
CPU Hardware Breaks can be used to cause the CPU to stop when a specificmemory location is read from or written to. Hardware breaks can be accessed bytyping Alt-B.
Note that C or Assembler syntax can be used with this facility.
In Assembler mode you will be prompted for a mask value. This mask has 1 bit toenable, therefore a mask value of -1 ($FFFFFFFF) will be the usual value to trap
one particular address.
In C mode you only need to enter the name of your C variable; the Debugger willautomatically calculate the correct address and mask value.

Psy-Q Development System

Using Debugger Windows
The following key strokes and mouse actions allow the programmer to exercise
control over the Debugger display - note that a complete list of all key options isgiven later in the chapter.

Moving Between Windows
Use one of the following methods to move between Debugger windows:•••

Press F1, followed by an up or down cursor key to point to the required window
Press Shift, plus up or down cursor key
Point and click at the required window

Selecting The Window TypeUse one of the following methods to change the type of the current window:••

Use the mouse to select the SET TYPE option from the WINDOW menu
Press Shift and F1

In each case a selection window is presented. To choose the new type - use themouse, type the initial letter or press the TAB key then ENTER.

Re-Sizing Windows
To change the size of a Debugger window:
1. Position the cursor in the required window
2. Press F2
3. Use the up or down cursor key to move the selected window edge to the desiredsize
4. Press ENTER to confirm
Press Ctrl-Z to re-present the original display.

Psy-Q Development System

Splitting An Existing Window
To add another window to the display:
1. Position the cursor in the required window
2. Press F3
3. Press a cursor key to specify the location of the new window
Note that the new window is the same type as the source window.

Joining Two Windows
To remove a Debugger window:
1.
2.
3.
4.

Position the cursor in the required window
Press F4
Use the up or down cursor key to select the window edge to be removed
Press ENTER to confirm

Moving The Cursor Within A Window
You can position the cursor by clicking at the new location with the left mousebutton. The cursor control keys also allow the re-positioning of the cursor in theselected window, as follows:•

Register Window - Use the four arrow keys to move between register values;
the HOME key positions the cursor in the top left register field.

•

Watch and Register Windows - Use the four arrow keys to move between
adjacent lines and characters; the HOME key positions the cursor in the top leftcharacter position.

•

Disassembly and Text Window - Use the up and down arrows to move thehighlight bar; the HOME key moves the line under the cursor to the top of thewindow.

•

Hex Window - Use the four arrow keys to move between adjacent lines andbytes/words; the HOME key moves the byte/word under the cursor to the top
left of the window.

Psy-Q Development System

Locking A Window
A window can be locked to dynamically display a specific memory region, by:•

Pressing Alt-L and entering an address or an expression which evaluates to an
address in the input box;•

Selecting the LOCK option from the WINDOW menu;•

Pressing Ctrl-L to turn the lock on and off.

•

Locking a display to the expression &0; this allows the Debugger to be started
with a window pointing to an address or label specified on the command line - seechapter 11.

If a lock expression is set, but de-activated by Ctrl-L, the Debugger will start-up
with the display initially positioned at the lock address, but the window start cansubsequently be changed with the cursor keys etc. as normal.

General Mouse Usage•

Clicking the left mouse button re-positions the cursor at the site of the click. If
the new position is in another window, this will become the active window.

•

Clicking the right mouse button on a register in the Register window will open
an Expression Input box.

•

Clicking the right mouse button on a memory field in the Hex window will open
an Expression Input box.

•

Clicking the right mouse button on a line in the Disassembly window toggles abreakpoint.

•

A window can be re-sized by clicking the left mouse button on a window edge
and dragging it to the new position.

•

Dragging a window border to the edge of the window deletes the window.

Psy-Q Development System

Keyboard Options
The following table is a complete list of keyboard options, categorised by function.
Many of these functions are duplicated by Menu options.

Expressions At many points in the session, the Debugger will prompt for input - this can often
take the form of an expression for evaluation. Expressions in the Debugger follow thesame rules as the Assembler (see chapter 3), with the following exceptions:••••

Prompts

Assembly language expressions may contain processor registers.
The Debugger assumes a default radix of hexadecimal, therefore, decimal
numbers must be preceded by a # sign.
Indirect addresses are indicated by square brackets [ ].
When the Debugger gets an indirect datum, it assumes a (32 bit) long word; thiscan be overridden by using the @ sign together with b or w following the square
bracket.

Each time that the Debugger requests input the reply is stored. These stored prompts
form a history which can be accessed (and then edited) at data entry time via the up
and down arrow keys. Note that, when the Debugger closes, the last ten historic
entries in each class are stored in the Configuration File, and restored the next timethat the Debugger is executed.

Leaving The Debugger
Ctrl-X
Alt-X
Alt-Z

Exit Debugger, without saving the current configuration
Exit the Debugger and save the current configuration
Exit to DOS shell; type EXIT to return to the Debugger

Window Handling
F1
Move to next window
F2
Re-size Window
F3
Divide Window into two
F4
Delete Window
Shift-Arrows Move to selected Window
Ctrl-Z
Zoom current Window; again to restore original display
Shift-F1
Select Window TypePsy-Q Development System

Debug Control
Ctrl-F2
Esc
Shift-Esc
Alt-R
Alt-I
Alt-U
F6
F7
F8
F9
Shift-F9

Re-download your CPE file to target and re-set PC
Halt the target, at first opportunity
Halt the target, turning off interrupts
Restore Registers from previous Save
Set the update interval; the interval is input in 18ths of a second, therefore,
18 means once a second, 9 means twice a second, etc
Toggle auto-update mode on or off
Run Target code until the instruction under the cursor is reached
Trace current instruction (or source line if in text display window)
Step-over current instruction; (as F7 but call instructions are stepped over)Run target code from current program location
Set temporary breakpoint at user specified address and run from current
location

File Accessing<>
Shift-F10

Upload memory from the target to a named file on the PC
Download a file from the PC to the target memory
Load a new configuration file

Miscellaneous
F10
Alt-H
Alt-D
Alt-n
Alt-N

Select a Menu Option
Hex Calculator; enter an expression to be evaluatedDisplay the amount of free memory
Switch to Virtual Screen n (1 - 9 plus 0= 10).
Label Continuation; enter first few letters from a label and press Alt-N tofind first match. Repeated Alt-N cycles through all matches.

Psy-Q Development System

Disassembly Window
Up/Down
Left/Right
PgUP/Dn
Home
Alt-G
Tab
Shift-Tab
Alt-L
Ctrl-L
Ctrl-D
Ctrl-S
Ctrl-N

Move highlight bar
Move display by one word
Move display by a page
Move display so that the highlighted line is at the top
Go to address specified in input window
Move the highlight bar to the Program Counter address
Make the Program Counter the same as the currently highlighted address
Lock the display to a specified address
Toggle Lock on or off
Disassembly memory to a PC text file
Search for a particular instruction fragment (as text, space as separator)
Continue search

File and Source Windows
Tab
Alt-G
Alt-T
Ctrl-S
Ctrl-N
Alt-P

Locate address of current PC and display corresponding source code
Locate source display to specified address
Override default tab settings for this window(prompts for a list of tab positions)Search for a text string
Continue searchSpecify source-file search path

Breakpoints
Alt-C
Ctrl-CF5
Shift-F5
Shift-F6

Enter condition for the highlighted breakpoint
Enter count for the highlighted breakpoint
Turn highlighted breakpoint on or off
Clear all current breakpoints
Reset all current breakpoint counts

Psy-Q Development System

Hex Window
ArrowsPgUp/Dn
Home
Alt-W
ENTER
0-9, A-F
+
Alt-G
Alt-F
Ctrl-S
Ctrl-N

Move to adjacent byte/word/long word
Move display by one page
Move display so that currently highlighted byte/word/long word is at thetop
Switch display between byte, word and long word
Change contents of current location to the result of an expression; enteredin an input window
Directly change contents of highlighted location
Increment contents of highlighted location
Decrement contents of highlighted location
Go to address specified in input window
Move display to address contained in highlighted location
Search for a hex (or text if started with “ character) string(prompts for a space separated list of bytes/words/longs)
Continue search

Register Window
ArrowsHome
ENTER
0-9, A-F

Move to next register
Move to top left register
Change contents of current register to the result of an expression; enteredin an input window
Directly change contents of highlighted register

Watch Window
Up/Down
Home
Ins
Del
+
Tab
Right/Left

Move to next watch expression
Move to top watch expression
Add a new watch expression
Delete the highlighted watch expression
Opens information on the data under the cursor (structure, array etc.) orde-references the data if it is a pointerCloses expanded information
Changes the result display format of a C expression under the cursor
Increments/Decrements array index under the cursor (currently only if notexpanded with +)Psy-Q Development System

Var Window
Up/Down
Home
Ins
Del
+
Tab
Right/Left<>

Move to next watch expression
Move to top watch expression
Add a new watch expression
Delete the highlighted watch expression
Opens information on the data under the cursor (structure, array etc.) orde-references the data if it is a pointerCloses expanded information
Changes the result display format of a C expression under the cursor
Increments/Decrements array index under the cursor (currently only if notexpanded with +)(Also comma and dot) Crawls up and down the stack, adjusting the scope ofcurrent debugger display to that of calling functions. Top level is a
‘C’ callstack display.

‘C’ Callstack Display>
Enter(Also dot) Return to current scope
Display the variables of the scope under the cursor.

Psy-Q Development System

Menu Options
The DBUGSAT menu affords easy mouse access to some of the commonest
Debugger functions. Note that if no mouse is available, the Menu can still beaccessed by pressing F10.
FILE
ReloadDown
UploadDisassemble
Exit to DOS
Exit Debugger

Reload the last executable file Download
Load a file to the Target
Upload specified data from the Target to a named file on thePC
Send specified section of Disassembly to a named PC file
Exit to DOS shell; type EXIT to return to the Debugger
Exit the Debugger and save the current configuration

RUN
Go
Stop
To Address
Backtrace

Run Target code from the current Program Counter
Halt the Target machine, turning off all interrupts
Run to address specified in input window
This function provides an UNDO of the updates effectedby the latest trace (the Debugger keeps a record of about
200 instructions, depending on their content).

Notes: Updates to certain write Registers in the target machine and memory areas
designated as write only, cannot be undone.
WINDOW
Set Type
Lock
Print
Set Tabs

Select Window Type
Lock the display to the address entered in an input window
Output screen to system printerEnter up to 8 tab positions - in decimal separated by spaces

Note: The Set Tabs function is only relevant to File and Source Disassembly
windows.
CONFIG
Load
Save

Load a new configuration file
Save the current configuration to the specified filePsy-Q Development System

CPU
Save Regs
Reset Regs
Reset

Save the current state of the registers
Reload the previously saved register state
Reset the Target Processor

STEP

Trace Mode; traps and Line A calls are stepped over

STEPOVER

Stepover Mode; subroutine calls and DBRA instructions are
stepped over.

Multiple Units
Description

The Saturn has a number of different CPUs. These are accessible as different unit
numbers on the same SCSI target ID.
In the Sega Saturn, the Master SH2 is Unit 2, the Slave SH2 is Unit 1 and the68000 is Unit 2. While running the Debugger, press Alt-T to cycle between the
different CPUs.
While connected to one unit, all Debugger processing of the other units is suspended.
The other units can run but interaction with the host PC is not possible until that unit
is selected. Switching units in this way saves the current Debugger settings for that
unit, i.e. windows set-up, breakpoints and Symbol Files.
To aid readability of the displays when viewing multiple units, the Debugger supports
up to 10 virtual screens; each screen has its own configuration file.
At start-up, all Symbol Files will be loaded and correctly referenced depending on theunit number being viewed. To effect this, the Assembler writes the unit number into
the Symbol File.

Psy-Q Development System

The Link Software
The adapter hardware contains software in ROM to enable it to communicate withthe host PC. In addition, this ROM contains code to perform some functions whichmaybe useful in the development stages of a product.
The Target interface software hooks the following 68000 exception vectors by
default:
68000 Vector
2

3
4
5
6
7
8
9
10

Location
$0008
$000C
$0010
$0014
$0018
$001C
$0020
$0024
$0028

Meaning
Bus Error has occurred
Error in Address foundIllegal Instruction foundDivide by Zero
CHK exception
TRAPV exception
Privilege violation
Trace exception
Line-A Vector

In particular, the Illegal Instruction and Trace Vectors are necessary for the correctfunction of the Debugger; the Line-A Vector is used to provide various userfunctions.
The Target interface software also hooks the following SH2 exception vectors by
default:
SH2 Vector
32
33
34
35

Location
VBR+32
VBR+33
VBR+34
VBR+35Type
Trap Instruction
Trap Instruction
Trap Instruction
Trap Instruction

VBR is the Vector Base Register.
The application software should not attempt to modify any of these vectors.

Psy-Q Development System

Debugging Your Program Using Psy-Q
To get you started with the Psy-Q DOS Debugger, this section provides a quick
guide to some of its most important features. Follow this on-line with the simple C
program SAMPLE.C (included with the software) and experiment with the
Debugger commands.
Due to the confidential nature of the information subject to a Sega developer’s
license, we cannot provide example Saturn source code. This sample program does
not refer to confidential Saturn hardware details; the intention is merely todemonstrate some of the Debugger features.
To build the demo, change into the SAMPLE directory and compile the program
SAMPLE.C by entering the following command line:
ccsh -g -O0 -Xo$6010000 sample.c -osample.cpe,sample.sym

This calls the CCSH program to compile the C source. The -g switch tells CCSH toproduce full debugging information (necessary for Source Level debugging). The -oswitch specifies the output filenames.
This example will output the executable file SAMPLE.CPE and the Symbol File
SAMPLE.SYM.
At this stage you could execute the .CPE File by entering:
RUN SAMPLEThis would not be very useful however, as this example does not produce any Saturn
display; therefore, in order to examine the code you must debug the sample using
DBUGSH.
Start the Debugger by entering the following command line:
DBUGSH sample /e

In this case, ‘sample’ specifies the name of the Symbol File. The /e switch causes the
Debugger to also load the .CPE File (default = same name as the Symbol File butwith a .SYM extension).

Psy-Q Development System

The Debugger will now start up and present the default layout. This is divided into
two windows; the top will show the CPU Registers whilst the second will be a
Disassembly display.
If however, the Debugger finds a standard Psy-Q C start-up, it will automatically run
the program to the start of the C function main( ) and switch to C source mode; thelower window will then display this source code.

CPU Register and Source Windows

If the Source window is not already displayed, select it by:••

Clicking the lower window with the mouse or
Pressing Shift and a cursor key to change to an adjoining window

From this window you can single step and set breakpoints in your source code.

Psy-Q Development System

To View Local Variables
Split the current window by pressing F3 and down arrow. Change to the lower
window (by Shift-arrow or clicking on it with the mouse) and then make this a
VARiable window (Shift-F1, V).
Now return to the Source window and press F7 several times until you trace intoanother function. As you trace through the program, notice that the variable scopechanges and that the Var window always displays the current local variables.

Source Window and Var Window showing Local Variables

Psy-Q Development System

To View Global Variables
Create another window and set its type to Watch; now press Alt-G to enter all yourglobal variables in this window. You can also enter specific C or Assembler
expressions (global and local) at the cursor position by pressing INSert. Entries canbe deleted using DELete.
In both the Var and Watch windows, you can de-reference pointers and arrays oropen up structures, unions and enums by placing the cursor over the relevant entry
and pressing ‘+’ on the numeric keypad. Close them again by pressing ‘-’.

Opened Up Structures In Watch Window

Psy-Q Development System

Useful Debugging Commands
F5 - Toggle breakpoint at cursor (Source or Disassembly)
F6 - Run to current cursor location (Source or Disassembly)
F7 - Single step (Source or Disassembly)
F8 - Step-over (i.e. break on next instruction or source line)
F9 - Run
ESC - Stop

If your program is running around an endless loop and you have hardware interrupt
support enabled (this requires an appropriate downloader version on the target), you
can press ESC at any time to stop the target. If you do not have hardware interrupt
support enabled, you can still stop the target if you have a pollhost ( ) call in a suitablelocation, for example your program main loop or a regular interrupt handler.

For further details of the Debugger please refer to the earlier part of this chapter andkeep an eye on the Psy-Q BBS for further updates.

Psy-Q Development System

C H A P T E R 12

The PSYLINK Linker
The Psy-Q Linker PSYLINK is a fully-featured linker which works with allprocessor types. It facilitates the splitting of complex programs into separate,
manageable sub-programs which can be recombined by PSYLINK into a final, single
application.

This chapter discusses the linker together with the Librarian utility, under thefollowing headings:••••

Command Line Syntax
Linker Command Files
XDEF, XREF and PUBLIC
GLOBALThe Linker-associated Assembler directives are repeated here for ease of reference.

Psy-Q Development System

PSYLINK Command Line
Description

The PSYLINK link process is controlled by a series of parameters on the command
line, and by the contents of a Linker command file. The syntax for the command line
is as follows:

SyntaxPSYLINK [switches] objectfile(s),output,symbolfile,mapfile,libraries
If a parameter is omitted, the separating comma must still appear unless it is the lastparameter of the line.

Switches

Switches are preceded by a forward slash (/), and are as follows:/bSpecifies that the linker should run in 'big' mode. This allows
the linker to link larger programs but with a link-time penalty.

/cTells the linker to link case sensitive; if it is omitted, all names
are converted to upper case.

/dDebug Mode - perform link only.

/e symb=value

Assigns value to symbol.

/i

Invokes a window containing Link details.

/m

Output all external symbols to the map file.

/n maximum

Set the maximum number of object files, or library modules,
that can be linked, 1 to 32768; default = 256
Higher values require larger amounts of memory.

/o address

Set an address for an ORG statement.

/o ? address

Request to Target to assign memory for ORG.

/p

Output padded pure binary object code; ORGed sections ofcode are separated with random data. (equivalent of /pb
switch on assembler)/ps

Output ASCII representation of binary file in Motorolas-record format.

Psy-Q Development System

/p20 and /p21

Output pure binary file in SNES mode 20 or 21.

/r format

Create operating specific output (am = Amiga).

/u numberSpecify the unit number in a multi-processor target.

/x address

Set address for the program to commence execution.

/z

Clear all requested BSS memory sections.

Objectfile(s) A list of object files, output by the Assembler using the /l option. File names are
separated by spaces or plus (+) signs; if the file starts with an @ sign, it signifies thename of a Linker command file - See below for a description of the format.
Output

The destination file for the linked code; if omitted no output code is produced. If theoutput file name is in the format Tn:, the linked code is directly sent to the target
machine - n specifies the SCSI device number.

Symbolfile

The destination file for the symbol table information used by the Debugger.

MapfileThe destination file for map information.

Libraryfiles Library files available - see The PSYLIB Librarian chapter for further information.

Psy-Q Development SystemLinker Command Files
Command files contain instructions for the Linker, about source files and how toorganise them. The Linker command file syntax is much like the Assembler syntax,
with the following commands available:

Commands

name
name
name

name

INCLUDE filename
Specify name of object file to be read.
INCLIBfilename
Specify library file to use
ORG
address
Specify ORG address for output
WORKSPACE address
Specify new target workspace address
EQU
value
Equate name to value
REGS
pc=address Set initial PC value
GROUP
attributes
Declare group
SECTIONattributes
Declare section with attributes
SECTION
name[,group] Declare section, and optionally specify its
group
ALIAS
oldnameSpecify an ALIAS for a symbol name
UNIT
unitnum
Specify destination unit numberGroup attributes:
BSS
ORG(address)
OBJ(address)
OBJ( )
OVER(group)
WORD
FILE("filename")
SIZE(maxsize)group is unitialised data
specify group's org address
specify group's obj addressgroup's obj address follows on from previous groupoverlay specified group(68000 only) group is absolute word addressable
write group's contents to specified filespecify maximum allowable size

Remarks•

Sections within a group are in the order that section definitions are encounteredin the command file or object/library files.

•

Any sections that are not placed in a specified group will be grouped together atthe beginning of the output.

•

Groups are output in the order in which they are declared in the Linker command
file or the order in which they are encountered in the object and library files.

•

Sections which are declared with attributes, (i.e. not in a group) in either theobject or library files, may be put into a specified group by the appropriate
declaration in the Linker command file.

Psy-Q Development System

Examplescomdatacode
bssdata

includeincludeinclude"inp.obj""sort.obj ""out.obj"

org
regs

1024
pc=progstart

group
group
group

word

sectionsectiondatal,comdata
data2,comdata

sectionsectioncodel,code
code2,code

sectionsectiontables,bssdata
buffers,bssdata

bss

GLOBAL
Description

The GLOBAL directive allows a symbol to be defined which will be treated as either
an XDEF or an XREF. If a symbol is defined as GLOBAL and is later defined as alabel, it will be treated as an XDEF. If the symbol is never defined, it will be treatedas an XREF.

Syntax

GLOBALSee Also

XREF, XDEF, PUBLIC

symbol[,symbol]

Remarks
This is useful in header files because it allows all separately assembled
modules to share one header file, defining all global symbols. Any of these symbols
later defined in a module will be XDEFed, the others will be treated as XREFs.

Psy-Q Development System

XDEF, XREF and PUBLIC

Description

If several sub-programs are being linked, to refer to symbols in a sub-program which
are defined in another sub-program, use XDEF, XREF and PUBLIC.

SyntaxRemarks

Examples

XDEF
XREF

symbol[,symbol]
symbol[,symbol]

PUBLICPUBLIConoff• In the sub-program where symbols are initially defined, the XDEF directive isused to declare them as externals.
• In the sub-program which refers the symbols, the XREF directive is used toindicate that the symbols are in a another sub-program.
• The Assembler does not completely evaluate an expression containing an XREFed
symbol; however, resolution will be effected by the linker.
• Specifying a size of .w on the XREF directive indicates that the symbol can beaccessed using absolute word addressing.
• The PUBLIC directive allows the programmer to declare a number of symbols as
externals. With a parameter of on, it tells the Assembler that all further symbols
should be automatically XDEFed, until a PUBLIC off is encountered.

Sub-program A contains the following declarations :
xdef
xref.w...

Scores,Scorers
PointsTable

The corresponding declarations in sub-program B are:OriginForce
Rebound

xdef
xref
...

PointsTable
Scores,Scorers

public=dc.w
dc.w
publicon
MainCharspeed*origin
45*angle
off

Psy-Q Development System

C H A P T E R 13

The PSYLIB Librarian
If the Linker cannot find a symbol in the files produced by the Assembler, it can be
instructed by a Linker command line option to search one or more object module
Library files.
This chapter discusses Library usage and the PSYLIB library maintenance program:••

PSYLIB Command Line Syntax
Using the Library feature

Psy-Q Development System

PSYLIB Command Line
Description

The Library program, PSYLIB.EXE, adds to, deletes from, lists and updates
libraries of object modules.

SyntaxPSYLIB [switches] library module...module
where switches are preceded by a forward slash ( / ), and separated by commas.

See Also

PSYLINK

Switches/a

Add the specified modules to the library/dDelete the specified module from the library/l

List the modules contained in the library/uUpdate the specified modules in the library/xExtract the specified modules from the library

Library

The name of the file to contain the object module library.

Module list

The object modules involved in the library maintenance.

Using the Library feature•

To incorporate a Library at link time, specify a library file on the Linker commandline - see chapter 12.

•

If the Linker locates the required external symbol in a nominated library file, themodule is extracted and linked with the object code output by the Assembler.

Psy-Q Development System

C H A P T E R 14

The CCSH Build Utility
CCSH is a build utility to execute the C Compiler, Assembler and Linker.
CCSH makes use of the ASSH Assembler to process the assembly syntax producedby the GNU C Compiler. It is discussed in the following sections:• CCSH Command Line• Source Files

Psy-Q Development System

CCSH Command Line
Description

CCSH.EXE is a utility that simplifies the process of running the separate 'C' compiler
passes and then assembling and linking the compiler output. Using CCSH you need
only specify the input files and what output format you require, and then CCSH itself
will execute the tools required to generate the output.

SyntaxCCSH [options / filename[,filename...]]
The command line consists of a sequence of control options and source file names.
Options are preceded by a minus sign (-), and filenames are separated by commas.
Long command lines can be stored in separate control files. These can then be usedon the command line by using a ‘@’ sign in front of the control file name.

Options

Control
-E
-S
-c

Debug
-g...

Pre-process only. If no output file is specified output is send
to the screen.
Compile to assembler source
Compile to object file. If an output file is specified, then all output issent to this file. Otherwise it saved as the source file name with an.OBJ extension.

Generate debug information for source level debugging

Optimisation-O0
No optimisation (default)-O or -O1
Standard level of optimisation-O2
Full optimisation

General-W...
Suppress all warnings-Dname=val Define pre-processor symbol name, and optionally to the value
specified.
-UnameUndefine the pre-defined symbol name before pre-processing starts-v
Print all commands before execution-f...
Compiler option-m...
Machine specific option

Psy-Q Development SystemLinker-llibname-X...
-odestin

Include specified library libname when linking
Specify linker option
Specify the destination. Either a file (e.g. prog.cpe), or target (e.g.
t0:) can be specified

See GNU C documentation for full description

ExampleCCSH -v -g -Xo$6010000 main.c -omain.cpe,main.sym
This example will execute the compiler to compile the source file MAIN.C ,then run
ASSH to produce the object file and finally will run PSYLINK to produce an
executable and symbol file (MAIN.CPE and MAIN.SYM respectively) ORGd tothe specified address. The -v switch will cause CCSH to echo all commands it
executes to stdout. The -g switch will request full debug info in the symbol file.
CCSH @main.cf -omain
This will force CCSH to use the contents of the MAIN.CF file on the command line,
before the -o option.

Psy-Q Development System

Source Files
The specified source files can be either C or assembler source files, or object files.
CCSH decides how to deal with a source file based on the files extension. The
following table describes how each file extension is processed:
.C
.I
.CC
.CPP
.II
.IPP
.ASM
.S
.otherRemarks

Passed through C pre-processor, C compiler, Assembler, Linker
Passed through C compiler, Assembler, Linker
Passed through C pre-processor, C++ compiler, Assembler, Linker
Passed through C pre-processor, C++ compiler, Assembler, Linker
Passed through C++ compiler, Assembler, Linker
Passed through C++ compiler, Assembler, Linker
Passed through C compiler, Assembler, Linker
Passed through Assembler, Linker
Passed through Linker• The PC file system is not case sensitive and so the case of the extension has noeffect.
• Various command line switches can stop processing at any stage, eliminating
linking, assembling or compiling.
• The -x option can be used to override the automatic selection of action based onfile extension.
• Files with extensions that are not recognised are treated as object files and passed
to the linker. This includes .OBJ files, the standard object file extension.
• Several different source files, which may have different file extensions, may beplaced on the command line.

Psy-Q Development System

C H A P T E R 15

The PSYMAKE Utility
PSYMAKE is a make utility for MS-DOS which automates the building andrebuilding of computer programs. It is general purpose and not limited to use with
the Psy-Q system. The utility is discussed under the following headings:••

Command Line Syntax
Format of the Makefile

Psy-Q Development System

PSYMAKE Command Line
Description

PSYMAKE only rebuilds the components of a system that need rebuilding. Whether
a program needs rebuilding is determined by the file date stamps of the target file andthe source files that it depends on. Generally, if any of the source files are newer than
the target file, the target file will be rebuilt.

SyntaxPSYMAKE [switches] [target file]
or
PSYMAKE @makefile.mak

Switches

Valid switch options are :/b/d name=string/f filename
/i
/q
/x

Build all, ignoring dates
Define name as string
Specify the MAKE file
Always ignore error status
Quiet mode; do not print commands before executing them
Do not execute commands - just print them

If no /f option is specified, the default makefile is MAKEFILE.MAK; if noextension is specified on the makefile name .MAK will be assumed.
If no target is specified, the first target defined in the makefile will be built.

Psy-Q Development System

Contents of the Makefile
The Makefile consists of a series of commands governed by explicit rules(dependencies) and implicit rules. When a target file needs to be built, PSYMAKE
will first search for a dependency rule for that specific file. If none can be found
PSYMAKE will use an implicit rule to build the target file.

Dependencies:
A dependency is constructed as follows :targetfile : [sourcefiles][command...
command ]•The first line instructs PSYMAKE that the file "targetfile" depends on the files
listed as "sourcefiles".

•If any of the source files are dated later than the target file or the target file does
not exist, PSYMAKE will issue the commands that follow in order to rebuild thetarget file.

•If no source files are specified the target file will always be rebuilt.

•

If any of the source files do not exist, PSYMAKE will attempt to build them first
before issuing the commands to build the current target file. If PSYMAKE
cannot find any rules defining how to build a required file, it will stop and reportan error.

The target file name must start in the left hand column. The commands to be
executed in order to build the target must all be preceded by white space (either
space or tab characters). The list of commands ends at the next line encountered witha character in the leftmost column.

Psy-Q Development System

Examples

main.cpe: main.68K inc1.h inc2.h
ASM68K main,mainThis tells PSYMAKE that main.cpe depends on the files main.68K, inc1.h andinc2.h. If any of these files are dated later than main.cpe, or main.cpe does not exist,
the command "ASM68K main,main" will be executed in order to create or update
main.cpe.

main.cpe: main.68K inc1.h inc2.h
ASM68K /l main,main,main
psylink main,main
Here, two commands are required in order to rebuild main.cpe.

Implicit Rules
If no commands are specified, PSYMAKE will search for an implicit rule todetermine how to build the target file. An implicit rule is a general rule stating how toderive files of one type from another type; for instance, how to convert .ASM files
into .EXE files.
Implicit rules take the form:.<source extension>.<target extension>:command[...
command ]Each <extension> is a 1, 2 or 3 character sequence specifying the DOS file extension
for a particular class of files.
At least one command must be specified.

Examples.s.bin:asm68K /p $*,$*
This states that to create a file of type .bin from a file of type .S, the ASM68K
command should be executed. (See below for an explanation of the $* substitutions.)

Psy-Q Development SystemExecuting commands:
Once the commands to execute have been determined, PSYMAKE will search forand invoke the command. Search order is:••current directory;
directories in the path.

If the command cannot be found as A.EXE or A.COM file or the command is A.BAT
file, PSYMAKE will invoke COMMAND.COM to execute the command/batch
file. This enables commands like CD and DEL to be used.

Command prefixes:
The commands in a dependency or implicit rule command list, may optionally be
prefixed with the following qualifiers :@- number-- suppress printing of command before execution- abort if exit status exceeds specified level- (without number) ignore exit status (never abort)•

Normally, unless /q is specified on the command line, PSYMAKE will print a
command before executing it. If the command is prefixed by @, it will not be
printed.

•If a command is prefixed with a hyphen followed by a number, PSYMAKE willabort if the command returns an error code greater than the specified number.

•

If a command is prefixed with a hyphen without a number, PSYMAKE will notabort if the command returns an error code.

•

If neither a hyphen or a hyphen+number is specified, and /i is not specified on thecommand line, PSYMAKE will abort if the command returns an error code otherthan 0.

Psy-Q Development System

Macros

A macro is a symbolic name which is equated to a piece of text. A reference to thatname can then be made and will be expanded to the assigned text. Macros take theform:name = text

Examples•The text of the macro starts at the first non-blank character after the equals sign (= ), and ends at the end of the line.

•

Case is significant in macro names.

•

Macro names may be redefined at any point.

•

If a macro definition refers to another macro, expansion takes place at time ofusage.

•A macro used in a rule is expanded immediately.

FLAGS = /p /s...
.68K.bin:
ASM68K $(FLAGS) /p $*,$*
The $(FLAGS) in the ASM68K command will be replaced with /p /s.

Pre-defined macros:
The following pre-defined macros all begin with a dollar sign and are intended to aid
file usage:$dDefined Test Macro, e.g.:!if $d(MODEL)# if MODEL is defined ...

$*Base file name with path,e.g.

C:\PSYQ\TEST$<

full file name with path,e.g.

C:\PSYQ\TEST.S$:

path only,

e.g.

C:\PSYQ$.

full file name, no path,e.g.

TEST.S$&base file name, no path,

e.g.

TEST

The filename pre-defined macros can only be used in command lists of dependency
and implicit rules.

Psy-Q Development System

Directives:

The following directives are available:!if
expression!elseif expression!else!endif
These directives allow conditional processing of the text between the if, elseif, elseand endif. Any non-zero expression is true; zero is false.

!error message

Print the message and stop.

!undef macroname

Undefines a macro name.

Expressions: Expressions are evaluated to 32 bits, and consist of the following components :Decimal Constants
Hexadecimal
Monadics
Dyadicse.g. 1 10 1234
e.g. $FF00 $123abc-~!
+-*/%><&| ^ && ||> < >= <= == (or = )!= (or <> )The operators have the same meanings as they do in the C language, except for = and<> ,which have been added for convenience.

Value assignment:
Macro names can be assigned a calculated value; for instance:
NUMFILES == $(NUMFILES)+1( Note two equals signs in value assignment)This evaluates the right hand side, converts it to a decimal ascii string and assigns theresult to the name on the left.
In the above example, if NUMFILES was currently "42", it will now be "43".

Note

NUMFILE = $(NUMFILES)+1
would have resulted in NUMFILES becoming "42+1".
Undefined macro names convert to '0' in expressions and null string elsewhere.

Psy-Q Development System

Comments:
Comments are introduced by a hash mark (#):
main.exe: main.s# main.exe only depends# on main.s# whole line comment

Line continuation:
A command too long to fit on one line may be continued on the next by making '\' thelast character on the line, with no following spaces/tabs:
main.exe : main.s i1.h i2.h \i3.h i4.h

Psy-Q Development System

C H A P T E R 16

Psy-Q Debugger for Windows 95
Introduction
The Psy-Q Debugger for Windows ‘95 takes advantage of the new range of 32-bit
operating systems available for PCs; it provides full source level as well as traditional
symbolic debugging and supports and enhances all the power of the DOS-based
version plus the advantages of a multi-tasking GUI environment.
It helps you to detect, diagnose and correct errors in your programs via the step andtrace facilities, with which you can examine local and global variables, registers andmemory.
Breakpoints can be set wherever you need them at C and Assembler level and if
required, these breaks can be made conditional on an expression. Additionally,
selected breakpoints can be disabled for particular runs.
The Debugger employs drop-down menus, tool buttons, keyboard shortcuts and popup menus to help you debug quickly and intuitively.
Projects
The Debugger uses Projects to group together details of Files, Targets, Units, Views
and other settings and preferences. All this information is saved and made available
for your next debugging session.
Views
The Debugger offers the functionality of splitting the screen into a number of Panes,
each displaying discreet or linked information. This information is available within aView, or document window (MDI Child). Each View can be split horizontally or
vertically into the number of Panes you require and each Pane can be set to show a
specific type of information.
You can have as many combinations of either tiled Panes or overlapping Views as
you choose.
Your choice of Views depends on the level at which you are debugging. For
example, it is appropriate to use a Register Pane for assembler debugging and a Local
Pane when debugging in C.

Psy-Q Development System

Individual Views can be saved on disk for subsequent use in other Projects.
However, when you close the Debugger and then re-start a session, your previous
screen set-up will initially be displayed automatically.
Colour Schemes
To aid identification, a separate colour scheme can be allocated to the Views used byeach Unit that you reference. Alternatively, the same colour can be allocated to all
Views.
Files
The Symbol Files you require are located and loaded by the Debugger and therelevant CPE and Binary Files are downloaded to the Target. Where a multi-unit
system is in use you must also specify the Unit where Symbol and Binary Files are to
be loaded.
Dynamic Update
Changes in memory are highlighted on each display update, showing which areas ofmemory are being altered as the Target is being run and you are stepping and tracing
your code.
The following topics are discussed in this chapter:
On-line Help
Installing the Debugger
Launching the Debugger
The Psy-Q File Server
Connecting the Target and Unit
Project Management
Psy-Q Debugger Productivity Features
Views
Panes
Debugging Options
Closing the Debugger

Psy-Q Development System

On-line Help Available For The Debugger
Help text describing the features covered in this chapter, can also be accessed on-line
via the Help menu on the main menu.
Selecting these options will result in the following:• Contents will display the Contents page of the help system in the left-hand side of
the screen. Clicking any of the underlined topics will provide further information
about the relevant subject.
• Pane Types and the required Pane will directly access relevant text for the chosen
Pane.
• Installation will display installation procedures.
• About will provide the Version Number.
Within the on-line help system, clicking text with a dotted underline will display a
pop-up description but double-clicking text with a solid underline will display another(linked) help page.
The buttons at the top of the help text window can be used to facilitate the following:• Search and/or Find to locate a particular word or topic.
• Back to re-display the previous page.
• << and >> to display the previous and next page in the browse sequence, as
outlined in the Table Of Contents. (See below).
• Glossary to display an alphabetic listing of terms found in the help system. Clickon any topic to obtain a pop-up definition.
As well as accessing information via the Contents page, on-line help can also belocated via the Table Of Contents in the right-hand area of the screen. This
represents the subject areas of the help system as book icons. Double-click any icon
to display titles of the individual pages which compose each ‘book’. Double-click
any of these pages and the text will be displayed in the left-hand side of the screen.

Psy-Q Development System

Installing The Debugger
A Set-up program is used to install the Debugger; this is distributed via either of thefollowing methods:• Full Release Files• Maintenance Patch Files
Both methods are described in more detail below the Directory Structure.
Directory Structure
All the Files relating to the Windows software live in one directory tree. This tree
can reside anywhere but it is probably easier to locate it on the root of a local drive.
The default directory name is:‘C:\PsyQ_Win\’and it is recommended that you follow this convention. Set-up also installs several
Files in the Windows System directory and adds two keys to the Registry.
These keys are:[HKEY_LOCAL_MACHINE\SOFTWARE\SN Systems] (hardware settings)[HKEY_CURRENT_USER\Software\SN Systems] (configuration information)
Set-up also registers the File types .psy (Psy-Q Project), .pqp (Psy-Q patch) and .cpeand adds some programs to the Start menu.

IMPORTANT: Do not install the program on a server and execute it across a
network. For un-installation advice, please contact SN Systems.

Psy-Q Development System

Obtaining Releases And Patches
Releases and patches are available directly from SN Systems’ BBS and ftp sites. In
order to access these sites you will need an account with the necessary permissions.
To apply for an account telephone SN Systems or contact them via
Support@snsys.com. Patches and releases can also be obtained via email in MIME,
provided that you are a member of the Windows-Users mailing list. (See below).
Note: Members of the Windows-Users mailing list will be notified of releases andpatches as they become available.

Determining The Latest Releases And Patches
This is achieved via any of the following methods:• Contact John@snsys.com• Look in one of the File sites for the latest Files and information• Send mail to the auto-responder maildrop - Versions@snsys.com.
Mailing Lists
SN Systems maintain the following mailing lists:• Announce@snsys.com - For all announcements regarding Psy-Q• Windows-Users@snsys.com - For up-to-date information• Windows-Discuss@snsys.com - For all Debugger users (discussion)
The first two are read-only and provide details about revisions and other information.
The third is an open read/write list which hosts any Debugger related discussions,problems, suggestions or comments.
For more information on these lists, send a HELP message to Norman@snsys.com(the Robot List Manager) or John@snsys.com.

Psy-Q Development SystemAddresses for SN Systems’ ftp, web and BBS sites• ftp://ftp.snsys.com• http://www.snsys.com• BBS - +44 (0)117 9299 796 and +44 (0)117 9299 798

Beta Test Scheme
SN Systems maintain a separate scheme for beta testing new versions of the
Debugger.
The benefits of this are as follows:• You will receive new versions of the Debugger before any other user
• You will have a prioritorised chance to supply feedback to the Debugger’s authors
If you are a member of this scheme, you don’t need to install release versions of the
Debugger.
For more information, contact John@snsys.com.

Psy-Q Development System

Installing A Full Release
A Full Release File contains an archive of several Files and a Set-up program that canbe used to install the Debugger automatically.

4

To install the release:1.

Obtain the latest full release from SN Systems.

2.

Read Readme.txt which contains last-minute installation instructions.

3.

If the release is on a floppy, launch Setup.exe straight-away. If however, therelease is in a zip File, you must unzip the File into a temporary directory and thenlaunch Setup from that temporary directory.

4.

If this is the first full installation of the Debugger, confirm the displayed license
conditions.

5.

Specify or confirm the directory in which you wish to install the Debugger.

6.

The Files will be installed and the Registry will be updated.

7.

Depending on the type of installation, specify the settings for the DEX Board or
SCSI Card. (See Configuring Your Dex Board/SCSI Card below).

8.

Once the dialogue has been completed the installation is complete.

Note: This method can be used for the first installation of the Debugger and also forsubsequent upgrades if you do not wish to use Maintenance Patches. See
Upgrading Your System below.

Psy-Q Development System

Upgrading Your System
From time to time, SN Systems will provide updates to the Debugger that introduce
bug fixes and new features. For your convenience, updates are supplied as fullinstallations and as maintenance patches.
A Maintenance Patch contains only the difference between Files so it is much smaller.
This makes it quicker to download and apply. However, patches can only be applied
over certain previous versions.

4

To apply a Maintenance Patch:
1.

Determine your current release by reading the About box for the Debugger.

2.

Obtain the Maintenance Patch from SN Systems. Instructions will be provided so
you can determine which patch must be applied.

3.

Apply the patch by using the PQSetup program. This is available on the Startmenu or by double-clicking a patch file (.pqp). Follow the on-line instructions.

Psy-Q Development System

Configuring Your Dex Boards
If you are installing a Full Release for the Sony PlayStation (DEX only), you mustspecify the settings for these DEX Boards.

4

Enter appropriate values to the dialogue box displayed during the Set-up program.

DEX Board Settings Dialogue Box

1.

Enter a 3 or 4-digit hexadecimal number to the Port Address and Parallel boxes
and specify an IRQ value by clicking on the down arrow and selecting as
appropriate.

2.

Click

3.

The installation is now complete.

.

IMPORTANT: Port Address and IRQ values must be correct for the Debugger towork. If they are incorrect or another device is configured to use
similar settings, the programs will not work.
Note: The Parallel setting should be set to the I/O address of the port to which yourdongle is connected. Most PCs use 378 for 1pt1:. If your dongle is on adifferent parallel port or your PC uses a non-standard port address, change thisvalue. See FAQ.DOC for more information.

Psy-Q Development System

Configuring Your SCSI Card
If you are installing a Full Release for a SCSI Target, you must specify the settings
for the SCSI Card.

4

Enter appropriate values to the dialogue box displayed during the Set-up program.

SCSI Card Settings Dialogue Box

1.

Specify a Port Address and IRQ value by clicking on the down arrows andselecting as appropriate.

2.

Click

.

The installation is now complete.

IMPORTANT: Port Address and IRQ values must be correct for the Debugger towork. If they are incorrect or another device is configured to use
similar settings, the programs will not work.
Note: The IRQ value can be set to 0 to run without interrupts. However, this is only
recommended for troubleshooting since running without interrupts will
seriously impair the performance of the system.

Psy-Q Development System

Testing The Installation
Once the Debugger has been installed, you should now run PsyServe.exe in order totest that the configuration is working correctly.
A similar message to the following should be displayed:
Psy-Q File and Message Server, Copyright 1995, SN Systems Ltd,
Version: 1.00 (December 1995)
Target: Sony Playstation Plug-In
Resources: Port=0x390, Interrupt=12
Loading SCSI Drivers...
Connected to SONY_PSX5.15
Ready to Serve
If no message appears at all, your Port and IRQ settings may be incorrect or there
may be a resource conflict with some other device.

4

However, you can change the Port/IRQ settings by re-running the Set-up program
as follows:

1.

Click

on the Open File dialogue box.

2.

Select the appropriate Card from the Cards menu.

You will then be presented with the same dialogue box as was displayed during
installation.
See FAQ.DOC if you continue to have problems.

Psy-Q Development System

Documentation
If you experience problems during installation, the following documents provide
useful information:• README.DOC details how to obtain and apply maintenance releases• FAQ.DOC contains Frequently Asked Questions and should be consulted if you
experience any problems• BUG.TXT describes how to report bugs
• TODO.TXT lists known bugs, problems and features that are not yet
incorporated into the Debugger

Psy-Q Development System

Launching The Debugger
There are several ways of launching the Psy-Q Debugger under Windows ‘95.

4

A simple way is as follows:1.

Select the Start menu from Windows 95.

2.

Choose the Programs option from the list displayed.

3.

Select the Psy-Q folder from the list of programs.

4.

Select Psy-Q Debugger from the folder.

You can also launch the Psy-Q Debugger from the desktop or folders or throughExplorer in Windows ‘95.
With the drag and drop facility you can drop a Psy-Q Debugger Project File(extension .PSY) onto the icon of the Debugger and the selected Project is launched.
Alternatively, as file type .PSY has been registered with the Windows ‘95 shell, you
can right-click on a Project File, select Debug from the menu and the Debugger will
be launched with the selected Project.
Note: While the Debugger is still running, you can open a new Project by following
the procedure described in the previous paragraph.
When you launch the Psy-Q Debugger it scans for recognised Units and if none arefound a dialogue box prompts you to either Repoll or Quit. If the latest downloader
has not been installed you are prompted to download this. The Psy-Q File server is
automatically launched with the Debugger.

See Also:
Launching PsyServe without the Debugger

Psy-Q Development System

The Psy-Q File Server
The primary function of the Psy-Q File Server is to provide the PC Open and PC
Read functions for your program.
It is always launched when the Debugger is launched and must always be running in
the background while the Debugger is being used, both file serving and collecting
messages.
When the File Server is running, the icon and name of the application appear on the
Task bar of Windows ‘95.
You can view the messages appended into the message window of the File Server
during debugging by clicking on this icon.

File Server Message Window

If you wish the message window to be permanently displayed on top of otherwindows, select Always on Top from the View menu.

Psy-Q Development System

When the Debugger or File server experiences a communication error, a dialogue box
will display a relevant error code and a Retry and Cancel button.

Communication Error Dialogue Box

Press Retry and the attempted connection will be repeated; press Cancel and thesystem will try to carry on and will attempt to recover from the error.
Note: If the Debugger comes up with this message, the File Server can still be used
to reset the Target.

File Server Menu Commands
In addition, seven menu commands can be used with the File server:• Run Project loads all Files (except Symbol Files) that are set to ‘download on
project startup’ and runs the Project without loading the Debugger• Download CPE File to the Target.
• Run CPE runs the Target after the CPE File has been downloaded.
• Ping determines the current status of the Target• Halt provides the option to stop the Target if it is running.
• Clear Window removes any File Server messages.
• Reset Target

Psy-Q Development System

Note: Resetting the Target while the Debugger is running may cause unpredictable
results.
Note: The Reset option is also available from the System menu of the File server.
IMPORTANT:The Psy-Q File Server must always be running when the
Debugger is running. You will not be permitted to stop theserver until you close the Debugger; however, the File Server
can be run without the Debugger .

Launching The File Server Without The
Debugger4

If you wish to launch the File Server independently of the Debugger, for example, to
run your Project without loading the Debugger:
1.

Select the Start menu of Windows ‘95.

2.

Choose the Programs option from the list displayed.

3.

Select the Psy-Q folder from the list of programs.

4.

Choose the Psy-Q File Server option from the folder.

Note: When you launch the File server the Target is automatically reset, whether
the Debugger is running or not.

See Also:
Launching the Debugger

Psy-Q Development System

Connecting The Target and Unit
The Psy-Q Debugger automatically checks your system when you launch it, identifies
any Targets that are connected and according to whether you are running a single ormulti-Unit system, automatically connects to the relevant Unit(s).
The Unit toolbar appears at the bottom of the Debugger window directly above theStatus line. The first icon in the toolbar has a pictogram of the Target known as theUnit button.

Unit Button

There will be a Unit toolbar and unique button for each Unit identified. Click on the
button to display the Unit menu. This menu allows you to download and load (asrelevant) foreign CPE and foreign Symbol Files and download non-foreign CPE andBinary Files. The menu also allows you to see and edit breakpoints.
The menu options are:
• Download CPE• Download Binary• Load Symbols• Breakpoints
Each toolbar contains a set of debugging icons which represent:• Starting programs• Stopping a program running• Stepping into a subroutine• Stepping over a subroutine

Psy-Q Development System

Note: Note that these actions operate only in respect of the relevant Unit; therefore,
where a multi-Unit system is in use they will not necessarily operate in respectof the Active View.
Note: The Psy-Q File server is automatically launched when the Psy-Q Debugger isstarted. The Server window displays any output from the Target while it isrunning.

Psy-Q Development SystemPsy-Q Projects
A Psy-Q Project is a combination of the elements and settings associated with a
specific development project.
It consists of any or all of the following:• Units to be debugged• Screen layout• CPE Files• Symbol Files• Binary Files• Breakpoints• Other settings and preferences.
This set of information is used by the Debugger to track the debugging process.
When you save a Project this includes all the Views, colour schemes and breakpoints
already specified for it. These settings are reinstated when the Project is next
opened.
Setting Up And Managing Projects

4

To create a new Project you can either:
1.

Open the default Psy-Q Project by selecting New from the Project menu.

2.

Save and name the Project.
or1.

As 1) above.

2.

Select files for the Project and add them to the file list.

3.

Set file properties for executable files.

4.

Save and name the Project5.

Re-open the Project with the files in the file list.

Psy-Q Development System

Selecting Files For Your Project
The Psy-Q Debugger uses files that are output from the build process. Three types offile may be included in the Project; these are:
• CPE Executable Files• Symbol Files• Binary Files
Adding Files To The List Of Project Files

4

This is achieved as follows:1.

Select the Project menu from the Menu bar.

2.

Choose Files from the menu; the Files dialog appears.

3.

Click

4.

Select CPE, Binary or Symbol Files from the ‘Files of Type’ drop-down list.

5.

Locate the file and click

6.

When you add a file to the file list a relevant dialog box requests you to set the fileproperties. For CPE and Binary Files these will determine the downloading offiles to the Target. Additionally, for Binary and Symbol Files, they determine theUnit to which they will be loaded. See the ‘Understanding File Properties’
sections below.

to insert them into your file list.

.

Note: It is not necessary to specify the Unit to which a CPE File should be loaded
as this information is held within the file itself.

7.

Repeat the operation until all the files you require appear in the list. To remove a
file from the list, highlight it and click

8.

Click

.

when you have added all the files you require.

The CPE and Binary Files will be downloaded in the order shown in the file list.

Psy-Q Development System

Note: As file type .CPE has been registered with the Windows ‘95 shell, you canrun a program directly from the shell by double-clicking on the relevant
CPE File. Alternatively, if you wish to download the file to the Target
without running it, right-click the relevant file and select Download fromthe menu.
Note: When you add Binary and Symbol Files to a Project they are not loaded
until the Project is saved and re-opened.

Changing The Order Of Files In The File List
If you have multiple CPE and Binary Files within your Project, the order in which
they are loaded during debugging is determined by the position you placed them in
the File list.

4

To change the file sequence:1.

Select the Project menu from the Menu bar.

2.

Choose Files from the menu.

3.

Highlight a file.

4.

Use

or

to alter the position of the file in the list.

Repeat the process until the files are in the required order.
Note: This option is only useful if you have multiple CPE and Binary Files in your
Project and the load order is important.

Psy-Q Development System

Specifying CPE File Properties
When you select a CPE File to include in your Project, a dialogue box requests thatyou set the properties for this file.
These properties allow you to control the downloading of files to the Target. The
options are:
• Download when Project starts - This causes the CPE File to be downloaded
when the Project is opened or reopened.
• Run after CPE has been downloaded - This causes the Unit to start running thecode after downloading the file.
You may select either or both of these properties for any CPE File in the Project.
If you do not set the properties of at least one CPE File, the Debugger will not
download any files to the Target when the Project is opened.

4

To change CPE File properties:
1.

Select the Project menu from the Menu bar.

2.

Choose Files from the menu.

3.

Select the CPE File to change.

4.

Click

5.

Use the check boxes to apply the properties.

6.

Click

.

.

Psy-Q Development System

Specifying Symbol File Properties
When you select a Symbol File to include in your Project, a dialogue box requests
that you confirm or specify the Unit to which the file should be loaded.

4

To change Symbol File properties:
1.

If the required Unit is not already displayed, click the down arrow until it appears.

2.

Highlight the required Unit.

3.

Click

4.

Click

.
.

Psy-Q Development System

Specifying Binary File Properties
When you select a Binary File to include in your Project, you must complete thefollowing dialogue box:

Binary File Properties Dialogue Box

These properties allow you to control the downloading of files to the Target:• Download when Project starts - If this is selected the Binary File will be
downloaded when the Project is opened or reopened.
• Downloaded to a specified address - The files will be downloaded to the address
specified. This should be in OX notation for hexadecimal numbers. The default
address will be zero.
• Specify the Unit where the File is to be loaded - Click on the down arrow todisplay further Units.
If you do not set the first option for at least one Binary File, the File Server will not
download any Binary Files to the Target when the Project is opened. However, all
Binary Files in the Project will be available on the relevant Unit menu.

4

To change Binary File properties:
1.

Select the Project menu from the Menu bar.

2.

Choose Files from the menu.

3.

Select the Binary File to change and click

4.

Select the Download when Project starts option if required and/or enter arelevant address.

5.

Confirm or specify the Unit where the File is to be loaded.

6.

Click

.

Psy-Q Development System.

Saving Your ProjectOnce the files have been selected, the new Project must be saved and re-loaded
before debugging can begin.

4

This is achieved as follows:1.

Select the Project menu from the Menu bar.

2.

Choose the Save option from the menu.

3.

Give a name and path to your Project.
File names in Windows ‘95 are up to 250 characters long and can contain spaces.
Psy-Q Debugger Project Files must be saved with the default File extension of
.PSY.

4.

Click

.

Note: For a new Project you can choose the Restore rather than the Save option.
Restore prompts you to save the Project before reloading it.
Note: The Save or Save As options can be used to save an existing Project.

Re-opening A Project
After saving a new Project you must re-open it before working with the files whichhave been added to the file list.

4

This is achieved as follows:1.

Select the Project menu from the Menu bar.

2.

Choose the Re-open option from the menu.

Note: The Re-open icon on the toolbar

can also be used to re-open a Project.

Psy-Q Development System

Saving A Project Under A New Name
The Save As option on the Project menu is used to save changes made to an existing
Project, under a new name.
The default File extension for a Psy-Q Debugger Project is .PSY. When you save
Project Files you must use this extension.

4

To save a Project under a new name:1.

Select the Project menu from the Menu bar.

2.

Choose the Save As option from the menu.

3.

Give a name and path to the renamed Project.

4.

Click

.

Restoring A Project
The Restore option on the Project menu is used to re-load a Project in the state inwhich it was last saved, abandoning any changes made since the last save.

4

To restore a Project:
1.

Select the Project menu from the Menu bar.

2.

Choose the Restore option from the menu.

Psy-Q Development System

Opening An Existing Project
When you launch the Psy-Q Debugger, the last Project you worked on will be loaded
automatically.

4

To open a different Project:
1.

Select the Project menu from the Menu bar.

2.

Choose the Open option from the menu.

3.

Select the Project (.PSY) you require.

4.

Click

.

Note: An existing Project can also be opened via the Open Project iconon the toolbar.

found

Note: As File type .PSY has been registered with the Windows ‘95 shell, you canrun a Project by double-clicking on the relevant .PSY File within the shell.
Alternatively, if you only wish to load the Project into the Debugger, rightclick the relevant file and select Debug from the menu.

Psy-Q Development System

Manually Loading Files Into A Project
External Files can be downloaded at any time; they are not saved with the Project.

4

External CPE Files are downloaded to the Target as follows:
1.

Click on the Unit menu at the base of the Debugger screen.

2.

Choose the Download CPE option from the menu.

3.

Choose the External File option.

4.

Browse and select the required CPE File.

5.

Click

.

Note: You can also download a CPE File by double/clicking it within the shell.

4

Symbol Files can be loaded into the Debugger as follows:
1.

Click on the relevant Unit menu at the base of the Debugger window.

2.

Choose the Load Symbols option from the menu.

3.

Browse and select the required Symbol File.

4.

Click

.

Psy-Q Development System

The Psy-Q Debugger Productivity Features
To enable you to work faster and more efficiently when using the Psy-Q Debugger,
the following two features speed up your control of the debugging runs.
• Toolbar Icons• Hot Keys

Toolbar Icons

The toolbar contains the group of icons shown above. Icons provide a quicker meansof activating commands and setting properties.
From left to right they represent the following actions:
Open a Project File
Save and then reopen the current ProjectOpen a new View
Switch to the next View
Split the Active Pane horizontally
Split the Active Pane vertically
Delete the Active Pane
Set the default colour scheme

The Show Toolbar option on the Project menu is used to toggle the menu bar on andoff. When the option is ticked the toolbar is displayed.

4

To toggle the toolbar:
1.

Select the Project menu from the Menu bar.

2.

Choose the Show Toolbar / Hide Toolbar option from the menu.

Note: Every Pane type has its own, additional toolbar which is appended to themain toolbar when that Pane is made Active.

Psy-Q Development System

Hot Keys
The following Hot Keys can be used instead of the Debugger menu options:
F2
F3
F4
F5
F6
F7
F8
F9
Esc
Ctrl + Shift + D
Ctrl + Shift + L
Ctrl + Shift + M
Ctrl + Shift + R
Ctrl + Shift + S
Ctrl + Shift + W
Shift + Arrow Keys

Ins

Split Horizontal
Split Vertical
Delete current Pane
Toggle breakpoint on and off
Run to cursor
Step into a subroutine
Step over a subroutine
Run a program
Stop a program running
Change Pane to Disassembly Pane
Change Pane to Local Pane
Change Pane to Memory Pane
Change Pane to Register Pane
Change Pane to Source Pane
Change Pane to Watch Pane
Activates adjacent Pane in the specified
direction. Where more than one, thecurrent caret position determines thePane to be made Active
New View

Note: These keys will all operate in respect of the Active Pane.

Psy-Q Development SystemPsy-Q Views
A View appears in the main window of the Psy-Q Debugger; it is used to display
debugging information according to your requirements and to control step and trace
actions during debugging.
When a Psy-Q Project is first created it has a default Pane layout.
Views can be split into as many Panes as you wish. These can be of the same ordifferent types.
Only one is Active at any time; it will be displayed in a different colour scheme to theothers.

Notes: Having created a View of different Panes you can save this as a View Fileeither in, or independent of, the Project. Further information about Panes
can be found in Working With Panes and Selecting A Pane Type.

Psy-Q Development System

Creating A Psy-Q View
Within a Psy-Q Project you can create as many Views as required; in turn, eachView can be split into as many Panes as you need.
When you open a new Project, one View is displayed for each Unit connected.

Default View

4

To create a new View:
1.

Select the View menu from the Menu bar.

2.

Choose the New option from the menu.

3.

From the Choose Unit box specify the Unit for which you wish to create a new
View.

Note: The Choose Unit box will not appear when you are connected to a single
Unit.

Psy-Q Development System

You can also use the New View icon on the toolbar
use the Hot Key Insert.

to create a new View or

Alternatively, you can open a new View from the relevant Unit button, in which case
you won’t be prompted for the required Unit.
Note: A new View is supplied with the title ‘Default View’. The View Name option
in the View menu should be used to give it a title.
Note: Views can be saved either inside or outside of Psy-Q Projects.

Cycling between Views

4

If you have more than one View open within a Project you can cycle between themas follows:1.

Select the View menu from the Menu bar.

2.

Choose the Next View option.

The Views are cycled around until you see the one you require. All Views appear on
the View list regardless of the Unit for which they have been specified.
Alternatively, the Next View icon on the toolbar
Ctrl + TAB can be used to cycle between Views.

Psy-Q Development System, the Hot Keys Ctrl + F6 orSaving Your Views
Any number of Views can be saved within a Project.
All open Views will automatically be saved when you save the Project and will be
opened when the Project is re-opened.
View Files can also be saved independently of Projects using the Save As commandon the View menu.

4This is achieved as follows:
1.

Arrange the Panes as you require.

2.

Select the View menu from the Menu bar.

3.

Choose the Save As option from the menu.

4.

Give the View a name and path.

5.

Click

.

Note: The name you give the View File is not displayed on the View. To give a
View a title use the View Name option on the View menu.

Naming A View

4

Because you can use many Views within a Project, it is helpful to give each View anindividual title.
1.

Select the View menu from the Menu bar.

2.

Choose the View Name option from the menu.

3.

Enter the View name in the edit box.

4.

Click

. The name appears at the top of the View.

Note: This is not the name of the File. See the note in Saving Your Views above
for further details.

Psy-Q Development System

Changing Colour Schemes In Views

4

To change the colours for a particular Unit:
1.

Activate a View/Pane on the Unit that you wish to set colours for.

2.

Select the View menu from the Menu bar.

3.

Choose Set Default Colours... from the menu.
The following areas may be changed for the Active Unit:
Inactive Pane background colour
Inactive Pane text colour
Active Pane background colour
Active Pane text colour
PC text colour
Changed information colour
Breakpoint background colour
Breakpoint text colour

4.

Click on the box representing the area you wish to amend.
A standard Windows dialogue box allows you to choose from a range of standard
or customised colours.

Set Default Colours Dialogue Box

Psy-Q Development System

5.

Select the required colour(s).

6.

The selected colour scheme will be displayed for all visible
Views.

7.

Selectto retain the revised colours orrevert to the original scheme.

Unit colours can also be amended by clicking on the Set Colour icon
toolbar.

Psy-Q Development Systemtoon theWorking With Panes
When a Psy-Q Project is first set up, the default View contains a default Pane layout
for each Unit connected. However, this View can be split into as many Panes as you
wish. These can be of the same or different types. Only one of the Panes is Active;
it will be displayed in a different colour scheme to the others.

4

A Pane can be made Active via any of the following methods:• Clicking on it• Changing the Active View and the first Pane created for that View will become
Active• Using Shift and the appropriate arrow key to Activate the Pane in the specified
direction• Clicking the right mouse button on the required Pane and selecting from thedisplayed menu

Splitting Panes

4

A View can be divided into as many Panes as you wish. Click on the one you wish to
split to make it Active, then:1.

Select the View menu from the Menu bar.

2.

Choose either Split Vertical or Split Horizontal from the menu.

The Active Pane is split in half, either vertically or horizontally, depending on yourchoice.
You can also split a Pane horizontally or vertically via the icons on the toolbar
or by using the hot keys F2 to split horizontally or F3 to split vertically.

Note: When you split a Pane the two halves will both be of the same type as theoriginal. The font for the new Pane will also match that of the original.

Psy-Q Development System

Changing Pane Sizes

4

To change the size of Panes:
Drag the splitter bar between the Panes with the mouse.
The size and position of the Panes is saved when you save the View or the Project.

Note: Splitter bars only control the areas between the Panes. If you wish to change
the size of the Debugger window you have to use the borders of the window
itself.

Deleting A Pane

4

The Delete Pane option on the View menu is used to delete a Pane within a View, as
follows:
1.

Click on the required Pane to make it Active.

2.

Select the View menu from the Menu bar.

3.

Choose Delete Pane from the menu.

Alternatively, the Delete Pane icon on the toolbar
to delete the Active Pane.

Psy-Q Development Systemor the hot key F4 can be used

Changing Fonts In Panes

4

If required, the Set Font command can be used to change the display of text within aPane, as follows:1.

Make the required Pane Active.

2.

Select the View menu from the menu bar.

3.

Choose Set Font from the menu.

A standard Windows dialogue box allows you to select from the available fonts.

Note: When you split a Pane, the new Pane will be displayed in the same font as theoriginal one.

IMPORTANT: You will only be able to use non proportional fonts, e.g. Courier,
New Courier, Fixed Sys, Terminal..

See Also:
Changing Colour Schemes In Views

Psy-Q Development System

Scrolling Within A Pane
Many Panes are unable to display the full set of information that is available to the
Debugger in the small screen area shown. Therefore, the Debugger puts scroll bars
onto Panes where there is more information than can be displayed on that part of thescreen.
To see this additional information drag the thumb within the scroll bar or click on thearrows at either end of the scroll bar.
You can also scroll to the region you want by clicking on the required Pane to makeit Active and then clicking and holding the left mouse button before dragging it to the
top or bottom of the Pane.

See Also:
Changing Pane Sizes

Psy-Q Development System

Selecting A Pane Type
There are six types of Pane and you may display any number and combination.
A menu that allows you to change Pane properties is accessed via the Pane menu on
the Menu bar or by right clicking the mouse on a relevant Pane. These menus are
unique to the type of Pane that is Active but all the menus have the option Change
Pane that allows you to switch between the different types.
Additionally, icons representing each type of Pane appear adjacent to the main
toolbar.

Registers Pane - Displays the registers of the relevant CPU
Memory Pane - Displays areas of memory within the Target
Source Pane - Displays Source Files associated with program that CPU is running
Disassembly Pane - Displays the code that the CPU is running
Watch Pane - Displays ‘watches’ or expressions
Local Pane - Displays local variables
Click on the relevant icon to change the Active Pane.

Note: You can also use the Hot Keys to switch between Pane types.

Psy-Q Development System

Icons representing menu options for the selected Pane are dynamically appended to
the far right of the main tool bar. For example, if a Disassembly Pane is Active,
Disassembly Pane options will be displayed.
Further details about the options for each type of Pane can be found below.

Memory Pane
There are three areas displayed on the Memory Pane: to the left is the memory
address; in the middle is the value at the displayed memory address; and to the right is
an optional ASCII display of the values which can be toggled on or off.

Memory Pane Display

You can goto an area of memory by typing the required address over the memory
address or by selecting Goto from the Pane menu and entering a known address orlabel name to the dialogue box displayed.

See Also:
Moving To A Known Address Or LabelUse the scroll bars or the goto functions described above to move around the display.
The default setting for the Pane is in bytes with the ASCII display set.

Psy-Q Development System

Change this default by selecting the Pane menu and choosing from the options:• Bytes• Words (bytes x 2)
• Double words (bytes x 4)
• ASCII (Toggle ASCII display on and off)
• Set Width (Changes the number of bytes displayed on a line)
Alternatively, clicking on these icons will activate theoptions listed above.
You can overtype the hexadecimal or ASCII displays to alter the content of thememory. A change to the hexadecimal display will be reflected in the ASCII display
and visa versa.
When you move the mouse pointer over the values, the Status line displays theMemory Address and one of the following Memory Types:
• RAM
• ROM
• Invalid.
Invalid memory is displayed as question marks instead of hexadecimal values and fullstops instead of ASCII.
The Set Width icon can be used to change the width of the display; click on the icon
and type in the number of bytes to be shown on each line.

The Active Pane can be made a Memory Pane via any one of the following
methods:
Clicking on the Memory Pane icon on the toolbar
Using the Pane Type option from the Pane Menu
Using the Hot Key Ctrl+Shift+M.

Psy-Q Development System

Registers PaneThe Registers Pane shows the registers of the central processing Unit. These can beovertyped if required.
If the CPU has a Status Register, you can overwrite the individual bits by typing 0 or
‘R’ to reset the bit or 1 or ‘S’ to set it.
The display also shows the disassembled instruction at the Program Counter (PC)and the address of the instruction which will be executed next.
It also shows the current status and (if relevant) exception of the CPU on the bottom
line of the Pane.

Registers Pane Display

When you click the right hand mouse button over a Registers Pane or select the Panemenu on the menu bar, you will see the Change Pane Type or Pane Operations
options. Note that these are the only menu options for this type of Pane.

The Active Pane can be made a Registers Pane via any of the following methods:
Clicking on the Registers Pane icon on the toolbar
Using the Pane Type option from the Pane menu
Using the Hot Key Ctrl+Shift+R

Psy-Q Development System

Disassembly PaneThe Disassembly Pane shows the disassembled code from an area of memory.
Four columns are displayed; the first shows the address or label; the second displays
the values at that location in hexadecimal; the disassembled op code is shown in thethird column and the fourth contains the op code parameters.

Disassembly Pane Display

When the cursor is positioned on a particular label on the Disassembly Pane, therelevant label name and value will be displayed on the Status line.
The Program Counter (PC) is shown on the screen preceded by the marker ‘>‘.
When you click the right hand mouse button over a Disassembly Pane or select fromthe Pane menu on the menu bar you see the following options:• Follow PC to anchor the Pane to the Program Counter• Goto to put the cursor at a known address or label name• Toggle breakpoint to set and remove breakpoints• Edit breakpoint to disable a breakpoint or make it conditional• Run to cursor to run the Unit to the cursor position.

Psy-Q Development System

These options can also be activated by:• Using the appropriate Hot Keys
• Clicking on theseicons

The Active Pane can become a Disassembly Pane via any one of the following
methods:
Clicking on the Disassembly Pane icon on the toolbar
Using the Pane Type option from the Pane menu
Using the Hot Key Ctrl+Shift+D

See Also:
Anchoring Panes To The PC
Moving To A Known Address Or Label
Setting Breakpoints
Editing Breakpoints

Psy-Q Development System

Source Pane
A Source Pane displays one of the Source Files included in your Project.

Source Pane Display

When you click the right hand mouse button over a Source Pane or select from thePane menu on the Menu bar you see the following options:• Follow PC to anchor the Pane to the Program Counter• Goto PC (space)• Goto to put the cursor at a known address or label name• Source Files to swap between the Source Files in the Project• Toggle breakpoint to set and remove breakpoints• Run to cursor to run the Unit to the cursor position.

Note: If the Program Counter (PC) is at a line displayed on the Pane it will be
preceded by the PC point line marker ‘>‘ and the line will be displayed in adifferent colour.
Note: If a breakpoint exists within the Pane it will display in a contrasting colour.

Psy-Q Development System

The options listed above can also be accessed:• By using the appropriate Hot Keys
• By clicking on these

icons

Note: If the display is not set to follow the Program Counter (PC), the file displayed
may not be the one executing at the PC.

The Active Pane can be made a Source Pane via any one of the following methods:
Clicking on the Source Pane icon on the toolbar
Using the Pane Type option from the Pane menu
Using the Hot Key Ctrl+Shift+S

See Also:
Anchoring Panes To The PC
Moving To A Known Address Or Label
Setting Breakpoints
Editing Breakpoints

Changing Source Files In The Source Pane
By default, the Source Pane displays the Source File which contains the PC or isblank if the PC is out of range of your source.

4

Any of the Project Source Files can be examined in this Pane by using the Source
Files option from the Source Pane menu, as follows:1.

Select the Source Pane menu from the Menu bar.

2.

Choose the Source Files option from the menu.

3.

Select a Source File from the list displayed.

4.

Click

.

Psy-Q Development System

Local Pane
The Local Pane is used to display all variables in the current local scope when you
are debugging in C.
As you step and trace, the contents of this Pane will change to display the variables in
the new scope.
You can expand or collapse variables and traverse array indices.

Local Pane Display

Variables can be viewed in hexadecimal or decimal modes by right-clicking within thePane and ‘toggling’ between Hexadecimal/Decimal (on the displayed menu) as
required. A tick will appear alongside Hexadecimal when this mode is selected.
Any Local variable that evaluates to a ‘C’, l-type expression, can be assigned a newvalue.
When you select the Local Pane menu or click the right hand mouse button over a
Local Pane you see the following menu:• Expand/Collapse - when the cursor is over a pointer, a structure or an array• Increase Index - when the cursor is over an array element• Decrease Index - when the cursor is over an array element.

Psy-Q Development System

These options can also be activated by:• Using the appropriate Hot Keys
• Clicking on these icons
Note: Use of the Local Pane is restricted to debugging in C.

The Active Pane can be made a Local Pane via any of the following methods:
Clicking on the Local Pane icon on the toolbar
Using the Pane Type option from the Pane menu
Using the Hot Key Ctrl+Shift+L

See Also:
Watch Pane
Expanding Or Collapsing A Variable
Traversing An Index

Psy-Q Development System

Watch Pane
The Watch Pane is used to evaluate and browse C type expressions.

Watch Pane Display

When you select the Watch Pane menu or click the right hand mouse button over a
Watch Pane, the following menu is displayed:• Add Watch• Edit Watch• Delete Watch• Clear All Watches• Expand/Collapse - to view/hide the components of a structure or an array• Increase Index - to view higher indexed values within an array• Decrease Index - to view lower indexed values within an array
These options can also be activated by the following methods:• Using the appropriate Hot Keys
• Clicking on the appropriate icons
Structures, pointers and arrays can be opened in a Watch Pane.

Psy-Q Development System• If you open a structure the members of that structure are displayed.
• If you open a pointer it is dereferenced.
• If you open an array the first element of the array is displayed.
The contents of the Watch Pane are saved within the View when the Project is saved.
Variables can be viewed in hexadecimal or decimal modes by right-clicking within thePane and ‘toggling’ between Hexadecimal/Decimal (on the displayed menu) as
required. A tick will appear alongside Hexadecimal when this mode is selected.
Any Watch variable that evaluates to a ‘C’, l-type expression, can be assigned a newvalue.
Note: The options Expand/Collapse and Increase Index ‘+’ and Decrease Index ‘-’
are only available for arrays, pointers and structures.

See Also:
Assigning Variables
Expanding Or Collapsing A Variable

The Active Pane can be made a Watch Pane via any one of the following methods:
Clicking on the Watch Pane icon on the toolbar
Using the Pane Type option from the Pane menu
Using the Hot Key Ctrl+Shift+W

Psy-Q Development System

C Type Expressions In Watch PaneThe following ‘C’ type expressions, shown in order of precedence, may be used toevaluate expressions within the Watch View of a Project:[]array subscript->

record lookup~-*&

unary prefix*/%

multiplicative+-

additive<< >>bitwise shifting<> <= >=

comparatives== !=equalities&

bitwise and^bitwise xor|

bitwise orNote: As in C, parenthesis can be used to override precedence.

Psy-Q Development System

Assigning Variables
Any variable that evaluates to a ‘C’, l-type expression can be assigned a new value.
For example, in the case of a de-referenced pointer, a new value can be assigned tothe pointer or the de-referenced expression.

4

Variables are assigned as follows:
1. Place the caret over the required expression to make it Active.
2. Press ‘=‘.
3. Enter the new value to the displayed dialogue box; this can be another expression
if required.
4. Click.

In the example below, this facility was used to assign a new value of 0x80002000 to
the specified pointer. The de-referenced structure changes to reflect the amended
value.

Displayed Structures For Pointer Address

Psy-Q Development System

Amended Structures After Pointer Assigned New Variable

IMPORTANT: The expression that you are assigning and the new value, musthave compatible types.
Note: Variables can be assigned whilst the Target is running.

Expanding Or Collapsing A Variable
Pointers, structures and arrays are variables which can be expanded or collapsed in
the Local or Watch Panes when you place the caret over them.
If you expand a pointer a line will be added below for the dereferenced pointer. For
example if the pointer is to an integer, the dereferenced pointer will display that
integer.
An expanded structure will display all the elements of that structure below it.
For an expanded array the second line of the display will display the first element of
the array.

4

To expand or collapse a variable:
1.

Select the Pane menu for the Local or Watch Panes.

2.

Choose the Expand or Collapse option from the menu.

Psy-Q Development System

When shown in the Watch Pane, expressions which can be expanded or collapsed will
be prefixed as follows:+

this indicates an expression that can be expanded-

this indicates that the expression is expanded and can beclosed.

This is followed by the expression’s type and value.

4

To edit an expression highlight it and press Return.

Note: It is also possible to expand or collapse an expression by using the expand or
collapse icons

on the Pane toolbar or pressing SPACE.

Traversing An Index
You can traverse an index if the caret is on an array element in the Local or Watch
Panes.
If an index is increased, the array will display the next array element.
Decreasing an index causes the previous array element to be displayed.

4

To increase or decrease an index:
1.

Select the Pane menu for the Local or Watch Panes.

2.

Choose the Increase Index or Decrease index option from the menu.

Note: It is also possible to expand or collapse a variable by using the increase index
or decrease index icons

on the Pane toolbar.

Psy-Q Development System

Adding A Watch
The Watch Pane is used to evaluate and browse C type expressions.

4

To add a watch or expression :1.

Make the Watch Pane the Active Pane.

2.

Select the Watch Pane menu from the Menu bar.

3.

Choose the Add Watch option from the menu.

4.

Type the required expression directly into this box or click the down arrow todisplay expressions which have been used previously.

Add Watch Dialogue Box
5.

Enter or click the required expression and selectThe Debugger also offers various ‘matching’ facilities whereby you can enter a partial
value and the program will search the current and global scopes for those matching
the specified criteria. These are described below in Additional Features WhenEntering Expressions.

Note: It is also possible to add a watch by clicking on the add watch icon
the Watch Pane toolbar.

See Also:
Expression Evaluation Features

Psy-Q Development SystemonAdditional Features When Entering Expressions
Simple Name Completion

4

With this facility, the program will attempt to complete the symbol to the right of thespecified expression, as follows:1.

Enter a partial expression to the Add Watch dialogue box.

2.

Click

or press Alt-M.

If you had specified:attr_
The Debugger will search for all symbols beginning with ‘attr’, first in the current
scope and then in the global scope.
If a single match is found, the specified expression will be completed automatically.
If more than one is located a dialogue box will list all matching symbols.

Symbol Selection Dialogue Box

3.

Highlight (select) the required symbol and click. See Multiple
Selection below for further details. The status line will display ‘no matches found’
where relevant.

Psy-Q Development System

Advanced Symbol Matching

4

In addition to basic name completion which always completes the symbol at the endof the specified expression, extended name completion can be used to complete asymbol anywhere in the expression, as follows:1.

Enter a partial expression.

2.

Place the caret (insertion point) on or at the end of the symbol you wish tocomplete and according to the group you wish to search, press one of thefollowing key combinations:
Alt-N - All symbols (Normal)
Alt-G - Global (Static & external variables)
Alt-L - Local (Automatic variables in scope)
Alt-F - Functions (Static & external)
Alt - T - Types (Typedef & structure tag).
Matching expressions will be displayed as described above.

3.

Highlight (select) the required symbol(s) and click.

Note: This advanced matching facility is only available from the keyboard.
Note: You cannot symbol match on register or label names.

Wild-Card Matching4

It is also possible to locate a particular symbol via the entry of a wild-card
expression. This can include ‘*’s (to match any number of characters) and ‘?’s (tomatch any single character) and is used as follows:1.

Enter a wild-card expression, for example *tion.

2.

Select it via Shift+Left Arrow or by double-clicking.

3.

Press Alt-N.

The Debugger will continue as described for Extended Name Completion. In theexample specified above it will search for all symbols ending in ‘tion’, first in thecurrent scope and then in the global.

Psy-Q Development System

Multiple Selection

4

If you are name completing or wild-card matching a single symbol and more than one
match is found, you can select all or some of the matches and add them to the Watch
Pane at the same time. Where several matches are found, they will be presented in an‘extended selection’ list box.
1.

Select symbols as required; use the mouse and Ctrl and/or shift keys to make aspecific selection or click

to highlight all the matched symbols.

Multiple Symbol Selection Dialogue Box

Use the mouse and Ctrl key to de-select a particular symbol from your list or
click

to de-select all the symbols

2.

When your selection is complete, click; the value in the dialogue entry
box will change to <multiple selection>. Note that this value cannot be edited.

3.

Click

to add your selection to the Watch Pane.

Note: To browse all symbols, clickwith no value in the dialogue box or
wild-card match using ‘*’ as the wild-card.

Psy-Q Development System

Editing A Watch

4

Any of the C type expressions that you can enter into the Watch Pane can be edited
as follows:1.

Make the Watch Pane the Active Pane.

2.

Select the Watch Pane menu from the Menu bar.

3.

Choose the Edit Watch option from the menu.

4.

Select the watch to edit.

5.

Amend as necessary and click
available via this dialogue box.

. History and matching facilities are

Note: It is also possible to edit a watch by clicking on the Edit Watch icon
the Watch Pane toolbar.
Note: To view variables in hexadecimal, right-click within the Pane and ‘toggle’‘Hexadecimal/Decimal’ as necessary. A tick will appear alongside
Hexadecimal when this option has been selected.

See Also:
Additional Features When Entering Expressions
Previously Entered Expressions History List

Psy-Q Development SystemonDeleting A Watch

4

Any of the C type expressions entered into the Watch Pane can be deleted as follows:1.

Make the Watch Pane the Active Pane.

2.

Select the Watch Pane menu from the Menu bar.

3.

Choose the Delete Watch option from the menu.

4.

Select the watch and press Enter.

Note: It is also possible to delete a watch by clicking on the Delete Watch iconon the Watch Pane toolbar or pressing DEL.
Note: You can only delete a Watch at the root of the expression, not on any
expanded part of it.

Clearing All Watches4

All of the C type expressions entered into the Watch Pane can be removed in one
action, as follows:1.

Make the Watch Pane the Active Pane.

2.

Select the Watch Pane menu from the menu bar.

3.

Choose the Clear All Watches option from the menu.

Note: You can also clear all watches by clicking on the Clear All Watches iconon the Watch Pane toolbar.

Psy-Q Development System

Debugging Your Program
The Psy-Q Debugger helps you to detect, diagnose and correct errors in yourprograms. This is achieved via facilities which enable you to step and trace throughyour code in order to examine local and global variables, registers and memory.
Breakpoints can be set wherever you need them at C and Assembler level and if
required, these breaks can be made conditional on an expression. Additionally,
selected breakpoints can be disabled for particular runs.
Your choice of Views depends on the level at which you are debugging. For example
it is appropriate to use a Register Pane for assembler debugging and a Local Panewhen debugging in C.

Specifying The Continual Update Rate4

It is possible to adjust the rate at which the Debugger updates information while theTarget is running. This is particularly important for Targets which connect
independently of a pollhost( ) since rapid connection rates may cripple the Target. It
is achieved as follows:1.

Select Continual Update Rate from the Project option on the main menu or press
Ctrl+I. A dialogue box displays the current rate in milliseconds:

Update Rate Dialogue Box
2.

Enter a new value and selectsessions and not as part of a Project.

. The rate is saved between all debugging

Psy-Q Development System

Forcing An Update
During continual update, the information you see in the Debugger windows won’t be
updated until the next connection; therefore, the slower the update rate, the longer itwill be before exceptions can be spotted. However, it is possible to force an updateby pressing Ctrl+U or selecting the Update option from Debug on the main menu.

Setting Breakpoints
Breakpoints can be set in the Source and Disassembly Panes. They can be absolute(i.e. always break) or conditional upon an expression.
They are displayed in the Pane as a different coloured bar.

4

To set a breakpoint:
1.

Make a Source or Disassembly Pane Active.

2.

Click on the instruction or line at which you want to set the break.

3.

Select the Debug menu from the Menu bar.

4.

Choose the Toggle breakpoints option from the menu.

Breakpoints can be made conditional upon an expression that you set, by using theEdit Breakpoint dialogue box found via the Breakpoints List on the Unit Menu.
A Project can have many breakpoints set and they are saved when the Project issaved. They are restored relative to Assembler labels wherever possible; this ensuresthey are preserved even when you alter the source code and rebuild.
Breakpoints can be removed by clicking on the colour bar and reversing the toggle
options taken to create it.

Note: Breakpoints can also be set and removed via the F5 key or the set / unset
breakpoint icons on the Pane toolbar.

Psy-Q Development System

Editing Breakpoints
The Breakpoints option on the Unit menu can be used to enable or disablebreakpoints for a particular debugging run or to make the breakpoints conditional on
an expression that you set.
The Breakpoints option on the Unit menu shows you a pop-up list of all the
breakpoints currently set in the Project, the address where they are located and thelabel (if one exists).
Enabled breakpoints will have a tick beside them.

4

To edit breakpoints:
1.

Select the Unit menu by clicking on the Unit button.

2.

Choose the Breakpoints option from the menu.

3.

Select the breakpoint you wish to edit.

Edit Breakpoint Dialogue Box

When you select a breakpoint from the list displayed on the Unit menu, the Edit
Breakpoint dialogue box shown above appears.
The enabled check box allows you to enable and disable breakpoints. When the
check box is set the breakpoint is enabled and only these will be included in a
debugging run.

Psy-Q Development System

There are two types of break:• Break at Point is a standard break.
• Break if expression is true is a conditional break.
4.

Select the type of break you require from the Type box pull-down list.
Both options display the breakpoint address in the Location box. The location canbe overtyped to move a break.
When the Break if expression is true option is enabled to create a conditional
breakpoint, enter a C like expression or a label in the Expression box.

5.

Use
made.

to leave the dialogue box without saving the changes you haveUse

to delete the selected breakpoint.

Clickwhen you have made all your changes.

Note: A quick way to make a breakpoint conditional is to place the cursor over a
breakpoint and use the Hot Keys Shift F5.

Any of the following methods can be used to create, remove and edit breakpoints:
The F5 key
The Breakpoint options from the Source or Disassembly Pane menus
The Breakpoint icons from the Pane toolbars

Psy-Q Development System

Stepping Into A Subroutine
The Step Into command allows you to trace the execution of the program one step at
a time and so isolate any bugs that might be present.
When you Step Into a subroutine call, the Program Counter moves to the start of thesubroutine and displays the relevant code. At the end of the subroutine you will be
returned to where it was called from.
At Assembler level a debugging step is the execution of a single instruction.
If you wish to use the Step Into command at Source level you must make the Source
Pane Active. In this case, one line at a time will be executed in each step and any
subroutines or calls within that line will be stepped into.

4

To Step Into a subroutine during debugging:
1.

Select the Debug menu from the Menu bar.

2.

Choose the Step Into option from the menu.

Note: Alternative ways of Stepping Into a subroutine are to use the Step Into iconon the Unit toolbar (at the bottom of the Debugger window)
or to press
F7. Note that it is possible to use the Step Into icon for a non-Active View.

Psy-Q Development System

Stepping Over A Subroutine
When you use the Step Over command, the subroutine is executed but not displayed
and the Program Counter moves to the next line of calling routine code.
At Assembler level a debugging step is the execution of a single instruction.
If you wish to use the Step Over command at Source level, you must first make theSource Pane Active. In this case, one line at a time will be executed in each step andany subroutines or calls within that line will be performed.

4

To Step Over a subroutine:
1.

Select the Debug menu from the Menu bar.

2.

Choose the Step Over option from the menu.

Note: Alternative ways of Stepping Over a subroutine are to use the Step Over iconby the Unit menu
or to press F8. Note that you can use the Step Overicon for a non-Active View.

Psy-Q Development System

Running To The Current Cursor Position
The Run to Cursor command can be used during debugging within the Source andDisassembly Panes.

4

To run to the current cursor position:
1.

Make a Source or Disassembly Pane active.

2.

Click on the displayed code at the point you want to run to.

3.

Select the Source or Disassembly menu from the Menu bar.

4.

Choose the Run To Cursor option from the menu.

If the Unit does not reach the cursor position it will continue running.
Note: Alternative methods of running to the cursor are to click on the Run To
Cursor icon on the Pane toolbar

or to use the Hot Key F6.

Note: You can use Run To Cursor while the Unit is running to make it stop at the
cursor position.

Psy-Q Development System

Running Programs
The Run command causes the CPU of the specified Unit to start running.
It will continue until it meets a breakpoint, a processor exception or is stopped by the
Stop or Run To Cursor commands.
During a debugging run the various Panes will show the progress of the run.

4

To start the program running:
1.

Select the Debug menu from the menu bar.

2.

Choose the Go option from the menu.

Note: Alternative ways to start the run are to click the Start button on the relevant
Unit toolbar

or to press F9.

Stopping A Program Running
The Stop command halts the CPU of the specified Unit as soon as possible.

4

It is specified as follows:1.

Select the Debug menu from the Menu bar.

2.

Choose the Stop option from the menu.

Note: Alternative ways to stop the run are to click the Stop button on the relevant
Unit toolbar

or to press Esc.

Psy-Q Development System

Moving The Program Counter
The program counter (PC) can be set via the Set PC command.
This command moves the program counter to the current cursor position.

4

It is found on the Pane menus for Source and Disassembly Panes and is set as
follows:
1.

Make a Source or Disassembly Pane Active.

2.

Place the caret where you wish the PC to move to.

3.

Click the right hand mouse button to call the Pane menu.

4.

Select the Set PC option from the menu.

With this command, no instructions are executed between the previous and new PC
position.
The opposite command to Set PC is Goto PC which takes the cursor to the positionof the Program Counter.

Note: An alternative way to activate the Set PC command is by using the Hot Key
Shift+Tab.

Psy-Q Development System

Moving The Caret To The PC
The caret point can be placed at the program counter address via the Goto PC
command.
This is found on the Pane menus for Source and Disassembly Panes.

4

To Set The PC:
1.

Make a Source or Disassembly Pane Active.

2.

Click the right hand mouse button to call the Pane menu.

3.

Select the Goto PC option from the menu.

Goto PC is the opposite command to Set PC which sets the Program Counter to thevalue at the current caret position.

Note: Alternatively, pressing the ‘space’ bar will directly place the caret point at
the program counter address.

Psy-Q Development System

Moving To A Known Address Or Label

4

The Goto command is available on the Source, Disassembly and Memory Panemenus. It is used to put the caret and PC at a known address, label name, registername or value of a specified C expression as described below:
1.

Make the Source, Disassembly or Memory Pane Active.

2.

Click the right hand mouse button to call the Pane menu.

3.

Select the Goto option from the menu.

4.

A dialogue box appears in which you enter the memory address, symbol name,register name or C expression.

5.

Click

to place the cursor at the entry point.

Go To Expression Dialogue Box
6.

Type the required expression directly in this box or click the down arrow todisplay expressions which have been entered previously.

7.

Enter or select the required expression and click. Note that ahexadecimal address must be prefixed with the string ‘0x’

As the Goto action will take you to the value of the specified expression, note theconsequences when you enter a name containing C debug information as well as an
Assembler label.
For example, if ‘_ramsize’ is specified you will be taken to the value of _ramsize, notto where it is defined. This is because the C expression evaluator sees the C
definition of _ramsize first and then evaluates it. To Goto this address, you mustenter either ‘&_ramsize’ or ‘:_ramsize’.

Psy-Q Development System

Alternatively, you could Goto ‘main’ (as functions evaluate to their address); to
Goto an offset from main, enter: ‘:main+offset’, ‘&main+offset’ or‘(int)main+offset’. This is because ‘main’ by itself has the type int ( ) which cannot
be added.

Note: When you have successfully ‘gone to’ an expression in a Memory Pane, the‘pointed to’ word is enclosed in a box. This will remain until you Goto
something else or anchor the Pane to an expression.

See Also:
Anchoring Memory Panes
Expression Evaluation Features
Previously Entered Expressions History List
Note: Alternatively, you can activate the Goto command via the Goto icon on the
toolbaror the Hot Key Ctrl G.

Psy-Q Development System

Expression Evaluation Features
Register Names
Register names can be specified in any dialogue box where expressions can beentered. By default, the evaluator looks for C symbols first, so any variables which
are the same as register names will be shown instead. If a name is being interpreted
as a register it will be prefixed by a ‘$’.
It is recommended that you use this ‘$’ prefix when entering register names toexplicitly tell the evaluator that it is looking at a register.
Note: Registers have a C type of ‘int’.

Typecasts and Typedefs
Typecasts can be entered to an expression via the usual C syntax.
If you entered ‘(int*)$fp’ to a Watch Pane you would see the following:+int*(int*)$fp = 0x8000ff00
Typecasting also works for structure tags; however, you are not required to enter
the keyword ‘struct’ when csting to a structure tag.
You would expect to see the following when typecasting to a structure (or class):-Tester* (Tester*)$fp = 0x807ff88-Tester+unsigned char* m_pName = 0x00000645+unsigned char* mpLongName = 0xFFFFFFFF
You can also cast to typedefs; for example, entering ‘(daddr_t)p’ will produce:
long (daddr_t)p = 0x00003024

Psy-Q Development System

Labels
Labels can also be included in a C expression. The evaluator looks for C level
information first and then label information. If it finds a label it will prefix it with a‘:’.
It is recommended that you use this prefix when entering labels to explicitly tell theevaluator that it is looking at a label.

Note: Labels have a C type of ‘int’.

FunctionsIf you include a function name in an expression, its value will be the same as its
address. It will appear in a Watch window as follows:int ( ) main = (...) (0x80010BFC)

Note: This is contrary to C where the value of a function, is what is returned fromthe function when it is executed.
Note: It is recommended that you access the address of a function via the ‘&’
operator or the Assembler label.

Expression Evaluation Name Resolution
In summary, the search order for a name in an expression is as follows:1.

Escaped Register Names (prefix ‘$’)2.

Escaped Label Names (prefix ‘:’)3.

C Names

4.

Register Names

5.

Label Names

Psy-Q Development System

Previously Entered Expressions History List
Once an expression has been specified via a Goto or Add/Edit Watch dialogue box, it
will be stored in a history buffer.
When you next access one of these dialogue boxes, click the down arrow to display alisting of these values.
At this point you can enter a new expression to the dialogue box or select one fromthe list and click. The selected expression can also be edited at this point.

Note: The most recent expressions used are held at the top of the list.

Anchoring Panes To The PC
By default the Source and Disassembly Panes are anchored to the Program Counter(PC).
This means that whenever possible the instruction or line at the PC is always
displayed in the Pane.

4

The Follow PC property is toggled as follows:1.

Make a Source or Disassembly Pane Active.

2.

Click the right hand mouse button to call the Pane menu.

3.

Select the Follow PC option from the menu.

Note: This option is also available from the Source and Disassembly Pane toolbar
or from the Source or Disassembly menus on the Menu bar.

Psy-Q Development System

Anchoring Memory Panes
Anchoring a Pane has the same function as using Goto on every Debugger update.

4

To anchor the Pane:
1.

Select Anchor... from the Pane menu or press Ctrl+A when a Memory Pane isactive.

2.

Enter an expression.

3.

Select.

The specified expression will appear in an indicator bar on the Pane. If this goes red,the expression cannot be evaluated in the current scope. Otherwise, the Pane will be‘anchored’ to the value of the expression and a box will be drawn around the anchor
point.
You can edit the expression by clicking the indicator.

4

To turn off anchoring:1.

Call up the Anchor dialogue box.

2.

Clear the box.

3.

Select.

Psy-Q Development SystemIdentifying Changed Information
Any changes to variables since the last debugging step are displayed in a colour of
your choice on all Panes except for Disassembly and Source.
This colour is set via the Set Default Colour option from the View menu.

See Also:
Changing colour schemes in Views

Closing The Debugger Without Saving Your
Changes
The Quit option on the Project menu stops the Psy-Q Debugger running but does
NOT save the current Project.

4

To close the Debugger without saving your changes:
1.

Select the Project menu from the Menu bar.

2.

Choose the Quit option from the menu.

Psy-Q Development System

Closing The Debugger And Saving Your
Changes
The Exit option on the Project menu saves the current Project at the latest state andstops the Psy-Q Debugger running.

4

To close the Debugger and save your changes:
1.

Select the Project menu from the Menu bar.

2.

Choose the Exit option from the menu.

Note: It is also possible to close the Project by clicking on the X icon on the systemmenu shown in the top right corner of the Debugger window.
Note: Next time you open the Debugger the last Project you saved will be launchedautomatically.

See Also:
Saving Your Project

Psy-Q Development SystemPsy-Q Development System

APPENDICES•

Appendix A - Error Messages

Psy-Q Development System

-1

Appendix A - Error Messages

This Appendix documents Psy-Q error messages, and is divided into the following sections:• Assembler Error Messages• PSYLINK Error Messages• PSYLIB Error Messages

Format:In the list below, %x represents the variable part of the error message, as follows:
%s
%c
%d
%l
%h
%n
%t

is replaced by a string
is replaced by a single characteris replaced by a 16 bit decimal number
is replaced by a 32 bit decimal number
is replaced by a 16 bit hexadecimal number
is replaced by a symbol nameis replaced by a symbol type, e.g. section, symbol or group.

Psy-Q Development System

Assembler Error Messages
Assembler Messages:'%n' cannot be used in an expression%n will be the name of something like a macro or register'%n' is not a group
Group name required'%n' is not a section
Section name expected but name %n was found
Alignment cannot be guaranteed
Warning of attempt to align that cannot be guaranteed due to the base alignment of
the current section
Alignment's parameter must be a defined name
In call to alignment( ) function
Assembly failed
Text of the FAIL statement
Bad size on opcode
E.g. attempt to use .b when only .w is allowed
Branch (%l bytes) is out of range
Branch too far
Branch to odd address
Warning of branch to an odd address
Cannot POPP to a local label
E.g. POPP @x
Cannot purge - name was never defined
Case choice expression cannot be evaluatedOn case statement
Code generated before first section directive
Code generating statements appeared before first section directive
Could not evaluate XDEF'd symbol
XDEF'd symbol was equated to something that could not be evaluated

Psy-Q Development System

-3

Could not open file '%s'
Datasize has not been specified
Must have a DATASIZE before DATA statement
Datasize value must be in range 1 to 256
DATASIZE statement
Decimal number illegal in this radix
Specified decimal digit not legal in current radix
DEF's parameter must be a name
Error in DEF( ) function reference
Division by zeroEnd of file reached without completion of %s construct
E.g. REPT with no ENDR
ENDM is illegal outside a macro definition
Error closing file
DOS close file call returned an error status
Error creating output file
Could not open the output file
Error creating temporary file
Could not create specified temporary file
Error in assembler options
Error in expression
Similar to syntax error
Error in floating point number
In IEEE32 / IEEE64 statement
Error in register list
Error in specification of register list for MOVEM / REG
Error opening list file
DOS open returned an error status
Error reading file
DOS read call returned an error status

Psy-Q Development System

Error writing list file
DOS write returned an error status or disk fullError writing object file
DOS write call returned an error or disk is fullError writing temporary file
Disk write error, probably disk fullErrors during pass 1 - pass 2 aborted
If pass 1 has errors then pass 2 is not performed
Expanded input line too long
After string equate replacement, etc. line must be <= 1024 chars
Expected comma after < ><...> bracketed parameter in MACRO call parameter list
Expected comma after operand
Expected comma between operands
Expected comma between options
In an OPT statement
Expecting '%s' at this point
Expecting one of ENDIF/ENDCASE etc. but found another directive
Expecting '+' or '-' after list command
In a LIST statement
Expecting '+' or '-' after option
In an OPT statement
Expecting a number after /b option
On Command line
Expecting comma between operands in INSTR
Expecting comma between operands in SUBSTR
Expecting comma or end of line after list
In { ... } list
Expecting ON or OFF after directive
In PUBLIC statement

Psy-Q Development System

-5Expecting options after /O
On Command line
Expecting quoted string as operandExpression must evaluate
Must be evaluated now, not on pass 2
Fatal error - macro exited with unterminated %s loop
End of macro with unterminated WHILE/REPT/DO loop.
Due to the way the assembler works, this must be treated as a fatal error
Fatal error - stack underflow - PANIC
Assembler internal error - should never occur!
File name must be quoted
Files may only be specified when producing CPE or pure binary
outputIn FILE attribute of group
Forward reference to redefinable symbol
Warning that a forward reference was made to a symbol that was given a number ofvalues in SET or = statements. The value used in the forward reference was the lastvalue the symbol was set to.
Function only available when using sections
Group '%n' is too large (%l bytes)
Group exceeds value in SIZE attribute
GROUP's parameter must be a defined name
In GROUP( ) function call
GROUPEND's parameter must be a group name
Error in call to GROUPEND( ) function
GROUPORG's parameter must be a group
In call to GROUPORG( ) function
GROUPSIZE's parameter must be a group name
Error in call to GROUPSIZE( ) function
IF does not have matching ENDIF/ENDC
Illegal addressing mode
Addressing mode not allowed for current op code

Psy-Q Development System

Illegal character '%c' (%d) in input
Strange (e.g. control) character in input file
Illegal character '%c' in opcode field
Illegal digit in suffixed binary number
In alternate number form 101b
Illegal digit in suffixed decimal number
In alternate number form 123d
Illegal digit in suffixed hexadecimal number
In alternate number form 1abh
Illegal group name
Illegal index value in SUBSTR
Illegal label
Label in left hand column starts with illegal character
Illegal name for macro parameter
In macro definition
Illegal name in command
Target name in ALIAS statement
Illegal name in locals list
In LOCAL statement
Illegal name in XDEF/XREF list
Illegal parameter number
Maximum of 32 parameters
Illegal section name
Illegal size specifier for absolute address
Can only use .w and .l on absolute addressing
Illegal start position/length in INCBIN
Illegal use of register equate
E.g. using a register equate in an expression
Illegal value (%l)
Illegal value (%l) for boundary in CNOP

Psy-Q Development System

-7
Illegal value (%l) for offset in CNOP
Illegal value for base in INSTR
Initialised data in BSS section
BSS sections must be uninitialised
Instruction moved to even address
Warning that a padding byte was inserted
Label '%n' multiply defined
LOCAL can only be used inside a macro
LOCAL statement found outside macro
Local labels may not be strings@x EQUS ... is illegal
Local symbols cannot be XDEF'd/XREF'd
MEXIT illegal outside of macros
Missing '(' in function call
Missing ')' after function parameter(s)Missing ')' after file name
In FILE attribute
Missing closing bracket in expression
Missing comma in list of case options
In =... case selector
Missing comma in XDEF/XREF list
MODULE has no corresponding MODEND
Module may not end until macro/loop expansion is complete
If a loop / macro call starts inside a module then there must not be a MODEND until
the loop / macro call finishes
Module must end before end of macro/loop expansion - MODEND
inserted
A module started inside a loop / macro call must end before the loop / macro call
does

Psy-Q Development System

More than one label specified
Only one label per line (can occur when second label does not start in left column but
ends in ':' )Move workspace command can only be used when downloading
In WORKSPACE statement
Names declared with local must not start with '%c'
In LOCAL statement
NARG can only be used inside a macro
Use of NARG outside macro
NARG's parameter must be a number or a macro parameter name
Illegal operand for NARG( ) function
No closing quote on string
No corresponding IF
ENDIF/ELSE without IF
No corresponding DO
UNTIL without DO
No corresponding REPTENDR without REPT
No corresponding WHILE
ENDW without WHILE
No matching CASE statement for ENDCASEENDCASE without CASE
No source file specified
No source file on command line
Non-binary character following %Non-hexadecimal character '%c' encountered
In HEX statement
Non-hexadecimal character starting number
Expecting 0-9 or A-F after $Non-numeric value in DATA statement
OBJ cannot be specified when producing linkable output
OBJ attribute on group

Psy-Q Development System

-9
Odd number of nibbles specified
In HEX statement
OFFSET's parameter must be a defined name
Error in OFFSET( ) function call
Old version of %n cannot be purged
Only macros can be purged
One string equate can only be equated to anotherAttempt to equate to expression, etc.
Only one of /p and /l may be specified
On Command line
Only one ORG may be specified before SECTION directive
Op-code not recognised
Option stack is empty
POPO without PUSHO
Options /l and /p not available when downloading to target
On Command line
ORG ? can only be used when downloading output
ORG address cannot be specified when producing linkable
outputNo ORG group attributes when producing linkable output
ORG cannot be used after SECTION directive
ORG cannot be used when producing linkable output
ORG must be specified before first section directive
When using sections only one ORG statement may appear before all section
statements (other than as group attributes)
Out of memory, Assembler aborting
Out of stack space, possibly due to recursive equates
Assemblers stack is full, possible cause is recursive equates, e.g. x equ y+1 , y equ
x*2
Overflow in DATA value
DATA value too big

Psy-Q Development System

Overlay cannot be specified when producing linkable output
No OVER group attributes when producing linkable output
Overlay must specify a previously defined group name
Error in OVER group attribute
Parameter stack is empty
POPP encountered but nothing to pop
POPP must specify a string or undefined name
Possible infinite loop in string substitution
E.g. reference to x where x is defined as x equs x+1
Previous group was not OBJ'd
OBJ( ) attribute specified but previous group had no obj attribute to follow on from
Psy-Q needs DOS version 3.1 or later
Purge must specify a macro name
Radix must be in range 2 to 16
REF's parameter must be a name
Error in REF( ) function reference
Register not recognised
Expecting a register name but did not recognise
Remainder by zero
As for division by 0 but for % (remainder)
Repeat count must not be negative
REPT statement error
Replicated text too big
Text being replicated in a loop must be buffered in memory but this loop was too big
to fitResident SCSI drivers not present
PSYBIOS does not appear to be loaded
SCSI card not present - assembly aborted
SECT's parameter must be a defined name
Error in SECT( ) function call
SECTEND's parameter must be a section name
Error in call to SECTEND( ) function

Psy-Q Development System

-11Section stack is empty
POPS without PUSHS
Section was previously in a different group
Section assigned to a different group on second invocation
SECTSIZE's parameter must be a section name
Error in call to SECTSIZE( ) function
Seek in output file failed
DOS seek call returned error status
Severity value must be in range 0 to 3
In INFORM statement
SHIFT can only be used inside a macro
SHIFT statement outside macro
Short macro calls in loops/macros must be defined before
loop/macro
Short macros may not contain labels
Size cannot be specified when producing linkable output
SIZE attribute on group
Size specified in /b option must be in range 2 to 64
On command line
Square root of negative number
Statement must have a label
No label on, for example, EQU op
STRCMP requires constant strings as parameters
String '%n' cannot be shifted
String specified in SHIFT statement is not a multi-element string (i.e. {...} bracketed)and so cannot be shifted.
STRLEN's operand must be a quoted string
Symbol '%n' cannot be XDEF'd/XREF'd
Symbol '%n' is already XDEF'd/XREF'd
Symbol '%n' not defined in this module
Undefined name encountered

Psy-Q Development System

Syntax error in expression
Timed out sending data to target
Target did not respond
Too many characters in character constantCharacter constants can be from 1 to 4 characters
Too many different sections
There is a maximum of 256 sections
Too many file names specified
On command line
Too many INCLUDE files
Limit of 512 INCLUDE files
Too many INCLUDE paths specified
Too many INCLUDE paths in /j options on command line
Too many output files specified
Maximum of 256 output files
Too many parameters in macro callMaximum number of parameters (32) exceeded
Too much temporary data
Assembler limit of 16m bytes of temporary data reached
TYPE's parameter must be a nameCall of TYPE( ) function
Unable to open command file
From Command line
Undefined name in command
Target name in ALIAS statement
Unexpected case option outside CASE statement
Found =... statement outside CASE/ENDCASE block
Unexpected characters at end of Command line
Unexpected characters at end of line
End of line expected but there were more characters encountered (other thancomments)
Unexpected end of line

Psy-Q Development System

-13Unexpected end of line in macro parameter
Unexpected end of line in list parameter
In { ... } list
Unexpected MODEND encountered
MODEND without preceding MODULE
UNIT can only be specified once
In UNIT statement
UNIT cannot be used when producing linkable output
In UNIT statement
Unknown option
In OPT statement
Unknown option /%c
Unknown option on Command line
Unrecognised attribute in GROUP directive
Unrecognised optimisation switch '%c'
In OPT statement or Command line
User pressed Break/Ctrl-C
Assembly aborted by user
XDEF'd symbol %n not defined
Symbol was XDEF'd but never defined
XDEF/XREF can only be used when producing linkable output
Zero length INCBIN - Warning of zero length INCBIN statement

Psy-Q Development System

Psylink Error Messages
Linker Messages:%t %n redefined as section
New definition of previously defined symbol%t '%n' redefined as group
New definition of previously defined symbol%t '%n' redefined as XDEF symbol
New definition of previously defined symbol
Attempt to switch section to %t '%n'Non-section type symbol referenced in section switch
Attempt to use %t '%n' as a section in expression
Section type symbol required
Code in BSS section '%n'
BSS type sections should not contain initialised data
COFF file has incorrect format
COFF format files are those produced by Sierra C cross compiler, etc.
Different processor type specified
Object code is for different processor type than target or attempt was made to linkcode for different processor types
Division by zero
Error closing file
DOS close file call returned error status
Error in /e option
On Command line
Error in /o option
On Command line
Error in /x option
On Command line
Error in command file
Error in Linker options
On Command line

Psy-Q Development System

-15

Error in REGS expression
Error reading file %f
DOS read file call returned error status
Error writing object file
DOS write file call returned error status - probably disk fullErrors during pass 1 - pass 2 aborted
Pass 2 does not take place if there were errors on Pass 1
Expecting a decimal or hex number/o option on Command line
File %f is in out-of-date format
File should be re-built be re-assembling
File %f is not a valid library file
File %f is not in PsyLink file format
Group '%n' is too large (%l bytes)
Group is larger than its size attribute allows
Group '%n' specified with different attributes
Different definitions of a group specify different attributes
Illegal XREF reference to %t '%n'Object file defines xref to symbol which cannot be xref'd, e.g. a Section nameMultiple run addresses specified
More than one run address specified
No source files specified
No source file on Command line
Object file made with out-of-date assembler
File should be re-built before re-assembling
Only built in groups can be used when making relocatable
outputWhen /r command line option is used, only the built in groups can be used, i.e. no
new groups may be defined
Option /p not available when downloading to target
Options /p and /r cannot be used together
On Command line

Psy-Q Development System

ORG ? can only be used when downloading output
Out of memory, Linker aborting
Previous group was not OBJ'd
Cannot specify OBJ() attribute if previous group did not have obj attribute
Reference to %t '%n' in expression
Use of, e.g. a section name in an expression
Reference to undefined symbol #%h
There is an internal error in the object file
Relocatable output cannot be ORG'dRemainder by zeroRun-time patch to odd address
Warning that a run-time longword patch to an odd address will occur which may
cause some Amiga systems to crash
SCSI card not present - linking aborted
Could not find SCSI card
SCSI drivers not loaded
PSYBIOS does not appear to be present
Section '%n' must be in one of groups code, data or BSS
When producing Amiga format code
Section '%n' placed in non-group symbol #%h
There is an internal error in the object file
Section '%n' placed in non-group symbol '%n'An attempt was made to place a section in a non-group type symbol
Section '%n' placed in two different groups
Section is placed in different groups
Section '%n' placed in unknown group symbol #%h
There is an internal error in the object file
Section '%n' must be in one of groups text, data or BSS
When producing ST format code
Symbol '%n' multiply defined
New definition of previously defined symbol

Psy-Q Development System

-17Symbol '%n' not defined
Undefined symbol
Symbol '%n' placed in non-section symbol #%h
There is an internal error in the object file
Symbol '%n' placed in unknown section symbol #%h
There is an internal error in the object file
Symbol in COFF format file has unrecognised class
COFF format files are those produced by Sierra C cross compiler, etc.
Timed out sending data to target
Target not responding or offline
Too many file names specified
Too many parameters on command line
Too many modules to link
Maximum of 256 modules may be linked
Too many symbols in COFF format file
COFF format files are those produced by Sierra C cross compiler, etc.
Unable to open output file
Could not open specified output file
Undefined symbol in COFF file patch record
COFF format files are those produced by Sierra C cross compiler, etc.
Unit number must be in range 0-127
Unknown option /%c
On Command line
Unknown processor type '%s'
Could not recognise target processor type
Unrecognised relocatable output format/r option on command line
User pressed Break/Ctrl-C
Linking aborted by user

Psy-Q Development System

Value (%l) out of range in instruction patch
Value to be patched in is out of range
WORKSPACE command can only be used when downloading output

Psy-Q Development System

-19

Psylib Error Messages
Librarian Messages:
Cannot add module : it already exists
Module may only appear in a library once
Could not create object file
Error creating object file when extracting
Could not create temporary file
Error creating temporary file
Could not open/create
DOS error opening file
Error reading library file
DOS error reading file
Error writing library file
DOS error writing file, probably disk full
Incorrect format in object file
Error in object file format - re-build it
No files matching
No object files matching the specifications were foundNo library file specified
No object files specified
No option specified
An action option must be specified on the command line
Unknown option /On Command line, option not recognised

Psy-Q Development SystemPsy-Q Development System

Symbols- ....................................................3-9, 14-2
! ............................................................. 3-9!x ........................................................... 15-7
# .........................................5-5, 11-15, 15-8
$ .............................................3-4, 3-11, 5-5$x ........................................................... 15-6
% ......................................................3-4, 3-9%d, %h, %s .............................................. 9-8& ...............................................3-2, 3-9, 5-4&0 ........................................................ 11-14' ............................................................. 4-6( ) ............................................................. 3-9* ...............................................3-5, 3-9, 5-6+ ............................................................. 3-9. ............................................................. 3-3/ . 1-8, 1-14, 2-2, 3-9, 11-2, 12-2, 13-2, 15-2/&n ......................................................... 11-3
: ............................................................. 3-3; ............................................................. 3-2< ............................................................. 3-9< >............................................................ 5-3<<............................................................. 3-9<=............................................................. 3-9<>............................................................. 3-9= .............................................3-9, 4-4, 4-32=? ........................................................... 4-32
> ....................................................3-9, 11-7>=............................................................. 3-9>>............................................................. 3-9? ....................................................3-3, 4-19
@ .2- 2,7, 3-3,5,6, 7-2, 9-4, 11-15, 12-3, 15-2
\ ...............................................3-4, 5-5, 5-6^ ............................................................. 3-9_ ............................................................. 3-3__RS..................................................3-5, 4-9_filename .................................................. 3-5{ ......................................................4-5, 5-6| ............................................................. 3-9~ ............................................................. 3-9
A
Activity Windows.................................... 11-5
Adding A Watch ................................... 16-57
ALIAS .................................................... 3-12
Alignment ........................3-8, 4-20, 4-21, 8-4
Alternate Numeric..................................... 9-4

Anchoring a Pane ..................................16-78
array......................................................16-52
ASM68K...................................................2-1
Command Line ......................................2-2
Environment Variable ............................2-4
ASMSH
Command Line .............................. 2-6, 2-7Specific Features ...................................2-8
Assembler
Command File ............................... 2-2, 2-7
Comment Lines .....................................3-2
Constants ...................................... 3-4, 3-5Continuation Lines.................................3-2
Error Messages.............................2-5, 16-2
Functions....................................... 3-7, 3-8
Operators ..............................................3-9
Options.......................................... 9-3, 9-4
Running with Brief ..............................1-15
User Termination...................................2-4
Warning Messages.................................9-4
Assembler, White Space ............................9-4
Assigning Variables ...............................16-54
Assignment Directives ...............................4-2
AUTOEXEC.BAT ............................ 1-2, 1-7
Automatic Even.... 4-9, 4-13, 4-14, 4-15, 4-20
B
Beta Test Scheme....................................16-6
Break at Point .......................................16-66
Break if expression is true......................16-66
Breakpoints ................................11-17, 16-64
Brief........................................................1-15
Macros ................................................1-16
BSS..................................................4-15, 8-2
Buffer Size ................................................1-8
C
CASE......................................................4-32
Case Sensitivity .........................................9-4
CCSH .....................................................14-1
Command Line ....................................14-2
Character Constants ..................................3-4
CNOP ..............................................4-21, 8-4
Command Files
Assembler...................................... 2-2, 2-7
PSYLINK ...........................................12-4
Command Lines
ASMSH ........................................ 2-6, 2-7
Assembler..............................................2-2

Psy-Q Development System

CCSH ................................................. 14-2
Debugger ............................................ 11-2
PSYBIOS ............................................. 1-8
PSYLIB .............................................. 13-2
PSYLINK ........................................... 12-2
PSYMAKE ......................................... 15-2
RUN ................................................... 1-14
COMMAND.COM ................................. 15-5
completion ............................................ 16-59
Configuration Files.................................. 11-4
Configuring Your Dex Boards................. 16-9
Configuring Your SCSI Card ................ 16-10
Constants
Character .............................................. 3-4
Integer .................................................. 3-4
Location Counter .................................. 3-6
Special .................................................. 3-5
Time and Date....................................... 3-5
Continual Update Rate .......................... 16-63
Continuation Lines
Assembler ............................................. 3-2
Makros.................................................. 5-4
CPE File Properties............................... 16-22
CPE Files ............1-14, 2-3, 4-37, 11-2, 11-16
D
DATA..................................................... 4-17
DATASIZE ............................................ 4-17
Date Constants.......................................... 3-5
DBUGSAT ...............................See Debugger
DC.......................................................... 4-13
DCB ....................................................... 4-14
Debugger
Activity Windows................................ 11-5
Breakpoints....................................... 11-17
Command Line.................................... 11-2
Configuration Files .............................. 11-4
Cursor Movement ............................. 11-13
Debugging Control............................ 11-16
Disassembly Window ...... 11-6, 11-9, 11-17
Exiting .............................................. 11-15
Expressions ....................................... 11-15
File Accessing ................................... 11-16
File Window...................................... 11-17
Hex Window ............................ 11-7, 11-18
Keyboard Options ..........11-15,20,21,22,23
Mouse Usage .................................... 11-14
Moving Between Windows................ 11-12
Prompts ............................................ 11-15
Register Window...................... 11-6, 11-18
Selecting Window Type..................... 11-12

Source Level Window .........................11-8
Source Window.................................11-17
Var Window.............................11-8, 11-19
Watch Window.........................11-8, 11-18
Window Handling..............................11-15
Window Joining.................................11-13
Window Locking ...............................11-14
Window Re-sizing .............................11-12
Window Splitting...............................11-13
Decrease Index......................................16-49
DEF ........................................................4-28
Deleting A Watch..................................16-62
Diagnostics, Target Interface ...................1-13
DISABLE ...............................................3-12
Disassembly Window...........11-6, 11-9, 11-17
DMA Channel ...........................................1-8
DO..........................................................4-35
Documentation ......................................16-12
DS...........................................................4-15
E
Edit breakpoint......................................16-45
Editing A Watch....................................16-61
ELSE ......................................................4-30
ELSEIF...................................................4-30
END........................................................4-30
ENDC .....................................................4-30
ENDCASE..............................................4-32
ENDIF ....................................................4-30
ENDM ......................................................5-2
ENDR .....................................................4-33
ENDW ....................................................4-34
Environment Variables ...... 1-7, 1-15, 2-4, 9-7
EQU..........................................................4-3
See also ........................................2-3, 5-11
EQUR .......................................................4-7
See also ...............................................5-11
EQUS .......................................................4-5
See also ...............................................5-11
Error Messages .......................................16-1
Assembler.....................................2-5, 16-2
PSYLIB ............................................16-19
PSYLINK .........................................16-14
EVEN ..............................................4-20, 8-4
Expand/Collapse....................................16-49
Expanding Or Collapsing A Variable .....16-55
Expressions
Constants ..............................................3-4
Debugger...........................................11-15
Functions...............................................3-7
Makefiles.............................................15-7

Psy-Q Development System

Operators .............................................. 3-9
Extended Name Completion.................. 16-59
F
FAIL......................................................... 9-8
FILE ......................................................... 8-3
File Window.......................................... 11-17
Fileserver Functions .....10-3,4,5,6,7,8,9,10,12
Firmware Functions...................... 10-2, 10-11
Follow PC............................................. 16-45
Functions .............................................. 16-76
Alignment ............................................. 3-8
Fileserver .................10-3,4,5,6,7,8,9,10,12
FileSize ................................................. 3-8
Firmware.................................. 10-2, 10-11
GroupEnd ............................................. 3-8
GroupOrg ............................................. 3-8
GroupSize............................................. 3-8
SectEnd ................................................ 3-8
SectSize ................................................ 3-8
G
GLOBAL....................................... 9-10, 12-5
Goto ..................................................... 16-45
GROUP .................................................... 8-2
See also................................................. 9-5
Group Attributes
BSS .............................................4-15, 8-2
FILE ..................................................... 8-3
OBJ....................................................... 8-3
ORG ..................................................... 8-2
OVER................................................... 8-3
SIZE ..................................................... 8-3
with Sections......................................... 8-4
WORD.................................................. 8-2
H
HEX ....................................................... 4-16
Hex Window................................ 11-7, 11-18
I
IEEE32................................................... 4-17
IEEE64................................................... 4-17
IF 4-30
INCBIN .................................................. 4-26
INCLUDE .............................................. 4-24
See also................................................. 2-3
Increase Index....................................... 16-49
INFORM .................................................. 9-8
Installation
Check List............................................. 1-2

PC Interface ..........................................1-3
PC Software ..........................................1-7
Target Interface..........................1-10, 1-18
Installing The Debugger ..........................16-4
INSTR ......................................................6-4
IRQ Number .............................................1-8
L
Labels....................................................16-76
Format...................................................3-3
Local .....................................................7-1
Symbols.................................................3-3
Launching The Debugger ......................16-13
Librarian..................................... See PSYLIB
Linker ..................................... See PSYLINKLIST .........................................................9-6
LOCAL.....................................................7-5
Local Labels
Descope ................................................9-4
Signifier.................................................9-4
Within Modules .....................................7-4
Location Counter ......................................3-6
Locking Window, Debugger..................11-14
M
MACRO....................................................5-2
See also .................................................5-6
Macros......................................................5-8
Continuation Lines.................................5-4
Control Characters ................................5-6
Entire Parameter....................................5-6
Extended Parameters .............................5-6
Integers to Text .....................................5-5
Parameter Type ...................................5-11
Parameters.............................................5-3
See also ...............................................5-11
Unique Labels........................................5-5
MAKEFILE.MAK ..................................15-2
Makefiles.................................................15-3
Command prefixes...............................15-5
Comments ...........................................15-8
Dependencies ......................................15-3
Directives ............................................15-7
Executing Commands ..........................15-5
Expressions .........................................15-7
Implicit Rules ......................................15-4
Line Continuation ................................15-8
Macros ................................................15-6
Pre-defined Macros .............................15-6
Value Assignment................................15-7
MEXIT .....................................................5-2

Psy-Q Development System

MODEND ................................................ 7-4
MODULE................................................. 7-4
N
NARG ...................................................... 5-7
See also................................................. 3-5
NOLIST ................................................... 9-6
O
OBJ .................................................4-22, 8-3
OBJEND ................................................ 4-22
Obtaining Releases And Patches .............. 16-5
OFFSET ................................................... 8-7
On-line Help Available For The Debugger16-3
Operator Precedence ............................... 3-10
Operators.................................................. 3-9
OPT.......................................................... 9-2
See also................................................. 2-2
ORG ................................................4-19, 8-2
OVER....................................................... 8-3
PPane Type ............................................. 16-41
PC Interface
Installation ............................................ 1-3
PC Software
Installation ............................................ 1-7
pointer .................................................. 16-52
Poll Host, Firmware Function................ 10-11
POPO ....................................................... 9-6
POPP ........................................................ 5-9
POPS ........................................................ 8-6
Project .................................................. 16-19
PSYBIOS ................................................. 1-8
Command Line...................................... 1-8
PSYLIB.................................................. 13-1
Command Line.................................... 13-2
Error Messages ................................. 16-19
PSYLINK ............................................... 12-1
Command File ..................................... 12-4
Command Line.................................... 12-2
Error Messages ................................. 16-14
PSYMAKE............................................. 15-1
Command Line.................................... 15-2
Makefile.............................................. 15-3
PsyServe.exe......................................... 16-11
PUBLIC...........................................9-9, 12-6
PURGE................................................... 5-10
PUSHO..................................................... 9-6
PUSHP ..................................................... 5-9
PUSHS ..................................................... 8-6

RRADIX ...................................................3-11
REF ........................................................4-27
REG..........................................................4-8
see also................................................5-11
Register Names .....................................16-75
Register Window..........................11-6, 11-18
REGS......................................................4-37
REPT ......................................................4-33
RS.............................................................4-9
RSRESET ...............................................4-11
RSSET....................................................4-10
RUN .......................................................1-14
Command Line ....................................1-14
Run to cursor ........................................16-45
S
SCSI Id .................... 1-6, 1-8, 1-14, 2-3, 11-4
SCSI Interface Bus................................16-19
SECT ........................................................8-7
SECTION .................................................8-4
See also .................................................4-4
SET...........................................................4-4
See also ...............................................5-11
SHIFT.......................................................5-7
Simple Name Completion ......................16-58
SIZE .........................................................8-3
Source Level Window ..................11-8, 11-17
Specifying Binary File Properties ...........16-24
Specifying Symbol File Properties..........16-23
Step Into command ...............................16-67
Step Over command ..............................16-68
STRCMP ..................................................6-3
STRLEN...................................................6-2
structure................................................16-52
SUBSTR...................................................6-5
T
Target Interface
Firmware Diagnostics ..........................1-13
Firmware Functions ..................10-2, 10-11
Installation..................................1-10, 1-18
Text Window ..........................................11-8
Time Constants .........................................3-5
Toggle breakpoint .................................16-45
Toolbar Icons ........................................16-29
Traversing An Index..............................16-56
TYPE......................................................5-11
Typecasts and Typedefs.........................16-75

Psy-Q Development System

U
UNIT ...................................................... 4-37
Unit toolbar........................................... 16-17
UNTIL.................................................... 4-35
V
Var Window ................................ 11-8, 11-19
W
Warnings, Assembler Messages................. 9-4
Watch Window ............................ 11-8, 11-18
WHILE................................................... 4-34
White Space, Assembler............................ 9-4

wild-card expression..............................16-59
WORD......................................................8-2
See also .................................................9-5
X
XDEF ..............................................9-9, 12-6
See also ...............................................5-11
XREF....................................... 9-5, 9-9, 12-6
See also ...............................................5-11
Z
Zilog Numbers................................... 3-4, 9-4

Psy-Q Development System