meulenbr@cstw68.prl.philips.nl (Frans Meulenbroeks) (01/17/90)
Minix ST 1.5.0 upgrade guide
Frans Meulenbroeks.
january 1990.
To Ruud and Erik,
whose early arrival delayed this project at least a month
but it was (and is) worth every second.
INTRODUCTION
This document describes how to upgrade your out-of-the-box Minix ST 1.1
sources to the 1.5.0 version.
The upgrade kit will not work with other ST kernels (e.g. gkernel, or
the kernel with Poole fs).
Since the new version is pretty compatible with PC 1.5.0 it is
baptised ST 1.5.0 and not 1.2. Version 1.2, 1.3 and 1.4 are never distributed.
ST 1.5.0 is as much compatible with PC 1.5.0 as possible.
There are some differences though:
- PC 1.5.0 supports Amoeba networking.
Since I don't have an Ethernet card for the ST, and because I'm not
aware of the existence of such a thing I did not look at this
- ST 1.5.0 supports formatting of disks
- ST 1.5.0 supports several hardware clocks. Note that since I do not
have all those hardware not all stuff is tested by me.
- several bug fixes were added in order to get things working on
an ST. Things which always break code on the ST are assumptions that
sizeof(char *) == sizeof(int), and dereferenced NULL pointers.
- elle
When typing these release notes, I noticed that elle is missing.
Since I do not have elle sources this has been left out.
- stterm
The PC term program was terribly slow on the ST due to shadowing.
Therefore I included another communications program, which I baptised
stterm. It is based upon a program received through usenet (sorry,
forgot the authors name), and is reworked by J.R. Bammi.
The idea behind this upgrade is to get close to the PC version.
For that reason I regretfully could not include several functional
enhancements, which I really would like to see included.
Fortunately at least some of these are rumored to be in future
versions.
WARNING
This upgrade is not trivial.
It can take several evenings to do the upgrade, especially if you have a
floppy only system.
It helps very much if you have already build a minix system in the
past. If you haven't done so, you might consider trying that first
before starting on this upgrade.
Also some familiarity with the minix commands is needed.
There might be one problem left in the kernel! I just got a crash
yesterday, which I was unable to reproduce. If you encounter problems
and discover either a fix, or a way to reproduce it, let me know.
However, it is also quite possible that this problem is due to flaky hardware
(you should have seen my system to know what I mean).
I'll try to see if I can reproduce the problem. If I come up with something I'll
let you know....
DISCLAIMER
This version is not an official version. That is: most likely it will
never be distributed by PH.
A previous upgrade kit was sent to Johan Stevenson for official
approval. Unfortunately he did not have the time to work on it.
Therefore Johan agreed that I would distribute the stuff to a small beta
test group, and then release it as a semi official release.
Also ast encouraged me to work on this.
After a lot of comments from the beta testers (thanks boys!) and a lot
of changes based upon those comments, this upgrade kit is the result.
The above means that this upgrade kit is *NOT* officially approved by Johan,
but I think at the time this is as close as official as we (the net) can
get it, and therefore I suggest to use this as THE 1.5.0 version until
something official comes up.
Note: Installing these changes will void your warranty.
Installing the changes is *NOT* recommended if you haven't build a
minix kernel before and/or if you have no C/Unix experience.
Both me (Frans Meulenbroeks), the beta testers, and all persons
that contributed code, do not grant any warranty, and will not be
liable to any damage done to you or your system, either direct or
indirect.
If you cannot live with this, just discard this upgrade kit.
(How is that for a change)
COPYRIGHT NOTICE
A number of the sources in this upgrade kit are copyrighted.
See the various files for more details.
The files have one thing in common: they are all snatched from Usenet
and IMHO they may be distributed freely.
As far as this upgrade kit concerns I want to make the following
statement:
"This upgrade kit carries a compilation copyright as far as the various
source files concerns. This document is copyrighted by F. Meulenbroeks,
1989. Everyone is granted permission to redistribute both the upgrade
kit and this document freely. However, it is explicitly forbidden to
make money from this in any way. "
Or in other words: feel free to share this with anyone else, but don't
ask money for it. It is explicitly forbidden to make money off this.
This implies that it is forbidden to put this in any PD library who
sells software for a larger amount than is needed for media cost (and
shipping if appropriate).
To some of you the above statement may seem quite rigid. However, I
hate to see other people make money out of my work.
Explicit permission is granted to ast to use (parts of) this in future
releases.
HARDWARE REQUIREMENTS
It might not be possible to install this upgrade if you have only 0.5 MB of
memory, or only a single sided floppy drive.
If you want to try with such a system I wish you good luck.
If you succeed, I'd like to hear from you, and how you achieved this.
Perhaps we can add a section to this document.
If you have a bare 520 with a SS drive only, you will not be able to do
this upgrade.
HOW THINGS ARE ARRANGED
The whole upgrade kit consist of 23 parts. These are:
part 0: this installation guide
part 1: include stuff (called inclshar)
part 2: lib stuff (called libshar.uue)
part 3-12: commands stuff (called comm1 - comm10)
part 13: sttools stuff (called sttlsshar)
part 14: test stuff (called testshar)
part 15: tos stuff (called tos.arc)
part 16-17: fs stuff (called fsshar1 - fsshar2)
part 18: mm stuff (called mmshar)
part 19-22: kernel stuff (called kernshr1 - kernshr4)
Apart from part 0 (which is this document and is plain ascii text) and
part 15 (which is a uuencoded arc file), all parts are send as uuencoded,
compressed shar files. This means that you have to uudecode all parts
first, then uncompress them using compress -d, and then extract them
using sh. This format is equivalent to the format in which the PC 1.5.0
was posted.
All the upgrades consist of either the complete files or a cdiff with the
original out-of-the-box 1.1 sources.
I have tacked a .cdif extension to all cdif files.
Unfortunately due to the limit minix places on file names, sometimes
the trailing .cdif may be truncated to .cdi or even .cd
Note that in 1.5.0 the h directory does not exist any more, but has
been renamed to /usr/include/minix.
Also the lib directory has been split into pieces. For the ST the
interesting subdirectories are atari ansi posix and other
Sometimes you'll be asked to take stuff from the PC 1.5.0 distribution.
This is done to avoid massive postings of stuff which is posted by ast
less than a month ago. I twice suggested you'd save these postings.
If you didn't do this bad luck to you. Try to find these postings on an
archive server first. You'll need them!
In one or two cases you're supplied with a patch to a PC posting.
In that case you are encouraged to keep the PC original around as well.
Future postings of ast will refer to the PC postings. I know ast will be
incorporating the patch I post in the next version.
With this release the PC and ST 1.5.0 are compatible (with a few small
exceptions) with respect to lib/include/commands/fs/mm/test
Part of sttools is also equivalent. Due to the different environments it
is not possible to fully integrate PC and ST stuff in this area.
The integration of the kernel is still in the works. This integration
will also be only a partial integration. Due to different hardware most
of the drivers cannot be integrated. Several other parts (e.g. proc.c
system.c memory.c clock.c a lot of .h files and perhaps tty.c) can (and
hopefully will) be shared between PC and ST.
Finally there is the tos stuff. There is no equivalent PC directory, so
there cannot be much integration. Since I develop minix under minix, I
rarely use the tos stuff, and maintaining or updating it is not a high
priority issue.
Notice that in several cases the ST specific makefile is called
something like st_makefile or Makefile.st. Be sure to use the proper
makefile in those cases!
SETTING UP YOUR SYSTEM
Before starting the actual upgrade process some initial preparation is
needed.
First of all I would urge to to make a copy of your src disks!
Do not apply this update on your original PH disks.
There is a chance that the installation instructions are incorrect, or
that you make a mistake while installing.
Always be careful with your originals!
If you have more than 1 MB of main memory you'll probably want to
create a version of minix with a huge ram disk, so that the ram disk can
accommodate both /bin and /usr/bin. This will speed up the compilation
process incredibly. Refer to your manual on how to do this.
If you have a hard disk it is wisest to dedicate a partition to minix and
to put all the sources on that disk. Personally, I've stuffed all sources
in /usr/src. Refer to the manual on how to set up this partition.
Furthermore I recommend backing up the disk before starting.
If you have a dual floppy system it is probably the best to make a floppy
containing the compiler and some other useful utilities (e.g. make)
If you have only one floppy drive and 1 MB of memory you'll have
to put all important stuff from /usr/bin (e.g. cc and make) on the ram
disk.
If you have no hard disk you'll have to put the sources on floppies.
It is best to put the sources for kernel mm fs and lib on a separate
disk. You can put the sttools and test sources together on one disk.
The sources for commands have to be split and must be placed on multiple
floppies. The upgrades for commands alone would fill a disk.
I think it is the best to put the subdirectories on a disk and the
remaining stuff on a second disk.
Note however, that I never attempted to build minix on a floppy based system.
Beware that if you split the commands, you have to deal with the makefile
as well.
The installation process which is explained below is written for a hard
disk user. If you are a floppy only user, you'll have to change disks
between a lot of the steps.
Also if you are low on disk space you might decide to remove the .o files
after you're done with a step.
Note that somewhere in the past I did this whole upgrade myself. Since
then there have been some changes, so I cannot guarantee that it all
works flawless. If you encounter any problems, sorry! If I had to
retest the posting would be delayed by another two or three weeks.
I've tried to be as explicit as possible so I hope all problems are
solvable.
CONFIGURING THE TOOLS
Before starting the upgrade you should change the amount of memory that
the various tools use.
Values which are reported to work are:
cc 3000
cpp 30000
cv 50000
as 50000
ld 100000
cem 100000
cg 30000
opt 40000
However, if you encounter problems because the compiler crashes you
might want to increase some of these values. Use cc -v to detect in which
pass the compiler crashes.
INSTALLATION PROCESS
Before starting with the installation process read this document very
carefully. At the end you'll find a list of common problems, so it is
important to read the document fully!
After reading the document you might want to reconsider the fact that
you want to do an upgrade. Most likely the upgrade will take several
evenings!
Still here? Ok, off we go:
1) go to the commands directory
2) mkdir make; cd make
3) unpack ST part #6 (comm4.uue) in this directory.
4) make -f makefile.st.1
5) (optionally) rm makefile && ln makefile.st makefile
6) install the new make in /usr/bin
If you have the old make on another place as well (e.g. /bin)
make sure to install it there as well.
7) make a subdirecotory commands/patch and unpack PC part #73 in this
directory.
8) make -f st_makefile
9) install patch in /usr/bin
10) unpack ST part #7 (comm5.uue)
11) cc -o crc -O crc.c
12) chmem =10000 crc
13) cp crc /usr/bin
14) cd /usr
15) mv include oldinclude
You can discard the oldinclude directory after doing the upgrade.
16) mkdir include
17) cd include
18) extract PC parts #15-#17 in this directory, followed by the ST include
posting. See also the comments in the include posting.
19) extract ST part #1 (inclshar.uue)
Examine and modify the files /usr/include/minix/config.h and
/usr/include/minix/boot.h. Minimally you'll need to change the
MACHINE definition in /usr/include/minix/config.h.
20) issue the command: patch <lib.h.cdif
It is wise to keep the old lib.h around for future upgrades!
21) create a directory /usr/src/lib/ansi
22) extract PC part #18 in this directory
23) create a directory /usr/src/lib/posix
24) extract PC part #19 in this directory
25) create a directory /usr/src/lib/other
26) extract PC parts #20 and #21 in this directory
27) create a directory /usr/src/lib/atari
move all .s files from the ST 1.1. distribution to this directory.
28) extract ST part #2 (libshar.uue).
29) mv /usr/lib/libc.a /usr/lib/oldlibc.a
You can discard /usr/lib/oldlibc.a after doing the upgrade.
30) execute all shell scripts called run.
First in the subdirectories. Then in /usr/src/lib.
31) mv /usr/src/lib/libc.a /usr/lib/libc.a
32) extract ST part #16 (fsshar) in the fs source directory
33) issue the following command in the fs dir:
for i in *.cdiff *.cdif *.cdi *.cd
do
patch < $i
done
This step is further on referred to as "apply the patches"
34) make -f st_makefile
if you are low on disk space you can remove the .o files after
fs.mix has been made.
35) extract ST part #17 (mmshar) in the mm source directory
36) apply the patches
37) make -f st_makefile
if you are low on disk space you can remove the .o files after
mm.mix has been made.
38) extract ST parts #18 to #21 (kernshr[1-4]) in the kernel source directory
39) apply the patches
40) if you have an old supra hard disk you may want to add -DSUPRA
to the CFLAGS line in the Makefile
if you have a real time clock on your disk controller board
choose the proper definition of CLOCKS
if you want to stay using the old keyboard bindings add -DCOMPAT to
the CFLAGS line in the Makefile.
If you don't add this define to the Makefile you'll get Simon
Poole's vt100 compatible key bindings. This is the default
situation.
41) make
if you are low on disk space you can remove the .o files after
kernel.mix has been made.
42) extract ST part #13 (sttlsshar) in the sttools directory
43) apply the patches
44) make
install message as /etc/message, passwd as /etc/passwd and ttytype
as /etc/ttytype
if required modify /etc/ttys and /etc/ttytype
If /etc is on the ram disk you should copy those files to
the disk from which the ram disk is loaded and not to /etc!
copy the minix.img file to a disk
45) extract ST part #14 (test shar) in a new test directory
the old tests are not used any more
46) make -f st_makefile
47) This step intentionally left blank.
You might want to get some sleep or coffee at this stage :-)
48) extract the PC parts #34-#48 and #50-#73 in the commands source
directory and the appropriate subdirectories.
49) remove all .cdif files extracted in the previous step.
50) extract ST parts #3 to #12 (comm[1-10]) in the commands source directory
51) apply the patches
52) rm make.c (this one is obsolete)
if you added -DCOMPAT to the kernel Makefile (see step 25) you
should do the same for commands/mined/Makefile
53) rename st_makefiles to makefile
54) execute the run script in the commands directory
55) execute make in the various subdirectories.
Be sure to use the proper makefile for the st
(often baptised st_makefile or Makefile.st)
56) install all binaries in either /bin /usr/bin or /etc, overwriting the
old binaries. Make sure that you don't leave old binaries in /bin
and put the new stuff in /usr/bin
If /bin and /etc are on the ram disk you should copy those files to
the disk from which the ram disk is loaded and not to /bin or /etc!
also you should install helpfile as /usr/lib/helpfile
help.more as /usr/lib/more.help
fortune.dat as /usr/lib/fortune.dat
57) go to the dev directory on the disk containing the root file system
and execute the MAKEDEV script from the sttools dir
Beware: if you have a ram disk, this is NOT the /dev directory.
If you apply MAKEDEV on the ram disk the changes will be lost
when rebooting.
58) boot the new kernel
The new kernel will typically be a lot larger than your
previous one. 10 kB is due to the fact that I increased the number
of buffers which are allocated by fs with 10 to be compatible with
Minix/PC. The remainder is due to new features and bug fixes.
For instance the rs232 driver takes about 2 kB.
59) if everything worked well you are now running minix 1.5.0
60) move tos.arc to a tos dis, unarc tos.arc and move the stuff to the TOS disk
61) (optionally) run the tests from the test dir
Beware of test 20: There are reports from PC users that this test
will trash hard disks! I didn't have the courage to test this on my
own hard disk!
62) Extract PC parts #1-#4 in /usr/doc
63) Extract PC parts #12-#13 in /usr/man
64) CONGRATULATIONS!!! YOU MADE IT!
SOME COMMON PITFALLS
The following are some common pitfalls which you might encounter.
Please check if none of these cases apply to you before reporting a
problem.
- The crc of file xyzzy does not match the value given in the file CRC
Check if you started with the original virgin sources as they are sold by
PH. Check if you applied all patches on the file xyzzy correctly and if
patch did not complain or reject diffs. Beware that not only files with .cdif
extension contain patches, but also files ending on .cdi and .cd
If the file xyzzy is in the include directory, you should also check if
it is one of the files which come from other parts of the system, and if
you have taken over that file properly. See the INSTALLATION PROCESS
chapter.
Also check if the file xyzzy is not part of the PC posting.
- make does not do its job properly
You should use the new make. There should be no need to modify any of the
make files apart from some configuration macros.
Watch out that you are not using an old make which happens to reside
earlier in your PATH (e.g. in /bin and have the new one in /usr/bin)
- patch does not like some of the cdiffs
Make sure that you use the patch which is shipped in this upgrade kit.
Watch out that you are not using an old patch which happens to reside
earlier in your PATH (e.g. in /bin and have the new one in /usr/bin)
- I made a new minix.img which boots, but I cannot log in
Most likely you've forgotten to install the new passwd file from sttools
in /etc of your root disk.
Reboot your old system and install the new passwd file.
- more does not work; it bumps out after the first screen
more does only work with the new minix.img. Most likely you're trying
with an older one. An alternative is that building the new minix.img
failed.
- more mostly works except for the h command
The h commands gives you help. It needs access to the file
/usr/lib/more.help. This file can be found in this upgrade kit under the
name help.more. Link or copy this file.
- more mostly works except for the v command
The v commands tries to start the program /usr/ucb/vi.
Most likely you do not have this program on this location.
- I've installed program xyzzy in /bin (or /etc) yesterday, and now it is gone
You probably copied the program to the ram disk.
Regenerate the program and make sure it is copied to your root disk!
- format does not work
You have probably not issued a proper mknod command. See step 33.
- fortune does not work
Have you installed fortune.dat in /usr/lib?
IF IT FAILS
If things do not work out as expected, you should check if you applied
the installation process correctly, if you used out of the box sources,
if the CRC's after the upgrade match, and if you are not in one of the
situations mentioned in the previous section.
Then check if there are any other messages on the net describing and
perhaps solving your problem. Also watch for additional parts of this
upgrade kit.
If the problem still exists, you can consider posting a message stating
your problem to the comp.os.minix group on usenet describing the problem
and preferably how you solved it.
If you post your problem you can prevent other people from spending a lot
of time fixing the same problem. Also I can collect all your messages and
add them to the next release.
THE FUTURE
I'll get minix ST even more in sync with the PC version (e.g. make the
tty driver equivalent)
Another thing on my wish list are the patches that were posted to allow
reading and writing of different formatted disks (e.g. 10 sectors/track).
I want to rework this a little thereby letting /dev/dd0 and /dev/fd0
collapse. This will also imply reworking the format program and perhaps
the tos program.
But first of all I'm going to take a small break away from minix.
I still have some other projects which I want to get completed, and of
course there are other things in life apart from computers....
ACKNOWLEDGEMENTS
I would like to thank everyone who contributed to this upgrade kit.
There are too many of you to mention you all separately, and the chances
of forgetting someone are just too great. Therefore I just would like to
say a big "Thank you" to everyone who contributed to this upgrade kit,
either by supplying code, sending comments, or being a beta tester.
Fortunately rules need to have exceptions, and therefore I would like to
say a big "Thanks" to my loving wife Toos, who never complained whenever
I was working on this upgrade.
Frans Meulenbroeks (meulenbr@cst.philips.nl)
Centre for Software Technology
( or try: ...!mcsun!phigate!prle!cst!meulenbr)