SNASM68K 68000 Cross Assembler System Manual

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 95

Download
Open PDF In Browser	View PDF

9',

CROSS

PRODUCTS

LI iI ITE

SNASM6SK
8/8/91

CopyrlEht

cro$

Products Ltd 1989-91

CROSS PAOOUCIS UMI1ED

LEE06

lBMo is a regisLcd lEd.malJ( ol lnl.mni.n.l Susii.s! M-hin.s Clrp..alion.
MS DOSo b a Ggisr.Gd rEd.ma* oI Mimdr c.DoEtio..
Bi6l is a lrad€ma* ol UideM.E lnc.

Introduction
Th€ Cross Products 68000 cross assembler syslem is a high performance
68000 assembly language development syslem runninq on MS-DOS and
PC-DOS computels.

Component! ol the Svstem
Assembler
SNASM6SK converls progEms winen in 68000 assembly language inlo
€ilh€r absolute code which can be senl dir€ctly to the larget machine, CPE
(Cross Producls Executabl€) files or object moctules suilabte Jor tinking.

Debugger
SNBUO6SK allows 68000 programs running on the larg€t machine io be
remotely debugged from lh€ dgvelopment Pc. lt has acc€ss to the symbots
used in lhe source cod€ allowing lull symbolic debugging.

Llnkar
SNLINK combines objecl modules created by SNASM68X, evatuales any
erpressions which could noi b€ resolved ea ier lt can gererais output i4 a
large vaisly ol formais including direct transmission down ihe SCS| tink.

Llbrarlan
An object module library is a coll€crion ol objecl modules thai reside in one
file. SNLIB is a ulility program ihai builds and marniarns objeci modute
libraries ior fte linker.

Hardwars Link
To speed program development, lhe development PC is connecled to the
larget machine using a SCSI (smallcompuler sysiems jnlerfacei bus. The
assembler, linkerand debugger use this inlerlac€ lo send code to the targel
machine_

Environment
A program can be assemblsd and debugged without exiting lhe Biel editor
wnich grearly speeds lhe EdivAssenbte/D€bug cycte.

wavs ol u3lng SNASiI
SNASM is an extremely ilexible sysiem ihai can be used in many dittereni
ways. A few ol these approachss are giv€n here lo give an overview of the
product.

Absolde 6ds wirhod sections- no linkind
The code is be ass€mbl€d al an absolule address, specilied wilh one or
more OFG directiv€s, and then eitherserf dkectty to thsiarget machine,
placed inlo a CPE lile oroutput in pure binary fomat.

Abelute 6de with..ctions n6 tinking
The ORG address of lh€ program musl be specitied belore any seclions are
opeisd. lf groups arc not used BSS type sectio4s a€ not av'aitabt€, and
sedions areplacsd in memory in the oder they occur. I groups ar€ used.
lh€y define lhe ordedng ot seclions in memory, and a ow-BSS type and

absolule word addressable sections

Lillirq
Each source fil€ is assembted usinq lhe /L switci io oroduce an obiect
module. Source modul€s cannot contain ORG directives. Th€ modites are
linksd to produce any, ot ths output types supported by ttre assemUei pruJ
some machine specilic relocatabte tomats.

There is no ne€d to use sectiors orgroups when Droduci.q tinkabte outout
Dtn many more tunciions ars avaitabb it ihey are ised. -

Hardwere R.dutremants
SNASMoSK requirss ihe tottowing minimum contigurarion

IBM-PC or compaiibte compuier
I or 16 bi! stor
- 256K ol memoru

. One lree

. MS.DOS 2.0 oilater
. A hard disk

we strongly recominend :.

8MH2 IBM PC/AT or taster

OOS 3.0 or above

. A fai haKl disk
. 640K ol main memory and a

l tvtb RAM disk

Hardware lnstallation
conligurho th. PC card

01234567

t-rt

IITTIM

t__l!
IITTTTTTII

The card can reside at one ot several addresses in the PC's pon map. The
links labelled 0-7 are used to sel the address as lollows :'

ult

Address

300-307

308-30F

2
3
4
5

310-317
318,31F
380,387
388,38F

390-397
3S8-39F

The cad js supplied wilh llnk 6 connecled so it is al address 390 hex.
The SCSI bus suppo(s up to eight devices, each ol which musl have a
ditferonl SCSI device number.
The links labell€d Al ar€ used to s6t th€ ScSldevice numberofth€
andlhe DMA and lntemJpi channels the card willuse.

cad

l]!t
B

c
D
E
H
I

Funcion

tFo5
tBoT
DROl

DACKl
DRO3

DACK3
Bii 2
Bil 1
Bir 0

SCSI lD of card

lnlerrupis are not cLrnonlly us€d so links A and Bshould be lefi
unconnsctsd. The cad ls supplied wilh linl6 C and D connecied so the card
uses DMA chann€l I . l, you wanl to us6 DMA channel 3 move both jumpers
to E end F, or il you don't wanl to use hardware DMA at all remove both
linl(s.

The cad is supplied wilh links G and H .onnscl€d giving the card a SCSI
device number of 6. This will only n€ed cnanging il it clashss
another
dsvics on lhe SCSI bus.

Fltilno lhe Card

1)
2i
3)
4)
5)
6)
7)

Vedly lhal no power is being supplied lo the compuler
Rsrnov€ the compute/s case,
Check thal lhe address and DMA senings olihe card will nol cause it
to clash wilh any olher cards in lhe computer.
Local€ afi smply slol and rsmove the backplate cover,
lnslallthe SCS|card by lirmly butcareiully prcssing lt down into ihe

slol.
Sscllr€ the card wilh lhe screw you removed from lhs
backplale.
Replece the compute/s case.

ll you changed the seilings oi lhe card make surc you know lhe addr€ss and
DMA channel you selected es you witl need this inlomation to comptete
insrallation.

Software lnstallatlon
Itlote: The SNASM inslall program is d€sign€d 10 customiss lhe Briel texl
ediio/s envircnm€ntlo €nable SNASM to wofi lrcm $ilhin Aiel. ll you
int€nd to work in lhis manner you should install Bie, before you inslall
SNASM,
Th€ install proghm provid€d on your SNASM disl bution disk will
automatically inslall the whole SNASM system . (Allquefies rrom lhe
program asking lorossr inpul ar€ t€minated '[y/nr. Hitting the ESoAPE k€y
at rhis prompr willabod immedialely.)
lnslall will ask ior the lollowing inlomalion:
1, lnslall ,irst ch€cl,s to see il il can fnd lhe defaull direclory lo copy lhe
SNASM executable liles io. This is o:\SNASM. lnstallwillgive the userthe
oplion to speci, any olher djr€clory.
2, The inslall program will now ask Jor th€ syst€m bool driv€ and check that it
can rincl an asloexec.bat lile there. ll willpersist in asking ior this in,ormalion
unlil it can find an auloexec-bal file-

3. Next it r€quir€slhe name olthe disk drivs in which the SNASM
distdbution disk is reslding.
The lnstallprcgram will now ask ilthe user requires 10 backlp old riles. lf
lhe answer is yes any fles in the targel direclory ollhe
on€ aboul lo be coplsd onlo it willbe saved (in thal dircctory)wilh lheir lile
€xtension changed lo'.old'. This oplion takes eflectlhroughoul lhe install
process and il il is not selecled lhe copy proc€ss willstop lor every iile lo ask
"lilename exists Ov€Iwrile/Backup/overwiie AlliO/B/Al'
,1.

lhese oplions have the lollowing eflects:
O: overwrite this lile repeat query ior nexl lile.
B:save old lile wilh '.old' extension rcpeat query.
A:oveMnte allliles ol same nameswithoui asking
(hroughoullhe whole of rhe lnsrallprccess).
5. Should lnslall delect lhal th€ dkectory holding rhe executable liles is nol
on the search peth ollhe use,s machin€ it will ask il il should add ii.

6.lnsilatlwill nexl looktorthe BPATH and BHELP environmental vaiables lo
delermifle wherc to copy the Biel mados and menu files lo. li willdisplay a
message asking ilthis isdssi€ble: as Bdei expects to lind lhem inthis
localion it is aclvisable 10 do so.
7. Berore ediling the auloexec.bal ile, lnslall will ask lhe useril a backup
should bs created(as autoexec.old). li willthen proceed lo sel several llags
within lhs Bri€f environmenlal variables and add ihe clmmand to install ihe
SCSILINK software on boolup. lnslall will always ask belore editing any

