2                                   HVCS
   3        IBM "Hypervisor Virtual Console Server" Installation Guide
   4                          for Linux Kernel 2.6.4+
   5                    Copyright (C) 2004 IBM Corporation
   8NOTE:Eight space tabs are the optimum editor setting for reading this file.
  11               Author(s) :  Ryan S. Arnold <>
  12                       Date Created: March, 02, 2004
  13                       Last Changed: August, 24, 2004
  16Table of contents:
  18        1.  Driver Introduction:
  19        2.  System Requirements
  20        3.  Build Options:
  21                3.1  Built-in:
  22                3.2  Module:
  23        4.  Installation:
  24        5.  Connection:
  25        6.  Disconnection:
  26        7.  Configuration:
  27        8.  Questions & Answers:
  28        9.  Reporting Bugs:
  311. Driver Introduction:
  33This is the device driver for the IBM Hypervisor Virtual Console Server,
  34"hvcs".  The IBM hvcs provides a tty driver interface to allow Linux user
  35space applications access to the system consoles of logically partitioned
  36operating systems (Linux and AIX) running on the same partitioned Power5
  37ppc64 system.  Physical hardware consoles per partition are not practical
  38on this hardware so system consoles are accessed by this driver using
  39firmware interfaces to virtual terminal devices.
  422. System Requirements:
  44This device driver was written using 2.6.4 Linux kernel APIs and will only
  45build and run on kernels of this version or later.
  47This driver was written to operate solely on IBM Power5 ppc64 hardware
  48though some care was taken to abstract the architecture dependent firmware
  49calls from the driver code.
  51Sysfs must be mounted on the system so that the user can determine which
  52major and minor numbers are associated with each vty-server.  Directions
  53for sysfs mounting are outside the scope of this document.
  563. Build Options:
  58The hvcs driver registers itself as a tty driver.  The tty layer
  59dynamically allocates a block of major and minor numbers in a quantity
  60requested by the registering driver.  The hvcs driver asks the tty layer
  61for 64 of these major/minor numbers by default to use for hvcs device node
  64If the default number of device entries is adequate then this driver can be
  65built into the kernel.  If not, the default can be over-ridden by inserting
  66the driver as a module with insmod parameters.
  693.1 Built-in:
  71The following menuconfig example demonstrates selecting to build this
  72driver into the kernel.
  74        Device Drivers  --->
  75                Character devices  --->
  76                        <*> IBM Hypervisor Virtual Console Server Support
  78Begin the kernel make process.
  813.2 Module:
  83The following menuconfig example demonstrates selecting to build this
  84driver as a kernel module.
  86        Device Drivers  --->
  87                Character devices  --->
  88                        <M> IBM Hypervisor Virtual Console Server Support
  90The make process will build the following kernel modules:
  92        hvcs.ko
  93        hvcserver.ko
  95To insert the module with the default allocation execute the following
  96commands in the order they appear:
  98        insmod hvcserver.ko
  99        insmod hvcs.ko
 101The hvcserver module contains architecture specific firmware calls and must
 102be inserted first, otherwise the hvcs module will not find some of the
 103symbols it expects.
 105To override the default use an insmod parameter as follows (requesting 4
 106tty devices as an example):
 108        insmod hvcs.ko hvcs_parm_num_devs=4
 110There is a maximum number of dev entries that can be specified on insmod.
 111We think that 1024 is currently a decent maximum number of server adapters
 112to allow.  This can always be changed by modifying the constant in the
 113source file before building.
 115NOTE: The length of time it takes to insmod the driver seems to be related
 116to the number of tty interfaces the registering driver requests.
 118In order to remove the driver module execute the following command:
 120        rmmod hvcs.ko
 122The recommended method for installing hvcs as a module is to use depmod to
 123build a current modules.dep file in /lib/modules/`uname -r` and then
 126modprobe hvcs hvcs_parm_num_devs=4
 128The modules.dep file indicates that hvcserver.ko needs to be inserted
 129before hvcs.ko and modprobe uses this file to smartly insert the modules in
 130the proper order.
 132The following modprobe command is used to remove hvcs and hvcserver in the
 133proper order:
 135modprobe -r hvcs
 1384. Installation:
 140The tty layer creates sysfs entries which contain the major and minor
 141numbers allocated for the hvcs driver.  The following snippet of "tree"
 142output of the sysfs directory shows where these numbers are presented:
 144        sys/
 145        |-- *other sysfs base dirs*
 146        |
 147        |-- class
 148        |   |-- *other classes of devices*
 149        |   |
 150        |   `-- tty
 151        |       |-- *other tty devices*
 152        |       |
 153        |       |-- hvcs0
 154        |       |   `-- dev
 155        |       |-- hvcs1
 156        |       |   `-- dev
 157        |       |-- hvcs2
 158        |       |   `-- dev
 159        |       |-- hvcs3
 160        |       |   `-- dev
 161        |       |
 162        |       |-- *other tty devices*
 163        |
 164        |-- *other sysfs base dirs*
 166For the above examples the following output is a result of cat'ing the
 167"dev" entry in the hvcs directory:
 169        Pow5:/sys/class/tty/hvcs0/ # cat dev
 170        254:0
 172        Pow5:/sys/class/tty/hvcs1/ # cat dev
 173        254:1
 175        Pow5:/sys/class/tty/hvcs2/ # cat dev
 176        254:2
 178        Pow5:/sys/class/tty/hvcs3/ # cat dev
 179        254:3
 181The output from reading the "dev" attribute is the char device major and
 182minor numbers that the tty layer has allocated for this driver's use.  Most
 183systems running hvcs will already have the device entries created or udev
 184will do it automatically.
 186Given the example output above, to manually create a /dev/hvcs* node entry
 187mknod can be used as follows:
 189        mknod /dev/hvcs0 c 254 0
 190        mknod /dev/hvcs1 c 254 1
 191        mknod /dev/hvcs2 c 254 2
 192        mknod /dev/hvcs3 c 254 3
 194Using mknod to manually create the device entries makes these device nodes
 195persistent.  Once created they will exist prior to the driver insmod.
 197Attempting to connect an application to /dev/hvcs* prior to insertion of
 198the hvcs module will result in an error message similar to the following:
 200        "/dev/hvcs*: No such device".
 202NOTE: Just because there is a device node present doesn't mean that there
 203is a vty-server device configured for that node.
 2065. Connection
 208Since this driver controls devices that provide a tty interface a user can
 209interact with the device node entries using any standard tty-interactive
 210method (e.g. "cat", "dd", "echo").  The intent of this driver however, is
 211to provide real time console interaction with a Linux partition's console,
 212which requires the use of applications that provide bi-directional,
 213interactive I/O with a tty device.
 215Applications (e.g. "minicom" and "screen") that act as terminal emulators
 216or perform terminal type control sequence conversion on the data being
 217passed through them are NOT acceptable for providing interactive console
 218I/O.  These programs often emulate antiquated terminal types (vt100 and
 219ANSI) and expect inbound data to take the form of one of these supported
 220terminal types but they either do not convert, or do not _adequately_
 221convert, outbound data into the terminal type of the terminal which invoked
 222them (though screen makes an attempt and can apparently be configured with
 223much termcap wrestling.)
 225For this reason kermit and cu are two of the recommended applications for
 226interacting with a Linux console via an hvcs device.  These programs simply
 227act as a conduit for data transfer to and from the tty device.  They do not
 228require inbound data to take the form of a particular terminal type, nor do
 229they cook outbound data to a particular terminal type.
 231In order to ensure proper functioning of console applications one must make
 232sure that once connected to a /dev/hvcs console that the console's $TERM
 233env variable is set to the exact terminal type of the terminal emulator
 234used to launch the interactive I/O application.  If one is using xterm and
 235kermit to connect to /dev/hvcs0 when the console prompt becomes available
 236one should "export TERM=xterm" on the console.  This tells ncurses
 237applications that are invoked from the console that they should output
 238control sequences that xterm can understand.
 240As a precautionary measure an hvcs user should always "exit" from their
 241session before disconnecting an application such as kermit from the device
 242node.  If this is not done, the next user to connect to the console will
 243continue using the previous user's logged in session which includes
 244using the $TERM variable that the previous user supplied.
 246Hotplug add and remove of vty-server adapters affects which /dev/hvcs* node
 247is used to connect to each vty-server adapter.  In order to determine which
 248vty-server adapter is associated with which /dev/hvcs* node a special sysfs
 249attribute has been added to each vty-server sysfs entry.  This entry is
 250called "index" and showing it reveals an integer that refers to the
 251/dev/hvcs* entry to use to connect to that device.  For instance cating the
 252index attribute of vty-server adapter 30000004 shows the following.
 254        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
 255        2
 257This index of '2' means that in order to connect to vty-server adapter
 25830000004 the user should interact with /dev/hvcs2.
 260It should be noted that due to the system hotplug I/O capabilities of a
 261system the /dev/hvcs* entry that interacts with a particular vty-server
 262adapter is not guaranteed to remain the same across system reboots.  Look
 263in the Q & A section for more on this issue.
 2666. Disconnection
 268As a security feature to prevent the delivery of stale data to an
 269unintended target the Power5 system firmware disables the fetching of data
 270and discards that data when a connection between a vty-server and a vty has
 271been severed.  As an example, when a vty-server is immediately disconnected
 272from a vty following output of data to the vty the vty adapter may not have
 273enough time between when it received the data interrupt and when the
 274connection was severed to fetch the data from firmware before the fetch is
 275disabled by firmware.
 277When hvcs is being used to serve consoles this behavior is not a huge issue
 278because the adapter stays connected for large amounts of time following
 279almost all data writes.  When hvcs is being used as a tty conduit to tunnel
 280data between two partitions [see Q & A below] this is a huge problem
 281because the standard Linux behavior when cat'ing or dd'ing data to a device
 282is to open the tty, send the data, and then close the tty.  If this driver
 283manually terminated vty-server connections on tty close this would close
 284the vty-server and vty connection before the target vty has had a chance to
 285fetch the data.
 287Additionally, disconnecting a vty-server and vty only on module removal or
 288adapter removal is impractical because other vty-servers in other
 289partitions may require the usage of the target vty at any time.
 291Due to this behavioral restriction disconnection of vty-servers from the
 292connected vty is a manual procedure using a write to a sysfs attribute
 293outlined below, on the other hand the initial vty-server connection to a
 294vty is established automatically by this driver.  Manual vty-server
 295connection is never required.
 297In order to terminate the connection between a vty-server and vty the
 298"vterm_state" sysfs attribute within each vty-server's sysfs entry is used.
 299Reading this attribute reveals the current connection state of the
 300vty-server adapter.  A zero means that the vty-server is not connected to a
 301vty.  A one indicates that a connection is active.
 303Writing a '0' (zero) to the vterm_state attribute will disconnect the VTERM
 304connection between the vty-server and target vty ONLY if the vterm_state
 305previously read '1'.  The write directive is ignored if the vterm_state
 306read '0' or if any value other than '0' was written to the vterm_state
 307attribute.  The following example will show the method used for verifying
 308the vty-server connection status and disconnecting a vty-server connection.
 310        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
 311        1
 313        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_state
 315        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
 316        0
 318All vty-server connections are automatically terminated when the device is
 319hotplug removed and when the module is removed.
 3227. Configuration
 324Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
 325is symlinked in several other sysfs tree directories, notably under the
 326hvcs driver entry, which looks like the following example:
 328        Pow5:/sys/bus/vio/drivers/hvcs # ls
 329        .  ..  30000003  30000004  rescan
 331By design, firmware notifies the hvcs driver of vty-server lifetimes and
 332partner vty removals but not the addition of partner vtys.  Since an HMC
 333Super Admin can add partner info dynamically we have provided the hvcs
 334driver sysfs directory with the "rescan" update attribute which will query
 335firmware and update the partner info for all the vty-servers that this
 336driver manages.  Writing a '1' to the attribute triggers the update.  An
 337explicit example follows:
 339        Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan
 341Reading the attribute will indicate a state of '1' or '0'.  A one indicates
 342that an update is in process.  A zero indicates that an update has
 343completed or was never executed.
 345Vty-server entries in this directory are a 32 bit partition unique unit
 346address that is created by firmware.  An example vty-server sysfs entry
 347looks like the following:
 349        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
 350        .   current_vty   devspec       name          partner_vtys
 351        ..  index         partner_clcs  vterm_state
 353Each entry is provided, by default with a "name" attribute.  Reading the
 354"name" attribute will reveal the device type as shown in the following
 357        Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
 358        vty-server
 360Each entry is also provided, by default, with a "devspec" attribute which
 361reveals the full device specification when read, as shown in the following
 364        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
 365        /vdevice/vty-server@30000004
 367Each vty-server sysfs dir is provided with two read-only attributes that
 368provide lists of easily parsed partner vty data: "partner_vtys" and
 371        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
 372        30000000
 373        30000001
 374        30000002
 375        30000000
 376        30000000
 378        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_clcs
 379        U5112.428.103048A-V3-C0
 380        U5112.428.103048A-V3-C2
 381        U5112.428.103048A-V3-C3
 382        U5112.428.103048A-V4-C0
 383        U5112.428.103048A-V5-C0
 385Reading partner_vtys returns a list of partner vtys.  Vty unit address
 386numbering is only per-partition-unique so entries will frequently repeat.
 388Reading partner_clcs returns a list of "converged location codes" which are
 389composed of a system serial number followed by "-V*", where the '*' is the
 390target partition number, and "-C*", where the '*' is the slot of the
 391adapter.  The first vty partner corresponds to the first clc item, the
 392second vty partner to the second clc item, etc.
 394A vty-server can only be connected to a single vty at a time.  The entry,
 395"current_vty" prints the clc of the currently selected partner vty when
 398The current_vty can be changed by writing a valid partner clc to the entry
 399as in the following example:
 401        Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
 402        8A-V4-C0 > current_vty
 404Changing the current_vty when a vty-server is already connected to a vty
 405does not affect the current connection.  The change takes effect when the
 406currently open connection is freed.
 408Information on the "vterm_state" attribute was covered earlier on the
 409chapter entitled "disconnection".
 4128. Questions & Answers:
 414Q: What are the security concerns involving hvcs?
 416A: There are three main security concerns:
 418        1. The creator of the /dev/hvcs* nodes has the ability to restrict
 419        the access of the device entries to certain users or groups.  It
 420        may be best to create a special hvcs group privilege for providing
 421        access to system consoles.
 423        2. To provide network security when grabbing the console it is
 424        suggested that the user connect to the console hosting partition
 425        using a secure method, such as SSH or sit at a hardware console.
 427        3. Make sure to exit the user session when done with a console or
 428        the next vty-server connection (which may be from another
 429        partition) will experience the previously logged in session.
 432Q: How do I multiplex a console that I grab through hvcs so that other
 433people can see it:
 435A: You can use "screen" to directly connect to the /dev/hvcs* device and
 436setup a session on your machine with the console group privileges.  As
 437pointed out earlier by default screen doesn't provide the termcap settings
 438for most terminal emulators to provide adequate character conversion from
 439term type "screen" to others.  This means that curses based programs may
 440not display properly in screen sessions.
 443Q: Why are the colors all messed up?
 444Q: Why are the control characters acting strange or not working?
 445Q: Why is the console output all strange and unintelligible?
 447A: Please see the preceding section on "Connection" for a discussion of how
 448applications can affect the display of character control sequences.
 449Additionally, just because you logged into the console using and xterm
 450doesn't mean someone else didn't log into the console with the HMC console
 451(vt320) before you and leave the session logged in.  The best thing to do
 452is to export TERM to the terminal type of your terminal emulator when you
 453get the console.  Additionally make sure to "exit" the console before you
 454disconnect from the console.  This will ensure that the next user gets
 455their own TERM type set when they login.
 458Q: When I try to CONNECT kermit to an hvcs device I get:
 459"Sorry, can't open connection: /dev/hvcs*"What is happening?
 461A: Some other Power5 console mechanism has a connection to the vty and
 462isn't giving it up.  You can try to force disconnect the consoles from the
 463HMC by right clicking on the partition and then selecting "close terminal".
 464Otherwise you have to hunt down the people who have console authority.  It
 465is possible that you already have the console open using another kermit
 466session and just forgot about it.  Please review the console options for
 467Power5 systems to determine the many ways a system console can be held.
 471A: Another user may not have a connectivity method currently attached to a
 472/dev/hvcs device but the vterm_state may reveal that they still have the
 473vty-server connection established.  They need to free this using the method
 474outlined in the section on "Disconnection" in order for others to connect
 475to the target vty.
 479A: The user profile you are using to execute kermit probably doesn't have
 480permissions to use the /dev/hvcs* device.
 484A: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs*
 485entry still exists (on systems without udev).
 489A: There is not a corresponding vty-server device that maps to an existing
 490/dev/hvcs* entry.
 493Q: When I try to CONNECT kermit to an hvcs device I get:
 494"Sorry, write access to UUCP lockfile directory denied."
 496A: The /dev/hvcs* entry you have specified doesn't exist where you said it
 497does?  Maybe you haven't inserted the module (on systems with udev).
 500Q: If I already have one Linux partition installed can I use hvcs on said
 501partition to provide the console for the install of a second Linux
 504A: Yes granted that your are connected to the /dev/hvcs* device using
 505kermit or cu or some other program that doesn't provide terminal emulation.
 508Q: Can I connect to more than one partition's console at a time using this
 511A: Yes.  Of course this means that there must be more than one vty-server
 512configured for this partition and each must point to a disconnected vty.
 515Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
 517A: Yes, if you have dlpar and hotplug enabled for your system and it has
 518been built into the kernel the hvcs drivers is configured to dynamically
 519handle additions of new devices and removals of unused devices.
 522Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
 523after a reboot.  What happened?
 525A: Assignment of vty-server adapters to /dev/hvcs* entries is always done
 526in the order that the adapters are exposed.  Due to hotplug capabilities of
 527this driver assignment of hotplug added vty-servers may be in a different
 528order than how they would be exposed on module load.  Rebooting or
 529reloading the module after dynamic addition may result in the /dev/hvcs*
 530and vty-server coupling changing if a vty-server adapter was added in a
 531slot between two other vty-server adapters.  Refer to the section above
 532on how to determine which vty-server goes with which /dev/hvcs* node.
 533Hint; look at the sysfs "index" attribute for the vty-server.
 536Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
 537device on that partition as the other end of the pipe?
 539A: Yes, on Power5 platforms the hvc_console driver provides a tty interface
 540for extra /dev/hvc* devices (where /dev/hvc0 is most likely the console).
 541In order to get a tty conduit working between the two partitions the HMC
 542Super Admin must create an additional "serial server" for the target
 543partition with the HMC gui which will show up as /dev/hvc* when the target
 544partition is rebooted.
 546The HMC Super Admin then creates an additional "serial client" for the
 547current partition and points this at the target partition's newly created
 548"serial server" adapter (remember the slot).  This shows up as an
 549additional /dev/hvcs* device.
 551Now a program on the target system can be configured to read or write to
 552/dev/hvc* and another program on the current partition can be configured to
 553read or write to /dev/hvcs*.  Now you have a tty conduit between two
 5579. Reporting Bugs:
 559The proper channel for reporting bugs is either through the Linux OS
 560distribution company that provided your OS or by posting issues to the
 561PowerPC development mailing list at:
 565This request is to provide a documented and searchable public exchange
 566of the problems and solutions surrounding this driver for the benefit of
 567all users.
 568 kindly hosted by Redpill Linpro AS, provider of Linux consulting and operations services since 1995.