Manual / Guide · 1983
The Advanced User Guide for the BBC Micro
§18.9 light pens: 6845 registers R16/R17 and the per-mode correction factors.
- bbc micro
- 6845
- light pen
Manual / Guide · 1983
§18.9 light pens: 6845 registers R16/R17 and the per-mode correction factors.
FOR THE BBC MICRO BRAY, DICKENS & HOLMES Oe) Pe ‘Mp Tt if The Advanced User Guide for the BBC Microcomputer Andrew C. Bray, St. Catharines College, Dept. of Computer Science, Cambridge University Adrian C. Dickens, Churchill College, Dept. of Engineering, Cambridge University Mark A. Holmes BA, Fitzwilliam College, Dept. of Clinical Veterinary Medicine, Cambridge University Published by the Cambridge Microcomputer Centre Published in the United Kingdom by: The Cambridge Microcomputer Centre, 153-154 East Road, Cambridge, England Telephone (0223) 355404 Tix 817445 ISBN 0 946827 00 1 Copyright © 1983 The Cambridge Microcomputer Centre First published 1983 The Authors would like to thank Clive Birks, Andrew Cripps, Nigel Dickens, Tim Dobson, Alistair France, Jonathan Griffiths, Dr Hermann Hauser, Nicholas Holmes, Dr John Horton, Chris Jordan, Brian Jones, Peter Morrison, Dan Nanayakkara and Alex Van Someren for their assistance in the production of this book. All rights reserved. This book is copyright. No part of this book may be copied or stored by any means whatsoever whether mechanical, photographic or electronic, except for private or study use as defined in the Copyright Act. All enquiries should be addressed to the publishers. While every precaution has been taken in the preparation of this book, the publisher assumes no responsibility for errors or omissions. Neither is any liability assumed for damages resulting from the use of information contained herein. The Authors gratefully acknowledge Acorn Computers Limited for their kind permission to reproduce the complete circuit diagram and keyboard circuit diagram. The Authors would like to point out that Acorn Computers Limited reserve the right to make improvements in the specification of its products. Therefore the circuit diagrams and other contents of this book may not be in complete agreement with the product supplied The Authors thank Rockwell International for their permission to reproduce diagrams from their R6522 data sheet. These diagrams remain the copyright of Rockwell International. Please note that within this text the terms Tube, Econet and Electron are registered tradenames of Acorn Computers Limited. CP/M is a registered trademark of Digital Research Inc. All references in this book to the BBC Microcomputer refer to the computer produced for the British Broadcasting Corporation by Acorn Computers Limited. This book was prepared using the Acornsoft VIEW wordprocessor on the BBC Microcomputer and then computer typeset by Computerset and MFK Graphics of Saffron Walden. Book production by Cambridge Marketing Limited. @ Contents Introduction 1 Introduction for those new to machine code Operating System Commands 2 Operating System commands Assembly Language Programming 3 4 5 6 The BASIC assembler Machine code arithmetic Addressing modes The assembler mnemonics Operating System interfaces 7 8 9 10 Operating system calls *EX/OSBYTE calls OSWORD calls Vectors 11 12 13 Memory usage Events Interrupts RS423 Paged ROMs Filing systems 14. 15 16 ee er et ee 11 Hardware 17 An introduction to the hardware 353. 18 The video circuit (6845) 359 19 20 21 377 385 395 397 24 25 26 27 The video ULA The serial interface The paged ROM select register Programming the 6522 VIA The system 6522, including sound and speech The user 6522 Disc and Econet interfaces The analogue-to-digital converter The Tube 417 425 427 429 433 OD 28 The 1 MHz bus 437 a 22 23 Q QB Appendices A B_ C_ D_ E F G_ H_ I J K C @ *EX/OSBYTE call index Operating System calls summary Table of key numbers VDU codes PLOT number summary Screen mode layouts US MOS differences Disc upgrade Circuit | Board links Keyboard circuit diagram Main circuit diagram 449 455 456 459 460 462 478 480 482 489 Inside Back Cover @ @ Cs) a Bibliography 491 Glossary 493 ® INDEX 499 a : ea Introduction The ‘Advanced User Guide for the BBC Microcomputer’ has been designed to be an invaluable supplement to the User Guide. Information already contained in the User Guide is only repeated in this book in sections which contain much new information and where ommitting the duplicated details would have left the section incomplete. Some parts of the User Guide are factually inaccurate or incomplete and where details in this book are at variance with corresponding information in the User Guide the reader will find that a more accurate description is usually found in these pages. This reference manual contains a considerable amount of information about 6502 assembly language programming, the operating system and the BBC Microcomputer hardware. The intention has not been to provide the inexperienced user with a tutorial to guide him or her through the complexities of these advanced concepts. However, it is hoped that the information has been presented in a way that enables users new to assembly language programming and unfamiliar with hardware topics to develop their understanding of the machine and to expand the scope of their programming. Contained within this book is an extensive description of the software environment and the hardware facilities available to @#@e@e0ed8e88088080 the assembly language programmer. The authors have presumed that the readers of this Advanced Guide are reasonably familiar with the basic use of the BBC Microcomputer. While every attempt has been made not to bury the facts under a mountain of computer jargon the use of technical terms is an inevitable consequence of attempting to condense a large number of facts into an easily accessible form. le oe ) Cn All the information about the operating system is exclusively based on OS 1.20. The hardware information has been verified with an issue 4 circuit board but where possible differences on earlier issue boards have been noted. While this book gives the programmer full access to all the BBC microcomputer’s extensive software and hardware @ 8 eo facilities using techniques which the designers of the machine x) 5 intended programmers to use, it also opens the door to a multitude of ‘illegal’ programming techniques. For the enthusiast, direct access to operating system variables or chip registers may enable him to perform the bizarre or even the merely curious. For the serious programmer, on the other hand, attention to compatability and machine standards will enable him to write software which will run on BBC Microcomputers of all configurations. The responsibility rests with YOU, the user. The value of your machine depends on continued software support of the highest quality; unlike many machines the BBC microcomputer has been designed to be used in a variety of different configurations and the operating system software provides extensive information about the current hardware and software status. The operating system makes most of the allowances required for the different configurations automatically, but only when the legal techniques are adhered to, so please use them. The final paragraph in this introduction must be a word of apology to those programmers engaged in the task of software protection. Many of the details contained in this book will give those intent on pirating software inspiration to circumvent their protection techniques. On the other hand these same details may also give the software protectors inspiration. In the end no software protection is complete. Any protection technique relies on the fact that the person trying to break the protection has a threshold at which he decides that the effort and resources required are greater than the reward. For some this threshold is higher than others but for these people the reward is often the victory in the intellectual battle with the programmer of the protection method. For those intent on denying the software producer his income, one hopes that this threshold is somewhat lower. 1 Introduction for those new to machine code There comes a time in every programmer's life (well, most programmers’, anyway) when the constraints of a high level language (e.g. BASIC) prevents him from implementing a particular program idea or from utilising some machine facility. At this stage the programmer must often seek recourse to the microprocessor’s native language, its machine code. At the heart of any microcomputer is the microprocessor. This microprocessor is the brain of the computer and provides the computer with all its computing power. The BBC Microcomputer uses a 6502 microprocessor and the brief description of machine code given here applies specifically to the 6502. The microprocessor performs instructions which are contained in memory. Each instruction which the microprocessor understands can be contained within a single byte of memory. Depending on the nature of this instruction the microprocessor may fetch a number of bytes of data from the memory locations following the instruction byte. Having executed this instruction the microprocessor moves on to the byte after the last data byte to get its next instruction. In this way the microprocessor works its way sequentially through a program. These single byte instructions are called operation codes (or just opcodes) although they are frequently referred to as machine instructions (or just instructions). The data used by the instructions are called the operands. A program using the native machine instructions is called a machine code program. An assembler is a software package (a language or a program) which enables a programmer to create a machine code program. Machine code is substantially different from a higher level language such as BASIC. The machine code programmer is limited to three registers for temporary storage of data while in BASIC he has unlimited use of variables. For more permanent storage in machine code programs, the register values can be copied to bytes of memory. Only very limited . arithmetic is available; there are no multiply or divide instructions. There are no automatic loop structures such as FOR... NEXT or REPEAT... UNTIL and any loops must be explicitly set up by the programmer using conditional branches (these approximate to IF .. THEN GOTO .. in BASIC). The range of instructions available are sufficient to enable extremely complex programs to be written but a lot more effort is required to implement the program. One of the most grave disadvantages of machine code is that very little error checking is made available to the programmer. A well designed assembler will help the programmer, but once the machine code program is running the only error checking is that which is provided within the program itself. At first glance it may appear that there is little to be gained from writing a machine code program. The principal advantage is that of speed. While assigning a value to a variable in BASIC will take about 1 millisecond, in machine code assigning a similar value will only take 10 microseconds. This is why fast moving arcade games have to be written in machine code. Some of the facilities available on the BBC Microcomputer can only be used when programming in machine code. For example, a user printer driver can only be implemented in machine code. Of no less importance than the design of the hardware or the choice of microprocessor in the machine is the operating system. This is a large, and highly complex machine code program which governs the machine. The operating system consists of a large number of routines which perform operations such as scanning the keyboard, updating the screen, performing analogue-to-digital conversions (for the joysticks) and controlling the sound generator. All these functions are performed by the operating system and are made available to other machine code programs. A machine code program with which all users will be familiar is BASIC. This program which provides the user with an easier way of using the microprocessor’s computing power constantly uses the operating system routines to get input from the keyboard and to reflect that input on the screen. BASIC recognises words of text and when it wants to use a hardware facility it calls a machine code routine within the operating system. The ©e great advantage of this independence of the language program from the direct use of hardware is that the same facilities can be offered to different languages. Writing a machine code program requires the programmer to place the appropriate values into successive memory locations corresponding to the opcodes and operands. This would be a very tedious business if it had to be done by looking up the opcode values in tables and poking in the values by hand. It is much faster, easier and more efficient to get the computer to do most of the work. A program which analyses text input representing opcode symbols, converts these to opcode values and inserts these values into memory is called an assembler. The text input consists of opcode mnemonics (three-letter words which specify the opcode type) followed by numbers, variable names or expressions which give the values of the operand to be used by the opcode. Like BASIC the assembler requires the program to be written in a defined way according to a syntax. The language that an assembler understands is called assembler or assembly language. In the BBC Microcomputer an assembler is available as part of the BASIC language and a description of how this assembler can be used is contained in the chapter on the BASIC assembler. Many of the following sections include descriptions of the various operating system routines and facilities which are available to the machine code programmer. de ee ee ii 0 0 ee " 10 2 Operating System commands The command-line interpreter resident within the operating system will recognise a number of commands and act apropriately upon receiving them. These commands are most often used from the keyboard or in BASIC programs using the “*” prefix. Commands may also be passed to the command-line interpreter using the OSCLI call (&FFF7) from machine code (see section 7.12 for details of OSCLI). Any command offered to the command-line interpreter but not recognised as a command resident in the command table is offered to paged ROMs for possible action. If it is not claimed by a paged service ROM it is presented to the currently selected filing system ROM. The filing system may recognise the command as one of its internal file commands or may attempt to load and execute a file specified by the command name (the cassette and ROM filing systems excepted), i.e. it is equivalent to **RUN <command name>’. Each command name may be abreviated by using enough letters to identify the command terminated by a full stop. The minimum abreviations for each command are noted below with the description of each command. The command-line interpreter does not distinguish between upper and lower case characters in the command name (“*cat’ has the same effect as “*CAT’). Where a string or filename is specified as a parameter the text need not be enclosed within paired quotation marks but must be separated from the command name by at least one space. Several of the operating sytem commands invoke OSBYTE calls and so their action mimics these calls. Where there is an equivalent OSBYTE call this has been indicated. 11 A number of commands are filing system dependent. Any command which creates or uses files is described for the ROM and cassette filing systems only. 2.1 *| An operating system command-line with a ‘|’, string escape character, as its first non-blank character will be ignored by the operating system. This could be used to put comment lines into a series of operating system commands placed in an EXEC file for example. 22, This command is directly equivalent to the *CAT command. 2.3 */<file name> This command is treated exactly the same as typing *RUN <file name> or *<file name>. The file name is offered directly to the filing system and will not be interpreted as a command. 2.4*BASIC (*B.) While the operating system is independent of any particular language and only serves to provide an interface between languages or utility software and the machine hardware, BASIC has been accorded special status. The *BASIC command is resident in the operating system command table and it enables the operating system to select a language in paged ROM not possessing a service entry point (for further details about paged ROMs see chapter 15). The operating system scans the paged ROMs and keeps a record of which paged ROM contains BASIC (see OSBYTE &BB/187). If a BASIC ROM is not present this command is offered to other paged ROMs. 12 ee 88 8 2.5*CAT (+) This command displays a catalogue of files from the selected filing system. When the cassette or ROM filing systems are selected the name of each file encountered is printed on the screen along with the block number of the last block read. When the last block is reached further information is printed out. If the default messages are selected then the length of the file will be added to the block number. FILENAME 09 0904 If extended messages have been selected then the catalogue printout after the final block has been reached will look like this:— FILENAME 09 = =0904 FFFFOE00 FFFF801F This file is a BASIC (level 1) program SAVEed from BASIC with PAGE=&E00 and the program is &904 bytes long. The fourth field in the catalogue printout is the start address of the file and the file will *LOAD to this address by default. The fifth field is the execution address. When using level 2 BASIC the execution address will be 8023. When an attempt is made to *RUN a file the processor jumps (using JSR) to this address. The two most-significant bytes of the four-byte fourth and fifth fields are set to the machine high order address (see OSBYTE &82/130). For details about selecting extended messages see *OPT. 2.6 *CODEx,y (*CO.) | OSBYTE with A=&88 (136) This command enables the user to incorporate his own command into the operating system command table. *CODE executes machine code indirected through the user vector (USERV) at locations &200,&201 (low-byte, high-byte). The default contents of the user vector produce the ‘Bad Command’ message. The machine code at USERV is entered with A=0, X=x and Y=y. 13 For example: 10 DIM Mcé 100 20 OSASCI=sFFE3 30 USERV=5200 40 FOR optt=0 TO 3 STEP3 50 P&=MCe 60 C 70 OPT opt’ 80 write 90 CMP #0 \ is this *copE ? 100 BEQ code \ if *cope call act upon it 110 BRK \ anything else, print error message 120 130 : P&=PR+1 : REM error number 140 CODE only please’ 150 S+LENSPS 160 170 OPT opt \ reset OPT 180 BRK \ op code value=0 190 .code TxA \ transfer contents of X reg. to Acc. 200 JSR OSASCI \ print ASCII character 210 RTS \ return to BASIC 220] 230 NEXT 240 PUSERV=write MOD 256 250 ?(USERV+l)=write DIV 256 This example prints out the ASCII character corresponding to the value of the first parameter given to the *CODE command. After this program has been run typing in “CODE 65’ or ‘*FX 136,65’ will cause a letter ‘A’ to be printed. The second parameter (stored in Y) if included, is ignored. See also *LINE. 2.7 *EXEC<filename> _ (*E.) Text files from the currently selected filing system can be used as if they were keyboard input using this command. A typical application might involve the setting up of a user’s favourite soft key definitions which are *EXECed in at the beginning of a programming session. See also *SPOOL and OSBYTE &C6/198. 14 @ 6 e *2.8*EXa,x,y (*F.) OSBYTE calls may be performed directly from the keyboard using this command. A, X and Y are loaded by the operating system from the command-line parameters. Any OSBYTE call may be made using the *FX command but it is not always appropriate to make an OSBYTE call using this direct method e.g. OSBYTE calls that return values in any of the registers. The *FX command is a useful way of making those OSBYTE calls which have a direct effect from a BASIC program or from the command-line interpreter. For further information on specific *FX/OSBYTE calls refer to chapter 8. 2.9*HELP (*H.) Typed in on a machine containing only the operating system and BASIC ROMs this command causes the version number of the operating system to be printed out i.e. OS 1.20 Each *HELP call is offered to any paged ROMs that are resident and these may be able to respond to futher command-line parameters. e.g. *HELP VIEW *HELP UTILS For more information about *HELP handling in paged ROMs see section 15.1.1 (service call 9). 2.10 *KEYn<string> (*K.) The ten red—topped function keys, the BREAK key, the COPY key and the four cursor control keys may be set up using this command. Using *KEYn with n in the range 0 to 9 sets up the function keys. *KEY10 can be used to program the BREAK key. Before the remaining programmable keys can be used a *FX4,2 must be performed. This disables cursor editing and enables the following soft keys:— *KEY 11 COPY *KEY “KEY *KEY *KEY 12 13 14 15 left cursor right cursor down cursor up cursor Each time a soft key is pressed a soft key character is inserted into the keyboard buffer. The soft key characters may be calculated by adding the soft key number to &80 (128). (A soft break actually places a character of value &CA in the input buffer but this behaves identically to character &8A.) See OSBYTEs &DD/221 to &E4/228 for more information about the function keys. Control codes may be introduced into the string by using an ‘escape’ character, ‘|’. This acts in a similar way to the CTRL key and so ‘|G’ gives a bell sound as the CTRL and G keys would if pressed simultaneously; ‘|G’ actually places a character of value 7 into the soft key buffer. The ‘|’ character may be inserted using the sequence ‘||’ and a quotation mark (‘) may be represented by preceding the quotation mark with the ‘escape’ character (‘|’). The delete character (ASCII &7F/ 127) may be introduced using the ‘escape’ character followed by a question mark. Characters of value greater than 127 may be inserted by using the escape sequence ‘|!’; this sequence will add 128 to the value of the next character in the string. eg. ‘IIA’ 128+65=193 WA’: 128-+1=129 This method of including non-printable characters into a string may be used in any string which is processed using the operating system routines GSINIT and GSREAD (see section 7.9) and is not restricted to use of the *KEY command. 2.11 *LINE<text> —(*LI.) This command executes machine code at the location pointed to by the contents of the user vector (USERV) at locations &200,&201 (low-byte,high-byte). The command enters this code with the A=1, X=least significant byte of string address and Y=most significant byte of string address. *LINE provides 16 . ® ® ® ® ® % ® ® e e e an easy method of incorporating a user function into the operating system command table. 10 DIM Mc’ 100 20 OSASCI=6FFE3 30 USERV=&200 40 FOR opt®=0 TO 3 STEP3 50 P&=MCB so 70 OPT opt’ 80 .write 90 cMP #1 \ is this *LINE? 100 BEQ code \ execute machine code if *LINE 110 BRK \ otherwise print out error message 120) 130 2P8=255 : Pte PRtl : REM error number 140 $P%="*LINE only please" 150 P8=PR+LENSPS leo 170 opr reset OPT 180 BRK op code value 0 190 .code = STX *LINE code entry point and store 200 sTY string address; low-byte,high-byte 210 LDY set up Y register for indexing 220 .loop LDA Post-Indexed Indirect addressing print out character 230 JSR 240 INY increment index 250 cMP test for end of string 260 BNE if not last character go round again 270 RTS finished POACEAE ALE 280 290 NEXT 300 2USERV- rite MOD 256 310 2(USERV+1)=write DIV 256 This example program sets up the user vector to point to some machine code which prints out the string pointed to by X and Y. After this program has been run typing in “*LINE THIS IS SOME TEXT’ results in “THIS IS SOME TEXT’ being printed out. See also *CODE. a e a i) 17 2.12 *LOAD<file name><address> (*L.) A file may be loaded into memory from the selected filing system using the *LOAD command. If the load address is not specified in the command line then the file will load at its start address (this is usually the address from which it was saved). 2.13*MOTORn (*M.) OSBYTE with A=&89 (137) This command executed with n=0 opens the cassette relay (i.e. switches the motor off) and with n=1 closes the cassette relay (i.e. motor on). 2.14*OPTx,y (*O.) |OSBYTE with A=&8B (139) This command is highly filing-system specific and although the general protocol of the cassette filing system is usually adhered to, other filing systems may interpret this command differently and expand upon it. For the cassette and ROM filing systems: *OPT 0,0 _ restore *OPT default values *OPT 1,0 _ turn off filing system messages *OPT *OPT *OPT *OPT *OPT *OPT 1,1 _ turn on filing system messages (non—-extended) 1,2 _ turn on extended messages 2,0 _ errors ignored though messages may be given 2,1 onerror, prompt for re-try 2,2 onerror, abort 3,n _ set interblock gaps to n/10 seconds (only relevent to cassette SAVE operations) When extended messages have been selected the following information is printed on the screen on completion of the filing system operation: file name — block no. — file length — start adr. — execution adr. All numeric values are printed in hexadecimal. See also *CAT. 18 7 2.15*ROM (*RO.) OSBYTE with A=&8D (141) The *ROM filing system is initialised using this command. The *ROM filing system is able to use paged ROMs or serially accessed ROMs associated with the speech processor. These ROMs must contain data in a block format similar to that used in the cassette filing system. With the ROM filing system initialised all other filing systems are disabled. For further details see section 16.11 in the filing systems chapter. 2.16 *RUN<file name> (*R.) This command causes a file to be loaded into memory at its start address and then the microprocessor jumps (using JSR) to the execution address. This is a method of loading and running machine code programs. Any text following the file name is available to pass parameters to the program. Parameter passing is not implemented for the cassette or ROM filing systems (see filing systems chapter 16). 2.17*SAVE <file name> <start addr> <exec.addr> <reload addr> _ (*S.) <end addr> The contents of memory may be saved to a file on the currently selected filing system using *SAVE. Only the start address and the end address are mandatory. If omitted the execution address will default to the start address. The reload address allows the start address stored with the file to be different to the actual start address used when saving. The end address may be in the form +length where the second field is preceded by a ‘+’ and the size of memory to be saved is specified in hexadecimal. er i eo a 19 2.18 *SPOOL <file name> (*SP.) The *SPOOL command causes all screen output to be repeated into a file. The file is opened by *“SPOOL <file name> and closed by repeating this command or by typing *SPOOL alone. See OSBYTEs &03 and &C7/199 for more information. 2.19*TAPEn (*T.) OSBYTE with A=&8C (140) *TAPE without any number selects cassette filing system and sets the default baud rate (1200). *TAPE3 selects tape with 300 baud and *TAPE12 selects 1200 baud. 2.20 *TVx,y (no abbreviation) OSBYTE with A=&90 (144) The *TV command allows the vertical position of the screen to be altered and interlace to be switched on or off. The first parameter causes the vertical position to be altered; a value of 0 causes no change, a value of 1 would cause the screen to be moved up one line and a value of 255 would cause the screen to be moved down one line. The second parameter should be 0 or 1, a value of 0 causes interlace to be enabled and a value of 1 causes interlace to be switched off. Any change of interlace or screen position will only come into effect at the next mode change and will remain until a further *TV command or a hard reset. Interlace cannot be turned off in mode 7. (It is possible to switch off interlace in mode 7 but the character set stored in the SAA 5050 is designed to be used with interlace on. Type in, VDU23,0,8,&90;0;0;0,23,0,9,&09;0;0;0 and you will see why the operating system disallows this. See chapter 18 for more information about programming the 6845 video controller chip.) 20 7 3 The BASIC Assembler One of the many atractive features of BBC BASIC is the incorporation of a mnemonic assembler within the language itself. This provides a powerful environment for the assembler and allows machine code to be easily incorporated within BASIC programs. Hybrid BASIC/machine code programs may often lead to the use of the best features of each language, the speed of machine code when it is required, coupled with the increased power of BASIC when speed is not of paramount importance. The assembler facilities available to users are dependent on the version of BASIC that is resident in the machine. To ascertain which version of BASIC is present type ‘REPORT’ following a BREAK. If the copyright message is dated 1981 then this is ‘old BASIC’ which will henceforth be referred to as Level 1 BASIC, and if the message is dated 1982 then this is ‘new BASIC’ which will be referred to as Level 2 BASIC. Below is an example of a simple machine code program written using the BASIC assembler. 10 20 25 30 40 60 OSWRCH=&FFE3 DIM Mc® 100 DIM data &20 FOR opt%=0 TO 3 STEP 3 Beene’ OPT opt 70 entry 15 80 .loop 90 100 110 120 130 140) 150 LDX LOA JSR INX LDA CPX BNE RTS #0 data OSWRCH data,X #520 loop \ set index count (in X reg.) to 0 \ load first item in accumulator \ perform VDU command \ increment index count \ load next VDU parameter \ has count reached 32 (20) ? \ if not then go round again \ back to BASIC NEXT opt® '=&0000FF38 240 CALL entry ee ee oe er i 21 This program performs some simple graphics using the BASIC VDU method to select the screen MODE and perform PLOTting. All the VDU codes are contained within the block of memory labelled ‘data’. Using the ! operator does not make it immediately obvious what is going on. Four bytes are inserted into memory with each ! operator. The least significant byte being inserted at the address specified. Each subsequent byte is inserted into the next byte of memory. ice. !data=&04190416 data!4=&00C800C8 will result in an equivalent to, VDU &16,&04,&19,&04, &C8,&00,&C8,&00 or, to separate it into its two components, VDU &16,&04 VDU &19,&04,&00C8;&00C8; or VDU 22,4 select MODE 4 VDU PLOT,4,200,200 — move absolute X,Y 25,4,200;200; Any program which can be written in BASIC may also be implemented in machine code although it is not always sensible to do so. There now follows a detailed description of using the BASIC mnemonic assembler. 3.1 The assembler delimiters ‘[’ and ‘J’. All the assembler statements should be enclosed within a pair of square brackets. When the BASIC program is RUN, the assembler statements contained between the square brackets are assembled into machine code. This code is inserted directly into memory at the address specified by P% and P% is incremented by the number of bytes in each instruction or directive. 22 Within the assembler delimiters the text of the assembly language program may be written. The assembly language program will consist of a number of assembler statements separated by new lines or colons (as in BASIC). Each assembler statement should consist of an optional label followed by an instruction (this will be a three letter assembler mnemonic or an assembler directive) and an operand (or address). If a label is included it should be separated from the instruction by at least one space. The operand need not be separated from the instruction. Any character following the operand and separated by at least one space from it will be totally ignored by the assembler which will move onto the next colon or line for the next statement. A comment may be placed after the operand field and should be preceded by an backslash (\). Any text following an backslash in an assembly statement will be ignored by the assembler upto the next colon or end-of-line. N.B. In level 1 BASIC colons cannot be included in expressions. Missing out a colon in a multi-statement line will result in the statement after the intended colon being ignored by the assembler. This error is often difficult to spot in a program which assembles without error but then fails to function as the programmer had anticipated. During assembly of the example program above the following printout is produced (with PAGE=&1900): >RUN 1BEA 1BEA 1BEA 1BEA 1BEC 1BEF 1BF2 OPT opt’ A2 00 entry LDX #0 \ set index count (in X reg.) to 0 BD 5A 1C .loop LDA data,X__\ load next VDU parameter 20 £3 FF JSR OSASCI \ perform VDU command E8 INX \ increment index count 1BF5 00 F5 1BF3 EO 20 CPX BNE loop _—-\ if not then go round again \ has count 1BF7 60 RTS \ back to location. #420 reached BASIC label/mnemonic/address op.code/data PPD dD DNHNSANS A DAD ADD \comment 23 32 (&20) ? 3.2 OPT, assembler option selection OPT is an assembler directive or non-assembling statement which can be included within an assembly program to select a number of different assembler options. The OPT command should be followed by a number to make the option selection. The assembler options are selected on the state of the least significant 2 or 3 bits of the OPT parameter. bit 0 if set, assembly listing enabled. bit 1 if set, assembler errors enabled. bit 2 if set, assembled code placed in memory at O% (Implemented in Level 2 BASIC only) In the example program above OPT is set up using the FOR..NEXT loop variable, opt%. On the first pass of the assembler OPT 0 is used, listing is supressed and assembler errors are not enabled. For the second pass an OPT 3 is used which switches on assembly listing and enables assembler errors. BASIC errors will be flagged as normal. The assembler errors which are supressed are the ‘Branch out of range’ error and the ‘No such variable’ error. These will normally be generated during the first pass when the assembler is resolving forward passes (see section 3.5). Bit 2 allows a program to be assembled into one region of memory while being set up to run at a different address. P%, the program counter (see below) should be set up as usual to provide the source of label values. If bit 2 is set then O% should be set up at the same time as P% to point to the start of memory into which the machine code is to be assembled. This facility is useful for assembling machine code where it is impossible to use the memory in which the program is eventually going to reside (e.g. Assembling programs which are going to be blown into EPROM for paged ROMs). This option is only available in Level 2 BASIC. Each time the assembler is entered the OPT value is initialised to 3. This means that a second chunk of assembler in the same BASIC program must perform its own OPT selection. 24 3.3 The Location Counter P% When the assembler is creating the machine code program the code produced is placed in memory starting from the address in P% (one of the resident integer variables) unless remote assembly has been selected using OPT (see section 3.2). eeaeaFS The programmer must set P% to a meaningful value before the assembly begins. The usual method for short programs is to DIMension a block of memory and to set P% to this value at the beginning of each pass of the assembler (as in the example above). A classic problem is sometimes encountered when a programmer adds more code to a short program which has been allocated space by this method. If the code created overflows the space DIMensioned for it and is over-written by BASIC, it will fail to operate as expected when tested; alternatively the code may over—write the BASIC dynamic storage and a ‘No such variable’ error will be flagged during the second pass of the assembler. The assembler updates P% as it is assembling and when it reaches the end of a pass the value of P% represents the address of the first ‘free’ byte of memory after the machine code program. 3.4 Labels Any BASIC numerically assignable item may be used as a label with the assembler (such as a variable or an array element). A label is defined by preceding the variable name with a full stop. The full stop prefix causes the assembler to set up a BASIC variable containing the current value of P%. Once set up this variable is available for use by any other part of the assembler or BASIC program. 3.5 Forward Referencing and Two Pass Assembly In the construction of a machine code program using the BASIC assembler a large number of labels may be generated. It is often the case that one part of the program needs to jump forward over another part of the program. Labels provide a convenient way of marking that point in the program to 25 DA OA A PAD DADSASN which the processor is to jump. When assembling the machine code, the assembler works sequentially through the program and in the case of a forward reference the assembler will encounter the reference before the label. In the normal course of events an error will be flagged (No such variable). In order to resolve forward references, two passes of the assembler are required. The first pass should be performed with error trapping switched off and during this pass all the labels will be initialised. A second pass will provide all the correct values required for forward referencing. During this second pass error trapping should be enabled to pick up any genuine programming mistakes. The most convenient way of performing the two passes is to use a FOR... NEXT loop. The programmer should make sure that P% is reinitialised at the beginning of the second pass. It is often convenient to set up the pseudo-operation OPT using the FOR loop variable (errors and listing disabled for the first pass, errors enabled and listing as required for the second). 3.6 The EQUate Facility in Level 2 BASIC One of the improvements made to Level 2 BASIC was the incorporation of some EQU pseudo-operation commands. These allow the incorporation of data by reserving memory within the body of the assembly language program. The EQUate operations available are-— EQUB equate byte reserves 1 byte of memory EQUWequate word EQUD equate double word EQUS equate string reserves 2 bytes of memory reserves 4 bytes of memory reserves memory as required These operations initialise the reserved memory to the values specified by the address field. The address field may contain a string, in double quotes, or string variable for the EQUS operation or a number or numeric variable for the other EQU operations. The assembler will use the least significant part of the value if too large a value is specified. 26 The example program, written in Level 2 BASIC, could have been written with lines 30 and 170 to 240 replaced with:— 141 .data BQUD 04190516 142 EQUD s00C800C8 143 EQUD 600000119 144 EQUD 601190064 145 EQUD s000000c8 146 EQUD 600000119 147 EQUD &0119FF9C 148 EQUD s0000FF38 In Level 1 BASIC one way to reserve space for data within the body of a machine code program is to leave the assembler using a right-hand square bracket and insert the data using the address contained in P%. P% should then be incremented by the appropriate amount before entering the assembler. e.g. to incorporate a string into a machine code program. 10 DIM Mct 100 40 FOR opt®=0 TO 3 STEP3 50 PR=MCE i 70 OPT opt® 80 entry LOY #0 \ zero loop index 90 -loop LDA string,¥ \ load accumulator with Y?string 100 JSR OSASCI \ write the character 110 INY \ increment loop index 120 CMP #60D \ is the current character a CR 130 BNE loop \ if not get the next character 140 JSR OSRDCH \ get character from keyboard 150 CMP #9 \ is it the TAB key 160 BNE error \ if not flag an error 170 RTS \ return to