Lines Matching +full:out +full:- +full:of +full:- +full:band
1 # uart-mux-support design
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
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.
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)
77 1. The console IO regardless of the mux state
80 There are constraints on some combinations of these. For instance:
82 - If the connection endpoint represents the TTY device exposed by Linux (1.1)
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
94 With these in mind we end up with the following table of design options:
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 …
114 switched to capture the output of whatever the satellite is printing. It is
115 important to log the output of the update process to understand any failures
121 2. A blade's satellite BMC, CPLD and host are all on separate ports of a UART
124 The boot process for a blade requires a sequence of actions across its
129 For ease of correlation, their output should be logged together.
133 Scenario 1 is problematic. It highlights the fundamental concern of ownership of
136 satellite BMC), but a user has shown intent for the selection of another (to
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
146 on the initiation of a connection (2.3), the user connecting to the host console
150 a reason. With extra actions, using the out-of-band command interface, they may
158 Should it be the responsibility of obmc-console to coordinate otherwise
159 un-coordinated users?
161 This is a question of policy: How those users should be coordinated will likely
162 look very different based on concerns such as the role of the platform in a
163 larger system, the roles and needs of the users interacting with it, and the
164 concrete design of the platform itself.
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
192 the problem. It's not yet clear that this is the case for either of IPMI or
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,
215 effectively creating multiple ways of doing something.
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:
260 property, and an `Activate()` method. The `Activate()` method, by nature of
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.
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
279 makes it easy to discover the state of the system. However, it motivates the
280 choice of a unified object tree to provide a common object path to host the
282 avoid an alternative instance of the "multiple representations of one thing"
283 problem highlighted in the discussion of claiming multiple bus names for the
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
289 system are related, and what the impact might be of activating any one of them.
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
293 becomes more of an implementation detail if either of design options 2.2 or 2.3
294 are selected. The choice in those cases is instead motivated by the level of
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
314 what's at the remote end of the BMC's TTY device for regular unmuxed consoles,
316 Taking this approach avoids adding a new endpoint ABI to obmc-console and
317 eliminates design options A-D inclusive.
319 Further, on the basis of frustrating behaviour in the face of lingering network
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
328 D-Bus representation above, the discussion on the PDI patch, and the impact on
330 the out-of-band command method (2.1).
333 endpoint of the most recent connection. This has the benefit of functioning for
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
339 This reasoning leaves us the choice of design options `F` and `G`.
343 and forth on that subject elsewhere[[1][drop-connections-discussion-1]]
344 [[2][drop-connections-discussion-2]], but it seems that not disconnecting
345 clients is effectively a worse implementation of design option `C`, which we've
346 already eliminated. It's worse than `C` because instead of 1 connection we could
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
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/
363 nexus in terms of both existing ABI, desired behaviour, and implementation
368 (connection-based mux control which disconnects conflicting clients) allows us
369 to _optionally_ implement an out-of-band command interface in addition, because
376 It's proposed that we use one obmc-console-server process to expose the `N`
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
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
392 Below is a block diagram of the relationships between the software and hardware
396 +--------------------+
398 +--------------------+
403 … +----+----+ +-----+ +-------+
405 … | | +-------+ +-------+ | +-----+ UART1 |
406 +-----------------------------------+ | | | | | | | | |…
407 | xyz.openbmc_project.Console.host1 +-----+ +-----+ ttyS0 +-----+ UART0 +-----+ | +…
408 +-----------------------------------+ | | | | | | | |
409 | obmc | +-------+ +-------+ | |
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
435 The initial format of these messages will be something like:
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
462 This was considered but it would duplicate configuration, like the definition of
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.