hvcs.txt

linux 内核源代码

===========================================================================
				   HVCS
	IBM "Hypervisor Virtual Console Server" Installation Guide
			  for Linux Kernel 2.6.4+
		    Copyright (C) 2004 IBM Corporation

===========================================================================
NOTE:Eight space tabs are the optimum editor setting for reading this file.
===========================================================================

	       Author(s) :  Ryan S. Arnold <[e-mail]>
		       Date Created: March, 02, 2004
		       Last Changed: August, 24, 2004

---------------------------------------------------------------------------
Table of contents:

	1.  Driver Introduction:
	2.  System Requirements
	3.  Build Options:
		3.1  Built-in:
		3.2  Module:
	4.  Installation:
	5.  Connection:
	6.  Disconnection:
	7.  Configuration:
	8.  Questions & Answers:
	9.  Reporting Bugs:

---------------------------------------------------------------------------
1. Driver Introduction:

This is the device driver for the IBM Hypervisor Virtual Console Server,
"hvcs".  The IBM hvcs provides a tty driver interface to allow Linux user
space applications access to the system consoles of logically partitioned
operating systems (Linux and AIX) running on the same partitioned Power5
ppc64 system.  Physical hardware consoles per partition are not practical
on this hardware so system consoles are accessed by this driver using
firmware interfaces to virtual terminal devices.

---------------------------------------------------------------------------
2. System Requirements:

This device driver was written using 2.6.4 Linux kernel APIs and will only
build and run on kernels of this version or later.

This driver was written to operate solely on IBM Power5 ppc64 hardware
though some care was taken to abstract the architecture dependent firmware
calls from the driver code.

Sysfs must be mounted on the system so that the user can determine which
major and minor numbers are associated with each vty-server.  Directions
for sysfs mounting are outside the scope of this document.

---------------------------------------------------------------------------
3. Build Options:

The hvcs driver registers itself as a tty driver.  The tty layer
dynamically allocates a block of major and minor numbers in a quantity
requested by the registering driver.  The hvcs driver asks the tty layer
for 64 of these major/minor numbers by default to use for hvcs device node
entries.

If the default number of device entries is adequate then this driver can be
built into the kernel.  If not, the default can be over-ridden by inserting
the driver as a module with insmod parameters.

---------------------------------------------------------------------------
3.1 Built-in:

The following menuconfig example demonstrates selecting to build this
driver into the kernel.

	Device Drivers  --->
		Character devices  --->
			<*> IBM Hypervisor Virtual Console Server Support

Begin the kernel make process.

---------------------------------------------------------------------------
3.2 Module:

The following menuconfig example demonstrates selecting to build this
driver as a kernel module.

	Device Drivers  --->
		Character devices  --->
			<M> IBM Hypervisor Virtual Console Server Support

The make process will build the following kernel modules:

	hvcs.ko
	hvcserver.ko

To insert the module with the default allocation execute the following
commands in the order they appear:

	insmod hvcserver.ko
	insmod hvcs.ko

The hvcserver module contains architecture specific firmware calls and must
be inserted first, otherwise the hvcs module will not find some of the
symbols it expects.

To override the default use an insmod parameter as follows (requesting 4
tty devices as an example):

	insmod hvcs.ko hvcs_parm_num_devs=4

There is a maximum number of dev entries that can be specified on insmod.
We think that 1024 is currently a decent maximum number of server adapters
to allow.  This can always be changed by modifying the constant in the
source file before building.

NOTE: The length of time it takes to insmod the driver seems to be related
to the number of tty interfaces the registering driver requests.

In order to remove the driver module execute the following command:

	rmmod hvcs.ko

The recommended method for installing hvcs as a module is to use depmod to
build a current modules.dep file in /lib/modules/`uname -r` and then
execute:

modprobe hvcs hvcs_parm_num_devs=4

The modules.dep file indicates that hvcserver.ko needs to be inserted
before hvcs.ko and modprobe uses this file to smartly insert the modules in
the proper order.

The following modprobe command is used to remove hvcs and hvcserver in the
proper order:

modprobe -r hvcs

---------------------------------------------------------------------------
4. Installation:

