http://wiki.amigaspirit.hu/index.php/Amiga_Machine_Language_(Chapter_3) Chapter 3. --------- 3.Working With Assemblers. ------------------------- 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.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.