Chapter 3. --------- 3.Working With Assemblers. ------------------------- The instructions that you've learned so far are incomprehensible to the MC68000 processor.The letters MOVE mean absolutely nothing to the processor-it needs the instructions in binary form.Every instruction must be coded in a word-which normally takes a lot of work. An assembler does this work for you.An assembler is a program that translates the instructions from text into the coresponding binary instructions.The text that is translated is called Mnemonic or Memcode.Its a lot easier working with text instructions-or does $4280 mean more to you than CLR.L D0? This chapter is about working with assemblers.We'll describe the following three: ASSEM; This is the assembler from the Amiga's development package.This assembler is quite powerful,but it is clearly inferior to its two fellow compilers in some areas. AssemPro; This is the Abacus assembler.It has a debugger in addition to the assembler.This lets you test and correct programs.In our opinion, it is the best one to use for writing and testing practice programs.For this reason,we wrote the programs in this book with this assembler. KUMA-SEKA; This is a popular assembler which also has a debugger. All assemblers perform a similar task-they translate memcode,so that you can write a runable program to disk.To test the program directly,you need a debugger which is something Assem doesn't have. 3.1.The Development Assembler. ----------------------------- This assembler is a plain disk assembler.That means that it can only assemble text files that are on disk and write the result back to disk.You can't make direct input or test run the new program. You can call ASSEM from the CLI by typing ASSEM followed by parameters that specify what you wish the assembler to do. In the simplest case,you call it like this: ASSEM Source -O Destination Source is the filename of the file containing the program text. Destination is the name of the file that contains the results of assembling after the process is over.The "-O"means that the following name is used for the object file. There are several other parameters that can be passed.These are written with their option(ie-O),so that the assembler knows what to do with the file that you've told it to use.The following possible options must be followed by a filename. -O Object file -V Error messages that occur during assembling are written to a file.If this isn't given,the error messages appear in the CLI window. -L The output of the assembled program lines are sent to this file.You can also use"PRT:"to have it printed. -H This file is read in at the beginning of the assembled file and assembled along with it. -E A file is created that contains lines which have EQU instructions. -C This option isn't followed by a filename but by another option.You can also use OPT to do this.The following options are available: OPT S A symbol table is created which contains all the labels and their values. OPT X A cross reference list is created(where labels are used). OPT W A number must follow this option.It sets the ammount of workspace to be reserved. The assembler creates an object file.This is not runnable.To make it runnable,you need to call the linker,ALINK.This program can link several assembled or compiled object files together to make a runnable program.In the simplest case,you enter the following instruction in the CLI: ALINK Source TO Destination Source is the object file produced by the assembler.Destination is the name of the program.It can be started directly. 3.2.AssemPro. ------------ Abacus's AssemPro is a package which combines editor,assembler and debugger in an easy to use package. The AssemPro Program is divided into several windows-one for the assembler,the editor,the debugger and several help functions. Producing a program is very easy: 1) Write the program with the editor and then store it to disk. 2) Start the assembler,so that the program is translated. 3) If desired,start the debugger,load the program and test it. Within the debugger you can work through parts of the program or even through single commands.As after each one of these steps the debugger shows you the state of the registers and flags in the status register,you can easily try the programs presented in this book. You need to load AssemPro only once when working with machine language programs.Thus you don't need to save back and to between editor,assembler,linker and debugger. AssemPro has an especially interesting function:the reassembler. With this debugger function you are able to convert runnable programs into the source text of the program.Once you have made the source text,you can edit the program using the editor and assemble it again.AssemPro is equipped with functions other assemblers miss.There are however,some differences you should know about.As many programs you see were written for the K-SEKA,be aware of one difference:the EVEN command.AssemPro uses the ALIGN instruction. Note,that when entering and assembling one of the programs in AssemPro you must make sure that you place an END directive at the end of the source text. The following is an introduction into working with AssemPro and the programs in this book. Start AssemPro normally,next click on the editor window and start typing in your program.If the program is on disk already,load it by selecting the appropriate menu or by using the key combination right key and .To do this you only need to ckick on the filename in the displayed requester and click on the OK gadget. Once you have typed in or loaded the program into the editor,you can assemble it.It is best to save your source before assembling. You assemble your program by clicking on the assembler window displayed above the editor window and pressing and .You can then choose how to locate your program in the memory.Remember that data used by the co-processors must be located in CHIP RAM. By clicking OK you start the assembler process.If you additionally select "breakable",you can cancel the process by pressing both shift keys.If any error occurs during assembling,AssemPro uses a window to tell you this.Use this window to correct the error and continue with "Save and try again". Now the runnable program is located in the Amiga's memory.Use the menu item "Save as"to save it on disk.If you want to store it on RAM disk,click the given filename and enter RAM: in front of this name.In addition you can click on the menu item "ICON"and choose if you only want the program itself on disk but the icon too.Use this icon to start the program at a later time from Workbench. To test-run the program,you move the debugger window to the foreground of the screen(for instance by clicking on the back gadget).Use "Load"in the debugger menu or to call the select file window,where you select the saved program.The program is then loaded into the memory and its shown disassembled. The highlighted line(orange)represents the current state of the program counter.This is the line where the processor reads its next instruction,provided you tell the processor so.There are three ways to do so. The first one is to start the program with "Start".This alternative does not enable you to stop the program if anything goes wrong. The second possibility,"Start breakable"is better in this respect. After the program starts,it continuously displays the registers contents on the left side of the window.In addition to that you can cancel the process by pressing .Note that this only works if your program doesn't use the key itself. The third possibility enables you to only partly run your program. You can do this by stepping through the program or by placing breakpoints throughout the program.You place these by clicking on the desired address and then pressing ."BREAKPOINT"is displayed where the command was displayed before.If you start the program now,it stops whenever it comes across any breakpoints. You can start a small part of the program by moving the mouse pointer to the orange line,clicking the left button and holding it down while you drag the mouse pointer downward.If you release the button,the processor works through this part of the program, stopping at the line,where you positioned the mouse pointer.This is a very useful method to step by step test a program. AssemPro as another helpful window:the Table.This window lists the valid address methods for instructions and the parameters of Amiga functions.This is extremely helpful whenever you are not sure about one of the instructions. 3.3.The K-SEKA Assembler. ------------------------ The SEKA assembler,from KUMA,has a simple text editor and a debugger in addition to the assembler.This program is controlled by simple instructions and it is easy to use.It is also multi- functional and quick,so it is great for small test and example programs.You can use it to write bigger programs once you've got use to the editor.Now lets look at the editor. To load a program as source code(text)into the editor,enter"r" (read).The program asks you for the name of the file with the ""prompt.You then enter the name of the text file.If you created the file with SEKA,the file is stored on disk with".s" on the end of its name.You don't need to include the".s"when you load the file.Thats taken care of automatically.("s"stands for source.) You can store programs you've just written or modified by using the"w"instruction.The program asks you for the name.If you enter "Test",the file is written to the disk with"Test.s"as its name. This is a normal text file in ASCII format. There are two ways to enter or change a programs:using the line editor or the screen editor.You can enter the second by hitting the key.The upper screen section is then reserved for the editor.You can move with the cursor keys and change the text easily.The lines that you enter are inserted into the existing text and automatically numbered.By hitting the key again,you leave the screen editor. There's really not much to say about this editor.It's really just for simple insertions and changes.Other functions are called in normal instruction mode,the mode in which">"is the input prompt. The following instructions are available to you for text editing (stands for a number.The meaning of the instructions is in parenthesis.) Instruction Function ---------------------------------------------------------------- t(Target) Puts the cursor on the highest line in the text. t Puts the cursor on line n. b(Bottom) Puts the cursor on the last line in the text. u(Up) Go up one line. u Go up n lines. d(Down) Go down one line. d Go down n lines. z(Zap) Deletes the current line. z Deletes n lines starting at the cursor line. e(Edit) Lets you edit the current line(and only that line). e Edit from line n. ftext(Find) Searches for the text entered starting at the current line.The case of a letter makes a difference,so make sure to enter it correctly. Blanks that appear after the f are looked for as well! f Continues searching beyond the text that was previously given. i(Insert) Starts the line editor.Now you can enter a program line by line.However,you can't use the cursor to move into another line.Line numbers are generated automatically.The lines that follow are moved down,not erased. ks(Kill Source) The source text is deleted if you answer"y" when the program asks if you are sure.Otherwise nothing happens. o(Old) Cancels the "ks"function and saves the old text p(Print) Prints the current line. p Prints n lines starting at cursor line. Those are the K-SEKA's editor functions.In combination with the screen editor,they allow for simple text editing.You can,for example,delete the current line(and other lines)while working in the screen editor by hitting to get into instruction mode and then entering"z"(or "z"). If you'd like to edit all lines that contain "trap",for example, you can do the following: -Jump to the beginning of the text using "t" -Search for a "trap"instruction by entering "ftrap" in the first line. -Press and edit the line. -Press again to get into instruction mode. -Search using "f",,etc.until you get to the end of the text. This sounds very clumsy,but in practise it works quite well and goes quickly.Experiment with the editor bit,so you can get use to it. Now here are the instructions for working with disks: Instruction Function ----------------------------------------------------------------- v(View files) Look at the disk's directory.You can also include the disk drive or subdirectory that interests you.For example,"vc"causes the "c"subdirectory to be listed and makes it the current directory. kf(Kill file) The program asks for the name of the file. The file is deleted(and you aren't asked if your sure either-so be careful). r(Read) After inputting this instruction,you'll be asked which file to load(FILENAME>).The file that you specify is then loaded.If only "r"is entered,a text file is loaded in the editor. ri(Read Image) Loads a file into memory.After you've entered the filename,SEKA asks for the address the file should begin at in memory (BEGIN>)and the highest address that should be used for the file(END>). rx(Read from Auxillary) This works just like the "ri"function except that it reads from the serial port instead of from disk(You don't need a file name). rl(Read Link file) This instruction reads in a SEKA created link file.First you'll be asked if you are sure,because the text buffer is erased when the link file is loaded. w(Write) After entering this instruction,you'll be asked for the name of the file the text should be written to.A".s"is automatically appended to the name,so that it can be recognized as a SEKA file. wi(Write Image) Stores a block of memory to disk after the name,beginning and end are entered. wx(Write to Auxillary) This is similar to"wi";the only difference is that the output is to the serial inter- face. wl(Write Link file) Asks for the name and then stores a link file that was assembled with the"I"option to disk.If this isn't available,the message "* * Link option not specified" appears. Once you've typed in or loaded a program,you can call the assembler and have the program translated.Just enter"a"to do so. You'll then be asked which options you want to use.If you enter a ,the program is assembled normally-ie the results of translating a program in memory is stored in memory.Then the program can be executed straight away. You can enter one or more of the following options,however: v The output of the results goes to the screen. p or e goes to the printer with a title line. h The output stops after every page and waits for a key stroke.This is useful for controlling output to the screen or for putting new sheets of paper in the printer. o This option allows the assembler to optimize all possible branch instructions.This allows the program code to be shorter than it would otherwise be.Several messages appear but you can ignore them. l This option causes linkable code to be produced.You can save it with the"wl"instruction and read it with the "rl" instruction. A symbol table is included at the end of the listing if desired. The table contains all labels and their values.It also contains macro names.A macro allows several instructions to be combined in to a single instruction. For example,suppose you wrote a routinethat outputs the text that register A0 points to.Every time you need to use the routine,you must type: lea text,a0 ;pointer to text in A0 bsr pline ;output text You can simplify this by defining a macro for this function.To do this,put the following at the beginning of the program: print:macro ;Macro with the name "Print" lea ?1,a0 ;Parameter in A0 bsr pmsg ;Output text endm ;End of macro Now,you can simply write the following in your program: print text ;Output text This line is replaced using the macro during assembly.The parameter "text"is inserted where "?1"appears in the macro.You can have several parameters in a macro.You give them names like "?2", "?3",etc... You can also decide whether you'd like to see the macros in the output listing of the assembler.This is one of the pseudo-ops that are available in the assembler.The SEKA assembler has the following pseudo-ops: dc Defines one or more data items that should appear in this location in the program.The word length can be specified with .B,.W,or .L-and if this is left off, .B is used.Text can be entered in question marks or apostrophes.For example:dc.b "Hello",10,13,0 blk Reserves a number of bytes,words or long words,depending on whether .B,.W,or .L is chosen.The first parameter specifies the number of words to be reserved.The second (which is optional)is used to fill the memory area.For example:blk.w 10,0 org The parameter that follows the org instruction is the address from which the (absolute) program should be assembled.For example: org $40000 code Causes the program to be assembled in relative mode,the mode in which a program is assembled starting at address 0.The Amiga takes care of the new addressing after the program is loaded. data This means that from here on only data appear.This can be left out. even Makes the current address even by sometimes inserting a fill byte. odd The opposite of even-it makes the address odd. end Assembling ends here. equ or Used for establishing the value of a label = For example: Value=123 or Value:equ 123 list Turns the output on again(after nlist).You can use the following parameters to influence the output: c Macro calls d Macro definitions e Macro expansion of the program x Code expansions For example: list e nlist Turns off output.You can use the same parameters here as with "list". page Causes the printer to execute a page feed,so that you'll start a new page. if The following parameter decides whether you should continue assembling.If it is zero,you won't continue assembling. else If the "if"parameter is zero,you'll begin assembling here. endif End of conditional assembling. macro Start of a macro definition. endm End of macro definition. ?n The text in the macro that is replaced by the nth parameter in the calling line. ?0 Generates a new three digit number for each macro call- this is very useful for local labels. For example: x?0:bsr pmsg illegal Produces an illegal machine language instruction. globl Defines the following label as globel when the "I"option of the assembler is chosen. Once you've assembled your program,the program code is in memory. Using the "h"instruction,you can find out how large the program is and where it is located in memory.The beginning and end address is given in hex and the length in decimal(according to the last executed operations): Work The memory area defined in the beginning Src Text in memory RelC Relocation table of the program RelD Relocation table of the memory area Code Program code produced Data The program's memory area You'll find program in memory at the location given by Code.It's a pain to have to enter this address whenever you want to start the program.It make's good sense to mark the beginning of the program with a label(for example,"run:").You can use the "g"instruction to run the program as follows: g run The"g"(GO)instruction is one of SEKA's debugger instrucions.Heres an overview: x Output all registers. xr Output and change of registers(ie xd0) gn Jump to address n.You`ll be asked for break points,addresses at which the program should be terminate. jn This is similar to the one above-a JSR is used to jump into the program.The program must end with a RTS instruction. qn Output the memory starting at address n.You can also specify the word length.For example: q.w $10000 nn Disassembled output starting at address n. an Direct assembling starting at address n.Direct program instructions are entered. nn Modify the contents of memory starting at address n.Here too the word length can be given.You can terminate input with the key. sn Executes the program instruction that the PC points to.After you enter this instruction,n program steps are executed. f Fill a memory area.You can choose the word width.All the needed parameters are asked for individually. c Copies one memory area to another.All the needed parameters are asked for individually. ? Outputs the value of an expression or a label. For example: ?run+$1000-256 a Sets an instruction sequence that is passed to the program when it starts as if it were started from CLI with this sequence. ! Leaves the SEKA assembler after being asked if your sure. You saw some of the calculations like SEKA can make in the "?" example.You can also use them in programming.The folowing operations work in SEKA: + Addition - Subtraction * Multiplication / Division & Logic AND ! Logic OR ~ EXclusive OR (XOR) These operations can also be combined.You can choose the counting system.A "$"stands for hexadecimal,"@"for octal,and "%"for binary. If these symbols aren`t used,the number is interpreted as a decimal number. Lets go back to the debugger.As mentioned,after entering "g address",you`ll be asked for break points.You can enter up to 16 addresses at which the program halts.If you don`t enter break points,but instead hit ,the program must end with an ILLEGAL instruction.If it ends instead with a RTS,the next return address from the stack is retrieved and jumped to.This is usually address 4 which causes SEKA to come back with "**Illegal Instruction at $000004",but theres no guarantee that it will.Your computor can end up so confused that it can`t function. The SEKA program puts an ILLEGAL instruction in the place specified as break points after saving the contents of these locations.If the processor hits an illegal instruction,it jumps back to the debugger by using the illegal instruction vector that SEKA set up earlier.Then SEKA repairs the modified memory locations and then displays the status line.Here you can find out where the program terminated. Using break points is a good technique for finding errors in the program.You can,for example,put a break point in front of a routine that you`re not sure about and start the program.When the program aborts at this spot,you can go through the routine step by step using the "s"option.Then you can watch what happens to the status line after each instruction and find the mistake. Program errors are called bugs.That`s why the program that finds them is called a debugger.