TCE Demo 2

home *** CD-ROM | disk | FTP | other *** search

/ TCE Demo 2 / TCE_DEMO_CD2.iso / demo_cd_.2 / mags / stosser / stoser08.arj / stoser08.msa / ISSUE_8 / 9.PNE < prev

Wrap

Text File | 1987-04-22 | 19KB | 588 lines

WRITING STOS EXTENSIONS - PART 1 of 3 ===================================== By Martin Cubitt for STOSSER disczine This small series takes a look at how to write an extension for STOS. A reasonable knowledge of assembly language is assumed. Firstly may I emphasise that this is not a definitive set of rules and I am certainly no expert on the subject. If you want to get the full details of writing STOS extensions then I suggest you write to Manadarin or Francois Lionet. The only documentation I have on the subject are three similar articles which appeared in the STOS Newsletter issues 8,9 and 10. I have been unable to obtain the Game Makers Manual which apparently has further information of the subject. Don't worry though. I do know enough to get you started! We will be writing an interpreter extension and then a compiler one. Finally we will write an installer program, just a simple one, so that we can add a little professionalism to our extension. Let's start with a little background on STOS extensions. STOS can only handle 26 extensions, using the letters A-Z. many of these are already in use and some have been reserved by Mandarin. Here is a small list of some extensions already defined by Mandarin: A - Compactor extension B - A bug in version 2.3 of STOS prevents this being valid! C - Compiler extension D - Maestro extension E - Squasher extension G - reserved H - reserved M - Musician extension Q - reserved R - reserved V - VIDI extension Many third part extension writers have used further extension id's: F - Double joystick extension G - Blitter extension H - Start extension M - Misty extension Q - Missing link extension part 1 R - Missing link extension part 2 S - Missing link extension part 3 T - TOME extension Z - EXTRA extension As you can see many third part programmers have ignored (or not known about) the standard laid down by Mandarin and clashed with existing or reserved id's. If Mandarin decide to use these reserved extension id's the third part extensions will not work and any BASIC program will be useless. So, be warned. There are still plenty of letters left to use, namely I,J,K,L,N,O,P,U,W,X and Y. Plus, some extensions may become obsolete or used rarely, like the TOME extension. I doubt a lot of people use it so if you become desperate for a letter to use I suggest you use one which is being used for a rarely used extension. Do not, however, be tempted to use the Mandarin-defined extensions with the exception of F (the extension is pretty much unused now). Before we start I must point out that I the source provided was written in Devpac 3.10 so you will need to convert anything your assembler does not like. Devpac is easily the most popular assembler so there should not be too many problems. Right, back to writing the actual extensions... Once you have decided your letter we can continue. The example extension for this article uses letter W. The interpreter version will be EG.EXW and the compiler will be EG.ECW. Please not that a command may accept parameters but never returns any whereas a function does return a value but may also accept them too! Take the following STOS commands/extensions: screen copy 5 to physic - command A=rnd(5) - function print A - command B=A/2 - function Throughout the series I will refer to both commands and functions just as commands unless this be incorrect! First thing to do is decide on what commands you want to have in your extension. For this example I am going to create one new command and two functions. You should first decide what the command should do and then decide on the command name. Remember that the command may not contain any embedded reserved word or command. Therefore you could not use the command printer status as the reserved command print is present. Personally I like to load up STOS and type my new command (yes, before I have written it) and if it appears ALL in upper case it will be okay. New command: eg This will display, on screen, a list of the commands available in the EG extension with a small description of each. This is extremely useful as a quick reference guide and can be found in the EXTRA extension by simply typing extra. New functions: =ndrv This returns the number of drives attached to the system. It ignores the internal drive as that has to be there anyway. It will include any RAM discs or hard drives attached. =range(A,B,C) This returns a value reflecting A in the range B to C. If A < B then =B else If A > C then =C else =A So we have decided on the new commands now. At this point I would decide on an apt name for the extension. I have called this extension EG as it is an example extension but a more descriptive name may have been the Pot Pourri extension as it contains various commands. As I am not the best person to explain things I have decided its examples all the way. I have loaded the EGINT.S file into this article and will now break it down further... Programmers all program using different methods so feel free to use your own programming techniques and commenting procedure. I think it is important to start your program with basic information... * Source name .......: EGINT.S * Object name .......: EG.EXW * Author ............: Martin Cubitt * Date ..............: 13th Oct 1993 * Description .......: Example STOS Interpreter extension * Contains 1 new command and 2 new functions:- * * (Remember that a function returns a value) * * * eg - this command displays the command * list of the EG extension. I think * all new extensions should have a * similar command as an on-line * reference to commands available. * * A=range(A,B,C) - a function which returns a value * based on A in the range B to C. If * A is less than B then A will become * the value of B. If A is greater than * C then A will become the value of C. * If the value of A >=B and <=C then * it will be unchanged. * * A=ndrv - this function returns the number * drives attached to your system (and * are available or turned on). If you * have the internal, one external and * a RAM disk the value will be 2 * because the internal drive is * assumed anyway. Well, that's the intro over with let's get down to the meat of the program... When STOS installs the extension it initialises any variables and sets any flag required by it. STOS call the start of your program which should be a BRA operation, pointing to your initialisation routine. * Jump to initialisation routine bra.s INIT * Create token list for commands/functions * Remember commands have even token numbers and functions odd ones The following byte is, presumably, a sort of marker used by STOS. * The following byte value of 128 is simply required by STOS dc.b 128 All commands use even numbered token where functions use the odd numbered tokens. The first token MUST be 128. This means the commands can use token number 128 - 254 and functions 129 - 255. The token is used internally by STOS as a reference to each command for each extension. Tokens 160 and 184 may not be used but I do not know why. I have used them with no problems! When entering your token/command list note the following: The command names MUST be in lower case. They can contain most characters including spaces. All character are significant so 'disc verify on' and 'disc verify off' will be treated as two completely separate commands as far as STOS is concerned. They cannot contain reserved words or commands. * Ensure your new command/function names are lower case and do not * contain any embedded reserved words such as 'printer value=...' as * this contains print and val! TOKENS: dc.b "eg",128 dc.b "range",129 dc.b "ndrv",131 Note that token 130 is not used but if I wanted another command it would go there. The token list is terminated with a 0. dc.b 0 The even instruction ensure that the next piece of code is assembles on an even boundary, nothing to do with STOS but necessary as a lot of byte declarations are used. even The jump table is a simple address look-up table which point to where each command is in memory. Although assembled as offsets STOS re-calculates actual address when your extension is installed. If any tokens were not used in the token list you must still store a dummy in the jump table for the non-used tokens. So I must include such a dummy for token 130. * Create the jump table * This extension has THREE new commands (or functions) and ONE dummy! JUMP: dc.w 4 dc.l EG dc.l RANGE dc.l DUMMY dc.l NDRV Next up you enter the message to be displayed when your extension is installed. Try to keep them short (unlike Misty & Missing Link) so that the previously installed extensions do not scroll up the screen where they are lost forever! Besides, they take up unnecessary memory. You actually need two messages. The first is for those who use English STOS and the second for those who use French STOS. You may use control character to get inverse image or underline but it would not be a good idea to clear the screen or something as all other install messages would vanish then! * Message to be shown when extension installed in STOS * First message for ENGLISH * Second for FRENCH MESSAGE: dc.b 10,10,"Example extension for STOSSER Disczine",0 dc.b 10,10,"Extension Example de STOSSER",0 A 0 byte terminates the messages dc.b 0 even Next we must define two variables which will be used later by the extension. The SYSTEM variable will hold the address of the STOS system routines. SYSTEM: dc.l 0 This will be used to hold the return address from where your command was called so that STOS can retake control when your command has finished. RETURN: dc.l 0 The initialisation routine is the first this executed by STOS when your extension is installed. It does two things. Firstly, it moves the address of the end of the extension into register a0. Secondly it moves the address of the cold start routine into the register a1. A return (rts) instruction finishes the routine. The label EXIT is used to hold the last address of the extension. INIT: lea EXIT,a0 lea COLDST,a1 rts The cold start routine actually performs some internal setting up by STOS regarding the extension. The routine passes the addresses of the messages, warm start routine, the token table and the jump table. The warm start routine is used to reset variables used in the extension when UNDO is pressed twice. COLDST: move.l a0,SYSTEM ; save address of STOS' system table lea MESSAGE,a0 lea WARM,a1 lea TOKENS,a2 lea JUMP,a3 WARM: rts Great, that is the interpreter header finished. Easy, eh? Next up we need to write the actual commands themselves. * eg command EG: Save the return address so STOS can return to where it was when the command was called. move.l (a7)+,RETURN Check data register d0. This holds the number of parameters which were passed. cmpi.w #0,d0 ; expect no parms bne NOPARMSERR Save stack, safe not sorry! movem.l a0-a6,-(a7) lea EGINFO(pc),a0 move.w #1,d7 trap #3 Restore stack. movem.l (a7)+,a0-a6 Allow a smooth return back to STOS. move.l RETURN,a0 jmp (a0) * Range function RANGE: move.l (a7)+,RETURN ;save return address cmpi.w #3,d0 ; expect 3 parms bne.s RANGEPARMERROR get each parameter form stack. d3 will hold the value of the returned parameter. bsr.s GETPARM move.l d3,d0 ; C bsr.s GETPARM move.l d3,d1 ; B bsr.s GETPARM move.l d3,d2 ; A movem.l a0-a6,-(a7) ;save stack cmp.l d1,d2 blt.s TOO_LOW ; A<B so A=B cmp.l d2,d0 bge.s OKAY ; Leave A as is move.w d0,d2 ; C<A so A=C bra.s OKAY TOO_LOW: move.w d1,d2 OKAY: move.l d2,d0 bsr.s SAVEPARM ;return parm/s movem.l (a7)+,a0-a6 ;restore stack move.l RETURN,a0 ;end routine jmp (a0) * Number of drives function NDRV: move.l (a7)+,RETURN ;save return address cmpi.w #0,d0 ; expect no parms bne.s NOPARMSERR movem.l a0-a6,-(a7) ;save stack moveq.l #0,d0 move.w ($4a6),d0 bsr.s SAVEPARM ;return parm/s movem.l (a7)+,a0-a6 ;restore stack move.l RETURN,a0 ;end routine jmp (a0) * Routines... Parameters are passed to your extension from STOS via the stack. They need to be pulled off in order to store them elsewhere. The following routine get an integer parameter only. Data registers d2,d3 and d4 hold information about each parameter pulled from the stack. They are stored in the following format: d2=0 - Integer d3=integer number d4=0 - not used d2=$40 - Real (floating point) d3=Top half of number d4=Bottom half of number d2=$80 - String d3=Address of string d4=0 - not used Remember that STOS string are not standard and are not terminated with a zero, as 68000 strings are. The first word of a STOS string holds the length of the string and then the string follows this. You will need to convert or code very carefully if you wish to use strings. * Get parameter GETPARM: move.l (a7)+,a0 movem.l (a7)+,d2-d4 Here we test that D2 is 0, for an integer tst.b d2 bne.s MISMATCH jmp (a0) Parameters returned by a function are simply stores as below using the rules for those values of incoming parameters. * Save parms for return SAVEPARM: Store actual value in d3 move.l d0,d3 Make d2 0 for integer move.w #0,d2 Make d4 0 as it is not used move.w d2,d4 rts * Errors... You must do your own error handling in STOS extensions. You may use the standard STOS error messages or use your own (or of course mix). The mismatch error is issued if the incorrect parameter is sent. * Mismatch error MISMATCH: Move the STOS error number (back of manual) into d0 moveq.l #19,d0 bra.s STOSERROR Where parms are sent to a command when they should not be there is no message so I wrote one... * No parms expected NOPARMSERR: Move the STOS error number reflecting the type of error (this should be shown when UNDO pressed but hardly ever works! See Maestro errors!). moveq.l #12,d0 Load the address of your error text lea NOPARMSERRTEXT(pc),a2 bra.s MYERROR * Range error parms RANGEPARMERROR: moveq.l #12,d0 lea RANGEPARMERRTEXT(pc),a2 bra.s MYERROR This procedure handles STOS errors * STOS error messages handled here STOSERROR: move.l SYSTEM,a0 move.l $14(a0),a0 jmp (a0) This procedure handles my own errors * My own error messages handled here! MYERROR: clr.l d1 clr.l d2 clr.l d3 clr.l d4 clr.l d5 clr.l d6 move.l SYSTEM,a0 move.l $18(a0),a0 jmp (a0) Dummy label for tokens not used DUMMY: Data for eg command EGINFO: dc.b 10,13,"* EG (Example) extension by M.Cubitt 1993 *" dc.b 10,13,"eg................: Information" dc.b 10,13,"=range(A,B,C).....: Make A in range B-C" dc.b 10,13,"=ndrv.............: No. of drives" dc.b 10,13,0 even Error text (English and then French)... RANGEPARMERRTEXT: dc.b "Expected three values for function",0 dc.b "3 values expected",0 even NOPARMSERRTEXT: dc.b "No parameters expected",0 dc.b "No parameters expected",0 even End of program marker dc.l 0 EXIT equ * And so there is a simple interpreter extension for STOS. Compiler the source as EG.EXW. Place this in your STOS folder. When you next boot STOS you should have a new set of commands. I have written a small program which uses all three commands so you can see what they do. I think it is a nice touch to provide examples of ALL new commands so that fellow STOSSERS understand how to use them. That is all for this part. In the next part I will show you how to write a compiler extension. It seems that a lot of people out there are unsure of how to do this. If you have any questions relating to this series please do not hesitate to contact me. As I said before, I only aim to get you started. Until part 2, good bye!