The tty layer creates sysfs entries which contain the major and minor
numbers allocated for the hvcs driver.  The following snippet of "tree"
output of the sysfs directory shows where these numbers are presented:

	sys/
	|-- *other sysfs base dirs*
	|
	|-- class
	|   |-- *other classes of devices*
	|   |
	|   `-- tty
	|       |-- *other tty devices*
	|       |
	|       |-- hvcs0
	|       |   `-- dev
	|       |-- hvcs1
	|       |   `-- dev
	|       |-- hvcs2
	|       |   `-- dev
	|       |-- hvcs3
	|       |   `-- dev
	|       |
	|       |-- *other tty devices*
	|
	|-- *other sysfs base dirs*

For the above examples the following output is a result of cat'ing the
"dev" entry in the hvcs directory:

	Pow5:/sys/class/tty/hvcs0/ # cat dev
	254:0

	Pow5:/sys/class/tty/hvcs1/ # cat dev
	254:1

	Pow5:/sys/class/tty/hvcs2/ # cat dev
	254:2

	Pow5:/sys/class/tty/hvcs3/ # cat dev
	254:3

The output from reading the "dev" attribute is the char device major and
minor numbers that the tty layer has allocated for this driver's use.  Most
systems running hvcs will already have the device entries created or udev
will do it automatically.

Given the example output above, to manually create a /dev/hvcs* node entry
mknod can be used as follows:

	mknod /dev/hvcs0 c 254 0
	mknod /dev/hvcs1 c 254 1
	mknod /dev/hvcs2 c 254 2
	mknod /dev/hvcs3 c 254 3

Using mknod to manually create the device entries makes these device nodes
persistent.  Once created they will exist prior to the driver insmod.

Attempting to connect an application to /dev/hvcs* prior to insertion of
the hvcs module will result in an error message similar to the following:

	"/dev/hvcs*: No such device".

NOTE: Just because there is a device node present doesn't mean that there
is a vty-server device configured for that node.

---------------------------------------------------------------------------
5. Connection

Since this driver controls devices that provide a tty interface a user can
interact with the device node entries using any standard tty-interactive
method (e.g. "cat", "dd", "echo").  The intent of this driver however, is
to provide real time console interaction with a Linux partition's console,
which requires the use of applications that provide bi-directional,
interactive I/O with a tty device.

Applications (e.g. "minicom" and "screen") that act as terminal emulators
or perform terminal type control sequence conversion on the data being
passed through them are NOT acceptable for providing interactive console
I/O.  These programs often emulate antiquated terminal types (vt100 and
ANSI) and expect inbound data to take the form of one of these supported
terminal types but they either do not convert, or do not _adequately_
convert, outbound data into the terminal type of the terminal which invoked
them (though screen makes an attempt and can apparently be configured with
much termcap wrestling.)

For this reason kermit and cu are two of the recommended applications for
interacting with a Linux console via an hvcs device.  These programs simply
act as a conduit for data transfer to and from the tty device.  They do not
require inbound data to take the form of a particular terminal type, nor do
they cook outbound data to a particular terminal type.

In order to ensure proper functioning of console applications one must make
sure that once connected to a /dev/hvcs console that the console's $TERM
env variable is set to the exact terminal type of the terminal emulator
used to launch the interactive I/O application.  If one is using xterm and
kermit to connect to /dev/hvcs0 when the console prompt becomes available
one should "export TERM=xterm" on the console.  This tells ncurses
applications that are invoked from the console that they should output
control sequences that xterm can understand.

As a precautionary measure an hvcs user should always "exit" from their
session before disconnecting an application such as kermit from the device
node.  If this is not done, the next user to connect to the console will
continue using the previous user's logged in session which includes
using the $TERM variable that the previous user supplied.

Hotplug add and remove of vty-server adapters affects which /dev/hvcs* node
is used to connect to each vty-server adapter.  In order to determine which
vty-server adapter is associated with which /dev/hvcs* node a special sysfs
attribute has been added to each vty-server sysfs entry.  This entry is
called "index" and showing it reveals an integer that refers to the
/dev/hvcs* entry to use to connect to that device.  For instance cating the
index attribute of vty-server adapter 30000004 shows the following.

	Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
	2

This index of '2' means that in order to connect to vty-server adapter
30000004 the user should interact with /dev/hvcs2.

It should be noted that due to the system hotplug I/O capabilities of a
system the /dev/hvcs* entry that interacts with a particular vty-server
adapter is not guaranteed to remain the same across system reboots.  Look
in the Q & A section for more on this issue.

---------------------------------------------------------------------------
6. Disconnection

As a security feature to prevent the delivery of stale data to an
unintended target the Power5 system firmware disables the fetching of data
and discards that data when a connection between a vty-server and a vty has
been severed.  As an example, when a vty-server is immediately disconnected
from a vty following output of data to the vty the vty adapter may not have
enough time between when it received the data interrupt and when the
connection was severed to fetch the data from firmware before the fetch is
disabled by firmware.

When hvcs is being used to serve consoles this behavior is not a huge issue
because the adapter stays connected for large amounts of time following
almost all data writes.  When hvcs is being used as a tty conduit to tunnel
data between two partitions [see Q & A below] this is a huge problem
because the standard Linux behavior when cat'ing or dd'ing data to a device
is to open the tty, send the data, and then close the tty.  If this driver
manually terminated vty-server connections on tty close this would close
the vty-server and vty connection before the target vty has had a chance to