====== Introduction ======

It's sometimes useful to add debugging prints to servers or drivers and have the output not show up on your screen, but redirected to serial. This way, you can log the prints to a text file or terminal on another box.

====== Things you can do with serial ======

===== Output =====

As stated, all kernel, drivers and servers (-lsys processes) output goes to serial when enabled with ''cttyline=0''. This makes it convenient to log, search, analyze etc. such output.

==== IS ====

IS is the information server that interrogates others / makes them print output. In serial mode, the result goes to serial instead of the screen. Press shift+F5 to see an overview of the various available debug dumps. Each is an F-key. Press the F-key to see the output on serial.

===== Input =====

The Minix kernel also listens to input from serial in this mode. Keys that do things:
    * '1' print a list of all processes and their state (flags, whether they are blocking, if so on which process, whether they are signalled, and so on), and stacktraces per process. very useful to deduce, if the system is hanging, on which process processes are blocking (dependency lines are printed for each process too). also for each process a stacktrace is printed so you can see exactly what the process (hanging or not) is doing right now.
    * '2' print a list of all runnable processes. nice to get a rough idea of what's going on (and that the system is alive at all) when pressed repeatedly.
    * '4' in SMP mode, print SMP cpu info
    * '5' print a stacktrace of all VFS threads

====== Enable serial on your Minix box ======

First you have to tell Minix to redirect ''printf'''s from system processes to serial out. You do this by providing the ''cttyline'' and ''cttybaud'' parameters to the kernel upon boot up. These days, the boot menu should have an "Edit boot menu" option which allows you to do this **temporarily** and without modifying any files. In the boot menu, select the "Edit boot menu" option. Then, for "Option (edit):", just press Enter to select the default. Then add ''cttyline=0 cttybaud=115200'' at the end of the shown line. Press Enter once more to boot with the options.

To modify the boot menu **permanently**, add the following to ///etc/boot.cfg.local// (create the file if it doesn't exist; it is only a single line, do not insert newlines in between):
<code>
menu=Start latest serial MINIX 3:load_mods /boot/minix_latest/mod*;multiboot /boot/minix_latest/kernel rootdevname=c0d0p0s0 cttyline=0 cttybaud=115200
</code>
After you've created that, run
<code>
# update_bootcfg
</code>
to update the boot configuration. If you also want the boot menu to be sent over serial instead of showing up on the screen, add
<code>
consdev=com0
</code>
to ///etc/boot.cfg.local// as well. Note that if add this line but you don't attach a null modem or terminal to your serial port, you won't see and be able to pick an option from the boot menu.
====== Setting up the receivers end ======

We can use serial out on real hardware and on VMs.

===== Qemu =====

To log the serial output to a file add the following option
<code>
-serial file:/path/to/file
</code>
If you want to be able to pick an option from the boot menu over serial, use
<code>
-serial stdio
</code>
If you want both, use ''tee'' to multiplex the output and ''sed'' to sanitize the output:
<code>
-serial stdio | sed -u 's/^M//g' | tee /path/to/file
</code>

===== VMware =====

Before you run a VM, edit the VM settings and add a Serial Port device. There you have a number of options such as redirecting to a physical device or a file.

It takes a little setting up, but the most pleasant resulting usage is to redirect it to a pipe and then connect to the pipe using e.g. a telnet client.

==== VMware under Windows =====

To do that under windows, redirect the serial output to a named pipe, and call it "\\.\pipe\com_1". Then download, install and run "Named Pipe TCP proxy." Make
a new connection and set Pipe name to "\\.\pipe\com_1", description "vmware." Start it. Set TCP port to e.g. 1001. Then configure a telnet client (e.g. putty works
well) to connect to localhost port 1001. If your vmware is running, you should see it connected and you have access to your serial console.

===== Real hardware =====

Connect your Minix box to a receiving box using a [[http://en.wikipedia.org/wiki/Nullmodem|null modem]] . Then start a terminal client on the receiving box such as kermit:
<code>
$ kermit -l /dev/ttyS0
</code>
However, this way kermit will stop working upon every reboot. You can use following script to prevent that (save as a file and make it executable):
<code sh>
#!/usr/bin/kermit +
kermit -E -l /dev/ttyS0
set speed 115200
set reliable
fast
set carrier-watch off
set flow-control none
set prefixing all
connect
</code>

==== FreeBSD ====

In the FreeBSD base system you can use tip. Edit /etc/remote to set the right parameters, e.g.:
<code>
uart0|com1:dv=/dev/cuau0:br#115200:pa=none:
</code>
Then:
<code>
# tip uart0
</code>
and you're in.