README.md
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 dbus-run-session 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