VersatileDebug --------------- The versatiledebug.library is a handy tool while developing MorphOS software. It is not required for end users. In fact it should never be required on an end user system, beside beta testing your software. Purpose -------- The main purpose of the versatiledebug.library is providing useful information to successfully debug your software. The 40 years of Amiga development have one common flaw, which even transferred to MorphOS: Debug output. Yes we have tools now to intercept debug data from serial ports and dump it as RAM-Debug, but in the end that is not the real problem. The main issue is to create the debug lines. Using nested debug lines and the lack of proper formatting is only the tip of the ice-berg. Ever tried to hex dump a structure? Ever wanted a line to separate debug sections? Right. Not fun. VersatileDebug allows all that and even more. It has a build in MungWall kind wall detection. It is no longer required to use MungWall and turn the entire operating system into a sluggish machine just to find errors within your own application. VersatileDebug only performs wall checks and pattern filling on your own application. Yes, MorphOS already has some of these options in place, but they have one critical issue. The problem is at 0x65977704! Not helpful. Performing a hex dump when reading the log is to late as the memory got mangled already with byte patterns. VersatileDebug performs an hex dump on the memory area and the two walls. So if it was an exec node or a plain string you know where to look at first glance. Even without any textual hint the structure and the length of the data may help to pinpoint the location in seconds. But this is not all. Versatiledebug.library is also tracking the memory. It is impossible to forget to free any kind of memory. As with wall hits you will get detailed information on that shady memory area and can focus on fixing the issue and not searching for the location for hours. Thats all? Wrong! Beside memory tracking the versatiledebug.library also supports resource tracking. Yes! Resource tracking. No more forgotten bitmaps, lost DOS locks or a left over readargs structure. Of course you will get detailed information on the lost resource, so you can pin point the location within your code. Since this feature is quite new there are only the most common functions of exec, dos, graphics, locale and iffparse covered, but more will follow in the future. On top of that VersatileDebug is now checking your applications stack. If your application or a component it is calling is using more than 95% of stack hell breaks loose and a warning will be dumped on every function call. Features: ---------- - Enhanced debug command which allows tricks like binary output for flags, hex dumps, repeated character output to create lines, timer delays and more. - MungWall like upper and lower memory wall checks - Randomly filled memory before allocation and after free - full memory resource tracking - resource tracking of the most common functions (memory, DOS locks, file handles, bitmaps, DOS args and more ) - stack tracking, so you can see how much stack your application needed. Also at 95% stack usage warnings will appear. How does it work ----------------- Versatiledebug.library will simply be compiled into your application. For example: You use the DOS function Open() to open a settings file. During compile the compiler will replace the dos function call with a function call into VersatileDebug, which does the tracking and calls the original Open() function itself. So all tracked functions from all libraries are gated through versatiledebug.library. Sounds complicated? No it isn´t. You mainly require one include and three macros, which will be used once. That is all. You include a config file from your application, VERSATILEDEBUG_BASE to define the library base, then use VERSATILEDEBUG_OPEN at first in main() and VERSATILE_CLOSE before returning to DOS. That is all. I included several examples to show you how to deal with it in the example folder. Any Caveats? ------------- Yes. If your application crashes it locks the database for your application. If you run it twice all resources tracked in the first instance will be reported as lost when leaving the second instance. Not a big deal. Reboot, change the ID of your application to create a new resource database or use VDebugPurge to flush your application from database. Also keep in mind that you cannot share the binary of your application without the versatiledebug.library. After compiling your application requires versatiledebug.library unless you turned debug off before compiling, which is done by a simple define. The version of the library in use must match (!) the version of the library at compile time. Before getting to exited: You must not use malloc() and releated functions. While basic malloc(), realloc(), free(), calloc() and strdup() are implemented, these are not recommended at all. Using additional functions like getline() or asprintf() will throw your application under the bus. Questions and Answers ---------------------- ° Is the versatiledebug.library stable to be used for development? The library itself is for about 10 years in use. Before it was a library it was a source code I copied over from project to project. Most MorphOS components developed by me are using it. Complex things like the notification manager MagicBeacon as well as small parts like screen bar modules. There are two huge applications using it (on my system during developing), which are SimpleCat and BoulderDäshNG. Yes, a four way scrolling video game is using the resource tracking library. But remember. During game play there is no allocation of any kind. On the other side the game has tons of Open(), ReadArgs(), AllocBitMap(), AllocVecTaskPooled(), ... and their counter parts, which all are gated through versatiledebug.library. It would dump any problem instantly. So yes! I consider this library as stable. ° Can I debug libraries and devices using versatiledebug.library? Yes. There are no limits on how to use the library and its features, if you respect the known boundaries regarding malloc() related memory. ° My application has multiple tasks and binaries. Can I use VersatileDebug? Yes, I personally used it to develop MagicBeacon, the notification manager of MorphOS, which has a main application, a library, a system preferences panel and shell commands. The only thing you need to be careful about is sending exec messages, which can be a problem. In case your application is not the receiver simply disable the memory tracking for that type of memory. Usually it is AllocMem() anyway, which is probably not used in your application anyway. ° Can I use a secondary system and debug the data via serial port? Yes, VersatileDebug is using the same debug method kputchr() to send the debug information. It is just a new way to create the debug output itself. ° Is the versatiledebug.library required to run my application? Yes and no. It depends if debug was enabled when compiling it. Without VersatileDebug enabled your application is the same as it ever was. ° Does this debug library make my application slower? Yes, but only minimal. Unlike MungWall and co. VersatileDebug only has an effect on your application itself and unless you constantly deal with memory allocation or freeing you won´t notice any slowdowns. Same for all the other tracking mechanisms. It is a little slower as memory blocks get checked on free and filled with random data to reveal other development mistakes. The tracking of other resources is also limited to your application calls and therefor not noticeable. Information gets stored or freed internally and most cpu power is used while performing the last check, when your applications exits. ° I need tracking of a specific library function, can I add it myself directly to the header myself? Unfortunately not. Even so the headers patch function calls during compilation the library needs to know which arguments to use and what to call. Depending on the functions result and input sometimes additional code is required. You can inform me and I can add the required information to the library and the function call to the list of supported tracking. ° Does VersatileDebug require additional memory? Yes, especially the memory checks require additional memory as the saftey walls need to be installed. In addition to that, every function call requires a structure to maintain resource tracking. Normal resource tracking calls eat up about 128 bytes of memory. Wall tracking about 8200 bytes per allocated memory block, but remember: This is not the end user state the actual memory usage is not important here. It is important to find any broken implementation inside your application to prevent crashing and leaking on the users end. Remember: The end user does not have a versatiledebug.library. ° What about the stack usage? It must be huge? VersatileDebug for sure takes some stack memory from your application, but it is within normal resonable range. The additional stack usage should be around 64 to 100 bytes as there are are no nested calls. If that is a problem for your application I strongly suggest to increase its stack anyway. :) ° Is the stack tracking exact? In one word: no. VersatileDebug does not patch or swap the stack. It relies on frequently calls to obtain or release memory or resources. Everytime your application does that it also calls versatiledebug.library, which then checks the current stack. However there is a 95% marker in place which will alert you on every call when it got hit just once. ° I updated VersatileDebug and now my application fails to work. Why? One simple reason. Your application needs to be recompiled. As mentioned above the library becomes part of your application. If the library got an API change it is no longer compatible. You probably should recompile the application anyway as that is the only way to get latest tracking features. The version of the library when using your application must be the same the header files based on, when compiling it. Revisions do not matter. If the version of the library changes you need to recompile your application, too.