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 userspace applications access to the system consoles of logically partitionedoperating systems (Linux and AIX) running on the same partitioned Power5ppc64 system. Physical hardware consoles per partition are not practicalon this hardware so system consoles are accessed by this driver usingfirmware interfaces to virtual terminal devices.

2. System Requirements:¶

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

This driver was written to operate solely on IBM Power5 ppc64 hardwarethough some care was taken to abstract the architecture dependent firmwarecalls from the driver code.

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

3. Build Options:¶

The hvcs driver registers itself as a tty driver. The tty layerdynamically allocates a block of major and minor numbers in a quantityrequested by the registering driver. The hvcs driver asks the tty layerfor 64 of these major/minor numbers by default to use for hvcs device nodeentries.

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

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

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

insmod hvcserver.koinsmod hvcs.ko

insmod hvcs.ko hvcs_parm_num_devs=4

rmmod hvcs.ko

modprobe hvcs hvcs_parm_num_devs=4

modprobe -r hvcs

4. Installation:¶

The tty layer creates sysfs entries which contain the major and minornumbers 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 dev254:0Pow5:/sys/class/tty/hvcs1/ # cat dev254:1Pow5:/sys/class/tty/hvcs2/ # cat dev254:2Pow5:/sys/class/tty/hvcs3/ # cat dev254:3

The output from reading the “dev” attribute is the char device major andminor numbers that the tty layer has allocated for this driver’s use. Mostsystems running hvcs will already have the device entries created or udevwill do it automatically.

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

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

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

Attempting to connect an application to /dev/hvcs* prior to insertion ofthe 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 thereis a vty-server device configured for that node.

5. Connection¶

Since this driver controls devices that provide a tty interface a user caninteract with the device node entries using any standard tty-interactivemethod (e.g. “cat”, “dd”, “echo”). The intent of this driver however, isto 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 emulatorsor perform terminal type control sequence conversion on the data beingpassed through them are NOT acceptable for providing interactive consoleI/O. These programs often emulate antiquated terminal types (vt100 andANSI) and expect inbound data to take the form of one of these supportedterminal types but they either do not convert, or do not _adequately_convert, outbound data into the terminal type of the terminal which invokedthem (though screen makes an attempt and can apparently be configured withmuch termcap wrestling.)

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

In order to ensure proper functioning of console applications one must makesure that once connected to a /dev/hvcs console that the console’s $TERMenv variable is set to the exact terminal type of the terminal emulatorused to launch the interactive I/O application. If one is using xterm andkermit to connect to /dev/hvcs0 when the console prompt becomes availableone should “export TERM=xterm” on the console. This tells ncursesapplications that are invoked from the console that they should outputcontrol sequences that xterm can understand.

As a precautionary measure an hvcs user should always “exit” from theirsession before disconnecting an application such as kermit from the devicenode. If this is not done, the next user to connect to the console willcontinue using the previous user’s logged in session which includesusing the $TERM variable that the previous user supplied.

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

Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index2

This index of ‘2’ means that in order to connect to vty-server adapter30000004 the user should interact with /dev/hvcs2.

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

6. Disconnection¶

As a security feature to prevent the delivery of stale data to anunintended target the Power5 system firmware disables the fetching of dataand discards that data when a connection between a vty-server and a vty hasbeen severed. As an example, when a vty-server is immediately disconnectedfrom a vty following output of data to the vty the vty adapter may not haveenough time between when it received the data interrupt and when theconnection was severed to fetch the data from firmware before the fetch isdisabled by firmware.

When hvcs is being used to serve consoles this behavior is not a huge issuebecause the adapter stays connected for large amounts of time followingalmost all data writes. When hvcs is being used as a tty conduit to tunneldata between two partitions [see Q & A below] this is a huge problembecause the standard Linux behavior when cat’ing or dd’ing data to a deviceis to open the tty, send the data, and then close the tty. If this drivermanually terminated vty-server connections on tty close this would closethe vty-server and vty connection before the target vty has had a chance tofetch the data.

Additionally, disconnecting a vty-server and vty only on module removal oradapter removal is impractical because other vty-servers in otherpartitions may require the usage of the target vty at any time.

Due to this behavioral restriction disconnection of vty-servers from theconnected vty is a manual procedure using a write to a sysfs attributeoutlined below, on the other hand the initial vty-server connection to avty is established automatically by this driver. Manual vty-serverconnection is never required.

