home *** CD-ROM | disk | FTP | other *** search
/ CBM Funet Archive / cbm-funet-archive-2003.iso / cbm / c128 / programming / d-ass.txt < prev    next >
Text File  |  1998-03-15  |  22KB  |  725 lines
  1. double-ass
  2. ==========
  3.  
  4. sOURCE: 128ER sh 22, mARKT & tECHNIK vERLAG, gERMANY
  5.  
  6. aUTHOR: rENE VAN bELZEN
  7. E-MAIL: HURRAY@XS4ALL.NL
  8. WWW   : HTTP://WWW.XS4ALL.NL/{$7e}HURRAY/CBM/
  9.  
  10.  
  11. bRIEF DESCRIPTION
  12. ----- -----------
  13.  
  14. wITH THIS 2-PASS ASSEMBLER YOU CAN CODE AS WELL FOR THE 8502
  15. MICROPROCESSOR AS FOR THE z-80 MICROPROCESSOR. bOTH PROCESSORS ARE
  16. PRESENT IN THAT WONDERFUL MACHINE, THE cbm-128.
  17.  
  18. tHIS DOCUMENT DESCRIBES HOW TO USE THE dOUBLE-aSS ASSEMBLER, BUT
  19. DOESN'T TEACH HOW TO CREATE CORRECT MACHINE LANGUAGE PROGRAMS. iT
  20. ASSUMES YOU HAVE EXPERIENCE WITH THE BUILT-IN mONITOR OF THE 128-MODE.
  21. hOWEVER, THIS DOCUMENT CONTAINS SOME CLUES ON HOW TO CODE IN ASSEMBLY
  22. LANGUAGE.
  23.  
  24.  
  25. iNTRODUCTION
  26. ------------
  27.  
  28. tHE 8502 NORMALLY RUNS ONLY IN cbm-64 AND IN cbm-128 MODE, AND THE z-80
  29. ONLY IN cp/m MODE. tHERE IS NO REASON WHY THE z-80 SHOULDN'T RUN IN THE
  30. 128 MODE TOO, SO IT DOES WHEN YOU TELL IT TO. uSING A TRICK, THAT IS
  31. EXPLAINED LATER, YOU CAN SWITCH BETWEEN PROCESSORS. yOU ACTIVATE THE
  32. ONE, WHILE THE OTHER IS SILENCED. wHEN 'SWITCHED BACK' THE 8502 RUNS
  33. HAPPILY ON LIKE IT EVEN NEVER HAD STOPPED AT ALL.
  34.  
  35. sO FAR SO GOOD, BUT A PITFALL IS THE LACK OF A SOLID USER INTERFACE IN
  36. THE 128-MODE FOR THE z-80. iN rom ONLY THE MOST NECESSARY ROUTINES TO
  37. START cp/m AND RESTART c=128 MODE ARE AVAILABEL. nOTHING LIKE THE 128
  38. ml-mONITOR HERE.
  39.  
  40. sO, WHEN PROGRAMMING THE z-80 IT MAKES ONLY SENSE TO PRODUCE SHORT
  41. ROUTINES YOU CAN peek() INTO MEMORY WITH A basic PROGRAM. wITH dOUBLE-aSS 
  42. ALL THAT HAS CHANGED. nOW YOU CAN DESIGN YOUR OWN z-80 ROUTINES,
  43. ALONG WITH 8502 ROUTINES. yOU CAN USE THE BLOCK TRANSFER POWER OF THE
  44. z-80 ALONG WITH THE kERNEL ROUTINES OF THE 8502.
  45.  
  46. tHE PROGRAM dOUBLE-aSS IS 9 kBYTES IN LENGTH AND IS LOCATED IN ram BANK
  47. 1, AND CAN NOT BE OVERWRITTEN BY basic SOURCE CODE. iT IS ALSO POSSIBLE
  48. TO PLACE THE SOFTWARE ON eprom, SO THAT IT'S PERMANENTLY AVAILABLE.
  49. tHIS OPTION WILL NOT BE COVERED HERE, HOWEVER.
  50.  
  51. btw, THE MACHINE CODES FOR THE 6502, 6510 (c=64), AND 8502 (c=128) ARE
  52. EXACTLY THE SAME. tHE ONLY DIFFERENCE SEEMS TO LAY IN THE INTERNAL LAY-OUT
  53. AND PROCESSING OF THE DATA (AND OF COURSE IN THE OPTIONAL 2 mHZ cpu
  54. CLOCK SPEED OF THE 8502).
  55.  
  56.  
  57. lOADING AND RUNNING THE PROGRAM
  58. ------- --- ------- --- -------
  59.  
  60. tO LOAD THE PROGRAM TYPE THE FOLLOWING LINES (EACH LINE ACTIVATED BY
  61. PRESSING THE <return>-KEY):
  62. dload "double-ass"
  63. run
  64.  
  65. aFTER A RESET, THE ASSEMBLER CAN BE RE-INSTALLED BY THE FOLLOWING LINE
  66. (AGAIN, ACTIVATE THE LINE BY PRESSING ON THE <return>-KEY):
  67. bank 1 : sys 5376
  68.  
  69.  
  70. oPERATING THE DOUBLE ASSEMBLER
  71. --------- --- ------ ---------
  72.  
  73. dOUBLE-aSS IS A FULL FEATURED ASSEMBLER THAT LEANS HEAVILY ON bASIC
  74. 7.0. sO YOU CAN STILL USE COMMANDS YOU KNOW AS A basic
  75. PROGRAMMER/OPERATOR. fURTHERMORE YOU WILL FIND THE FOLLOWING COMMANDS:
  76.  
  77.  
  78. 1. find(STRING)
  79.  
  80. tHIS COMMAND LISTS ALL PROGRAM LINES IN THE SOURCE CODE IN WHICH THE
  81. TEXT STRING OCCURS. tHERE ARE NO SPACES ALLOWED IN THE find STRING
  82. (EVEN NOT BETWEEN 'find' AND THE STRING).
  83.  
  84. eXAMPLES:
  85.  
  86. (NOTE: IN THIS DOCUMENT THE COMMANDS BETWEEN '<' AND '>' ARE KEYBOARD
  87. ENTRIES, E.G. <return> MEANS YOU HAVE TO PRESS THE rETURN BUTTON ON THE
  88. KEYBOARD)
  89.  
  90. fIND THE LINES WITH THE WORD 'labels' IN IT.
  91. --------------------------------------
  92. findlabels<return>
  93. 1010 ;labels
  94.  
  95. ready.
  96. ---------------------------------------
  97.  
  98. fIND THE LINES WITH THE WORD 'buffer' IN IT.
  99. ---------------------------------------
  100. findbuffer<return>
  101. 1020 buffer = $0c00
  102. 2030 lda buffer, x
  103. 3050 sta buffer, x
  104. 4000 ;the buffer is empty
  105.  
  106. ready.
  107. ---------------------------------------
  108.  
  109.  
  110. 2. merge "file name", unit
  111.  
  112. tHIS COMMAND LOADS THE FILE THAT IS SPECIFIED BY "file name" UNDER
  113. (AFTER) THE SOURCE CODE THAT WAS ALREADY PRESENT IN MEMORY. iF YOU WANT
  114. THE LINE NUMBERS APPEAR IN THE CORRECT ORDER, USE renumber TO RE-LINK
  115. THE LINES
  116.  
  117. e.G. SUPPOSE THE LINE NUMBERS IN THE OLD FILE RUN FROM 10 TILL 250. aND
  118. SUPPOSE THOSE IN THE MERGE FILE RUN FROM 100 TILL 300. aFTER MERGING
  119. THE LINE NUMBERING WILL BE 10, 20, ... 250, 100, 110, ... 300. aFTER
  120. "renumber 10,10" THE LINE NUMBERING WILL BE 10,20,...,460.
  121.  
  122. tHE SYNTAX OF MERGE IS SIMILAR TO THAT OF load (c=64 basic 2.0
  123. COMMAND).
  124.  
  125. eXAMPLES:
  126.  
  127. mERGE THE FILE "second.src" FROM UNIT 8, AND RENUMBER THE LINES FROM
  128. 1000 AND UPWARDS, WITH AN INCREMENT OF 10.
  129. ---------------------------------------
  130. merge "second.src", 8<return>
  131.  
  132. renumber 1000, 10<return>
  133. ---------------------------------------
  134.  
  135. mERGE THE FILE "game.src" FROM UNIT 1 (dATASETTE), AND RENUMBER THE
  136. LINES (10, 20, ...)
  137. ---------------------------------------
  138. merge "game.src", 1<return>
  139.  
  140. renumber<return>
  141. ---------------------------------------
  142.  
  143.  
  144. tHE PRINCIPLES OF 2-PASS ASSEMBLY
  145. --- ---------- -- ------ --------
  146.  
  147. dOUBLE-aSS IS AN 2-PASS ASSEMBLER. tHIS MEANS THAT TWO STEPS TAKE
  148. PLACE:
  149.  
  150. step 1. cALCULATION OF THE SO CALLED "SYMBOL TABLE". iN THIS TABLE ALL
  151. LABELS ARE CALCULATED INTO 16 BIT VALUES. tHOSE VALUES ARE DERIVED FROM
  152. THE LABEL DECLARATIONS IN THE SOURCE CODE. iN GENERAL A LABEL
  153. REPRESENTS A MEMORY LOCATION.
  154.  
  155. step 2. cOMBINING OF THE SOURCE CODE AND THE SYMBOL TABLE INTO AN
  156. OBJECT CODE (MACHINE LANGUAGE).
  157.  
  158.  
  159. hOW TO MAKE SOURCE CODE
  160. --- -- ---- ------ ----
  161.  
  162. tHE ASSEMBLY SOURCE CODE IS TYPED IN LINES, JUST LIKE basic PROGRAMS.
  163. tHE LINES ARE STORED TEMPORARY IN MEMORY, AND CAN BE SAVED JUST AS ANY
  164. OTHER bASIC PROGRAM LISTING.
  165.  
  166. dOUBLE-aSS KNOWS IF IT IS DISPLAYED IN 40 OR 80 COLUMNS MODE, AND
  167. ADJUSTS THE LAY-OUT ACCORDINGLY.
  168.  
  169. iN THE LINES YOU CAN FIND TWO TYPES OF SYMBOLIC CODING:
  170. 1. PROCESSOR OPCODES (8502 OR z-80)
  171. 2. PSEUDO OPCODES (DIRECTIONS FOR THE ASSEMBLY)
  172.  
  173. btw: oPCODE STANDS FOR 'OPERATION CODE'.
  174.  
  175. tHE PSEUDO OPCODE TECHNIQUE PROVIDES THE PROGRAMMER WITH WAYS TO DESIGN
  176. HIS PROGRAMS IN A FLEXIBLE WAY. nOTHING IS SOLID AND CONCRETE AT THE
  177. CODING STAGE. hE CAN PLAY AROUND WITH DIFFERENT STRATEGIES, WITHOUT
  178. BEING BOTHERED WITH THE LEVEL OF DETAIL THE MICROPROCESSOR INSISTS ON.
  179. wHEN THE MOST EFFICIENT STRATEGY IS FOUND HE CAN ASSEMBLE THE SOURCE
  180. CODE TO MACHINE EXECUTABLE OBJECT CODE, AND TEST THE PROGRAM.
  181.  
  182. tHE MOST COMMON USE OF PSEUDO OPCODING IS LABELING (THE OTHER PSEUDOS
  183. ARE DISCUSSED BELOW), WHICH WILL BE DISCUSSED IN DETAIL NOW.
  184.  
  185.  
  186. lABELS
  187. ------
  188.  
  189. a LABEL IS A BIT LIKE VARIABLES IN THE basic INTERPRETER. basic CAN
  190. DISTINGUISH BETWEEN THE 2 FIRST CHARACTERS, dOUBLE-aSS BETWEEN THE
  191. FIRST 40 CHARACTERS. tHE FIRST LETTER HAS TO BE A LETTER OF THE
  192. ALPHABET (A, B, ... Z), THE OTHERS MAY BE LETTERS OR FIGURES. nOTE THAT
  193. YOU CAN ONLY USE UNDERCAST LETTERS, NO CAPITAL LETTERS.
  194.  
  195. mANY ASSEMBLERS USE A MAXIMUM OF 6 CHARACTERS FOR A LABEL. tO ENSURE
  196. PORTABILITY, YOU MIGHT CONSIDER LIMITTING YOUR LABELS TO THAT MAXIMUM
  197. OF 6 CHARACTERS.
  198.  
  199. lABELS CAN BE USED IN DIFFERENT WAYS:
  200.  
  201. 1. dEFINITIONS
  202. tHE LABEL GETS AN EXPLICIT VALUE.
  203.  
  204. eXAMPLE:
  205.  
  206. aSSIGN THE VALUE $d600 TO THE LABEL vdcreg.
  207. ---------------------------------------
  208. vdcreg = $d600
  209. ---------------------------------------
  210.  
  211. 2. rEDEFINITIONS
  212. tHE LABEL GETS A NEW EXPLICIT VALUE.
  213.  
  214. eXAMPLE:
  215. iNCREMENT THE ORIGINAL VALUE BY 1, WITHOUT INTRODUCING A NEW LABEL
  216. (NOTE THE DOUBLE '==', INSTEAD OF THE SINGLE '=' OF THE DEFINITION).
  217. ---------------------------------------
  218. vdcreg == vdcreg + 1
  219. ---------------------------------------
  220.  
  221. 3. vALUE OF THE PROGRAM COUNTER
  222. tHE MICROPROCESSOR KEEPS TRACK OF WHICH OPCODE TO PERFORM NEXT IN A
  223. SPECIAL REGISTER, THE PROGRAM COUNTER. tHE NOTATION OF THIS PROGRAM
  224. COUNTER IS AN ASTERIX '*'.
  225.  
  226. eXAMPLE:
  227. aSSIGN THE VALUE OF THE PROGRAM COUNTER TO THE LABEL prgcnt.
  228. ---------------------------------------
  229. prgcnt = *
  230. ---------------------------------------
  231.  
  232. nOTE: ALTERNATIVE NOTATIONS FOR THE ABOBE EXPRESSION ARE:
  233. ---------------------------------------
  234. prgcnt
  235. prgcnt:
  236. ---------------------------------------
  237.  
  238.  
  239. 4. iMPLICIT DEFINITIONS
  240. tHE LABEL IS ASSIGNED A VALUE IN RELATION TO THE POSITION IN THE SOURCE
  241. LIST.
  242.  
  243. eXAMPLE:
  244. dEFINE THE START ADDRES OF THE OBJECT CODE (EXECUTABLE MACHINE
  245. LANGUAGE).
  246. ---------------------------------------
  247. *= $0b00
  248. ---------------------------------------
  249. mIND YOU, DON'T PLACE A SPACE BETWEEN '*' AND '='!
  250.  
  251. nOTE: SOME ASSEMBLERS HAVE A SPECIFIC WAY TO DEFINE THE START OF THE
  252. OBJECT CODE, NAMELY:
  253. ---------------------------------------
  254. .org = $0b00
  255. ---------------------------------------
  256. dOUBLE-aSS DOESN'T RECOGNIZE THIS PSEUDOCODE. iF YOU ARE USING SOURCE
  257. CODE LISTINGS MADE WITH OTHER ASSEMBLERS, PLEASE REPLACE THE EXPRESSION
  258. '.org' WITH '*='.
  259.  
  260.  
  261. pROCESSOR OPCODES
  262. --------- -------
  263.  
  264. tHESE COMMANDS WILL BE TRANSFERED TO THE MACHINE LANGUAGE PROGRAM
  265. DURING ASSEMBLY. tHEY ARE THE EXECUTABLE COMMANDS. iF YOU WANT TO LEARN
  266. USING THEM, i SUGGEST YOU READ A GOOD BOOK ON EITHER PROCESSOR, OR SCAN
  267. THE iNTERNET FOR USEFUL DOCUMENTS.
  268.  
  269. 8502 OPCODES
  270. ---------------------------------------
  271. adc and asl bit bpl bmi bvc bvs
  272. bcc bcs bne beq cmp cpx cpy dec
  273. eor inc jmp jsr lda ldx ldy lsr
  274. nop ora pha php pla plp rti rts
  275. rol ror sbc sec sed sei tax tay
  276. tsx txa txs tya sta stx sty
  277. ---------------------------------------
  278.  
  279. z-80 oPCODES
  280. ---------------------------------------
  281. adc  add  and  bit  call ccf  cp
  282. cpd  cpdr cpi  cpir cpl  daa  dec
  283. di   djnz ei   ex   exx  halt im
  284. in   inc  ind  indr ini  inir jp
  285. jr   ld   ldd  lddr ldi  ldir neg
  286. nop  or   otdr otir out  outd outi
  287. pop  push res  ret  reti retn rl
  288. rla  rlc  rlca rld  rr   rra  rrc
  289. rrca rrd  rst  sbc  scf  set  sla
  290. sra  srl  sub  xor
  291. ---------------------------------------
  292.  
  293.  
  294. pARAMETERS
  295. ----------
  296.  
  297. pARAMETERS CAN BE CONSIDERED AS THE DATA WHERE UPON THE (PSEUDO) OPCODE
  298. OPERATES. tHEY MAY CONSIST OF CONSTANTS AND LABELS, AND A COMBINATION
  299. OF THESE TWO.
  300.  
  301. cONSTANTS ARE NOTED IN THE FOLLOWING WAYS:
  302. $31de              HEXADECIMAL
  303. 6590               DECIMAL
  304. %11 0001 1011 1110 BINARY
  305. 'az'               ascii
  306.  
  307. cONSTANTS AND LABELS CAN BE MIXED IN THE FOLLOWING WAYS:
  308. + ADDITION
  309. - SUBTRACTION
  310. * MULTIPLICATION
  311. / DIVISION
  312. ! LOGIC or
  313. & LOGIC and
  314. ^ LOGIC xor
  315. < LOW ORDER VALUE BYTE (LO-BYTE) OF AN 16-BIT VALUE
  316. > HIGH ORDER VALUE BYTE (HI-BYTE) OF AN 16-BIT VALUE
  317.  
  318. eXAMPLES OF '^', '<' AND '>'
  319.  
  320. ---------------------------------------
  321. %101010 ^ %010101
  322. ---------------------------------------
  323. (RESULT %111111)
  324.  
  325. ---------------------------------------
  326. < $1234
  327. ---------------------------------------
  328. (RESULT $34)
  329.  
  330. ---------------------------------------
  331. > $1234
  332. ---------------------------------------
  333. (RESULT $12)
  334.  
  335. tHERE IS NO HIERARCHY, OPERATIONS ARE EVALUATED AS THEY ARE WRITTEN
  336. DOWN FROM LEFT TO RIGHT, WITH THE EXCEPTION OF BRACKETS '(' AND ')'
  337. WHICH ARE EVALUATED FIRST.
  338.  
  339. fURTHERMORE THE DIFFERENT NOTATIONS OF CONSTANTS MAY BE MIXED IN ONE
  340. EXPRESSION:
  341. ---------------------------------------
  342. $13 + %1010 + 'c'
  343. ---------------------------------------
  344.  
  345. tHE ADDRESSES ARE CALCULATED AS EFFICIENT AS POSSIBLE ON ASSEMBLY. tHAT
  346. MEANS THAT A EXPRESSION LIKE:
  347. ---------------------------------------
  348. lda $91
  349. ---------------------------------------
  350. USES THE ZEROPAGE ADDRESSING TECHNIQUE. a ABSOLUTE (16-BITS) ADDRESSING
  351. TECHNIQUE CAN BE FORCED WITH:
  352. ---------------------------------------
  353. lda !$91
  354. ---------------------------------------
  355. WHICH IS ASSEMBLED TO:
  356. ---------------------------------------
  357. ad 91 00 lda $0091
  358. ---------------------------------------
  359.  
  360. oF COURSE THE SAME APPLIES WHEN A LABEL IS USED:
  361. ---------------------------------------
  362. zeropage = $91
  363. adc !zeropage
  364. ---------------------------------------
  365.  
  366.  
  367. pSEUDO OPCODES
  368. ------ -------
  369.  
  370. ---------------------------------------
  371. ;    =    ==   *=   .asc .byt .wor 
  372. .mod .obj .lis .sym .lst .sst .end
  373. .fil .lf  .if= .if< .slo .fas .err
  374. ---------------------------------------
  375.  
  376.  
  377. ;
  378.  
  379. FORMAT: ; SOME COMMENT
  380. wITH THIS PSEUDO OPCODE YOU CAN ADD COMMENT THAT THE ASSEMBLER IGNORES.
  381. iT IS GOOD PRACTICE TO COMMENT YOUR SOURCE CODE. iF YOU WANT TO CHANGE
  382. IT YEARS LATER, IT IS NOT SO DIFFICULT TO UNDERSTAND WHAT THE ROUTINES
  383. ARE SUPPOSED TO DO.
  384.  
  385.  
  386. =
  387. ==
  388. *=
  389.  
  390. sEE ABOVE.
  391.  
  392.  
  393. .asc
  394.  
  395. FORMAT: .asc "text"
  396. wITH THIS PSEUDO OPCODE YOU CAN PIN DOWN TEXT TO A CERTAIN LOCATION IN
  397. MEMORY. wHERE IT OCCURS, THE TEXT IS INSERTED. tHE NUMBER OF CHARACTERS
  398. IS LIMITED BY THE LENGTH OF A basic LINE (160 CHARACTERS). lONGER TEXTS
  399. SHOULD BE LISTED IN MORE THAN ONE LINE.
  400.  
  401. wHEN YOU PLACE A LABEL IN THE LINE BEFORE THE .asc PSEUDO OPCODE YOU
  402. CAN REFER TO THE FIRST CHARACTER IN THE TEXT WITH THAT LABEL.
  403.  
  404.  
  405. .byt
  406.  
  407. FORMAT: .byt BYTE, BYTE, ...
  408.  
  409. jUST AS WITH .asc YOU CAN DEFINE A STRING OF CHARACTERS (OR VALUES)
  410. WITH THE PSEUDO OPCODE .byt. tHE SAME RESTRICTIONS AND POSSIBILITIES
  411. APPLY.
  412.  
  413.  
  414. .wor
  415.  
  416. FORMAT: .wor WORD, WORD, ...
  417. sIMILAR TO .byt, ONLY WITH 16-BIT VALUES IN THE LO/HI NOTATION. e.G.
  418. $1234 IS STORED AS:
  419. ---------------------------------------
  420. >00b13 34 12
  421. ---------------------------------------
  422.  
  423.  
  424. .mod
  425.  
  426. FORMAT: .mod 1 OR .mod 2
  427. wITH THIS PSEUDO OPCODE YOU CAN SWITCH TO THE z-80 MODE (.mod 1) AND
  428. THE 8502 MODE (.mod 2). yOU CAN USE THE SAME PSEUDO OPCODES, BUT ONLY
  429. THE APPROPRIATE PROCESSOR OPCODES ARE VALID. iF NO .mod IS DEFINED THE
  430. 8502 MODE APPLIES.
  431.  
  432. iF YOU WANT TO SWITCH FROM THE 8502 PROCESSOR TO THE z-80 PROCESSOR,
  433. YOU CAN USE THE ROUTINE BELOW IN THE SECTION sWITCHING BETWEEN
  434. PROCESSORS.
  435.  
  436.  
  437. .obj
  438.  
  439. tHIS PSEUDO OPCODE IMPLIES WHERE TO PUT THE OBJECT CODE (THE EXECUTABLE
  440. MACHINE LANGUAGE PROGRAM). hERE ARE THE POSSIBILITIES:
  441.  
  442. SAVE NO OBJECT CODE - CHOOSE:
  443. ---------------------------------------
  444. .obj nothing
  445. .obj n
  446. ---------------------------------------
  447.  
  448. SAVE OBJECT CODE TO MEMORY (TAKE CARE NO TO OVERWRITE THE ASSEMBLER!) -
  449. CHOOSE:
  450. ---------------------------------------
  451. .obj memory
  452. .obj m
  453. ---------------------------------------
  454.  
  455. SAVE TO MEMORY WITH A CERTAIN MEMORY BANK CONFIGURATION - CHOOSE:
  456. ---------------------------------------
  457. .obj memory, bank
  458. .obj m, bank
  459. ---------------------------------------
  460.  
  461. SAVE TO A EXTERNAL STORAGE DEVICE (DEV. = 1, 8, ... 15), WITH AN
  462. OPTIONAL SECUNDARY ADDRESS (SA) AND FILE NAME (NM$) (THOSE LAST TWO ARE
  463. OBLIGATORY IN CASE OF A FLOPPY DISC DRIVE):
  464. ---------------------------------------
  465. .obj DV (, SA)(, NM$)
  466. ---------------------------------------
  467.  
  468.  
  469. .lis
  470.  
  471. tHIS PSEUDO OPCODE GENERATES A FORMATTED LIST OF THE SOURCE CODE. tHE
  472. CODE IS A TEXT FILE, NOT AN basic PROGRAM FILE. .lis HAS SIMILAR
  473. VARIETIES AS .obj (S. ABOVE):
  474.  
  475. NO LISTING:
  476. ---------------------------------------
  477. .lis nothing
  478. .lis n
  479. ---------------------------------------
  480.  
  481. LIST TO SCREEN:
  482. ---------------------------------------
  483. .lis screen
  484. .lis s
  485. ---------------------------------------
  486.  
  487. LIST TO EXTERNAL STORAGE DEVICE:
  488. ---------------------------------------
  489. .lis DV (, SA)(, NM$)
  490. ---------------------------------------
  491.  
  492.  
  493. .sym
  494.  
  495. dURING PASS 1 (CALCULATION OF LABELS) THE SYMBOL TABLE IS GENERATED. iF
  496. YOU PLACE THE .sym PSEUDO OPCODE IN THE LAST LINE (WITH THE HIGHEST
  497. LINE NUMBER), YOU GET A LIST OF LABELS AFTER PASS 1 IS COMPLETED.
  498. aGAIN, HERE ARE SOME VARIETIES:
  499.  
  500. NO LISTING:
  501. ---------------------------------------
  502. .sym nothing
  503. .sym n
  504. ---------------------------------------
  505.  
  506. LIST TO SCREEN:
  507. ---------------------------------------
  508. .sym screen
  509. .sym s
  510. ---------------------------------------
  511.  
  512. LIST TO EXTERNAL DEVICE (1, 4, 5, 8, ... 15):
  513. ---------------------------------------
  514. .sym DV (, SA)(, NM$)
  515. ---------------------------------------
  516.  
  517.  
  518. .sst AND .lst
  519.  
  520. yOU CAN STORE THE SYMBOL TABLE (NOT THE LISTING) ITSELF ON FLOPPY DISC,
  521. AND RETRIEVE IT AGAIN WHEN NEEDED.
  522.  
  523. STORE TO DISC:
  524. ---------------------------------------
  525. .sst DV, SA, NM$
  526. ---------------------------------------
  527.  
  528. LOAD FROM DISC:
  529. ---------------------------------------
  530. .lst DV, SA, NM$
  531. ---------------------------------------
  532.  
  533. nOTE: (IF YOU DIDN'T KNOW ALREADY) THE SECUNDARY ADDRESS FOR STORING IS
  534. 1 (ONE) AND FOR LOADING 0 (ZERO). sO IN .sst USE 1 FOR THE SECUNDARY
  535. ADDRESS, AND IN .lst USE 0 FOR SA.
  536.  
  537.  
  538. .fil AND .lf
  539.  
  540. tO ACTUALLY LINK THE FILES YOU HAVE TO INSTRUCT THE ASSEMBLER TO DO SO,
  541. WITH A .fil STATEMENT. .fil LOADS THE NEXT SOURCE FILE.
  542.  
  543. .fil HAS THE SYNTAX:
  544. ---------------------------------------
  545. .fil DV, NM$
  546. ---------------------------------------
  547.  
  548. pLACE THE .fil STATEMENT AS THE LAST STATEMENT IN THE SOURCE FILE WHEN
  549. ASSEMBLING MORE THAN ONE SOURCE FILE. iN THE LAST SOURCE FILE IN THE
  550. ASSEMBLY ROW USE .lf INSTEAD. .lf SHOULD POINT TO THE FIRST FILE IN THE
  551. ASSEMBLY ROW.
  552.  
  553. .lf HAS THE FOLLOWING SYNTAX:
  554. ---------------------------------------
  555. .lf DV, NM$
  556. ---------------------------------------
  557.  
  558.  
  559. .end
  560.  
  561. wITH THIS PSEUDO OPCODE, THAT IS OPTIONAL, YOU INVOKE PASS 2
  562. IMMEDIATELY. iF ANY OPCODES FOLLOW, THEY ARE NOT PROCESSED BY THE
  563. ASSEMBLER.
  564.  
  565. yOU COULD PLACE SOME LINE OF basic AFTER THE .end STATEMENT (E.G.
  566. COMMENT LINES FROM ONE PROGRAMMER TO ANOTHER THAT DON'T HAVE TO APPEAR
  567. IN THE FORMATTED SOURCE LISTING, AND ARE TEMPORARY IN NATURE).
  568.  
  569.  
  570. .fas
  571.  
  572. nORMALLY dOUBLE-aSS RUNS IN 1 mHZ MODUS. wITH THIS PSEUDO OPCODE YOU
  573. CAN FORCE THE ASSEMBLER TO DOUBLE IT'S SPEED. aFTER ASSEMBLY THE
  574. PROCESSOR SPEED RETURNS TO 1 mHZ.
  575.  
  576.  
  577. .slo
  578.  
  579. sWITCHES BACK TO THE 1 mHZ MODUS. tHIS CAN BE OMITTED, BECAUSE dOUBLE-aSS
  580. AUTOMATICALLY RETURNS TO THE 1 mHZ MODUS AFTER ASSEMBLY.
  581.  
  582.  
  583. .err
  584.  
  585. iF THE 2 mHZ MODE IS ACTIVE AND A ERROR OCCURS, dOUBLE-aSS SWITCHES
  586. BACK TO 1 mHZ, AND WAIT FOR A PRESS ON A BUTTON BY THE USER, SO HE CAN
  587. SEE THE ERROR THAT OCCURRED. aFTER THE USER HAS PRESSED A KEY, THE
  588. ASSEMBLER CONTINUES AT FULL SPEED.
  589.  
  590.  
  591. .if=
  592.  
  593. SYNTAX:
  594. .if= VALUE 1, VALUE 2, LINE NUMBER
  595.  
  596. vALUE 1 AND 2 ARE VALID dOUBLE-aSS EXPRESSIONS. iF VALUES 1 AND 2 ARE
  597. EQUAL, THE ASSEMBLY CONTINUES ON THE SPECIFIED LINE NUMBER, OTHERWISE
  598. THE ASSEMBLY CONTINUES RIGHT AFTER THE .if STATEMENT.
  599.  
  600.  
  601. .if< VALUE 1, VALUE 2, LINE NUMBER
  602.  
  603. sIMILAR TO .if=. iF VALUE 1 IS SMALLER THAN VALUE 2 THEN ASSEMBLY
  604. CONTINUES AT THE SPECIFIED LINE NUMBER, OTHERWISE THE ASSEMBLY
  605. CONTINUES AFTER THE .if< STATEMENT.
  606.  
  607.  
  608. sWITCHING BETWEEN PROCESSORS
  609. --------- ------- ----------
  610.  
  611. sWITCHING BETWEEN THE 8502 MICROPROCESSOR AND THE z-80 MICROPROCESSOR
  612. IS A DELICATE BUSINESS, WHICH SHOULD BE PROGRAMMED WITH CARE. uSE THE
  613. FOLLOWING SUBROUTINE TO ASSURE CRASH-FREE OPERATION.
  614.  
  615. ---------------------------------------
  616. 1000 *= $8000      ; START ON $8000 (CHANGE IF NECESSARY)
  617. 1010 .lis n        ; NO LISTING
  618. 1020 .obj m        ; OBJECT CODE IN MEMORY
  619. 1030 :
  620. 1040 :             ; tHIS PART IS ESSENTIAL, NO ERRORS ALLOWED
  621. 1050 :
  622. 1060 lda $ff00     ; mmu BANK CONFIGURATION REGISTER
  623. 1070 pha           ; SAVE IT ON STACK
  624. 1080 sei           ; DISABLE THE SYSTEM INTERRUPT
  625. 1090 lda #$c3      ; STORE z-80 OPCODE - jp
  626. 1100 sta $ffee     ; ON BOOT-LINK ADDRESS $ffee .. $fff0
  627. 1110 lda #<z80     ; LOBYTE z-80 ROUTINE, DEFINED BELOW
  628. 1120 sta $ffef
  629. 1130 lda #>z80     ; HIBYTE z-80 ROUTINE
  630. 1140 sta $fff0
  631. 1150 lda #$3e      ; SET THE CONFIGURATION REGISTER
  632. 1160 sta $ff00     ; WITH THE APPROPRIATE VALUE
  633. 1170 lda $d505     ; SAVE THE MODE CONFIGURATION REGISTER
  634. 1180 pha           ; FOR LATER
  635. 1190 lda #$b0      ; AND SET THE MODE CONFIGURATION
  636. 1200 sta $d505     ; TO 'z-80 ACTIVE'
  637. 1210 :             ; WHEN THIS LAST INSTRUCTION IS EXECUTED
  638. 1220 :             ; THE z-80 IS ACTIVE AND THE 8502 IS FROZEN
  639. 1230 nop           ; important: GIVE THE 8502 TIME TO START
  640. 1240 pla           ; NOW BACK IN GOOD OL' 8502 MODE
  641. 1250 sta $d505     ; RESTORE OLD MODE CONFIGURATION
  642. 1260 pla           ; AND
  643. 1270 sta $ff00     ; OLD MEMORY CONFIGURATION
  644. 1280 cli           ; ENABLE THE SYSTEM INTERRUPT
  645. 1290 rts           ; END OF ESSENTIAL SUBROUTINE
  646. 1300 :
  647. 1500 :             ; rOUTINE FOR THE z-80
  648. 1510 :
  649. 1520 z80           ; lABEL FOR THE z-80 ROUTINE (S.A. ABOVE)
  650. 1530 .mod 1        ; z-80 OPCODES NOW VALID IN ASSEMBLER
  651. 1540 ld a, $3f     ; CHANGE VALUE OF CONFIGURATION REGISTER
  652. 1550 ld ($ff00), a ; TO THE APPROPRIATE VALUE
  653. 1560 :
  654. 1570 :             ; *** SAMPLE PROGRAM
  655. 1580 :             ;     - CLEAR vic-ii GRAPHIC SCREEN
  656. 1590 :
  657. 1600 ld a, $00     ; fILL BYTE $00 ON THE FIRST
  658. 1610 ld ($2000), a ; LOCATION OF GRAPHIC SCREEN ($2000)
  659. 1620 ld hl, $2000  ; LOAD hl WITH ADDRESS VALUE $2000
  660. 1630 ld de, $2001  ; LOAD de WITH ADDRESS VALUE $2001
  661. 1640 ld bc, 7999   ; LOAD bc REGISTER WITH 7999
  662. 1650 :             ; (NUMBER OF BYTES TO FILL)
  663. 1660 ldir          ; EXECUTE (hl) -> (de), 7999 TIMES
  664. 1670 :
  665. 1680 :             ; *** END OF SAMPLE PROGRAM
  666. 1690 :
  667. 1700 :             ; cRUCIAL FOR THE SWITCH BACK
  668. 1710 :
  669. 1720 jp $ffe0      ; JUMP TO BOOTLINK ROUTINE IN THE z-80 rom
  670. 1730 :             ; I.E. SWITCH 8502 ON, AND z-80 OFF
  671. ---------------------------------------
  672.  
  673.  
  674. dON'TS AND DO'S
  675. ------ --- ----
  676.  
  677. dON'T WRITE
  678. ---------------------------------------
  679. * = $1300
  680. ---------------------------------------
  681. BUT WRITE
  682. ---------------------------------------
  683. *= $1300
  684. ---------------------------------------
  685.  
  686. aLWAYS PLACE SPACES BETWEEN OPCODES AND THEIR OPERANDS:
  687.  
  688. ---------------------------------------
  689. lda#$00
  690. ---------------------------------------
  691. THIS IS WRONG, IT SHOULD BE TYPED LIKE THIS:
  692.  
  693. ---------------------------------------
  694. lda #$00
  695. ---------------------------------------
  696.  
  697. tRY TO PUT AS MUCH OF THE SOURCE CODE IN ONE FILE AS POSSIBLE. tHIS
  698. SAFES TIME DURING THE ASSEMBLY, BECAUSE FILELOADING AND SAVING CAN BE
  699. TIMECONSUMING ON A cbm MACHINE. mERGE THE DIFFERENT PARTS IN ONE MAJOR
  700. SOURCE CODE FILE. yOU CAN THEN EASILY FINE-TUNE THE WHOLE PROGRAM.
  701.  
  702. tRY TO ONLY USE STANDARIZED EXTENSIONS FOR THE FILES:
  703. 1. NO EXTENSION OR .bin FOR THE OBJECT FILE
  704. 2. .lst FOR A basic LISTING WITH SOURCE CODE
  705. 3. .sym FOR A FILE WITH THE SYMBOL TABLE
  706. 4. .src FOR A FORMATTED SOURCE LISTING
  707.  
  708. uSE AS LESS COMMENT IN YOUR OWN WORK SOURCE LISTING AS POSSIBLE. rATHER
  709. THAN COMMENTING INSIDE YOUR FILE, USE EXTERNAL COMMENTING. eXTENSIVE
  710. COMMENTING 'CHEWS UP' MEMORY AND TAKES A LOT OF ASSEMBLY TIME.
  711.  
  712. wHEN DOCUMENTING THE FINAL RELEASE (OBLIGATORY WHEN YOU WRITE FOR
  713. SOMEONE ELSE) YOU CAN BEST MAKE TWO FILES: ONE FOR ASSEMBLE WITH AS
  714. LITTLE COMMENT AS POSSIBLE, AND A FORMATTED PRINT-OUT OF THAT SAME FILE
  715. TO DISK (THE .lis SOURCE CODE DUMP), WHICH YOU EXTEND WITH COMMENTS IN
  716. A WORDPROCESSOR.
  717.  
  718. iT IS IMPORTANT IN MULTI FILE ASSEMBLY TO ONLY GIVE THE START ADDRESS
  719. AT THE BEGINNING OF THE FIRST LINK FILE. aLSO THE .obj STATEMENT HAS TO
  720. BE IN THE SECOND LINE OF THE FIRST LINK FILE. oTHER CONSTRUCTIONS MIGHT
  721. CONFUSE THE ASSEMBLER.
  722.  
  723. ---------------------------------------
  724. end of document
  725.