{"id":13562141,"url":"https://github.com/weltling/convey","last_synced_at":"2025-03-15T14:30:53.206Z","repository":{"id":138348721,"uuid":"222537326","full_name":"weltling/convey","owner":"weltling","description":"Communication through a serial port or named pipe","archived":false,"fork":false,"pushed_at":"2023-07-19T21:01:22.000Z","size":84,"stargazers_count":55,"open_issues_count":0,"forks_count":11,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-02-27T03:11:18.053Z","etag":null,"topics":["com-port","hyper-v","kernel","kernel-debug","kernel-dev","linux","raspberry-pi","serial","serial-console","serial-port","virtual-machine","vmlinux","windows","wsl","wsl2"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/weltling.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2019-11-18T20:22:35.000Z","updated_at":"2024-10-16T18:45:17.000Z","dependencies_parsed_at":"2024-01-16T18:23:54.144Z","dependency_job_id":null,"html_url":"https://github.com/weltling/convey","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weltling%2Fconvey","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weltling%2Fconvey/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weltling%2Fconvey/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/weltling%2Fconvey/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/weltling","download_url":"https://codeload.github.com/weltling/convey/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243742696,"owners_count":20340689,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["com-port","hyper-v","kernel","kernel-debug","kernel-dev","linux","raspberry-pi","serial","serial-console","serial-port","virtual-machine","vmlinux","windows","wsl","wsl2"],"created_at":"2024-08-01T13:01:05.067Z","updated_at":"2025-03-15T14:30:52.931Z","avatar_url":"https://github.com/weltling.png","language":"C++","readme":"# The convey tool\n\n[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.\n\nConvey is distributed under the BSD 2-clause license.\n\n\n# Building\n\n## Visual C++\n\n- Get onto the VC++ shell\n- nmake /nologo\n\n## Clang\n\n- Get onto the VC++ shell\n- nmake /nologo CXX=\"c:\\Program Files\\LLVM\\bin\\clang-cl.exe\" LD=\"c:\\Program Files\\LLVM\\bin\\lld-link.exe\"\n\n\n# Usage with a physical COM port\n\nThe physical COM port usage is a simple as invoking the tool with the COM port name.\n\n- Invoke `convey.exe COM\u003cnum\u003e`\n- For the port with number \u003e= 10, use `\\.\\COM\u003cnum\u003e`\n\nThere'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.\n\n\n# Usage with Hyper-V\n\nHypervisors 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.\n\n## Preparing Hyper-V\n\n### On host, conifgure a com port\n\nAssign a named pipe that will be passed as a COM1 into a VM.\n\n`Set-VMComPort -VMName \u003cvm name\u003e -Number 1 -Path \\\\.\\pipe\\\u003cpipe name\u003e`\n\nView configured COM ports on a VM.\n\n`Get-VMComPort -VMName \u003cvm name\u003e`\n\n### Inside the VM\n\nAdd `console=ttyS0,115200 console=tty0` to the kernel parameters. Note, that `ttyS0` is what is usually\navailable on a typical setup. Depending on the hardware and system configuration, this device name can\nbe different.\n\n### Optional\n\nConfigure autologin for `ttyS0` or another terminal device you've chosen.\n\n\n## Connecting to a VM\n\n### Method 1\n\n- Start the VM.\n- Start an elevated cmd window and invoke `convey.exe \\\\.\\pipe\\\u003cpipe name\u003e`.\n\n### Method 2\n\n- Before starting the VM, invoke convey with the `--poll` argument.\n- Start the VM.\n\n\n# Debugging Linux kernel\n\n## Prerequisities\n\n- Download the unstripped vmlinux to your local machine, or\n- Download the vmlinux and the debug symbols.\n- Download the kernel sources corresponding to the given kernel build.\n\n## On host, create a PTY mapping to the VM named pipe\n\nInvoke WSL on an elevated console and run\n\n`socat PTY,link=/tmp/my-vm-pty,raw,echo=0 SYSTEM:\"while true; do ./convey.exe //./pipe/\u003cpipe name\u003e; sleep 0.1; done\"`\n\n## VM setup\n\nAdd `nokaslr` to the kernel command line.\n\nSee also a more detailed documentation on the (kgdb)[https://www.kernel.org/doc/html/v4.17/dev-tools/kgdb.html] page.\n\n### Turn on kernel debug mode\n\n#### Method 1\n\nInside the VM, execute the commands below:\n\n- `echo ttyS0 \u003e /sys/module/kgdboc/parameters/kgdboc`\n- `echo g \u003e /proc/sysrq-trigger`\n\n#### Method 2\n\nAdd a suitable configuration to the kernel command line, for example `kgdboc=ttyS0,115200 kgdbwait`.\n\n## On host, start debugging\n\nRun another WSL shell and invoke\n\n```\n$ gdb ./vmlinux\n(gdb) set serial baud 115200\n(gdb) target remote /tmp/my-vm-pty\n```\n\nHere you are. This doesn't need an elevated console.\n\n\n# Troubleshooting \u0026 Tricks\n\n## Disable input echoing\n\n`stty -F /dev/ttyS0 -echo`\n\n## The serial screen size is too small\n\nUse stty to set the desired columns and rows number, for example\n\n`stty columns 235 rows 62`\n\n## Pointing gdb to the sources\n\n`(gdb) set substitute-path /sources/were/compiled/here /put/sources/here`\n\nTo add multiple folders to be searched by GDB, use\n\n`(gdb) set dir /path/to/base/dir`\n\nAlternatively, unpack kernel sources under /usr/src/kernel or where ever else the kernel was built. \n\n## GDB tells `Remote replied unexpectedly to 'vMustReplyEmpty': vMustReplyEmpty`\n\nForgot to bring kernel into the debugging mode?\n\n## Not all frames are resolved\n\nAdd `nokaslr` to the kernel parameters.\n\n# Sysrq cannot be sent due to the lockdown\n\nIf the `lockdown=` option is on the kernel cmdline, it has to be removed.\n\nSome distribution might also allow to disable lockdown at runtime. In a VM, `Alt+SysRq+x` can be sent by:\n\n```\n$ echo 1 \u003e /proc/sys/kernel/sysrq\n$ echo x \u003e /proc/sysrq-trigger\n```\n\n# Links\n\n- https://www.kernel.org/doc/html/latest/admin-guide/serial-console.html\n- https://www.kernel.org/doc/html/v4.17/dev-tools/kgdb.html\n- https://www.elinux.org/Debugging_The_Linux_Kernel_Using_Gdb\n- http://man7.org/linux/man-pages/man1/stty.1.html\n- https://linux.die.net/man/1/socat\n- https://stackoverflow.com/questions/14584504/problems-to-connect-gdb-over-an-serial-port-to-an-kgdb-build-kernel\n- https://unix.stackexchange.com/questions/125183/how-to-find-which-serial-port-is-in-use\n- https://sourceware.org/gdb/onlinedocs/gdb/Source-Path.html\n\n# TODO\n\n- Check VMWare and VirtualBox.\n- Check other things like Windows VM or any other possible counter part exposing named pipes.\n- \u003cstrike\u003eAdd console options for more flexibility.\u003c/strike\u003e\n- Implement sending/receiving a file.\n- ...\n\n","funding_links":[],"categories":["C++","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweltling%2Fconvey","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fweltling%2Fconvey","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fweltling%2Fconvey/lists"}