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 but it's really 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.

A NULL-Modem cable can one 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 create fake hardware flow control.
3. Partial handshaking
   Advanced "cheat" cable.
4. Full handshaking
   No cheats, just everything that can be in null-modem cable.

In general, to create a basic NULL-modem cable (that one, with "no hardware handshaking") it is enough to cross over pins 2 and 3 (RxD with TxD) and connect the ground pin. Even with such a simple null-modem cable of just 3 wires, you will be able to output debug information and everything will work. You can of course build a cable with full handshaking and it will also work but the hardware may or may support it. For example, the X1000 does not support hardware handshaking and even if you have such a cable, the terminal software where you will capture your debug output you still need to choose the "no handshaking" option. Classic Amiga serial ports support hardware h handshaking. For example, AmigaExplorer from AmigaForever transfers data between Amiga and Windows computers via serial and handshaking helps in that case. So it's better to have a full-handshaking cable and to test it with your hardware. But if you need a null-modem cable just for capturing debug output, a simple 3 wire null-modem cable will allow up to 115200 and it's more than enough.

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

Since serial ports can be only of 2 types (DB25 and DB9) there are 3 possible pin outs for null-modem cables with full handshaking: DB25 to DB25, DB9 to DB25 and DB9 to DB9.

DB9 to DB9 serial cables are fairly easy to find in stores today but they are not likely to be null-modem cables and you will need to work on them. DB25 are more rare and you may need to build a cable yourself. Just buy connectors and connect the necessary wires as shown above.

You can also build a cable which has 2 connectors on either side (i.e. DB9 and DB25 on one side and DB9 and DB25 on the other) so you can use either connector type as needed. This can be handy when you have a classic Amiga and modern PowerPC hardware and connected to a PC for example. To build such a cable just follow the same pin logic as shown below and just double them where needed.

Another way to solve the problem would be to buy a straight serial cable and add a small connector-adapter which will change the wiring from straight to null modem like in the screenshot below:

You can find even more information about null-modem cables on Wikipedia.

Connect them now!

Serial<->Serial

There is nothing else you need except a working null-modem cable. As we discussed before, all you need is a null modem and it works. It must be a real null modem cable or a straight serial cable with a null-modem adapter; doesn't matter which one.

Serial<->USB

This section is important and interesting for anyone who works with AmigaOS. The reason is that it is more difficult to find x86 hardware (which most of us have use as a necessary part of life) with built-in serial ports. It is even more difficult to find a notebook with a serial port. The solution is to use commonly available USB to serial adapters. There are plenty of them from all sorts of different companies. Despite the fact that they are common, some adapters are better than others. Although most will work without problems you still may run into problems. The reason for this is that USB does not directly translate to serial from a hardware perspective. Data must be buffered between the two while at the same time keeping accurate timing. There is software inside the adapter which is doing that. Some software is better than others and thus you can have one serial adapter work fine while another one is not reliable and loses data. For any serious serial use, nothing beats an actual serial port which is why business grade PCs usually have them built-in or as an option. Serial to USB adapters visually look 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