              Minix Virtual Console Patches Release 1.0

                      Gordon Irlam, 1990 May 13

1) Overview.
   ---------

This set of patches allows the Minix 1.5.10 (aka Minix 1.5) IBM PC kernel
sources to be patched to allow multiple ttys to be associated with the
system's physical display and keyboard.  At any time a single tty is
associated with the physical console.  Keys are defined to allow the tty
currently associated with the physical console to be changed.  The number of
virtual consoles is fixed and can only be altered by recompiling the kernel
and building a new boot disk.

2) Use.
   ----

Once you have installed the virtual console patches you will be able to have
multiple login sessions and switch between them using the function keys.

F5 is used to cycle from one virtual console to the next.  This is
particularly convenient if you only have two virtual consoles as you can use
F5 to toggle between them.

The keys F1 through F4 are used to switch directly to any one of the first 4
virtual consoles.  If you have fewer than 4 virtual consoles some of these
keys will have no effect.  The keys previously bound to F1 through F3 are now
bound to F6 through F8.  F6 toggles the scrolling mode, F7 lists the process
table, and F8 lists the memory map.  This takes a bit of getting used to.

When you switch virtual consoles the previous virtual console is hidden from
view, but output can still be written to it, and programs can still read
characters that have been buffered as input to that virtual console.  If you
want to stop a program from running you can press ctrl-S before switching
screens.  This will stop the program when it next tries to write to the
screen.

3) Installation.
   -------------

It is recommended that you read this document in full before installing the
virtual console patches.

To install these patches you will need the Minix 1.5.10 IBM PC kernel sources.
The crc's of the files to be modified should match the values listed below.

32891  25528 console.c
36166  23181 keyboard.c
32720   4897 proto.h
02936   3663 table.c
19472  35315 tty.c
07201   6653 tty.h

It should also be possible to apply these patches to the Minix 1.5.5, 1.5.6,
1.5.8, or 1.5.9 kernel sources without significant difficulty, but on any
earlier versions of Minix you may encounter some problems.

Patch the kernel sources with commands similar to the following.

cp console.c keyboard.c tty.c tty.h kernel
cat proto.h.cdif table.cdif | patch -d kernel

Check that the crc's of the resulting files match the values listed in the
file kernel_crcs included as part of this distribution.

You may wish to edit tty.h to adjust the number of virtual consoles to be
supported.  This value is given by the symbolic constant NR_CONSOLES.  The
default value of two virtual consoles is convenient as this allows you to swap
back and forth between the two screens using a single key (F5).  This is
particularly useful if want to compare two different versions of a file.  The
operating system consumes roughly 165k of memory plus 4k for each virtual
console.  In addition /usr/bin/login wastes 16k for each line that has logins
enabled that is not currently in use.

Compile a new version of the kernel and build a boot disk.  Keep your original
boot disk just in case something goes wrong.

Now make the character special files for the new tty devices.  If you use a
RAM disk make sure you do this on the root image device and not on the RAM
disk.  Also make sure you keep a copy of your original RAM disk in case
something goes wrong.

su root

mknod dev/console c 4 0	# special console device
# Note, dev/tty0 probably already exists.
mknod dev/tty0 c 4 0    # alias for dev/console to provide backward
			# compatibility (used by init and other programs)

# Note, dev/tty1, and dev/tty2 probably already exist.
mknod dev/tty1 c 4 1    # first virtual console
mknod dev/tty2 c 4 2    # second virtual console
# If you have more than two virtual consoles you should also create dev/tty3,
# dev/tty4, and so on.

mknod dev/tty64 c 4 64  # first serial line
mknod dev/tty65 c 4 65  # second serial line

chmod ugo+rw dev/console dev/tty*    # set access permissions

Now edit the etc/ttys files on the root image device to enable logins to be
performed on the appropriate lines.  Here is an example.

00tty0
10tty1
10tty2
0ftty64
0ftty65

The first character of each entry indicates whether logins are enabled on the
terminal line, the second denotes the baud rate, and the remaining characters
identify the terminal device.  As an abbreviation it is possible to omit the
string "tty" for a device of the form "ttyn".  This has not been done in the
above example.  For more details on the format of etc/ttys have a look at the
first few pages of tools/init.c.

The above example will work without modification if you have built a kernel
with two virtual consoles.

It is important that logins are disabled on tty0.  Check that etc/ttys no
longer contains either of the following two entries "100", or "10tty0".  (The
virtual console kernel is usable on a system that has logins enabled on tty0,
but only if logins are not enabled on any of the virtual consoles at the same
time.)

You should also edit etc/ttytype, creating new entries for the virtual
consoles, and adjusting the serial line names.  You should use the terminal
name "minix-vc" if you want linewrap turned off.  Or "minix-vcam" if you want
linewrap turned on.  Linewrap causes the cursor to wrap around to the start of
the next line if it reaches the end of the current line.  The etc/ttytype file
will probably end up looking something like this.

minix-vcam tty0
minix-vcam tty1
minix-vcam tty2
unknown tty64
unknown tty65

Finally copy the new termcap file that has been provided to etc/termcap.

You are now ready to try out the new kernel.  Shut Minix down and reboot using
the new boot disk.  The system should read itself from disk and bring up the
boot menu.  You should select the usual options to boot Minix.  If all goes
well things will proceed as normal and, apart from a copyright message, you
should not notice any difference in the boot process.  By hitting F5 you
should now be able to switch between virtual consoles, and login on either
console.

4) Customization.
   --------------

If the patches have worked you will probably find it convenient to alter the
etc/rc file, and/or your .profile so that you can easily keep track of which
virtual console is currently in the foreground.

Compile setterm.c, and place it in /usr/bin or /usr/local/bin.

