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 SN SYSTEMS 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.
Please note that as the Psy-Q System software is constantly being updated, it is quite likely that 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 are available for download via the SN Systems BBS.
Contents Introduction ...................................................................................................................................i About Psy-Q ........................................................................................................................ ii Psy-Q for Sega Saturn......................................................................................................... iii Psy-Q Issue Information...................................................................
Data Definition.........................................................................................................................4-12 DC..................................................................................................................................4-13 DCB ...............................................................................................................................4-14 DS ...............................................................................................
Local Labels ...............................................................................................................................7-1 Syntax and Scope..............................................................................................................7-2 MODULE and MODEND.................................................................................................7-4 LOCAL...................................................................................................................
The PSYLINK Linker..............................................................................................................12-1 PSYLINK Command Line...............................................................................................12-2 Linker Command Files ....................................................................................................12-4 GLOBAL........................................................................................................................
Naming A View...............................................................................................................16-34 Changing Colour Schemes In Views ................................................................................16-35 Working With Panes........................................................................................................16-37 Splitting Panes.................................................................................................................
Introduction Psy-Q for the Sega Saturn is a fast PC based cross development system for producing and testing mixed C and/or assembler programs for the Sega Saturn games 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.
About Psy-Q • Psy-Q has been developed by Psygnosis and SN Systems, with many years of experience of development software and developers' needs. Psy-Q represents the next generation of development systems, backed up by a commitment to continual 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 popular development systems.
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 on battery-backed SRAM to allow for future firmware updates. Also included are assorted functions for useful run-time control of the development environment, as well as extensive fileserver facilities, to allow the target to manipulate files on the host PC.
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.
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.BAT COPYING COPYING.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.
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.
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 in this chapter under the following headings: • • • • • • Installation Check List Installing the PC Interface Installing the PC Software PSYBIOS Installing the Target Interface Firmware Diagnostics Psy-Q Developm
Installation Check List • Check the configuration of the Psy-Q PC board and install in the host PC - see later 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.
Installing the PC Interface The Psy-Q PC Interface board should be fitted in to an empty 16 bit slot in the host PC. 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, this causes 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.
DIP SWITCHES The PC card is configured by altering the three dip switch banks on the card. These switches alter: DMA IRQ SCSI Termination Power IO 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 Used SCSI Termination Power IO Address - A3 - A8 Card SCSI ID DMA DEFAULT On, On Off, Off Off, Off On Off Off Off Off Off Off, Off On Off, On, On, On, On, Off On, On, On DMA channels 5, 6, and 7 are available on the PC card.
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 Power The 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 increments of 8.
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.
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.
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. Syntax PSYBIOS [switches] where each switch is preceded by a forward slash ( / ) and separated by spaces.
Remarks • • • • • Examples Normally, PSYBIOS.COM is loaded in the AUTOEXEC.BAT; it can safely be loaded 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 mode of operating the interface.
Installing the Target Interface WARNING: Never insert or remove the Psy-Q Target Interface when the target is switched 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.
If you are using a ‘Programming Box’, then you should install the Interface in a similar 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 not suitable for developing programs.
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 no parameters). 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.
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 down then the adapter firmware will print to the screen to report on it's current configuration and the results of some more extensive self-tests.
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.
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 superstructure with 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.
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 your projects you will find the additional Psy-Q keystrokes much more convenient and powerful.
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 and add 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 and debugger.
Installing the Windows ’95 Debugger Installation Instructions Note: You will need to know your Psy-Q SCSI card hardware resource settings to complete 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 the Windows ‘95 Debugger. Installing Automatically from Floppy Disk Ensure there is at least 1.5mb free on your C drive and in addition, 2.
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.
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.
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.
/j pathname Nominate a search path for INCLUDE files. /k Permits the inclusion of pre-defined foreign conditionals, such as IFND - see also MACROS, chapter 5. /l Output a file for the Psylink Linker. /m Expand all macros encountered. /o options Specify Assembler options - see chapter 9 for a 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.
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 require a DOS operation to spot it) Pressing Esc • Examples The Assembler checks for an environment variable called ASM68K or ASMSH.
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.
The ASSH Assembler ASSH is not intended for assembling hand-written assembly code but ASMSH was written for this purpose and provides a number of powerful macro facilities for convenient 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.
Assembler Command Line Syntax ASMSH /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.
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 for the 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).
• 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 the assembler does not know the destination of the jump. e.g.
clearscr module mov.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.
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 and translated into a machine-readable format. Normally, the format of Assembler statements will mirror the format of the host language, and the Assemblers follow this convention.
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 then taken 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.
Format of Names and Labels Names and Labels consist of standard alpha-numeric symbols, including upper-case letters, 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 not when referenced. Question Mark (?), Underscore (_), Dot (.) These three characters are often used to improve the overall readability AT sign @ Indicates the start of a local label - see chapter 7.
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.
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 month 0 = Sunday; 6 = Saturday 00 - 23 00 - 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.
Location Counter constants: The current value of the program pointer can be used as a constant. To substitute the value of the location counter at the current position, an asterisk (*) is used: Firstbss section equ 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.
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 the following pages.
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 a symbol 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.
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 positive a is negative (see Note1) = + * / % Binary Binary Binary Binary Binary Binary 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 << >> Binary Binary a<>b Shift a to the left, b times Shift a to
Hierarchy of Operators Expressions in the Assemblers are evaluated using the following precedence rules: • Parentheses form the primary level of hierarchy and force precedence - their contents 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 their associativity - normally, from left to right, except unary operators.
11 RADIX Description The Assemblers default to a base of 10 for integers. This may be changed by preceding 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. Syntax RADIX newbase Remarks 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 to a decimal base.
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. Syntax newname Remarks Symbolic names currently known to the Assemblers may be ALIASed and DISABLEd. However, these directives must not be used to disable Assembler directives.
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.
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 Description Assigns the result of the expression, as a constant value, to the preceding symbolic name. Syntax symbol 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 be saved 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 command line.
SET Description Assigns the result of the expression, as a variable, to the preceding symbolic name. Syntax symbol 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 to contain forward references. If a SET cannot be evaluated as it is currently defined, an error is generated.
EQUS Description Assigns a text or string variable to a symbol. Syntax symbol name EQUS "text" symbol name EQUS 'text' symbol name EQUS symbol name See Also EQU, SET Remarks Examples • Textual operands are delimited by double or single quotes. If it is required to include 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.
z equs "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\a converts to dc.l number123a SA equs 'StartAddress' ... dc.l \SA\4 converts to dc.l StartAddress4 Note To include single quotes in a string delimited by single quotes, either change the delimiters to double quotes, or double-up the internal single quote.
EQUR Description Defines a symbol as an alternative for a data register or an address register. Syntax symbol name EQUR register name See Also REG Remarks • The major use of the EQUR directive is to improve the overall readability of the source code. • In order that the Assembler can evaluate the expression correctly, dots are not allowed as part of the symbol name of a EQUR (see example below). Examples cmp.b RGBinds(a2,d1.
REG Description Defines a symbol as an alternative for a list of data registers or address registers. Syntax symbol name REG list See Also EQUR Remarks Examples • As with EQUR, the main purpose of the REG directive is to improve the overall readability of the code. • Likewise, dots are not permitted in the symbol name of a REG. Windset reg ... d0-d7/a1-a2 lea movem.w movem.
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. Syntax symbol 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.
Icon_no Dropcode Actcode Actname Objpos Artlen 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 Syntax Assigns 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.
RSRESET Description Sets the __RS variable to zero. Syntax See Also RSRESET [value] RS, RSSET Remarks Examples • Using this directive is the normal way to initialise the __RS counter at the start of a new data structure. • The optional parameter is provided for compatibility with other assemblers; if present, RSRESET behaves like the RESET directive.
Data Definition The directives in this section are used to define data and reserve space.
DC Description This directive evaluates the expressions in the operand field, and assigns the results to the preceding symbol, in the format specified by the .size parameter. Argument expressions may be numeric values, strings or symbols. Syntax symbol 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.
DCB Description This directive generates a block of memory, of the specified length, containing the specified value. Syntax DCB.size where .size is .b .w .l length,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 for word and long word ensure that the program counter is aligned to the next word boundary. Examples dcb.b 256,$7F generates 256 bytes containing $7F. dcb.
DS Description Allocates memory to the symbol, of the specified length, and initialises it to zero. Syntax symbol name DS.size where .size is .b .w .l length byte word long 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 for word and long word ensure that the program counter is aligned to the next word boundary.
HEX Description This directive takes a list of unsigned hex nibble pairs as an argument, which are concatenated to give bytes. It is intended as a quick way of inputting small hex expressions. Syntax symbol name HEX hexlist See Also INCBIN Remarks Data stored as HEX is difficult to read, less memory-efficient and causes more work for the Assembler. Therefore, it is suggested that the HEX statement is used for comparatively minor data definitions only.
DATASIZE and DATA Description Syntax Together, 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.
Controlling Program Execution The directives in this section are used to alter the state of the program counter and control the execution of the Assembler.
ORG Description The ORG directive informs the Assembler of the location of the code in the target machine. Syntax ORG address[,parameter] where address is a previously-defined symbol, or a hex or decimal value, optionally preceded by a question mark (?) and followed by a (target-specific) numeric parameter. See Also OBJ, OBJEND, GROUP, SECTION Remarks • If a link file is output, the ORG directive must not be used - see Groups and Sections, chapter 8.
EVEN Description This directive aligns the program counter to the next word boundary. Syntax See Also EVEN CNOP Remarks Examples • There is a related assembler option, AE - Automatic Even. If set, the word and long 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.
CNOP Description Resets the program counter to a specified offset from the specified size boundary. Syntax CNOP offset,size boundary See Also EVEN Remarks As with the EVEN directive, 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 for that section. Therefore, a CNOP statement, with a size boundary of 2, is not allowed in a section that is byte-aligned. Examples section.l Firstoff = Firstsize = ...
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. Syntax OBJ 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.
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 and control their usage; also discussed are operators to aid the control of code to be assembled from INCLUDEd files.
INCLUDE Description Informs the Assembler to draw in and process another source file, before resuming the processing of the current file. Syntax INCLUDE filename where filename is the name of the source file to be processed, including drive and path identifiers - see Note. The filename may be surrounded by quotes, but they will be ignored. See Also INCBIN Remarks Traditionally, there will be one main file of source code, which contains INCLUDE's for all the other files. INCLUDEd files can be nested.
include include include maths.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 used or the backslash may be replaced by a forward slash (solidus). Thus, include d:\source\levels.asm may be re-written as: include d:\\source\levels.
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. Syntax symbol • • See Also INCBIN filename[,start,length] filename is the name of the source file to be processed, including drive and path identifiers - see Note1.
Note2 The 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 of code are to be INCLUDEd.
DEF Description Like the REF operator, DEF is a special function. It allows the programmer to determine 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. Examples loadadr execadr relocadr 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.
Controlling Assembly The following directives give instructions to the Assemblers, during the assembly process.
END Description The END directive informs the Assembler to cease its assembly of the source code. Syntax See 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. startrel move.w lea ...
Remarks • The ENDC and ENDIF directives are interchangeable. • If the ELSEIF directive is used without a following expression, it acts the same as 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. Examples sec_dir if equ Sega-MD 2 sec_dir elseif equ Sega-CD 1 else equ endif 3 sec_dir round round movopt tempstr num if macro add.
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.
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.
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 the ramifications of this. Examples MultP Indic Indic Note equ ... = while move.w ...
To avoid this, set a variable each time round the loop to indicate that looping should continue: s looping s looping 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. Syntax DO ...
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 Example For relocatable code, which is specific to the target, or pure binary code, this directive is not available.
CHAPTER 5 Macros The Assemblers provide extensive macro facilities; these allow the programmer to assign names to complete code sequences. They may then be used in the main program like existing assembler directives.
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 the macro 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 optional parameters, the source lines are pulled into the main program and expanded by substituting the place markers with the invocation parameters.
Macro Parameters Parameters Example Macro parameters obey the following rules: • The parameters listed on the macro invocation line may appear at any point in the code declared between the MACRO and ENDM statements. Each parameter is introduced 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.
Example Credits • Example macro dc.w dc.b dc.b even endm ... Credits \1,\2 \3 0 11,10, 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 terminated by an ampersand (&) and continued on the next line to improve readability. chstr cheatstr macro rept dc.b shift endr dc.b even endm ...
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 RunTime dc.
Entire Parameter If the special parameter \_ (backslash underscore) is encountered in a macro, it is expanded to the complete argument specified on the macro invocation statement. Examples All macro dc.b endm ... All \_ 1,2,3,4 will generate db 1,2,3,4 Control Characters The parameter \^x, where x denotes a control character, will generate the specified control character.
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. Syntax directive NARG ... SHIFT where NARG is a reserved, predefined symbol. See Also Extended Parameters Examples routes macro rept if dc.w else dc.w endif shift endr endm ...
MACROS Description The MACROS directive allows the entry of a single line of code as a macro, with no associated ENDM directive. The single line of code can be a control structure directive. Syntax Label 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 another assembler.
PUSHP, POPP Description These directives allow text to be pushed into, and then popped from, a string variable. Syntax PUSHP POPP string string Remarks 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.
PURGE Description The PURGE directive removes an expanded macro from the internal tables and releases 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 ...
TYPE Description TYPE is a function used to provide information about a symbol. It is frequently used with a macro to determine the nature of its parameters. The value is returned as a word; the meanings of the bit settings are given below.
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 and prepare subsets.
STRLEN Description A function which returns the length of the text specified in the brackets. Syntax STRLEN(string) See Also STRCMP Remarks The STRLEN function is available at any point in the operand. Examples Nummov macro rept move.1 endr endm ... Nummov strlen(\1) (a1)+, (a0)+ 12345 The number of characters in the string is used as the extent of the loop.
STRCMP Description A function which compares two text strings in the brackets, and returns true if they match, otherwise it returns false. Syntax STRCMP(string1,string2) See Also STRLEN Remarks When comparing two text strings, the STRCMP function starts numbering the characters in the target texts from one. Examples Vers equ ... if move.w else if move.w else if move.
INSTR Description This function searches a text string for a specified sub-string. If the string does not contain the sub-string, the result of zero is returned; if the sub-string is present, the result 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. Syntax See Also SUBSTR Examples Mess Note INSTR ([start,]string, sub-string) equs ... if move.w else move.
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. Syntax symbol See Also INSTR, EQUS Remarks When assigning a sub-string to a symbol, the SUBSTR directive starts numbering the characters in the source text from one.
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.
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.
The code above shows a typical use for Local Labels, as "place markers" within a self-contained sub-routine. The scope is defined by the non-local labels, Plot2 and Plot3; 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,d3 d3,d0 setplot set ...
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 defined elsewhere cannot be referenced within the current module. Syntax See Also MODULE ... ... MODEND LOCAL Remarks Examples • Modules can be nested.
LOCAL Description The LOCAL directive is used to declare a set of macro-specific labels. Syntax See Also LOCAL symbol,..,symbol MODULE Remarks Examples • The scope of symbols declared using the LOCAL directive is restricted to the host 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.
CHAPTER 8 Structuring the Program Normally, the organisation of the memory of the target machine does not match the layout of the source files. The Assemblers however, use Groups and Sections to create a structured target memory and relocatable program sections.
GROUP Description This directive declares a group with up to seven group attributes. Syntax GroupName 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.
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. Example Group1 group org($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.
SECTION Description This directive declares a logical code section. Syntax SECTION.size SectionName[,Group] SectionName SECTION.size [Attribute,..Attribute] The second format is a special case, designed to allow definition of a section with group attributes - see below for a description.
• 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.
g_short g_code g_bss firstbss group group group word section section section section section short1,g_short short2,g_short shortcode,g_short code,g_code bss,g_bss equ * bss PUSHS and POPS Description These directives allow the programmer to open a new, temporary section, then return to the original section. PUSHS saves the current section, POPS restores it. Syntax PUSHS POPS Examples plotcomp passdl move.w move.w bsr.s move.w move.w addq.w ...
SECT and OFFSET Description The SECT function returns the address of the section in which the symbol in the brackets is defined. The OFFSET function returns the offset value from the beginning of the section. Syntax SECT (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.
CHAPTER 9 Options, Listings and Errors This chapter completes the discussion of the Assemblers and their facilities.
OPT Description This directive allows Assembler options to be enabled or disabled in the application code. See ‘Assembler Options’ below for a full listing. Syntax See 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 • Examples Options may also be enabled or disabled by using the /O switch on the Assembler command line - see Command Line Syntax, chapter 2.
Assembler Options The following reference list shows the default settings for the various options and optimisations available during assembly. More detailed descriptions are given below.
Option Descriptions AE - Automatic Even When using the word and long word forms of DC, DCB, DS and RS, enabling this option 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 of numeric constants in Zilog or lntel format, i.e. followed by H, D or B to signify Hex, Decimal or Binary.
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.
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. Syntax PUSHO POPO See Also OPT Examples SetAlts SETALTS pusho opt ws+, c+ = dc.w height * time 256 * SetAlts popo LIST and NOLIST Description Syntax The NOLIST directive turns off listing generation; the LIST directive turns on the listing.
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 the first 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.
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.
XDEF, XREF and PUBLIC Description If several sub-programs are being linked, use XDEF, XREF and PUBLIC to refer to symbols in a sub-program which are defined in another sub-program. Syntax XDEF XREF.size symbol[,symbol] symbol[,symbol] PUBLIC PUBLIC on off Remarks Examples • In the sub-program where symbols are initially defined, the XDEF directive is used to declare them as externals.
GLOBAL Description Syntax 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 a label, it will be treated as an XDEF. If the symbol is never defined, it will be treated as an XREF. GLOBAL symbol[,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.
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 access files 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.
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.
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. Syntax pollhost is defined as a macro: #define pollhost() 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.
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.
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().
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.
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.
The PCclose Function Description This function closes an open file on the host.
The PCcreat Function Description This function creates a new file on the host.
Assembly Language Facilities The adapter firmware provides some useful functions which can be accessed from the SH2 cpus via TrapA calls. These functions allow user software to interact with the adapter downloader firmware and to change the configuration of the adapter firmware. Also, there are a few duplicate functions accessed via the 68000 LineA interface, that is, 68000 instructions with opcodes $Axxx.
Fileserver Functions The target adapter also contains software to provide fileserver functions. These are accessed 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.
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 Offset Seek Mode Returns: r0.
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 will revert to a symbolic disassembly, when no source level information is available.
Debugger Command Line Syntax DBUGSAT [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 - the symbol files will then be loaded in the order specified.
/r## Specify data screen rows in video bios. /R Use alternative mnemonics in register window. /sfile Override 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 the command line.
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 overridden with 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.
Activity Windows The Debugger display consists of one or more activity windows. The number of windows, 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 normally contains a display of the registers, the lower window shows the disassembly of the target program code. The Debugger can run up to 10 virtual screens; each screen has its own configuration file - see chapter 11.
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 or Entering 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 are substituted as appropriate.
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 is displayed in a different colour; the breakpoint count and expression details are shown at the end of the line. The Hex window displays memory in hexadecimal, either in byte, word or long word form.
The Watch and Variable windows allow variables, tables and code locations to be monitored 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.
You can step, trace, run to cursor and set breakpoints in the source code in much the same 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, may correspond to the execution of one or more instructions.
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.
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 of concurrent overlays are supported over multiple memory areas. A simple overlay is included with the Psy-Q software.
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 is given later in the chapter.
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.
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 - see chapter 11.
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 the same rules as the Assembler (see chapter 3), with the following exceptions: • • • • Prompts Assembly language expressions may contain processor registers.
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 li
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 partic
Hex Window Arrows PgUp/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 the top Switch display between byte, word and long word Change contents of current location to the result of an expression; entered in an input window Directly change contents of highlighted location Increment contents of highlighted location Decrement contents of highlighted location Go to address
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.
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 be accessed by pressing F10.
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.
The Link Software The adapter hardware contains software in ROM to enable it to communicate with the host PC. In addition, this ROM contains code to perform some functions which maybe useful in the development stages of a product.
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.
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; the lower window will then display this source code.
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 into another function. As you trace through the program, notice that the variable scope changes and that the Var window always displays the current local variables.
To View Global Variables Create another window and set its type to Watch; now press Alt-G to enter all your global variables in this window. You can also enter specific C or Assembler expressions (global and local) at the cursor position by pressing INSert. Entries can be deleted using DELete. In both the Var and Watch windows, you can de-reference pointers and arrays or open up structures, unions and enums by placing the cursor over the relevant entry and pressing ‘+’ on the numeric keypad.
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.
C H A P T E R 12 The PSYLINK Linker The Psy-Q Linker PSYLINK is a fully-featured linker which works with all processor types. It facilitates the splitting of complex programs into separate, manageable sub-programs which can be recombined by PSYLINK into a final, single application.
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: Syntax PSYLINK [switches] objectfile(s),output,symbolfile,mapfile,libraries If a parameter is omitted, the separating comma must still appear unless it is the last parameter of the line.
/p20 and /p21 Output pure binary file in SNES mode 20 or 21. /r format Create operating specific output (am = Amiga). /u number Specify 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.
Linker Command Files Command files contain instructions for the Linker, about source files and how to organise them.
Examples comdata code bssdata include include include "inp.obj" "sort.obj " "out.obj" org regs 1024 pc=progstart group group group word section section datal,comdata data2,comdata section section codel,code code2,code section section tables,bssdata buffers,bssdata bss GLOBAL Description Syntax See Also The GLOBAL directive allows a symbol to be defined which will be treated as either an XDEF or an XREF.
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. Syntax Remarks Examples XDEF XREF symbol[,symbol] symbol[,symbol] PUBLIC PUBLIC on off • In the sub-program where symbols are initially defined, the XDEF directive is used to declare them as externals.
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.
PSYLIB Command Line Description The Library program, PSYLIB.EXE, adds to, deletes from, lists and updates libraries of object modules. Syntax PSYLIB [switches] library module...module where switches are preceded by a forward slash ( / ), and separated by commas.
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 produced by the GNU C Compiler.
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. Syntax CCSH [options / filename[,filename...]] The command line consists of a sequence of control options and source file names.
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 Example CCSH -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.
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 .
C H A P T E R 15 The PSYMAKE Utility PSYMAKE is a make utility for MS-DOS which automates the building and rebuilding of computer programs. It is general purpose and not limited to use with the Psy-Q 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 and the 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. Syntax PSYMAKE [switches] [target file] or PSYMAKE @makefile.
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 ...
Examples main.cpe: main.68K inc1.h inc2.h ASM68K main,main This tells PSYMAKE that main.cpe depends on the files main.68K, inc1.h and inc2.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.
Executing commands: Once the commands to execute have been determined, PSYMAKE will search for and 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.
Macros A macro is a symbolic name which is equated to a piece of text. A reference to that name can then be made and will be expanded to the assigned text. Macros take the form: 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 of usage.
Directives: The following directives are available: !if expression !elseif expression !else !endif These directives allow conditional processing of the text between the if, elseif, else and 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 Dyadics e.g. 1 10 1234 e.g.
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 '\' the last character on the line, with no following spaces/tabs: main.exe : main.s i1.h i2.h \ i3.h i4.
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.
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 by each Unit that you reference. Alternatively, the same colour can be allocated to all Views.
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.
Installing The Debugger A Set-up program is used to install the Debugger; this is distributed via either of the following 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.
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).
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.
Installing A Full Release A Full Release File contains an archive of several Files and a Set-up program that can be 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.
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 full installations 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.
Configuring Your Dex Boards If you are installing a Full Release for the Sony PlayStation (DEX only), you must specify 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. .
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 and selecting as appropriate. 2. Click . The installation is now complete. IMPORTANT: Port Address and IRQ values must be correct for the Debugger to work.
Testing The Installation Once the Debugger has been installed, you should now run PsyServe.exe in order to test 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.
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.
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 through Explorer in Windows ‘95.
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.
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 the system 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.
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 the server until you close the Debugger; however, the File Server can be run without the Debugger .
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 or multi-Unit system, automatically connects to the relevant Unit(s). The Unit toolbar appears at the bottom of the Debugger window directly above the Status line. The first icon in the toolbar has a pictogram of the Target known as the Unit button.
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 respect of the Active View. Note: The Psy-Q File server is automatically launched when the Psy-Q Debugger is started. The Server window displays any output from the Target while it is running.
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.
Selecting Files For Your Project The Psy-Q Debugger uses files that are output from the build process. Three types of file 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.
Note: As file type .CPE has been registered with the Windows ‘95 shell, you can run 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 from the menu. Note: When you add Binary and Symbol Files to a Project they are not loaded until the Project is saved and re-opened.
Specifying CPE File Properties When you select a CPE File to include in your Project, a dialogue box requests that you 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 the code after downloading the file.
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 . .
Specifying Binary File Properties When you select a Binary File to include in your Project, you must complete the following 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.
Saving Your Project Once 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 .
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 .
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 icon on the toolbar. found Note: As File type .
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.
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 means of activating commands and setting properties.
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
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 or different types. Only one is Active at any time; it will be displayed in a different colour scheme to the others.
Creating A Psy-Q View Within a Psy-Q Project you can create as many Views as required; in turn, each View 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.
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.
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 command on the View menu. 4 This 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 .
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.
5. Select the required colour(s). 6. The selected colour scheme will be displayed for all visible Views. 7. Select to retain the revised colours or revert to the original scheme. Unit colours can also be amended by clicking on the Set Colour icon toolbar.
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.
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.
Changing Fonts In Panes 4 If required, the Set Font command can be used to change the display of text within a Pane, 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 the original one. IMPORTANT: You will only be able to use non proportional fonts, e.g.
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 the screen. To see this additional information drag the thumb within the scroll bar or click on the arrows at either end of the scroll bar.
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.
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.
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 the options listed above. You can overtype the hexadecimal or ASCII displays to alter the content of the memory. A change to the hexadecimal display will be reflected in the ASCII display and visa versa.
Registers Pane The Registers Pane shows the registers of the central processing Unit. These can be overtyped 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.
Disassembly Pane The 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 the third 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, the relevant label name and value will be displayed on the Status line.
These options can also be activated by: • Using the appropriate Hot Keys • Clicking on these icons 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.
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.
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 the Pane and ‘toggling’ between Hexadecimal/Decimal (on the displayed menu) as required.
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.
Watch Pane The Watch Pane is used to evaluate and browse C type expressions.
• 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 the Pane and ‘toggling’ between Hexadecimal/Decimal (on the displayed menu) as required. A tick will appear alongside Hexadecimal when this mode is selected.
C Type Expressions In Watch Pane The following ‘C’ type expressions, shown in order of precedence, may be used to evaluate 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 or Note: As in C, parenthesis can be used to override precedence.
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 to the 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 .
Amended Structures After Pointer Assigned New Variable IMPORTANT: The expression that you are assigning and the new value, must have 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.
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 be closed. 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.
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 to display expressions which have been used previously. Add Watch Dialogue Box 5.
Additional Features When Entering Expressions Simple Name Completion 4 With this facility, the program will attempt to complete the symbol to the right of the specified 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.
Advanced Symbol Matching 4 In addition to basic name completion which always completes the symbol at the end of the specified expression, extended name completion can be used to complete a symbol anywhere in the expression, as follows: 1. Enter a partial expression. 2.
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 a specific selection or click to highlight all the matched symbols.
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.
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 icon on 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.
Debugging Your Program The Psy-Q Debugger helps you to detect, diagnose and correct errors in your programs. This is achieved via facilities which enable you to step and trace through your 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.
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 it will be before exceptions can be spotted. However, it is possible to force an update by 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.
Editing Breakpoints The Breakpoints option on the Unit menu can be used to enable or disable breakpoints 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 the label (if one exists). Enabled breakpoints will have a tick beside them. 4 To edit breakpoints: 1.
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 can be 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.
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 the subroutine 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.
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 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 performed.
Running To The Current Cursor Position The Run to Cursor command can be used during debugging within the Source and Disassembly 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.
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.
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.
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 the value at the current caret position.
Moving To A Known Address Or Label 4 The Goto command is available on the Source, Disassembly and Memory Pane menus. It is used to put the caret and PC at a known address, label name, register name 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.
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.
Expression Evaluation Features Register Names Register names can be specified in any dialogue box where expressions can be entered. 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 to explicitly tell the evaluator that it is looking at a register.
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 the evaluator that it is looking at a label. Note: Labels have a C type of ‘int’. Functions If you include a function name in an expression, its value will be the same as its address.
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 a listing of these values. At this point you can enter a new expression to the dialogue box or select one from the 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 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 is active. 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.
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.
Closing The Debugger And Saving Your Changes The Exit option on the Project menu saves the current Project at the latest state and stops 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 system menu shown in the top right corner of the Debugger window.
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 character is 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
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
-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 zero End of file reached without completion of %s construct E.g.
Error writing list file DOS write returned an error status or disk full Error writing object file DOS write call returned an error or disk is full Error writing temporary file Disk write error, probably disk full Errors 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 < > <...
-5 Expecting options after /O On Command line Expecting quoted string as operand Expression 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.
Illegal character '%c' (%d) in input Strange (e.g.
-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 ...
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
-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 another Attempt to equate to expression, etc.
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.
-11 Section 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 c
Syntax error in expression Timed out sending data to target Target did not respond Too many characters in character constant Character 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 cal
-13 Unexpected end of line in macro parameter Unexpected end of line in list parameter In { ...
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
-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 full Errors 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 (%
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.
-17 Symbol '%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.
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 matc
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 ......................................
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 .........................................
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 ..................................
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 .................
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..................