1 files changed, 144 insertions, 0 deletions
diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.txt
new file mode 100644
index 000000000000..f51eb4bc2ff1
--- /dev/null
+++ b/Documentation/ia64/serial.txt
@@ -0,0 +1,144 @@
+SERIAL DEVICE NAMING
+    As of 2.6.10, serial devices on ia64 are named based on the
+    order of ACPI and PCI enumeration.  The first device in the
+    ACPI namespace (if any) becomes /dev/ttyS0, the second becomes
+    /dev/ttyS1, etc., and PCI devices are named sequentially
+    starting after the ACPI devices.
+    Prior to 2.6.10, there were confusing exceptions to this:
+        - Firmware on some machines (mostly from HP) provides an HCDP
+          table[1] that tells the kernel about devices that can be used
+          as a serial console.  If the user specified "console=ttyS0"
+          or the EFI ConOut path contained only UART devices, the
+          kernel registered the device described by the HCDP as
+          /dev/ttyS0.
+        - If there was no HCDP, we assumed there were UARTs at the
+          legacy COM port addresses (I/O ports 0x3f8 and 0x2f8), so
+          the kernel registered those as /dev/ttyS0 and /dev/ttyS1.
+    Any additional ACPI or PCI devices were registered sequentially
+    after /dev/ttyS0 as they were discovered.
+    With an HCDP, device names changed depending on EFI configuration
+    and "console=" arguments.  Without an HCDP, device names didn't
+    change, but we registered devices that might not really exist.
+    For example, an HP rx1600 with a single built-in serial port
+    (described in the ACPI namespace) plus an MP[2] (a PCI device) has
+    these ports:
+                                  pre-2.6.10      pre-2.6.10
+                    MMIO         (EFI console    (EFI console
+                   address        on builtin)     on MP port)    2.6.10
+                  ==========      ==========      ==========     ======
+      builtin     0xff5e0000        ttyS0           ttyS1         ttyS0
+      MP UPS      0xf8031000        ttyS1           ttyS2         ttyS1
+      MP Console  0xf8030000        ttyS2           ttyS0         ttyS2
+      MP 2        0xf8030010        ttyS3           ttyS3         ttyS3
+      MP 3        0xf8030038        ttyS4           ttyS4         ttyS4
+CONSOLE SELECTION
+    EFI knows what your console devices are, but it doesn't tell the
+    kernel quite enough to actually locate them.  The DIG64 HCDP
+    table[1] does tell the kernel where potential serial console
+    devices are, but not all firmware supplies it.  Also, EFI supports
+    multiple simultaneous consoles and doesn't tell the kernel which
+    should be the "primary" one.
+    So how do you tell Linux which console device to use?
+        - If your firmware supplies the HCDP, it is simplest to
+          configure EFI with a single device (either a UART or a VGA
+          card) as the console.  Then you don't need to tell Linux
+          anything; the kernel will automatically use the EFI console.
+          (This works only in 2.6.6 or later; prior to that you had
+          to specify "console=ttyS0" to get a serial console.)
+        - Without an HCDP, Linux defaults to a VGA console unless you
+          specify a "console=" argument.
+    NOTE: Don't assume that a serial console device will be /dev/ttyS0.
+    It might be ttyS1, ttyS2, etc.  Make sure you have the appropriate
+    entries in /etc/inittab (for getty) and /etc/securetty (to allow
+    root login).
+EARLY SERIAL CONSOLE
+    The kernel can't start using a serial console until it knows where
+    the device lives.  Normally this happens when the driver enumerates
+    all the serial devices, which can happen a minute or more after the
+    kernel starts booting.
+    2.6.10 and later kernels have an "early uart" driver that works
+    very early in the boot process.  The kernel will automatically use
+    this if the user supplies an argument like "console=uart,io,0x3f8",
+    or if the EFI console path contains only a UART device and the
+    firmware supplies an HCDP.
+TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
+    No kernel output after elilo prints "Uncompressing Linux... done":
+        - You specified "console=ttyS0" but Linux changed the device
+          to which ttyS0 refers.  Configure exactly one EFI console
+          device[3] and remove the "console=" option.
+        - The EFI console path contains both a VGA device and a UART.
+          EFI and elilo use both, but Linux defaults to VGA.  Remove
+          the VGA device from the EFI console path[3].
+        - Multiple UARTs selected as EFI console devices.  EFI and
+          elilo use all selected devices, but Linux uses only one.
+          Make sure only one UART is selected in the EFI console
+          path[3].
+        - You're connected to an HP MP port[2] but have a non-MP UART
+          selected as EFI console device.  EFI uses the MP as a
+          console device even when it isn't explicitly selected.
+          Either move the console cable to the non-MP UART, or change
+          the EFI console path[3] to the MP UART.
+    Long pause (60+ seconds) between "Uncompressing Linux... done" and
+    start of kernel output:
+        - No early console because you used "console=ttyS<n>".  Remove
+          the "console=" option if your firmware supplies an HCDP.
+        - If you don't have an HCDP, the kernel doesn't know where
+          your console lives until the driver discovers serial
+          devices.  Use "console=uart, io,0x3f8" (or appropriate
+          address for your machine).
+    Kernel and init script output works fine, but no "login:" prompt:
+        - Add getty entry to /etc/inittab for console tty.  Look for
+          the "Adding console on ttyS<n>" message that tells you which
+          device is the console.
+    "login:" prompt, but can't login as root:
+        - Add entry to /etc/securetty for console tty.
+[1] http://www.dig64.org/specifications/DIG64_PCDPv20.pdf
+    The table was originally defined as the "HCDP" for "Headless
+    Console/Debug Port."  The current version is the "PCDP" for
+    "Primary Console and Debug Port Devices."
+[2] The HP MP (management processor) is a PCI device that provides
+    several UARTs.  One of the UARTs is often used as a console; the
+    EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart".
+    The external connection is usually a 25-pin connector, and a
+    special dongle converts that to three 9-pin connectors, one of
+    which is labelled "Console."
+[3] EFI console devices are configured using the EFI Boot Manager
+    "Boot option maintenance" menu.  You may have to interrupt the
+    boot sequence to use this menu, and you will have to reset the
+    box after changing console configuration.

