Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/weltling/convey
Communication through a serial port or named pipe
https://github.com/weltling/convey
com-port hyper-v kernel kernel-debug kernel-dev linux raspberry-pi serial serial-console serial-port virtual-machine vmlinux windows wsl wsl2
Last synced: 3 months ago
JSON representation
Communication through a serial port or named pipe
- Host: GitHub
- URL: https://github.com/weltling/convey
- Owner: weltling
- License: other
- Created: 2019-11-18T20:22:35.000Z (about 5 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T21:01:22.000Z (over 1 year ago)
- Last Synced: 2024-08-01T13:25:24.881Z (6 months ago)
- Topics: com-port, hyper-v, kernel, kernel-debug, kernel-dev, linux, raspberry-pi, serial, serial-console, serial-port, virtual-machine, vmlinux, windows, wsl, wsl2
- Language: C++
- Homepage:
- Size: 82 KB
- Stars: 53
- Watchers: 4
- Forks: 10
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# The convey tool
[Convey](https://github.com/weltling/convey) is an inter-process communication tool with capabilities to communicate through a named pipe or a serial port. Notable features include the communication with Hyper-V virtual machines through an emulated COM port. Simplicity from the use point is the most point of focus for this tool.
Convey is distributed under the BSD 2-clause license.
# Building
## Visual C++
- Get onto the VC++ shell
- nmake /nologo
## Clang
- Get onto the VC++ shell
- nmake /nologo CXX="c:\Program Files\LLVM\bin\clang-cl.exe" LD="c:\Program Files\LLVM\bin\lld-link.exe"
# Usage with a physical COM port
The physical COM port usage is a simple as invoking the tool with the COM port name.
- Invoke `convey.exe COM`
- For the port with number >= 10, use `\.\COM`
There's no difference whether it's a native COM port or a USB-to-COM convertor. As long as the COM port appears under the device manager, it is usable.
# Usage with Hyper-V
Hypervisors like Hyper-V provide a functionality to emulate a serial port in the VM, while exposing it as a named pipe to the host Windows machine. Using convey, it is possible to connect to a virtual machine's virtual serial port from the host system using the exposed named pipe.
## Preparing Hyper-V
### On host, conifgure a com port
Assign a named pipe that will be passed as a COM1 into a VM.
`Set-VMComPort -VMName -Number 1 -Path \\.\pipe\`
View configured COM ports on a VM.
`Get-VMComPort -VMName `
### Inside the VM
Add `console=ttyS0,115200 console=tty0` to the kernel parameters. Note, that `ttyS0` is what is usually
available on a typical setup. Depending on the hardware and system configuration, this device name can
be different.
### Optional
Configure autologin for `ttyS0` or another terminal device you've chosen.
## Connecting to a VM
### Method 1
- Start the VM.
- Start an elevated cmd window and invoke `convey.exe \\.\pipe\`.
### Method 2
- Before starting the VM, invoke convey with the `--poll` argument.
- Start the VM.
# Debugging Linux kernel
## Prerequisities
- Download the unstripped vmlinux to your local machine, or
- Download the vmlinux and the debug symbols.
- Download the kernel sources corresponding to the given kernel build.
## On host, create a PTY mapping to the VM named pipe
Invoke WSL on an elevated console and run
`socat PTY,link=/tmp/my-vm-pty,raw,echo=0 SYSTEM:"while true; do ./convey.exe //./pipe/; sleep 0.1; done"`
## VM setup
Add `nokaslr` to the kernel command line.
See also a more detailed documentation on the (kgdb)[https://www.kernel.org/doc/html/v4.17/dev-tools/kgdb.html] page.
### Turn on kernel debug mode
#### Method 1
Inside the VM, execute the commands below:
- `echo ttyS0 > /sys/module/kgdboc/parameters/kgdboc`
- `echo g > /proc/sysrq-trigger`
#### Method 2
Add a suitable configuration to the kernel command line, for example `kgdboc=ttyS0,115200 kgdbwait`.
## On host, start debugging
Run another WSL shell and invoke
```
$ gdb ./vmlinux
(gdb) set serial baud 115200
(gdb) target remote /tmp/my-vm-pty
```
Here you are. This doesn't need an elevated console.
# Troubleshooting & Tricks
## Disable input echoing
`stty -F /dev/ttyS0 -echo`
## The serial screen size is too small
Use stty to set the desired columns and rows number, for example
`stty columns 235 rows 62`
## Pointing gdb to the sources
`(gdb) set substitute-path /sources/were/compiled/here /put/sources/here`
To add multiple folders to be searched by GDB, use
`(gdb) set dir /path/to/base/dir`
Alternatively, unpack kernel sources under /usr/src/kernel or where ever else the kernel was built.
## GDB tells `Remote replied unexpectedly to 'vMustReplyEmpty': vMustReplyEmpty`
Forgot to bring kernel into the debugging mode?
## Not all frames are resolved
Add `nokaslr` to the kernel parameters.
# Sysrq cannot be sent due to the lockdown
If the `lockdown=` option is on the kernel cmdline, it has to be removed.
Some distribution might also allow to disable lockdown at runtime. In a VM, `Alt+SysRq+x` can be sent by:
```
$ echo 1 > /proc/sys/kernel/sysrq
$ echo x > /proc/sysrq-trigger
```
# Links
- https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html
- https://www.kernel.org/doc/html/v4.17/dev-tools/kgdb.html
- https://www.elinux.org/Debugging_The_Linux_Kernel_Using_Gdb
- http://man7.org/linux/man-pages/man1/stty.1.html
- https://linux.die.net/man/1/socat
- https://stackoverflow.com/questions/14584504/problems-to-connect-gdb-over-an-serial-port-to-an-kgdb-build-kernel
- https://unix.stackexchange.com/questions/125183/how-to-find-which-serial-port-is-in-use
- https://sourceware.org/gdb/onlinedocs/gdb/Source-Path.html
# TODO
- Check VMWare and VirtualBox.
- Check other things like Windows VM or any other possible counter part exposing named pipes.
- Add console options for more flexibility.
- Implement sending/receiving a file.
- ...