portion ol lho autoexec.bat lile.
8, ll lnsiall lsaves a message on exil saying lhat ihe otd SNAST!,| macro stadup code is presenl in lle us€rs slartup.cb macro lile lhis is due to a changs
in the manner in which lh6 SNASM Bdel macros ar6 initiated on starring an
ediling session. Th€ llne 1oad_macro('snasm")' should bs remov€d {rom the
fi16 startup.cb (r€siding in the direclory pointed lo by the BPATH
envircnmenlal variabls - \bieflmacros by d€rauh ) andihe lite re-compil€d,
Ths communicaiions belrxeen the PC and the target machine are handted
by a program called SCSILINK which mu$ be instatted botore any orth€
other programs can be run. lnstallwilladd a tinelo do thjsyour
auloexec-bal llls, The inrormation belowwillb€ ot us€ i, you wish to instattit
at a nondelault addrcss.
UsaE€:

SCSILINK addr€ssl,D1[,]?]
lhe delault is
SCSILINK 390,D1
Th€ address is whalever was s€l using links 0-7 on the SNASM PC card
and lhe number alt€r the D should be rhe DMA chann€lyou are using.

ll no DMAchaflnelis specilied hardware DMA wilt nol be used and unless
you have a fasl compul€rdata lransmission spesd wjllbe reduced.
The lparameleris usedlo giv€ the card a diflerent SCS|dsvice number
wilhoul opening th€ compuler and changing lhe linls, howeverthis is nol
SCS|L|NKchecks for th€ exisience ol lhe PC cad as it instatts irsett. and
repons any erors at lhis lime.
g.You should r€-s€t your computer when lnstallllnishes io benefil from lh€

new SNASM environment.

Running the Assembler
ll you inlend uslng SNASMoSK as a sland alone assembler instead o,
tunning itlrom within BBIEF you must be familiarwith lhe command lin€

Command

lln. Svnt r

SNASM68k /switches sourceiile,objectfi le,symbollile,lisllile,t€mpf ile

Swllchas

/b number

Set si2e of inlernal bulf€rs (Kbytes 2-64)
enable lisling of lines lhal are in lailed

/d
/6 symb=value
/g

condilional struciures
Debug mode - do no! run
Equale symbollo value
Wdte non{lobal symbols to linker objecl
tit€

path
/k
,l
/m
/o opls
,!
,v
,2
4

Display inlormation window dudng
assembly
specily include lile search palh
Allow uss of il€q sic,
produc€ linkable oulpul iile
B(pand macros in lislings
Set assembl€r options/optimisations
Produce pur€ binary insl€ad ot.CPE
wile equales lo symbol/linker ,ile
include tin€ number inro. in linkerlile

Se€ the section on Options lalerin this manuallora iulllist olthe assembler
options and oplimisalions-

Sourcetlle

Oblectflto
Symbolllle

Llsttllo

Temptlle

File containing 68000 sourc€ to bs assembted_ tf this is
omitl€d SNASM6SK willpdni rhe above inlonnation in a help
message.ll no exlension is givsn Jorlhe source lile it is
assumed lo be ,68K.
Flle lo reclive objecl cod€ ouiput. lllhls is omitted no object
code will be generaled. ll you want the object code lo be s€fi
lo a largel computer use T?: as lhe objec ile wh€re ? is the
SCSId€vic€ number ol the laEol.
File to rcc€ive symbollable inrormalion iordebugger.
Fil6 to receive any lisling oulpul.
File 1o be used lor any data lhat will not lit in memorywhitst
assembling. lllhis is omitled the lile willbe called
SNASM.TMP ora unique nam€ il your DOS veEion is high

enough.
e.gSNASM68K /o ow+,an+,e+ t€sl,68k,17:,|€si.sym,,e:

Assembles lesl.68k wilh warnings reporled, allernate numerics enabled and
eror line printing suppressed. Obj€cl cod€ will be sent lo the targel with
SCSI device number 7. No lisling will be generated, symbols wiil be writien

to lesl.sym and the temporary rile will be gsnsraled on disk E:.
Each tim€ SNASMGSK is run it check for an optional €nvironment vaiable
called SNASM6SK which contains delaull swilchss, oplions and filespecs.

egs€l snasm6Sk=/c-,17:,,,e:\tmp
Disables case s6nsilivily, makes delault output go to larget 7 and sets lhe
dolaull lemporary lile 1o be €ltmp. Anylhing set in the environmenl variable
can be over-iddon on lhe command lins,

Assembly can be slopp€d by pressing Controlc, or il you are ass€mbling
lrom within Bdeland you arc using the inlomation window, by pressing Esc.
l, the rilsl it€m on the cofimend line starts wilh an at sign (@) it is taken to be
ihe name ol a fil€ conlaining lhe assemblsr options,

eg-

SNASMS8K @snasm.cmd
wh€re snasm.cnd contains :.
test.68k,
t7t,
iest-tst

SNASM6SK /j cl\include /e z=1 tes1.68k,t7:,,t€sl.lst

Bunnlnd lrom wirhln BriEI
1. Th€ Brie, edilor macrcs thal interlace SNASM to lh€ editor have b€en
revised to aork wjth lh6 Crcss Producls make utilily SnMake and h€ncs
provide a beller working environmont lorlhe SNASM user. ln praclical tems
ihis m€ans that wjthin Bde, the dialogu6-box interface to SNASM has been
complolely sc6pped and now relies on using SnMakE and ils associaied
'project liles'lortho selting up and ex€culing of exlernal commands. Whilsl
Ihis involves slightly morc
in iriiial setling-up il oflers longertern iiF€
sevings and much more llexibilily,

Using SnMake is delalled ln lhe sed,on 'Using SnMake' and will not be
gon€ inio in greai delail here. Th€ SNASM €nvironment now relies on the
creation ol a'projed file'foreach prcjscl the user is undenaking. Thes€ ar€
tiles dilised by SnMake whlch hold inlorfiation aboul ihe tite dependencios
lor lhat projecl and the rules by which the output lile(s) can be crcaled
according to those dep€ndencies. (5o6 Using SnMake' ). This means that
commancls and thear optjons arg put into the p,oject lfle as they would be
enl€r€d lrom the cofimand lin€, instead ot being set up in the dialogue-box

The Snasm main m€nu ls lnvok€d by pressing All-Fg. The menu optionsthat
ale available are discuss€d in sequence below. Navigation lhrough lhe
rnenus is dooe using lh€ up and clown arrow ksys, ssleci items using the

rsluh

key, escaD€ willexil allmenus.

liake.

Keyboard€quivalentAlt-Flo-

Thls opllon invokes SnMake on the cufienlly select€d proj€cl ril€.

S6l6ci Prol.ct

File.

Keyboard equivalent Cli-Fg.

When lhis is seleclad il brings up awindow showing allth€ lil€s
wilh a '.prj' €xt€nsion in th€ cunenl direciory, il one is cuirently
s€lecled il wil be highlighled. These are rho poject flss. The
fiIst llne olthe projecl ril€s is displayed in lhis window as an
aid tolhe users memory il multiple proiect lilss are presenl in
lh€ currenl direclory, See lhe sub.m€nu item 'Show comm€nt
lines'lor more informalion on putting such comments inlo prcject
files. Sel€cling ong of lhes6 libnames willb ng up a sub-menu

otfering lour options.

1. S€l6ct this file. Selecting this optlon make ths highlighted
project lile 'cuffenl', l.e- invold g th€ mak€ option will stari
snMak€ wiih th€ highlighted proj€ct lil€.

.nd Make. Mak6 th€ Hghlighled projeci lile cLrffent and
invoksthe make utility at lhe sam€ tim€.
2. Select

3. Show comment lln6s, This displays allthe texr in the project
file from lh€ top ollhe lile to the [SnMake] tabet. This is a
rcquired label in a projoct fil€ and SnMake does not begin to gars€
lh€ fl6 rorinpul unlilit encounlers this label. Thus any t€xt
can be placed belor€ this labsl withou! causing an enor.
.1.

Edn thts flte. Edit lhe hightighied project tite.

Nole: only sub"msnu options 1 and 2

cur€nl proiect lile.

O.bug.

alerlh6 setting ollhe

KeyboardequivalentCti-Flo.

This option €nt€lslhe debugger sp€dfied in th€ curent project
lile.(See'Using SnMake'for more iniomation on sening the
debugger).

Set Dsbug

Hode.

No keyboad squivalenl.

Selecting this oplion brings up a sub-menu with onty two options:
On and Ofl, one ol which will bs hignlighted. These oplions
controllhe setling ollhe special macro '$l' in the proiecl lile.
This macro €xpands 10 lhe setlings ol lhe debug and inio swirches
on lhe Snasm command tine. lnio mode is always on when SnMake

is invoked korn within Bi€f, making Snasm and Snlink bring up
slatLrs windows allowing the user 10 monilor their progress.

Debug mode can be sel lrom this menu oplion, determining

whelherths progam being Inade, (assuming il is being

downloaded lo a target machhe) is run immedialely (debug mode
Oil) or waiis wiih lhe program counter s€l to th€ valu6 sp€cifi€d
by lhe user with the 'regs dircclive (d€bug mod€ - On). ll must be
slress€d that thjs conlrol only slsms lrom lhe corect use ot lhe
special macro $l'in the ploiect iile. (See'Using SnMake).

Eveluete.

Keyboard equivalenlCtd-E.

This option invok€s lhe expression evaluaror sp€cilied ln the
curent project lile.(See'using SnMake'lor more inlormalion on
s€tting lhe expr€ssion evalualor), ll any t€rl jn the curentwindow is
highlightedlhis tunction willanefipl to pass it to the
expression evalualor, if not it will prcmpl ,or inpui on the Biel
status line.

Jump to

label.

Koyboard equivalent Cid-G.

This oplion examines the currenl cursor poslllon and d€lemines
it it is on a valid label(SNASM 68000 assembly language syntar).
llso itjump6 to lhal label, iJ nol il pmmpls lor a labelname to

Undo lasl labet. Keyboard equivalent

This oplion undoes the offscrs ol 'Jump ro label'.

Sav€

all

bull6rs.

Keyboard equival€nt All-S.

This option saves all butlers orrrenlly being edil6d.

Errot

wlndou.

K€yboard equivalent Cld-Q.

This option opens an error window lo display the cunent conlenls
ollhe eror ,ile 'erlors.eri in the cLrrrent directory. This is
lhe file to which allenoroulpd is r€direcled by Snlvaks. llth6re
are enoE in a ional that lhis lunclion can undersland(i.e.
similarlo Snasm and Snli.k)lhe user can sl6p lhrough lhe errors
using th€ up and down anow keys. Hitting enter on a highlighled
enorwilltakethe us€r to the reponed erorposition in ths r€levard
sourcs fle. The 'Home' and 'End' keys can beused lo move lrom lhe
top and botlom oi lhe eror tutfer rcspectiv€ly and pressing Cld whilsl
using the up and down arow kels allowsthe userto mov€ around in
th€ eror bufter line by line. Slriking ent€ron a lin€ that tie macros
do noi recognis€ as coniaining an enor msssage witl result in an
eror message lo thal ellect.

K€yboard equivalent Ctd'NThis option scans the lil€ 'errors.en' and moves the culsorlo the
nert gnor in lhg sorirce code. Bepealed invocations willstep
through lhe €Irors, On linding no mors errors the iunclion will
display a message lo lhal eflect on lhe slatus lins,

SCSI errors

lxhllit

assemblino

l, you ale s€nding lhe object oulpul down the SCSI harclwarc you may
occasionally see an error messao€ end be given lhe option to Abon, Retry or
Bus Bos€l ald R€try. The fiessage willlellyou wher6 the enor was detecleo
(Locally or by lhe Targel)and whal causedthe eror.

Examplas
LOCAL: Target nol available

LOCAL: Bus nol ava aue
ll lh€ errcr was csus€d by a power spik€ or by ih€ targei being tempora ly
unavailabl€ Retry will usually qet lhinEs Eoino aoain. l, ihis does not work
Bus Beset and Retry may b€ ellecliv€ as it resets alt devices on lh€ SCSI
bus and r€conn€cts wilh the 1ar9e1 belore having another go, Abolt should
be used il neilherofth€ abovs wo*, or illhe eror was caus€d by something
likelhe targel running outol memory, es this caus€s lhs ass€mblerto stop
assembling and €xil.

Debugglng
SNBUG6SK ls a lulHeatured debuggerwhich uses the SCSI hardwar€ to
enable you to r€motely d€bug a program running on your target machine.
Th€ dsbugger has eccess lo symbols within your program and its
expression €valuator has all th€ t€alurcs ol SNASM6SK which allows lull
symbolic d€bugging.

Th€ SNAUGoSK debugg€r lels you :-

. Trace your code Inslruclion by instruclion
, Sse lh€ varues ol your variables rn a van€ty ol lormais

. Change ihe value ol6ny vaiabl€ or msmory locaiion
is exeMed or wh€n

. Set breakpoinls lo slop when an instruction
a cendn condilion is mel.

To make it easier to mov€ between Bdel lor €daling and SNBUG6SK ror
d€bugging, where possible we hav€ lri€d lo use Briefs conlrot keys and

The

Lht

Soflwar.

The Unk Sottware usually resides in ROM on lh6 target machine inlerface
and it communicales wilh lhe ass€mbler and debugger. To snable the target
machine lo b€ d€bugg€d lhe unk sonware uses sevsralol the target
machines vectorc. These are

:
Veclor Number AddBs
2
0008
3
000c
4
0010
5
0014
6
0018
7
001c
I
0020
I
0024
32
0080

Flnction
lllegal inslruction
Zero divide
Chk inslruclion

Pivilege violation
Trace
Trap0

The debuggercan Oain control o, th6 laEel whenever ons or lhe above
exceplions occurs. ll your program is running noftnally none ol ihe above
should happen, so io ensure thd lhs debugger can gain conlrol rt requires
you should execute a lrapo inslruction al rcgulerinleruals. This 'lcan, ilyou
wanl, b€ wilhin an inlerrupt rouline such as vedical ,lyback.

Command llne Syniar
SNBUG63K /swilches syrnbolf ile
The s$1lches can be anerlhe symbol lile name il you ldish, and you are atso

allowed lo sp€cily seve€t symbol liles,

Switches

Load conliguralion lile
Thjs is to allow expressions to be
evaluated irom within 8d€f, you will

/lNumber

lNumbsr
/Number
/tNumbor
/gNumb€r

Example

no1

Load CPE nle inlo target
Ovedd€ video bios dala screen rows
Turn continuous updale on or ofl
Sp€cify rale ol update (See All-l)
Set lab€l l€vel
Set largel lD

Use Hercules graphics ddvers
Hali target al debugger stariup

snbug6Sk /m128 main.sym diskulil.sym

GenErrl Concepts
The dsbuggeis display consisis ol a number o, wjndows ol live basic lypes.
These are Begisler, Disassembly, Memory,Walch and File. Wndows can be
splitto lom lwo windows, th€ boderbetween two wjndows can b€ moved or
rsmoved and the lype ol wlndows can be changed.
You can have as many D,sasssmbly, Memory, Watch and lil€ windows as
you want bui you are resiicied lo only one regisierwinsow. You can move

belween windows al will, wlth lhe curenrly aclive window b€ing highlignied.
Wilhin each window lhe keyboad controls allowe you io change tie
windowb slate orsend qlmmandslo thetaEet machine.
ll conlinuous updale mode is on,lhs windows are reiresh€d at whatever rate
s€l,orlhe update interval. lllhis mode is not €nabl€d windows are onty
updaled when soms thing happens, i.€. a key is prsssed or a breakpoinl
is

The r€glst€r window displays lhe contents o, all o, the processo/s qeneral
registers. ahe cuisor can be moved around lh€ window and lhe contenls ol
any olthe regisleB changsd €ilher by typing the newvalue dkectly or by
pressing R€tum and €nledng an expression.

Dlsassembly wlndow
Thjs wiidow displays your code in disassembled ,ormat. Wh€r€ possible
symbols are used inslead of hex addresses lo make the 'codei more
r€adable. lfthe largets PC is al one ofthe lines in lh€ disassembty ir is
marked wirh a gr€al€rlhan sign (>). lfa breakpoint is sel lhe colour oithe
13

lin€ changes and th6 brcakpoinl expression and courl arc displayed afler
ll ihe debugger has b€en lold the name ol lhe symbot iable n reptaces
numefic values wlh lheir symbolic equivalents. Exaclly whgrc this ,s done ls
conlrorled using lhe label level. Local labels will oe seen ,n lh6 disassemb,y
window if lhey have been enabled at assemblylime using the v+/- option.
L6v€l

o
1

3
4

Ellecl
No symbols excepl ln addr€ss ,ield
As abov€ plus non-immedale or oflset symbols
All the abovs plus long immediat€
Allhe above plus oftsel(An)
All the ebove plus ofis€t(An,Dn)

Memory is displayed In h6x lormal as eilhsr byles, words or tong words. As
in lhe Begist€r wndow you c6n dir€clly enier new data or pr6ss reium io
erder an expression.
Th€ Waich window is usedto display thecont€nis ot memory at an address
given by an erpression which can, ol courss. conrain symbols lt rs used to
monilorlh€ value ol variables and lables as your program runs.

This window rs used io view laxt lilss. l,suatty sorrrc€ code. You can browse
around lhe iile and clo simple searches, bLt you cannot make changss lo lhe
lile-

Conlldur.ilon Flle!
when lhe debugger slans up ii geis ils inilrat siaie trom a contiguration t.te

called someth.ng like .SNBUG68K.CF? where ? s tne SCS| tD ot your
chosen larg€|. The /s switch can be used on lhe command line io aause a
diflerent coniig fil€ to be loaded. These titss can be saved and loaded al
anylime during lhe debugging session, so you can have a tew of your mosi
usetul conliguralions s€v€d on disk. ll a contiguEjion tite retels td a symbot
which no longer exists then thal pan ot lhe coitiguralion witt be Onoreit. tf a
conliguralion lile was saved wilh the debuqqer in a video fiode ivih a
r€solu{on ditterenl to lhe curr€nt one. you witt b€ given ihe choice ot either
swilching inlo lhe nsw mode. orignodng ihe fte a[ogelh€r

Ihe only enties in the contrg tite that you wrt, usualy need lo chalge are
lhose which specily lhs areas ol lh€ targets memory lhal can be rcrd and
wntl6n. This intormalron ls ussd lo prev€ ths debugger lrying lo access
memory areas which would calse an address error;itthe link io the target
goes down when you look al cedai. memory areas or it sohe arcas appea,
lo coniajn zeros ihen lhese sniriss reed to be changed.
You can €dil lh€ conrig lile, using a ten ediiorsuch as Bri6f, and chang€ the
memory areas und€rlh€ headings #readram and i'wdleram, the formi is a

simple lisl ol start and end addrcsses ot vatid areas, and you can have as
f€w or as ma4y entnes as you wish. Pt€as€ ke€p lhe fofliat ot ihe config tite
id€nlicsl lo lh6 odginal esbihelwise ths debugder can hav€ p.obtems r€ading il.

Prombt Hlstorv
whenever lhe debugger prompls lor a reply such as an expression or a
b'sakpoi condilion, you ci! nep back through otd rcptiea to that prompl
using cursor up and down. Tie prompt line can be edled with culsor tefl and
right, wilh homs, end and back"space perloming as you would erp€ct,

Svmbol Compl.tl6n
whsn€veryou are entering an €xprcssion you c{ln get lhe debuggerto try lo
compl€t€ lhe name olthe symbolyou arc ryping using Atr-N.
hAre arc

s6v€ral symbols which start with th€ text you heve enl€red, lhen you can
cycl€ lhEugh thes€ by pressinq AI-N aoain,

Erpr.s.lon

Evaluator

The debuggeruseslhe same expression €valualor as the assembterwith
the lollowing chaog€s :-

. Ths d€laull base is H€xadecimal. Decimal numbers are prec€ded by a
hash

(f)

. Processor regislers can be

used In sxoressions

. Square bracksts around an €xpression are used to pertom indiroction.

The dobugger felches a byl€. word or long word lmdr the targ6t, end sign
€xtends ir be{or€ using it in the expr€ssioi. Long wods are tatched by
debull wilh the @ operalor berng used to chanaethis as shown b€toiv.

Examples

100
#100
Iaol

100 h€x, 256 dedmal
100 decimal
Long word at AO
Ia0+d0.wl@w+ai F€tch the wod trom a0+d0, sign €xtend ii and add il lo
a1

Tte.b,

.w and,loperaioE which sign extend lhsiroperators trom the
specili€d l€ngth io a long woE can ctash wilh dots in tabet names. I this
occurs you can eilher bracket lhe expression and pul th€ .w oulside the
brackets or use \w inst€ad just as in the assembler.

Kevboard Controlc
General (nolk in all windows)

F1
F2
Fg
F4

Move to adjacent window
tbve a window edoe

Splil a

window -

R€mov€ a window edge

[,love lo adjacenl window (Tlese may not

wofi on

all

keyboards)
I\rove cu Isor lo lhe top ol lhs window. ln the Regisl€r and
Watch windows only lhe cursor moves whereas in lh6

Disassembly and M€mory windows the window address is
changsd so lhat the iiem underlhe cutsor moves io the $an

Cttlz

Toggle Fullscreen display on curent window

shifl-F1

cl+F2

Chang€ window type
Reslar! debugging s€ssion (when using a CPE fil€)

AII.L
cr -L

Sel window lock sxpression and lum on lock.
Toggle window locl on/ofl. (Prompis lorerpression it one
hasn'l been enlered)

AII.H
AII.D
Att x

ctd-x

llt-z

Display creation dal€ ol debugger
Exitdebugger (Automalically saves cunent slate lo
SNBUG6SK.CF?)
Eril wilhoul saving stale
DOS gateway Type exir', lo relurn io debugger

AII.S

save laEel regisleB
Resiors saved regisleF

cld-R

Resel. SSP and PC are loaded lom locations
load€d wilh S2700.

Esc

Hall targ€t machine as soon as possibte
Haltlarget inachine and tum ot irngrrupis,DMA

Shilt-Esc
Ah.U

AtH

and 4, SR is

Toggle conlinual updale mod€ on/ofl. lDelault ott)
Sei inlerual for conlinual updare il l8tis o{ a sec6rd. {o=Ftal
out, 2=9 limes p€r second, l8=once p6r second)
Upload bytes lrom targst into e lite
Download by.les lrcm a fle to tarEst memory

Ctrl-F
F10

Save cufl€nt conl]guraiion to a lile

shifl-F10

Load conliguralion

Att-0..7

Change targel number. The currenl setup is saved lo lh€
conlig lile and a new conlig lite torlhe new targel is toaded.

il€

Eeglsier window

Arrou6
Reium
0-9/A-F

irove qJrsor
Change reoislels valu€ lo resull of an expression
Enler new valu€s at cursor

llemory wlndow

Arrows

Mova cursor

Relum
0-9/A-F

Move cursor up/down a page al a lime
Chango msmory valu€ lo r€sult otan oxprsssion
Enler new values at cursor
Goto €xprsssion, Changes window slarl address lo result ol

AIt.G

Swilch bstwe€n byl€, l]vord and long word display
Set window slarl to value ol long l|ord under cursor
lncr€m€nUdecrcment value under culsor

lns
Del

Add e new walch expression
Remove a watch expression

Dlsass€mbly window

up/down

leflnght

Alt-G
Tab
Shift'Tab
Alt-C
Cld.C
Alt-Fs
F5
F6
F7
F8
Fg
shift-F5
shin-F5
shitt-F7
shift.F9

Llne up/down
irove a word al a time

ilov€ curcor up/down a page al a lim€
Golo gxpression, Moves cuEorto r€sult ol expr€ssion
Move drsorlo PC
Move PC to cursor
Attach condilion lo brealeoinl at cursor
Attach counl lo breakpoint d srrsor
B€set all breakpoint counts

Toggle breakpoint al cursor
Run cld€ at larg€t unli! instruclion al cursor
Trac€s. Steps ov€rtraps and line NF
St€p ov€r. St€ps ovsrsubroutine calls and dblas
Starl laEet executing cod€ lrom oJrent PC
Clear all breakpoinls
Res€t all breakpoint counts
Forced trace. Traces down lraps and lin€ A/F
Run lo sp€cii€d addr€ss
lncremenvdscrem€nt label level

'17

File Window

up/down
l€turight
Home/End

Enter
Alr'G
All-S
Alt-N

Line up/down

Characl€rlelvrighl
irove cursor up/down a page at
Beginning/End ol file
Change lile nam6

lim6

Goto lin6
Search
Next ocdrrance ol search slring

tlerctrEr-IxEsr
This swilch, wlich should only b€ used wilh heroJles mono cards, causos
lhe debuggerto us€ its buit-in hi'rssolution hercules diveElo give you
many more rows ol characl€B on ths scr€€n, The /90 uses 80x50 mode and

/gl

90r4ai.

Source Code Syntax
The slalemsnls in 68000 source code arc eithor instructions which can be
translaled into 68000 machine cods, or dir€ctives. Di.eclives are ussd lo
controllhe operation ofths ass€mblerand how it lnteDrcts the source c!de.
SNASM6SK supports the Motorola standard 68000 mnemonics. Thes€
mnemonics are not sxF,lained in this manual as il is nol inlended to be a

58000luiorial.

Stalemenl Format
Slal€menls have the tollowing general form
label

op€ralion operand

commenl

Ndes
. Lab€ls always stad inlh6lirsl column unless they €nd with acoton (:).
. Fisrds are separaied by tabs orspaces.
. Anyihing on a line anerlhe op€ration and operand ls taken as a comment but
lo avoid conlusion il is r€commended thal lhey bsgrn wiih a semi-coton.'

. Blank lines and lines coniaining only tab6 and spaces are comments
. Lines slarling wilh a semi-c{lon or an ast€nskare commenls.
. Lines staning wilh an equals sign are case statement setectors,
Labels end Svhbols

kbels.nd

Symbols nust ob€y lhe lollowing rures

. A symbol contains characlers from the set:
A-Z

disils

0-9

Unde6corc L) and Oot (.)

Digits may not be lhe lllsl charactsr of a symbol except in loca, labels.

A symbol may optionally be lollowed by acolon when il is detined but nol
when it is r€l€r€nced

. Local labels bsgin wiih an al

(@) or optionatty a dol(.) Tlese are e,(ptained

later in ihls manual.
As labelscan cont6in dots it ls possibte tor there sometinres to be con,usion
aboui whelher adol is pan ol e labelor a siz6 moditier.ltthis happens you

1 The wS
oplion makes rhe dsemuer lnslst on a seri-@ton betore comenls. see the
ssclion on oplDns ior moro inronEton.

can €jlh6r bracket the expression oruse backslash 0)in place ot the dot on
lhe size modilier.

Erempl€s ol symbots

Mysymbol

@Local

A135

Last_One

The assembler has various predelined constanls available which usuatly
siarl wilh an undeBcoie. ll you want 10 avoid clashes wilh any luture ones ol
theselhen avoid the use ol undeGcore as the lilsl character ot a label.

lnieder constanrs
Thedelault base ror constanis is decimal unl€ss the RADIX operalor is us€d
to chang€ it. Hexad€cimal numb€Is arc pr€ceded by a dollarsign and
binaiy numbeB by a penentsign. lryou want to use theASCllvalue ol a
characler as a conslant place il in quotes. ll a character is preced€d by caret
(^) the corresponding culrolcharacter is subsl 0t6d.

CoL(.nt

DecimalVelue

1234

'1234

$A0

160

'?"

42
65
63

%i01010
'4',

BADU

Syni.x

FADIX

cdnstant

ljnless you tellil olh€Mise lhe assembler assu mes thai the radtr ot a
numbernol preceded by $ or% is decimal. Wiih the RADTX operaoryou can
change lhis delaull lo any valu€ betwsen 2 (binary) and t6 (heredeclmat).
The argumenl lo lhs BADIX op€raior is always evituated using decimd aa

Irh€ AN (alternale numeic) option is enabtsd, you can atso detile
conslanls in lh€ Zlogllnlel lashion. Th€ number, which must begin wiih a
decimal digil, is lollowed by H,D,Oor B to specily the base as Hdx, Decimal,
Oclalor Binary respeclively, This fsaiu.e does notwork il ihe defaul rcdix is
>1 0 as B and D ar€ valid hex digits.
Location Cou.rer
An asleisk (') wh€n us€d as a conslanl substiluteslhe value olthe cuiienl

Example
MyString
MyStringLen

dc.b

'Hello Wofld

'-Mysldng
20

Exotesslons
SNASM6SK uses a signed 32-bit integel expression evalualor which has
th€ lollowing operators :-

Operators

I!Lg!

+x
-x

posiiive(unary)
negalive(unary)
addition

X+Y

;
v"
&

I
0

x.Y

mulliplicalion
quotient oJ divislon
remaindsr ol division
logical and
logical inclusiv€ or
logical complimenl

)sY
x%Y
x&Y
x!Y

-x

shi,t X lefr (Y iimes)
shifl X ight (Y limes)

(x)

Comparlson
grealerlhan
grealer lhan or equals

Funclions
der{)

reo

nars0
sircmp0
stden0
inslr0
lvpe0
sqn0
secl0

ofiseo
filesize0

DEF(X)
REF(x)

symboldelined

NARG(X)

parameleis argumenl counl

STRC P(S1,S2)

sling compa

STBLEN(S1)

stfing lengih

TYPE(X)

typ€ ol a symbol

oFFSET(X)
FtLEStZE(S1)

Size

rNsrB([x,]s1,s2)

soRr(x)
sEcT(x)

son

ofa lile

Speclal constants

narg
_rs

NABG

parameleB passed to macro

__R S

currenivalue ol rc counler

Jear, _monlh, _day, _weekday,
ssconds
_houls,
-minules,

lime and daie conslanls

For a lrue rosull compaison operaloB relurn -1, lorlatse lhey retum

Some ot ihs above lu4cliols and consiarts may be un.amitia. bur ihey are
'
erplained laier in ihe

m€nual.

Note
Unlike some assembleF SNASM6SK uses a lull 32-bit sxpresston
evaluator, so you must bs careful when using large numb€6. A number
needs b[ 31 sel lo be negalive, nol jun bit 23.

Erampls

Pa)o
€qu
i lhe abovo is NOT lhe sm. aq
PalO
€qu
Op.r.lol

$FF8240

;posrl,ve numbe/

$FFFF8240 ; negativ€ numberl

Prccedence

SNASM68K evaluales expressions using the totlowing rutes

. Op€alors wiih

higher pr€cedence are perlohed betore ones wilh tower

. gp€lalors with lh€ 6ame precedenc€ are pedorned lelt to ight
. Expr€ssions in parenihesis are always evaruated ,irsl as thei have
high€si priodty

the

The table below shows opeElor precedence in dsscending ordet

+, -,

(unary)

+, - (binary)

li is usually bssl to parenthesiz€ an erpression to make ii ctear lo bolh
yoursell and lhe assembl€rwhat you msan,
ALIAS and DISABLE

llany ollh€ assemble/s pr€-defined constants orlunciions ctash with
symbols in yourprogram or il you simply donl trke th€ cuneni names yoJ
can remove the delinitions wrlh the DISABLE command. As lh s woutd make
the funciion inaccessable you can Jirsi rename ii using AL|AS.
Example
-Tvpe
Typo

alias

lype
tvps

;

Typ€ ol account

ALIAS ard DISABLE can be ussd on ary nams {symDot. turct,on macro etc)
that lhe assembler has akeady encounlered bLlr il cannoi be used lo renrove

or rename assemblsr inslructions or direciives-

Equates
Equates are a way o, attaching a symbolic name to a conslanl orvariable
numedc valug- This improves cod€ readability and means onty having to
change one line lo change lhe value orthe constant.

Perman.nl Edual€s
EOU
This islhe mosl common lyp€ ol equaie. Tle symbolon the len handside ot
lhe lin€ on which the EOU directiv€ occurs is assigned rhe resutt ofthe
€xpression on rhe dghl.

Example3
-1

equ
lOPort
Entries
EnlryLenglh

$300
equ
€qu

Tolalsize
8it3

16
Enld€s'EnlryLength
8

Onc€ a symbolis given avalue with the EOU directive any atempt to assign

e newvalue willgenerale an error.

ll is podeclly l€galto re.equare asymbolto the same value as

ir atready
holds,. These are called banign red€nnitions and will usually occlr when an

include ,ile delines hardware localions tor ilsell ihat the main prog€m also
Mosl assembl€rinsisl lhal th€ €xpression lo which the symbolis equaled
conlains no loMard r€ferences. With SNASM6SK how€ver, as much as
possible ol the exprsssion is evaluai€d, andlhe r€mainder olth€ wofi is
don€ at the end ol the lirst pass. You should be careiut when ,olwad
referencing local symbols in ihls way. as lhey wirr probabry not exist when
lhe evaluation is done

Bedelinable Equal€s
SET and =

Wh€reas EQU is used ior delining conslanls SET and = are used tor
delining variables. A symboldelined with either ollhese directives can have
its value changod as onen as you like. Th€s€ vadables arc trequentty us€d
as loop counlels and scrE ch vadablss jn macros.

Example

Freespac€ set
Freespaco ;;

Freespac€+l

024

;

zero tree space lolal

;

K more lree her6

Set and = are synonymouse.g.

Tolal

=0
=

Total+1

SNASM6SX generales a waming il a variable is reierenced belore it is
delined, lJ you do loMard relerence a vaiable, the value subsiiluled willbe
lh€ value ol lhe variable al lhe end ol lhe lirct pass.
Unlike EOU lhe aqument ot SET musl not conlain lorwad references. AJso
no iniormalion aboul th€ type olthe erpression is inhedted by the symbol,
which meanslhey are nol always lhe best choic€ in code using seclions,

eg.

section

Code,Text

Marker

;This next line will9;6 an eroras'is l€lative to ihe start oithe seclion and
;Ma erisjusta number
;ll Maker is derin€d wilh an EOU ihe €xpression willevaluale.
dcb.b

'-lvtarker,63

Strlno Eduates
EOIJS
EQUS is used lo assign a value lo a stdng variable. Stdng var ables are
used lorihings like version and copyight messages oras scralch va.iables
As symbols .quat.d silh lhe EOUS direciive can be used anywhere in your
code they must b€ preceded by a backslash 0) character so the assembler
knows thal a sldng equale is lollowino. ll ther€ could be conlusion as to
whers th€ name orlhe strino variable ends use a second backlash as a
delimiler. The only exception lo lhis rule is in expressions, as il ths
assemblerlinds a symbolwhich is a slfing va able whilsl evaluating an
expresslon. th€n lho stdng is substiluled automalically.

The parameter 10 the EOUS directive will usually be delimited by quoles in
which case thal lexl is assigned lo th€ sting 6qsate. ll the quoies are
ommitled lhe ass€mblsr expecls the parameler to b€ ths neme ol an already
dgrined slfng €quate,lhe conlents oJ which are tlansfered 1o lh€ new stdng
The parameter can also b€ enclosed in cudy brackets ({}) lh€ use ol this is
explained in the seclion on macros.

Examples
1)

€qus

'Demo VeEion 0.21 22105/89'

dc.b

'D€mo Version 0.21 22105/89'

'lnlDispAddr'

IDA

; expands

dc.l

\IDA\1

dc.l

lnlDispAddrl

to
\IDA\2

;

erpands to

; Note use

lr DispAddr2

ol second backslasi as delimit€r

HexSlr

,
;

exPands lo

hex

\Hexsti\Hexslr

her

FFOOEFOO

Note lwo backslashes

Sldngs are delimiled with quoles, single (')ordouble ('). The quotes which
are used lo delimit the stdng aner th€ EOUS direclive do nol become part oi
the symbols conlents.lryou want to pul asingle quolo in lhe string yor.r can
eitherdouble up the single quolo ord€limil the sidng with double quot€s.
Exadly ih€ same applies 10 double quotes: eilherdelimir wirh single quotes

Examples
Singlel

1t's great'

Single2
Doublel

"l1sgrcaf'

Double2

equs

'They shouted "Yes ' togelhe/
"They shouled ""Yes'" logethe/'

There is a prcdefined sling equale called _lllename which holds the name
oflhe lil€ b€ing assembled- This is lhe lile on which SNASM was invoked
not lhe cur€nt includo ril€.

Exampl6

dc.b

'To rebuild lhis assemble Llilename,0

BS Eduates
RS. RSSET, RSRESET

Syntar

Ss.size
RSSET

Count

Value

BSEESET Ualuel
RS equales are used when you wanl lo deline a sel of symbols as onsets
inlo some data struclure bul do not want 10 keep track ol the ollsels yourcell.

The assembler has an inlernd vanabb called _FS which is ussd lo keep
irack ofthe curr€ni ofiset. When you dgline a symbolusing lne RS direclive
_BS's valus is assigned lo the symbol and lhe counler is advanced by the
speci,ied numb€rol byles, words orlong words. The RSRESET dkeclive
zeros _FS and is used al lhe start ol each new strucIure. FSSET puls any
value you like into the _FlS variable, it is used when you want to stan the
offsels al somelhing olher lian zeroFor compalibility wilh olher assemblers,lhe RSRESET dlreclive can lake an
oplional parameler. which il presenl causes it lo behave exaclly like lhe
RSSET direclive.

Exampl€s
1)

Fil6Handle
Fil€Open

FileName
FilePos

rs.b
16.l

Filespecsize Is.b
;or w€ could have used
Filespecsize equ
2)
Issel

tWe could have used

1
1
8+3
1
0

_RS=o
;_RS=2
;_BS=3
; _RS=14
i =18 _RS
;

_RS

-8

;
;

rsres€t -8
i bui this is lor compelibility
and ils use is
;

ObjXPos
ObjYpos
ObjFlags
Objspeed

is nol advanced h€re.

rs.l
rs.l

rs.w
rs.w

-ve as address register poinls
eight byl6s jnlo dala slructure

discouraged

lilhe auto€ven

_BS

option is enabl€dthe wod and long loms oi BS lorce the
variable to b€ s€t to lhs ne{ even bourda.y bsrore ihe operation is

L,se oi RS and associated direclives rssults in dae$ruclure d€finitions thai,
in addiiion to being easy to read, allow you to acld or subtract fields without
having lo count on yourlingelsl

Pr.-d.flned Constantg
To help you ke€p lEck orwhrch velsions ol your prog.ams were made
when. SNASM6SK prcvid€s the lolowlnE pre.defined numeric conslanis.

Narog
-YEAR
-MONTH

Gr€goian (e.9. 1989)
1=January... l2=December

-DAY
-WEEKDAY

_HOURS
_MINUTES
_SECONDS

Exampl6
AsmDay

day

Noles
The above conslants holdthe date and time ai the slart ot assembly: iheir
valugs do not change dudng asseobly.
To put lle dale and time inlo a slring yo.r can use lhs \# parameterwhich is
described lal€r in the cha er on Macrcs,

Faolsler eosaieg
EOUB
EOUR is osod to deline a symbolas a synonym tor a data o. address

rcgisler lo improve code readability.

Example

move.w
;

d0, Ofls(a3d2.w)

@uld be wnllen as :-

Powsr
CelDataRr
Curlndex

equr

€qur
€qur
;"r"."

d0
a3
d2
Power,Oits(CaDelaPlr,Curlnder.w)

Dols ars not pemitt€d in the nam€s ol regisier equates so that the
assembler knows lhal Cudndsx.w m€ans the low€rword ol {d2) ratherrhan
a register €quate called Curlndex.w.

BKi
Simila y BEG is used to deline a sy.nbolasa synonym tor a tisl otdala or

Erampla

movem.l
:could be wrinen as

d0-d6/a0.a6..(sp)

MainR€gs req

movem.l

d0{6/a0-a6
MainRegs,-(sp)

L.
29
l

Detining Data
Dellnln9 lnltlall..d Oala
D.a
The DC dkeclive takes a variable number of argumenls and all€r evalualing
thsm places lhe results in lh€ objecl code in eilherby,le, word or long word

Examples
-69,202
0

LineLengih
Signalure

dc.l
dc.l

'zM'

ExelD
EnorNum

Erolstr

Dispatch

SldngBufisr

dc.b
dc.l

'Maximum length exceeded',o

Rouiinel,Rouline2,nouIne3

llyou wanl to pul asingle quote (') in a$nng you can eitherdouble up the
single quote ordelimillhe slring with double quotes ("). Exaclly the same
applies to doubl€ quoles: €ilher delimit wiih single quoles or use lwo

Examples
Singlel
Singl€2

dc.b
dc.b

Doubl€1
Double2

dc.b

'll"s greal'
"ll's great"
'They shouied "Yes" rogether
'Th€y shouted '"'Yes"" togethe/'

DCE

Syntax

DCB[.size] count,value

The DCB directive is used lo generate a block o, memory conlaining a
specitied numberof instances olths sams byie, word or long value.

Examples
dcb.b

100,63
256,7

; 100 byles containinq 63
;256 wods coniaining 7

l{lhe auto.even oplion is enabl€d lhs wod and long lorms ol DC and DCB
iorcelh€ program counlerlo the next even boundary b€lor€ lhs operation is

Whereas some assemblers lruncate out ol range parameters
inio rang€, SNASM6SK gives an srror
e.g.

Allollhe following cause

dc.w
dc.b
dc.b

lorce lhern

eroi:70000
-40000
260

n30

greater lhan 65535
less ihan .32768
grealer the 256
less lhan 128

Handv tio

llyou detineWod and By.le as shown below you can uss lhsm as a quick
and r€adable way of lruncating a numb€rto a word or byle.
Byte

'$FF&',

BigNumber

70000
\Word\-40000
\Word\BigNumber

(h.b

\Byie\(-80'9)
\Byie\aigNumber

iBrackelsareimportanll

EEX
The HEX dircclive is followed by a slream ot hex nibblss which are paireduP lo givs byles.
e.g.

MaskTabl
i

dc.b

could b€ wdllen as...
hex

MaskTabl

$01,$02,$04,$08,$10,920,$40,$80
0102040810204080

The HEX direcliv€ should only b€ used lorsmallamounts ol dala. Dala
stored as h€x is very unr€adable, takes twice the space ol blnary dala and is
slower to load and assemble. Ratherthan having vast quaniiiies ol hex data
you may preler ro pul lhe data into a iile as raw byles and use the lNcBlN
directiv€ d€scribed laler
DATA and DATASIZE

The DC dir€ctiv€ can only be used lorconslanls that can be contained wlhin
32 bils, lt is somslimss n€csssary lo plac€ larger conslanls wilhin code and
the DATA and DATASIZE direclives havs b€en provided lorthis purpose.
DATASIZE is lollowed by e single paramelerwhich speci,i€s how many
bytes are lo be used lor conslanls delined using the DATA directive. The
DATA dirocliv6 has avariable numberof parameters, which are decimal by
delaull bul which can b€ hex il pr€ceeded by a dollar ($). Binary numberc
and the altemate numefic lom cannot be used.

Erample

datasize

dala
dala
data

;256 bil numbeE
10000,1000000
$100,-200
200000000

B.servind S.ac.
DS
The DS dirocliv€ is used lo
€.9.

ScrarchBuiier

Pointetist

iese

d5.b
ds.w

e, and inilialise lo zero, a block ot memory.

1000
,6

;space for 1000 bytes
; space lor 16 wods

lrlhe aulo+ven optlon ls enabledlhe word and long word lorms o{ DS lorc€
the program counlerlo the nen ev€n boundary belore lhe operation is
performed.
The OS dir€clive is used in BSS lyp€ sections 1o reserue space. Uke
€verything in BSS sections no inilialisalion is p€rlormed, so don't rely on
there b€ing zeros in menoryl

Changing the Program Gountel
cre
OBG ls used to telllhe assembler wh6re inlhelargot machinelh€ cod€ is io
reside. You sholld.ol use the ORG directive ilyou ar€ producing linkable
oulput as tha linker decjd€s whgr€ th€ vadous parls o, lhs program are lo
go. ll you ar€ nol using seclions in your prcgram you are lres io us€ as
many ORG dirsctivss as you wish.

Erampls
Slartl

otg

lea

$400
lvrstack,sp

lf lhe argumentlo ORG sla(s wilh a qu€slion mark (?) n as inrelpreted as the
amount of RAM lh€ prcgram fleeds and the targel is asked to reserue lhat
much memory, Ths targ€tthen returns ihe sddress al which it managed lo
rcsevs th€ RAM and SNASM6SK assemblesthe pogram to run al that

Example

Slart

org
l€a

?512',1024

;

asklor 5l2K ol Ram

VaBase(pc),a6

This lacility is us€rulwhen developing lora macnine wilh the operating
systsm resident. This lorm ol the OBG darective can tak€ an optional second
palamel€rwhich indicates the lype ot memorylo b6 resorved, Th€ value of
this parameler is specilic to lhe velsion ol lhe larg€t soltware being used.
EYEN
The EVEN direciive lorces lhe prcOram counter lo lhe n€n even address.

Example
Prompl
;

&.b

'Hit a key when ready',o

Butsr musi be on word boundary

BuJl€r

ds.b

1024

cloe
CNOP sets lhe program counierlo agiven olrs€t rrom any size boundary

Examples
cnop

o,2
o,4
64,128

;

same as even direciive

; nexl long word boundary
;

64 byles above next 1 28

; b).le boundary

Wh€n using seclons il ,s noi possible lo align lhe prcgram counier to a
larger boundary ihan lhe aliqnmenr ol the cureni s€cton, i e. EVEN cannot

be used in a byte aligned seciion and CNOP lo a 4 byles boundary cannot
be us€d in a wod aligned section.
OBJ and OBJEND

All code g€nelalsd an€rlh€ OBJ directive but before lhe OBJEND dk€clive
willslillbe placed at thesame place in memory bullhe code wjllhave all
ollsels sel lor il lo run at th€ address specllied alter the OBJ dk€ciivs.
ThiS is sometim€s reJored to as asssmbly with otlsel.

Exemple

-.
_

RunAddr
@Loop
Reloccode

oQ
equ
l€a
lea
move.w

dbra
jmp

$8000

$400
Reloccode,ao
BunAddr.al
*(RelocEnd-Rotocoode)/2-1
(a0)+,(a1)+
do,@Loop
Retocoodo

obj
RunAddr
willbe set to run at RunAddr
jmp
Slarlup
.ou".,, *$z7oo,sr

; EveMhing within this section

$anup

obi"no
RelocEnd
OBJ and OBJEND should always be paired correcity it you need lo reverl lo
'normal assembly, Dont ommil an OBJEN0 diecliv€ or use lwo otthem, or
aflempt lo nest OBJ/OB.,END pairs, as the assembter wilt toose track oi
where lhe PC acrually is, and no doubl you willlool

lncluding Source and Binary
INCLUDE

_
-

You will almo$ ceneinly wani lo break yosr source code into several smaller
,iles eilhsrlo make il more manageabl€ orso you can lse some olthe pans
in more lhan one program,
The INCLUDE direclive tells lhe assembler lo proc€ss anotherfil€ belorc
continuing wilh lhe clnenl one. You will nomatly heve one rool' ,ile which
includ€s all the olher parls ol your cocle. ll you wanl, lhese includ€d ril€s can
include liles of their own.

Example

SlarlupCode jmp

include
includ€
MainEnlry lEa

MainEnlry
'equs.asmr
c:\general\malhs.asm
Mystack,sp

lllh€ lext lollowing the backslash can be conlused $ith asling equate use
eilher lwo backslashes or a lolward slash. You may encloselhs file spsc. in
quoles if you wish bul lhey are optional.
e.g.

include
includ€

ll lhe fil€ c€nnot be found in lhe

c:\\general\mAhs.asm
c/general/maths.asm

ent direclory it is searched,or in all

dkectoies specilied wilh the 4 sw1ch.

tNcEtN

l, you have a lot ol data in raw binary romal such as graphics or music dala,
you oan us€ the INCBIN directive lo include lhis into your prooram. As the
daia is jusr byres the assembler knows norhing abour its inlemat slruclurc
and you will have to put a label on the dala and handl€ ot sets into lt
yoursell.

Exampte

lea
add.w
add.w
SineTable iii"Uin

SineTable,ao
d0.d0
d0,a0 i lndsx wods in sine iabte
'c:\labres\sintab.bin'

See the abov€ notes on using backslashes in palh namss,

tlthe lile cannol b€ round in the curenl directory it is ssarched for in
dirccloies specilisd with the /jswitch.

att

lfyou needlo know the size ola binaryllle bofore you includs il then you
can uselh€ FILESIZE ,unclion. This retums lhe size ol alile in b).tes or
minus one il lhe lile ennot be lound

Ex.mpla
EinHeader

dc.l
lncbin

fileslz€('sinlab.bin)
sintab.bin

DEF and REF

ll you havo a gsneral purpos€ piece ol source code that will b€ includod in
quit€ a lsw projects you oiten want to have conlrol ovgr e)(actly which
routines ar9 included, Tle REFoperalor relums true ilthe symbolfollowing it
has already been relerenced,

Erampla

rel(Prirn0

movem.l

do/ao.-(sp)

;This is only assembled il Pintf has been rer€r€nced

Pnn
;

end oi

pinll

rts

Th€ DEF operator returns true illhe symbollollowing ii has already been
delined. You can us€ lh€ DEFtunclion lo ch€ck illhe va able has akeadv
been delined and lhen detln€ il only i, n€cessery.

Example
;

il
ds.b

-del(SlfingBuller)

This is only assembled if StingBuff€r hasnl been delined

SldngBullei

endil

EEE
The lype lunction provides inJormation about a symbol. lt enabtes a macro
to delermin€ exactly what il has b€en passed as a parameier.
The valug retumed is a word, wilh the bils having the lollowing meanings :0
1

2
3
4
5
6
7

Sel il symbol has absolule value
Set llsymbolis relalive lo slan ol a section
Sel il syfibol was derined using 'SET' direciive
Sel il symbol is a macro
Set if symbol is a sldng equals
Sel il symbolwas derinsd using an 'EOU'directive
S€t il symbolwas specalied in an'XREF statement
Sei ilsymbolwas sp€cilied in an'XDEF nalemenl
Sel ilsymbolis a tunclion (STBCMP, NARG elc.)
Sel il symbol is a group name

10
1
12
13
14
l5
1

'
-

Sel
Sel
Sel
Set
Sel
Sel

ilsymbolis a macro paramstsr
i, symbo! is a shon macro (MACROS)
ifsymbolis a seclion name

il symbolis absollte wod addrsssabl€
il symbol is a r€gister equal€
il syrnbol is a register lisl equale

To check specifc bits roturned by th€ ryPE lunclion use the bitwjse and
operator (&).

Erample

ir
inlolm

0p€01 )&$200)=0 ; ch€c* bit 9
3.'y"s is nol a grcup name!',\1'

endif

Setting Target Parameters
BECS
ll you are silhsr ssnding cods straight lo the taeel machine or il you are
producing a CPE fil€, it is possible to specily the values lhat you wanl the
68000 regisleB to have wh€n your code is €x€culed, lJsually lhis leature is
used tosetlhe Pc at which you wanl €x€cution to begin, andlhevalue of
SR ar rhis rime.

Example

org
regs
Codestad lsa

$400

pecodestan,sr=$2700
Myslack,aT

As the 68000 has two slack poinlsls you must use be speciiic about which
you mean by using USP and SSP.

This lealure cannot be us6d ilyou arc producing machine specilic
.elocalable or pure binary formals.

WOBKSPACE

Ths laEel solware uses about 1 K of memory ,or its own workspace. Wiih
mos! versions of th€ larcel sollwars il is possible io change ihe address ol
rhis usinq the WORKSPACE command.

Example

wo*space

$80000
${00

; above 512K

Assembly Flow Control
END l€lls the asssmbler lo immedialsly stop processing lines. The usg ol
END is onliroly optional as SNASM68K aulomatically stops when lhe €nd ol
lhe source lil€ is reached. END has an optional parameter which can b€
used lo sp€dt ihe ex€oiion address ol lhe prog,am. Use ollhis f€ature is
discouEgsd asihe REGS dircclive can t€ used lo achi€v€ that sam6 ihing.

Erample3
1)

Slanupcods

lea

; End of proqram

;;
end

; No sian address
No enor here as lhis line is never reached.

Slartupcod€

lea

lvrSlack,sp

jmp
end

lF ELSE ELSEIF and

&anupCode

;

slat al slartupcode

ENDIF

Th€s€ ar€ ussd lo conlrol€)(aclly which lines ol code get assembled.
Conditional assembly is us€lulilyou need to generale severalversions ot
lhe program, but il is mainly us€d in macros lo c€lse lhem to expand
diff erenlly under dillerent condilions.

Exslnples
1)

DebugMode

equ
equ

0
Falss

;The lollowing cod€;ill be skipp€d il D€bugMode is lalse

it
DebugMode
move.w XPosilion.do
Pdl
Fr
endif

English
German
Language
i Assemble

equ
equ
equ

equ

I
2
English

correcl;;nk odenng sldng ac.oding to qrrr€nt language.

Lanquage-English

dc.b

Two b€ers pl6as6',0

€lse
it
dc.b

Language=Fr€nch
'D6ux beir silvous plait',o

Language=Geman

if
dc.b

'Zw€i bier bitle',o

endil
endil

endil
3)
English

equ

0
1

2
English

Languag€

tAssemble corrocl drink ordoing string according lo currenl language.
it
Language=English
dc.b
dc.b

€lseil
dc.b

'Dsux beir sil vous plait',o
Language=German
'Zwei bier bilte,0

Ngles
ln example ihree th€ ELSEIF direclive has been used lo make th6 cods
more readable. ln lhe same example ENDC is ussd inslead ol ENDIF to
show thal they arc synonymous,
For compatibilily wiih other assemblels lhe ELSEIF direciive can be lsed
withoui any paramelers in which cas€ il acts exactly like an ELSE dircciivs.

lndenling ol code has been used in thss€ €ramples to male tho cod€ more
readable. You may wish lo do the sam€ rhrng bul ii is €niir€ly optional.
The logical not (-) op€rator can be used lo branch on lhe opposite ol a
condition bui you musi be car€tullo parenlhesiz€ the €xpression corectly.

e.g;ll may be templinglow le

il
ll

; bul you probably wanied

CASE-aod

-Language=German

-(Languag€=Geman)

INDCASE

lf you hav6 a symbol which you wanl to nse lo saleci b€iw€sn sev€ral piecss
ot code as in €rampl€ lhr€€ abovo,lh6 CASE directive can bo used. This
dkective can be used in place ofthe lF direclive as shown in example one
below, bul ii really comss inio iis own lormulti'way choices.

Syntax

CASE

Expression

=Expression{,Expression)

EN DC ASE

Example3

0
True
Larg€Butf€r

equ

True

LargeBull6r
=True

ds.b
ds.b

256

1024

2')
i A6sembls corrscl ddnk ord€ring string according lo cur.snl language.
English
€qu
0
1

2
English

German
Language

-English

dc.b
dc.b
dc.b

Languag6
'Two beers pleass',o
'D€aux bek sil vous pleil',o
'Zw€i bier bifle',0

€qu
o
SaveMode €qu
2
ProgMode equ
SaveMode
ProsMode
;;"
=ExeculeMode,D€bugMode ;Selecloneilhervalue
l6a
l,lystack,sp
jmp
Codesiarl
Codeslart.ao
=SavoMode l€a
mov6q #0d0
move.w #Codss€cis,dl
jsr
Wnleseclors
rls
Inform 3,'Bad valu€ lor ProsMode'
=?
See laterinlhis manualtor
ExeculeMod€

DebugMode equ

etplanalion ol INFORM

;

6ndcase
NglEs
The =? cas€ is us€d il non€ o, the olher cases succeed, ll lh€r6 is no =?
cass and allths oih€r cas€s lalllhen non€ ol lhs cod€ will b€ assembled.

BEEK!4ENDE
The REPT direcliv€ is used to repeat a shon soclion olcod€ a
prsdel€min€d number o, times.

Syntax

HEPT

Expr€ssion

ittoa
Eramples
1)

r€pl

mov6.w

d0,-(a0)

endr
2)

Tabl€Enln€s equ

lnder

0
TableEnldes
lnd€x
lnd€x+64

lnd€r

=
repl
clc.w
endr

WHILE .nd ENoW
Th€ WHILE dkecliv€ is us€d 1o repeat a short section o, cod€ whilsl an

exprcssion evaluales lrue,

Syntex

WHILE

Expression

Exow
Eremple

Factor

equ

i Build lhe code r€quired 10 muhiply by

T€mp
-

T€mp

whil€
rol.w
=
€ndw

laclor

Factor

Templ
(s0)
T6mp>>1

DAi[d]]NIlL
Th6 DO/IJNT|L loop is similar to lh€ WHILE/ENDWH|LE loop excepl th€
condiiion is checked al the end olths loop andthe toop,ng tinishes once the
condilion b€comes lrue.

Syntax
DO

iixrt

Expression

equ

Example

Faclor
I

Build lhe code rsquirerl lo muliply ry laclor
Factor

Temp
*

Temp

=
do
rol.w
until

(a0)
Temp>>1
Temp<=1

Macros
A macro is a way ol giving a sequence ol assembler lines asymbolic name
so they can be assembled lal€r as many limes as you require, A macro is
invoked es il it wfiere a new direclive and like dk€clives param€l€rs can be
passod lo them. They ar€ used to ext€nd ths ledtures ol lhe assembler or
jusl save a bil of tyFing.

lntroduclnd llacro3
MACRO and ENDM

Th€ lines b€tween the MACRO and lh€ ENDM dk€ctives are stored an
memory and can b€ relerenced uslng th€ label proc€ding th€ MACRO

Example
;

Expands to two

NOPI
nop
nop

Delay

TwoNops ; assemble lwo NOP!
TwoNops ;lwo more

WheneverTwoNops is used as if il wer€ a dirccliv€ lhe macro is expanded.

MEXII
Th€ MEXIT dksclive causes expansion ol ihe currenl macro lo slop
immediately.

Exemple
;Macro $lrich repeal a stdng acedain numberollimes.

NewDs

macro
it
inlorm
mexit

natg<>2
2,'Wrong numbsr of parameters

€ndit

repl
dc.b

u
\1

€ndm

NewDs
lhe

'Hello',2

MEXIT direclive is supporled lor compalibilily reasons as the
above could be vwitten much mors neally using rhe lF..ELSE..ENDlF

lllcro

Peremeter!

A macro can lake parameters which can be used any,u/here in the macro

iu$ as (lh€y w€re sting 6quaies, i.e. prec€dsd by a backstash (\). Again it

there could b€ arry conlusion lh6 parameter c€n bs temrnaleo wilh another
backslash.
Ther€ can b€ up to thidy two param€i€rs, \O to\31 wiih \O being the size ot
lh€ macro,.e. rhe t€xl l6lrowirig th€ dol (.) any, when lhe mairo was
invoked-

Erample
1)
I Macro io increm€nl regisie.

lnc

addq.\o

#1,\1

endm

lnc
lnc.b
lnc.l

dl
d7

expandslo addq. #1d0
the assembler ignores the doi
expands to addq.b #1.d1
expands lo addq.w #1,d0
expands io addq.l#1,d7

:Macro!o branch il rsgisier notzero
BENz

ts1.w
bn€.\o

endm

BlaNz

BraNz.s

do,Exit
dT,Again

3)
I ll you €nclos€ an argurne in angte bEckets (<>) you can us6 spac€s and
r

6mm.ain

Format

macro

dc.b

13,13,'\1...,,0

endm

Foma
SHIFT and NABG

ll is oJten ussrullo have a macro which takes avaiabte number ol
parameleE. Th€ pr€delined NARG symbot and ihe SHtfT direciive a,e used
Io delsm:ne how many paramelerslhsre are and nep ihrough ihem Shirl
causes \1 io b€ losi and shrttslhe resto h€ parametarc dow-n so th€ \l
b€comos what \2 was etc

Example
;Macro to DC the given parameterc ait€r doubling them

DCtz

macrc

repl
dc.\o

nars

V'2

shilt
endr
endm

iiC,e.*

2,8,9 ;lhswords4,'16and lsareDC?

S€€ ihe descn ion of €xt€nded macro param€tors lor mors uses ol SHIFT
and NARG.

Named Macro P.ramel.ri
ll you prefer you can assign symbolic nam€s lo the macro paiamelers lo be

usd inslead

o, \1 10 \31.

Examplo

Scale

macro
dc.w

X.Y.Faclor

Uc\Faclor,\nFaclor

endm

Shorl ilacros
MACROS

Nomally controlslruclurcs musl be propedy n€sled wilhin macros. ll you
stait a slruclurc in a rnacro you musl inish il belore lhe ENDM and €qually
you canflot terrninale a structur€ thai you didn't stan in that macro.

You may occasionally when porling code from othsr assgmbl€ls, n€ed to
delins macros to imilate conl,ol struclures. Shon macros coniain only a
single line ol cods, bul this line can be a control structure direclive it you

Erelnples
r)
iMacro lo implementthe lFEo (il equals) conditjonal

if€q

i Nole: Short macros

macros

it
\1=0
donl have an ENDM
ileq
DebugMode
inair

2)
; Macro to implem€nt the IFNO

ifnd

Counl

(il not defioed) conditionat

macrcs

il
ifnd
dc.w

-del01)
Count
0

endil
Nol€
lf the,k command lin6 oplion is used lhe abovs macrcs are automaticatty
defined along with several others.

ErtEndcd Pel.meters
SNASM68K allows you to pass a list oi ilems €nctosed in cudy blackels (0)

lo a macro paramet€r.

The NARG symbol has been exlend€d so lhat it can repo( how many ilems
have been assigned lo a parameier and sim ady SHTFT can now be used

Exampla

Black
Green
Red

equ
€qu
€qu

0
1

; Macro which takes colourc and point lisls

;e.9.
; Black,{0,2,3},Green,{0,3,6,8},Red,12,4}
; and gen€ralos dala conlaining the colour,lhe counl
;

ol points and

th€n lhe point dala

;e.9.
;
i
I
:

dc.b Black
dc-b 3
dc.b 0,2,3
dc.b Green

clc.b

dc.b 0.3.6.8
: dc,b Red
:

tdc.b2
;dc.b 2,rl

PolygonLlsl

macro

Polygons\@ =
;

narcl2

Check narg was ev€n

if
inlorm

else
; Handle all polygons

points\@

rept
dc.b
=
dc.b
rept
dc.b
shifl

polygons\@'2onarg
2,'Bad parameter list
polygons\@
\1

narg(2)
points\@
poinls\@

\2
2

€ndr

shili
shin

dndr
endil
endm

;ovgonList Black,{0,2,3),creen,{0,3,6,8},Bed,{2,4}

The abov€ erample may look complex bul note how alllhe complexily is
hidden away inside the macro and how neat the main code took.
For compalibilily with olhsrassemblels il is possible lo equale a

symblto a

list ol paramelers using EOUS and use NARG and SHIFT on the stnng
equale €xactly as they werc used on lhe macro parameler above, This
,ealure allows the macro to accept lisls o, arg!menls using angle brackeis
instead of clrrly brackels.

Examplo
Delltems
Dav

t1)

rspt
dc.b
shift

nars(Day)
\Day,0

oay

deftems

<'Mon',Tue','wed,'Tiu','Fri','Sat','sun'>

Delllems

{'Mon','Tue','Wed','Thu','Fri','Sal','Sun'}

i normally we would hav€ used :-

C6nllnuatlon Lln.s
lf when you are invoking a macro, th€ lins becomesvery long, you can
lerminale th€ llne with a backslash N, and continue lhe list ol paramelers on

Erample
DoubleT

dc.w
Dou

bleT

\1'2,\2'2,\3'2,\4'2.\5',2.\6'2.\7'2
1 1 1 1 ,2222,3333,4444,5555,\
6666.7777

Label lmporrind
A macro can impoi th€ label on lhe line on which il was invoked and use it
iust like any olh€r parameler. The lab€l is not delined ro be al lhe current PC
as usually happens, in lact, unless the macro specilically assigns a value to
lhe symbol in some way il is undelined,
To l€ll SNASM6SK that you woutd tike to use tabet imponing you must
specily use astensk {') as ihe fiIsi named macro parameier, ihen you can
us€ \'to substitute lorthe label-

Example
;A Macro that assigns labels relativ€ to the slan ot a dala labte.
macro ',Dala
€qu
'.var8as€

repl
dc.\o
shift

narg(Dala)

\Daia
Data

endr

VarBass

equ

rc.w
rc.w
i;

|'1,2,3,41

{5,6,7,8}

va€ase{pc),a6

move.w

Ll(a6)d0

Advrnced lrecro Feetur.s
PtISHP and POPP

SNASM6SK l6ls you push some rerl and taler pop it into any sling vadabte.

Exampte
; DC

palam€lels in revorse oder

BackDC

; Push lhem all

macro

local

temp

repl
narc
pushp \f

ipush text contents ot\1

shii

€ndr

now pop and OC them

rept

popp
dc.\o

naru

lemp

; pop

lsxi pushed ea ier

Uemp

sndr
endm

i;ackDc.w

1,5,7,E

You are not restricted lo poping the parameler in lhe same macrc that
push€d it. Ihis allows some very ffexible maoos 1o be wdtt€n lo handte s€tireler€ncing data slructures.

nrnind numbers

into sttinos

The\*and \$ paEmeteB substilute the
50

decimat or hex vatue

ofa

symbol

inlo your cod€ al any polnl. They are used lo lum oumbers ido *nngs lor
lomattlng dala or blrildin€ arrays o, symbols.

Eral'lptet

1)
i PlJt lhe

(hta and llmo lnto a sldng

AsmDale
; oQands 10
AsmDate
2)

Colo
Coll
Col63
Col99
Index
lndex

lndex

clc.b 1#-dayl#_monlh^#Jea/

dc.b

'13/121989'

6qu
equ
equ
squ
=
dc.w
=
dc.w
=
dc.w
dc.w

$FFF

$FoF
SoFF
$FFo

CoA#lnd€x ;€xpanG lo Colo
1

Col\#lndex ;etpancls to Coll
99

Col\#lnd€x ; €xpands lo Col99
Col\$lnd€x ; €xpands to Col63

iThe words DCd will be $FFF,$F0F,$FF0 and $oFF.

Unloue Lab€ls

There is a special macro paEmeter \@ which expands lo an undeE@rc
lollowed by a d€cimal numb€r which increments upon sach macro
invocalion to guaranloe uniqueness.

Exemple

Delay
Loop\@

macrc

move.w

dbra

\2,Loop\@

€ndm

D€lay

\1.U

#3,d0

Each time lhe macrc is €xpand€d a dift€reni labelsuch as Loop_000 or

.
-

Loop_300 will ba generaled.

zuBGE
Macros can take up a larce amoudl of m€mory and sven though
SNASM6SK stor€s macros very €fticJenlly th€y might as w€llbe r€movsd if
lhey are no longer needed. The PURGE directive removes a macro lrom lhe
symboltable and fre€s up the memory ll was using.

Ex.mple

SigMacrc

mecro

iino'
;

Code that uses BigMaco

BigMacro

1,2,3

purge

BigMacro

; BigMacro now no long€r exists and can b€ rsdefrned if we wanl_

ll a macrc puEss itsolf, tho delinhion ollhe macro ls not rcmoved untilthe
macrc exits.

tl you jusl want to red€fine a macro lhere ls no nsed lo purge
when a new
derinilion ollhe macro is encounter€d th6 old macro is automatically purged,
A macro can, i, you really want, r€define its€ltl The new delinilion wilt be
eflectiv€ nexl lime lh€ macro is irvoked bul does not inter,erewiih the
expsnsion ol lhe currenl invocalion,

ExEmple

StranEs

Slrange

inlorm
macro
inlorm

o,'H€llo,
o,'GoodBye'

€ndm

$renge
€ndm

6i'"ns"
Strange
This will oulpul :.
H€llo

GoodBye
GoodBye

String Handllng
SNASM6SK provides some uselulsling handling funclions and directives
whlch arc used (usually in macros) lor comparing. searching and slicing
sldngs.

slEtE!
STRLEN is a lunction lhal can be us6d anyl here in an expression and
which relums the lsngth ih characl€G ol its stdng parameter.

ExahPle

; Macrc to DC stdng precsded by ils tenglh

Stdng

macrc

dc.b

strl€n01),\1

