1 ==============================================
2 HVCS IBM "Hypervisor Virtual Console Server" I
3 ==============================================
4
5 for Linux Kernel 2.6.4+
6
7 Copyright (C) 2004 IBM Corporation
8
9 .. ===========================================
10 .. NOTE:Eight space tabs are the optimum edito
11 .. ===========================================
12
13
14 Author(s): Ryan S. Arnold <rsa@us.ibm.com>
15
16 Date Created: March, 02, 2004
17 Last Changed: August, 24, 2004
18
19 .. Table of contents:
20
21 1. Driver Introduction:
22 2. System Requirements
23 3. Build Options:
24 3.1 Built-in:
25 3.2 Module:
26 4. Installation:
27 5. Connection:
28 6. Disconnection:
29 7. Configuration:
30 8. Questions & Answers:
31 9. Reporting Bugs:
32
33 1. Driver Introduction:
34 =======================
35
36 This is the device driver for the IBM Hypervis
37 "hvcs". The IBM hvcs provides a tty driver in
38 space applications access to the system consol
39 operating systems (Linux and AIX) running on t
40 ppc64 system. Physical hardware consoles per
41 on this hardware so system consoles are access
42 firmware interfaces to virtual terminal device
43
44 2. System Requirements:
45 =======================
46
47 This device driver was written using 2.6.4 Lin
48 build and run on kernels of this version or la
49
50 This driver was written to operate solely on I
51 though some care was taken to abstract the arc
52 calls from the driver code.
53
54 Sysfs must be mounted on the system so that th
55 major and minor numbers are associated with ea
56 for sysfs mounting are outside the scope of th
57
58 3. Build Options:
59 =================
60
61 The hvcs driver registers itself as a tty driv
62 dynamically allocates a block of major and min
63 requested by the registering driver. The hvcs
64 for 64 of these major/minor numbers by default
65 entries.
66
67 If the default number of device entries is ade
68 built into the kernel. If not, the default ca
69 the driver as a module with insmod parameters.
70
71 3.1 Built-in:
72 -------------
73
74 The following menuconfig example demonstrates
75 driver into the kernel::
76
77 Device Drivers --->
78 Character devices --->
79 <*> IBM Hypervisor Vir
80
81 Begin the kernel make process.
82
83 3.2 Module:
84 -----------
85
86 The following menuconfig example demonstrates
87 driver as a kernel module::
88
89 Device Drivers --->
90 Character devices --->
91 <M> IBM Hypervisor Vir
92
93 The make process will build the following kern
94
95 - hvcs.ko
96 - hvcserver.ko
97
98 To insert the module with the default allocati
99 commands in the order they appear::
100
101 insmod hvcserver.ko
102 insmod hvcs.ko
103
104 The hvcserver module contains architecture spe
105 be inserted first, otherwise the hvcs module w
106 symbols it expects.
107
108 To override the default use an insmod paramete
109 tty devices as an example)::
110
111 insmod hvcs.ko hvcs_parm_num_devs=4
112
113 There is a maximum number of dev entries that
114 We think that 1024 is currently a decent maxim
115 to allow. This can always be changed by modif
116 source file before building.
117
118 NOTE: The length of time it takes to insmod th
119 to the number of tty interfaces the registerin
120
121 In order to remove the driver module execute t
122
123 rmmod hvcs.ko
124
125 The recommended method for installing hvcs as
126 build a current modules.dep file in /lib/modul
127 execute::
128
129 modprobe hvcs hvcs_parm_num_devs=4
130
131 The modules.dep file indicates that hvcserver.
132 before hvcs.ko and modprobe uses this file to
133 the proper order.
134
135 The following modprobe command is used to remo
136 proper order::
137
138 modprobe -r hvcs
139
140 4. Installation:
141 ================
142
143 The tty layer creates sysfs entries which cont
144 numbers allocated for the hvcs driver. The fo
145 output of the sysfs directory shows where thes
146
147 sys/
148 |-- *other sysfs base dirs*
149 |
150 |-- class
151 | |-- *other classes of devices*
152 | |
153 | `-- tty
154 | |-- *other tty devices*
155 | |
156 | |-- hvcs0
157 | | `-- dev
158 | |-- hvcs1
159 | | `-- dev
160 | |-- hvcs2
161 | | `-- dev
162 | |-- hvcs3
163 | | `-- dev
164 | |
165 | |-- *other tty devices*
166 |
167 |-- *other sysfs base dirs*
168
169 For the above examples the following output is
170 "dev" entry in the hvcs directory::
171
172 Pow5:/sys/class/tty/hvcs0/ # cat dev
173 254:0
174
175 Pow5:/sys/class/tty/hvcs1/ # cat dev
176 254:1
177
178 Pow5:/sys/class/tty/hvcs2/ # cat dev
179 254:2
180
181 Pow5:/sys/class/tty/hvcs3/ # cat dev
182 254:3
183
184 The output from reading the "dev" attribute is
185 minor numbers that the tty layer has allocated
186 systems running hvcs will already have the dev
187 will do it automatically.
188
189 Given the example output above, to manually cr
190 mknod can be used as follows::
191
192 mknod /dev/hvcs0 c 254 0
193 mknod /dev/hvcs1 c 254 1
194 mknod /dev/hvcs2 c 254 2
195 mknod /dev/hvcs3 c 254 3
196
197 Using mknod to manually create the device entr
198 persistent. Once created they will exist prio
199
200 Attempting to connect an application to /dev/h
201 the hvcs module will result in an error messag
202
203 "/dev/hvcs*: No such device".
204
205 NOTE: Just because there is a device node pres
206 is a vty-server device configured for that nod
207
208 5. Connection
209 =============
210
211 Since this driver controls devices that provid
212 interact with the device node entries using an
213 method (e.g. "cat", "dd", "echo"). The intent
214 to provide real time console interaction with
215 which requires the use of applications that pr
216 interactive I/O with a tty device.
217
218 Applications (e.g. "minicom" and "screen") tha
219 or perform terminal type control sequence conv
220 passed through them are NOT acceptable for pro
221 I/O. These programs often emulate antiquated
222 ANSI) and expect inbound data to take the form
223 terminal types but they either do not convert,
224 convert, outbound data into the terminal type
225 them (though screen makes an attempt and can a
226 much termcap wrestling.)
227
228 For this reason kermit and cu are two of the r
229 interacting with a Linux console via an hvcs d
230 act as a conduit for data transfer to and from
231 require inbound data to take the form of a par
232 they cook outbound data to a particular termin
233
234 In order to ensure proper functioning of conso
235 sure that once connected to a /dev/hvcs consol
236 env variable is set to the exact terminal type
237 used to launch the interactive I/O application
238 kermit to connect to /dev/hvcs0 when the conso
239 one should "export TERM=xterm" on the console.
240 applications that are invoked from the console
241 control sequences that xterm can understand.
242
243 As a precautionary measure an hvcs user should
244 session before disconnecting an application su
245 node. If this is not done, the next user to c
246 continue using the previous user's logged in s
247 using the $TERM variable that the previous use
248
249 Hotplug add and remove of vty-server adapters
250 is used to connect to each vty-server adapter.
251 vty-server adapter is associated with which /d
252 attribute has been added to each vty-server sy
253 called "index" and showing it reveals an integ
254 /dev/hvcs* entry to use to connect to that dev
255 index attribute of vty-server adapter 30000004
256
257 Pow5:/sys/bus/vio/drivers/hvcs/3000000
258 2
259
260 This index of '2' means that in order to conne
261 30000004 the user should interact with /dev/hv
262
263 It should be noted that due to the system hotp
264 system the /dev/hvcs* entry that interacts wit
265 adapter is not guaranteed to remain the same a
266 in the Q & A section for more on this issue.
267
268 6. Disconnection
269 ================
270
271 As a security feature to prevent the delivery
272 unintended target the Power5 system firmware d
273 and discards that data when a connection betwe
274 been severed. As an example, when a vty-serve
275 from a vty following output of data to the vty
276 enough time between when it received the data
277 connection was severed to fetch the data from
278 disabled by firmware.
279
280 When hvcs is being used to serve consoles this
281 because the adapter stays connected for large
282 almost all data writes. When hvcs is being us
283 data between two partitions [see Q & A below]
284 because the standard Linux behavior when cat'i
285 is to open the tty, send the data, and then cl
286 manually terminated vty-server connections on
287 the vty-server and vty connection before the t
288 fetch the data.
289
290 Additionally, disconnecting a vty-server and v
291 adapter removal is impractical because other v
292 partitions may require the usage of the target
293
294 Due to this behavioral restriction disconnecti
295 connected vty is a manual procedure using a wr
296 outlined below, on the other hand the initial
297 vty is established automatically by this drive
298 connection is never required.
299
300 In order to terminate the connection between a
301 "vterm_state" sysfs attribute within each vty-
302 Reading this attribute reveals the current con
303 vty-server adapter. A zero means that the vty
304 vty. A one indicates that a connection is act
305
306 Writing a '0' (zero) to the vterm_state attrib
307 connection between the vty-server and target v
308 previously read '1'. The write directive is i
309 read '0' or if any value other than '0' was wr
310 attribute. The following example will show th
311 the vty-server connection status and disconnec
312
313 Pow5:/sys/bus/vio/drivers/hvcs/3000000
314 1
315
316 Pow5:/sys/bus/vio/drivers/hvcs/3000000
317
318 Pow5:/sys/bus/vio/drivers/hvcs/3000000
319 0
320
321 All vty-server connections are automatically t
322 hotplug removed and when the module is removed
323
324 7. Configuration
325 ================
326
327 Each vty-server has a sysfs entry in the /sys/
328 is symlinked in several other sysfs tree direc
329 hvcs driver entry, which looks like the follow
330
331 Pow5:/sys/bus/vio/drivers/hvcs # ls
332 . .. 30000003 30000004 rescan
333
334 By design, firmware notifies the hvcs driver o
335 partner vty removals but not the addition of p
336 Super Admin can add partner info dynamically w
337 driver sysfs directory with the "rescan" updat
338 firmware and update the partner info for all t
339 driver manages. Writing a '1' to the attribut
340 explicit example follows:
341
342 Pow5:/sys/bus/vio/drivers/hvcs # echo
343
344 Reading the attribute will indicate a state of
345 that an update is in process. A zero indicate
346 completed or was never executed.
347
348 Vty-server entries in this directory are a 32
349 address that is created by firmware. An examp
350 looks like the following::
351
352 Pow5:/sys/bus/vio/drivers/hvcs/3000000
353 . current_vty devspec name
354 .. index partner_clcs vterm_
355
356 Each entry is provided, by default with a "nam
357 "name" attribute will reveal the device type a
358 example::
359
360 Pow5:/sys/bus/vio/drivers/hvcs/3000000
361 vty-server
362
363 Each entry is also provided, by default, with
364 reveals the full device specification when rea
365 example::
366
367 Pow5:/sys/bus/vio/drivers/hvcs/3000000
368 /vdevice/vty-server@30000004
369
370 Each vty-server sysfs dir is provided with two
371 provide lists of easily parsed partner vty dat
372 "partner_clcs"::
373
374 Pow5:/sys/bus/vio/drivers/hvcs/3000000
375 30000000
376 30000001
377 30000002
378 30000000
379 30000000
380
381 Pow5:/sys/bus/vio/drivers/hvcs/3000000
382 U5112.428.103048A-V3-C0
383 U5112.428.103048A-V3-C2
384 U5112.428.103048A-V3-C3
385 U5112.428.103048A-V4-C0
386 U5112.428.103048A-V5-C0
387
388 Reading partner_vtys returns a list of partner
389 numbering is only per-partition-unique so entr
390
391 Reading partner_clcs returns a list of "conver
392 composed of a system serial number followed by
393 target partition number, and "-C*", where the
394 adapter. The first vty partner corresponds to
395 second vty partner to the second clc item, etc
396
397 A vty-server can only be connected to a single
398 "current_vty" prints the clc of the currently
399 read.
400
401 The current_vty can be changed by writing a va
402 as in the following example::
403
404 Pow5:/sys/bus/vio/drivers/hvcs/3000000
405 8A-V4-C0 > current_vty
406
407 Changing the current_vty when a vty-server is
408 does not affect the current connection. The c
409 currently open connection is freed.
410
411 Information on the "vterm_state" attribute was
412 chapter entitled "disconnection".
413
414 8. Questions & Answers:
415 =======================
416
417 Q: What are the security concerns involving hv
418
419 A: There are three main security concerns:
420
421 1. The creator of the /dev/hvcs* nodes
422 the access of the device entries to ce
423 may be best to create a special hvcs g
424 access to system consoles.
425
426 2. To provide network security when gr
427 suggested that the user connect to the
428 using a secure method, such as SSH or
429
430 3. Make sure to exit the user session
431 the next vty-server connection (which
432 partition) will experience the previou
433
434 ----------------------------------------------
435
436 Q: How do I multiplex a console that I grab th
437 people can see it:
438
439 A: You can use "screen" to directly connect to
440 setup a session on your machine with the conso
441 pointed out earlier by default screen doesn't
442 for most terminal emulators to provide adequat
443 term type "screen" to others. This means that
444 not display properly in screen sessions.
445
446 ----------------------------------------------
447
448 Q: Why are the colors all messed up?
449 Q: Why are the control characters acting stran
450 Q: Why is the console output all strange and u
451
452 A: Please see the preceding section on "Connec
453 applications can affect the display of charact
454 Additionally, just because you logged into the
455 doesn't mean someone else didn't log into the
456 (vt320) before you and leave the session logge
457 is to export TERM to the terminal type of your
458 get the console. Additionally make sure to "e
459 disconnect from the console. This will ensure
460 their own TERM type set when they login.
461
462 ----------------------------------------------
463
464 Q: When I try to CONNECT kermit to an hvcs dev
465 "Sorry, can't open connection: /dev/hvcs*"What
466
467 A: Some other Power5 console mechanism has a c
468 isn't giving it up. You can try to force disc
469 HMC by right clicking on the partition and the
470 Otherwise you have to hunt down the people who
471 is possible that you already have the console
472 session and just forgot about it. Please revi
473 Power5 systems to determine the many ways a sy
474
475 OR
476
477 A: Another user may not have a connectivity me
478 /dev/hvcs device but the vterm_state may revea
479 vty-server connection established. They need
480 outlined in the section on "Disconnection" in
481 to the target vty.
482
483 OR
484
485 A: The user profile you are using to execute k
486 permissions to use the /dev/hvcs* device.
487
488 OR
489
490 A: You probably haven't inserted the hvcs.ko m
491 entry still exists (on systems without udev).
492
493 OR
494
495 A: There is not a corresponding vty-server dev
496 /dev/hvcs* entry.
497
498 ----------------------------------------------
499
500 Q: When I try to CONNECT kermit to an hvcs dev
501 "Sorry, write access to UUCP lockfile director
502
503 A: The /dev/hvcs* entry you have specified doe
504 does? Maybe you haven't inserted the module (
505
506 ----------------------------------------------
507
508 Q: If I already have one Linux partition insta
509 partition to provide the console for the insta
510 partition?
511
512 A: Yes granted that your are connected to the
513 kermit or cu or some other program that doesn'
514
515 ----------------------------------------------
516
517 Q: Can I connect to more than one partition's
518 driver?
519
520 A: Yes. Of course this means that there must
521 configured for this partition and each must po
522
523 ----------------------------------------------
524
525 Q: Does the hvcs driver support dynamic (hotpl
526
527 A: Yes, if you have dlpar and hotplug enabled
528 been built into the kernel the hvcs drivers is
529 handle additions of new devices and removals o
530
531 ----------------------------------------------
532
533 Q: For some reason /dev/hvcs* doesn't map to t
534 after a reboot. What happened?
535
536 A: Assignment of vty-server adapters to /dev/h
537 in the order that the adapters are exposed. D
538 this driver assignment of hotplug added vty-se
539 order than how they would be exposed on module
540 reloading the module after dynamic addition ma
541 and vty-server coupling changing if a vty-serv
542 slot between two other vty-server adapters. R
543 on how to determine which vty-server goes with
544 Hint; look at the sysfs "index" attribute for
545
546 ----------------------------------------------
547
548 Q: Can I use /dev/hvcs* as a conduit to anothe
549 device on that partition as the other end of t
550
551 A: Yes, on Power5 platforms the hvc_console dr
552 for extra /dev/hvc* devices (where /dev/hvc0 i
553 In order to get a tty conduit working between
554 Super Admin must create an additional "serial
555 partition with the HMC gui which will show up
556 partition is rebooted.
557
558 The HMC Super Admin then creates an additional
559 current partition and points this at the targe
560 "serial server" adapter (remember the slot).
561 additional /dev/hvcs* device.
562
563 Now a program on the target system can be conf
564 /dev/hvc* and another program on the current p
565 read or write to /dev/hvcs*. Now you have a t
566 partitions.
567
568 ----------------------------------------------
569
570 9. Reporting Bugs:
571 ==================
572
573 The proper channel for reporting bugs is eithe
574 distribution company that provided your OS or
575 PowerPC development mailing list at:
576
577 linuxppc-dev@lists.ozlabs.org
578
579 This request is to provide a documented and se
580 of the problems and solutions surrounding this
581 all users.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.