[PATCH] Documentation/serial-console: Document the behavior when the last console= parameter is not used

[Petr Mladek]

The console= kernel command-line parameter defines where the kernel
messages appear. It can be used multiple times to make the kernel log
visible on more devices.

The ordering of the console= parameters is important. In particular,
the last one defines which device can be accessed also via /dev/console.

The behavior is more complicated when the last console= parameter is
ignored by kernel. It might be surprising because it was not intentional.
The kernel just works this way historically.

There were few attempts to change the behavior. Unfortunately, it can't
be done because it would break existing users. Document the historical
behavior at least.

Link: https://lore.kernel.org/r/20170606143149.GB7604@xxxxxxxxxxxxxxx
Link: https://lore.kernel.org/r/20230213113912.1237943-1-rkanwal@xxxxxxxxxxxx
Signed-off-by: Petr Mladek <pmladek@xxxxxxxx>
---
 Documentation/admin-guide/serial-console.rst | 36 ++++++++++++++++++--
 1 file changed, 33 insertions(+), 3 deletions(-)

diff --git a/Documentation/admin-guide/serial-console.rst b/Documentation/admin-guide/serial-console.rst
index 58b32832e50a..8c8b94e54e26 100644
--- a/Documentation/admin-guide/serial-console.rst
+++ b/Documentation/admin-guide/serial-console.rst
@@ -33,8 +33,11 @@ The format of this option is::
 			9600n8. The maximum baudrate is 115200.
 
 You can specify multiple console= options on the kernel command line.
-Output will appear on all of them. The last device will be used when
-you open ``/dev/console``. So, for example::
+
+The behavior is well defined when each device type is mentioned only once.
+In this case, the output will appear on all requested consoles. And
+the last device will be used when you open ``/dev/console``.
+So, for example::
 
 	console=ttyS1,9600 console=tty0
 
@@ -42,7 +45,34 @@ defines that opening ``/dev/console`` will get you the current foreground
 virtual console, and kernel messages will appear on both the VGA
 console and the 2nd serial port (ttyS1 or COM2) at 9600 baud.
 
-Note that you can only define one console per device type (serial, video).
+The behavior is more complicated when the same device type is defined more
+times. In this case, there are the following two rules:
+
+1. The output will appear only on the first device of each defined type.
+
+2. ``/dev/console`` will be associated with the first registered device.
+   Where the registration order depends on how kernel initializes various
+   subsystems.
+
+   This rule is used also when the last console= parameter is not used
+   for other reasons. For example, because of a typo or because
+   the hardware is not available.
+
+The result might be surprising. For example, the following two command
+lines have the same result:
+
+	console=ttyS1,9600 console=tty0 console=tty1
+	console=tty0 console=ttyS1,9600 console=tty1
+
+The kernel messages are printed only on ``tty0`` and ``ttyS1``. And
+``/dev/console`` gets associated with ``tty0``. It is because kernel
+tries to register graphical consoles before serial ones. It does it
+because of the default behavior when no console device is specified,
+see below.
+
+Note that the last ``console=tty1`` parameter still makes a difference.
+The kernel command line is used also by systemd. It would use the last
+defined ``tty1`` as the login console.
 
 If no console device is specified, the first device found capable of
 acting as a system console will be used. At this time, the system
-- 
2.35.3