cc -o setterm setterm.c
chmem =8192 setterm
cp setterm /usr/local/bin

If you have a color display you can now add the following lines to etc/rc.

/usr/local/bin/setterm -term minix-vc -foreground white -background blue \
                       -clear rest -store > /dev/tty1
/usr/local/bin/setterm -term minix-vc -foreground cyan -background blue \
                       -clear all -store > /dev/tty2

This sends sequences of escape characters to the first two virtual consoles to
set the foreground and background colors.  The "-clear" argument then clears
the screen, so that the entire screen will be set to the specified colors.
For the first virtual console only the bottom half of the screen is cleared so
that any messages that have been displayed by etc/rc are not erased.  The
"-store" option makes the current screen attributes, including the colors, the
default attributes, so that even if an application changes the current screen
attributes they can be readily restored - either by the application or by
manually sending a string to restore the default attributes.  It is necessary
to specify "-term minix-vc" in the above commands because the TERM environment
variable is undefined while etc/rc is executing.

If you have a monochrome display you can add the following to etc/rc.

setterm -term minix-vc -bold on -store > /dev/tty1

This turns on bold video for the first virtual console.

Regardless of your display type you should add lines similar to the following
to your .profile file.

eval `tset`
setterm -initialize
export TERM

This will set the TERM environment variable to the value specified by
/etc/ttytype.  You can replace the line "eval `tset`" by "TERM=minix-vc" or
"TERM=minix-vcam" if you wish to override the terminal type specified in
/etc/ttytype.  Note that if TERM is not initialized then by default it has the
value "minix".  This precludes many of the options in setterm from being
utilized - they can still be specified but they will be ignored.

"setterm -initialize" sends the appropriate initialization string to the
current virtual console.  This includes turning linewrap on or off as
specified by the value of TERM.

You may want to add the following lines to your .profile, following the
previous lines.

PS1=`setterm -bold on; tty | cut -c9-`'< '`setterm -bold off`
export PS1

This will give you a bold prompt looking something like this.

2<

The first character indicates the virtual console that you are using.

Type setterm without any arguments to get a list of all the possible arguments
that can be specified.  Note that "setterm -softscroll on" can be used to
enable software scrolling if you have non-standard display hardware.

A full list of escape sequences can be found in the file escape_codes that is
part of this distribution.

5) Technical Notes.
   ----------------

The following notes are mainly of interest to people who want to modify the
Minix kernel.  But, even if you don't you may find it useful to quickly skim
through them.

    - The changes made go beyond adding support for virtual consoles.  Many of
      the changes have attempted to clean up the tty driver.  In particular
      many of the changes relate to separating the generic tty code from the
      code that implements a particular class of tty devices.  The console
      driver and tty driver are now reasonably separate.  The tty driver
      however still contains a lot of the high level RS232 code.  Many changes
      have been an expression of personal preference as to how the tty task
      should be written.

    - The main files that have been changed are tty.c, tty.h, console.c, and
      keyboard.h.  Other files have changed only to the extent necessary to
      support the changes to these files.

    - The virtual console driver does not make use of the routines scr_up,
      scr_down, or wait_retrace in klib88.x.  These routines can be deleted.
      The virtual console driver does not call vid_copy in klib88.x with
      buffer equal to zero.  The code for supporting this can be deleted.

    - The erase display and erase line escape sequences now take a numeric
      parameter that specifies the region to be deleted.  Additional set
      graphic rendition aspects have been implemented.  The reset to initial
      state, and device control string sequences have been added.

    - The reset to initial state, rendition set, and rendition reset control
      functions are intended only for use on a login session basis, they
      provide a means to set up a user's personal preferences.  Use of these
      control functions by normal applications would diminish their
      usefulness.  The standard Minix 1.5.10 console driver is able to provide
      much of the functionality of these control functions by not resetting
      the screen colors in response to a set graphics rendition default
      command.  This however is not permitted by the relevant standard.  The
      virtual console driver adheres to the requirements of the standard.

    - The device with minor number 0 is a special device that always refers to
      the current foreground console.  This is often a useful place to send
      error messages.  The file system and memory tasks both do this.  Output
      from the kernel also does this bypassing the tty tasks external
      interface.  User processes can also access this device, although it is
      not normally sensible to attempt to read from it.

    - The current version of init requires a device called /dev/tty0 when it
      starts up.  This should be changed to /dev/console which should replace
      /dev/tty0.

    - A few programs refer to /dev/tty0, or expect tty minor numbers to be
      single digit values, and hence do not work properly with the patched
      kernel.  These programs are few, and the problems are minor.

    - The toggle scroll mode key (F6) still works, but no longer alters the
      contents of the screen.

    - It should be possible to only enable logins on a single virtual console,
      and have your .profile start up shells on the other virtual terminals.
      I have never tried this, but depending on what you are doing this may be
      a better alternative than having to login multiple times.

6) Updates.
   --------

I will endeavor to keep these patches up to date with the latest version of
Minix and fix any bugs that may be found in them.  They will be available for
anonymous ftp from the site ftp.adelaide.edu.au (129.127.40.3) in the
directory pub/minix/local.

7) Restrictions.
   -------------

These patches are copyrighted.  Details of this and conditions for the use,
modification, and redistribution of these patches are contained in the file
COPYRIGHT that is part of this distribution.

8) Acknowledgments.
   ----------------

Many thanks to Bruce Evans for testing the virtual console patches, providing
useful suggestions, and helping me integrate the virtual console patches with
the rest of the kernel.  Thanks in advance to Andrew Cagney for arranging to
have these patches made available for anonymous ftp.



                                    - Share and Prosper,

                                            Gordon Irlam,
                                            Adelaide, Australia.

                                            (gordoni@cs.ua.oz.au)
