***************************************************************************** *** *** *** MASTER DEVPAC V1.0a *** *** The Documentation File *** *** *** ***************************************************************************** First words: ------------ Ok, you're having one of the most powerful assembler in your drive but you don't know how to use it. That's no problem because we decided to write this little file which should give you advise how to work with the Master Devpac. Please notice that this is only a shortcut of the original Devpac V2.0 docu- mentation (We translate it from German into English)!!! If you like this assembler please consider buying the original!!! At this point we want to send a little message to HiSoft: The only reason why we made this illegal piece of software is that we waited too long for Devpac Professional on the Amiga. On the Atari ST, however, it is available since a long time. So HiSoft, it's really YOUR fault! Believe us: We really don't like to do such illegal stuff (in fact we HATE it!) but with your lazyness you forced us to do it. We are not one of those shitty pirates: We HAVE the original of the Devpac! *************************************************** *** THE EDITOR *** *************************************************** The CLI command line: --------------------- There are several options your can set in command line when you start the editor from CLI: 1> run mgenam2 [...] The options are: '-s' : sets the editor workspace (in kb!) '-x' : maximum of XREF's '+c' : case sensitive while assembly '-c' : lower case '+l' : produces linkable code '-l' : produces executable code '-w' : use window instead of screen Example: 1> run genam2 df0:myfile.s -s50 +c -x200 -l These options tell the editor to allocate 50kb, load the source code 'MyFile' from DF0:. The assembler will produce executable code while assembling with case sensitivity and the maximum amount of XREF's will be 200. The file requesters: -------------------- We included the 'Requester Library' (req.library) instead of the old ARP Lib- rary because this one is much, much better. But if you don't like it you can also work with the old ARP Lib. Just don't copy the req.library in the 'libs' directory of your work disk. A very important thing is that we finally included a 'Delete File' requester. I'm sure you're be happy to hear this! I think there is no need to explain the functions of the file requester, don't you? Key combinations for the editor: -------------------------------- Take a close look at the following because they're very important! CURSOR-UP / CTRL-E : Cursor up CURSOR-DOWN / CTRL-X : Cursor down CURSOR-LEFT / CTRL-S : Cursor left CURSOR-RIGHT / CTRL-D : Cursor right RETURN / ENTER : Return DELETE : Deletes the actual cursor position BACKSPACE : Deletes the char left to the cursor ALT-CURSOR-UP / RIGHT-AMIGA-T : Jump to begin of text ALT-CURSOR-DOWN / RIGHT-AMIGA-B : Jump to end of text ALT-CURSOR-LEFT : Set cursor to begin of line ALT-CURSOR-RIGHT : Set cursor to end of line SHIFT-CURSOR-UP / CTRL-R : Jump one page up SHIFT-CURSOR-DOWN / CTRL-C : Jump one page down SHIFT-CURSOR-LEFT / CTRL-A : Set cursor to begin of left word SHIFT-CURSOR-RIGHT / CTRL-F : Set cursor to begin of right word RIGHT-AMIGA-G : Jump to a special line (requester appears!) RIGHT-AMIGA-Q : Quit the editor CTRL-Y : Delete actual line CTRL-Q : Delete from cursor position till EOL RIGHT-AMIGA-C : Clear source RIGHT-AMIGA-S : Save source with file requester (Save As) RIGHT-AMIGA-SHIFT-S : Save source without file requester (Save) RIGHT-AMIGA-L : Load source/text RIGHT-AMIGA-I : Insert file at cursor position RIGHT-AMIGA-O : Change directory RIGHT-AMIGA-F : Find Requester RIGHT-AMIGA-N : Find next string RIGHT-AMIGA-P : Find previous string RIGHT-AMIGA-R : Replace string F1 : Mark begin of block F2 : Mark end of block F3 : Save block with file requester F4 : Copy block to actual cursor position F5 : Block paste F6 : Lowercase block F10 : Color Requester SHIFT-F3 : Delete block SHIFT-F4 : Block remember SHIFT-F5 : Block remember (?????????????????????) SHIFT-F6 : Uppercase block RIGHT-AMIGA-W : Print block HELP / RIGHT-AMIGA-H : Little help-menu with block functions RIGHT-AMIGA-A : Assemble with requester RIGHT-AMIGA-SHIFT-A : Assemble without requester RIGHT-AMIGA-X : Start assembled programm RIGHT-AMIGA-SHIFT-X : Start programm and enter command line RIGHT-AMIGA-D : Debug (only when monam2 was loaded!) RIGHT-AMIGA-M : Execute Debugger (") AMIGA-J : Jump to next error And now the normal system key combinations: ------------------------------------------- LEFT-AMIGA-M : Screen to front LEFT-AMIGA-N : Screen to back RIGHT-AMIGA-Q : Undo (in string gadget) RIGHT-AMIGA-X : Clear string (in string gadget) Some notes: ----------- - It is possible to set the cursor on the screen with the mouse, too! - You can interrupt the find commands with 'ESC'. - Some people complained that the editor is so slow in scrolling. We think this is no problem: Just use the page up/down function like we do! Miscellaneous to the Preferences: --------------------------------- 'AutoIntend' means that the cursor will be set to the same x-position like in the previous. This is useful when you program with one or two tabs before the mnemonic. Additional we included a new feature: Press SHIFT-RETURN when AutoIntend is off and you have AutoIntend. When AutoIntend is turned on and you press SHIFT-RETURN you have no AutoIntend! Just try it! 'End of Line'. With this flag you can decide whether the cursor should stop at the end of each line or not. 'Full Size'. This is only useful when you prefer a window instead of a screen in the editor. It'll set the window to the maximum size. 'Mem Display'. With this you can decide if there should be displayed the free memory or the used memory in the status line. Calculator instructions: ------------------------ ~ : not - : neg 0-9: Dec % : Bin @ : Oct $ : Hex ' : String (max 4 Chars, right filling) '' = ' im String " : String (max 4 Chars, right filling) "" = " im String shift left,shift right << >> ;Priority 5 and & ;Priority 4 or | ;Priority 4 or ! ;Priority 4 eor ^ ;Priority 4 multiply * ;Priority 3 divide / ;Priority 3 plus + ;Priority 2 minus - ;Priority 2 equal = => <= <> ;Priority 1 The 3D Look: ------------ We decided to use the new 3d look instead of the boring KickV1.3 look. *************************************************** *** The Assembler *** *************************************************** General info: ------------- It has to be placed in the 'c' directory of your workdisk or harddisk (the debugger, too!). Then when you start the editor, the assembler and the debug- ger will be loaded at once, too. The assembler of the Master Devpac is called 'genim2'. It can be executed from the editor. However you also call it from the CLI because it's also a stand-alone assembler. The stand-alone assembler: -------------------------- The command-line looks like this: 1> genim2 MainFile <-options> If the MainFile has no extention the standard extention '.s' will be used. The options are: '-B' : produces no binary file '-C' : no case-sensitive (OPT C-) '-D' : debug (OPT D+) '-L' : linkable code (OPT L+) '-M' : slow assemble mode (Danger: Not the same as OPT M+) '-O' : name of destination file. Follows 'O' without space '-P' : name of listing file. Follows 'P' without space '-Q' : wait until key pressed after assembly '-T' : tabulator set. Amount follows 'T' without space '-X' : extended debug (OPT X+). You need it if only the ex- ported symbols while generating linkable code should be exported (OPT X+) Some examples: genim2 test -b : assembles the file 'test.s' without producing a binary file. That's just a syntax check. genim2 test -oram:test -p : assembles 'test.s' in the file 'ram:test' and produces a listing file called 'test.lst' genim2 test -ldpprt: : assembles 'test.s' in linkable code with complete debug information and sends the listing to the parallel port. The assembly event: ------------------- Genim is a two-pass assembler. You can stop the assembly event text output by pressing any key and can continue with 'return'. With CTRL+C you can interrupt the assembler. But you shouldn't start the binary file because it's incomplete! Labels: ------- Labels normally begin in the first column. The colon (':') after the label is optional. But if the label begins in another column the colon is a must! Labels can begin with the chars a..z, A..Z, umlauts (ä,ö,ü) and the char '_'. Afterwards the chars 0..9 and the full stop ('.') are also allowed. Macro names and register equates mustn't contain full stops! Labels which begin with a full stop or number sequences which end with '$' are local labels. The standard of the significant label bytes is 127. Labels shouldn't have the same names as registers or reserved words like 'SR, CCR or USP'. Some examples of correct labels: test, Test, TEST, _test, _test.end, test5, _5test Some examples of incorrect labels: .test, 5test, _&e, test> In genim there are only the reserved symbols _LK, _RS, _G2 which begin with the '_'. Comments: --------- Every space or tab which isn't in quotation marks and is found after the operands is considered as the begin of the comment area which will be ignored by the assembler. Don't use spaces or tabs between the operands because this can't cause errors easily. Especially after the 'DC'!!! rts ;that's ok! rts;that's wrong! * that's a whole comment line ; that's also a whole comment line Expressions: ------------ Genim allows complex expressions and supports full operator priority, brackets and logical operations. There are two sorts of expressions: absolute and relative expressions. The difference is important. Absolute expressions are constants which are known to the assembler. Relative expressions are program addresses which are not known during the assembly event because the program can be put to any address by the AmigaDOS-Loader. Operators in decreasing priority: - plus sign (+), minus sign (-) - bit NOT (~) - shift left (<<) and shift right (>>) - equal (=), higher as (>) and lower as (<) - AND (&), OR (!) and XOR (^) - multiplication (*), division (/) - addition (+), subtraction (-) The compare operators are ZERO when the expression is FALSE or -1 ($ffffffff) when it's TRUE. Expressions with the same priority will be calculated from left to right. Spaces in expressions (except in strings) are not allowed. All expressions will be calculated in 32 bit arithmetic with sign. There is no overflow test! Numbers: -------- Absolute numbers are possible in different ways: dec (1029), hex ($12f), oct (@730), bin (%1000101), chr ('X') Char constants: --------------- They can have a max. length of 4 bytes. They must begin with '"' or "'", how- ever if you start with quotation marks you must also end with them! The same is for "'"!!! So the following example is incorrect: 'LAME" (!!!!!) Here are some examples: "Q" Q $00000051 'hi' hi $00006869 "Test" Test $54637374 "it's" it's $6974277c 'it''s it's $6974277c The strings in 'dc.b' are subject to the same rules. The char '*' has the value of the counter at the begin of the program and is always relative. General stuff: -------------- The genim knows all common addressing types of the Motorola MC68000. You can write the mnemonics, register-names, etc. in capital letters or in small letters. The register names d0-d7 and a0-a7 can also be expressed as R0-R15. Local labels: ------------- Genim supports local labels. Local labels are labels which are only part of a special part of the source code. The have a leading full stop ('.') and depend on the previous non-local label. Length1: move.l 4(sp),a0 .Loop: tst.b (a0)+ bne.s .Loop rts Length2: move.l 4(sp),a0 .Loop: tst.b -(a0) bne.s .Loop rts In this example there are two local labels with the name '.Loop'. The first belongs to 'Length1' and the second to 'Length2'. To prevent misunderstand- ings with the absolute addressing you mustn't use '.w' and '.l' as local label names. If you want NORMAL labels with a leading full stop you must use OPT U+. Then you can declare local labels with the char '_'. Strings which end with a '$' are also local labels. Symbols and Full stops: ----------------------- There is a little problem when using symbols including full stops in genim. Just look at this example: move.l Vector.w,d0 'Vector' is an absolute value but the assembler thinks it's a label. So this will cause an >undefined label< error. To avoid this you should set the symbol in brackets: move.l (Vector).w,d0 But you can certainly use the full stop after numeric expressions as e.g: move.l $4.w,a6 The Instruction Set: -------------------- Word boundary: All instructions except DC.B and DS.B will be assembled to word boundary. If you also want DC.B use on a word boundary you should use the 'EVEN' instruction. Condidition codes: The alternative condition codes 'HS' and 'LO' equal to 'CC' and 'CS' will be supported in the Bcc, DBcc and Scc instructions. Branches: A BRA.S to the following instruction is not allowed and will be replaced by a NOP! BTST: BTST is unique compared with the other bit instructions, because the PC-relative addressing is allowed. CLR: CLR An is not allowed. Use SUB.L An,An instead (Don't forget: This instructions won't set the flags! CMP: If the source is immediate CMPI will be produced. If the destination is a address-register CMPA will be used. If you use a postincrement in both addressing modes a CMPM will be generated. DBcc: DBRA will be accepted as DBF. ILLEGAL: This instruction will generate the opcode-word $4afc LINK: Genim displays a warning if the value is odd or positive. MOVE from CCR: That's an instruction of the MC68010+ processors. It'll be converted into a MOVE from SR. MOVEQ: Values between 128 and 255 will cause a warning. You can prevent this by using MOVEQ.L! Assembler Directives: --------------------- All the assembler directives can be written in capital or small letters. '<' and '>' declare optional parameters. Assembler Control: ------------------ END: This command sets the end of the source file. Everything which comes after the END will be ignored by the assembler. INCLUDE Filename: This command includes another source code part. The filename must be in the normal AmigaDOS format. If there is a space in it you have to set quotation marks. INCDIR "Directory"<,"Directory" and so on>: This command builds a list of all the directories in which the assembler should search for the include files. This command must stand before the INCLUDE-command! INCBIN Filename: With this command you can include a binary file at this position. So you don't have to convert them into DC-directives. OPT Option <,Option>...: OPT makes it possible to set some assembler flags. The options begin with a char followed by a plus ('+') or minus ('-'). Here's a list of all the available options: ------------------------------------------- OPT A+: The PC-addressing mode will be used whenever possible. If you want to skip this function in some parts of your program you should set the expression in brackets followed by '.L'. OPT C : Sets case-sensitive mode. This option has should stand at the BEGINNING of your source! If you use OPT C- the source will be assembled without case-sensitive. You also can set the significant bytes of the labels with e.g. 'OPT C16+' (Now 16 bytes of the label- name are significant. OPT D : Debugging information. If you use 'OPT D+' genim will create a debug hunk after the normal hunks of your program. This is very useful while debugging because you can work with the real label names instead of memory addresses. But don't forget to remove this hunk before you spread you program because it's VERY easy to make a source code out of it again!!! OPT L : If you use the option 'OPT L+' genim will produce linkable code instead of executeable code. This directive MUST stand at the FIRST line of the source!!! OPT M : 'OPT M+' is called macro-expansion. This will change the assembler listing a little bit because the whole MACRO calls will be replaced by the real macro code. With 'OPT M-' you can turn this off. OPT N : Narrow listing. This option is used for printers which can't print more than 80 chars in one line. So this option will produce a listing without line numbers and object code. Use 'OPT N-' to change to normal mode. OPT O : Optimize option. OPT O1+ : Optimizes backwards branches when possible. Turn of with O1- OPT O2+ : Optimizes 'move.l Value(a0),d3' in 'move.l (a0),d3' when Value is NULL. OPT O+ : Turns on all optimizations OPT O- : Turns them off OPT OW- : The warnings concerning the optimization will be skipped. OPT P : This option checks whether the code is pc-relative or not. Turn off with 'OPT P-'. OPT S : 'OPT S+' turns the symbol table in the assembler listing on. You should turn this function off when using include files because the symbol table will become very long. OPT T : Type Check. Genam can detect bugs in your programs by checking your expressions. It checks whether they are absolute or relative. You can turn on the Type Check with 'T+' and off with 'T-'. OPT U : If you use this option local labels have to begin with '_' instead of the full stop. OPT W : You can turn the warnings off with 'W-' OPT X : Extended Debug. With this optinion on symbols will be put out with a length of 22 instead of 8 chars. EVEN bounds the program counter to an even address (word boundary!). You don't need EVEN very often because genim bounds all commands on word boundary automatically! But in spite of this it's better to use then EVEN command in every case! CNOP offset,boundary. I don't explain this because everybody should know it. FAIL. This is used to produce a user error. You can let the assembler fail if there are e.g. too much macro arguments. OUTPUT filename. With this you can set the name of the output file. REPT/ENDR. This is a repeat loop. An example: REPT 512/4 ;Fast copy of sector data move.l (a0)+,(a1)+ ENDR These three lines let the assembler assemble the line 'move.l (a0)+,(a1)+' 128 times. So you don't have to write this line 128 times in your source. But don't try to define labels between a REPT/ENDR loop because this makes a 'label defined twice' error appear! Listing control: ---------------- Here's only a little overview over these commands because I think this isn't very useful... (Buy the original if you what the complete docs! Hehe) LIST : Listing on NOLIST : Listing off LLEN : Set page length PLEN : Set line length TTL : Set title SUBTTL : Set subtitle SPC : Give out space PAGE : Page feed LISTCHAR : Give out control char FORMAT : Definies listing format Label instructions: ------------------- Label EQU expression : Same as 'Label = expression' Label EQUR Register : With this instruction you can give a register a special name. Don't forget to define the register equate before using it! Label SET expression : Nearly the same as EQU. There is one difference: You can give a label different values in one source! That means that the value of the label can change after some lines. Label REG Registerlist : This is used to prevent mistakes with the movem command. You can simply write later in the source: MyRegs REG d0-d7 movem.l MyRegs,-(sp) and movem.l (sp)+,MyRegs is the same as: movem.l d0-d7,-(sp) and movem.l (sp)+,d0-d7 RS. This is used to define offsets. Here an example: rsreset Blub: rs.l 1 Hugo: rs.w 1 Bert: rs.b 1 Now you can read out of the list with: (a0 has to point at the beginning of the list) move.l Blub(a0),d0 ;Blub=0 move.w Hugo(a0),d1 ;Hugo=4 move.b Bert(a0),d2 ;Bert=6 I think that's a very useful instruction. RSRESET. This instruction resets the counter. RSSET. Sets the counter to a special value. RS. This is a reserved symbol. It always contains the actual value of the rs-counter. Conditional Assembly: --------------------- Conditional assembly allows you to write a program that has many internal options, which you can choose while assembly. This can be very useful for different reasons: - The program shall work on two machines - You want to insert debug-code - Two slightly different versions of one program are needed These directives were all needed while developing the Devpac. At the beginning of a comditional block must be one of the many IF-directives. IFEQ Expression IFNE Expression IFGT Expression IFGE Expression IFLT Expression IFLE Expression The Expression is calculated and the compared with 0 and then the conditional assembly is switched on or off depending on the result of the expression. Example: DEBUG has the value 1 IFEQ DEBUG logon dc.b "enter command: ",0 EDNC IFNE DEBUG opt d+ logon: dc.b "come on!",0 ENDC In this case the first part is not assembled because 1 is not equal (not EQ) 0 and the second part is assembled because 1 is not equal (NE) 0. IFD Label IFND Label This directive allows you to check the existence of the 'Label'. If you use IFD the assembly will be turned off if 'Label' exists. IFC 'String1','String2' This directive allows you to let the assembly depend on the contents of two strings. If both are equal the assembly will be turned on. IFNC 'String1','String2' Same as above except that the assembly will be turned off if the strings are equal. ELSEIF With this directive you can turn the conditional assembly on/off. ENDC This terminates the actual IF-level. (it's like ENDIF in BASIC) IIF expression command This is a special kind of the IF instruction. It's only used for ONE command. So it's a short form if the IF instruction. BTW: You shouldn't terminate IIF with ENDC. Macro Operations: ----------------- Macro's in Devpac can handle up to 36 different parameters. Label MACRO This instruction starts the macro definition. All the following lines will be copied into the macro buffer until the ENDM instructions appears. ENDM This instruction terminates the macro definition. You can't define a label in a line which contains the ENDM instruction. MEXIT Terminates the macro development. NARG This is a reserved symbol. It contains the amount of values which each macro call has or ZERO if the assembler isn't in a macro. Note: You have to write NARG in capital letters. Each macro parameter has a number (from 1 to 36). Before every number there has to be a backslash '\'. There is one exception: \@ is also a valid macro parameter. This will create different labels by every macro call. Here an example: WAITBLIT MACRO .\@: btst #6,$dff002 bne.s .\@ ENDM You can use this macro as often as you want: There won't be a 'label defined twice'-error. Sections: --------- Section string,. String is the section name. Here are the different section types: CODE Code-section, Public Memory CODE_F Code-section, Fast Memory CODE_C Code-section, Chip Memory DATA Data-section, Public Memory DATA_F Data-section, Fast Memory DATA_C Data-section, Chip Memory BSS BSS-section, Public Memory BSS_F BSS-section, Fast Memory BSS_C BSS-section, Chip Memory Example: section MyProgram,code_c When you chose this section type the AmigaDOS loader will always load your program in CHIP memory. That's very useful! *************************************************** *** Monam - The Debugger *** *************************************************** Here a little overview over all Monam commands. Sorry but we have really no time to translate the whole documentation! (Give me a scanner...) Window-Commands: ---------------- RIGHT-AMIGA-A : Set Start Address RIGHT-AMIGA-B : Set Breakpoint RIGHT-AMIGA-E : Edit Window RIGHT-AMIGA-F : Font Size RIGHT-AMIGA-L : Bind Window RIGHT-AMIGA-O : Calculate expression RIGHT-AMIGA-P : Printer dump RIGHT-AMIGA-R : Set register RIGHT-AMIGA-S : Split window RIGHT-AMIGA-T : Change Window type RIGHT-AMIGA-Z : Zoom window Breakpoints: ------------ RIGHT-AMIGA-B : Set Breakpoint HELP : Breakpoint and Segment overview CTRL-B : Set Breakpoint U : Go until CTRL-K : Delete all Breakpoints CTRL-A : Set Breakpoint and execute CTRL-X : Stop execution Load and Save: -------------- CTRL-L : Load executable B : Load binary S : Save binary A : Load ASCII and execute programs Program execution: ------------------ CTRL-R : Back to program/Run CTRL-Z : Single Step CTRL-Y : Single Step CTRL-T : Trace R : Run (different types) Memory peeker: -------------- G : Search in memory N : Next occurence Miscellaneous: -------------- CTRL-C : Break CTRL-Q : Quit CTRL-P : Preferences I : Intelligent copy W : Fill memory L : Show Labels CTRL-U : Deallocate Symbols P : Disassemble to printer/disk M : Change address O : Evaluate D : Change drive and path H : Show history