Lines Matching refs:the
8 NOTE:Eight space tabs are the optimum editor setting for reading this file.
33 This is the device driver for the IBM Hypervisor Virtual Console Server,
35 space applications access to the system consoles of logically partitioned
36 operating systems (Linux and AIX) running on the same partitioned Power5
48 though some care was taken to abstract the architecture dependent firmware
49 calls from the driver code.
51 Sysfs must be mounted on the system so that the user can determine which
53 for sysfs mounting are outside the scope of this document.
60 requested by the registering driver. The hvcs driver asks the tty layer
64 If the default number of device entries is adequate then this driver can be
65 built into the kernel. If not, the default can be over-ridden by inserting
66 the driver as a module with insmod parameters.
72 driver into the kernel.
78 Begin the kernel make process.
90 The make process will build the following kernel modules:
95 To insert the module with the default allocation execute the following
96 commands in the order they appear:
102 be inserted first, otherwise the hvcs module will not find some of the
105 To override the default use an insmod parameter as follows (requesting 4
112 to allow. This can always be changed by modifying the constant in the
115 NOTE: The length of time it takes to insmod the driver seems to be related
116 to the number of tty interfaces the registering driver requests.
118 In order to remove the driver module execute the following command:
129 before hvcs.ko and modprobe uses this file to smartly insert the modules in
130 the proper order.
132 The following modprobe command is used to remove hvcs and hvcserver in the
140 The tty layer creates sysfs entries which contain the major and minor
141 numbers allocated for the hvcs driver. The following snippet of "tree"
142 output of the sysfs directory shows where these numbers are presented:
166 For the above examples the following output is a result of cat'ing the
167 "dev" entry in the hvcs directory:
181 The output from reading the "dev" attribute is the char device major and
182 minor numbers that the tty layer has allocated for this driver's use. Most
183 systems running hvcs will already have the device entries created or udev
186 Given the example output above, to manually create a /dev/hvcs* node entry
194 Using mknod to manually create the device entries makes these device nodes
195 persistent. Once created they will exist prior to the driver insmod.
198 the hvcs module will result in an error message similar to the following:
209 interact with the device node entries using any standard tty-interactive
212 which requires the use of applications that provide bi-directional,
216 or perform terminal type control sequence conversion on the data being
219 ANSI) and expect inbound data to take the form of one of these supported
221 convert, outbound data into the terminal type of the terminal which invoked
225 For this reason kermit and cu are two of the recommended applications for
227 act as a conduit for data transfer to and from the tty device. They do not
228 require inbound data to take the form of a particular terminal type, nor do
232 sure that once connected to a /dev/hvcs console that the console's $TERM
233 env variable is set to the exact terminal type of the terminal emulator
234 used to launch the interactive I/O application. If one is using xterm and
235 kermit to connect to /dev/hvcs0 when the console prompt becomes available
236 one should "export TERM=xterm" on the console. This tells ncurses
237 applications that are invoked from the console that they should output
241 session before disconnecting an application such as kermit from the device
242 node. If this is not done, the next user to connect to the console will
243 continue using the previous user's logged in session which includes
244 using the $TERM variable that the previous user supplied.
250 called "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
252 index attribute of vty-server adapter 30000004 shows the following.
258 30000004 the user should interact with /dev/hvcs2.
260 It should be noted that due to the system hotplug I/O capabilities of a
261 system the /dev/hvcs* entry that interacts with a particular vty-server
262 adapter is not guaranteed to remain the same across system reboots. Look
263 in the Q & A section for more on this issue.
268 As a security feature to prevent the delivery of stale data to an
269 unintended target the Power5 system firmware disables the fetching of data
272 from a vty following output of data to the vty the vty adapter may not have
273 enough time between when it received the data interrupt and when the
274 connection was severed to fetch the data from firmware before the fetch is
278 because the adapter stays connected for large amounts of time following
281 because the standard Linux behavior when cat'ing or dd'ing data to a device
282 is to open the tty, send the data, and then close the tty. If this driver
284 the vty-server and vty connection before the target vty has had a chance to
285 fetch the data.
289 partitions may require the usage of the target vty at any time.
291 Due to this behavioral restriction disconnection of vty-servers from the
293 outlined below, on the other hand the initial vty-server connection to a
297 In order to terminate the connection between a vty-server and vty the
299 Reading this attribute reveals the current connection state of the
300 vty-server adapter. A zero means that the vty-server is not connected to a
303 Writing a '0' (zero) to the vterm_state attribute will disconnect the VTERM
304 connection between the vty-server and target vty ONLY if the vterm_state
305 previously read '1'. The write directive is ignored if the vterm_state
306 read '0' or if any value other than '0' was written to the vterm_state
307 attribute. The following example will show the method used for verifying
308 the vty-server connection status and disconnecting a vty-server connection.
318 All vty-server connections are automatically terminated when the device is
319 hotplug removed and when the module is removed.
324 Each vty-server has a sysfs entry in the /sys/devices/vio directory, which
325 is symlinked in several other sysfs tree directories, notably under the
326 hvcs driver entry, which looks like the following example:
331 By design, firmware notifies the hvcs driver of vty-server lifetimes and
332 partner vty removals but not the addition of partner vtys. Since an HMC
333 Super Admin can add partner info dynamically we have provided the hvcs
334 driver sysfs directory with the "rescan" update attribute which will query
335 firmware and update the partner info for all the vty-servers that this
336 driver manages. Writing a '1' to the attribute triggers the update. An
341 Reading the attribute will indicate a state of '1' or '0'. A one indicates
347 looks like the following:
353 Each entry is provided, by default with a "name" attribute. Reading the
354 "name" attribute will reveal the device type as shown in the following
361 reveals the full device specification when read, as shown in the following
389 composed of a system serial number followed by "-V*", where the '*' is the
390 target partition number, and "-C*", where the '*' is the slot of the
391 adapter. The first vty partner corresponds to the first clc item, the
392 second vty partner to the second clc item, etc.
395 "current_vty" prints the clc of the currently selected partner vty when
398 The current_vty can be changed by writing a valid partner clc to the entry
399 as in the following example:
404 Changing the current_vty when a vty-server is already connected to a vty
405 does not affect the current connection. The change takes effect when the
408 Information on the "vterm_state" attribute was covered earlier on the
414 Q: What are the security concerns involving hvcs?
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
423 2. To provide network security when grabbing the console it is
424 suggested that the user connect to the console hosting partition
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.
435 A: You can use "screen" to directly connect to the /dev/hvcs* device and
436 setup a session on your machine with the console group privileges. As
437 pointed out earlier by default screen doesn't provide the termcap settings
443 Q: Why are the colors all messed up?
444 Q: Why are the control characters acting strange or not working?
445 Q: Why is the console output all strange and unintelligible?
447 A: Please see the preceding section on "Connection" for a discussion of how
448 applications can affect the display of character control sequences.
449 Additionally, just because you logged into the console using and xterm
450 doesn'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
452 is to export TERM to the terminal type of your terminal emulator when you
453 get the console. Additionally make sure to "exit" the console before you
454 disconnect from the console. This will ensure that the next user gets
461 A: Some other Power5 console mechanism has a connection to the vty and
462 isn't giving it up. You can try to force disconnect the consoles from the
463 HMC by right clicking on the partition and then selecting "close terminal".
464 Otherwise you have to hunt down the people who have console authority. It
465 is possible that you already have the console open using another kermit
466 session and just forgot about it. Please review the console options for
467 Power5 systems to determine the many ways a system console can be held.
472 /dev/hvcs device but the vterm_state may reveal that they still have the
473 vty-server connection established. They need to free this using the method
474 outlined in the section on "Disconnection" in order for others to connect
475 to the target vty.
480 permissions to use the /dev/hvcs* device.
484 A: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs*
497 does? Maybe you haven't inserted the module (on systems with udev).
501 partition to provide the console for the install of a second Linux
504 A: Yes granted that your are connected to the /dev/hvcs* device using
515 Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
518 been built into the kernel the hvcs drivers is configured to dynamically
522 Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
526 in the order that the adapters are exposed. Due to hotplug capabilities of
529 reloading the module after dynamic addition may result in the /dev/hvcs*
531 slot between two other vty-server adapters. Refer to the section above
533 Hint; look at the sysfs "index" attribute for the vty-server.
537 device on that partition as the other end of the pipe?
539 A: Yes, on Power5 platforms the hvc_console driver provides a tty interface
540 for extra /dev/hvc* devices (where /dev/hvc0 is most likely the console).
541 In order to get a tty conduit working between the two partitions the HMC
542 Super Admin must create an additional "serial server" for the target
543 partition with the HMC gui which will show up as /dev/hvc* when the target
546 The HMC Super Admin then creates an additional "serial client" for the
547 current partition and points this at the target partition's newly created
548 "serial server" adapter (remember the slot). This shows up as an
551 Now 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
559 The proper channel for reporting bugs is either through the Linux OS
560 distribution company that provided your OS or by posting issues to the
566 of the problems and solutions surrounding this driver for the benefit of