Copyright (c) Hyperion Entertainment and contributors.
Advanced Serial Debugging Guide
Contents
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 software-kind capability to catch the bugs (like redirecting debug outputs to memory and catch them by dumpdebugbuffer or by tools like Sashimi), still its sometime not enough. For example as we have no protection of input/intuition areas, we still can be in situation when os not operational visually, but still works. Intuition, input and any other necessary components can crashes on some hardcore bug, and while GrimReaper utility have no way to spawn itself and die, kernel, still can blown some debug information about crash on serial.
To begin with, you should know that aos4 have 2 "reapers". One its that one, user friendly utility from system:utility/ called GrimReaper. That can be called as "hi-level" one. Another "reaper" its reaper in the kernel itself (which is real reaper, and which is call user-friendly GrimReaper when time is come). So, you can imagine that when things go nasty, kernel's reaper can catch something and throw on the serial, but OS can die right after that, and visually you just see a "freeze" of OS, and you can't know what happens, and of course no stack-trace or even just dump of register's state.
That mean 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 its still possible to be in hope that system friendly GR will popup for you always and there will be nothing so hardcore which will crash intuition/input and "freeze" the OS or so, but its just not enough when it come to real work.
You may ask now why, why serial port at all is used? Why not parallel, or anything? Why all the time everyone says "use serial debugging", like there is nothing else to what you can connect your cables. The answer is in history: Serial was chosen because of simply transferring of data: bit by bit, not like for example done in parallel port. Sure, today there is different interfaces which also can throw information bit by bit (like Ethernet, Firewire and USB), but just serial port was chosen at beginning, when there wasn't any USBs or so in computers. Then, that's no surprise why on old amigaos3 which works on old commodore amigas, all the debug output go via serials. Now, we have of course different kind of hardware where USB is present, but just and because we still support old machines, and because of historic reasons, and because of easy way to works with we still use serial port for debugging purposes.
Serial and NULL-Modem
Serial
Serial port (which often called as RS-232, while in reality it is RS-232C) today is practically removed from all modern computers and replaced by USB, but still, from time to time, you can find out a x86 motherboard with serial port attached. Of course there is solutions to still have serial port on modern PC hardware like usb2serial adapters, and which we for sure need if our computer where we will catch the output didn't have serial, but about that we will talk later. Now, all what we need to know, is that all our PowerPC based Amigas (old 1200/4000 and new AmigaOne, Sams, Peg2, X1000) have Serial port and os4 kernel's reaper thrown the debug output over that serial port.
Serial port can be just 2 types of pinouts: 9 pins and 25 pins.
25 pin one, which usually called db25, was first one (and because of that we have exactly 25 pins one in old a1200/a4000), but after some years software to use only half of pins, and then 9pin one (which usually called db9, but in reality it is de9), was result of simplicity. And while a1200/a4000 have old serial connectors with 25 pins, Pegasos2, X1000, Sams have 9 pins connectors. That's in general make no differences for our topic, just if you will build your cabled from scratch, then you just should take in account where and what pins are placed.
While information given there is enough for our article, you still can check Wikipedia for more info about serial port and rs232c standard itself: http://en.wikipedia.org/wiki/Serial_port
NULL-Modem
Today, things are different. Terminals and modems are gone and computers got the same kind of serial port that terminals used to have: "DTE". As result, we can't connect them with a straight, pin-2-pin cable, because it will connect important for data transferring pins (TX to TX and RX to RX) like it was when we connect serial port with modem back in times, and that will not work. Solution is to swap necessary wires: TX from one side to RX of another side. That's already can be called as simply "Null Modem Cable" (through, without ground connected, which is better to do always).
Usually when you go to shop in 2013 and somehow found a modem-cable, it pretty possible will be _NOT_ null-modem one. You need to ask _exactly_ null-modem one, where pins will be swapped. Of course, workers at shop can even not understand what you ask, as its all very unpopular today. Visually cables just looks the same, just inside wires can be not swapped => you will have straight serial cable => nothing will works when you will try to catch your output.
NULL-Modem cable can be of 4 types:
- No hardware handshaking
This cable has only the data and signal ground wires connected. I.e. Rx, Tx and Ground. - Loop back handshaking
Just some "cheat" cable to make a fake flow control. - Partial handshaking
Advanced "cheat" cable. - 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 HW. 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 amigaos4. The reasons is that there is no more modern x86 HW (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 HW which didn't have inbuild serial port, one more serial port. Visually they looks just like this:
Can be different of course, as it just about what kind of connector. 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 ubs-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 "etherhen", 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 restested by many ppls.
Terminal Software and port settings
Now, after you have your cable connected beetwen 2 machines, you need software which will catch the data from one of sides. The "reciever" side can be and as x86 (and with windows, and with linux, and with macos, and whatever else), and amiga with amigaos, or pOS, or unixes, or whatever was done for old amiga hardware, or ppc macs, or any kind of another HW. 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 get it there: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Be sure that you get latest/full version, because in internet some stripped versions flyed where is no support of serial connections done. Normal version with working serial support will looks like this:
On amiga (if you connect 2 amigas by serial) you can use old 68k Term4.8:
On linux <insert here>
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 thats 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 HW 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 HW 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 way
As we have many different hardware on which AmigaOS can be run today, then there is no surprise that they all use different firmwares: A1/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 way
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 to troubleshoting. If you build/buy cable, adapters and all the stuff, connect everything beetwen, fireup 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. Twice recheck a cable.
The best and only one way will be a meter which set to "beep" or 0mhs, so when you will touch wires on different sides you will heard "beep" if it connected. Recheck all of them as they should be, and if all is ok, then cable is fine. If you use null-modem adapter on top of "straight" serial cable, then recheck with it anyway just in case, by the same meter.
3. Check program's settings and settings of the port if it usb-2-serial one.
Be sure that for you have right settings and in terminal software (expectually those ones about speed, flow control and parity) as well as
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]. http://wiki.amigaos.net/index.php/Debug_Kernel [4.] http://wiki.amigaos.net/index.php/Exec_Debug
