Advanced Serial Debugging Guide

Author

Roman Kargin and Lyle Hazelwood
Copyright © 2013 Roman Kargin and Lyle Hazelwood
Proofreading and grammar corrections by the AmigaOS Wiki team.

Introduction

While AmigaOS has "hi-level" capabilities to help debug problems (e.g. redirecting debug outputs to memory and displaying the log with DumpDebugBuffer or using serial redirection tools like Sashimi) it is sometimes still not enough. For example, there is no protection for areas like input and Intuition so we can get into a situation where the GUI is not operational but the OS is still working. Intuition, input and any other necessary components can crash and then the GrimReaper utility has no way to spawn itself. Meanwhile, the kernel can still can output debug information about the crash on serial.

To begin with, you should know that AmigaOS has 2 reapers. One is a user friendly utility from SYS:System called GrimReaper. The GrimReaper can be called a "hi-level" one. Another reaper is called Reaper which is a part of the kernel itself. The kernel's Reaper actually launches the user-friendly GrimReaper when a required. So, you can imagine that when things get nasty, the kernel's reaper can catch some information and output it to the serial and the OS may die soon after that. Visually, you just see a "freeze" of the OS and you don't know what happened and of course no stack trace or register dump.

That means that when you want to do some serious work and you need any way to catch your bugs and/or debug any of your problematic code, then serial debugging is the best and only one way. Of course it's still possible to hope that the system friendly GrimReaper will popup for you and that there will be nothing so hardcore which it will crash Intuition and "freeze" the OS but that's just not enough when it come to doing real work.

You may ask now why the serial port is used at all? Why not parallel or something else? Why does everyone keep telling you to use serial debugging as if there is nothing else you can connect a cable to? The answer is in simplicity and reliability. Serial was chosen because it is simple to transfer data, bit by bit, not like for example done with a parallel port. There are different interfaces which also can transfer information bit by bit (like Ethernet, Firewire and USB) but the standard serial port is common to all platforms and far less complex. It comes as no surprise that the old AmigaOS 3 which works on classic Amigas, all output debug information via serial ports. Now, we have different kinds of hardware where USB is pervasive but USB is very complex and still not as reliable for debugging purposes.

Serial and NULL-Modem

Serial

Serial ports (often called RS-232 when in reality it is RS-232C) have disappeared as a standard option on many user level computers and have been replaced by USB. You can still find many business level x86 motherboards with serial ports. There are solutions for PC hardware without a serial port like USB to serial converters but we will talk about that later. Right now, all we need to know is that all our PowerPC based Amigas, classic Amigas and even the AmigaOne-X1000 have a serial port and the AmigaOS kernel's reaper outputs debug information over that serial port.

Serial ports most often come in two pin outs: 9 pins and 25 pins.

25 Pin Connector

9 Pin Connector

The 25 pin one, which is usually called DB25, was the first one and is used on the classic Amigas. After some time, software was simplified to use only half of the pins and then 9 pin connector (usually called DB9 but in reality it is DE9) was created. While classic Amigas have the older serial connectors with 25 pins, the Pegasos2, X1000 and Sams all have 9 pin connectors. In general, it makes no differences for our purposes. This is just information in case you decide to build your cable from scratch.

While the information given there is enough for our article, you still can check out Wikipedia for more information about serial ports and the RS232C standard itself at http://en.wikipedia.org/wiki/Serial_port.

NULL-Modem

In the good old days, when Modems/Teletypes were used to connect over the serial port, it was expected that one side is the Data Terminal Equipment (DTE) (usually a computer/terminal) and the other side is Data Circuit-terminating Equipment (DCE) (usually a Modem). One side which is an output on a DTE is an input on a DCE and vice versa. Because of that DCE can be connected to a DTE with a straight wired cable.

Today things are different. Terminals and Modems have mostly disappeared and computers have the same kind of serial port that terminals used to have: DTE. As a result, we can't connect them with a straight, pin to pin cable because it will connect the data transfer pins (TX to TX and RX to RX) like it was when we connect a serial port with a Modem and that will not work. The solution is to swap the data transfer wires: TX to RX. That's what is simply called a Null Modem Cable (though without ground connected which is always better to do).

Usually when you go into a shop and find a modem cable it is most often not a null-model cable. You need to ask for a null-modem cable where the data pins have been crossed over. Visually, the cables look exactly the same. Only the wires inside are not cross over and thus it will not transfer any serial debug output.

NULL-Modem cable can be of 4 types:

1. No hardware handshaking
   This cable has only the data and signal ground wires connected. I.e. Rx, Tx and Ground.
2. Loop back handshaking
   Just some "cheat" cable to make a fake flow control.
3. Partial handshaking
   Advanced "cheat" cable.
4. Full handshaking
   No cheats, just everything what can be in null-modem cable.

