.pn 24
.if \nh=0 .so macros
.LP
.de Op
.ti -0.15i
\\&\\fB\\$1\\fR \\$2
.br
..
.CP 3 "\*(M0 ON THE ATARI ST"
.PP
In this chapter we will describe how to boot and install \*(Mx on the Atari ST.
It is assumed that the reader is already familiar with \*(Mx in general,
and has at least some knowledge of
.Ux .
.PP
Booting and installing \*(Mx on the Atari ST is complicated by a variety
of factors:
.HS
.Bu
Atari STs are sold with a wide variety of incompatible keyboards
.Bu
Some versions can only handle 360K diskettes; others can handle 360K and 720K diskettes
.Bu
Some people have winchester disks (hard disks); others do not
.Bu
The amount of memory available ranges from 512K to 4M
.Bu
The Mega ST differs in some ways from the Atari ST 520 and 1040
.HS
.PP
Together, these different configurations give problems.
Our solution has been to provide a base version that will require at least 1MB of
memory and one 720K disk drive, and make it possible for
people with larger configurations to adapt the system to take advantage of
their extra hardware.
This chapter explains how that is done.
.PP
It is possible to run 
.MX 
on a system with 512K of memory, but that leaves very little space for
applications. In this case the best thing to do is to work without a 
ram disk at all, and keep the root filesystem on either hard disk or
diskette. 
Running 
.MX
on a system with only a 360K disk drive is also possible. However
in that case you must first split each 720K diskettes in the distribution
into two 360K ones. Since you do not have a disk drive capable of
dealing with 720K diskettes, you should do this on a friends system.
Sec. 3.6 describes how to split a 720K diskette into two 360K ones.
.SP 1
.SE "THE MINIX-ST DISTRIBUTION"
.SP 1
.PP
The \*(Ms distribution consists of ten diskettes.
One of them contains a binary of the operating system and is used for
booting \*(Ms.
Eight others contain \*(Mx file systems.
Only one of them contains a \s-2TOS\s0 file system.
(We use \s-2TOS\s0 as the name for any combination of BIOS, XBIOS, GEMDOS,
GEM, AES and VDI).
.PP
All distribution diskettes are double-side, and formatted on both sides.
However, two diskettes contain only 360K of information written
on one side of the diskette.
In other words, these two diskettes are written as if they were single
sided diskettes.
Here is the list of the diskettes:
.sp 1
.SP 0.5
.TS
center,box;
c c c c c
l l l l l.
\fBName	Sides	Size	File sys.	Description\fR
_
00.TOS	\0DS	720K	TOS	utilities that run as \s-2TOS\s0 programs
01.BOOT	\0DS	360K	special	used for booting \*(Mx
02.ROOT	\0DS	360K	\*(Mx	root file system copied to RAM disk
03.USR1	\0DS	720K	\*(Mx	most commonly used commands
04.USR2	\0DS	720K	\*(Mx	commands part 2 of 3
05.USR3	\0DS	720K	\*(Mx	commands part 3 of 3
06.ACK	\0DS	720K	\*(Mx	compiler binaries and libraries
07.SRC1	\0DS	720K	\*(Mx	sources of the \*(Mx operating system
08.SRC2	\0DS	720K	\*(Mx	sources of commands part 1 of 2
09.SRC3	\0DS	720K	\*(Mx	sources of commands part 2 of 2
.TE
.SP 0.5
.sp
We will refer to these diskettes in the rest of this manual by
their name in the first column of this table, for example, 01.BOOT.
.PP
Before you start working with these diskettes we urge you
to copy all of them.
You can use normal \s-2TOS\s0 procedures, like dragging icon FLOPPY DISK A
onto icon FLOPPY DISK B, to make the copies.
Whenever we refer to diskettes as 01.BOOT, 02.ROOT, 03.USR1 etc.
we always mean a write-enabled copy of the original diskettes.
Store the original diskettes after copying and
keep them write protected under all circumstances.
Do not use your originals as work diskettes.
.SE "NATIONAL KEYBOARDS"
.PP
The Atari ST comes with different keyboards in different countries.
This lack of standardization is a major nuisance.
Atari solved the problem by providing a different version of their
operating system for each country.
We have chosen a different strategy: a single version that can be adapted
to the various keyboards.
This section describes how to set up \*(Mx for your keyboard.
.PP
Unless you have an Atari ST with a United States
version of the keyboard,
you 
.I must
first adapt \*(Mx
to your particular version of the keyboard.
Even with a United States
version this procedure can do no harm, so if in doubt proceed.
If you skip this procedure,
it is assumed that the keys
generate the characters that are engraved on the key tops of the
United States keyboard,
that is, the key below the DEL will generate the ASCII backslash
character (\e) unshifted, and the ASCII bar (|) if shifted, irrespective
of the character engraved on the key tops of your keyboard.
.PP
\*(Mx cannot handle the national characters themselves,
like o-umlaut for Germany.
The adaptations described below only allow you
to enter the ASCII characters in the way you are used to with \s-2TOS\s0.
In this respect \*(Mx behaves like most versions of
.Ux .
.PP
\*(Mx has its own keyboard translation tables build into the operating
system.
A special tool is provided to extract the keyboard tables
from a running version of \s-2TOS\s0 and to adapt the tables in the binary
version of the \*(Mx kernel accordingly,
without the need to recompile the \*(Mx kernel.
Note that the \*(Mx keyboard translation tables have exactly the
same format as used by \s-2TOS\s0.
.PP
Some keyboard versions need so many keys for special non-ASCII
characters that combinations with the Alternate (ALT) key are
used to generate some ASCII characters.
For instance, in France the key below the Delete (DEL)
generates the ASCII sharp sign (#), SHIFT-# generates the bar (|),
ALT-# generates the at-sign (@), and ALT-SHIFT-# generates the
tilde.
The keyboard tables do not take the ALT key into account, so
Atari delivers several national versions of the \s-2TOS\s0 operating system
to cope with these problems, as mentioned above.
In order to avoid national versions of \*(Mx,
we have built into the keyboard driver
a little table of special ALT and ALT-SHIFT combinations
for the limited number of national keyboard versions that we knew of:
United States, United Kingdom, Germany, France and Spain.
If you happen to have another version
you can make a simple modification in the keyboard driver of the
kernel, but that takes effect only after recompiling the kernel.
Refer to the chapter on kernel recompilation.
.PP
To adapt the keyboard tables proceed as follows:
.HS
.LI
.IT
Boot \s-2TOS\s0 and insert 00.TOS in drive 0.
.IT
Open a window onto drive 0 by double clicking the
FLOPPY DISK A icon.
.IT
Run \fICOMMAND.TOS\fR found on diskette 00.TOS by double clicking.
\fICOMMAND.TOS\fR is a simple line-oriented command interpreter.
.IT
Run \fIFIXKEYS.PRG\fR by typing
.HS
.Cx "fixkeys  a:"
.IT
Insert unprotected 01.BOOT
 when you are asked to do so,
and confirm by hitting the RETURN key.
.IT
Wait for the program to reply with
.HS
.Cx "Done"
.HS
.LX
.PP
You are now ready to boot \*(Mx.
.SP 1.5
.SE "BOOTING MINIX-ST
.SP 1.5
.PP
This section presents a boot procedure for \*(Ms that
works on all configurations of the Atari ST.
Following sections describe how to
adapt the set of diskettes so that you can use \*(Mx
effectively on your particular combination
of memory and disk drives.
For example, if you have more than 512K you can
increase the size of the RAM disk from 160K to 300K, if you have 1M of memory,
or to 1M or more if you have even more memory.
If you have a hard disk, all of the diskettes can be copied
onto one or more of its partitions.
Finally, some of the options for booting \*(Mx will be explained.
But first the procedure for booting that works on all configurations
is described.
.PP
Throughout the discussion below, lines printed in the
\s-2\f5Helvetica typeface\fR\s0
are either commands you should type on the keyboard, or are lines that
the computer will display for you.
In a few of the examples, \fIitalics\fR characters or words appear in 
a command.
These represent values that you are to fill in.
.PP
Booting is a three stage procedure. First the operating system
itself is loaded into memory. Then the ROOT file system is copied
to a RAM disk allocated in memory. Finally, the script
.I /etc/rc
is executed and a message will be displayed on the screen asking
you to log on.
.PP
To boot \*(Ms, proceed as follows:
.HS
.LI
.IT
Turn off the ST and then insert diskette 01.BOOT in drive 0.
You could push the RESET button as well, but that may not free memory
occupied by a crash resistant \s-2TOS\s0 RAM disk you may have running.
Moreover, it fails if you normally boot from the winchester. 
.IT
Wait ten seconds, then turn on the ST.
It will read the operating system (about 153K)
from diskette in a few seconds.
The screen will turn black and it will show on
the top two lines the message:
.HS
.Cx "Booting MINIX 1.5.  Copyright 1990 Prentice-Hall, Inc."
.br
.Cx "Insert ROOT diskette and hit RETURN (or specify bootdev)"
.IT
Replace 01.BOOT by diskette 02.ROOT and hit RETURN.
Alternatives will be explained later.
The system will respond with:
.HS
.na
.Cx "Memory size\^=\^992K  MINIX\^=\^153K  RAM disk\^=\^160K  Available\^=\^679K"
.ad
.HS
for a system with 1M of RAM (numbers might deviate a little).
Adding 32K (the size of the video memory) to the first number
should give the amount of memory in your ST.
.IT
A fourth line will be displayed that reads:
.HS
.Cx "RAM disk. To load:   120K           Loaded:   0K"
.HS
(The number 120 may vary a little). In rapid succession the number 0
will be increased in steps of 18K, until the whole line is replaced by:
.HS
.Cx "RAM disk loaded.    Please remove root diskette."
.IT
When the RAM disk is loaded, the system initialization
file,
.I /etc/rc,
is executed.
It asks you to remove the root file system and insert the
.I /usr
file system (03.USR1) in drive 0 and type a RETURN.
Do so.
.IT
After
.I /usr
has been mounted, you will next be requested to enter
the date (and time).
Enter a 12-digit number in the form MMDDYYhhmmss, followed by a RETURN.
For example, 9:35 p.m. on June 01, 1990 was 060190213500.
.IT
You will now get the message:
.HS
.Cx "login:"
.HS
on the screen.
Type:
.HS
.Cx "root"
.HS
and wait for the system to ask for your password.
Then type:
.HS
.Cx "Geheim"
.HS
being careful to type the first letter in upper case.
Lower and upper case letters are always distinct in \*(Mx.
Alternatively, you could have used the name \*(OQast\*(CQ together
with the password \*(OQWachtwoord\*(CQ.
This is much preferred when you use the system normally, but for now
it is troublesome.
.SP 1
.IT
If you have successfully logged in, the shell will display a prompt 
(sharp sign for root, dollar sign otherwise) on the screen.
Try typing:
.HS
.Cx "ls  \(enl"
.HS
to see what is in the root directory.
Note that you need six 
keystrokes: \*(OQl\*(CQ, \*(OQs\*(CQ, space, \*(OQ\(en\*(CQ, \*(OQl\*(CQ, and a RETURN.
Then type
.HS
.Cx "ls  \(enl  /bin"
.HS
to see what is in the
.I /bin
directory on the root device (RAM disk).
After that, try:
.HS
.Cx "ls  \(enl  /usr/bin"
.HS
to see what is on the drive 0 diskette.
To stop the display from scrolling out of view, type CTRL-S; to restart it,
type CTRL-Q.
(Note that CTRL-S means depress the \*(OQControl\*(CQ key on the keyboard
and then hit the 
.I S
key while \*(OQcontrol\*(CQ is still depressed.)
.SP 1
.IT
You can now edit files, compile programs, or do many other things.
The reference manuals given in chapters 8 and 9 of this manual 
give a brief description of the programs available.
However, before rushing off we advise you to adapt the system to your
hardware configuration first, as described in the next sections.
.SP 1
.IT
When you are finished working, and want to log out, type CTRL-D.
The
.HS
.Cx "login:"
.HS
message will appear, and you or another user can log in again.
.SP 1
.IT
When you want to shut the computer down, make sure all processes
have finished, if need be, by killing them with
.I kill .
Then type
.I sync
or just log out.
When the disk light goes out, you can turn the computer power off.
Never turn the system off without first running
.I sync
or logging out (which does an implied
.I sync ).
Failure to obey this rule will generally result in a garbled file system
and lost data.
.LX
.SE "INCREASING THE SIZE OF YOUR RAM DISK"
.PP
If you have 1M or more of memory,
we advise you to increase the size of the RAM disk from 160K to 300K or more.
A larger ramdisk allows you to use the RAM disk to copy complete or partial
file systems from one diskette to another.
It also gives you plenty of space to add a few more utilities
to the ROOT file system. Finally, it allows you to compile much
larger programs without running out of disk space for the intermediate
results.
On the other hand it leaves you with less memory to run your
\*(Mx applications. Choosing a RAM disk of 300K leaves you enough
memory to recompile most the sources and perform many other tasks.
.PP
It is easiest, to use a 360K diskette to carry
this enlarged ROOT file system.
However, it is a little tricky, to use a 360K diskette to carry
a larger ROOT file system. Say you want to make a 512K RAM disk.
You may wonder how a 512K RAM disk
can be initialized by reading it in from a 360K diskette during the
boot procedure. 
The secret is that the 512K RAM disk is not completely full.
Part of it is initially empty so it can be used for scratch files.
Only the initialized part (up to 360K) has to be read in.
The only problem with this approach is that if you make new root file
systems, you should be careful that they do not exceed 360K of data.
Failing to do so may damage the file system on your diskette severely.
.PP
To install a 512K RAM disk, you must first make a 512K root file system
diskette as described below.
When \*(Mx is booted, it looks at the size of the root file system and sets
its size accordingly.
If you have more than 1 MB, you might even consider making a RAM disk
larger than 512K, although only 360K can be initialized at start-up time.
To do this, proceed as follows.
.LI
.IT
Take an empty, formatted diskette and label it 10.R512
.IT
Boot \*(Ms as described above and login as root.
Then type:
.HS
.Cx "for  i  in  cpdir  mkfs;  do  cp  /usr/bin/$i  /bin;  done"
.br
.Cx "/etc/umount  /dev/dd0"
.IT
Insert 10.R512 in drive 0 and type:
.HS
.Cx "mkfs  \(ent  /dev/fd0  512"
.br
.Cx "/etc/mount  /dev/fd0  /user"
.br
.Cx "cpdir  \(enmsv  /  /user"
.IT
Logout by typing CTRL-D.
.IT
Insert 01.BOOT in drive 0 and type CTRL-ALT-DEL to reboot 
using 01.BOOT, 10.R512 and 03.USR1.
.LX
.PP
Do not forget the \fB\(ent\fR option to \fImkfs\fR. It suppresses the check
if the new file system fits on the medium.
The program
.I cpdir
will tell you that it skipped the directory
.I /user
to avoid recursion.
.PP
By changing the argument
.I 512
to
.I mkfs
you can adapt the size of the RAM disk.
However, if you take a value less than 250 you will run into the problem
that \fImkfs\fP allocates not enough inodes to store all the
entries of the root file system.
If you have 1M of memory and you want to recompile the system a RAM disk of
300K is recommended.
Replace the last two occurrences of
.I /dev/fd0
by
.I /dev/dd0
if you prefer to use 720K diskettes, or by
.I /dev/hd3 ,
or any other hard disk partition,
if you want to load the RAM disk from the winchester.
Read the section on boot options below if you do.
.PP
Note that a copy of the programs
.I cpdir
and
.I mkfs
will be present in
.I /bin
on your new ROOT diskette.
.SE "ADAPTING PROGRAMS TO USE EXTRA RAM"
.PP
As distributed, the C compiler is tuned to work on even the
smallest Atari ST configuration.
This causes problems if you want to recompile (parts of) \*(Mx.
The first part of the C compiler proper,
.I /usr/lib/cem ,
as distributed is configured for a stack size of 40K, but it
needs about 70000 bytes more to compile some of the larger source files
on the distribution diskettes.
It is possible to compile small programs on a 512K machine
with the default memory allocation of the compiler.
.PP
If you have at least one of the following:
.Bu
more than 512K of memory
.Bu
two drives, either diskette or hard disk
.HS
.LP
there are ways to recompile all of \*(Mx.
Note that it is impossible to recompile some parts of \*(Mx
on an ST with only 512K of memory and a single drive.
.PP
You are strongly advised to execute the following procedure now
if you have more than the minimal 512K of memory.
.LI
.IT
Boot \*(Ms and login as root.
.IT
Type:
.HS
.Cx "cp  /usr/bin/chmem  /bin"
.br
.Cx "chmem  =35000  /usr/bin/make"
.br
.Cx "/etc/umount  /dev/dd0"
.IT
Insert 06.ACK in drive 0 and type:
.HS
.Cx "/etc/mount  /dev/dd0  /usr"
.br
.Cx "chmem  =110000  /usr/lib/cem"
.LX
.HS
.PP
A similar procedure can be executed if you encounter any other
program that needs more memory.
.SP 0.5
.SE "USING SINGLE-SIDED DISKETTES"
.SP 0.5
.PP
The distribution contains several 720K diskettes.
Most, but not all, Atari ST machines, have a disk drive that can 
handle 720K diskettes. Only a few older systems can only handle
360K diskettes.
If you have one of these systems do not despair.
You can split a single 720K diskette into a pair of 360K diskettes on a
system with a 720K disk drive. Since you do not have such a system
you will have to borrow one from a friend or perhaps your local dealer.
.PP
To split 04.USR2 into 13.USR2A and 14.USR2B proceed as follows:
.LI
.IT
Boot \*(Ms using 01.BOOT, 10.R512 and 03.USR1; login as root.
.IT
Type:
.HS
.Cx "for  i  in  cpdir  mkfs  rmdir;  do  cp  /usr/bin/$i  /bin;  done"
.br
.Cx "/etc/umount  /dev/dd0"
.IT
Insert 04.USR2 in drive 0 and type:
.HS
.Cx "/etc/mount  /dev/dd0  /user"
.br
.Cx "mkdir  /tmp/a"
.IT
Now copy files from \fI/user\fR to \fI/tmp/a\fR.
You should add files to /tmp/a until the command
.HS
.Cx "du  \(ens  /tmp/a"
.HS
reports a value just below 355.
.IT
Unmount using:
.HS
.Cx "/etc/umount  /dev/dd0"
.IT
Remove 04.USR2 and insert an empty, single-side formatted disk
labeled 13.USR2A in drive 0 and type:
.HS
.Cx "mkfs  /dev/fd0  360"
.br
.Cx "/etc/mount  /dev/fd0  /user"
.br
.Cx "cpdir  \(enmsv  /tmp/a  /user"
.br
.Cx "/etc/umount  /dev/fd0"
.br
.Cx "rm  \(enrf  /tmp/a"
.IT
Repeat the same process for the second half of the files on 04.USR2,
using an empty, single-side formatted disk labeled 14.USR2B.
.LX
.PP
Be careful about the subtle difference between
.I /usr
and
.I /user ,
between
.I /dev/fd0
and
.I /dev/dd0 ,
and between
.I 13.USR2A ,
.I 14.USR2B
and
.I 04.USR2 .
The result is two 360K diskettes that contain all of 04.USR2.
Similarly, you can divide others.
.PP
It may happen that you need more than two 360K disks to contain
all files of one 720K disk, because the file system itself
imposes some overhead that is now doubled.
Use three 360K diskettes in those cases.
.PP
After you have divided all other 720K diskettes and
you have verified your work, you should make another copy of your
root diskette (02.ROOT or 10.R512) and
modify the file \fI/etc/rc\fR on that new copy,
replacing the line
.CC "/etc/mount  /dev/dd0  /usr"
by
.CC "/etc/mount  /dev/fd0  /usr"
Now you can use this new 360K version of 
.MX
just like the original one.
However exercise some care when dealing with
examples in this chapter or section 7.2, since they assume a 720K
version. 
.SE "USING A HARD DISK"
.PP
If you have a hard disk and one or more partitions free for \*(Mx,
you can use it to keep (part of) the distributed diskettes on line.
If you have any choice, use a small (512K to 1M) partition 3 
(\fI/dev/hd3\fR) to hold the ROOT file system that is copied to the RAM disk
at boot time. See the section on boot options below.
One of the other partitions, for example 4 (\fI/dev/hd4\fR), can be as big
as 32M and can be mounted on \fI/usr\fR.
It is also possible to keep the root file system on diskette and only
use a partition to store the usr file system. In that case you can skip
step 6 below. The penalty for keeping the root file system on diskette
is an additional disk swap and some additional delay when booting the
system. There is no difference in behavior after booting.
You could use the whole disk (\fI/dev/hd5\fR) (up to 32 MB)
as one single \*(Mx file system, but that would make the disk useless
for \s-2TOS\s0.
.PP
This section describes the steps to set up \*(Mx on such a system.
.PP
.SS "Step 1: Backup the Hard Disk"
.PP
If you are already used your hard disk for \s-2TOS\s0, before even 
.I contemplating 
installing
.MX ,
you should make a complete backup of the contents of your hard disk onto
diskette or another medium.
As a bare minimum, installing
.MX
will require erasing one partition of your hard disk, and possibly two.
However, to prevent disaster in the event that you make an error during the
setup procedure, it is highly desirable that you backup the 
.I entire
disk before you even start.
Your files are too valuable to put at risk.
.PP
It is worth noting that 
.MX
has a program,
.I tos ,
that can read \s-2TOS\s0 diskettes.
Thus if you make your backup on diskettes, you will be able to read the files
into the
.MX
file system after you have completed the hard disk installation.
.SS "Step 2: Verify that Your Hard Disk is Atari Compatible"
.PP
There are a number of different hardware vendors for the Atari ST. Most
of their disks work with \*(Mx. However, some hard disks will not co-operate
with \*(Mx. For example it is known that some of the very first Supra
disk controllers will not work with \*(Mx, due to a bug in the controller.
Newer Supra disks (the ones with a SCSI out port) do not have
this problem.
.PP
To verify that 
.MX
is indeed able to correctly access your hard disk, boot
.MX
as described above, but instead of logging in as
.I ast ,
log in as
.I root ,
using 
.I Geheim
as password (note the upper case \fIG\fR).
If you are already logged in as
.I ast ,
use CTRL-D to log out, then log in again as 
.I root
(without rebooting).
Logging in as 
.I root
makes you the superuser and gives you the sharp sign (#) as prompt instead
of the usual dollar sign.
The superuser is the system administrator and has special privileges
denied ordinary users.
To install
.MX
on your hard disk, you will need these privileges.
Once the installation is complete, you should always log in as
.I ast ,
or create your own login name as described later in this manual.
.PP
Once you are successfully logged in as 
.I root ,
type:
.CC "dd  if=/dev/hd5  of=/dev/null  count=200"
After a short time, you should get the message:
.HS
.Cx "200+0  records  in"
.br
.Cx "200+0  records  out"
.HS
If you get an error message or no response,
.MX
cannot use your hard disk controller.
.PP
.SS "Step 3: Partition the Hard Disk"
.PP
Initialize the hard disk (formatting and partitioning) using the
tools supplied by Atari, notably the \fIHDX.PRG\fR utility.
If you have already partitioned your disk before, and you are happy with
the partition sizes you can skip this step. Be warned that partitioning
the hard disk will destroy all information on that disk.
\*(Mx is not equipped to initialize your disk.
The \*(Mx disk driver requires no special settings of the
.I pi_flag
and
.I pi_id
fields (see the Atari hard disk manual), mainly because the
Atari hard disk driver code is deficient in properly maintaining
the hard disk information found in sector 0.
This requires you not to mix up which operating system should
operate on which partition, unfortunately.
\*(Mx checks the super block on mounts and it is unlikely that a \s-2TOS\s0
partition will be accepted. However, writing to a \s-2TOS\s0 partition
by accessing \fI/dev/hd?\fR directly, although superuser only, is not
prevented. Be careful.
Similarly, avoid \s-2TOS\s0 accesses to \*(Mx partitions.
It is a good idea to remove the icons for the \*(Mx partitions from
the \s-2TOS\s0 desktop.
.PP
Another problem is that the \fIHDX.PRG\fR seems not to
format the last sector on the disk properly, so never use the
last sector of the last partition.
This is probably a bug in \fIHDX.PRG\fR.
So, whenever you make a \*(Mx file system on the last partition,
subtract 1 from the real number of sectors of that partition when
calling
.I mkfs .
.PP
If you have any choice, allocate a small partition 3
of 512K, and a large partition 4 of at least 10M.
This setup is assumed in the rest of this section.
.SS "Step 4: Make a MINIX File System on Each MINIX Partition"
.PP
Now that the disk is physically partitioned, it is time to put a
.MX
file system on each
.MX
partition.
To do this, determine the number of sectors in each partition.
\fIHDX.PRG\fR will have told you the number of sectors when partitioning.
The number may not be quite what you had expected due to the use of entire
cylinders and rounding effects.
Compute the number of 1K blocks in each
.MX
partition by dividing the number of sectors by 2 (one block is two
512-byte sectors).
.PP
An alternative is to use the command
.I readall 
with the option \fB\(ent\fR on each partition.
For example:
.HS
.Cx "readall \(ent /dev/rhd4"
.HS
will tell you the number of 1k blocks on \fI/dev/hd4\fR.
It is possible that during the execution of readall you get a few error messages
about unrecoverable disk errors. These error messages can be ignored safely.
.PP
To create a file system of, say, 512 blocks of 1K on partition 3
and 10239 blocks of 1K on partition 4, log in as root and type:
.HS
.Cx "mkfs  /dev/hd3  512
.br
.Cx "mkfs  /dev/hd4  10239
.HS
Notice the 10239 (10240 minus 1) due to the bug in \fIHDX.PRG\fR mentioned before.
For other
.MX
partitions (or sizes) type the analogous commands.
Do not run \fImkfs\fR on \s-2TOS\s0 or other partitions.
Be very careful not to make a typing error here, as making a new file system
destroys all information on the partition specified.
.PP
You can verify that the file systems have been made by typing:
.HS
.Cx "df  /dev/hd3"
.br
.Cx "df  /dev/hd4"
.HS
which will report on the i-nodes and blocks present on each file system.
The total number of blocks should agree with the number you used in the
\fImkfs\fR command.
.PP
You can now mount your new file systems.
To mount \fI/dev/hd3\fR (partition 3) on \fI/user\fR, type:
.CC "/etc/mount  /dev/hd3  /user"
To change to \fI/dev/hd3\fR, type:
.CC "cd  /user"
This puts you in the root directory of the partition 3 file system.
.SS "Step 5: Check for Bad Blocks"
.PP
With current manufacturing technology, it is nearly impossible for disk vendors
to deliver perfect drives.
Almost every drive has some bad blocks on it.
If 
.MX
were to use a bad block in one of your files, you might lose some valuable
data, so it is important to locate all the bad blocks before putting any files
on the disk and make sure they do not cause trouble.
.PP
The scheme used in 
.MX
is to put all the bad blocks into dummy files, so that the disk space allocator
will think they are in use and leave them alone.
This method is more efficient than wasting entire tracks as spares, as is
sometimes done.
Suppose that you have allocated partitions 3 and 4 for
.MX .
To locate the bad blocks on partition 3, first log in as
.I root ,
go to the root directory, and unmount the partition, if mounted,
by typing:
.SP 0.25
.HS
.Cx "cd  /"
.br
.Cx "/etc/umount  /dev/hd3"
.HS
.SP 0.25
It is important that the next commands be executed on the root device, since
they will attempt to mount and unmount \fI/dev/hd3\fR, which will fail if your working
directory is there.
To locate all the bad blocks, type:
.SP 0.25
.HS
.Cx "readall  \(enb  /dev/rhd3  >bad.3"
.HS
.SP 0.25
.PP
Depending on the size and speed of your disk, this operation may take a
substantial fraction of an hour.
Please be patient.
It is possible that during the execution of \fIreadall\fR you get a few error messages
about unrecoverable disk errors. These error messages can be ignored safely.
When it is finished, a prompt will appear on the screen.
When it does, you can examine the output files using \fIcat\fR, \fImore\fR,
or an editor, for example, by typing:
.SP 0.25
.HS
.Cx "cat  bad.3"
.HS
.SP 0.25
The output will be a shell script that calls \fIbadblocks\fR with up to seven
arguments, each one the number of a bad block.
Bad blocks often cluster together.
This is normal.
.PP
To mark the blocks as bad, type:
.SP 0.25
.HS
.Cx "sh  <bad.3"
.HS
.SP 0.25
When this command finishes, several files full of bad blocks may have been
created in the root directory of the device containing the bad blocks. In
the example above these files are created in the top level directory of /dev/hd3.
After mounting the disk you can examine them by typing:
.HS
.Cx "ls  \(enla"
.HS
They will all have names starting with \fI.Bad_\fR, followed by some numbers.
Do not examine or remove the files.
You can now remove the shell script by typing:
.SP 0.5
.HS
.Cx "rm  bad.3"
.HS
.SP 0.5
If you now type:
.SP 0.5
.HS
.Cx "df  /dev/hd3"
.HS
.SP 0.5
you will notice that the number of blocks used has increased by the number of
bad blocks found, and the number of free blocks has decreased by the same
amount.
.PP
If you have more 
.MX
partitions, go to the root directory and unmount the current partition.
Then mount the next partition and repeat the same process.
If the next partition is 4, the sequence is as follows (where the text
starting at the # signs are just comments):
.SP 0.5
.HS
.nf
.ta 2.0i
.Cx "cd /	# go to the root directory"
.Cx "/etc/umount /dev/hd3	# if still mounted
.Cx "readall \(enb /dev/rdh4 >bad.4	# find the bad blocks on partition 4"
.Cx "sh <bad.4	# mark the bad blocks on partition 4"
.Cx "rm bad.4	# remove the shell script"
.Cx "/etc/umount /dev/hd4"
.fi
.HS
.SP 0.5
.PP
There is a small chance that a bad block will occur in the i-node list of
a new file system.
If this occurs, you must go back to Step 3 and repartition the disk with
different sizes, trying until all of the i-node blocks are good.
.SP 1.5
.SS "Step 6: Initialize the Root File System"
.SP 1.5
.PP
When 
.MX
boots, it needs a root file system.
By default, this root file system is read from a 360K diskette and
copied into memory as a RAM disk.
If you have a hard disk an easier alternative is to read the root file
system from a hard disk partition, preferably \fI/dev/hd3\fR,
and copy it into the RAM disk.
.PP
This requires you to make a copy of the root file system onto \fI/dev/hd3\fR.
In the discussion below we will put the root file system
on the 512K partition \fI/dev/hd3\fR on which we have already made
an empty file system above.
However, you could equally well use another partition, but take
care that the size of the file system you make on that partition
(the argument to \fImkfs\fR) is used as the size of your RAM disk.
.PP
The procedure below is actually rather similar to the procedure
described before to increase the size of your RAM disk.
Proceed as follows:
.LI
.IT
Boot \*(Ms with 01.BOOT, any ROOT (02.ROOT or 10.R512) and 03.USR1 and login as root.
Then type:
.HS
.Cx "for  i  in  cpdir  mkfs  chmod;  do  cp  /usr/bin/$i  /bin;  done"
.br
.Cx "/etc/umount  /dev/dd0"
.br
.Cx "/etc/mount  /dev/hd3  /user"
.br
.Cx "cpdir  \(enmsv  /  /user"
.IT
Logout by typing CTRL-D.
.LX
You can now test if the new root file system really can be used
to boot from.
Insert 01.BOOT in drive 0 and type CTRL-ALT-DEL to reboot.
You will be confronted again with the message:
.HS
.Cx "Insert ROOT diskette and hit RETURN (or specify bootdev)"
.HS
As alternative for the insertion of 02.ROOT or 10.R512 as second
step in the boot procedure you now have three option:
.LI
.IT
Keep the 01.BOOT diskette in drive 0, and hit RETURN.
\*(Ms will not find a file system on the diskette and will try to
load the root file system from hard disk partion 3, precisely where
we have created our new root file system.
.IT
Reply with
.HS
.Cx "3,3"
.HS
to override the default by loading the root file system from hard disk
partition 3.
.IT
Reply with any other drive specification, like
.HS
.Cx "3,2"
.HS
if you want to load the root file system from partition 2, for instance.
.LX
.SP 1
.SS "Step 7: Initialize \f4/usr\fR"
.SP 1
.PP
The next step is creating all the directories.
A shell script called \fI/etc/setup_usr\fR has been provided to do most of the
work.
It creates a large number of directories.
Next, it copies files from the distribution diskettes
to the \fI/usr\fR tree on the hard disk.
It asks for 03.USR1 to 09.SRC3 in sequence.
Just follow the instructions that appear on the screen until the 
\*(OQInstallation completed\*(CQ message appears.
To perform the installation be sure you are logged in as \fIroot\fR.
We assume that you have setup \fI/dev/hd4\fR as described above,
and that \fI/dev/hd4\fR contains at least 10M.
Then, proceed as follows:
.HS
.LI
.IT
Boot \*(Ms using 01.BOOT, any ROOT (02.ROOT, 10.R512 or hd3) and 03.USR1 and login as root.
.IT
Type the commands:
.HS
.Cx "for  i  in  cpdir  test  echo;  do  cp  /usr/bin/$i  /bin;  done"
.br
.Cx "/etc/umount  /dev/dd0"
.br
.Cx "/etc/mount  /dev/hd4  /usr"
.br
.Cx "/etc/setup_usr"
.IT
Follow the instructions displayed by the \fIsetup_usr\fR script.
If your partition is smaller than 10M, the best thing to do is to install only
the binaries onto the hard disk. Type \fIquit\fR when the system asks
you to insert disk 07 (07.SRC1).
Installing only the binaries will require 4M.
.LX
.PP
Except for the boot diskette and the tos diskette, all the distribution diskettes are
normal 
.MX
file systems that you can mount and inspect if something should go wrong.
When this shell script finishes, the entire
.MX
file system will be installed on the hard disk.
Most of the files on the distribution diskettes are compressed files
(with suffix \fI.Z\fR) or compressed archives (with suffix \fI.a.Z\fR).
If, for some reason, installation fails part way through, you may be left
with some \fI.a.Z\fR, \fI.a\fR or \fI.Z\fR files on the disk
A file \fIfile.a.Z\fR can be decompressed using :
.HS
.Cx "compress \(end file.a.Z"
.HS
If the result is an archive (with suffix \fI.a\fR), you can extract the
files from the archive with the \fIar\fR command, for example:
.HS
.Cx "ar x file.a"
.HS
At this point the files \fIfile.a.Z\fR and \fIfile.a\fR can be removed.
The only archive that you \fImust\fR keep as an archive is \fIlibc.a\fR
as the C compiler expects it this way.
Do not extract the individual files from it!
.PP
From now on you can mount \fI/dev/hd4\fR at boot time as \fI/usr\fR by making a
small change in
.I /etc/rc
found on the ROOT file system (diskette or winchester).
Use 
.I mined 
(see chapter 9 on how to use \fI mined\fR) to change the first
two lines that read:
.HS
.Cx "/bin/getlf  \(fm\(fmPlease insert /usr diskette in drive 0.  Then hit RETURN.\(fm\(fm"
.br
.Cx "/etc/mount /dev/dd0 /usr"
.HS
by a single line that reads:
.HS
.Cx "/etc/mount /dev/hd4 /usr"
.HS
Inserting diskette 03.USR1 will no longer be necessary at boot time.
.SP -0.5
.SE "USING A MEGA ST"
.SP -0.5
.PP
The Mega ST series is internally quite similar to the 
Atari 520 ST and 1040 ST machines. It has more memory, which is automatically
supported by \*(Ms.
It has a blitter chip, but currently \*(Ms does not support it.
Another standard feature is the battery powered real time clock.
To eliminate the need to type the date each time the system is boot, 
a small program that reads out the current date and
time from the real time clock, and sets the \*(Mx time accordingly has
been provided.
If you have a Mega ST you are advised to adapt the file
.I /etc/rc
so that it will use that program
.I megartc
whenever you boot. Replace the line that reads:
.HS
.Cx "/usr/bin/date \(enq </dev/tty"
.HS
by the following two lines:
.HS
.Cx "/usr/bin/megartc"
.br
.Cx "/usr/bin/date"
.HS
Note that
.I megartc
is found on 03.USR1.
This change has the following effect.
The program
.I date
queries the terminal for the date and then installs the date.
The program
.I megartc
takes the date from the real time clock instead of asking for it from
the terminal.
The second line causes the date to be printed.
.PP
As an aside, please note that any other commands inserted in the file
.I /etc/rc
will be executed before the system is booted.
However, when inserting commands there, be sure that they do not require
programs or files that are on diskettes that have not yet been mounted.
.SP -0.5
.SE "USING A DISK CONTROLLER BASED CLOCK"
.SP -0.5
.PP
Since the original Atari ST did not contain a battery powered real time 
clock, quite a number of add-on clocks have appeared on the market.
\*(Ms supports the real time clock from Weide.
It also supports the clocks available on various third party
disk controller boards, but only if you recompile your kernel with
the \fB\(enDCLOCKS\fR option in the kernel Makefile turned on.
See chapter 7 for an explanation of rebuilding the kernel.
For both types of clocks
a small program that reads out the current date and
time from the real time clock, and sets the \*(Mx time accordingly has
been provided.
In both cases you are advised to adapt the file
.I /etc/rc
so that it will read the real time clock whenever you boot.
If you have a Weide real time clock replace the line that reads:
.HS
.Cx "/usr/bin/date \(enq </dev/tty"
.HS
by the following two lines:
.HS
.Cx "/usr/bin/weidertc"
.br
.Cx "/usr/bin/date"
.HS
If you have a disk controller with a real time clock
and have a modified operating system (\fIMINIX.IMG\fR) on your 01.BOOT
diskette, replace the same line by:
.HS
.Cx "/usr/bin/diskrtc \fIcontroller\fR"
.br
.Cx "/usr/bin/date"
.HS
\fRwhere \fIcontroller\fR is one of 
.I supra , 
.I icd , 
.I bms1
(for a BMS 100 controller) or 
.I bms2
(for a BMS 200 controller).
Note that also these programs
are found on 03.USR1.
.SE "BOOT PROCEDURE OPTIONS"
.PP
The boot sequence we have described so far always starts with
a 360K BOOT diskette in drive 0, followed by
a 360K ROOT diskette in drive 0.
Between the BOOT and ROOT diskette you have always answered the
question:
.HS
.Cx "Insert ROOT diskette and hit RETURN (or specify bootdev)"
.HS
by hitting RETURN.
If the ROOT file system is found on another device you may specify
that device as:
.HS
.SP 0.50
     \fImajor,minor\fR
.HS
.SP 0.50
where
.I major
is a decimal number specifying the device type and
.I minor
is a decimal number specifying the drive and/or partition.
These \fImajor,minor\fR pairs correspond with the numbers you see
in the output of:
.SP 0.50
.HS
.Cx "ls  \(enl  /dev"
.HS
.SP 0.50
Some of the useful combinations are:
.sp
.SP 1
.TS
center,box;
c c c c
n n l l.
\fBMajor	Minor	Device	Description\fR
_
2	0	fd0	360K diskette in drive 0
2	1	fd1	360K diskette in drive 1
2	8	dd0	720K diskette in drive 0
2	9	dd1	720K diskette in drive 1
3	1	hd1	partition 1 of hard disk 0
3	2	hd2	partition 2 of hard disk 0
3	3	hd3	partition 3 of hard disk 0
3	4	hd4	partition 4 of hard disk 0
3	5	hd5	complete hard disk 0
.TE
.SP 1
.sp
.PP
So, if ROOT is found on a 720K diskette in drive 1
the second line of your screen will look like:
.HS
.SP 0.5
.Cx "Insert ROOT diskette and hit RETURN (or specify bootdev) 2,9"
.SP 0.5
.HS
.PP
If you specify nothing or anything illegal, \*(Mx will check two
default devices in sequence. First it tries to read the super block
of the ROOT file system on 2,0 (360K diskette in drive 0).
Only if that fails (read error or illegal super block) it tries 3,3
(partition 3 of hard disk 0).
That is why we advised you to use \fI/dev/hd3\fR as copy of the RAM disk.
.PP
One of the more exotic options of the boot sequence is to read the
\*(Mx operating system itself from a \s-2TOS\s0 file, not using the BOOT
diskette. On the diskette 00.TOS you find a \s-2TOS\s0 program
\fIMINIX.PRG\fR
that takes as first argument the name of a \s-2TOS\s0 file,
default \fIMINIX.IMG\fR, that contains the operating system.
You can create the file \fIMINIX.IMG\fR yourself by reading enough sectors
from the BOOT diskette, starting with sector 0,
but it requires at least one other diskette, hard or RAM disk besides a:.
The procedure below assumes that you have a \s-2TOS\s0 RAM disk named
.I m: .
Proceed as follows:
.LI
.IT
Start \s-2TOS\s0.
.IT
Insert a copy of 00.TOS, in drive 0.
.IT
Double click icon FLOPPY DISK A.
.IT
Double click \fICOMMAND.TOS\fR on A:
.HS
.Cx "rflop  a:  m:\eminix.img  100000"
.IT
Insert protected 01.BOOT if you are asked and hit RETURN.
.IT
When done, put \fIMINIX.PRG\fR and \fIMINIX.IMG\fR onto a \s-2TOS\s0 diskette
.LX
.PP
The third argument to \fIRFLOP\fR is the number of bytes to read.
100000 is more than sufficient for the operating system as distributed.
You can now copy \fIMINIX.PRG\fR and \fIMINIX.IMG\fR
to a \s-2TOS\s0 partition of the
hard disk.
Assuming that you normally boot \s-2TOS\s0 from the hard disk, you can
subsequently switch to \*(Mx by double clicking \fIMINIX.PRG\fR.
If you want to switch back to \s-2TOS\s0 you logout by typing CTRL-D.
If you see the prompt 
.I login: 
again, type CTRL-ALT-DEL.
.SP -0.7
.SE "UNPACKING THE SOURCES"
.SP -0.3
.PP
The sources, except the compiler and \fIelle\fR, 
are on the SRC diskettes. 
These diskettes are normal \*(Mx file 
systems, which you can mount using the command:
.HS
.Cx "mount /dev/dd0 /user"
.HS
The files on the distribution diskettes are
compressed archives (with suffix \fI.a.Z\fR).
If you want to extract the sources from 
a file \fIfile.a.Z\fR you should first copy 
this file to either an empty diskette, or
to the RAM disk, if the latter is large enough. 
Typically about 4 times the size of the compressed file is 
required when extracting the sources. If later on you want to
recompile the sources even more space may be required. That is why you first
should copy the compressed source file to an empty diskette.
Your copy of \fIfile.a.Z\fR can be decompressed using:
.HS
.Cx "compress \(end file.a.Z"
.HS
After decompressing you can remove your copy of \fIfile.a.Z\fR.
Now you can extract the
files from the archive with the \fIar\fR command, for example:
.HS
.Cx "ar x file.a"
.HS
At this point all files from the archive are extracted.
You can now remove \fIfile.a\fR since it is no longer needed.
.SP 2
.SE "THE TOS TOOLS"
.SP 2
.PP
Several tools have been developed for \s-2TOS\s0.
In the early stages of the \*(Ms port \s-2TOS\s0 was used as the
development environment. That forced us to port tools like
.I mkfs
and
.I build ,
and to develop the programs
.I minix
and
.I relmix .
Later, when the native \*(Ms C compiler became available, we could use
\*(Ms itself for further development.
Rather than simply discarding the \s-2TOS\s0 tools, we have included them in the
distribution for the benefit of people wishing to do further \*(Ms
developments using \s-2TOS\s0.
Below we describe these tools in the same style as the \*(Mx commands.



.SP 1
.CD "BUILD.PRG \(en build \f4MINIX.IMG\fR out of its constituent parts"
.SX "build \fIbootblok kernel mm fs init menu minix.img"
.FL "\fR(none)"
.PP
.I Build
takes the six constituent parts and
produces the \*(Ms operating system image.
That image, if written onto a diskette starting at sector 0,
is bootable on the Atari ST.
Alternatively, the program \fIMINIX.PRG\fR can be used once \s-2TOS\s0 is
up and running.



.SP 1.5
.CD "FIXKEYS.PRG \(en patch BOOT diskette for \s-2TOS\s0 keyboard table"
.SX "fixkeys \fR[\fB\(end\fR] [\fB\(eno\fR] \fIdrive"
.FL "\(end" "Double-sided diskette"
.FL "\(eno" "Accept not only a: and b:"
.EY "fixkeys a:" "Modify BOOT diskette in drive a:"
.PP
.I Fixkeys
patches the keyboard tables of the currently active version of \s-2TOS\s0
into the \*(Ms operating system image
as normally found on the BOOT diskettes.
It can only operate on diskettes, not on file images.


.SP 1
.CD "KEYTBL.TTP \(en display the keyboard tables"
.SX "keytbl.ttp \fR[\fIfile\fR]"
.FL "\fR(none)"
.PP
.I Keytbl
writes the keyboard tables to the file whose name is gives as a
parameter (or to standard output if no parameter is present). This file
can be used when recompiling the kernel. Refer to chapter 7 for details
on how to recompile the kernel.



.SP 1
.CD "MINIX.PRG \(en boot \*(Ms from an image on file"
.SX "minix \fR[\fIimage\fR]"
.FL "(none)"
.EY "minix minix.img" "boot \*(Ms from minix.img"
.PP
.I Minix
allows you to boot \*(Ms if \s-2TOS\s0 is already up and running.
It reads the operating system image from a \s-2TOS\s0 file into memory,
copies the image to address 0 and
jumps to the address found at location 4.
There is no way back to \s-2TOS\s0, except by rebooting the machine.



.SP 1
.CD "MKFS.PRG \(en make a \*(Ms file system"
.SX "mkfs \fR[\fB\(endol\fR] \fIdrive prototype"
.FL "\(end" "Double-sided diskette"
.FL "\(eno" "Overwrite: accept not only a: and b:"
.FL "\(enl" "Make a listing on standard output"
.EX "mkfs a: proto" "Make a file system on drive a:"
.EX "mkfs -d b: 360" "Make empty 360 block file system"
.PP
.I Mkfs
builds a file system and copies specified files to it.
See chapter 8 for a description of the proto file syntax.
The files used to initialize the new file system
should conform to the \s-2TOS\s0 syntax,
including backslashes and drive specifications.



.CD "RELMIX.PRG \(en change loadfile from .68K to .MIX format"
.SX "relmix \fR[\fB+\fIamount\fR] \fR[\fB\(mi\fIamount\fR] \fR[\fB=\fIamount\fR] \fIprog.68k prog.mix"
.FL "+" "Increase memory allocation"
.FL "\(mi" "Decrease memory allocation"
.FL "=" "Set memory allocation"
.EY "relmix =2000 x.68k x.mix" "Make \*(Ms style loadfile"
.PP
The Alcyon 4.14 C compiler, part of the Atari ST developers kit,
produces a loadfile in .68K format. A simple
transformation of the header, removal of the symbol table,
and a transformation of the relocation information as performed
by the RELMOD.PRG program (also part of the developers kit)
does the trick.



.CD "RFLOP.PRG \(en read bytes from diskette"
.SX "rflop [\(end][\(eno] \fIdrive file bytes"
.FL "\(end" "Double-sided diskette"
.FL "\(eno" "Accept not only a: and b:"
.EY "rflop a: minix.img 100000" "Read \fIminix.img\fR from BOOT diskette"
.PP
An arbitrary number of bytes is read from the diskette and written
to a \s-2TOS\s0 file. Reading always starts at sector 0.



.CD "WFLOP.PRG \(en write bytes to diskette"
.SX "wflop \fR[\fB\(end\fR] [\fB\(eno\fR] \fIdrive file"
.FL "\(end" "Double-sided diskette"
.FL "\(eno" "Accept not only a: and b:"
.EX "wflop a: minix.img" "Make BOOT diskette"
.PP
A \s-2TOS\s0 file is written to a diskette, starting at sector 0.
This overwrites the information in sector 0 used by \s-2TOS\s0 to
determine the type of the diskette.
.SE "TROUBLESHOOTING"
.PP
As a user of \*(Ms you may be confronted with some of the error messages
the system can produce.
The following subsections give guidelines on you how to react.
It also explains how you can use the built-in debugging aids.
.PP
If you have problems booting the system, try
the following steps:
power down the machine,
wait 10 seconds,
insert the BOOT diskette in drive 0,
and power up the machine.
If you have a hard disk and normally boot from the hard disk directly,
you may either force booting from the diskette as described in the
Atari hard disk manual, or start \*(Ms using the supplied \s-2TOS\s0 program
\fIMINIX.PRG\fR, as described in section 3.9 of this manual.
.PP
Either way, the screen should turn black and you will see two
lines printed on the top of the screen, asking you to insert the ROOT
diskette.
If these lines do not appear, the BOOT diskette is probably damaged.
.PP
Hitting RETURN at this point should give one more line. If not, you
might suspect the keyboard or the BOOT diskette.
Normally, when the root file system is being read in,
regular progress reports appear on the screen.
If not, the diskette drive may not be working correctly with the
\*(Ms diskette driver
(e.g., because your diskette controller
does not generate interrupts as it should).
This should not be a problem with all known Atari ST production models,
but we have heard about some problems with very old development machines.
If disk error messages appear on the screen, your
drive may need slower step rates than usual.
Official Atari diskette drives should work correctly.
.PP
If the system behaves funny or even crashes while loading the root file
system, the ROOT diskette is suspect. 
It might be corrupted or too big for this machine. 
If so, try it with (a copy of) your 02.ROOT diskette.
.PP
If you have gone through these critical initial steps you should not
have any problems getting \*(Ms booted, since the essential resources,
the diskette, the keyboard and the screen are probably all right.
.SP 1
.SS "Error Messages"
.SP 1
.PP
Many of the error messages are also found in \*(Mp.
Here we list the \*(Ms specific ones.
In all cases % followed by a letter gives the 
.I printf 
format of the number.
.PP
Three messages are printed by the kernel if commands
running on top of the operating system itself encounter problems,
such as unsolicited hardware traps and stack overflow.
These three are:
.in +0.25i

.Op "\(bu sig=%d to pid=%d at pc=%X"
Generated if bus errors, segmentation faults, illegal instructions or
funny traps are encountered,

.Op "\(bu Stack low (pid=%d,pc=%X,sp=%X,end=%X)"
If a stack overflow has happened or is about to happen, and

.Op "\(bu Unexpected trap.  Vector = %d"
.Op "   This may be due to accidentally including"
.Op "   a non-MINIX library routine that is trying to make a system call."
If any of the trap instructions is executed that is not used by \*(Ms.
In both cases, the system will continue, but the program is likely to
be aborted with a core dump generated on the file
.I core .
.in -0.25i
.sp
.LP
A number of messages announce unexpected hardware events, sometimes
only a warning, sometimes more serious, but not immediately fatal.
In this category fall:
.in +0.25i

.Op "\(bu fd%d: timeout"
No diskette in drive (you have 15 seconds to insert one)

.Op "\(bu fd%d: read: dma status = 0x%x"
DMA error on diskette read request

.Op "\(bu fd%d: read sector %d: fdc status = 0x%x"
Diskette controller error on read request

.Op "\(bu fd%d: write protected"
Writing to write-protected diskette

.Op "\(bu fd%d: write sector %d: fdc status = 0x%x"
Diskette controller error on write request

.Op "\(bu fd%d: recalibrate failed. status = 0x%x"
Cannot find track 0

.Op "\(bu hd: read: drive=%d sector=%D status=0x%x"
Hard disk error on read request

.Op "\(bu hd: write: drive=%d sector=%D status=0x%x"
Hard disk error on write request

.Op "\(bu DMA interrupt discarded"
Unsolicited interrupt from device on DMA bus

.Op "\(bu midi interrupt: status=%x, data=%x"
Unsolicited interrupt from MIDI interface

.Op "\(bu Fake interrupt handler for %s. trap = %02x"
Unsolicited interrupt from:
.nf
.in +0.25i
timint,00: timer A of MFP chip
timint,01: timer B of MFP chip
timint,03: timer D of MFP chip
siaint,00: MFP RS232: char received
siaint,01: MFP RS232: receive error
siaint,02: MFP RS232: char transmitted
siaint,03: MFP RS232: transmit error
iob,01: MFP RS232 Data Carrier Detect
iob,02: MFP RS232 Clear To Send
iob,03: unused
iob,06: MFP RS232 Ring Indicator
iob,07: Monochrome Monitor Detect
.in -0.25i
.fi

.Op "\(bu Printer is not available"
Ready bit off: not connected or off line

.Op "\(bu printer: still busy"
Interrupt received, but not ready
.in -0.25i
.sp
.LP
More serious conditions cause a system panic. A message is
printed and an infinite loop is entered. Only a reset helps:
push the RESET button (sometimes CTRL-ALT-DEL works as well).
The most important \*(Ms specific kernel panics are:
.in +0.25i

.Op "\(bu dma:ASSERT(%s) failed"
Consistency checking in stdma.c

.Op "\(bu fd:ASSERT(%s) failed"
Consistency checking in stfloppy.c

.Op "\(bu Nonexisting interrupt. Vector = %d"
A trap via one of the vectors that is unassigned

.Op "\(bu Unexpected interrupt.  Vector = %d"
A trap via one of the autovectors not used by the ST

.Op "\(bu trap via vector %d"
A synchronous trap in kernel mode

.Op "\(bu no shadow?"
Two processes share an ORIGINAL, but neither points to a SHADOW

.Op "\(bu rmshadow: cannot handle physio shadows"
SHADOW with p_physio set must be copied to ORIGINAL.

.Op "\(bu only shadow(s)"
All that share ORIGINAL have SHADOW set

.Op "\(bu tty_init: unknown terminal %d"
For all NR_TTYS an initialization routine must be called
.in -0.25i
.sp
.LP
The important file system panics are:
.in +0.25i

.Op "\(bu Invalid root file system"
.HS
.Op "\(bu RAM disk is too big. # blocks = %d"
.HS
.Op "\(bu Root file system corrupted.  Possibly wrong diskette."
.HS
.Op "\(bu init: can't load root bit maps"
.HS
.Op "\(bu Disk error loading BOOT disk %d"
.in -0.25i
.sp
.LP
For all these errors retry booting with (a copy of) 02.ROOT.
.SP 0.5
.SS "Debugging Aids"
.SP 0.5
.PP
Some of the internal tables can be inspected by special key
combinations.
The keyboard driver recognizes the following key combinations
and calls debugging routines in the kernel:
.HS
.TS
center,box;
l l.
CTRL-ALT-F1	dump of the process table
CTRL-ALT-F2	dump of the memory map
CTRL-ALT-F3	dump of the status of the current process
.TE
.HS
.PP
The process table shows
the current and lowest stack pointer detected,
the CPU time spend in user mode and system mode,
and the memory slot occupied for each process, including
kernel tasks, as well as other information.
.PP
The memory map shows (for user processes only) the location and
length of the text, data and stack segments,
and the shadowing fields
.I p_shadow ,
.I p_nflips
and
.I p_physio .
.PP
The status of the current process shows the register values
most recently saved,
a memory dump around the location of the program counter, and
a memory dump around the location of the stack pointer.
The memory dumps can be used to give a stack trace and,
by manual disassembly, the instructions executed most recently.
.PP
The CTRL-ALT-F6 key combination toggles an option to dump
the same tables whenever the message
.HS
sig=%d to pid=%d at pc=%X
.HS
is printed and whenever the system panics.
By default the \*(OQautomatic table dump\*(CQ option is OFF.
.PP
The CTRL-ALT-F5 key combination toggles an option to send all kernel
generated output not only to the screen but also to the line printer.
By default the \*(OQkernel output to printer\*(CQ option is OFF.
If the printer is offline, the printing is temporarily suppressed.
If the \*(OQkernel output to printer\*(CQ option is ON, and the printer
switches from online to offline,
it may take a few seconds to detect this,
since initially it looks similar to a printer buffer full condition.
Be patient.
.PP
The CTRL-ALT-F4 key combination toggles an option to send all kernel
generated output to the screen.
By default the \*(OQkernel output to screen\*(CQ option is ON.
.PP
A good procedure, if you encounter a problem and you want to spot it,
is to isolate the problem such that it is reproducible.
Then, insert paper in the printer and
toggle CTRL-ALT-F5 and CTRL-ALT-F6 to capture the debugging
information on paper while you reproduce the error situation.
.PP
If the problem is in a command the
.I core
file contains a memory dump at the time of the crash.
These post mortem dumps can be analyzed using the mdb debugger.
Refer to chapter 9 for a description of 
.I mdb .
.PP
If problems are encountered in the \*(Ms driver, you have a chance
that that driver has debugging statements coded in. By changing
either the #DEBUG or #TRACE definitions, you can effectuate these
statements, but only after recompilation. 
Refer to chapter 7 on how to recompile
.MX