In order to terminate the connection between a vty-server and vty the“vterm_state” sysfs attribute within each vty-server’s sysfs entry is used.Reading this attribute reveals the current connection state of thevty-server adapter. A zero means that the vty-server is not connected to avty. A one indicates that a connection is active.

Writing a ‘0’ (zero) to the vterm_state attribute will disconnect the VTERMconnection between the vty-server and target vty ONLY if the vterm_statepreviously read ‘1’. The write directive is ignored if the vterm_stateread ‘0’ or if any value other than ‘0’ was written to the vterm_stateattribute. The following example will show the method used for verifyingthe vty-server connection status and disconnecting a vty-server connection:

Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state1Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_statePow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state0

All vty-server connections are automatically terminated when the device ishotplug removed and when the module is removed.

7. Configuration¶

Each vty-server has a sysfs entry in the /sys/devices/vio directory, whichis symlinked in several other sysfs tree directories, notably under thehvcs driver entry, which looks like the following example:

Pow5:/sys/bus/vio/drivers/hvcs # ls.  ..  30000003  30000004  rescan

By design, firmware notifies the hvcs driver of vty-server lifetimes andpartner vty removals but not the addition of partner vtys. Since an HMCSuper Admin can add partner info dynamically we have provided the hvcsdriver sysfs directory with the “rescan” update attribute which will queryfirmware and update the partner info for all the vty-servers that thisdriver manages. Writing a ‘1’ to the attribute triggers the update. Anexplicit example follows:

Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan

Reading the attribute will indicate a state of ‘1’ or ‘0’. A one indicatesthat an update is in process. A zero indicates that an update hascompleted or was never executed.

Vty-server entries in this directory are a 32 bit partition unique unitaddress that is created by firmware. An example vty-server sysfs entrylooks like the following:

Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls.   current_vty   devspec       name          partner_vtys..  index         partner_clcs  vterm_state

Each entry is provided, by default with a “name” attribute. Reading the“name” attribute will reveal the device type as shown in the followingexample:

Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat namevty-server

Each entry is also provided, by default, with a “devspec” attribute whichreveals the full device specification when read, as shown in the followingexample:

Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec/vdevice/vty-server@30000004

Each vty-server sysfs dir is provided with two read-only attributes thatprovide lists of easily parsed partner vty data: “partner_vtys” and“partner_clcs”:

Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys3000000030000001300000023000000030000000Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_clcsU5112.428.103048A-V3-C0U5112.428.103048A-V3-C2U5112.428.103048A-V3-C3U5112.428.103048A-V4-C0U5112.428.103048A-V5-C0

Reading partner_vtys returns a list of partner vtys. Vty unit addressnumbering is only per-partition-unique so entries will frequently repeat.

Reading partner_clcs returns a list of “converged location codes” which arecomposed of a system serial number followed by “-V*”, where the ‘*’ is thetarget partition number, and “-C*”, where the ‘*’ is the slot of theadapter. The first vty partner corresponds to the first clc item, thesecond vty partner to the second clc item, etc.

A vty-server can only be connected to a single vty at a time. The entry,“current_vty” prints the clc of the currently selected partner vty whenread.

The current_vty can be changed by writing a valid partner clc to the entryas in the following example:

Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.103048A-V4-C0 > current_vty

Changing the current_vty when a vty-server is already connected to a vtydoes not affect the current connection. The change takes effect when thecurrently open connection is freed.

Information on the “vterm_state” attribute was covered earlier on thechapter entitled “disconnection”.

8. Questions & Answers:¶

Q: What are the security concerns involving hvcs?

A: There are three main security concerns:

1. The creator of the /dev/hvcs* nodes has the ability to restrictthe access of the device entries to certain users or groups. Itmay be best to create a special hvcs group privilege for providingaccess to system consoles.

2. To provide network security when grabbing the console it issuggested that the user connect to the console hosting partitionusing a secure method, such as SSH or sit at a hardware console.

3. Make sure to exit the user session when done with a console orthe next vty-server connection (which may be from anotherpartition) will experience the previously logged in session.

Q: How do I multiplex a console that I grab through hvcs so that otherpeople can see it:

A: You can use “screen” to directly connect to the /dev/hvcs* device andsetup a session on your machine with the console group privileges. Aspointed out earlier by default screen doesn’t provide the termcap settingsfor most terminal emulators to provide adequate character conversion fromterm type “screen” to others. This means that curses based programs maynot display properly in screen sessions.

