xref: /openbmc/obmc-console/README.md (revision 289e6479) 
1# obmc-console
2
3## To Build
4
5To build this project, run the following shell commands:
6
7    meson setup build
8    meson compile -C build
9
10To test:
11
12    meson test -C build
13
14## To Run Server
15
16Running the server requires a serial port (e.g. /dev/ttyS0):
17
18    touch obmc-console.conf
19    ./obmc-console-server --config obmc-console.conf ttyS0
20
21## To Connect Client
22
23To connect to the server, simply run the client:
24
25    ./obmc-console-client
26
27To disconnect the client, use the standard `~.` combination.
28
29## Underlying design
30
31This shows how the host UART connection is abstracted within the BMC as a Unix
32domain socket.
33
34                +---------------------------------------------------------------------------------------------+
35                |                                                                                             |
36                |       obmc-console-client       unix domain socket         obmc-console-server              |
37                |                                                                                             |
38                |     +----------------------+                           +------------------------+           |
39                |     |   client.2200.conf   |  +---------------------+  | server.ttyVUART0.conf  |           |
40            +---+--+  +----------------------+  |                     |  +------------------------+  +--------+-------+
41    Network    | 2200 +-->                      +->+ @obmc-console.host0 +<-+                        <--+ /dev/ttyVUART0 |   UARTs
42            +---+--+  | console-id = "host0" |  |                     |  |  console-id = "host0"  |  +--------+-------+
43                |     |                      |  +---------------------+  |                        |           |
44                |     +----------------------+                           +------------------------+           |
45                |                                                                                             |
46                |                                                                                             |
47                |                                                                                             |
48                +---------------------------------------------------------------------------------------------+
49
50This supports multiple independent consoles. The `console-id` is a unique
51portion for the unix domain socket created by the obmc-console-server instance.
52The server needs to know this because it needs to know what to name the pipe;
53the client needs to know it as it needs to form the abstract socket name to
54which to connect.
55
56## Mux Support
57
58In some hardware designs, multiple UARTS may be available behind a Mux. Please
59reference
60[docs/mux-support.md](https://github.com/openbmc/obmc-console/blob/master/docs/mux-support.md)
61in that case.
62
63## Sample Development Setup
64
65For developing obmc-console, we can use pseudo terminals (pty's) in Linux.
66
67The socat command will output names of 2 pty's, one of which is the master and
68the other one is the slave. The master pty can be used to emulate a UART.
69
70    $ socat -d -d pty,raw,echo=0,link=pty1 pty,raw,echo=0,link=pty2
71
72    $ obmc-console-server --console-id dev $(realpath pty2)
73
74    $ obmc-console-client -i dev
75
76    # this message should appear for the client
77    $ echo "hi" > pty1
78