blob: 044240db3fc793e6fee6ec9a2b6743063d39c21c [file] [log] [blame]
Gary Jennejohn16a28ef2008-11-06 15:04:23 +01001/*
2 * (C) Copyright 2008
3 * Gary Jennejohn, DENX Software Engineering GmbH <garyj@denx.de>
4 *
Wolfgang Denk1a459662013-07-08 09:37:19 +02005 * SPDX-License-Identifier: GPL-2.0+
Gary Jennejohn16a28ef2008-11-06 15:04:23 +01006 */
7
8U-Boot console multiplexing
9===========================
10
11HOW CONSOLE MULTIPLEXING WORKS
12------------------------------
13
14This functionality is controlled with CONFIG_CONSOLE_MUX in the board
15configuration file.
16
17Two new files, common/iomux.c and include/iomux.h, contain the heart
18(iomux_doenv()) of the environment setting implementation.
19
20iomux_doenv() is called in common/cmd_nvedit.c to handle setenv and in
21common/console.c in console_init_r() during bootup to initialize
22stdio_devices[].
23
24A user can use a comma-separated list of devices to set stdin, stdout
25and stderr. For example: "setenv stdin serial,nc". NOTE: No spaces
26are allowed around the comma(s)!
27
28The length of the list is limited by malloc(), since the array used
29is allocated and freed dynamically.
30
31It should be possible to specify any device which console_assign()
32finds acceptable, but the code has only been tested with serial and
33nc.
34
35iomux_doenv() prevents multiple use of the same device, e.g. "setenv
36stdin nc,nc,serial" will discard the second nc. iomux_doenv() is
37not able to modify the environment, however, so that "pri stdin" still
38shows "nc,nc,serial".
39
40The major change in common/console.c was to modify fgetc() to call
41the iomux_tstc() routine in a for-loop. iomux_tstc() in turn calls
42the tstc() routine for every registered device, but exits immediately
43when one of them returns true. fgetc() then calls iomux_getc(),
44which calls the corresponding getc() routine. fgetc() hangs in
45the for-loop until iomux_tstc() returns true and the input can be
46retrieved.
47
48Thus, a user can type into any device registered for stdin. No effort
49has been made to demulitplex simultaneous input from multiple stdin
50devices.
51
52fputc() and fputs() have been modified to call iomux_putc() and
53iomux_puts() respectively, which call the corresponding output
54routines for every registered device.
55
56Thus, a user can see the ouput for any device registered for stdout
57or stderr on all devices registered for stdout or stderr. As an
58example, if stdin=serial,nc and stdout=serial,nc then all output
59for serial, e.g. echos of input on serial, will appear on serial and nc.
60
61Just as with the old console code, this statement is still true:
62If not defined in the environment, the first input device is assigned
63to the 'stdin' file, the first output one to 'stdout' and 'stderr'.
64
65If CONFIG_SYS_CONSOLE_IS_IN_ENV is defined then multiple input/output
66devices can be set at boot time if defined in the environment.
67
68CAVEATS
69-------
70
71Note that common/iomux.c calls console_assign() for every registered
72device as it is discovered. This means that the environment settings
73for application consoles will be set to the last device in the list.
74
75On a slow machine, such as MPC852T clocked at 66MHz, the overhead associated
76with calling tstc() and then getc() means that copy&paste will normally not
77work, even when stdin=stdout=stderr=serial.
78On a faster machine, such as a sequoia, cut&paste of longer (about 80
79characters) lines works fine when serial is the only device used.
80
81Using nc as a stdin device results in even more overhead because nc_tstc()
82is quite slow. Even on a sequoia cut&paste does not work on the serial
83interface when nc is added to stdin, although there is no character loss using
84the ethernet interface for input. In this test case stdin=serial,nc and
85stdout=serial.
86
87In addition, the overhead associated with sending to two devices, when one of
88them is nc, also causes problems. Even on a sequoia cut&paste does not work
89on the serial interface (stdin=serial) when nc is added to stdout (stdout=
90serial,nc).