14d2e26a3SMauro Carvalho Chehab=============================================================== 24d2e26a3SMauro Carvalho ChehabHVCS IBM "Hypervisor Virtual Console Server" Installation Guide 34d2e26a3SMauro Carvalho Chehab=============================================================== 44d2e26a3SMauro Carvalho Chehab 54d2e26a3SMauro Carvalho Chehabfor Linux Kernel 2.6.4+ 64d2e26a3SMauro Carvalho Chehab 74d2e26a3SMauro Carvalho ChehabCopyright (C) 2004 IBM Corporation 84d2e26a3SMauro Carvalho Chehab 94d2e26a3SMauro Carvalho Chehab.. =========================================================================== 104d2e26a3SMauro Carvalho Chehab.. NOTE:Eight space tabs are the optimum editor setting for reading this file. 114d2e26a3SMauro Carvalho Chehab.. =========================================================================== 124d2e26a3SMauro Carvalho Chehab 134d2e26a3SMauro Carvalho Chehab 144d2e26a3SMauro Carvalho ChehabAuthor(s): Ryan S. Arnold <rsa@us.ibm.com> 154d2e26a3SMauro Carvalho Chehab 164d2e26a3SMauro Carvalho ChehabDate Created: March, 02, 2004 174d2e26a3SMauro Carvalho ChehabLast Changed: August, 24, 2004 184d2e26a3SMauro Carvalho Chehab 194d2e26a3SMauro Carvalho Chehab.. Table of contents: 204d2e26a3SMauro Carvalho Chehab 214d2e26a3SMauro Carvalho Chehab 1. Driver Introduction: 224d2e26a3SMauro Carvalho Chehab 2. System Requirements 234d2e26a3SMauro Carvalho Chehab 3. Build Options: 244d2e26a3SMauro Carvalho Chehab 3.1 Built-in: 254d2e26a3SMauro Carvalho Chehab 3.2 Module: 264d2e26a3SMauro Carvalho Chehab 4. Installation: 274d2e26a3SMauro Carvalho Chehab 5. Connection: 284d2e26a3SMauro Carvalho Chehab 6. Disconnection: 294d2e26a3SMauro Carvalho Chehab 7. Configuration: 304d2e26a3SMauro Carvalho Chehab 8. Questions & Answers: 314d2e26a3SMauro Carvalho Chehab 9. Reporting Bugs: 324d2e26a3SMauro Carvalho Chehab 334d2e26a3SMauro Carvalho Chehab1. Driver Introduction: 344d2e26a3SMauro Carvalho Chehab======================= 354d2e26a3SMauro Carvalho Chehab 364d2e26a3SMauro Carvalho ChehabThis is the device driver for the IBM Hypervisor Virtual Console Server, 374d2e26a3SMauro Carvalho Chehab"hvcs". The IBM hvcs provides a tty driver interface to allow Linux user 384d2e26a3SMauro Carvalho Chehabspace applications access to the system consoles of logically partitioned 394d2e26a3SMauro Carvalho Chehaboperating systems (Linux and AIX) running on the same partitioned Power5 404d2e26a3SMauro Carvalho Chehabppc64 system. Physical hardware consoles per partition are not practical 414d2e26a3SMauro Carvalho Chehabon this hardware so system consoles are accessed by this driver using 424d2e26a3SMauro Carvalho Chehabfirmware interfaces to virtual terminal devices. 434d2e26a3SMauro Carvalho Chehab 444d2e26a3SMauro Carvalho Chehab2. System Requirements: 454d2e26a3SMauro Carvalho Chehab======================= 464d2e26a3SMauro Carvalho Chehab 474d2e26a3SMauro Carvalho ChehabThis device driver was written using 2.6.4 Linux kernel APIs and will only 484d2e26a3SMauro Carvalho Chehabbuild and run on kernels of this version or later. 494d2e26a3SMauro Carvalho Chehab 504d2e26a3SMauro Carvalho ChehabThis driver was written to operate solely on IBM Power5 ppc64 hardware 514d2e26a3SMauro Carvalho Chehabthough some care was taken to abstract the architecture dependent firmware 524d2e26a3SMauro Carvalho Chehabcalls from the driver code. 534d2e26a3SMauro Carvalho Chehab 544d2e26a3SMauro Carvalho ChehabSysfs must be mounted on the system so that the user can determine which 554d2e26a3SMauro Carvalho Chehabmajor and minor numbers are associated with each vty-server. Directions 564d2e26a3SMauro Carvalho Chehabfor sysfs mounting are outside the scope of this document. 574d2e26a3SMauro Carvalho Chehab 584d2e26a3SMauro Carvalho Chehab3. Build Options: 594d2e26a3SMauro Carvalho Chehab================= 604d2e26a3SMauro Carvalho Chehab 614d2e26a3SMauro Carvalho ChehabThe hvcs driver registers itself as a tty driver. The tty layer 624d2e26a3SMauro Carvalho Chehabdynamically allocates a block of major and minor numbers in a quantity 634d2e26a3SMauro Carvalho Chehabrequested by the registering driver. The hvcs driver asks the tty layer 644d2e26a3SMauro Carvalho Chehabfor 64 of these major/minor numbers by default to use for hvcs device node 654d2e26a3SMauro Carvalho Chehabentries. 664d2e26a3SMauro Carvalho Chehab 674d2e26a3SMauro Carvalho ChehabIf the default number of device entries is adequate then this driver can be 684d2e26a3SMauro Carvalho Chehabbuilt into the kernel. If not, the default can be over-ridden by inserting 694d2e26a3SMauro Carvalho Chehabthe driver as a module with insmod parameters. 704d2e26a3SMauro Carvalho Chehab 714d2e26a3SMauro Carvalho Chehab3.1 Built-in: 724d2e26a3SMauro Carvalho Chehab------------- 734d2e26a3SMauro Carvalho Chehab 744d2e26a3SMauro Carvalho ChehabThe following menuconfig example demonstrates selecting to build this 754d2e26a3SMauro Carvalho Chehabdriver into the kernel:: 764d2e26a3SMauro Carvalho Chehab 774d2e26a3SMauro Carvalho Chehab Device Drivers ---> 784d2e26a3SMauro Carvalho Chehab Character devices ---> 794d2e26a3SMauro Carvalho Chehab <*> IBM Hypervisor Virtual Console Server Support 804d2e26a3SMauro Carvalho Chehab 814d2e26a3SMauro Carvalho ChehabBegin the kernel make process. 824d2e26a3SMauro Carvalho Chehab 834d2e26a3SMauro Carvalho Chehab3.2 Module: 844d2e26a3SMauro Carvalho Chehab----------- 854d2e26a3SMauro Carvalho Chehab 864d2e26a3SMauro Carvalho ChehabThe following menuconfig example demonstrates selecting to build this 874d2e26a3SMauro Carvalho Chehabdriver as a kernel module:: 884d2e26a3SMauro Carvalho Chehab 894d2e26a3SMauro Carvalho Chehab Device Drivers ---> 904d2e26a3SMauro Carvalho Chehab Character devices ---> 914d2e26a3SMauro Carvalho Chehab <M> IBM Hypervisor Virtual Console Server Support 924d2e26a3SMauro Carvalho Chehab 934d2e26a3SMauro Carvalho ChehabThe make process will build the following kernel modules: 944d2e26a3SMauro Carvalho Chehab 954d2e26a3SMauro Carvalho Chehab - hvcs.ko 964d2e26a3SMauro Carvalho Chehab - hvcserver.ko 974d2e26a3SMauro Carvalho Chehab 984d2e26a3SMauro Carvalho ChehabTo insert the module with the default allocation execute the following 994d2e26a3SMauro Carvalho Chehabcommands in the order they appear:: 1004d2e26a3SMauro Carvalho Chehab 1014d2e26a3SMauro Carvalho Chehab insmod hvcserver.ko 1024d2e26a3SMauro Carvalho Chehab insmod hvcs.ko 1034d2e26a3SMauro Carvalho Chehab 1044d2e26a3SMauro Carvalho ChehabThe hvcserver module contains architecture specific firmware calls and must 1054d2e26a3SMauro Carvalho Chehabbe inserted first, otherwise the hvcs module will not find some of the 1064d2e26a3SMauro Carvalho Chehabsymbols it expects. 1074d2e26a3SMauro Carvalho Chehab 1084d2e26a3SMauro Carvalho ChehabTo override the default use an insmod parameter as follows (requesting 4 1094d2e26a3SMauro Carvalho Chehabtty devices as an example):: 1104d2e26a3SMauro Carvalho Chehab 1114d2e26a3SMauro Carvalho Chehab insmod hvcs.ko hvcs_parm_num_devs=4 1124d2e26a3SMauro Carvalho Chehab 1134d2e26a3SMauro Carvalho ChehabThere is a maximum number of dev entries that can be specified on insmod. 1144d2e26a3SMauro Carvalho ChehabWe think that 1024 is currently a decent maximum number of server adapters 1154d2e26a3SMauro Carvalho Chehabto allow. This can always be changed by modifying the constant in the 1164d2e26a3SMauro Carvalho Chehabsource file before building. 1174d2e26a3SMauro Carvalho Chehab 1184d2e26a3SMauro Carvalho ChehabNOTE: The length of time it takes to insmod the driver seems to be related 1194d2e26a3SMauro Carvalho Chehabto the number of tty interfaces the registering driver requests. 1204d2e26a3SMauro Carvalho Chehab 1214d2e26a3SMauro Carvalho ChehabIn order to remove the driver module execute the following command:: 1224d2e26a3SMauro Carvalho Chehab 1234d2e26a3SMauro Carvalho Chehab rmmod hvcs.ko 1244d2e26a3SMauro Carvalho Chehab 1254d2e26a3SMauro Carvalho ChehabThe recommended method for installing hvcs as a module is to use depmod to 1264d2e26a3SMauro Carvalho Chehabbuild a current modules.dep file in /lib/modules/`uname -r` and then 1274d2e26a3SMauro Carvalho Chehabexecute:: 1284d2e26a3SMauro Carvalho Chehab 1294d2e26a3SMauro Carvalho Chehab modprobe hvcs hvcs_parm_num_devs=4 1304d2e26a3SMauro Carvalho Chehab 1314d2e26a3SMauro Carvalho ChehabThe modules.dep file indicates that hvcserver.ko needs to be inserted 1324d2e26a3SMauro Carvalho Chehabbefore hvcs.ko and modprobe uses this file to smartly insert the modules in 1334d2e26a3SMauro Carvalho Chehabthe proper order. 1344d2e26a3SMauro Carvalho Chehab 1354d2e26a3SMauro Carvalho ChehabThe following modprobe command is used to remove hvcs and hvcserver in the 1364d2e26a3SMauro Carvalho Chehabproper order:: 1374d2e26a3SMauro Carvalho Chehab 1384d2e26a3SMauro Carvalho Chehab modprobe -r hvcs 1394d2e26a3SMauro Carvalho Chehab 1404d2e26a3SMauro Carvalho Chehab4. Installation: 1414d2e26a3SMauro Carvalho Chehab================ 1424d2e26a3SMauro Carvalho Chehab 1434d2e26a3SMauro Carvalho ChehabThe tty layer creates sysfs entries which contain the major and minor 1444d2e26a3SMauro Carvalho Chehabnumbers allocated for the hvcs driver. The following snippet of "tree" 1454d2e26a3SMauro Carvalho Chehaboutput of the sysfs directory shows where these numbers are presented:: 1464d2e26a3SMauro Carvalho Chehab 1474d2e26a3SMauro Carvalho Chehab sys/ 1484d2e26a3SMauro Carvalho Chehab |-- *other sysfs base dirs* 1494d2e26a3SMauro Carvalho Chehab | 1504d2e26a3SMauro Carvalho Chehab |-- class 1514d2e26a3SMauro Carvalho Chehab | |-- *other classes of devices* 1524d2e26a3SMauro Carvalho Chehab | | 1534d2e26a3SMauro Carvalho Chehab | `-- tty 1544d2e26a3SMauro Carvalho Chehab | |-- *other tty devices* 1554d2e26a3SMauro Carvalho Chehab | | 1564d2e26a3SMauro Carvalho Chehab | |-- hvcs0 1574d2e26a3SMauro Carvalho Chehab | | `-- dev 1584d2e26a3SMauro Carvalho Chehab | |-- hvcs1 1594d2e26a3SMauro Carvalho Chehab | | `-- dev 1604d2e26a3SMauro Carvalho Chehab | |-- hvcs2 1614d2e26a3SMauro Carvalho Chehab | | `-- dev 1624d2e26a3SMauro Carvalho Chehab | |-- hvcs3 1634d2e26a3SMauro Carvalho Chehab | | `-- dev 1644d2e26a3SMauro Carvalho Chehab | | 1654d2e26a3SMauro Carvalho Chehab | |-- *other tty devices* 1664d2e26a3SMauro Carvalho Chehab | 1674d2e26a3SMauro Carvalho Chehab |-- *other sysfs base dirs* 1684d2e26a3SMauro Carvalho Chehab 1694d2e26a3SMauro Carvalho ChehabFor the above examples the following output is a result of cat'ing the 1704d2e26a3SMauro Carvalho Chehab"dev" entry in the hvcs directory:: 1714d2e26a3SMauro Carvalho Chehab 1724d2e26a3SMauro Carvalho Chehab Pow5:/sys/class/tty/hvcs0/ # cat dev 1734d2e26a3SMauro Carvalho Chehab 254:0 1744d2e26a3SMauro Carvalho Chehab 1754d2e26a3SMauro Carvalho Chehab Pow5:/sys/class/tty/hvcs1/ # cat dev 1764d2e26a3SMauro Carvalho Chehab 254:1 1774d2e26a3SMauro Carvalho Chehab 1784d2e26a3SMauro Carvalho Chehab Pow5:/sys/class/tty/hvcs2/ # cat dev 1794d2e26a3SMauro Carvalho Chehab 254:2 1804d2e26a3SMauro Carvalho Chehab 1814d2e26a3SMauro Carvalho Chehab Pow5:/sys/class/tty/hvcs3/ # cat dev 1824d2e26a3SMauro Carvalho Chehab 254:3 1834d2e26a3SMauro Carvalho Chehab 1844d2e26a3SMauro Carvalho ChehabThe output from reading the "dev" attribute is the char device major and 1854d2e26a3SMauro Carvalho Chehabminor numbers that the tty layer has allocated for this driver's use. Most 1864d2e26a3SMauro Carvalho Chehabsystems running hvcs will already have the device entries created or udev 1874d2e26a3SMauro Carvalho Chehabwill do it automatically. 1884d2e26a3SMauro Carvalho Chehab 1894d2e26a3SMauro Carvalho ChehabGiven the example output above, to manually create a /dev/hvcs* node entry 1904d2e26a3SMauro Carvalho Chehabmknod can be used as follows:: 1914d2e26a3SMauro Carvalho Chehab 1924d2e26a3SMauro Carvalho Chehab mknod /dev/hvcs0 c 254 0 1934d2e26a3SMauro Carvalho Chehab mknod /dev/hvcs1 c 254 1 1944d2e26a3SMauro Carvalho Chehab mknod /dev/hvcs2 c 254 2 1954d2e26a3SMauro Carvalho Chehab mknod /dev/hvcs3 c 254 3 1964d2e26a3SMauro Carvalho Chehab 1974d2e26a3SMauro Carvalho ChehabUsing mknod to manually create the device entries makes these device nodes 1984d2e26a3SMauro Carvalho Chehabpersistent. Once created they will exist prior to the driver insmod. 1994d2e26a3SMauro Carvalho Chehab 2004d2e26a3SMauro Carvalho ChehabAttempting to connect an application to /dev/hvcs* prior to insertion of 2014d2e26a3SMauro Carvalho Chehabthe hvcs module will result in an error message similar to the following:: 2024d2e26a3SMauro Carvalho Chehab 2034d2e26a3SMauro Carvalho Chehab "/dev/hvcs*: No such device". 2044d2e26a3SMauro Carvalho Chehab 2054d2e26a3SMauro Carvalho ChehabNOTE: Just because there is a device node present doesn't mean that there 2064d2e26a3SMauro Carvalho Chehabis a vty-server device configured for that node. 2074d2e26a3SMauro Carvalho Chehab 2084d2e26a3SMauro Carvalho Chehab5. Connection 2094d2e26a3SMauro Carvalho Chehab============= 2104d2e26a3SMauro Carvalho Chehab 2114d2e26a3SMauro Carvalho ChehabSince this driver controls devices that provide a tty interface a user can 2124d2e26a3SMauro Carvalho Chehabinteract with the device node entries using any standard tty-interactive 2134d2e26a3SMauro Carvalho Chehabmethod (e.g. "cat", "dd", "echo"). The intent of this driver however, is 2144d2e26a3SMauro Carvalho Chehabto provide real time console interaction with a Linux partition's console, 2154d2e26a3SMauro Carvalho Chehabwhich requires the use of applications that provide bi-directional, 2164d2e26a3SMauro Carvalho Chehabinteractive I/O with a tty device. 2174d2e26a3SMauro Carvalho Chehab 2184d2e26a3SMauro Carvalho ChehabApplications (e.g. "minicom" and "screen") that act as terminal emulators 2194d2e26a3SMauro Carvalho Chehabor perform terminal type control sequence conversion on the data being 2204d2e26a3SMauro Carvalho Chehabpassed through them are NOT acceptable for providing interactive console 2214d2e26a3SMauro Carvalho ChehabI/O. These programs often emulate antiquated terminal types (vt100 and 2224d2e26a3SMauro Carvalho ChehabANSI) and expect inbound data to take the form of one of these supported 2234d2e26a3SMauro Carvalho Chehabterminal types but they either do not convert, or do not _adequately_ 2244d2e26a3SMauro Carvalho Chehabconvert, outbound data into the terminal type of the terminal which invoked 2254d2e26a3SMauro Carvalho Chehabthem (though screen makes an attempt and can apparently be configured with 2264d2e26a3SMauro Carvalho Chehabmuch termcap wrestling.) 2274d2e26a3SMauro Carvalho Chehab 2284d2e26a3SMauro Carvalho ChehabFor this reason kermit and cu are two of the recommended applications for 2294d2e26a3SMauro Carvalho Chehabinteracting with a Linux console via an hvcs device. These programs simply 2304d2e26a3SMauro Carvalho Chehabact as a conduit for data transfer to and from the tty device. They do not 2314d2e26a3SMauro Carvalho Chehabrequire inbound data to take the form of a particular terminal type, nor do 2324d2e26a3SMauro Carvalho Chehabthey cook outbound data to a particular terminal type. 2334d2e26a3SMauro Carvalho Chehab 2344d2e26a3SMauro Carvalho ChehabIn order to ensure proper functioning of console applications one must make 2354d2e26a3SMauro Carvalho Chehabsure that once connected to a /dev/hvcs console that the console's $TERM 2364d2e26a3SMauro Carvalho Chehabenv variable is set to the exact terminal type of the terminal emulator 2374d2e26a3SMauro Carvalho Chehabused to launch the interactive I/O application. If one is using xterm and 2384d2e26a3SMauro Carvalho Chehabkermit to connect to /dev/hvcs0 when the console prompt becomes available 2394d2e26a3SMauro Carvalho Chehabone should "export TERM=xterm" on the console. This tells ncurses 2404d2e26a3SMauro Carvalho Chehabapplications that are invoked from the console that they should output 2414d2e26a3SMauro Carvalho Chehabcontrol sequences that xterm can understand. 2424d2e26a3SMauro Carvalho Chehab 2434d2e26a3SMauro Carvalho ChehabAs a precautionary measure an hvcs user should always "exit" from their 2444d2e26a3SMauro Carvalho Chehabsession before disconnecting an application such as kermit from the device 2454d2e26a3SMauro Carvalho Chehabnode. If this is not done, the next user to connect to the console will 2464d2e26a3SMauro Carvalho Chehabcontinue using the previous user's logged in session which includes 2474d2e26a3SMauro Carvalho Chehabusing the $TERM variable that the previous user supplied. 2484d2e26a3SMauro Carvalho Chehab 2494d2e26a3SMauro Carvalho ChehabHotplug add and remove of vty-server adapters affects which /dev/hvcs* node 2504d2e26a3SMauro Carvalho Chehabis used to connect to each vty-server adapter. In order to determine which 2514d2e26a3SMauro Carvalho Chehabvty-server adapter is associated with which /dev/hvcs* node a special sysfs 2524d2e26a3SMauro Carvalho Chehabattribute has been added to each vty-server sysfs entry. This entry is 2534d2e26a3SMauro Carvalho Chehabcalled "index" and showing it reveals an integer that refers to the 2544d2e26a3SMauro Carvalho Chehab/dev/hvcs* entry to use to connect to that device. For instance cating the 2554d2e26a3SMauro Carvalho Chehabindex attribute of vty-server adapter 30000004 shows the following:: 2564d2e26a3SMauro Carvalho Chehab 2574d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index 2584d2e26a3SMauro Carvalho Chehab 2 2594d2e26a3SMauro Carvalho Chehab 2604d2e26a3SMauro Carvalho ChehabThis index of '2' means that in order to connect to vty-server adapter 2614d2e26a3SMauro Carvalho Chehab30000004 the user should interact with /dev/hvcs2. 2624d2e26a3SMauro Carvalho Chehab 2634d2e26a3SMauro Carvalho ChehabIt should be noted that due to the system hotplug I/O capabilities of a 2644d2e26a3SMauro Carvalho Chehabsystem the /dev/hvcs* entry that interacts with a particular vty-server 2654d2e26a3SMauro Carvalho Chehabadapter is not guaranteed to remain the same across system reboots. Look 2664d2e26a3SMauro Carvalho Chehabin the Q & A section for more on this issue. 2674d2e26a3SMauro Carvalho Chehab 2684d2e26a3SMauro Carvalho Chehab6. Disconnection 2694d2e26a3SMauro Carvalho Chehab================ 2704d2e26a3SMauro Carvalho Chehab 2714d2e26a3SMauro Carvalho ChehabAs a security feature to prevent the delivery of stale data to an 2724d2e26a3SMauro Carvalho Chehabunintended target the Power5 system firmware disables the fetching of data 2734d2e26a3SMauro Carvalho Chehaband discards that data when a connection between a vty-server and a vty has 2744d2e26a3SMauro Carvalho Chehabbeen severed. As an example, when a vty-server is immediately disconnected 2754d2e26a3SMauro Carvalho Chehabfrom a vty following output of data to the vty the vty adapter may not have 2764d2e26a3SMauro Carvalho Chehabenough time between when it received the data interrupt and when the 2774d2e26a3SMauro Carvalho Chehabconnection was severed to fetch the data from firmware before the fetch is 2784d2e26a3SMauro Carvalho Chehabdisabled by firmware. 2794d2e26a3SMauro Carvalho Chehab 2804d2e26a3SMauro Carvalho ChehabWhen hvcs is being used to serve consoles this behavior is not a huge issue 2814d2e26a3SMauro Carvalho Chehabbecause the adapter stays connected for large amounts of time following 2824d2e26a3SMauro Carvalho Chehabalmost all data writes. When hvcs is being used as a tty conduit to tunnel 2834d2e26a3SMauro Carvalho Chehabdata between two partitions [see Q & A below] this is a huge problem 2844d2e26a3SMauro Carvalho Chehabbecause the standard Linux behavior when cat'ing or dd'ing data to a device 2854d2e26a3SMauro Carvalho Chehabis to open the tty, send the data, and then close the tty. If this driver 2864d2e26a3SMauro Carvalho Chehabmanually terminated vty-server connections on tty close this would close 2874d2e26a3SMauro Carvalho Chehabthe vty-server and vty connection before the target vty has had a chance to 2884d2e26a3SMauro Carvalho Chehabfetch the data. 2894d2e26a3SMauro Carvalho Chehab 2904d2e26a3SMauro Carvalho ChehabAdditionally, disconnecting a vty-server and vty only on module removal or 2914d2e26a3SMauro Carvalho Chehabadapter removal is impractical because other vty-servers in other 2924d2e26a3SMauro Carvalho Chehabpartitions may require the usage of the target vty at any time. 2934d2e26a3SMauro Carvalho Chehab 2944d2e26a3SMauro Carvalho ChehabDue to this behavioral restriction disconnection of vty-servers from the 2954d2e26a3SMauro Carvalho Chehabconnected vty is a manual procedure using a write to a sysfs attribute 2964d2e26a3SMauro Carvalho Chehaboutlined below, on the other hand the initial vty-server connection to a 2974d2e26a3SMauro Carvalho Chehabvty is established automatically by this driver. Manual vty-server 2984d2e26a3SMauro Carvalho Chehabconnection is never required. 2994d2e26a3SMauro Carvalho Chehab 3004d2e26a3SMauro Carvalho ChehabIn order to terminate the connection between a vty-server and vty the 3014d2e26a3SMauro Carvalho Chehab"vterm_state" sysfs attribute within each vty-server's sysfs entry is used. 3024d2e26a3SMauro Carvalho ChehabReading this attribute reveals the current connection state of the 3034d2e26a3SMauro Carvalho Chehabvty-server adapter. A zero means that the vty-server is not connected to a 3044d2e26a3SMauro Carvalho Chehabvty. A one indicates that a connection is active. 3054d2e26a3SMauro Carvalho Chehab 3064d2e26a3SMauro Carvalho ChehabWriting a '0' (zero) to the vterm_state attribute will disconnect the VTERM 3074d2e26a3SMauro Carvalho Chehabconnection between the vty-server and target vty ONLY if the vterm_state 3084d2e26a3SMauro Carvalho Chehabpreviously read '1'. The write directive is ignored if the vterm_state 3094d2e26a3SMauro Carvalho Chehabread '0' or if any value other than '0' was written to the vterm_state 3104d2e26a3SMauro Carvalho Chehabattribute. The following example will show the method used for verifying 3114d2e26a3SMauro Carvalho Chehabthe vty-server connection status and disconnecting a vty-server connection:: 3124d2e26a3SMauro Carvalho Chehab 3134d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state 3144d2e26a3SMauro Carvalho Chehab 1 3154d2e26a3SMauro Carvalho Chehab 3164d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_state 3174d2e26a3SMauro Carvalho Chehab 3184d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state 3194d2e26a3SMauro Carvalho Chehab 0 3204d2e26a3SMauro Carvalho Chehab 3214d2e26a3SMauro Carvalho ChehabAll vty-server connections are automatically terminated when the device is 3224d2e26a3SMauro Carvalho Chehabhotplug removed and when the module is removed. 3234d2e26a3SMauro Carvalho Chehab 3244d2e26a3SMauro Carvalho Chehab7. Configuration 3254d2e26a3SMauro Carvalho Chehab================ 3264d2e26a3SMauro Carvalho Chehab 3274d2e26a3SMauro Carvalho ChehabEach vty-server has a sysfs entry in the /sys/devices/vio directory, which 3284d2e26a3SMauro Carvalho Chehabis symlinked in several other sysfs tree directories, notably under the 3294d2e26a3SMauro Carvalho Chehabhvcs driver entry, which looks like the following example:: 3304d2e26a3SMauro Carvalho Chehab 3314d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs # ls 3324d2e26a3SMauro Carvalho Chehab . .. 30000003 30000004 rescan 3334d2e26a3SMauro Carvalho Chehab 3344d2e26a3SMauro Carvalho ChehabBy design, firmware notifies the hvcs driver of vty-server lifetimes and 3354d2e26a3SMauro Carvalho Chehabpartner vty removals but not the addition of partner vtys. Since an HMC 3364d2e26a3SMauro Carvalho ChehabSuper Admin can add partner info dynamically we have provided the hvcs 3374d2e26a3SMauro Carvalho Chehabdriver sysfs directory with the "rescan" update attribute which will query 3384d2e26a3SMauro Carvalho Chehabfirmware and update the partner info for all the vty-servers that this 3394d2e26a3SMauro Carvalho Chehabdriver manages. Writing a '1' to the attribute triggers the update. An 3404d2e26a3SMauro Carvalho Chehabexplicit example follows: 3414d2e26a3SMauro Carvalho Chehab 3424d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan 3434d2e26a3SMauro Carvalho Chehab 3444d2e26a3SMauro Carvalho ChehabReading the attribute will indicate a state of '1' or '0'. A one indicates 3454d2e26a3SMauro Carvalho Chehabthat an update is in process. A zero indicates that an update has 3464d2e26a3SMauro Carvalho Chehabcompleted or was never executed. 3474d2e26a3SMauro Carvalho Chehab 3484d2e26a3SMauro Carvalho ChehabVty-server entries in this directory are a 32 bit partition unique unit 3494d2e26a3SMauro Carvalho Chehabaddress that is created by firmware. An example vty-server sysfs entry 3504d2e26a3SMauro Carvalho Chehablooks like the following:: 3514d2e26a3SMauro Carvalho Chehab 3524d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls 3534d2e26a3SMauro Carvalho Chehab . current_vty devspec name partner_vtys 3544d2e26a3SMauro Carvalho Chehab .. index partner_clcs vterm_state 3554d2e26a3SMauro Carvalho Chehab 3564d2e26a3SMauro Carvalho ChehabEach entry is provided, by default with a "name" attribute. Reading the 3574d2e26a3SMauro Carvalho Chehab"name" attribute will reveal the device type as shown in the following 3584d2e26a3SMauro Carvalho Chehabexample:: 3594d2e26a3SMauro Carvalho Chehab 3604d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name 3614d2e26a3SMauro Carvalho Chehab vty-server 3624d2e26a3SMauro Carvalho Chehab 3634d2e26a3SMauro Carvalho ChehabEach entry is also provided, by default, with a "devspec" attribute which 3644d2e26a3SMauro Carvalho Chehabreveals the full device specification when read, as shown in the following 3654d2e26a3SMauro Carvalho Chehabexample:: 3664d2e26a3SMauro Carvalho Chehab 3674d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec 3684d2e26a3SMauro Carvalho Chehab /vdevice/vty-server@30000004 3694d2e26a3SMauro Carvalho Chehab 3704d2e26a3SMauro Carvalho ChehabEach vty-server sysfs dir is provided with two read-only attributes that 3714d2e26a3SMauro Carvalho Chehabprovide lists of easily parsed partner vty data: "partner_vtys" and 3724d2e26a3SMauro Carvalho Chehab"partner_clcs":: 3734d2e26a3SMauro Carvalho Chehab 3744d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys 3754d2e26a3SMauro Carvalho Chehab 30000000 3764d2e26a3SMauro Carvalho Chehab 30000001 3774d2e26a3SMauro Carvalho Chehab 30000002 3784d2e26a3SMauro Carvalho Chehab 30000000 3794d2e26a3SMauro Carvalho Chehab 30000000 3804d2e26a3SMauro Carvalho Chehab 3814d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_clcs 3824d2e26a3SMauro Carvalho Chehab U5112.428.103048A-V3-C0 3834d2e26a3SMauro Carvalho Chehab U5112.428.103048A-V3-C2 3844d2e26a3SMauro Carvalho Chehab U5112.428.103048A-V3-C3 3854d2e26a3SMauro Carvalho Chehab U5112.428.103048A-V4-C0 3864d2e26a3SMauro Carvalho Chehab U5112.428.103048A-V5-C0 3874d2e26a3SMauro Carvalho Chehab 3884d2e26a3SMauro Carvalho ChehabReading partner_vtys returns a list of partner vtys. Vty unit address 3894d2e26a3SMauro Carvalho Chehabnumbering is only per-partition-unique so entries will frequently repeat. 3904d2e26a3SMauro Carvalho Chehab 3914d2e26a3SMauro Carvalho ChehabReading partner_clcs returns a list of "converged location codes" which are 3924d2e26a3SMauro Carvalho Chehabcomposed of a system serial number followed by "-V*", where the '*' is the 3934d2e26a3SMauro Carvalho Chehabtarget partition number, and "-C*", where the '*' is the slot of the 3944d2e26a3SMauro Carvalho Chehabadapter. The first vty partner corresponds to the first clc item, the 3954d2e26a3SMauro Carvalho Chehabsecond vty partner to the second clc item, etc. 3964d2e26a3SMauro Carvalho Chehab 3974d2e26a3SMauro Carvalho ChehabA vty-server can only be connected to a single vty at a time. The entry, 3984d2e26a3SMauro Carvalho Chehab"current_vty" prints the clc of the currently selected partner vty when 3994d2e26a3SMauro Carvalho Chehabread. 4004d2e26a3SMauro Carvalho Chehab 4014d2e26a3SMauro Carvalho ChehabThe current_vty can be changed by writing a valid partner clc to the entry 4024d2e26a3SMauro Carvalho Chehabas in the following example:: 4034d2e26a3SMauro Carvalho Chehab 4044d2e26a3SMauro Carvalho Chehab Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304 4054d2e26a3SMauro Carvalho Chehab 8A-V4-C0 > current_vty 4064d2e26a3SMauro Carvalho Chehab 4074d2e26a3SMauro Carvalho ChehabChanging the current_vty when a vty-server is already connected to a vty 4084d2e26a3SMauro Carvalho Chehabdoes not affect the current connection. The change takes effect when the 4094d2e26a3SMauro Carvalho Chehabcurrently open connection is freed. 4104d2e26a3SMauro Carvalho Chehab 4114d2e26a3SMauro Carvalho ChehabInformation on the "vterm_state" attribute was covered earlier on the 4124d2e26a3SMauro Carvalho Chehabchapter entitled "disconnection". 4134d2e26a3SMauro Carvalho Chehab 4144d2e26a3SMauro Carvalho Chehab8. Questions & Answers: 4154d2e26a3SMauro Carvalho Chehab======================= 4164d2e26a3SMauro Carvalho Chehab 4174d2e26a3SMauro Carvalho ChehabQ: What are the security concerns involving hvcs? 4184d2e26a3SMauro Carvalho Chehab 4194d2e26a3SMauro Carvalho ChehabA: There are three main security concerns: 4204d2e26a3SMauro Carvalho Chehab 4214d2e26a3SMauro Carvalho Chehab 1. The creator of the /dev/hvcs* nodes has the ability to restrict 4224d2e26a3SMauro Carvalho Chehab the access of the device entries to certain users or groups. It 4234d2e26a3SMauro Carvalho Chehab may be best to create a special hvcs group privilege for providing 4244d2e26a3SMauro Carvalho Chehab access to system consoles. 4254d2e26a3SMauro Carvalho Chehab 4264d2e26a3SMauro Carvalho Chehab 2. To provide network security when grabbing the console it is 4274d2e26a3SMauro Carvalho Chehab suggested that the user connect to the console hosting partition 4284d2e26a3SMauro Carvalho Chehab using a secure method, such as SSH or sit at a hardware console. 4294d2e26a3SMauro Carvalho Chehab 4304d2e26a3SMauro Carvalho Chehab 3. Make sure to exit the user session when done with a console or 4314d2e26a3SMauro Carvalho Chehab the next vty-server connection (which may be from another 4324d2e26a3SMauro Carvalho Chehab partition) will experience the previously logged in session. 4334d2e26a3SMauro Carvalho Chehab 4344d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 4354d2e26a3SMauro Carvalho Chehab 4364d2e26a3SMauro Carvalho ChehabQ: How do I multiplex a console that I grab through hvcs so that other 4374d2e26a3SMauro Carvalho Chehabpeople can see it: 4384d2e26a3SMauro Carvalho Chehab 4394d2e26a3SMauro Carvalho ChehabA: You can use "screen" to directly connect to the /dev/hvcs* device and 4404d2e26a3SMauro Carvalho Chehabsetup a session on your machine with the console group privileges. As 4414d2e26a3SMauro Carvalho Chehabpointed out earlier by default screen doesn't provide the termcap settings 4424d2e26a3SMauro Carvalho Chehabfor most terminal emulators to provide adequate character conversion from 4434d2e26a3SMauro Carvalho Chehabterm type "screen" to others. This means that curses based programs may 4444d2e26a3SMauro Carvalho Chehabnot display properly in screen sessions. 4454d2e26a3SMauro Carvalho Chehab 4464d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 4474d2e26a3SMauro Carvalho Chehab 4484d2e26a3SMauro Carvalho ChehabQ: Why are the colors all messed up? 4494d2e26a3SMauro Carvalho ChehabQ: Why are the control characters acting strange or not working? 4504d2e26a3SMauro Carvalho ChehabQ: Why is the console output all strange and unintelligible? 4514d2e26a3SMauro Carvalho Chehab 4524d2e26a3SMauro Carvalho ChehabA: Please see the preceding section on "Connection" for a discussion of how 4534d2e26a3SMauro Carvalho Chehabapplications can affect the display of character control sequences. 4544d2e26a3SMauro Carvalho ChehabAdditionally, just because you logged into the console using and xterm 4554d2e26a3SMauro Carvalho Chehabdoesn't mean someone else didn't log into the console with the HMC console 4564d2e26a3SMauro Carvalho Chehab(vt320) before you and leave the session logged in. The best thing to do 4574d2e26a3SMauro Carvalho Chehabis to export TERM to the terminal type of your terminal emulator when you 4584d2e26a3SMauro Carvalho Chehabget the console. Additionally make sure to "exit" the console before you 4594d2e26a3SMauro Carvalho Chehabdisconnect from the console. This will ensure that the next user gets 4604d2e26a3SMauro Carvalho Chehabtheir own TERM type set when they login. 4614d2e26a3SMauro Carvalho Chehab 4624d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 4634d2e26a3SMauro Carvalho Chehab 4644d2e26a3SMauro Carvalho ChehabQ: When I try to CONNECT kermit to an hvcs device I get: 4654d2e26a3SMauro Carvalho Chehab"Sorry, can't open connection: /dev/hvcs*"What is happening? 4664d2e26a3SMauro Carvalho Chehab 4674d2e26a3SMauro Carvalho ChehabA: Some other Power5 console mechanism has a connection to the vty and 4684d2e26a3SMauro Carvalho Chehabisn't giving it up. You can try to force disconnect the consoles from the 4694d2e26a3SMauro Carvalho ChehabHMC by right clicking on the partition and then selecting "close terminal". 4704d2e26a3SMauro Carvalho ChehabOtherwise you have to hunt down the people who have console authority. It 4714d2e26a3SMauro Carvalho Chehabis possible that you already have the console open using another kermit 4724d2e26a3SMauro Carvalho Chehabsession and just forgot about it. Please review the console options for 4734d2e26a3SMauro Carvalho ChehabPower5 systems to determine the many ways a system console can be held. 4744d2e26a3SMauro Carvalho Chehab 4754d2e26a3SMauro Carvalho ChehabOR 4764d2e26a3SMauro Carvalho Chehab 4774d2e26a3SMauro Carvalho ChehabA: Another user may not have a connectivity method currently attached to a 4784d2e26a3SMauro Carvalho Chehab/dev/hvcs device but the vterm_state may reveal that they still have the 4794d2e26a3SMauro Carvalho Chehabvty-server connection established. They need to free this using the method 4804d2e26a3SMauro Carvalho Chehaboutlined in the section on "Disconnection" in order for others to connect 4814d2e26a3SMauro Carvalho Chehabto the target vty. 4824d2e26a3SMauro Carvalho Chehab 4834d2e26a3SMauro Carvalho ChehabOR 4844d2e26a3SMauro Carvalho Chehab 4854d2e26a3SMauro Carvalho ChehabA: The user profile you are using to execute kermit probably doesn't have 4864d2e26a3SMauro Carvalho Chehabpermissions to use the /dev/hvcs* device. 4874d2e26a3SMauro Carvalho Chehab 4884d2e26a3SMauro Carvalho ChehabOR 4894d2e26a3SMauro Carvalho Chehab 4904d2e26a3SMauro Carvalho ChehabA: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs* 4914d2e26a3SMauro Carvalho Chehabentry still exists (on systems without udev). 4924d2e26a3SMauro Carvalho Chehab 4934d2e26a3SMauro Carvalho ChehabOR 4944d2e26a3SMauro Carvalho Chehab 4954d2e26a3SMauro Carvalho ChehabA: There is not a corresponding vty-server device that maps to an existing 4964d2e26a3SMauro Carvalho Chehab/dev/hvcs* entry. 4974d2e26a3SMauro Carvalho Chehab 4984d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 4994d2e26a3SMauro Carvalho Chehab 5004d2e26a3SMauro Carvalho ChehabQ: When I try to CONNECT kermit to an hvcs device I get: 5014d2e26a3SMauro Carvalho Chehab"Sorry, write access to UUCP lockfile directory denied." 5024d2e26a3SMauro Carvalho Chehab 5034d2e26a3SMauro Carvalho ChehabA: The /dev/hvcs* entry you have specified doesn't exist where you said it 5044d2e26a3SMauro Carvalho Chehabdoes? Maybe you haven't inserted the module (on systems with udev). 5054d2e26a3SMauro Carvalho Chehab 5064d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 5074d2e26a3SMauro Carvalho Chehab 5084d2e26a3SMauro Carvalho ChehabQ: If I already have one Linux partition installed can I use hvcs on said 5094d2e26a3SMauro Carvalho Chehabpartition to provide the console for the install of a second Linux 5104d2e26a3SMauro Carvalho Chehabpartition? 5114d2e26a3SMauro Carvalho Chehab 5124d2e26a3SMauro Carvalho ChehabA: Yes granted that your are connected to the /dev/hvcs* device using 5134d2e26a3SMauro Carvalho Chehabkermit or cu or some other program that doesn't provide terminal emulation. 5144d2e26a3SMauro Carvalho Chehab 5154d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 5164d2e26a3SMauro Carvalho Chehab 5174d2e26a3SMauro Carvalho ChehabQ: Can I connect to more than one partition's console at a time using this 5184d2e26a3SMauro Carvalho Chehabdriver? 5194d2e26a3SMauro Carvalho Chehab 5204d2e26a3SMauro Carvalho ChehabA: Yes. Of course this means that there must be more than one vty-server 5214d2e26a3SMauro Carvalho Chehabconfigured for this partition and each must point to a disconnected vty. 5224d2e26a3SMauro Carvalho Chehab 5234d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 5244d2e26a3SMauro Carvalho Chehab 5254d2e26a3SMauro Carvalho ChehabQ: Does the hvcs driver support dynamic (hotplug) addition of devices? 5264d2e26a3SMauro Carvalho Chehab 5274d2e26a3SMauro Carvalho ChehabA: Yes, if you have dlpar and hotplug enabled for your system and it has 5284d2e26a3SMauro Carvalho Chehabbeen built into the kernel the hvcs drivers is configured to dynamically 5294d2e26a3SMauro Carvalho Chehabhandle additions of new devices and removals of unused devices. 5304d2e26a3SMauro Carvalho Chehab 5314d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 5324d2e26a3SMauro Carvalho Chehab 5334d2e26a3SMauro Carvalho ChehabQ: For some reason /dev/hvcs* doesn't map to the same vty-server adapter 5344d2e26a3SMauro Carvalho Chehabafter a reboot. What happened? 5354d2e26a3SMauro Carvalho Chehab 5364d2e26a3SMauro Carvalho ChehabA: Assignment of vty-server adapters to /dev/hvcs* entries is always done 5374d2e26a3SMauro Carvalho Chehabin the order that the adapters are exposed. Due to hotplug capabilities of 5384d2e26a3SMauro Carvalho Chehabthis driver assignment of hotplug added vty-servers may be in a different 5394d2e26a3SMauro Carvalho Chehaborder than how they would be exposed on module load. Rebooting or 5404d2e26a3SMauro Carvalho Chehabreloading the module after dynamic addition may result in the /dev/hvcs* 5414d2e26a3SMauro Carvalho Chehaband vty-server coupling changing if a vty-server adapter was added in a 5424d2e26a3SMauro Carvalho Chehabslot between two other vty-server adapters. Refer to the section above 5434d2e26a3SMauro Carvalho Chehabon how to determine which vty-server goes with which /dev/hvcs* node. 5444d2e26a3SMauro Carvalho ChehabHint; look at the sysfs "index" attribute for the vty-server. 5454d2e26a3SMauro Carvalho Chehab 5464d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 5474d2e26a3SMauro Carvalho Chehab 5484d2e26a3SMauro Carvalho ChehabQ: Can I use /dev/hvcs* as a conduit to another partition and use a tty 5494d2e26a3SMauro Carvalho Chehabdevice on that partition as the other end of the pipe? 5504d2e26a3SMauro Carvalho Chehab 5514d2e26a3SMauro Carvalho ChehabA: Yes, on Power5 platforms the hvc_console driver provides a tty interface 5524d2e26a3SMauro Carvalho Chehabfor extra /dev/hvc* devices (where /dev/hvc0 is most likely the console). 5534d2e26a3SMauro Carvalho ChehabIn order to get a tty conduit working between the two partitions the HMC 5544d2e26a3SMauro Carvalho ChehabSuper Admin must create an additional "serial server" for the target 5554d2e26a3SMauro Carvalho Chehabpartition with the HMC gui which will show up as /dev/hvc* when the target 5564d2e26a3SMauro Carvalho Chehabpartition is rebooted. 5574d2e26a3SMauro Carvalho Chehab 5584d2e26a3SMauro Carvalho ChehabThe HMC Super Admin then creates an additional "serial client" for the 5594d2e26a3SMauro Carvalho Chehabcurrent partition and points this at the target partition's newly created 5604d2e26a3SMauro Carvalho Chehab"serial server" adapter (remember the slot). This shows up as an 5614d2e26a3SMauro Carvalho Chehabadditional /dev/hvcs* device. 5624d2e26a3SMauro Carvalho Chehab 5634d2e26a3SMauro Carvalho ChehabNow a program on the target system can be configured to read or write to 5644d2e26a3SMauro Carvalho Chehab/dev/hvc* and another program on the current partition can be configured to 5654d2e26a3SMauro Carvalho Chehabread or write to /dev/hvcs*. Now you have a tty conduit between two 5664d2e26a3SMauro Carvalho Chehabpartitions. 5674d2e26a3SMauro Carvalho Chehab 5684d2e26a3SMauro Carvalho Chehab--------------------------------------------------------------------------- 5694d2e26a3SMauro Carvalho Chehab 5704d2e26a3SMauro Carvalho Chehab9. Reporting Bugs: 5714d2e26a3SMauro Carvalho Chehab================== 5724d2e26a3SMauro Carvalho Chehab 5734d2e26a3SMauro Carvalho ChehabThe proper channel for reporting bugs is either through the Linux OS 5744d2e26a3SMauro Carvalho Chehabdistribution company that provided your OS or by posting issues to the 5754d2e26a3SMauro Carvalho ChehabPowerPC development mailing list at: 5764d2e26a3SMauro Carvalho Chehab 5774d2e26a3SMauro Carvalho Chehablinuxppc-dev@lists.ozlabs.org 5784d2e26a3SMauro Carvalho Chehab 5794d2e26a3SMauro Carvalho ChehabThis request is to provide a documented and searchable public exchange 5804d2e26a3SMauro Carvalho Chehabof the problems and solutions surrounding this driver for the benefit of 5814d2e26a3SMauro Carvalho Chehaball users. 582