Lines Matching +full:mux +full:-
1 # uart-mux-support design
12 Some hardware configurations feature a UART mux which can be switched via GPIOs.
13 To support this configuration, obmc-console needs to provide a method for
18 There are already [open changes for obmc-console][obmc-console-uart-mux-series]
21 [obmc-console-uart-mux-series]:
22 https://gerrit.openbmc.org/c/openbmc/obmc-console/+/71864
25 subprojects - not in the way of causing regression, but later when the mentioned
30 - The user can select a console to be muxed
32 - Platform policy (whichever service implements it) can select the appropriate
35 - It is clear to whoever is reading the logs of that console when a console was
36 connected or disconnected via mux control. There should be no inexplicable
39 - The mux configuration can be specified in a single file
41 - Console selection (implies mux control) must be possible from an external
44 The scope of this change is obmc-console and other projects which rely on the
51 There are a number of choices available for adding mux support into
52 obmc-console:
54 1. What the "connection endpoint" (Unix domain socket, D-Bus object) represents.
58 2. The desired downstream mux port
60 2. How the mux state is controlled. We might control it by any of:
62 1. An out-of-band command (e.g. via a D-Bus method that's somehow associated
64 2. An in-band command (e.g. introducing an SSH-style escape-sequence)
65 3. Selecting the mux port based on the endpoint to which the user has
68 3. The circumstances under which we allow the mux state to be changed
70 1. Active connections prevent the mux state from being changed
71 2. The mux state can always change but will terminate any existing
73 3. The mux state can always change and has no impact on existing conflicting
77 1. The console IO regardless of the mux state
78 2. The console IO isolated to a specific mux port
82 - If the connection endpoint represents the TTY device exposed by Linux (1.1)
83 then we can't select the mux port based on the endpoint to which the user has
86 - If the connection endpoint represents the desired downstream mux port (1.2)
87 then it doesn't make sense to implement support for an in-band command to
88 change the mux state (2.2) as it's a violation of the abstraction
90 - If the connection endpoint represents the desired downstream mux port (1.2)
91 then it can't provide the console IO of another mux port (4.1) as that's
96 | ID | Connection Endpoint (1) | Mux Control Defined By (2) | Mux Control Policy (3) …
97 | --- | ----------------------- | -------------------------- | ------------------------------------…
98 | A | TTY (1.1) | Out-of-band command (2.1) | Active connections prevent mux chang…
99 | B | TTY | Out-of-band command | Mux change with disconnections (3.2)…
100 | C | TTY | Out-of-band command | Mux change without disconnections (3…
101 | D | TTY | In-band command (2.2) | Mux change without disconnections …
102 | E | Mux port (1.2) | Connection-based (2.3) | Conflicting connections prevent mux …
103 | F | Mux port | Connection-based | Mux change with disconnections …
104 | G | Mux port | Connection-based | Mux change without disconnections …
105 | H | Mux port | Out-of-band command | Conflicting connections prevent mux …
106 | I | Mux port | Out-of-band command | Mux change with disconnections …
107 | J | Mux port | Out-of-band command | Mux change without disconnections …
111 1. A UART mux selecting between a satellite BMC on a blade and the blade host
113 A software update is in progress on the satellite BMC and the mux has been
122 mux, and relevant output from the blade's boot process must be captured
134 the mux state. In the scenario the system is in a sensitive state where a
135 specific mux configuration is required (to output update progress from the
139 What should occur? And does this choice impact how we choose to control the mux?
141 Taking a connection-based approach to setting the mux state (2.3) will cause the
145 By contrast, by setting the mux state with an out-of-band command (2.1) and not
150 a reason. With extra actions, using the out-of-band command interface, they may
151 equally choose to switch the mux without regard for the system state, disrupting
158 Should it be the responsibility of obmc-console to coordinate otherwise
159 un-coordinated users?
166 obmc-console should implement a mechanism to control the mux state, but likely
169 A further concern for the out-of-band command approach is its interactions with
172 1. The dropbear/obmc-console-client integration exposing consoles via SSH
174 3. [phosphor-net-ipmid](https://github.com/openbmc/phosphor-net-ipmid/blob/master/sol/sol_manager.h…
176 With the out-of-band command approach these components have to choose between:
178 - Not providing any capability to change the mux state; rather, they defer to
181 - Expose some mechanism for setting the mux state in terms of their own external
184 - Assume that a user connecting to the exposed console endpoint wants to select
185 that console if it's behind a mux
196 the out-of-band command interface when they receive a connection for a given
197 console. The net result is no behavioural difference from obmc-console
202 ### How are muxed consoles represented on D-Bus?
204 Every console will have its own D-Bus name, as this is backwards-compatible with
207 Multiple consoles can be represented as a split- or unified- object tree.
209 ### Tradeoffs of unified vs split object tree on D-Bus
211 In split-tree, it is not clear which consoles all belong to one UART mux, but in
212 unified-tree, this is clear.
214 In unified-tree, one console is reachable via the D-Bus name of another,
220 busctl set-property xyz.openbmc_project.Console.host1 \
231 busctl tree --user xyz.openbmc_project.Console.host1
242 busctl tree --user xyz.openbmc_project.Console.host1
248 busctl tree --user xyz.openbmc_project.Console.host2
255 The choice of representation impacts how the mux can be described on D-Bus,
256 which is necessary if the out-of-band command strategy (2.1) is chosen. Two
257 possibilities for exposing an out-of-band mux control on D-Bus are:
262 switch the mux without requiring caller-supplied parameters. The `Activate`
263 property is `true` when the mux is configured for the console of interest,
264 and `false` otherwise. A `PropertiesChanged` D-Bus signal for the `Active`
265 variable may alert local users to changes of mux state.
267 2. Implement a `Mux` interface on an object common to all consoles exposed by
268 the mux. The `Mux` interface might have a writable string `Selected` property
269 that represents the state of the mux and provides a mechanism to switch it to
273 phosphor-dbus-interfaces][pdi-uart-mux-control-interface].
275 [pdi-uart-mux-control-interface]:
276 https://gerrit.openbmc.org/c/openbmc/phosphor-dbus-interfaces/+/71878/comment/dd34b099_66dbc49e/
278 The second approach is quite explicit - directly representing the mux state
281 `Mux` interface (e.g. at `/xyz/openbmc_project/console`). This is desired to
284 unified object tree: If the tree isn't unified, this `Mux` interface would have
285 to be represented and synchronised on objects across multiple D-Bus connections.
288 trade-off previously mentioned, that it's unclear how any of the consoles in the
291 Choosing a strategy for D-Bus representation is required if we add to the D-Bus
292 API, i.e. with the out-of-band command design point (2.1). However, the choice
299 To help shape the choices here, we have the existing behaviours of obmc-console
300 [discussed on the PDI patch][pdi-uart-mux-control-interface]:
304 2. Concurrent console support is implemented as one obmc-console-server process
307 3. As each Linux TTY device is paired with its obmc-console-server process, each
308 obmc-console-server D-Bus connection needs a unique name
310 4. We use the unique console-ids to name global resources, including both the
311 D-Bus connection and the instance's unix domain socket.
313 As in the linked discussion, given the `console-id` value really represents
316 Taking this approach avoids adding a new endpoint ABI to obmc-console and
317 eliminates design options A-D inclusive.
320 connections, preventing mux changes on the grounds of an existing connection
324 differentiated by how the mux is switched, and its effect on already-connected
327 Concentrating on how the mux is switched, based on the discussion about the
328 D-Bus representation above, the discussion on the PDI patch, and the impact on
330 the out-of-band command method (2.1).
332 By contrast we can consider the alternative: We make the mux state reflect the
334 both the Unix domain socket and D-Bus access with no further effort. Neither
335 bmcweb nor phosphor-net-ipmid need be patched. The choice also eliminates the
336 D-Bus complications mentioned above as there's no need for the additional D-Bus
342 endpoints that are not the endpoint selected by the mux. There's been some back
343 and forth on that subject elsewhere[[1][drop-connections-discussion-1]]
344 [[2][drop-connections-discussion-2]], but it seems that not disconnecting
347 have `N` connections for `N` mux ports, `(N - 1)` of which are idle. Not only
348 that, but the `(N - 1)` connections are effectively zombies, as they have no way
349 to switch the mux back to their associated port without establishing yet another
351 order to switch the mux we may as well disconnect the existing session, in which
352 case it may as well have been disconnected when the mux switched away to begin
355 [drop-connections-discussion-1]:
356 https://gerrit.openbmc.org/c/openbmc/obmc-console/+/71228/comment/62a5fce9_60c3ad3e/
357 [drop-connections-discussion-2]:
358 https://gerrit.openbmc.org/c/openbmc/obmc-console/+/71867/comment/756f0abe_5ebe8d66/
368 (connection-based mux control which disconnects conflicting clients) allows us
369 to _optionally_ implement an out-of-band command interface in addition, because
371 conflicting clients are disconnected and the mux is switched. This may be
376 It's proposed that we use one obmc-console-server process to expose the `N`
377 consoles connected to a UART mux, where each console represents one mux port.
378 The mux is switched based on the endpoint of the most recent client connection,
382 The internal datastructures of obmc-console will change to accomodate the
386 provide a similar approach for specifying the mux GPIOs to that used by [the
387 i2c-mux-gpio devicetree binding][linux-i2c-mux-gpio].
389 [linux-i2c-mux-gpio]:
390 …rnel/git/torvalds/linux.git/tree/Documentation/devicetree/bindings/i2c/i2c-mux-gpio.yaml?h=v6.9#n12
396 +--------------------+
398 +--------------------+
403 … +----+----+ +-----+ +-------+
405 … | | +-------+ +-------+ | +-----+ UART1 |
406 +-----------------------------------+ | | | | | | | | |…
407 | xyz.openbmc_project.Console.host1 +-----+ +-----+ ttyS0 +-----+ UART0 +-----+ | +…
408 +-----------------------------------+ | | | | | | | |
409 | obmc | +-------+ +-------+ | |
410 | console | | MUX |
411 | server | +-------+ | |
412 +-----------------------------------+ | | | | | |
413 | xyz.openbmc_project.Console.host2 +-----+ +-------------------+ GPIO +-----+ | +…
414 +-----------------------------------+ | | | | | | |…
415 … | | +-------+ | +-----+ UART2 |
417 … +----+----+ +-----+ +-------+
422 disconnection events of a console via mux control will produce messages for
427 - Making it clear this message is from obmc-console
428 - Timestamp
429 - Indication of connected/disconnected
432 about mux state. Any application on the other side of the uart could also
438 [obmc-console] %Y-%m-%d %H:%M:%S UTC CONNECTED
439 [obmc-console] %Y-%m-%d %H:%M:%S UTC DISCONNECTED
444 For the D-Bus representation we choose the unified tree.
455 ### Multiple obmc-console-server processes for the multiple consoles
463 the mux GPIOs. Inconsistencies across the files would also need to be managed.
480 - Does this repository require a new repository? No
481 - Who will be the initial maintainer(s) of this repository?
482 - Which repositories are expected to be modified to execute this design?
483 obmc-console, docs
484 - Make a list, and add listed repository maintainers to the gerrit review.