1# Mux Support 2 3In some hardware designs, multiple UARTS may be available behind a Mux, which 4requires obmc-console to select one at a time. 5 6For example, let's say behind `/dev/ttyS0` there are `UART1` and `UART2`, behind 7a mux. GPIO `UART-MUX-CTL` can be used to select one. This scenario is shown in 8the [Example Diagram](#example-diagram) 9 10Then there will be one obmc-console-server process, and 2 consoles will be 11created in this server process. 12 13The obmc-console-server will receive configuration for both consoles detailing 14the gpios to be used to control the mux and the values they should have when 15they are active. 16 17The implementation documented here has been made based on the 18[design document](https://github.com/openbmc/docs/blob/master/designs/uart-mux-support.md) 19 20## Userspace Implementation 21 22The kernel will not be aware of this mux and the support can be implemented in 23userspace. 24 25Reasons for this are that the hardware this is for is not static (blade server) 26and thus cannot be represented by devicetree. Also, it is unclear how the 27virtual uart should notify a process that the mux state has changed. 28 29When a userspace implementation is available for reference, this may later pave 30the way for a kernel implementation if someone wants to do that. 31 32## Configuration Example 33 34The configuration is similar to i2c-mux-gpio in the linux kernel. 35 36The order of GPIOs listed in 'mux-gpios' forms the LSB-first bit representation 37of an N-bit number that is taken from 'mux-index'. 38 39For declaring the different consoles, the section name, e.g. `[host1]` must be 40the same as the console-id. All of the section names need to be unique. 41 42```sh 43$ cat server.conf 44mux-gpios = MUX_CTL 45 46[host1] 47mux-index = 0 48logfile = /var/log/console-host1.log 49 50[host2] 51mux-index = 1 52logfile = /var/log/console-host2.log 53``` 54 55Now the server can be started. See the [Dbus Interface](#dbus-interface-example) 56and [Example Diagram](#example-diagram) 57 58```sh 59obmc-console-server --config server.conf /dev/ttyS0 60``` 61 62## Mux Control 63 64Mux Control happens implicitly via connections. When a client connects to a 65console, the new connection is accepted and the console-server switches the mux 66to this console. Any clients connected to other consoles are disconnected. 67 68### Mux Control - Example 69 70```sh 71$ obmc-console-client -i host2 & 72[1] 3422 73$ obmc-console-client -i host1 74``` 75 76Connecting to console 'host1' will cause console 'host2' to: 77 781. stop forwarding bytes 792. print a log message to its clients, if the server was connected before, see 80 [Mux Control Log](#mux-control-log) 81 82Then the following happens for console 'host1': 83 841. switch the mux using the gpios 852. print a log message to its clients, if the server was disconnected before, 86 see [Mux Control Log](#mux-control-log) 873. start forwarding bytes. 88 89## Mux Control Log 90 91Whenever the mux is switched, there should be a way for people reading the log 92to know that that console was (dis)connected, and at which time. Otherwise there 93may be confusion as to why there is a gap in the logs. 94 95So obmc-console-server will print one of these messages to all clients: 96 97```sh 98[obmc-console] %Y-%m-%d %H:%M:%S UTC CONNECTED 99``` 100 101```sh 102[obmc-console] %Y-%m-%d %H:%M:%S UTC DISCONNECTED 103``` 104 105### Mux Control Log Disclaimer 106 107Note that this log message is not a reliable source of information, and is only 108provided as a convenience feature. This same log message could be printed by 109anything that's connected to the uart on the other side. 110 111The exact format of this log message is not fixed and could change. 112 113## Dbus Interface Example 114 115```sh 116$ busctl list 117... 118xyz.openbmc_project.Console.host1 926 obmc-console-server root ... 119xyz.openbmc_project.Console.host2 926 obmc-console-server root ... 120... 121``` 122 123```sh 124$ busctl tree xyz.openbmc_project.Console.host2 125└─ /xyz 126 └─ /xyz/openbmc_project 127 └─ /xyz/openbmc_project/console 128 └─ /xyz/openbmc_project/console/host1 129 └─ /xyz/openbmc_project/console/host2 130 131$ busctl tree xyz.openbmc_project.Console.host1 132└─ /xyz 133 └─ /xyz/openbmc_project 134 └─ /xyz/openbmc_project/console 135 └─ /xyz/openbmc_project/console/host1 136 └─ /xyz/openbmc_project/console/host2 137``` 138 139```sh 140$ busctl introspect xyz.openbmc_project.Console.host1 /xyz/openbmc_project/console/host1 141NAME TYPE SIGNATURE RESULT/VALUE FLAGS 142org.freedesktop.DBus.Introspectable interface - - - 143.Introspect method - s - 144org.freedesktop.DBus.Peer interface - - - 145.GetMachineId method - s - 146.Ping method - - - 147org.freedesktop.DBus.Properties interface - - - 148.Get method ss v - 149.GetAll method s a{sv} - 150.Set method ssv - - 151.PropertiesChanged signal sa{sv}as - - 152xyz.openbmc_project.Console.Access interface - - - 153.Connect method - h - 154``` 155 156## Example Diagram 157 158```text 159 +--------------------+ 160 | server.conf | 161 +--------------------+ 162 | 163 | 164 | 165 | 166 +----+----+ +-----+ +-------+ 167 | | | | | | 168 | | +-------+ +-------+ | +-----+ UART1 | 169+-----------------------------------+ | | | | | | | | | | 170| xyz.openbmc_project.Console.host1 +-----+ +-----+ ttyS0 +-----+ UART0 +-----+ | +-------+ 171+-----------------------------------+ | | | | | | | | 172 | obmc | +-------+ +-------+ | | 173 | console | | MUX | 174 | server | +-------+ | | 175+-----------------------------------+ | | | | | | 176| xyz.openbmc_project.Console.host2 +-----+ +-------------------+ GPIO +-----+ | +-------+ 177+-----------------------------------+ | | | | | | | | 178 | | +-------+ | +-----+ UART2 | 179 | | | | | | 180 +----+----+ +-----+ +-------+ 181 182``` 183