String

'H€rro'

strcmp(slringl,stringl)

6ndm

slEct P
Synta,

symbol

STRCMP is a lunction thal retuhs a boolean vatue (0 ror fatse,
which i6the result ol compaiing its two stdng paramel€rs.

-t lortrue)

Erampla

Language equs
-

'English'

;Assemble correct ddnk ordering sting according to curent language,

if
dc.b
else
il
dc.b
€lse
if
dc.b

slrcmp{lLang uag€ ,'Engtish')
'Two beers pleas€,,o

strcmp(\Language','Frsnch')
'Deux beksilvous plait',o
strcmp(\tanq0age,,,G6rman,)
'Zw€i bier biie',0

endif
endil

endit

INSIE

Synlax

symbol

lNt(lstad,lstnng,sub-sl

ng)

INSTR is used to s€arch a siing ro see it it contains a sub-stdng. tfthe sub,
string cannot be lound the rcsul is 2ero othelwjse il is the ofJset into the
stdng thal lhe sub-sting occu ed. Here as in all or ihe slring commands the

lirsl characlgr in lh€ sting is character nlmber

Erample
'lntemal iest version 0.9'
i S€i DebugMode

i;e veBion ging conlains

il
DebugMode else
DobugMode =

the word

l€st

instr(1velsion','test,)
-1

€ndi,

INSTR5 oplionallilsl pahmeter is rhe position from which to slart the

SUBSTF

Synlax

subslr

lsiart],lendl.slfi nE

