About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / powerpc / hvcs.txt




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:04 EST.

1	===========================================================================
2					   HVCS
3		IBM "Hypervisor Virtual Console Server" Installation Guide
4				  for Linux Kernel 2.6.4+
5			    Copyright (C) 2004 IBM Corporation
6	
7	===========================================================================
8	NOTE:Eight space tabs are the optimum editor setting for reading this file.
9	===========================================================================
10	
11		       Author(s) :  Ryan S. Arnold <rsa@us.ibm.com>
12			       Date Created: March, 02, 2004
13			       Last Changed: August, 24, 2004
14	
15	---------------------------------------------------------------------------
16	Table of contents:
17	
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:
29	
30	---------------------------------------------------------------------------
31	1. Driver Introduction:
32	
33	This 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
35	space applications access to the system consoles of logically partitioned
36	operating systems (Linux and AIX) running on the same partitioned Power5
37	ppc64 system.  Physical hardware consoles per partition are not practical
38	on this hardware so system consoles are accessed by this driver using
39	firmware interfaces to virtual terminal devices.
40	
41	---------------------------------------------------------------------------
42	2. System Requirements:
43	
44	This device driver was written using 2.6.4 Linux kernel APIs and will only
45	build and run on kernels of this version or later.
46	
47	This driver was written to operate solely on IBM Power5 ppc64 hardware
48	though some care was taken to abstract the architecture dependent firmware
49	calls from the driver code.
50	
51	Sysfs must be mounted on the system so that the user can determine which
52	major and minor numbers are associated with each vty-server.  Directions
53	for sysfs mounting are outside the scope of this document.
54	
55	---------------------------------------------------------------------------
56	3. Build Options:
57	
58	The hvcs driver registers itself as a tty driver.  The tty layer
59	dynamically allocates a block of major and minor numbers in a quantity
60	requested by the registering driver.  The hvcs driver asks the tty layer
61	for 64 of these major/minor numbers by default to use for hvcs device node
62	entries.
63	
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.
67	
68	---------------------------------------------------------------------------
69	3.1 Built-in:
70	
71	The following menuconfig example demonstrates selecting to build this
72	driver into the kernel.
73	
74		Device Drivers  --->
75			Character devices  --->
76				<*> IBM Hypervisor Virtual Console Server Support
77	
78	Begin the kernel make process.
79	
80	---------------------------------------------------------------------------
81	3.2 Module:
82	
83	The following menuconfig example demonstrates selecting to build this
84	driver as a kernel module.
85	
86		Device Drivers  --->
87			Character devices  --->
88				<M> IBM Hypervisor Virtual Console Server Support
89	
90	The make process will build the following kernel modules:
91	
92		hvcs.ko
93		hvcserver.ko
94	
95	To insert the module with the default allocation execute the following
96	commands in the order they appear:
97	
98		insmod hvcserver.ko
99		insmod hvcs.ko
100	
101	The hvcserver module contains architecture specific firmware calls and must
102	be inserted first, otherwise the hvcs module will not find some of the
103	symbols it expects.
104	
105	To override the default use an insmod parameter as follows (requesting 4
106	tty devices as an example):
107	
108		insmod hvcs.ko hvcs_parm_num_devs=4
109	
110	There is a maximum number of dev entries that can be specified on insmod.
111	We think that 1024 is currently a decent maximum number of server adapters
112	to allow.  This can always be changed by modifying the constant in the
113	source file before building.
114	
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.
117	
118	In order to remove the driver module execute the following command:
119	
120		rmmod hvcs.ko
121	
122	The recommended method for installing hvcs as a module is to use depmod to
123	build a current modules.dep file in /lib/modules/`uname -r` and then
124	execute:
125	
126	modprobe hvcs hvcs_parm_num_devs=4
127	
128	The modules.dep file indicates that hvcserver.ko needs to be inserted
129	before hvcs.ko and modprobe uses this file to smartly insert the modules in
130	the proper order.
131	
132	The following modprobe command is used to remove hvcs and hvcserver in the
133	proper order:
134	
135	modprobe -r hvcs
136	
137	---------------------------------------------------------------------------
138	4. Installation:
139	
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:
143	
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*
165	
166	For the above examples the following output is a result of cat'ing the
167	"dev" entry in the hvcs directory:
168	
169		Pow5:/sys/class/tty/hvcs0/ # cat dev
170		254:0
171	
172		Pow5:/sys/class/tty/hvcs1/ # cat dev
173		254:1
174	
175		Pow5:/sys/class/tty/hvcs2/ # cat dev
176		254:2
177	
178		Pow5:/sys/class/tty/hvcs3/ # cat dev
179		254:3
180	
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
184	will do it automatically.
185	
186	Given the example output above, to manually create a /dev/hvcs* node entry
187	mknod can be used as follows:
188	
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
193	
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.
196	
197	Attempting to connect an application to /dev/hvcs* prior to insertion of
198	the hvcs module will result in an error message similar to the following:
199	
200		"/dev/hvcs*: No such device".
201	
202	NOTE: Just because there is a device node present doesn't mean that there
203	is a vty-server device configured for that node.
204	
205	---------------------------------------------------------------------------
206	5. Connection
207	
208	Since this driver controls devices that provide a tty interface a user can
209	interact with the device node entries using any standard tty-interactive
210	method (e.g. "cat", "dd", "echo").  The intent of this driver however, is
211	to provide real time console interaction with a Linux partition's console,
212	which requires the use of applications that provide bi-directional,
213	interactive I/O with a tty device.
214	
215	Applications (e.g. "minicom" and "screen") that act as terminal emulators
216	or perform terminal type control sequence conversion on the data being
217	passed through them are NOT acceptable for providing interactive console
218	I/O.  These programs often emulate antiquated terminal types (vt100 and
219	ANSI) and expect inbound data to take the form of one of these supported
220	terminal types but they either do not convert, or do not _adequately_
221	convert, outbound data into the terminal type of the terminal which invoked
222	them (though screen makes an attempt and can apparently be configured with
223	much termcap wrestling.)
224	
225	For this reason kermit and cu are two of the recommended applications for
226	interacting with a Linux console via an hvcs device.  These programs simply
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
229	they cook outbound data to a particular terminal type.
230	
231	In order to ensure proper functioning of console applications one must make
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
238	control sequences that xterm can understand.
239	
240	As a precautionary measure an hvcs user should always "exit" from their
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.
245	
246	Hotplug add and remove of vty-server adapters affects which /dev/hvcs* node
247	is used to connect to each vty-server adapter.  In order to determine which
248	vty-server adapter is associated with which /dev/hvcs* node a special sysfs
249	attribute has been added to each vty-server sysfs entry.  This entry is
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.
253	
254		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat index
255		2
256	
257	This index of '2' means that in order to connect to vty-server adapter
258	30000004 the user should interact with /dev/hvcs2.
259	
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.
264	
265	---------------------------------------------------------------------------
266	6. Disconnection
267	
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
270	and discards that data when a connection between a vty-server and a vty has
271	been severed.  As an example, when a vty-server is immediately disconnected
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
275	disabled by firmware.
276	
277	When hvcs is being used to serve consoles this behavior is not a huge issue
278	because the adapter stays connected for large amounts of time following
279	almost all data writes.  When hvcs is being used as a tty conduit to tunnel
280	data between two partitions [see Q & A below] this is a huge problem
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
283	manually terminated vty-server connections on tty close this would close
284	the vty-server and vty connection before the target vty has had a chance to
285	fetch the data.
286	
287	Additionally, disconnecting a vty-server and vty only on module removal or
288	adapter removal is impractical because other vty-servers in other
289	partitions may require the usage of the target vty at any time.
290	
291	Due to this behavioral restriction disconnection of vty-servers from the
292	connected vty is a manual procedure using a write to a sysfs attribute
293	outlined below, on the other hand the initial vty-server connection to a
294	vty is established automatically by this driver.  Manual vty-server
295	connection is never required.
296	
297	In 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.
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
301	vty.  A one indicates that a connection is active.
302	
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.
309	
310		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
311		1
312	
313		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo 0 > vterm_state
314	
315		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat vterm_state
316		0
317	
318	All vty-server connections are automatically terminated when the device is
319	hotplug removed and when the module is removed.
320	
321	---------------------------------------------------------------------------
322	7. Configuration
323	
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:
327	
328		Pow5:/sys/bus/vio/drivers/hvcs # ls
329		.  ..  30000003  30000004  rescan
330	
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
337	explicit example follows:
338	
339		Pow5:/sys/bus/vio/drivers/hvcs # echo 1 > rescan
340	
341	Reading the attribute will indicate a state of '1' or '0'.  A one indicates
342	that an update is in process.  A zero indicates that an update has
343	completed or was never executed.
344	
345	Vty-server entries in this directory are a 32 bit partition unique unit
346	address that is created by firmware.  An example vty-server sysfs entry
347	looks like the following:
348	
349		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # ls
350		.   current_vty   devspec       name          partner_vtys
351		..  index         partner_clcs  vterm_state
352	
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
355	example:
356	
357		Pow5:/sys/bus/vio/drivers/hvcs/30000003 # cat name
358		vty-server
359	
360	Each entry is also provided, by default, with a "devspec" attribute which
361	reveals the full device specification when read, as shown in the following
362	example:
363	
364		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat devspec
365		/vdevice/vty-server@30000004
366	
367	Each vty-server sysfs dir is provided with two read-only attributes that
368	provide lists of easily parsed partner vty data: "partner_vtys" and
369	"partner_clcs".
370	
371		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # cat partner_vtys
372		30000000
373		30000001
374		30000002
375		30000000
376		30000000
377	
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
384	
385	Reading partner_vtys returns a list of partner vtys.  Vty unit address
386	numbering is only per-partition-unique so entries will frequently repeat.
387	
388	Reading partner_clcs returns a list of "converged location codes" which are
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.
393	
394	A 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
396	read.
397	
398	The current_vty can be changed by writing a valid partner clc to the entry
399	as in the following example:
400	
401		Pow5:/sys/bus/vio/drivers/hvcs/30000004 # echo U5112.428.10304
402		8A-V4-C0 > current_vty
403	
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
406	currently open connection is freed.
407	
408	Information on the "vterm_state" attribute was covered earlier on the
409	chapter entitled "disconnection".
410	
411	---------------------------------------------------------------------------
412	8. Questions & Answers:
413	===========================================================================
414	Q: What are the security concerns involving hvcs?
415	
416	A: There are three main security concerns:
417	
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.
422	
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.
426	
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.
430	
431	---------------------------------------------------------------------------
432	Q: How do I multiplex a console that I grab through hvcs so that other
433	people can see it:
434	
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
438	for most terminal emulators to provide adequate character conversion from
439	term type "screen" to others.  This means that curses based programs may
440	not display properly in screen sessions.
441	
442	---------------------------------------------------------------------------
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?
446	
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
455	their own TERM type set when they login.
456	
457	---------------------------------------------------------------------------
458	Q: When I try to CONNECT kermit to an hvcs device I get:
459	"Sorry, can't open connection: /dev/hvcs*"What is happening?
460	
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.
468	
469	OR
470	
471	A: 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
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.
476	
477	OR
478	
479	A: The user profile you are using to execute kermit probably doesn't have
480	permissions to use the /dev/hvcs* device.
481	
482	OR
483	
484	A: You probably haven't inserted the hvcs.ko module yet but the /dev/hvcs*
485	entry still exists (on systems without udev).
486	
487	OR
488	
489	A: There is not a corresponding vty-server device that maps to an existing
490	/dev/hvcs* entry.
491	
492	---------------------------------------------------------------------------
493	Q: When I try to CONNECT kermit to an hvcs device I get:
494	"Sorry, write access to UUCP lockfile directory denied."
495	
496	A: The /dev/hvcs* entry you have specified doesn't exist where you said it
497	does?  Maybe you haven't inserted the module (on systems with udev).
498	
499	---------------------------------------------------------------------------
500	Q: If I already have one Linux partition installed can I use hvcs on said
501	partition to provide the console for the install of a second Linux
502	partition?
503	
504	A: Yes granted that your are connected to the /dev/hvcs* device using
505	kermit or cu or some other program that doesn't provide terminal emulation.
506	
507	---------------------------------------------------------------------------
508	Q: Can I connect to more than one partition's console at a time using this
509	driver?
510	
511	A: Yes.  Of course this means that there must be more than one vty-server
512	configured for this partition and each must point to a disconnected vty.
513	
514	---------------------------------------------------------------------------
515	Q: Does the hvcs driver support dynamic (hotplug) addition of devices?
516	
517	A: Yes, if you have dlpar and hotplug enabled for your system and it has
518	been built into the kernel the hvcs drivers is configured to dynamically
519	handle additions of new devices and removals of unused devices.
520	
521	---------------------------------------------------------------------------
522	Q: For some reason /dev/hvcs* doesn't map to the same vty-server adapter
523	after a reboot.  What happened?
524	
525	A: Assignment of vty-server adapters to /dev/hvcs* entries is always done
526	in the order that the adapters are exposed.  Due to hotplug capabilities of
527	this driver assignment of hotplug added vty-servers may be in a different
528	order than how they would be exposed on module load.  Rebooting or
529	reloading the module after dynamic addition may result in the /dev/hvcs*
530	and vty-server coupling changing if a vty-server adapter was added in a
531	slot between two other vty-server adapters.  Refer to the section above
532	on how to determine which vty-server goes with which /dev/hvcs* node.
533	Hint; look at the sysfs "index" attribute for the vty-server.
534	
535	---------------------------------------------------------------------------
536	Q: Can I use /dev/hvcs* as a conduit to another partition and use a tty
537	device on that partition as the other end of the pipe?
538	
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
544	partition is rebooted.
545	
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
549	additional /dev/hvcs* device.
550	
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
553	read or write to /dev/hvcs*.  Now you have a tty conduit between two
554	partitions.
555	
556	---------------------------------------------------------------------------
557	9. Reporting Bugs:
558	
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
561	PowerPC development mailing list at:
562	
563	linuxppc-dev@lists.ozlabs.org
564	
565	This request is to provide a documented and searchable public exchange
566	of the problems and solutions surrounding this driver for the benefit of
567	all users.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.