Q: Why are the colors all messed up?Q: Why are the control characters acting strange or not working?Q: Why is the console output all strange and unintelligible?

A: Please see the preceding section on “Connection” for a discussion of howapplications can affect the display of character control sequences.Additionally, just because you logged into the console using and xtermdoesn’t mean someone else didn’t log into the console with the HMC console(vt320) before you and leave the session logged in. The best thing to dois to export TERM to the terminal type of your terminal emulator when youget the console. Additionally make sure to “exit” the console before youdisconnect from the console. This will ensure that the next user getstheir own TERM type set when they login.

Q: When I try to CONNECT kermit to an hvcs device I get:“Sorry, can’t open connection: /dev/hvcs*”What is happening?

A: Some other Power5 console mechanism has a connection to the vty andisn’t giving it up. You can try to force disconnect the consoles from theHMC by right clicking on the partition and then selecting “close terminal”.Otherwise you have to hunt down the people who have console authority. Itis possible that you already have the console open using another kermitsession and just forgot about it. Please review the console options forPower5 systems to determine the many ways a system console can be held.

OR

A: Another user may not have a connectivity method currently attached to a/dev/hvcs device but the vterm_state may reveal that they still have thevty-server connection established. They need to free this using the methodoutlined in the section on “Disconnection” in order for others to connectto the target vty.

OR

A: The user profile you are using to execute kermit probably doesn’t havepermissions to use the /dev/hvcs* device.

OR

A: You probably haven’t inserted the hvcs.ko module yet but the /dev/hvcs*entry still exists (on systems without udev).

OR

A: There is not a corresponding vty-server device that maps to an existing/dev/hvcs* entry.

Q: When I try to CONNECT kermit to an hvcs device I get:“Sorry, write access to UUCP lockfile directory denied.”

A: The /dev/hvcs* entry you have specified doesn’t exist where you said itdoes? Maybe you haven’t inserted the module (on systems with udev).

Q: If I already have one Linux partition installed can I use hvcs on saidpartition to provide the console for the install of a second Linuxpartition?

A: Yes granted that your are connected to the /dev/hvcs* device usingkermit or cu or some other program that doesn’t provide terminal emulation.

Q: Can I connect to more than one partition’s console at a time using thisdriver?

A: Yes. Of course this means that there must be more than one vty-serverconfigured for this partition and each must point to a disconnected vty.

Q: Does the hvcs driver support dynamic (hotplug) addition of devices?

A: Yes, if you have dlpar and hotplug enabled for your system and it hasbeen built into the kernel the hvcs drivers is configured to dynamicallyhandle additions of new devices and removals of unused devices.

Q: For some reason /dev/hvcs* doesn’t map to the same vty-server adapterafter a reboot. What happened?

A: Assignment of vty-server adapters to /dev/hvcs* entries is always donein the order that the adapters are exposed. Due to hotplug capabilities ofthis driver assignment of hotplug added vty-servers may be in a differentorder than how they would be exposed on module load. Rebooting orreloading the module after dynamic addition may result in the /dev/hvcs*and vty-server coupling changing if a vty-server adapter was added in aslot between two other vty-server adapters. Refer to the section aboveon how to determine which vty-server goes with which /dev/hvcs* node.Hint; look at the sysfs “index” attribute for the vty-server.

Q: Can I use /dev/hvcs* as a conduit to another partition and use a ttydevice on that partition as the other end of the pipe?

A: Yes, on Power5 platforms the hvc_console driver provides a tty interfacefor extra /dev/hvc* devices (where /dev/hvc0 is most likely the console).In order to get a tty conduit working between the two partitions the HMCSuper Admin must create an additional “serial server” for the targetpartition with the HMC gui which will show up as /dev/hvc* when the targetpartition is rebooted.

The HMC Super Admin then creates an additional “serial client” for thecurrent partition and points this at the target partition’s newly created“serial server” adapter (remember the slot). This shows up as anadditional /dev/hvcs* device.

Now a program on the target system can be configured to read or write to/dev/hvc* and another program on the current partition can be configured toread or write to /dev/hvcs*. Now you have a tty conduit between twopartitions.

9. Reporting Bugs:¶

The proper channel for reporting bugs is either through the Linux OSdistribution company that provided your OS or by posting issues to thePowerPC development mailing list at:

linuxppc-dev@lists.ozlabs.org

This request is to provide a documented and searchable public exchangeof the problems and solutions surrounding this driver for the benefit ofall users.