Changes between Initial Version and Version 1 of UsersGuide/UserSerialConsole

Timestamp:

2017-05-06T14:10:57Z (7 years ago)

Author:

Jakub Jermář

Comment:

Add a guide for using user mode serial console

UsersGuide/UserSerialConsole

@@ +1 @@
+= User Serial Console =
+
+In order to use a serial console for the command line UI, a couple of conditions have to be met:
+
+  * HelenOS must support passing boot arguments to the kernel on the given platform
+  * HelenOS must have a userspace driver for the serial console device
+  * the user needs to pass the exact location service path to the serial console device in the `console` argument
+
+Currently, these requirements are satisfied on ia32, amd64 and sparc64/sun4u.
+
+== ia32 and amd64 ==
+
+Assuming your serial console device is at `devices/\hw\pci0\00:01.0\com1\a` (this is the case in QEMU), modify your grub.cfg to contain the following:
+
+{{{
+        multiboot /boot/kernel.bin console=devices/\\hw\\pci0\\00:01.0\\com1\\a
+}}}
+
+Note that the backslashes must be escaped on the GRUB command line. If you are modifying boot/Makefile.grub, make sure to escape the backslashes properly:
+
+{{{
+=== modified file 'boot/Makefile.grub'
+--- boot/Makefile.grub  2016-04-05 19:04:11 +0000
++++ boot/Makefile.grub  2017-05-06 13:38:00 +0000
+@@ -85,7 +85,7 @@
+        for module in $(MODULES) ; do \
+                echo "  echo 'Loading $$module'" >> $(BOOT_CONFIG) ; \
+                if [ "$$module" = "kernel.bin" ] ; then \
+-                       echo "  $(MULTIBOOT_CMD) /boot/$$module" >> $(BOOT_CONFIG) ; \
++                       echo "  $(MULTIBOOT_CMD) /boot/$$module console=devices/\\\\hw\\\\pci0\\\\00:01.0\\\\com1\\\\a" >> $(BOOT_CONFIG) ; \
+                else \
+                        echo "  $(MODULE_CMD) /boot/$$module /boot/$$module" >> $(BOOT_CONFIG) ; \
+                fi \
+
+}}}
+
+Upon boot, the `console` service should start using the serial console for its input/output. We can run HelenOS using the `tools/ew.py` in QEMU:
+
+{{{
+$ xterm -e `tools/ew.py -d` -serial stdio
+}}}
+
+or if we want a complete headless run, we do:
+
+{{{
+xterm -e `tools/ew.py -d` -nographic
+}}}
+
+== sparc64/sun4u ==
+
+Serial console on sun4u is known to be working only under QEMU and is fully integrated into `tools\ew.py`:
+
+{{{
+bash-4.3$ tools/ew.py -d
+xterm -T "HelenOS/sparc64 on generic" -e qemu-system-sparc64 -M sun4u --prom-env boot-args="console=devices/\hw\pci0\00:03.0\com1\a" -drive file=hdisk.img,index=0,media=disk,format=raw -device e1000,vlan=0 -net user,hostfwd=udp::8080-:8080,hostfwd=udp::8081-:8081,hostfwd=tcp::8080-:8080,hostfwd=tcp::8081-:8081,hostfwd=tcp::2223-:2223 -usb -boot d -cdrom image.iso -nographic
+}}}
+