As you see, in general, to have basic NULL-modem cable (that one, with "no hardware handshaking") it is enough to have swap pins 2 and 3 (i.e. RxD with TxD) and connect ground pin the same on both sides. Even with such a simply null-modem cable of just 3 wires, you can have your debug output and everything will works. You can of course build cable with full handshaking, and it will works by itself, just handshaking itself can not works on some hardware. For example, x1000 does not support hardware handshaking at all, and even if you have such a cable, in terminal software where you will catch your debug output, it still will need to choice "no handshaking". From another side, old A1200/A4000 serial ports support Handshaking (for example, such software as AmigaExplorer from AmigaForever, do transferring between Amiga and Windows computers via serials null-modem cables, and there is speed matter and handshaking helps there). So its better to have just full-handshaking cable, and to test it with your hardware. But if you need null-modem cable just for debug output (and in general that's why it need it most of time), even simply null-modem cable are allow 115200 and its more than enough for debug output. At least, there wasn't any problems ever when you need to catch a output from serial, and you can't, because 115200 somehow not enough.

Note
If you have 2 computers which you want to connect between via serial ports, you need NULL modem cable, and not "straight" serial cable.

As serial ports can be only of 2 types (db25 and db9), then there is 3 possible pinouts for null-modem cables with full handshaking can be: db25<->db25, db9<->db25, db9<->db9.

While db9<->db9 serial cables is possible to find out in shops today, they can be not null-modem ones (and you need to works on them), with db25 you have almost for sure deal to build it yourself (just buy connectors, and connect necessary wires as shown on pinouts).

You also can build some cable which will have per 2 connectors on 2 sides : db9 and db25 on one side, and the same db9 and db25 on another side, so when you need to choice the port you need. For example can be handy when you have and old A1200/A4000, and modern PowerPC hardware, and your PCs happens to be different, etc. I.e. you not need to soldering iron again new cable, just will use one-for-all-times. To build that one you just follow the same pinout logic as shown below, just double them where you need that.

To add, you even can go another way: you just buy classic serial cable (let's say in show you didn't find null-modem one, which is pretty much possible will be like this), and then, you just buy small connector-adapter which will do for you that "cross-wire" of pins, and which will make from your "straight" serial cable, a null modem one. Like that on screenshot:

If you want any more info about null-modem cables, you always can check Wikipedia there: http://en.wikipedia.org/wiki/Null_modem

Connect them now!

Serial<->Serial

There is nothing else you need as only working null-modem cable. As we discuss before it does not matter how you do it, but just it should be null-modem in end and works. Is it real null-modem cable, or just "straight" serial cable with null-modem adapter does not matter: just for serial ports wires should be swapped and you just connect your Amiga hardware with any other hardware (with another Amiga, or with any x86 hardware, not so matter) by that cable.

Serial<->USB

That's the part which is most important and interesting for anyone who today works with AmigaOS. The reasons is that there is no more modern x86 hardware (which all of us have most of time as necessary part of life) with serial port. More of it, most of tired from those big boxes and have only notebooks, which, again, have no serial ports anymore. The solutions there is easy : you can find out in any shop (yes, even in 2013), USB to Serial adapters. There is plenty of them , from different companies, most of which works with no problems, because all what those adapters do, its just make for your hardware which didn't have built-in serial port, one more serial port. Visually they looks just like this:

Can be different of course, as it just about what form of connector is used when build a cable. Look can be different, but idea the same : in system you have now serial port. I for myself use one from Gembird based on Chips PS2303 on my notebook with winxp, where after installing of drivers it shows ups as COM17:

After you have in your system new serial port which come from USB to serial adapter, you can think that now you have just serial adapter on your computer, and everything will be the same as if you connect just Serial with Serial. The same exactly null-modem cable, the same can be null-modem adapter with "straight" cable and so on.

Serial<->Anything

You of course can connect to ANY port in any of your computer any kind of adapter (which you will make yourself, or buy from anywhere), which will just make for your system new "serial". I.e. you can not only use Serial to USB adapters, but, Serial to Fireware adapters (if you will lucky enough to find out that, or that will build it yourself), or, even, serial to "Ethernet", and also, write your own driver for, etc.

What I trying to point there, is does not matter how, but you just need to make serial in your system. USB to serial adapters just used mostly because they popular, can be find out in shops, easy to utilize, and everything is tested and retested by many people.

Terminal Software and port settings

Now, after you have your cable connected between 2 machines, you need software which will catch the data from one of sides. The "receiver" side can be an x86 (and with Windows, and with Linux, and with Mac OS, and whatever else), and Amiga with AmigaOS, or pOS, or Unix, or whatever was done for old Amiga hardware, or PowerPC Macs, or any kind of another hardware. That software called "Terminal" software and as most of us use x86 notebooks to capture debug outputs from our Amigas, we will start from x86.

The best terminal software for x86 are PuTTY. You can PuTTY from http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html. Be sure that you get latest/full version because there are some stripped versions around with no support of serial connections. Normal version with working serial support will looks like this:

On Amiga (if you connect 2 Amigas by serial) you can use old 68k Term 4.8:

On Linux you can use the same putty, or well-known minicom.

On Mac <insert here>

But its all in general about how just to get all the data. Debug outputs its plain text data, so anything which just cat grab info from your serial port and redirect where you need (to console or to file, not so matter) will works. I.e. you can just write your own simple code which will recieve data, without needs of any terminals. But that's in theory, in practice of course better to use something which already done.

The settings which you need to use and which 100% will works on any of Amiga hardware from which you want to get your serial output are:

baud: 115200 
data bits: 8 
stop bits: 1 
parity: none 
flow control: none

It may works with some other settings (like different parity and flow control), but as it point out before, on some hardware it may not works at all, on another will works not as extended, so just use it all the time like this when you do your first tests. After all you always can do your experiments when everything will works with those settings.

How to redirect debug output to serial

By default debug output of AmigaOS sends to the memory, and not to serial: that's done for simplicity user friendly usage of debug logs. I.e. you have something happens, not especially bugs, just any debug output and you want to see it. So you just type in console "dumpdebugbuffer", and it show you what debug output was (you also can use Sashimi tool, its will automatically redirect output to the console in real time).

So to make all your serial debug logging, you need to switch output to serial. For that you have 2 ways: boot options in the firmwares (UBOOT for Sams/old AmigaOnes, OpenFirmware for Pegasos2 and CFE for X1000) and "kdebug" utility.

Firmware method

As we have many different hardware on which AmigaOS can be run today, then there is no surprise that they all use different firmwares: AmigaOne-XE/MicroA1-C/Sams use UBOOT, Pegasos2 use OpenFirmware and X1000 uses CFE. For all of them bootmenu options will be different, and you need to refer to the documentation which come with hardware, but in all the cases you have variable called "os4_commandline" to which you spend your arguments, for example:

X1000/CFE to set debuglevel to 0 and output to serial:

os4_commandline DEBUGLEVEL=0 SERIAL

Pegasos2 OpenFirmware to redirect output to serial with debug kernel's option "munge":

os4_commandline='munge' 

Sams UBOOT with the same munge, debuglevel=7 and serial redirect:

os4_commandline=.....

Kdebug method

Kdebug is command line utility placed in System:C/kdebug and come as part of Kernel. By that utility you can redirect your output to serial/memory (i.e. it will overwrite what you do from firmware), as well as by that you can setup debug levels. You just put for example to s:user-startup something like:

run >NIL: kdebug "debug level 5"
run >NIL: kdebug "console serial"

And so you have level 5 output thrown on your serial line.

Get most of serial debugging

To start with, you need to read those 2 articles:

1. The Debug Kernel
2. Exec Debug

From which you should do the accumtion just when you develop anything, you should all the time use debug.kernel. Debug.kernel provide you with some more functionality in compare with user's plain kernel, as well as it give you ability to plays with debug levels, where you can choice how much of "system" debug output you want to get. Its pretty easy to miss that bit, that debug-levels works only on debug.kernels. Usually developers start to plays with levels, see no changes, and start to think "wtf, why it not works". It works, just kernel should be debug one.

And while debug kernel give you some debug functionality, it still didn't cover everything possible like for example do old MungWalls (i.e. debug kernel have only "Munge" feature, but not "Wall" feature), or like for example do MemGuard (can be found on OS4Depot), which add on top of kernel some more dirty-stuff-catch.

So, to get most of your serial debugging, you need to use that combo: debug kernel with "munge" option enabled, "memguard" running on background and set debug level to the value you find most interesting. Usually 5 or 7 is enough, but sometime when bug so heavy and strange, you can raise the volume in hope to see something interesting.

If nothing works

Now on to troubleshooting. If you build/buy a cable, adapters and all the stuff, connect everything between, fire up the terminal software, setup everything correctly and still nothing works, then:

1. Check the ports.

Easy way to check if the port is working

... TODO to finish ...

2. Check the cable twice.

The best way to check a cable is with a multimeter. Set it so that when you touch wires on different sides you will heard a "beep" if it connected. Check that all of the connections are as they should be. If you use null-modem adapter on top of "straight" serial cable, then check it anyway, just in case, with the same meter.

3. Check program's settings and settings of the port if it USB to serial one.

Be sure that for you have right settings and in the terminal software (especially the baud, flow control and parity).

Final words

While the whole topic we describe is more or less easy one, there wasn't normall guide till now which describe from the begining evertyhing: i.e. what kind of cable you can use, how to build it, how to use usb2serial adapters, what settings should be used and what to do with all of this. We hope that this guide will at least cover all the gaps in that terms, and any developer who ever will head "use serial debugging" will just read that article, and will have no questions. Anyway, if you have any more info to add, or just found a wrong part somewhere, just send me mail on kas1e@yandex.ru and i can udate article.

Links

[1.] http://en.wikipedia.org/wiki/Serial_port
[2.] http://en.wikipedia.org/wiki/Null_modem
[3.] Debug Kernel
[4.] Exec Debug