*************************************************************************** * * * Make System for HyperC * * Programmed by * * Gary F. Desrochers and Andy Werner * * Documentation for * * Version 1.1 * * Written by * * Gary Desrochers * * * *************************************************************************** In case you don't know what you are reading by now, this is the documentation for version 1.0 of the system maker for HyperC called Makesys. The Story: On comp.sys.apple2 there was always small talk about HyperC but everyone kept saying that it was not possible to make a system program with it. One of the first programs that proved this statement false was the program ProBlock by Mike Pender, which included 3 files to make it run but it was/is a system program in its own right. This set of system routines make a very large leap toward the one system file program using HyperC. This is the closest anyone so far has been able to reach with HyperC and anyone can now use it. It is simple. Andy Werner was the first person who tried to make the idea into a reality. He started creating Makesys after we had partially disassembled opsys and I had written HC.System. He had enough code for the job so he took up the challenge. He succeeded in doing this for all 8 bit Apple II's (Not the IIgs). One of the first stand alone programs that came out was Sokoban which was ported to C in HyperC by Evan Day. At the time I was working on the Hi Res graphics routines and did not follow what was going on. I did receive programs that I was asked to try out to make sure they worked. I realized Andy was having a problem with the IIgs but I thought he could work it out. Andy was also working on several other projects (I shouldn't talk about yet.) and was getting very frustrated on the IIgs problem. He came very close to making it work, which is a pretty good feat for someone who doesn't own a IIgs. This is when I came along. Me looking for something to fill up the 15 minutes a day that I had to kill. (:-)) He asked me to take it over and see what I could do with it. He sent me the code for the parts he had done so far and explained to me what he had done and what problems he was having. (By the way, I can say, he has a neat macro library that isn't finished yet but getting better and better as time goes by, for 658xx machine instructions.) Using parts of his makesys, HC.System, and home made coding, I have refined it so that it now works on the IIgs. Since getting this done, I have tried to make it easier to use. My idea was to let the linker do it all. This was accomplished with the exception of the files opsys, mover, adder, and append. These are run individually from a script, though, so that making a system using HyperC is as close as one editing and one "makesys myfile" away. Most of the important routines are contained in one library called (what else but) makesyslib and two object files systart.o and sysend.o. But enough of this name calling. Let's get down to business. In this archive file you should have found the following files: makesys sys.files append adder mover systart.o sysend.o makesyslib entrance.c entrance.o box.c box.o exitsysprog.a exitsysprog.o trial.c trial.system drawtour.system makesys.doc I will make a feeble attempt to try and describe these files one by one in easy every day terms. I will probably fail but try to follow anyways. Well here goes... --------------------------------------------------------------------------- makesys This is the script file which controls the system file making processes. It actually contains two scripts but you need to edit the scripts to fit your special needs.(No kinky stuff intended.) One script (which is the one set when you get this script) is the one that would link any normal HyperC program. This means that the program will be linked and made into a system program at the 2000 hex address. The second script is in there as well (you can watch it go by when using the first script) but it is commented out. It is used to link a program at any location other than at 2000. Syntax: makesys sysfilename sysfilename = The same name you want the .system file to be. The .system extention will be added later on in the script. Warning: System files are excluded from locations between and including 2001-20FF because this would need the mover header and instead of over writing itself (it isn't smart enough to move itself, just another program) the code must be excluded from this space. Right now it does not use the whole space, but for future expansion we reserve the right to reserve this one page in memory for movers use. This is not a problem with normal system programs because they start at 2000 and don't need the mover routine. ---------------------------------------------------------------------------- sys.files This is the list of files and libraries that the linker needs to know in order to link the system file. This is the editing part I was talking about in the introduction. Before sysmaker can do its job it needs to know what your .o file (object file) is. You need to replace the last object file you linked (In the version shipped with this the name of the object file is trial.o) with your new object file. Of course, you can edit this list as you feel comfortable with it. There are exceptions. These exceptions are systart.o (the system file replacement for s.o) and sysend.o. These must remain in the position they are in in order to build the system file table at the beginning of the system file. The other libraries and object files can be moved around as you see fit. You cannot move systart.o and sysend.o or the screen will shake, the keyboard will die, and your computer may go off into lala land and not return until a three finger salute is issued. This is not guaranteed, so don't try it thinking it would be a cool thing to see. You may only get a and then the four friendly lines at the top of the screen telling you something about nothing in particular. ----------------------------------------------------------------------------- append This program is the program that is used by the system maker script to tack opsys onto the end of your program. The syntax for it being called by itself would be: append intsysfile opsyspos newsysfile intsysfile = the intermediate system file created with the linker or the adder program. opsyspos = the pathname of your opsys file. newsysfile = the name of the system file name. Warning: This file is only a system file in name only. The file needs to be run through the mksys command in HyperC. Check your HyperC manual for details on the workings of mksys. ------------------------------------------------------------------------------ adder (and mover) This program adds the mover to your program. If your program uses a different postion other then 2000 hex then it must have the mover file in its entirety added to it. This is so that when your program is run at location 2000 the program can be moved instead of causing a system crash because it was made to run at 6000 hex, let's say.(Would be the case for hires graphics routines.) Mover is an alternate header which uses the addresses in the system program table that was built at link time to move your program to an alternate address. It performs this feat in one fell swoop. It moves your program to its rightful position in memory by performing a right mover. It does this one (even though it is smaller) so that it doesn't overwrite part of the program being transferred by mistake. It should always work because you are excluded from memory links below 2100 not including 2000. Warning: (Yes another one. shheezzz) When the mover moves your file to its new position, it also moves opsys which is tacked onto the end of it. This should be no big problem for small programs but since opsys takes up 1800 hex bytes, this may be a problem with big programs or programs that are using overlays because the overlays may be there also. Sorry no fix for this as of yet. Make sure you check the HyperC manual and the ProDOS tech manual for important memory locations, if you think you may have exceeded these positions. Syntax: adder sysfilename moverfile intsysfile sysfilename = the pathname of the system file as produced by the linker. moverfile = the pathname of the file named mover. intsysfile = the pathname of what you want your new intermediate sys file to be. Aside: Actually the order of the adder verses the append command are not important. The append can be first or the adder can be first but they both need to be run if making a system program at postions other then 2000. ------------------------------------------------------------------------------ systart.o This is an object file that is a replacement for the s.o that you used to use when making programs that only ran under HyperC environment. This is the header file if the system program is going to be linked at the normal system file address of 2000 hex. If not then the mover must be tacked on as explained above. It sets the pathname, fixes the stack, positions opsys into memory and then and then calls the patch routine. The patch routine patches opsys, patches the brk routine, calls opsys to set up the system, regains control, and runs a program called _EnterSysProg and then runs main. After your program quits using a normal completion (the } ), an exit(), or a quit() call, control returns to the patcher which runs _ExitSysProg, unpatches the brk vector and then performs a quit call. This needs to be the first file to be linked (just like the normal s.o). ------------------------------------------------------------------------------ sysend.o This is a reference for the linker, to tell it where the end of your program is so that it can update the table in systart.o. This must be the last file on the command line for a link or the last file in the sys.files file. The only other thing it does is extend your program by two bytes. ------------------------------------------------------------------------------ makesyslib All library files, with a few exceptions as explained below, that are needed for a system file are contained in this library. The concept of letting the linker do all the work was used in the case of these files. This library includes: patch.o - This was explained above in the systart part of these docs. entrance.o - the name of this file is not important. See below. box.o - only needed if you use the default entrance.o for the _EnterSysProg. un.install.o - contains the code to install/uninstall any needed brk routines into place before opsys is executed. brk.rout.o - the brk routine for the IIgs. exitsysprog.o - the name of this is not important. See below. As I said above, there are several programs that are not needed in the library. What I mean is that you can install your own programs instead of these. The files I am talking about are the files entrance.o and exitsysprog.o which are only programs that supply references for the linker so that it can have somewhere to go when calling two main routines. These two routines would be called: in C: EnterSysProg() ExitSysProg() and in assembly: _EnterSysProg _ExitSysProg These routines can be used for opening splash screens or exiting error routines and stuff like that. Be creative or how about nothing at all. ---------------------------------------------------------------------------- Trivia on the rest of the files. If you want to remove the files: box.o entrance.o exitsysprog.o you can, just as long as you replace them with your own programs.(That is except for box.o. That doesn't need to be replaced. If is just a library file that entrance.o needs.) These routines can be in either C or assembly. The only thing is that they cannot contain any hyperc exit or quit calls. They must end as a normal C program (an }) or in assembly an rts. This is because otherwise you will create an infinite loop or you may skip your main program altogether. These are provided along with the already installed ones in the library just in case you delete them from the library and don't feel like remaking them from the original code. For: box.c entrance.c exitsysprog.a these are examples of what they can look like. If you want to know what box.c is and does then just look at it. trial.c This shows you the different ways to quit from a program. It is also the program the sysmaker is set up for out of the box. trial.system Just in case you want to try it before you make it. drawtour.system Uses a program that is supplied with the HGRLIB for HyperC. You need to get the library separately but this file shows that you can make a system file at a different location other then 2000 hex. This one was linked at 6000 hex. It also shows a brief outline of what the graphics libraries can do. Just to make sure that keypresses are captured, you may have to clear the keyboard with a clrkbd(); call when exiting your program. Since it is not needed for all C programs, it is not in the system maker. ______________________________________________________________________________ This version is version 1.0. It is Freeware by Gary F. Desrochers and Andy Werner. We would at least like to be included in your splash screen or if nothing else, put in your docs for any program you make using this for the effort we put into this. If you have any problems please contact us. Gary Desrochers gdesroch@slate.mines.colorado.edu Andy Werner st2975@siucvmb.siu.edu