diff --git a/Documentation/ia64/serial.txt b/Documentation/ia64/serial.txt new file mode 100644 index 000000000000..f51eb4bc2ff1 --- /dev/null +++ b/Documentation/ia64/serial.txt
@@ -0,0 +1,144 @@
	1	SERIAL DEVICE NAMING
	2
	3	As of 2.6.10, serial devices on ia64 are named based on the
	4	order of ACPI and PCI enumeration. The first device in the
	5	ACPI namespace (if any) becomes /dev/ttyS0, the second becomes
	6	/dev/ttyS1, etc., and PCI devices are named sequentially
	7	starting after the ACPI devices.
	8
	9	Prior to 2.6.10, there were confusing exceptions to this:
	10
	11	- Firmware on some machines (mostly from HP) provides an HCDP
	12	table[1] that tells the kernel about devices that can be used
	13	as a serial console. If the user specified "console=ttyS0"
	14	or the EFI ConOut path contained only UART devices, the
	15	kernel registered the device described by the HCDP as
	16	/dev/ttyS0.
	17
	18	- If there was no HCDP, we assumed there were UARTs at the
	19	legacy COM port addresses (I/O ports 0x3f8 and 0x2f8), so
	20	the kernel registered those as /dev/ttyS0 and /dev/ttyS1.
	21
	22	Any additional ACPI or PCI devices were registered sequentially
	23	after /dev/ttyS0 as they were discovered.
	24
	25	With an HCDP, device names changed depending on EFI configuration
	26	and "console=" arguments. Without an HCDP, device names didn't
	27	change, but we registered devices that might not really exist.
	28
	29	For example, an HP rx1600 with a single built-in serial port
	30	(described in the ACPI namespace) plus an MP[2] (a PCI device) has
	31	these ports:
	32
	33	pre-2.6.10 pre-2.6.10
	34	MMIO (EFI console (EFI console
	35	address on builtin) on MP port) 2.6.10
	36	========== ========== ========== ======
	37	builtin 0xff5e0000 ttyS0 ttyS1 ttyS0
	38	MP UPS 0xf8031000 ttyS1 ttyS2 ttyS1
	39	MP Console 0xf8030000 ttyS2 ttyS0 ttyS2
	40	MP 2 0xf8030010 ttyS3 ttyS3 ttyS3
	41	MP 3 0xf8030038 ttyS4 ttyS4 ttyS4
	42
	43	CONSOLE SELECTION
	44
	45	EFI knows what your console devices are, but it doesn't tell the
	46	kernel quite enough to actually locate them. The DIG64 HCDP
	47	table[1] does tell the kernel where potential serial console
	48	devices are, but not all firmware supplies it. Also, EFI supports
	49	multiple simultaneous consoles and doesn't tell the kernel which
	50	should be the "primary" one.
	51
	52	So how do you tell Linux which console device to use?
	53
	54	- If your firmware supplies the HCDP, it is simplest to
	55	configure EFI with a single device (either a UART or a VGA
	56	card) as the console. Then you don't need to tell Linux
	57	anything; the kernel will automatically use the EFI console.
	58
	59	(This works only in 2.6.6 or later; prior to that you had
	60	to specify "console=ttyS0" to get a serial console.)
	61
	62	- Without an HCDP, Linux defaults to a VGA console unless you
	63	specify a "console=" argument.
	64
	65	NOTE: Don't assume that a serial console device will be /dev/ttyS0.
	66	It might be ttyS1, ttyS2, etc. Make sure you have the appropriate
	67	entries in /etc/inittab (for getty) and /etc/securetty (to allow
	68	root login).
	69
	70	EARLY SERIAL CONSOLE
	71
	72	The kernel can't start using a serial console until it knows where
	73	the device lives. Normally this happens when the driver enumerates
	74	all the serial devices, which can happen a minute or more after the
	75	kernel starts booting.
	76
	77	2.6.10 and later kernels have an "early uart" driver that works
	78	very early in the boot process. The kernel will automatically use
	79	this if the user supplies an argument like "console=uart,io,0x3f8",
	80	or if the EFI console path contains only a UART device and the
	81	firmware supplies an HCDP.
	82
	83	TROUBLESHOOTING SERIAL CONSOLE PROBLEMS
	84
	85	No kernel output after elilo prints "Uncompressing Linux... done":
	86
	87	- You specified "console=ttyS0" but Linux changed the device
	88	to which ttyS0 refers. Configure exactly one EFI console
	89	device[3] and remove the "console=" option.
	90
	91	- The EFI console path contains both a VGA device and a UART.
	92	EFI and elilo use both, but Linux defaults to VGA. Remove
	93	the VGA device from the EFI console path[3].
	94
	95	- Multiple UARTs selected as EFI console devices. EFI and
	96	elilo use all selected devices, but Linux uses only one.
	97	Make sure only one UART is selected in the EFI console
	98	path[3].
	99
	100	- You're connected to an HP MP port[2] but have a non-MP UART
	101	selected as EFI console device. EFI uses the MP as a
	102	console device even when it isn't explicitly selected.
	103	Either move the console cable to the non-MP UART, or change
	104	the EFI console path[3] to the MP UART.
	105
	106	Long pause (60+ seconds) between "Uncompressing Linux... done" and
	107	start of kernel output:
	108
	109	- No early console because you used "console=ttyS<n>". Remove
	110	the "console=" option if your firmware supplies an HCDP.
	111
	112	- If you don't have an HCDP, the kernel doesn't know where
	113	your console lives until the driver discovers serial
	114	devices. Use "console=uart, io,0x3f8" (or appropriate
	115	address for your machine).
	116
	117	Kernel and init script output works fine, but no "login:" prompt:
	118
	119	- Add getty entry to /etc/inittab for console tty. Look for
	120	the "Adding console on ttyS<n>" message that tells you which
	121	device is the console.
	122
	123	"login:" prompt, but can't login as root:
	124
	125	- Add entry to /etc/securetty for console tty.
	126
	127
	128
	129	[1] http://www.dig64.org/specifications/DIG64_PCDPv20.pdf
	130	The table was originally defined as the "HCDP" for "Headless
	131	Console/Debug Port." The current version is the "PCDP" for
	132	"Primary Console and Debug Port Devices."
	133
	134	[2] The HP MP (management processor) is a PCI device that provides
	135	several UARTs. One of the UARTs is often used as a console; the
	136	EFI Boot Manager identifies it as "Acpi(HWP0002,700)/Pci(...)/Uart".
	137	The external connection is usually a 25-pin connector, and a
	138	special dongle converts that to three 9-pin connectors, one of
	139	which is labelled "Console."
	140
	141	[3] EFI console devices are configured using the EFI Boot Manager
	142	"Boot option maintenance" menu. You may have to interrupt the
	143	boot sequence to use this menu, and you will have to reset the
	144	box after changing console configuration.