SUBSTB rs s,mJarro EOUS in rrar I rs a way or doing a sinng equale
\owever allows lhe slan and end characl€.s olthe 5r.r9 io be specitied.

Example

equs 'What does lhis do?'
Templ
subst 6,9,1T€n$i
iTempl will equal'does (without lhe quot€s of couGe)
Temp2
substr ,4,\Te$$r
; Temp2 will equal What
T€mp3
subslr 6.,1Te$$i
TestSlr

; Temp3 will

equal does this do?'

Local Labels and Modules
Wh€n you ar€ writing a large program il becomes very hard to lhink oi an
inlormalive and uniquo name ior €ach label . Local labels help solve lhis
problem as lh€y only o(ist wilhin an area called rheir 'scope' and lhey can
be r€-used oulsid€ lhis ar€a. They ar€ mainly us€d within routines as 'place
ma*ers ,or shps and loop€ whor6lh€re is no ne€d for oth€r routines lo be
Local labels hav€ afl al sjgn (@) as lhei.lirsl chaBcler and lhis is lollow€d
by an valid label characlers.

Erampla
I These are all local lab€ls
@Lab€l

@L1

@123
SNASi,6SK has two ways of conlrolling the scope ol local labels. ln the lirst

ol these a loc€l label's scope extends belwsen lwo non'local labels.

Exampl6

tsl.w
bne-s
addq.w

lncNzD0

d0
@Nolnc
#1,d0

@Nolnc

lncNzDl

bne.s
addq.w

@Nolnc

#1dl

rls

@Nolnc

The local label @No lnc can be re-ussd as it's scop€ is between lncNzDo

and lncNzDl.
This iorm oi

scidng

is supported

lorcompatibiliiy r€asons and it is nol

MODULE and MODEND
SNASM6SK has anotherscoping system which can b€ ussd ireely wilh the
above scheme and which giv€slhe progEmmer much more crnlroloverthe
Code which is belween MODULE and MODEND directives is said lo
compiss a module, A local label delined in a modul€ cannot be relerenced
oulsde lhal module, and can be r€-used lr€ely. Equally .ny local labels
d€fin€d oulside lhe module cannol be r€Isr€ncsd within it.

Erample
CleaDala

module

@Loop

bsr
dbra

@Clearll
d1,@Loop

rls

@Clearn
@Loop

clr.b
dbra

(a0)+
d2,@Loop

rts

;end of @Clearll
;

A rclerence to @Loop would rcler lo lhe lirsl deiinition as we

: are back in the module ClearDala,

modend
i snd o, ClearDaia

A label js assumed lo b€ inside a modul€ if it is declared on any line alter the
IVIODULE direclive uplo and including the lin€ on which the MODEND

Orlslde modules ths'belween non-locals' scoping is in ,orce fui it is wonh
noling lhal a module is trealed lik€ a non'local and defallr scoping is
block€d by il.
s.g,

:This will nol wo* unl€ss it is all €nclosed in a mod]lle.

