This DOC file commences a very extensive coverage (350K+) on the
excellent package Devpac V2. The manual is divided into many
parts, all of which may be found on this Sewer Doc Disk Number 8.
Special thanks once again to the Animal House who typed the entire
manual single-handedly. Quite a good effort and one which will be
beneficial to many ST programmers out there. This file (and every
one of these files) was edited by Sewer Rat.
CHAPTER 1
INTRODUCTION
ALWAYS MAKE A BACK-UP
Before using DevpacST you should make a back-up copy of the
original disk and put the original away in a safe place. It is not
copy-protected to allow easy back-up and to avoid inconvenience.
This disk may be backed up using the Desktop or any back-up
utility.
Before hiding away your master disk make a note of the serial
number (if you have an original??? Then you would not be reading
this.!!)
REGISTRATION CARD
Enclosed with the manual is a registration card (sorry not
for you, and you get a free 68000 Pocket Guide [ œ2.95 from any
good bookshop. ] )
THE README FILE
As with all Hisoft products DevpacST is continually being
improved and the latest details cannot be included in this manual
may be found in the README.S file on the disk. This file should be
read at this point, by double clicking on its icon from the
Desktop and the clicking on the Show button. You can direct it to
the printer by clicking on the Print button.
THE DEVELOPMENT CYCLE
The purpose of DevpacST is to allow you to enter assembly language
programs, assemble them to machine-code and debug them if ( or
should that be 'when' {oh! sarcasm!} ) they don't work. Depending
on your application, you may also be using a linker to join
together seperate modules, possibly with the output from a high
level language compiler. Of course the faster the development
cycle, the faster you can get your programs up and running and
DevpacST was designed to be as fast and powerful as possible.
The link stage is optional, as is the Compile stage.
DEVPAC DISK CONTENTS
PROGRAMS
GENST2.PRG GEM screen editor and assembler
MONST2.PRG the GEM program debugger
MONST2.TOS the TOS program debugger
GENST2.TTP stand-alone version of assembler
AMONST2.PRG auto-resident debugger
CHECKST.PRG diagnostic program
LINKST.TTP GST-format linker
NOTRACE.PRG trace exception dis-abler
MENU2ASM.TTP menu compiler
TEXT FILES
README.S latest details about DevpacST
DEMO.S very simple TOS program used in tutorial
GEMTEST.S simple GEM demo program
DESKACC.S example desk accessory
GEMMACRO.S macros for AES/VDI interface
AESLIB.S AES library source
VDILIB.S VDI library source
NOTRACE.S source to NOTRACE.PRG
MENUTEST.S example GEM program using menu
MENUTEST.MDF sample menu definition file
MAKEGEM.S creates GEMLIB
GEMLIB.LNK control for GEMLIB
BINARY FILES
GEMLIB.BIN AES & VDI library
FOLDERS
OLDGEM update GEM examples from GenST 1
HOW TO USE THE MANUAL
This manual makes no attempt to teach 68000 assembly language
programming or to detail the instruction set. For the former, the
bibliography lists suitable books, while for the latter the
supplied Pocket Guide is very useful. The Appendices give an
overview of the technical aspects of the Atari ST but they are not
intended as a complete technical description of the machine.
This manual is set out in five chapters, this introduction, a
chapter on the screen editor, a chapter on the macro assembler, a
chapter on the debugger, then a chapter on the linker. In addition
there are eight Appendices which detail various additional
information. We suggest you use the manual in a way that depends
on what type of user you are;
DEVPACST VERSION 1 USERS
Turn to Appendix H and read the section describing the new
features, then read the Reference section of Chapter 4 if you
intend using MonST, as it has changed considerably. The other
section you may read is that on File Formats in Chapter 3 if you
are interested in generating linkable code.
BEGINNERS
If you are a newcomer to assembly language then we recommend
that you read one of the books in the Bibliography alongside this
manual.
At the end of this chapter there is a simple tutorial which
you should follow to familiarise yourself with the use of the main
parts of the program suite.
Chapter 2 details the editor and is well worth reading,
though much of Chapter 3, detailing the assembler, is liable to
mean nothing until you become more experienced. The Overview
section of Chapter 4, the debugger, is strongly recommended,
though Chapter 5 and the Appendices can be left for a while.
Looking at the supplied source code may be helpful, but the GEM
programs may be hard going as they were not written with the
beginner in mind.
EXPERIENCED USER
If you are experienced in the use of 68000 assembly language
but have not used DevpacST before then here is a very quick way of
assembling a source file:
Load GENST2.PRG, Press Alt-L and select your file which will
load into the editor. Press Alt-A and select the options which you
require - if generating executable code then click on the Memory
button for additional speed. Pressing RETURN will start the
assembler, which may be paused by pressing Ctrl-S, Ctrl-Q resumes.
Any assembly errors will be remembered and on return to the editor
you will be placed on the first one. Subsequent errors may be
found by pressing Alt-J.
To run your successfully-assembled program (if assembled to
memory ) press Alt-X. If assembled to disk press Alt-O then select
the program.
As a quick introduction to the debugger the following
tutorial is recommended. If you have any problems please read the
relevant section of the manual before contacting us for technical
support.
A VERY QUICK TUTORIAL
This is a quick tutorial intended to let you see how quick
and easy it is to edit, assemble and debug programs with DevpacST.
In this tutorial we are going to assemble and run a simple
program, which contains two errors, and debug it. The program
itself is intended to print a message and wait for a key to be
pressed before quitting.
To start with load GENST2.PRG from your back-up copy (you
have made a backup, haven't you?) which must also contain the
files MONST2.PRG and DEMO.S, at minimum, by double clicking on its
icon. After a short delay the screen will show an empty window; to
load the file you should move the mouse over the FILE menu and
click on LOAD. The standard GEM file selector will then appear and
the file we want is called DEMO.S. You may either double-click on
the name or type it in and press RETURN to load the file.
When the file has loaded the window will show the top lines
of the file. If you want to have a quick look at the program you
may click on the scroll bar or use the cursor keys.
With most shorter programs it is best to have a trial
assembly that doesn't produce a listing or binary file to check
the syntax of the source and show up any typing errors and so on.
Move the mouse to the Program menu and click on Assemble.
A dialogue box will appear, which should be left alone except
the button near the bottom, labelled NONE, should be clicked on.
Click on the Assemble button or press RETURN and the assembly will
begin.
The assembler will report an error, instruction not
recognised, and pressing any key will return you to the editor. he
cursor will be placed on the incorrect line and the error message
displayed in the status line.
The program line should be changed from MOV.W to MOVE.W so do
this, then click on Assemble form the Program menu again. This
time click on the Memory button, this means the program will be
assembled into memory, instead of onto disk. This is very much
faster and allows you to try things out immediately, which is
exactly what we want. Clicking on the Assemble button will again
assemble it, and after you press a key to return to the editor
it's ready to run.
The assembly worked this time, so click on RUN from the
Program menu, and what happens? Not a lot it would seem, except
that a couple of bombs appear briefly on the screen - oh, there's
a bug.
The tool for finding bugs is a debugger, so click on Debug
from the Program menu. The debugger is described more fully later
on, but for now we just want to run the program from the debugger
to 'catch' the bombs and find out what causes them, so press Ctrl-
R.
After a brief delay the message Bus Error will appear in the
bottom window, with the disassembly window showing the current
instruction
MOVE.W 1,-(A7)
This will cause a bus error because location 1 is in
protected memory which cannot be accessed in user mode - there
should be a hash sign before the 1 to put the immediate value 1 on
the stack. To return to the editor press Ctrl-C, so we can fix
this bug in the source code.
Press Alt-T, to go to the top of the file, then click on Find
from the Search menu. We are going to find the errant instruction
so enter
MOVE.W
then press Return to start the search. The first occurrence
has a hash sign, so press Alt-N to find the next, which is the
line
MOVE.W C_CONIN,-(A7)
Ahah! - this is the one, so add a hash to change it to
MOVE.W #C_CONIN,-(A7)
then assemble it again. If you click on RUN from the Program
menu you should see the message, and pressing any key will return
you to the editor.
However, did you notice how messy the screen was - the
desktop pattern looked very untidy and you possibly got mouse
'droppings' left on the screen. This was because DEMO is a TOS
program running with a GEM screen - to change this, click on RUN
WITH GEM from the Program menu - the check mark next to it should
disappear. If you select RUN again you see the display is a lot
neater, isn't it? If you run a GEM program you must ensure the
check mark is there beforehand, otherwise nasty things can happen.
Although the program now works we shall use MonST, the
debugger, to trace through the program, step by step. To do this
click on Debug from the Program menu, and the debugger will appear
with the message Breakpoint, showing your program.
There are various windows, the top one displaying the machine
registers, the second a disassembly of the program, the third some
other memory, and the bottom window displaying various messages.
If you look at window 2, the disassembly window, you will see
the current instruction, which in our case is
MOVE.L #STRING,-(A7)
As the debug was specified in the source code any symbols
will appear in the debugger.
Let's check the area around string Press Alt-3 and you should
see the window 3's title inverted. Next press Alt-A and a dialogue
box will appear, asking WINDOW START ADDRESS? - to this enter
string
(it must be in lower-case) and press RETURN. This will
re-display window 3 at the address, showing the message in both
hex and ASCII.
To execute this MOVE instruction press Ctrl-Z. This will
execute the instruction then the screen will be updated to reflect
the new values of the program counter and register A7. If you
press Ctrl-Z again the MOVE.W instruction will be executed. If you
look at the hex display next to A7 you should see a word of 9,
which is what you would expect after that instruction.
The next instruction is TRAP #1 to call GEMDOS to print a
string, but hang on - would we notice a string printed in the
middle of the MonST display? Never fear. MonST has its own screen
to avoid interference with your program's, to see this press the
V key, which will show a blank screen, ready for your program.
Pressing any other key will return you to MonST.
To execute this call press Ctrl-z, which will have printed
the string. To prove it press V again, then any key to return to
MonST.
Press Ctrl-Z twice more until you reach the next Trap. This
one waits for a key press so hit Ctrl-z and the program displays
will automatically appear, waiting for a key. When you're ready,
press the q key. You will return to MonST and if you look at the
register window the low 8bits of register D0 should be $71, the
ASCII code for q, and next to that it will be shown as q (unless
in low-res.)
The final Trap quits the program. So to let it run its course
press Ctrl-R, you will then return to the editor as the program
has finished.
Note the way we have used the Ctrl-X to mean hold the Ctrl
key and press the key X, whilst Return or RETURN means press
return.
END OF CHAPTER 1
ÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿÿ
Back to HiSoft DevpacST Version 2 - Manual