TUTORIAL FOR INSTALLING MINIX-386 Modified 12/3/90: jwn This is meant to be a step-by-step tutorial on moving from standard Minix 1.5.10 to Bruce Evans's modification which allows the full use of the Intel 386 CPU. I'm going to refer to the modified system from here on out as "Minix-386", but it should be clearly understood that we are merely talking about standard Minix, with the modifications written by Bruce. I'm also going to make certain assumptions regarding the audience for such a tutorial. These assumptions are as follows: 1. Access to the Internet, and capability of transferring files via ftp. 2. A 386 system, with a hard-disk and at least a 1.2 meg floppy drive. Minix 1.5.10 should be already installed on the hard-disk. 3. Some means of transferring binary files from Internet to the Minix system. In my case, I use PC-NFS, and can ftp from DOS and then use DOSREAD from Minix. But just whatever works for you should be ok. Just remember that these files are BINARY, so when using things such as ftp, dosread and kermit, be sure and set the binary option. 4. Familiarity with such standard programs as ftp, patch, make, dosread, crc, etc. I'll try and make comments from time to time which may be helpful, but I am not going to really get down to basics. You most likely want to hold off on going to an experimental system such as Minix-386 if you are not at least at that level. (On the other hand, there's nothing like jumping in the water to learn to swim, and if someone gives it the old college try anyway, don't hesitate to send me some e-mail if you have a problem, even if it is really basic). I strongly recommend the excellent tutorial which Glen Overby wrote, and which is available from plains.nodak.edu. I do not remember the exact name, but it is something like Glen0.tute.tar. Before starting this, I recommend that you back up your Minix system if you have not already done so. Although nothing that I am going to tell you *should* mess up your hard disk....always remember Murphy's law! Get a good 1.2 meg floppy disk, format it, and then make a file system on it. (mkfs /dev/at0 1200). ------------------------------------------------------------------ Step 1. ftp to an archive. I recommend plains.nodak.edu [134.129.111.64] if you're in the US, but there are probably other good ones as well. The following is going to assume plains.nodak.edu. Step 2. Change to directory pub/Minix/oz. Step 3. Set mode to binary and ftp the following files: mx386_1.1.t.Z mx386_1.1.01.Z bcc.tar.Z bccbin16.tar.Z bccbin32.tar.Z bcclib.tar.Z shoelace-1.0a.tar.Z Note: There are other interesting files in pub/Minix/oz, but I recommend you stick with these. (NOTE: At the time this tutorial was originally written, there was a problem with cppmake at Minix 1.5.10. Since that time, cppmake has been re-released to the net at the 1.5.10 level. Unfortunately, I have not yet had a chance to check it out, so I'm not going to change the tutorial yet. But I probably will on the next iteration). mx386_1.1.t.Z is a compressed, tar file of all of the material necessary to get Minix-386 running. mx386_1.1.01.Z is a compressed ASCII file (not a tar file) which contains a bug fix necessary for mx386_1.1.t.Z. bcc.tar.Z is a compressed tar file of the source file for bcc (which we won't use, but I recommend getting it anyway, just in case). This file also contains bcc.doc and bcc.bugs. These are not needed immediately, but should be read before doing anything with the source (bcc.c). bccbin16.tar.Z is a compressed tar file containing binaries for the version of the compiler that runs under standard Minix 1.5.10. bccbin32.tar.Z is a compressed tar file containing binaries for the version of the compiler that runs under Minix-386. bcclib.tar.Z are all the library source files necessary to support the compiler. shoelace-1.0a.tar.Z is a collection of files necessary to utilize what has been called "a preliminary boot program". It has very good documentation, and is probably a good thing to use. In this document, however, I am just going to use it to make a floppy that will boot up your 32-bit system because I cannot for the life of me make a boot disk the regular way that works. If you can, I urge you to post the necessary information :-) To make matters even worse, the first time I compiled the system, I DID make a good boot disk...but I can't duplicate it. Shoelace is better, anyway. NOTE: It may seem a little confusing that there are two compilers, which seem to be alike, but there is a good explanation. Either of the compilers will produce either 16-bit or 32-bit object files (depending on whether they get a -0 argument or a -3 argument). However, the present Minix system only runs in the 16 bit mode. So therefore, you have to have a compiler which also runs in the 16 bit mode. Use it to produce 32-bit object files, and then after you have a 32-bit version of Minix, you can use the 32-bit compiler. Now set up a Minix directory called /usr/oz, and move all of the ftp'd files to Minix, using DOSREAD or whatever other mechanism you might have. (If you have a Unix machine, such as a Sun or whatever, you might want to uncompress and untar there, and just move the files over to Minix. If you do that, you have to make the appropriate adjustments to the following steps). Step 4. Uncompress all files: compress -d mx386_1.1.t.Z # produce a tar file compress -d mx386_1.1.01.Z # produce an ASCII message ...etc. NOTE: Most of the tar files, when untarred, will make their own subdirectory. However, Shoelace does not do this, so you have to manually make a shoelace directory (/usr/oz/shoelace), move the .tar file to it, and untar it there. Step 5. Untar mx386_1.1.t (tar xf mx386_1.1.t). This will make a subdirectory called mx386_1.1, which contains the following: README1.1 # read this!! bin0 # a directory - 16 bit compiler bin3 # another directory - 32 bit compiler fs # another directory - fs material kernel # another directory - kernel stuff mm # another directory - mm stuff tools # another directory - tools stuff mx386_1.1.crc # crc listing of mx386 package runtime.crc # crc listing of things needed Lets rename the subdirectory ("mv mx386_1.1 mx386"), since it is easier to work with that short name :-) Also, at this point, stop, get a beer (or a cup of coffee) and carefully read the README1.1 file. It tells you just about everything that is in this tutorial. So use it as a reference guide. Step 6. Untar mx386_1.1.01, and use a text editor, such as elle, to remove the top material, so that you can run it through the shell (i.e., remove everything up to the line that says "/bin/sh"). Then run it through the shell ("/bin/sh mx386_1.1.01"). Step 7. This will give you a .crc and a .cdif file. Move both of them to the /usr/oz/mx386/kernel directory and run patch against klib386.x with the .cdif file (that is: "patch klib386.x klib386.x.cdif") to produce an updated klib386.x file. Check the new crc against the one given in the .crc file. Step 8. Mount your 1.2 meg floppy - let us say on user. (That is, do a /etc/mount /dev/at0 /user, assuming that you have your 1.2 meg drive as drive 0) AT THIS POINT, I AM GOING TO ASSUME THAT YOU HAVE A DIRECTORY CALLED /USR/OZ/MX386, AND THAT THE MATERIAL WHICH CAME FROM THE FILE MX386 FILES IS IN IT. I AM GOING TO ALSO ASSUME THAT YOU HAVE A DIRECTORY CALLED /USR/OZ/BCC, AND THAT THE MATERIAL WHICH CAME FROM THE BCC FILES IS IN IT. THE /USR/OZ/BCC DIRECTORY LOOKS LIKE THIS: bcc - a directory, which came from bcc.tar.Z bccbin16 - a directory, which came from bccbin16.tar.Z bccbin32 - a directory, which came from bccbin32.tar.Z bcclib - a directory, which came from bcclib.tar.Z Step 9. Here we will make the directory structure on /user which will be needed as the root when you boot up your 32-bit system. cd /user # (mounted above, on at0) mkdir usr # /usr for Minix-386 cd / # copy root stuff to new partition cpdir -s dev /user/dev cpdir -ms etc /user/etc cd /user/etc rm mount umount update # ruthlessly root out 16-bit binaries Note: Edit /user/etc/rc so that it does not try and mount stuff. Just comment out the part that mounts /usr. Your /usr directory will be on the floppy when you boot it up later. In fact, I recommend going through /user/etc/rc and commenting out everything which is not absolutely essential. Now, set up root for compiling stuff. You don't want to have your root in RAM for this. I presume you are mounting a disk partition as root. If not, you will have to change all the paths "/local/..." in bcc.c to something else, perhaps "/usr/local/...", and recompile bcc. cd / mkdir local cd /usr/oz/bcc cpdir -ms bccbin16 /local/bin # Move 16-bit compiler cpdir -ms bccbin32 /local/bin3 # and the 32-bit compiler Step 10. Now you need to go through and apply Bruce's changes to the standard 1.5.10 material. ("cpdir -ms" is recommended by Bruce). cd /usr/oz/mx386 cpdir -ms bin0 /local/bin # 16-bit compiler stuff cpdir -ms bin3 /local/bin3 # 32-bit compiler stuff cpdir -ms fs /usr/src/fs # mods for fs cpdir -ms kernel /usr/src/kernel # mods for kernel cpdir -ms mm /usr/src/mm # mods for mm cpdir -ms tools /usr/src/tools # mods for tools Step 11. Now apply Bruce's changes to /usr include and to the standard library routines. cd /usr/oz/bcc/lib/fix1.5.10 # move Bruce's changes cp include.cdif /usr/include # to include cp ansi.cdif /usr/src/lib/ansi # to ansi cp other.cdif /usr/src/lib/other # to other cp posix.cdif /usr/src/lib/posix # and to posix cd /usr/include # now apply the changes patch < include.cdif cd /usr/src/lib/ansi patch < ansi.cdif cd /usr/src/lib/other patch < other.cdif cd /usr/src/lib/posix patch < posix.cdif Also apply the necessary changes to tools cd /usr/src/tools patch < tools.cdif Step 12. Copy the additional bcc library stuff. cd /usr/oz/bcc/lib cpdir -ms bcc /usr/src/lib/bcc Step 13. At this point, you should use /usr/oz/mx386/runtime.crc and check the crc's against your files. NOTE: What Bruce refers to as "/local/bin0" will be your "/local/bin", and what he refers to as "/local/bin" will be your "/local/bin3". That is, he is using the bin3 directory for bin, and you want to use the bin0 directory as bin. You will notice that he does not give a crc for EVERYTHING which is on your file system, but only for the things that he has either added or put there. So, for example, in crc checking /usr/include, he gives under "/usr/include" the routines which were patched, such as fcntl.h, lib.h, etc. The stuff shown as "/usr/include/dist" is merely for comparison with standard 1.5.10, and should not necessarily be on your partition. However, if you want to really be safe, you could set up such a subdirectory to save the things prior to changing them, so that you can always go back to where you where. (But since I advised you to backup before you started, it should not be necessary.....) The material which he does NOT show - for example the remainder of /usr/include - is expected to match Minix 1.5.10 crc's. If you did not have a clean 1.5.10 system (i.e., matched crc's) to begin with, there may be problems. Do not be fooled (like I did) into thinking that just because it is not shown in runtime.crc that it should not be there! However, in the real world we live in, very few of us actually do have exact crc matches on EVERYTHING....so do the best you can with it. Use caution, however. If every little library routine and makefile does not match to the nth degree, you may, with luck, get by. But if there are big discrepancies, or the discrepancy is in the operating system itself, you might save time by getting if fixed before proceeding. In /usr/src/kernel, note that the crc for klib386.x shown in the runtime.crc file is not correct, since you should have previously patched that with the material from the mx386_1.1.01 file. The correct crc should be: 54263 20437 klib386.x My makefile.cpp for /usr/src/kernel also does not match the runtime.crc file (I show 03660 4085 makefile.cpp). Note that for /usr/src/lib/ansi, posix, and other, Bruce again shows on runtime.crc only the files which he changed. There will, of course, be ALL of the files from Minix 1.5.10 in /usr/src/lib. The ones which he does not show should match Minix 1.5.10 crc's. Step 14. Recompile "make" so that it will recognize .o files (instead of using .s files). To do this, just change to your /usr/src/commands/make directory, and edit the Makefile to remove -DPCMINIX from the CFLAGS line, so that it just reads "CFLAGS = -Dunix". Then do a make, produce a new object file of make, and move it to /usr/bin (I would recommend that you save the old make first. For example: cd /usr/bin mv make make_s cd /usr/src/commands/bin mv make /usr/bin Step 15. Now, we are ready to compile the libraries. First of all, change your path, so that you will have access to the compiler. At the same time, change cc to something else, and link the name "cc" to the bcc compiler. (The reason for changing cc to some other name is to be sure that if you re-boot and forget to change your path, you will not start compiling with the wrong compiler!) PATH=/local/bin:$PATH export PATH cd /usr/bin # assuming that cc is here mv cc cc_old cd /local/bin ln bcc cc # since some makefiles use cc Step 16. Now, lets compile the libraries...but before doing so, be SURE that there aren't any refuge .s files hanging around. They cause problems! cd /usr/src/lib/ansi rm *.s cd ../posix rm *.s cd ../ibm rm *.s cd ../other rm *.s cd ../string rm *.s cd /usr/src/lib/bcc sh makelib 86 | tee makelib.out 2>&1 Several things can go wrong here. If something is not working, check to be sure you set the PATH right. Check to be sure that you have the proper files in /local/bin. Check to be sure that cpp is in /lib (because it is needed to convert .x files). Check to be sure that you don't have some kind of garbage in with the source files. If you get compile errors, check to be sure that your crc's check with Bruce's. There should not be any compile errors. Check the file makelib.out carefully, and see if it contains any error messages. There should not be any. If there are, fix them, clean up stuff by doing: sh makelib 86 clean and then start over with: sh makelib 86 | tee makelib.out 2>&1 But assuming everything is eventually ok, you should now have a 16-bit library which will be in /usr/src/lib/bcc/i86. Move this to /usr/local/lib/i86, as shown in the following: cd /usr mkdir local cd local mkdir lib cd lib mkdir i86 cd /usr/src/lib/bcc/i86 cp * /usr/local/lib/i86 There is a little library which we need for /usr/src/kernel, so let's go ahead and make it now. cd /usr/src/lib/bcc/86 ar r /usr/src/kernel/longlib.a laddl.o lcmpl.o ldecl.o lorl.o \ lsll.o lsrul.o cd /usr/src/kernel ar t longlib.a # check to be sure they are there... Now, clean up the 16 bit stuff, so the 32-bit library can be compiled. There are things in it the 16-bit library which later on are going to be needed to make the 32-bit system. Later on, if you get cramped for space, you can remove the 16-bit libraries if you run completely under Minix-386. cd /usr/src/lib/bcc sh makelib 86 clean sh makelib 386 | tee makelib.out 2>&1 Same warnings hold, of course, as above. But if the 16-bit library compiled ok, most likely the 32-bit one will also :-) cd /usr/src/lib/bcc/i386 cp * /usr/local/lib/i386 # copy to permanent home sh makelib 386 clean # if you are tight for space Step 17. OK, now lets make the operating system itself. The time has now come to discuss the makefile problem. Bruce has assumed that we are using cppmake. But, as previously stated, cppmake was not working under Minix 1.5.10 when I put this tutorial together, so I recommend we go without it for now (coward's way out - I SHOULD check out the new cppmake and change the tutorial accordingly!) The first thing to do is to make the directory where kernel, fs, and mm are going to be put (that is, the object files). cd /etc mkdir system Doing the makefiles for mm and fs are both easy. Just use elle and delete some blanks which are at the beginning of some of the "#" commands. Then use cpp to generate a makefile. cd /usr/src/mm rm *.s *.o # can't be too careful... elle makefile.cpp # be sure all "#" commands start in column 1 /usr/lib/cpp -P -DINTEL_32BITS makefile.cpp > makefile make # generate /etc/system/mm cd /usr/src/fs rm *.s *.o elle makefile.cpp # again, be sure all "#" commands start in col 1 /usr/lib/cpp -P -DINTEL_32BITS makefile.cpp > makefile make # generate /etc/system/fs NOTE: You will get a warning message from ld that _exit has been redefined. This is normal. /usr/src/kernel gives more of a problem, because cpp does not like the comments (which begin with "#") in makefile.cpp. The easiest thing seems to just make a copy of makefile.cpp, use elle to remove all of the comments, and then run cpp on it. Be careful though that when you remove something that it IS a comment, rather than a cpp command! So read before deleting. cd /usr/src/kernel cp makefile.cpp xx elle xx # remove all of the comment lines rm *.s *.o # be sure... config 386 # set up proper files. /usr/lib/cpp -P -DINTEL_32BITS xx > makefile make # generate /etc/system/kernel NOTE: ld complains that _unlock and _lock are redefined. Again, this is normal. PROBLEM AT THIS POINT! I have not had much luck with making a boot disk using /usr/src/tools, so I am going to recommend using the Shoelace method instead. Therefore, I am going to just make init, move it over to /etc/system, and stop there, so that I can get this $%@#& tutorial posted! (But I'll keep working on it :-)) By the way, a comment was made on the net that the stacksize in init.c needs to be made greater. I have not personally had a problem with it, but you might want to consider changing the constant within init.c to make it greater, if you have a problem with loading init. cd /usr/src/tools cc -3 -c -D_POSIX_SOURCE -D_MINIX init.c ld -3 -o /etc/system/init /usr/local/lib/i386/head.o \ init.o /usr/local/lib/i386/libc.a NOTE: ld complains that _sbrk and _exit are redefined. Again, this is normal. Step 18. Now, go back to /usr/src/oz and uncompress and untar the file containing Shoelace (shoelace-1.0a.tar.Z). You need to switch back to the regular old ACK compiler, and use the old version of make. cd /usr/bin mv cc_old cc mv make make_o mv make_s make PATH=/usr/bin:/bin export PATH cd /usr/src/oz/shoelace make -f makefile.min # make shoelace stuff Read the file "readme" carefully. It will tell you in detail how to make a floppy disk. Just use the 1.2 meg disk that you already have mounted for this! That is, do the "./laceup /dev/at0 5.25dshd". (The readme file says to use /dev/fd0 5.2h dsdd, but since you have a 1.2 meg disk, you need to use /dev/at0 5.25dshd). Next, copy shoelace to it, as per the readme file. THEN, copy the kernel, mm, fs and init files. Copy config to /user/etc/config. cd /etc/system cp * /user # copy kernel, fs, mm, init (Do NOT, however, follow the readme directions to "copy a /bin/sh, login, etc. onto the floppy" because you want to put 32-bit versions of these on there. This will be done a little bit later.) Also, you need to edit the /user/config file a little bit, so that it fits your configuration. Use elle and comment out the line which says: run /etc/system/db Step 19. If all of this worked ok, then you should now have a 32-bit boot disk. Now, you want to Make a few more 32-bit files...which means that you need to compile a few commands. First, switch back to bcc: cd /usr/bin mv cc cc_old mv make make_s mv make_o make PATH=/local/bin:$PATH export path Now make the files you are going to need: cd /user mkdir bin cd /usr/src/commands/sh We will dispense with using makefiles for right now...you can play with these and adjust them to your satisfaction later. rm *.s *.o cc -3 -D_POSIX_SOURCE -o /user/bin/sh *.c cd /usr/src/commands cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/bin/login login.c cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/etc/update update.c cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/etc/mount mount.c cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/etc/umount umount.c cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/bin/cat cat.c cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/bin/ls ls.c cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/bin/cp cp.c cd /usr/src/commands/ibm cc -3 -D_POSIX_SOURCE -D_MINIX -o /user/bin/readclock readclock.c NOW, finally, and at last. You have a 1.2 meg floppy which has a Minix-386 system on it (a skelton system, to be sure), and which you can boot up. What you want to do now is boot it up, see if everything works, and if it does, you should be able to now think in terms of making a Minix-386 hard disk partition, compiling all commands, etc. The biggest problem that you are going to have is mixing the 16-bit and 32-bit binaries. If you try and run a 16-bit program while in 32-bit mode, you get an error. And vice-versa. Here is a little program you can run to check: main() { char buf[10]; if (read(0,buf,4) != 4) { printf("Length error reading file.\n"); exit(1); } if (buf[3] == 0x04) printf(" is 8086\n"); else if (buf[3] == 0x10) printf(" is 80386\n"); else printf(" is unknown\n"); } Just compile it and run it against /bin, /usr/bin, /etc. For example, say you call the program "check_cpu": cd /usr for i in * do echo $i - `(check_cpu < $i)` done Good luck, congratulations, and welcome to Minix-386!!! Another problem which pops up is that /etc/rc will have a call to something which does not exist. This makes the system hang. For example, if you do not have a program called /usr/bin/readclock, but yet /etc/rc has a command to execute that program, you hang! (p.s. If you have problems, suggestions, criticisms or comments about this tutorial, please feel free to send them to me. Better still, make notes as you go, and use your own experience with it to post a better one!) John Nall nall@sun8.scri.fsu.edu ª nall@sun8.scri.fsu.edu ¶¨/hn Nal8Kjl4 jll@sun8.s