@Loop

movem.w

@SubModule

moaure

d7,1sp)

modend

movem.w

dbra

(sp)+,d7
d7,@Loop

The assemblsr willgivs an ermronlhe last line ofthe above example aslhe
DBFA is not within @Loop's scops.
Macro sxpansion has no ellect on the scoping oflocallabels, Any local
labels which exisls in a module can be relerenced wilhin a macrc expand€d
in lhal module. Ilyou wanl a macro lo have ils own locallabels you can
eitheruse a module wilhin the macro, use lhe\@ parameteroruse the

LOCAL dir€ciive described below
The use ol modules is sfongiy recommendsd as lhey serve 10 neatly

'€ncapsulate' roulioes and rigidly detine where lab€ls locallo roulines can
and canl be relerenced.

LOCAL
The LOCAL dircclive is anolher way oJ declring labsls within macrcs. Any
symbols d€dar€d wiih the local dir€clive can be Lrs€d as if they were norma
symbols but thsir scope is limt€d to ih€ cuned macro.

Erample

D6lay
Loop

fiacro

local Loop
move.w \1,\2
dbra \2,Loop
endm

Localdoes nol lype lhg symbols it dsfinss, You can go ahead and declare
them as lab€ls, le( equales or whal€ver you iik€,
e.g.

Demo

Slring,
Gravily
Skip

local
bra
equs
equ

Skip,Slngl,Glavily
Stip

\1\\2' ; Sting squaie

endn

iNumefic eqlate
;Label

Options
SNASM6SK has sovetal opiions which can b€ controlled either wtlhin ths
program or {rom lhe command line. See lhs s€ctiofl on command line
syntax lor iniormalion on selling assembler options on the command line.

AEI
The OPT dirsclivs is used lo set lhe state o, th6 assgmblers options trom
within the source code.

Assembler oplions:

AilIevialca

Descndion

Dcladl
On

olf
ofl
oll

ot
oit

oll
off

Optlmlsatlons:

otf

ofi
otf

olf

oll

osq

olt

Allemate numeiic lormat
Case sensilivily
Descope locals on equ and set
Ptint source lin€ whlch caused error
Use dol (.) instead ol al (@) for locals
Treat equated symbols like labels
Prinl wamings
Allow whit6 space in operands
Writ€ local labels to syrnbol tile
PC relativ€ oplimisation
Shod branch oplimisation
Absolule word oplimisation
Zsro displacem€nt opiirhisaiion
Add quac.k optimisation
SublBcl quick optimisalion
Move quick opiimisalion

Ex.mple
; Enable all oplimisations
;

opl
opt

o2+,os+,ow+
Turn otl aulo-ev€n and warnings
ae-,w-

Alternatively the /O swilch can be used lo sel lh6se opiions on lhe command
lin€, ss€ lhs eadiersection on command line syntar.
AE - Aulomatic Ev6n
Wh6n this option is enabled word length dala directivess force the program
counler lo lh€ nexl wod boLrndary belore ihey are execuled. This appties lo
lhe wod and long word lorms ol DC,DCB,DS and RS.

AN ' Altemale NumEdc
Enables use ol Zilog/lntel lom ol conslanls. Seethe seclion on FADTX ior a
full cl€scriplion ol this iacility.

C - Case Sensitiviiv
When this is enabledlhe case oilhe lellsE in e labetb nam€ becomes
imponad. For instance you could hav6 on€ tabet catted Biglabel and

anoth€r called biglabel.

Ai-Aeselr-Lacals
Oulside modules th€ EQIJ and SET dircctives do nor usuatty atiect the scope
ol local labels. Set this oplion il you wanl EOU and SET ro descope locats.
E - Erhr I ina Printind
When ih€ ass€mbler dolocis an eror il ls report€d atong with the tite nane
and lins numberwhere il occurcd. ll this opiion is enabtad the iext ot ihe tine
lhat caused lhe €rorwillalso be pnnted,
L-

Lm.! Lahel CheEcter

SNASM us€s ihe al sign 1@) as its delault toce! tab€l character. This option
changes lhis lo dol (.)
S - Tr€at aouates like labels
Wh€n lhis opiaon is €nabled lhe assembter treais e+rated symbots like
labels and wnles th6m lo ths symbollabte as such,

W'Give waminds
There are s€verallhings lhal even lhough lhey are nol errors are unusual
€nough ror il lo be wonh fie assembler repoding lh€m. tt you don,t wanr
warnings repodinE lh€n disable ihis ootion,
WS - Allow while soac6
Normally in 68000 source code comments lollow any while spac€ in lhe
operard fi€ld. This prevents th€ us€ ol iab and space to incr6ase code

readabihy io lne WS oplion has b€en added, which causes the assembt€r
ignore whils spac€ in operands and to insist on the use olserni-colon io

V - Wnte

loels

to rvmholtable

l, you wanl lo se€ local labels in lhe debugg€r then enabte lhrs opiion. To
keep lhe size ol the symboltable down you may prefsr to only tum on lhis
option lor rhe part ol lhe cods you are cunontty debugging.

OP - PC Ralaiive Oblimisation
Changes absoults long addressing lo PC rslalive addressing wherever
possibl€ and l€gal.
OS - Shorl Branch Ootimisalion
Backwards relalive branches that could uss th€ short form ev€n though you
hav€ not sp€cilied it ale used automatically if you snable this option.

O\l-

Absold€ Wod Ooilmlsatlon

ll you use lhe absolut€ long addrcssing mode and the address

wod the ass€mbl€r willuse the shoner mode

willf

anto

il lhis option is enabled.

OZ - Zem Disolec€menl Ootimlsation

lfyou us€ the addrcss register lndirect with displacement addiessjng mode
and ths displacem€nt is zero,lh6 ass€mbler will use the addr€ss r€gister
indir€ct mode ii thls opllon is €nabled.
OAO OSO and OMO Ouick lnsrrucrion Oorimisation

Tiis oplion caus€salladd, sub and
as lho quick

rohs to be coded

move instructions that coLtld be coded
as such. Only move.l is changed lo moveq

All ol lhe above optimisalions can only bg perlormed on backwad
PUSHO aod POPO

lfyou wantlochangethe setting olan oplion bi€tly andthen rerum ilto ils
previous value you can us€ PT SHO to save th€ cuir€nt state ot att the
options snd later us€ POPO lo relum lhem to th€ir pr€vious 9a1e.

Example
ByteSlream

opt
dc.b

ae-

;
;

sav€ slale ol options
lurn off auto even

3
456
512,80

p0po

i rsslor€

slale

Errors and Warnings
Erols

and wamings are generated by th€ assembl€r wh€n€v€r il detecls
anything wrong. SNASM provides a means lorlhe programmer lo aaise
enors if an €rorcondiiion occuls whicn lhe assembler can't detaci. i.e.. a
data table becoming too lae€.

INFOqM
INFORM can 9sn6rale snors of rour different sevenles and display
messages wilh emb€dded parameters to descrjbs the eiror in detail,

Syntat

lNFOBli

sevedly,stiingl,op€randsl

Sevedty is a number lrom 0lo 3 wh€r€ 0 causes lhe messageto be pinled
but no aciion taken, 1 gives awaming,2 giv€s an snorand 3 causes a falal
srror where assembly slops immediately.

lltha sldng conlains 7d, %h and./.s ih€s€ arc subdnqed with the decimat,
hex or sting valu€s ol lhe opsrands in ths order that they occur.

Erample

Slrucslan
SlrucEnd

Struclen

dc.w

equ
if
inloim
inlorm

SlrucEnd-Strucsiad
Struclen>1oz4
o,'Start=%hEnd=%h',Slrucstart,Struclen
2,'Sfucture loo long'

endil
EAIL

Fail is supporlsd ,or compatibilily and is the equivalenl ol

intorm

3,'Assemblyfailed'

I
I
I
I
I
I
I
I

Listings
It a lislino lile name is given on lhe command line or il one is set by delauli in
the SNASM6SK environmenl vaiable lhen lhe assembler $ill generate a
listing ollhe program dunng $e lirst pass.

ll.lk!d.!O!.ir
As lislings as usually used to check how macrcs are expaMed it is very rare
thal you willwahl the whole ot yourprcgram lisied. Usring is always on al
thestan ollhe program (ila lisling fle isspecilisd). Ths NOLIST directive is
used to lurn oii lisling gen€Elion whilsl lh€ LlsT dir€clive turns it backon
again.
Altematively you can uss the LIST directive wilh eilher plus (+)or minus (-)
as a pararn€l€r to tu rn listing mode on and off. The assembler has an
int€mal lisling slale which slans d 0 and lisling oulpr,.l is only gen€Ialed
when this vaiable is positive. LIST wilhout a paraneler sels lhis variable to
0, NOLISTSetS il to -1, L|STplus incEmenls it and LIST minus decr€m€nls
it.

Example
Not listed

NOLIST

islate=-l, no listing

LIST

Listed
LIST
Not listed

LIST

Nol listed

I
I
I
I
I
I

Listsd

LISI
LIST

+
+

slaie=o, lisiing

;slale=-1, no listing

isiaie='z, no lisling
istate=.1, no listing
tsiale=o, lisli'rg

Normally lhe assemblerlurns ofl lisling generaiion whenever il is expanding
a macro. l, you need lo see how your macros ars expanding use the /M
switch on ihe command lin€. Similarly code which is being ignorcd dle io

condilional assgrnbly does not go inio the listing unless lh€ /c swiich is used.

I
I
I
I
I
lr

I
I
I

I
I
I
I

Sections and Groups
lntroductlon to Sections and Groups
Seciions are used when you want parls ol your program thal are in dillerent
placss ln lhs source @de lo be placed n€{ to €ach other in memory. ll you
wanl all o, your varjables atthe botlom ol memory lollowed by stfing6
lollow€d by ereculabl€ code then you should be using sections.
Seclions ar€ also used when you want lo produce oulput in a machine

specilic r€localable iomat.

ln addition lo seclions SNASM supporls lhe concopt otgroups which are a
way of making sure c€rlain secllons arc togelh€r in memory and ol
assigning thsm vadous attibut€s.

Syntax
Declaring a gioup :.

GroupName GaOUP

lcroup Anributesl

ll a group has mulliple aflnbules th€y ar6 all listed aiterlhe group directiv€
separaied by commas.

Atdhde
oFx3
OBJ

stzE
BSS
WORD

FILE
OVER

Funciion
Specily address in memory al whlch to place group
Allows a whole group lo use assembly with otlsei
Speci,ies maximum si:e lor group
BSS groups do not conlain any initialised daia
Tells lhe assembler/linker thal a group can be absolule word
Used lo wile contenis o'agroup ro a binary Iie
Causes iwo or more goups lo $an al the sare aod ess in
memory

Opening a seciion :-

SECTION SectionNamel,GroupNamel
ll ihe group name is omitt€dthen ihe seclion willb€ placed in a delauft
unnamsd group unless lhe seclion has been previously assigned lo a
grorp. in whic'r cas6 lhalgroup will be used, lt is possible to wriie a prog.am
lhal doesni use groups at all bd aSS iyoe seciions witt nolbe avaitabte.
The SECIION direclivs can be optionally lollowed by a size specilying its
alignment. The defaull alignmenl is word which means that att parts ot ihe
seciion will slarl on a word bounda"y. ll a seclor s byie atigned ihe EVEN
direciive cannor be used wilhin ii. The CNOP directvo canioi be used to
align lhe PC to a largervalu€ lhan ihe alignmenl ol lh€ curent seciion_

t
I
I
I
I
I
I
t

I
t
I

t
I

Example u3ing sections and groups

AiB

So lhal vafables can be absolute word addressable ihey must be ai lhe stafi
olthe program. Ths vafiable are lo be lollowed by lwo sections conlaining

slings and one conlaining executable code, Uninitialised data is to rcside
in a seclion of its own above allihe oihers€ctionsCede

LowGroup
Codecrcup
Bsscroup
Slringcroup

group
group
group
group

bss

ors

$1000

;When using seclions only one ORG is allowed and it musl be belore
;

s€clion de,inilions

vaQ
Scratch
Temp

section
dc.w
dc.w
section
ds.w
ds.l
seciion.b

CRLF

Prompl
FaceList

dc.b
dc.b
seclion
ds.b

s€clion.b
Hello

dc.b
s€ciion
Iea

Dala,Lowcroup
2
89

Tables,Bsscrol]p
256
100
Slring 1 Slingc roup
13,10,0
,

>',0
Tables,Bsscroup
64

Sting2,Slingcroup
'welcome lo SNASM',o
Code,Codecroup

lvrslack,aT

nop

Goups are paced in mernory

in lhe order in which lhey arc declared wiih
sections placed within grcsps in the order in which lhey ar€ opened.

PUSHS and POPS
ll you need 10 lemporaily opsn a newseclion (in a macro lor inslancs), you
can use PUSHS lo save ihe current seclion, open a new secr on, and rhel
use POPS to reved lo the old sedbn

Example
i macro

lo place lhe cunenl Pc into a separale section

local

Temp

Temp
pushs

seclion

clc.l
pops

Marksection
Teinp

eadm

SECkIIIIEESEI
Th€ SECT lunction rslums the bsss ol th€ s€ction In which its F arameter is
dgfined, This cennol be evaluat€d until lhe end ol lh€ second pass it you
arcnl linking, and il you are linking il eannot be €valual€d unlil link iam€.
The OFFSETrunction returnslhs ofls€t olasymbolin its section, which can
always bs €valual€d on the iirst pass. lt you are linking OFFSET relums the
otlssl of the symbol lrom the bas€ ol th€ curent module's contdbution to lhe
sedion, so s€ct(x)+offsel(x) will not equal x. This has be6n done to allow
OFFSET lo b€ evaluat€d at assemble time, which is very ussrullorthings

like :-

oflse()&1
dc.b
'1
n

curonl PC is odd
add a minus one

; ll
;

6ndil

Note the use ol offsel(') lo gel oltset into s€ction oi clrent PC. ll you want
the rue oflsel inlo s€ction whilsl linking uso x-seciion(x).

Settind Group OAG'S
h is possible lo sei rhe ORG address ol a group totally independani,y ot the
acldresses ol lhe olh€r Eroups.

Exampl€
Code
Data
B9s

Debug

gr0up
group
group
gioup

Bss

ors($80000)

;Debug code 512K

The gmups without lhe org affibut€will be daced sequentatty al lhe acdrsss
given in lh6 oig dksctive as usual,

Ov.rlavlno droubr
ll ls pcsibl€ lo have severalgrouFrs staning atlhe same address using the
OVER attdbule. All of lhe groups will hav€ lhe same start address and
enough rcom willb€ lelt lorthe largest group.

Erampls
Overlayl
OJetlay2
O!erlay3

group
group
group

ove(Ovedayl)
ov6(Oveiay2)

Wrflno GrouE io Flleg
It is possible lo wfle grcups lo seperat€ purc binary liles whilst l€avjng the
other groups to be wdtt€n to ih€ nomal oulpul- This facility is us€d lor
overlay riles and loadeble data liles.

Examplo

Cod€
Dala
Ovgrlayl

Ovedayl b

Owday2

group
group

roup
group
roup
g
g

org ($80000),iil€('Oveday

.bin')

;This also goes inlo ovedayl.bin
orgl$80000),Jils('Ov€ilay2.bin')

Nol€ that all groups declared aller a group thal has a lile
writlen to lhis lil€.

atl bule are also

The FILE ett bde can b€ used in conjunction wilh the OVER attribute lo pul
ov€rleys into s€p€rata liles with the start addresses of the overlays att being

Mrchlne Sbeclflc nelocetable Formars

SI
Ifyou are using lhe liflkerto produce.TOS, .PRG or.TTP liles you should
dgclare the following groups.

Text
Dala
Bss

group
group

group

bss

Th€ order is not imponad aslhe llnker declarcs ihem implicilly.

llyou do not need to have multipls ssc.tions wilhin each group you can omit
lhe group dedaE ons and us€ lhe delaull group names lo identily the
Example

seclion

Text

ssciion
dc-w

move.w

*234.d0
Dala

ll yo do lhis you looselhe abilityto have mulliplg sections in each group and
the link€r has lo perlorm lhe ch€cls Jorinitialis€d data in BSS grcups.

A.ulcr
Ityou are using the linker to p,oduce an Amiga executable frle you should
declar€ the lollowing groups.
Code
Data
Bsa

Code_i
Daia_,
B,qg_,

Cod€_c
Data_c

Bss

grcup
group
group
group
9roup
9roup
group
group

group

bss

The order is not important eslhe linkerdeclares ihem implicitly.
lJ you do not nssd to hav€ multipl€ sections within each group you can omit
the group dedaralions and us€ the detault group names 1o identi, ihe

Example

Spriteo

seclion
trap
seclion
dc.w

Code
#0

Dala-c
34

l, yo do this you loos€ the abilitylo have mulliple seciions in eacn group and
the linker has to p€dorm th€ checks lorinitialised data in BSS groups.

Linking
SNLINK is a lully i€alured link€rwhich allows you lo writo your pogram in
s€v€rals€parate modules and then linklh€ss modulss together to produce
the final program.

Command

lln. svntrr

SNLINK /swilches source(s),outpulrile,symbollile,maplile,libra

Switches

/d
/e symb=value

Debug mod€ - do not run
Equate syrhbol

Un onsrnal symbols lo map lile
/o Numb€r
/o ?Number

Asklarcel lor memory lor org address

/r Fomat
/x Number

Produce pure binary oulpul
Produce machine speofic relocatable lile
Set exgcute address

Set org addr€ss

Relocatable lormats arecurenlly STfor.TOS liles orAM forAmiga hunk

SourcaFlla

Oulpulrll.
Symbolfll.

M.pFlle

Llbrarles

On€ or more source files (produced by lhe assembler)
separal€d by eitherspeces or plus signs {+) or th6 name ol a
link€r command lile oreceded by an at sign (@)
Fil€ b recsive objeci code o"'lpul. llthis is omtied ro objecl
code willbe generated, lJ you want lhe object code lo b€ sent
to a targel compuier use T?: as the obj€cllil€ where ? is rhe
SCS|device numb€r ol lne taroel.
Frle io r€ceive symbol labls inf;maiion tor debugge'.
File 1o receive map inlormation
Ubrary lileslo search

Linker command llles
Linker command files conla'n instruclions lhat tslt ih€ linkerwhich objecr
lil€s lo rcad, where lo orglh€m and inlohalion about groups, Thes€
inslructions have a v€ry similarfomallo lhe instruclions in the assembter tor

Th€ lollowing instructions can be used:j Comment

include
inclib
org
org
r€Es
group
seclion

Filename
Filename

; rcad objoct tite
:

search tibrary tite

AddI
OBG address ol prcgram
?sizel,lypel ;asr ia.get lor m€mory
pc=addr : sel €xecdion address
:

lanibules]

i define qroup

namel,groupl ;delin€s€ction
i

nove workspace on largel

Groups are plsc€d in memory in rhe oder in which they are dectar€d, it a
group is d€clar€d in lhe prcgram which is not declared in the command tite il
is placed on lhe €nd ofth€ defned groups.
S€clions within each group are placed in memory in lhe order in which they
are specilied, a seciion is Used in the prooram ilhich is noi doctared in lh;
clmmand lil€ it is placed on lhs €nd ofthe defined s€ctions in the
appropriate group.
Paris of a seclion flom difterent source lites are concat€naied in lhe ord€r in
which lh€ source liles are spocilied.
When groups are dsdared in yoursource @de lhere is no need to specily
any atdbules olh€rlhan WORD and BSS; att other aflributes are ign6red
wh6n linking. lf these affbutes are sp€ilied in the source they muat also b€
specitied rn lhe linker command lile aid vic€ verca.

Example llnker command file
;Command lile lor Amiga Widget sorler
include lnput.obi
include Softer.obj
include Olnpui.obj

org
regs
Lowcroup group
Codecroup qroup
Bsscroup group

section
section
seclion
section
seclion
seclion

1024
pc=Progsiarl
Word
Bss

Dalal,Lowcrcup
Dala2,Lowcroup

Codel,Codocroup
Code2.Codecroup
Tables.Bsscroup
BuffeB,BssGroup

The groups and soctions witt be in ihe tottowino order
:Start ol erecutablo at 1024

Lowcroup Dalal

Data2

Codecroup Codel
Code2

Bsscroup Tablss
Burrels
The sam€ group anibutes are allowed as lorlhe GROUP dkeclive in ihe
XDEF. XFEF and PUBLIC
When you arc linking s€v€ral modu es togethor you willwant io relerto
symbols d€l5ned in on€ module in difierent module. To do this you must
declare symbols as €xl€mal in the rnodule in which th€y are dgined using
XDEF, andlhen in th€ module in wlrich th€y ar€ us6d you musi use XREF to
lellthe assemblerlhal th€ symbolis in a dilferenl module. Any expression
ihal conlains an XREFU symbol will nol be tully evalualed by lhe ass€mbl€r
and will, instead, b€ resolved by the linker
You can lelllhe ass€mblsrthat a symbolcan be aocessed using absorLtg
word addressing by specilying lhe wod size on rhe XBEF directive.

Exsmple

XBEF and XDEF

Source modul€

ANOlher
Sourcd module 2

LargeTable

xrcl.w
xdsl
section
lea
molu

xdel
xrcl
ssctjon
ds.w
section
isr
isr

LargeTable
ABoutine,ANolher

Codel,Tsxl
LargeTabl€,ao
d0,d0

LaEeTabl€
ARoutine,ANoher
Tables,Bsscroup
100

Cod€l,Ten
ARoutine
ANOlher

l, you wanl to d€clare a large numberolsymbols as €xiernalyou can use the
PUBLIC direclive to l€llth6 assgmblerthat alt tunher symbots shoutd
aulomatlcally bo XDEF?.

Example

Speed
Dir€clion

public
dc.w
dc.w
pubtic

100

;No need to XDEFthis
;

orlhis

Libraries
A objeci module libraiy is a lil€ conteining sev€ral objecl modul€s. Thess
librai€s can b€ searched by lh€ link€r iJ it cannol find a symbol in the object
files. ll the linkerlinds thet lh€ enemal symbolii n€eds is derined in a library
module lhen lhe modul€ will be exlracled and linked wiln the objeci
modules.
SNLIB js a ulilily program lor creallng and mainlaining obj6cl module
libraries.

CaEEelll-lils-gller
SNLIB /swiich librarylile modules

switchos /a

/d
/u
fi
/

ldd

modulos to library
Delet€ modules lrcm library

Update modules in library
Extracl modLrles lrom library
List modul€s in library

lnst llhd

lh.

soltware

The SCSI Link

SCS|Unk is install€d eilher rrom rhe command lin6 ortrcm a batch rite
(usually auloexec.bat), and it must bs installed berore any olthe assembtsrs
or dsbuggers can be used.
SYNTAX:
SCSlUnk CardAddrl,D?l[,]?]
The address is whatever acldress you sel using linls 0-7 on the PC cad,

