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