andlh€ numberafierthe D shoutd

lte

DMA channelyou ar€ using.

!t you havs lell lhe links as supplied jusl insen:-

SCSlLink 390,D1
l, no oMA channel is sp€cilied hardware DMA will ml be used and unless
you have a last cornpuigr dala llansmission speed will b3 r€ducsd,
Th€ I param€l€r is ussd to give the cad a diflerent SCSI devics numb€r
withoui opening lhe compulerand changing the links; this will nol usually be
necessary.

lnt.rfecE 16 scstLtt{K
The SCSlUnk software is acc€ssed using ini 7dh. AH is us€d to s€lecl the
required funclion as shown below.

AH=o Resel SCSI Bus
R€s€ls alldevic€s on lh€ SCSI bus

lnO!'

Eno,s

AH-1 Connect to taroet
Arbilral€s lor us€ o, bus and selecls larget.
AL=Target tD

tn
Errols

CF set i, €ror, Al=lniliator€rror, AH=Targel enor

AH=2 Send command
Sends lhe commend block to th€ target and

In
Oui
Enors

ES:BX. poinlerto parameter

pefoms and rclated l/O.
block shown below

CF ssl il enor, Al=lnitiaior eror, AH=Targ€t €nor

Pa,ameter block: (Allwilh 8086 byle ordering)
Size o, command
Dword
Ot s€t o, command
UIonC
Segmenl ol command
Word
Size ot
Dword
Ollset ol
Wod
S€gm€nl ol
Word

block
block
block
butler
butter
bufisr

Th€ conlenis of lhe command block which ar€ desc b€d late r have most
signilicanl byles and words iirctl

AH=3 Set Tim.Out
Change one ot SCSlUnk's intemaliimeouls lo allow communicalion with
very slow tarcBts.
AL=TimeOul Numb€r
BX=New value (55ms licks)
Out
Errors

Number Function

0
1
2
3

waillorbus
Tim€ to wait lor new phase
Max lime 10 sendreceive bloct
Tim6 to wail lor reselect
Timelo

Delault
18
5
18
180

AH=4 G€t Eror Stdng
Gel text 10 pdnl when an eroris reponed,
AL=Errcr number
Es:Bx=pointerio zero lerminaied sling

ln
Oul

Enors
AH=s Get A.Hr6ss
Get inlormation aboul current hardwarc conriguraiion.

lnOut

AL=Dma Channel, AH=lnitialor lD, BX=Card Addr

ErroE

AH=6 P'n Data
Save dala lor lai€r r€irieval. (Stored ln PSP ol SCStLink)
CX-By.l€ counl (1,256), ES:BX=Data lo sav€

ln
Errors

Out

CF set ll €rror, AL:1 Too muci data

AH=7-Ger-&E
Rslri€ve data stor€d using Funclion 6
Cx=8yls counl (1 -256), ES:BX=Butler lo ,ill
Oid
E.rors
CF sel il sror, AL=l Too much dala

AH=a Terminat6 *sion
lJ a program has mad€ any use ol thes€ link commands il should issue a
Teminate Session command as il sxils ev€n i, il is exiting due lo a SCSI
enor. This command exisls so lhal any soltware ihai iniercepls inl 7Dh
knows wh€n olher programs hav€ iinished with lh6 link.

AtE9-EaL-Bqt/ert

Whenev€ra program pedoms a GetR€gscommand and the exception ihai
has occur€d is nol ons lhal it spscilicelly handles il should perlom a Poll
Request calllo see il6ny driverthai has chained onlo int 7Dh handles il.
This service exists solhatlhlngs sLrch as resid€nl diskseN€6 can continue

to run €v€n whilsl dsbugg€B and prorilgrs arc running, The resid€nl driver
assu.nes lhal a connect has b€€n perlormed andkieslo leave the largei
AL-Targel lD

AL:-l

i, a resident diver handled event
AL=-2 il a residenl ddverexpeiencad a SCSIerrcr

Oul
Errors

SCSILINK CommEnd orotocol
The lollowinO is a lisl olthe commands cufi€nlly delined. Nol allol ihese
commands arc c{rrenlly suppoded - the Sendlmpl command lets you check
whal commands the soflwarg at the olhsr end suppons, some o, lhese
commands will only b€ handled by downloadsrs which leav6 lh€ machines
OS r€sidsnl, and lhese downloaders usually support some €xlra commands
lo suppot 1116 handling and muhi-lasking.
l, th€ top bit ol a command byle is set lhe larget will disco.nect
alter execuling the command and repo ng lhe slalus. This means lhe
soflware can suppoi up 1o128 commands.

Commands

0
1
2
3
4
5
6
7
8
9

EUer

Noop
Sendlmpl
S€ndlD

SendAddr
RecvAddr

2
2
2
2
10

FindRam 10
FlessN€Ram 10
Fr€oRam 10
ReBool 2
Makesale 2

10 Return 2
32 SsndMem l0

oata
ln
ln
ln

;
ln

;

Adi!tr
Do nothing except reporl stalus
Send binary array ol valid commands

S€nd rnachins/proc€ssor lD
Send slart and lengih ol link workspace
Change address of link workspace
Find how much memory is lroe
Ask OS lor some memory
Hand memory back to OS
Rebool iarget
Prepare lor Be-send
Relurn to OS
Send a block ol memory

33
34
35
40
41
48
68

RecvMem
VeritMem
Checksum
SendRegs
RecvRegs

GoPC

G€loSEr

1
1
1

2
2
2
2

0 Out
0 olrt
0ln

Roceive a block o, memory
Vedfy a block ol rnemory
Generat€ checkum ol a block o, memory

Send regisler block
Receivs regjster block
lnvoke cod€ at PC wilhoul rslum addr
Get result o, lasl OS funclion

orl

Format ot 2 bvte commends
Bde Function
0
1

Command byte
Modilier (sel to zero

unused)

Foriral ol 10 bvt. command3
ESe

Funclion

0
1

2-5
6-9

Modifier (set to zero ir unused)
Lenglh field
Addr€ss li€ld

commands ln deiall

N9!!
Command 0

Modilier

Functlon
Does nolhing, However lhis can be used lo discon nect lhe tarcet by seting
lhe lop bii as usual.

Se!.cfD.pI

Command I

Modilier

Oata-lra[slered
Ofisel
Binary
aray ol commands

terlll
16

Functlon
Targel sends 15 byle binary array indicaling which ol lhe 128 commands it
supporls. The data is bigondian so lh6 firsl byt€ is lor commands 127-120.

S.ndlD
Command 2

Modirier
Data

Transfered

Processor lD
Machine id

Ojjset
0
1?

Lenoth

12
12

Functlon
Taeel sends slfing giving proc€ssor and madin€ lD.

S!-o!A!-Cr
Command 3

Modifi€r

Transrered

Data

Funclion

Start of link memory
Lenglh ol link memory

OflSel telllh
4
0
4
4

Th€ link soltwere repods lhe address and lengrh of the block ol memory il is
using. lllhe link sofiwars doesnl use any ram rhe lengrh will b€ zerc.

RecvAddr

Command 4
Modifier
Length

Address

Data
New

New address lor link memory

Transfered
addross

OlGgf
0

Functlon

Causos link sotlwarc lo relocate ilselr.

L.nr'ih
4

lrlB

Command 5

Modilier
Length
Address
Data
Ram

0
Type ol BAM to reserve

Translered
fr6e

fiaqet sp€cific)

Ollsrt
0

Lenoth
4

Funcllon
Asks th€ targ€ts OS th€ size ot ihe largest block ol contiguous memory lhal il

can allocatg.

EeserveBam

Command 6

Modifier
knglh
Address

Data

o
Amount ol ram to reservs
Type ol BAM to r€s€lve OaBet specifc)

Transfered

Memory handle
Address ot ram

Oll$l
0
4

te!g$
4
4

Functlon
Target machine asks OS for ram and passes back a handls which will be
requir€d to lai€rlrce the memory andlhs base address ofih6 btock o,
memory.

Frr.Fam

Command 7

Moditi€r
Lengih
Address

0
Memory handle

Functlon
Hand m€mory back to OS

BeBoot

command 8

Modilier

Fu.cilon
Targ€t machine rebools and gogs lhrough normal bool piocess

UBkeSale
Command 9

Modili€r

Functton
Target machines puts the hardware into lh6 sarest conliguralion possible_
This usually involves disabling all DMA and int€rrupis, going out of potted
mode and lrssing any r€servecl ram.

Birlrr!
Command l0

Modirier

Funcllon
Target retums to OS

S!!!U!n
Commancl 32

Modifisr
Lenglh
Addross

0
Size of block in bytss
Address oJ block in taEet

Ollset

Dat. Tr.nsf.red

Stream of bytes

Taeetsencb a block ol

ram

Lerclb

lengih given in command

to initiator

Es.c.IlileE
Command 33

Modilier
Length
Address

0
Size of block in bytes
Address oi block in laEet

Data Transfered
Stream ol bytes

Ollsel
0

Functlon
TaEel receives a block o, ram ,rom initiator

Leldn

length given in command

V.rlfvil.m
Command 34

Modifi€r
L€ngth
Address
Daia

0
Size ol block in byt€s
Address ol block in targel

Transterod
of bytes

Stream

Oflsel
0

Length

length given in command

Functlon
Targel receives a block o{ ram lrom initiator bul just checks il
againsl current ravn conlents.

CheckSrm
Command 35

Modili€r
Length
Address

0
Siz€ ol block
Addr€ss ol block in taeet

Data Transfered
Additive checksum of bytes

OIlSgl tellfb
0
4

Funcllon
Talget adds logether allthe bytes in the delined lange and retums the long
word resuh

SendBeds
Command 40

ModiJi€r

Dala Translerad
Register block

Ollsel
082

Lenglh

Functlon
The targel sends ils copy ol ths 68000 registeE to the iniliator.

Regisler block lomat is :-

r€gdo
regdl
r€gd2
r€gd3
regd4
regds
regd6

ds.l
ds.l
ds.l
ds.l
ds.l
ds.l
ds.l

I
1
1
1
1

I
1

ds.l
ds.l
ds.l
ds.l
ds.l
ds.l
ds.l
ds.l
ds.l
ds.l

rcgd7
rsga0
regal
rega2
rega3

tega4
regaS

rega6
regssp
regusp
regpc

ds-l

regsr
ds.b

ds.b
ds.l

reginsl

1
1

Exc€ption typs (-1 =Sladup,
1=Runnins)
Exceplion lunclion code
Address thai caused eror
lnstruclion lhal caus€d €rror

Br.!.IBrcr
Command

Modifer

D2te Transfered
Regisl6r block

Ollsei
oa2

Ie-EdI

Funcllon
lnilialorsends nsw r€gjsler block to targel,
C-QEC

Command 48

Modirier

Funcllon
Targgt reslores all r€gisier from regisier block and iumps to PC

GelOSErr
Command 68

Modilier

Data TFnsfere.!
OS 6ffor code

Oitrst
04

Lelslh

Fu.cllon
Betums the enor code lorthe lasl OS iunclion lhe link softwarc

Using SnMake
SnMaks was designed lo allow Snasm and associalsd Cross Producls
soltware tools 10 be used from wilhin lhe Bdel editorwith lhe maximum ol
SnMak€ works on th€ lime honourcd mak€ ulility pfinciplo ot rcading a lile
suppli€d by lhe user in which are deiined the rclalionships belween lhe
targs(s) ihs user wishes to cr€at€ and lhe source liles from which thal iargei
is to be created. The target will b6 said 1o b6 d€pendant upon its so!rce tiles
which ers g€n€dcally known as dependencies. The iile in which thes€
r€lationships are detin€d is known as lhs 'mak€Jile', allhough in discussing
SnMake w€ shallalso refer lo them as'projecl liles as willbecome clearer
lat€r Once SnMake has r€ad this nle itdeterminps which largels hav€
dependanls nhich have been updaled since th€ largel lile was created, and
thus which largels musl be recreaied from their dependanls. SnMake
discoveG how lo recreale lhe targets from rules specifi€d in lhe makellls as
discussed b€low. SnMake has a number ol lealures thal allow ii to work in
clos€ conjunclion with Snasm and olher Crcss Pioducts development tools
bui which m€an il diflers lrom lhe more normal make ulillly synlax !n a

Snl\lake and Brlel
Cross Products have pmduc€d a numb€r ol macros rorthe Bdel edilorto
enhanc€ lh€ envilonm€nt lor th€ Snasm user. Some oi lhose macros
inlerlace ihe editor wilh SnMake and allow the user to invoke lhe utiliiy from
within lh6 €dilor. Nole lhal lhe new macros do away wiih lhe dialog-box
jnledace lo Snasm and any user wishing to use Snasm trom wilhin B €J
using the slandard macros will hav€ lo us6 SnMak€ as described below.
This is nol, howeve( acomplex matler.
The followjng descnplion assumes thatthe BieI macros are being used as
supplied, wilhout any reallocalion ol key-binclings.
The Snasm menu is invokedwithin Briel wilh the AllFg keys. The m€nu ilem
'S€lect Proj€ct File' will bring up a N/indow displaying all lhe liles in the
cunent direclory which have a '-pri' exlension. The tirsi line otthese liles is
displayed ro helplhe user rcmembgr whal luncuon lhey perlorm. Ths islhe
mandalory extension for liles to be used as SnMake makeiiles and will be
refened lo as project,iles in lh6 rcmainderollhis section. Should 8de, be
unabl€ lo find any prciecl tiles in the currenl direciory it will display a
msssage on the status line lo that eflect. SnMake can be invoked lrom the
command lin€ wilh the /p switch set (see below tordelails ol switches and
command line usage) in which case it will altempt lo append a'.pi'
sxl€nsionlo the mak€lile name it isgiven. ln lhis mode it is said to be in
'proiecl mod€'. When invokod rrom Biel SnMake is always;n pojecl mode.

Creallng prolecl llle3
Projecl liles musl cornain a lab€lbeginning in the tirsi cotumn otthe form:

ISnMake]
SnMake willignore any t6xt berore lhis labeland ii il iindslh6 €nd o, fil€
belore encounledng itwjllissue an 6rrcr and erit- Wrlhin Bfiellhis will resu[
in an errcr window appearing . Th€ s€arch lorthis lab€lis not case sensitive.
Once il has discovered this label SnMaks will regard eveMhing tottowing as
valid inpui untilil €ncounlers enolher'f in th. firdcotumn;rlhdend of tii'e.
Two olhervalid lab€ls are cunenty suDpoded: lDebugl end [Evar]. They onty
hava signlflcanc€ il the proj€ct lile is sereded wlhin Bnet. The lext nonblank llne lollowing lhe lDebug] label is d€€m€d to hold the Debugger
command line the userwishgs to have issued upon invoking the'Debug,
m€nu selection trcm lhe Snasm n6nu ( s€e 'Usang SNASM wilhin Brief ror
details on using th€ new Snasm macros wilhin Bi€l) and simitadyrorthe
line following lh€ lEval] label which invokes th€ exprsssion evatLiator ot the
ussrs choics. ln lhe case ol lhe IEvaI comnand rine 6 sp€cial loken SS$'
can be placed in the sldng and any ma*ed input witr be ptacsd in ihe siing

al lhal poinl.

Thus a simpl€ project lile might look as lollows:

----b€ginning oi iile

here------

projed lile lo assemble prog.68klo17:
lsnmakel
17a,

prog.68k
snasm6Sk $l prcg.68k,t7:,prog.sym

[D€bus]
snbug6Sk prog.syn
IEvall
snbug6Sk to$$$ prcg.sym

DefinlnO targeis.
SnMake r€gards anything srarting ln colurnn 0 and rerminated wilh a.;, as a
targsl d€daration. Thus:

targsll;
tgtl;
eihislgl;
are allvalid

laEsl

namos. White space ln tarcel dedaralions ls strlppod out.

Deflnlng dependencles.
Anylhing iollowing the ';' on the same line as a taEel decla€llon is regarded
as a dependencl declaralion. Multiple dgpendenciss are declared
separaled by whiie spaca and lin€ cutinualion (see b€low) can bs used.
The lollowing line:

largell.cp€; src1.68k src2.68k
declares that targetl .cp€ is d€p€ndani on src1 .60k and src2.68k and
SnMako will a empl to invok€ any rules defrnsd ,or larg€t1 .cpe il the
dalenime slamps ot €ilh€r srcl .68k or src2.68k snow them lo have been
updaled since targetl .cp€ was lasl cr€at€d,

speclal targets.
SnMake suppons a numberol spsciallarg€ls,

.lNlT;

any commands lollowjng lhis target dsclaration will always be
when thls prcject lile is executecl.

ca ied oul lirsl

.DONE;

any commands tollor dng thls target declaration will always be
carried out lasl when lhis prcloct lil€ is sxecut€d.

-lNlTand.DONE clo not have to be declared aslh€ lirst and last targels
within lhe makeiile, Snmake u/ill recognise th€m and rc-adjusi its lisi of
largels accodingly. .lNlT and .DONE will always be execlJl€d and should
nol be d€clar€d with depsndants.

l?:;

the larcels on lhe SCSI bus are recognised and wi,l always
cause th€ rul€s associal€d with il to be invoked. These largels should be

declared wilh d€p€nd€ncies.

l7::

src1.68k
snasm6Sk $l srcl.68k,17:

declares that src1.68k should be asssmbled down to SCSI raeel t7: . This
wiltoccur every time th€ projocl rils is exscuted. See secrion Speclal
Macros'lor th€ significance of'$l'in ihe command,
.RESOUFCE;
lhjs larget dedaralion should be lollowed by a lisl
ol programs lhat are able to utilise resource filss, ll musl be the iirst item
declared int lhe prol:ect ,il€ alt€r lhe lsnMakel label.

l, a command line lor one o,lhese prcghms exc€€ds 128 characl€rs in
lenglh, SnMake will splil it down into a temporary lile wiih each command
line aigum€nt plac€d on a now line and will callthe command with that iile
prsceded by an '@' charact€r. i,e.

lSnMak€l
BESOUCE;

lgt;

d€p1

somecmd depl .......... very long command line > 128chars

det€cling an overlong command lin€ SnMaks will create a temporary
r€source fi16 and call som€cmd as lollows:
som€cmd @lmpl .$$$

Deflnlng orpllcli

ru1e3.

Anything lollowing the end ol e laEel declaElion line is considered a rul€
dedalation. To be valld;a ru16 declaBlion must be ind€nt€d by at leasl one
space or lab. Blank lines lollowing a largel d€claralion arc ignored. More
than one command may tollow a gven largel, each stariing on a new lirc
and indenled as described above-

largell.obj; depl d€p2
snasm6Sk

dopl dep2,targsll .obi

delines a rule lelling snMak€ lhal illargell.objis yo!ngerlhan eitherdepl
or dop2 it should issus lhe comrhand

'snash68k,1 d€pl dsp2,largell.obj'

Deflnlng Impllclt

rul$.

ll SnMake cannol rind an explicil rute with which lo create a targ€t il will
atlempt lo do so by invoking any implicit rules delined in the prcjecl lile.
lmplicil rul€ delnnions musl begin in lhe flsl column and begin wilh a'.'
character SnMak€, on s€arching the list of implicii rules il has delined, looks
lor a rul€ that matches ihe exlension of lhe larget il is lrying 1o mak6. This is
the firsl portion of the implicil rule declaralion. Thuslo delin€ an implicii rule
thal SnMak€ will use lo d6al wilh any targets wilh a '.obj' €xtension rhe
lollowing is the required li6l pan or lhe dedararion:
.obj
having found liis SnMake will proce€d to atlsmpt lo fiatch lhe second pan
ol the declaralion; ihis is delimhed irom lhe ftrst part by a ',' characler thus:

.obj,.68k
this inloms SnMake thal any largets wilh a '.obj' extension are to be created
lrcm a depsndsncy oflh€ sam€ name but wilh a'.68k exlension. Th6

second part olthe declaralion fiusl bogin wilh a'.'characl€r, unlsss a path
nams is speciied as below:

.obi,e1€mp\.68k
This tells SnMak€ that any ta€els rvilh a '.obj' €xlension are lo be crealed
lrom a dep€nd€ncy oflhe same name bd wilh a'.68k extension in directory
e:lemP.

Dellnlng .ul€s tor lmpllcll iarg6t3.
The rule iollowing an lmpllcil target dorinition must be indenlsd by al least
one space or tab.
Two macrcs exist lo aid sp€cjlying implicil rul€s. These are $+ and $-. $+
signilieslh€ largel and $- its depndency. Thuslhe following impliol rule
.obj,.68k
snasm6Sk $+,$-

wh€n invoked upon target progl.obj will resull in ihe following command:

snasn$8k progl

.68k,prog 1.ob,

Points io note on using implicd rul€s.

a. Explicil ruleswillalways be used in prelerence lo implicit rules i,
explicil rules have been sel lor a givefl largel.
b. ll mor€ than on€ set ol implicil rules are delinecl lorthe same target
group,lhal implicil rule mosl rec€ntly d€lined (in lerms of position wirhin ihe
project lile)willbe invoked upon any suitabletaqels thus:
.obj,.68k
any suitableiargels in lhis areawillb€ cr€at€d irom files ofthe same
name with a
€xt€nsion,

"68k

.obj,el€mp\.68k

iollowing rhis new implicil rule delinition any suitabl€ targ€ts in lhis

arsawillbe crealed from liles ollhe same name wilh a '.68k' exiension in
dkectory e:lemp.

Macios.
Macros can be passed into SnMake lrom the command line using the /e
rilch as d€scrib€d below in the Command Line Options section. Within a
make/proiecllile the can b€ delined using the lollowing synlax:

maCiOl=SOm€nam€

macro dejinitions must begin inlhe fltsl column ollhe line. White space is
sldpp€d oul ol macro derinitions.

Wh€n delin€d macros ar€ rergrencgd they must be idenlified using the
,ollowing melhod

$(macroname)

_
_

thus giv6n lh6 abov6 macro d€linition $(macrol ) will €rpand to lomenam€',
'$'signs can b6 prot€cled lrom att€mpl6d macro expansion by the addition
ol the macrc syntax brcak€r'$. Thus $$20000 is passed though SnMake as
$20000.
The lollowing macro funclions allow th€ us€rto manipulat€ definod macrcs.
$e(macroflame) €xpands lo lhe extension oi macrcname,

maCrcnAme=t6st.Obj

$e(macroname) sxpands ro'.obj'
$n(macroname) expands lo onlylhe rilenams oflh€ macro dslinilion

macroname=6lesht€st.obj
$€(macronam€) expands 1o t€st.obl
$p(macronam€) €xpands lo the palhnam€ ofthe macrc delinilion

macroname=6lesl\lemp\lssl,obj
lo el€st\t€mp\'

$p(macroname) expands

$d(macroname) expands tolhs d vs nam€ oflhe macro delinition
macrcnam€=e16sl\lemp\len.obj
$d(macroname) expands to'e:'

$b(macroname) expands lo the lilename in th€ macro delinition
macroname=€ lesl\lemp\prog 1 .obj
$b(mecroneme) expands to'prog1'

Line contlnuetlon.

To conlinu€ a line without introducing a n€w1in€ character the 1'character
by a carriage return is used. Thus

lollgdialejy loliowed

lhistgl;
-

d€pl d€p2 dep3 d€p4 deps dep6 depT depS depg

dep10 depl1
declares depl lo dgp11 as dep€ndencies io rhisrgr. Wlhoul
maft SnMake would lruncale fte d€psndency lisr at depg.

lle conriuai'on

Commsnts.
A line on which lhe filst characl€r is a hash ma* will be regaded as a

Speclal macro3.
For use wilh Snasm and Snlink a spscial mac.o is provided by SnMake
which allows lh€ s9tting o,lhe I and /d switches on lhe command lines of
those programs.

The/i switch lo Snasm and Snlink lorces them to create an outpuwindow to
which they send lheiroulput whilsl running. This €nabl€s the user to watch
th€ir progress ,rom wirhin B.iei. This oplion is always s€l by the Bdsl macros
supplied by Cross Produc'ts.
The /d swilch to Snasm and Snlink lorceslhem inlo debug mode, ii aJile is
being assembled,'linked lo alarget machine il willnol be run ifthis switci is
set;thus allowing th€ us€rlo €nt€r the debugger belore execution of thal
csde starts. This option can be coniroll€d lrom lhe Bdel Snasm m€nu using
lhe 'Set Debug Mode' menu iism,

Conlrol of these switch€s is not possible lrom wilhin Bfel il the $l macro is
nol presenl on the Snasm6Sk and Sniinkcommand lin€s in lhe project lile

largl; depl dep2
snasmoSk S!

d€pl dsp2,taEl

assuming lhat debug mode is set lo 'ON! using ihe 'Set Debug Nlod€' oplion
Itom Bieflhis command willexpand io
snasmoSk

I depl

dep2 ,l,arg1

ln addilion lhs /d and ,,i swilchss sel up lwo macros, D€buqstr and lnlosr,
which can b€ t€st€d with the lilde, command as descdb€d betow.

Condlllonals.
A conditional capability is prcvjd€d within SnMake by the lildef command.
This allows the user lo delermine ila macro is derin€d and act upon that
inlonnation. Thus in lhe lollowng case:

l7:t

prog1.68k

snasmoSk $! prog1.68k,t7:,prog1.sym
liJdsl(D€bugstr)

snbug6Sk prcg1.sym
il ihe special macro 'oebugsti is s€l i e. debug mode is on, the debugger

willb€ invoked every lime SnMak€ is
87

'Noked

with lh's proteci lite.

The l€ndilclmmand is rcquired lo l€lminale lh6 lildel call. Il SnMake
reaches lie end of th€ projscl lil€ with an unbalanced numb€r o, calls to
liidel and lendif an erorwillr€sult.
An lelse stalemenl is also supporled as shown below:

!idsl(Debugstr)

t7:;

17:;

progl.68k

snasm6Sk $l prc91 .68k,17:,prog 1.sym
snbug6Sk progl.sym
prog1.68k
snasm6Sk prcg1.68k,r7:

This example perlorns lhe same task as the previous one in asliglrtly more
rou.d-aboul manner.

lnvoklng Snlttako from th6 command llno
Th6 syntax lor calling SnMake lrom lhe command line is aslollows:
snmake
all arguments on the command line are oplional. lnvoking SnMake wnh no
argum€nls callrses it lo look lora makeiile called 'makefile' and process thal.
The opiional parameler specilies an alternalive makelile name. lf
is speci,i€d all€rroi inrormalion will be oulpul to lhal lile.
Switchss

SnMake ac.epis live swilches lrom the command line.

/q
/p

Oui€t mod€. No echoing is done as SnMak€ prcceeds.
Proj€ct mode. This lorces SnMake lo treal mak€liles as prcjecl liles
i.e. as il invoked lrom within Bnef. ll no makerile name is specili€d
SnMake will detaull lo maketile.pi. ln project mode all oulput from
SnMake goes io a file call€d snmk.€r, any ermroulpul lromlhe
programs invoked by Snlvlak€ will appear on-sceen unless an error
Jile is specilied.

/d
,,i
/9
,D

Set debug mod6. S€ls the specjal macro $1. Only ol use i, invoking
snasm or snlink lrom ihe makelile,
S6t into mode, As above.

Pass a macro delinilion lnto SnMake. Synlax /enam€=Frcd.
This would sel up a macro name which would expandlo Fred.
Build all. All rules carried oul regadless .

Exampl6s:
The lollowing example is a projecl liles lhat will prcduce a Jile called
lesll .cpe lrom ih€ sourcs liles e |srcl .68k e:src2.68k . Iert in this style is
cofifient text a&ecl to aid the reader and is not pan ol he SnMake syntax.

-------------Ptuier,
,ile io create

tssrl.cpe

fhis

Snnake in pmject nade stais rcading at

tSnMakel

this label

srcl.obt;

esrc1.68k

5nasm68k $l

src2.obj

/z e:src1.68Lslc1.obi,src1.sym

e:src2.68k

snasm6Sk $l

lesll.cps
snlink

will appeat in the projec! file

/z €:src2.60k,src2-obi,src2-sym

srcl.obj src2.obj
lesll .cpe

src1 .obj src2.obi,

lD€bugl

Snbug68k src1.sym

src2.sym

SnMake stops rcacling hercDebugget is invoked using this

sfing
lEvall

Snbug6Sk V$$$ srcl.sym

-------End

ol project

src2.sym

frle--------

Exptessbn evaluatot is
invoked with this shng

Other Utilities
Sncopy
Tl'rs uiihy is a vadanr on ihe copy command in lhal ii wilt ontv @ov thosa
source fles ihat have been more r€cenity wdfl€n ihan anyta;letiries il tinos
ol lhe same name

li haslhe tollowing command tine syntax:
sncopy source1+source2+.... la€et direclory
wh€re swilches arel
/a - r€lr6sh atti rsg-sdtess oJ retative ages (retresh AI rhode).
/q - do nol echo afier retresh (Outet hode).

sncopy f le1.68k+tit€2.68k c:\source
would caus€ sncopy lo ssarch in d,reclory c:\sourcs tor tites named
Illel.68k and lile2.68k and compare therr tim€ and dale stamps (iiihe
files exisl)lo those ollhsliles ot the sans name in the currerit
drrectrcry. tflhe tit€s in th€ current directory are newerltlan those in
c:\source orfites onhe same name do not exrst in c:\60urce a copy wifl
ln the lottowing case, due lo the uss ot ihe /q and /a swiiches alt tites
are copied and no echoing is done to lhs screen.

sncopy /q/a

,ite 1.68k+rite2.68k

c:hourc€

Sncopy supports wildcard paflerns:
sncopy '.68k d:\src

will copy att fl€ ending in the ,.68k enension tflo lhe drrectorv d.\src i,
no younger lile ot lhs same name is tound resioing lhere. '

Slcopy will be of mosl use lo those who keep copies ot source liles on a
rast d€vice, such as a ram dtst(, whitst lhey wdrk o'n rhem and wil thus
oenem Dy usrng a copy program ihal wil nol alow the accidental coovind ot
or0 source lites over thos€ ihsl have b€€n more recen y updaied. ' ' -

lndex
\$ 50

\'49

\@ 51
27
-RS 28
_DAY

.HOURS 28

_MINUTES 28
_MONTH 28
_SECONOS 28
_WEEKDAY 28
YEAR 28
ALIAS 22
CASE 41
cNoP 33

MODULE 55
NARG 45
NOLTST 62
OBJ 34
OB.JEND 34
OFFSET 65
OPT 58
ORG 33
POPO 60
POPP 50

POPS 64
PUBLIC 70
PUBGE 51

PUSHO 60
PUSHP 50
PUSHS 64

DATA 31

BADIX 20

DATASIZE 3I
DC 30
DCB 30

REF36

DEF36

aEPr 42

OISABLE 22
DO 43

RS 27

ELSE 39
ELSEIF 39
ENO 39
ENOCASE 41

sEcT 65

os 32

ENDIF39
ENDM 44

REG 29
REGS 38

BSBESET2T
RSSET 27
SET 24
SHIFT 45
STRCMP 53
SIRLEN 53
SUBSTR 54

ENDB 42
ENOW 42

TYPE 36

EOU 24
EOUR 28

WHILE 42

EOUS 25
EVEN 33

FAIL6l
FILESIZE 36
HEX 31
lF 39

lNcBtN 35
INCLUDE 35
INFOBM6l
INSTR 53

LtsT 62
LOCAL 57
MACRO 44

MACROS 46
MEXIT 44
MODEND 55

UNTIL43
WORKSPACE 38
XDEFTO
XREFTO

mo,.rozJa
Source Exif Data:
File Type : PDF
File Type Extension : pdf
MIME Type : application/pdf
PDF Version : 1.3
Linearized : No
Page Count : 95

EXIF Metadata provided by EXIF.tools

SNASM68K 68000 Cross Assembler System Manual

Navigation menu

Versions of this User Manual:

Views

Navigation