Troubleshooting Your Software - Revision history

Janne Peräaho: Added link to the section "Understanding the alert error numbers".

2015-12-09T13:38:16Z

Added link to the section "Understanding the alert error numbers".

← Older revision		Revision as of 13:38, 9 December 2015
Line 26:		Line 26:
	Memory corruption, address errors, and illegal instruction errors are generally caused by use of an uninitialized, incorrectly initialized, or already freed/closed pointer or memory. You may be using the pointer directly, or it may be one that you placed (or forgot to place) in a structure passed to system calls. Or you may be overwriting one of your arrays, or accidentally modifying or incrementing a pointer later used in a free/close. Be sure to test the return of all open/allocation type functions before using the result, and only close/free things that you successfully opened/allocated. Use watchdog/torture utilities such as ''MemGuard'' to catch use of uninitialized pointers or freed memory, and other memory misuse problems. Use the debugging tool ''TNT'' to get additional debugging information instead of a Software Error requester. You may also be overflowing your stack - your compiler's stack checking option may be able to catch this. Cut stack usage by dynamically allocating large structures, buffers, and arrays which are currently defined inside your functions.		Memory corruption, address errors, and illegal instruction errors are generally caused by use of an uninitialized, incorrectly initialized, or already freed/closed pointer or memory. You may be using the pointer directly, or it may be one that you placed (or forgot to place) in a structure passed to system calls. Or you may be overwriting one of your arrays, or accidentally modifying or incrementing a pointer later used in a free/close. Be sure to test the return of all open/allocation type functions before using the result, and only close/free things that you successfully opened/allocated. Use watchdog/torture utilities such as ''MemGuard'' to catch use of uninitialized pointers or freed memory, and other memory misuse problems. Use the debugging tool ''TNT'' to get additional debugging information instead of a Software Error requester. You may also be overflowing your stack - your compiler's stack checking option may be able to catch this. Cut stack usage by dynamically allocating large structures, buffers, and arrays which are currently defined inside your functions.

	Corruption or crashes can also be caused by passing wrong or missing arguments to a system call (for example SetAPen(3) or SetAPen(win,3), instead of SetAPen(rp,3)). C programmers should use function prototypes to catch such errors. If using short integers be sure to explicitly type long constants as long (e.g., 42L). (For example, with short ints, 1 << 17 may become zero). If corruption is occurring during exit, use printf() (or kprintf(), etc.) with Delay(n) to slow down your cleanup and broadcast each step. See ~~<exec/alerts.h>~~ for Amiga-specific alert numbers. Also see "Crashes - After Exit" below.		Corruption or crashes can also be caused by passing wrong or missing arguments to a system call (for example SetAPen(3) or SetAPen(win,3), instead of SetAPen(rp,3)). C programmers should use function prototypes to catch such errors. If using short integers be sure to explicitly type long constants as long (e.g., 42L). (For example, with short ints, 1 << 17 may become zero). If corruption is occurring during exit, use printf() (or kprintf(), etc.) with Delay(n) to slow down your cleanup and broadcast each step. See [[Understanding the alert error numbers]] for Amiga-specific alert numbers. Also see "Crashes - After Exit" below.

	==== After Exit ====		==== After Exit ====

Alexandre Balaban: Categorized into Debug

2013-02-18T15:43:31Z

Categorized into Debug

← Older revision		Revision as of 15:43, 18 February 2013
Line 1:		Line 1:
			[[Category:Debug]]
	== Troubleshooting Your Software ==		== Troubleshooting Your Software ==

Alexandre Balaban: /* Use debugging tools */ Added internal and external links for GDB, debug kernel, db101 and memguard.

2013-02-18T15:42:11Z

Use debugging tools: Added internal and external links for GDB, debug kernel, db101 and memguard.

← Older revision		Revision as of 15:42, 18 February 2013
Line 135:		Line 135:
	=== Use debugging tools ===		=== Use debugging tools ===

	A variety of debugging tools are available to help locate faulty code. Some of these are source level and other debuggers, crash interceptors, vital watchdog and memory invalidation tools like ''MemGuard''.		A variety of debugging tools are available to help locate faulty code. Some of these are source level and other debuggers (e.g. [[GDB_for_Beginners\|GDB]] or [http://os4depot.net/index.php?function=showfile&file=development/debug/db101.lha db101]), crash interceptors, vital watchdog and memory invalidation tools like [http://os4depot.net/index.php?function=showfile&file=development/debug/memguard.lha ''MemGuard''].

			AmigaOS4's [[Debug Kernel]] is probably the first step of practical debugging.

	== A Final Word About Testing ==		== A Final Word About Testing ==

Steven Solie at 18:34, 11 September 2012

2012-09-11T18:34:24Z

← Older revision		Revision as of 18:34, 11 September 2012
Line 1:		Line 1:
	{{NeedUpdate}}
	== Troubleshooting Your Software ==		== Troubleshooting Your Software ==

Steven Solie: /* A Final Word About Testing */

2012-09-11T18:33:57Z

A Final Word About Testing

← Older revision		Revision as of 18:33, 11 September 2012
Line 140:		Line 140:
	== A Final Word About Testing ==		== A Final Word About Testing ==

	Test your program with memory watchdog and invalidation tools on a wide variety of systems and configurations. Programs with coding errors may appear to work properly on one or more configurations, but may fail or cause fatal problems on another~~. Make sure that your code is tested on both a ''68000'' and a ''68020''/''30'', on machines with and without Fast RAM, and on machines with and without enhanced chips~~. Test all of your program functions on every machine.		Test your program with memory watchdog and invalidation tools on a wide variety of systems and configurations. Programs with coding errors may appear to work properly on one or more configurations, but may fail or cause fatal problems on another. Test all of your program functions on every machine.

	Test all error and abort code. A program with missing error checks or unsafe cleanup might work fine when all of the items it opens or allocates are available, but may fail fatally when an error or problem is encountered. Try your code with missing files, filenames with spaces, incorrect filenames, cancelled requesters, Ctrl-C, missing libraries or devices, low memory, missing hardware, etc.		Test all error and abort code. A program with missing error checks or unsafe cleanup might work fine when all of the items it opens or allocates are available, but may fail fatally when an error or problem is encountered. Try your code with missing files, filenames with spaces, incorrect filenames, cancelled requesters, Ctrl-C, missing libraries or devices, low memory, missing hardware, etc.

	Test all of your text input functions with high-ASCII characters (such as the character produced by pressing Alt-F then "A"). Note that RAWKEY codes can be different keyboard characters on national keyboards (higher levels of keyboard input are automatically translated to the proper characters). If your program will be distributed internationally, support and take advantage of the additional screen lines available on a PAL system. Enhanced Agnus chip machines may be switched to be PAL or NTSC via motherboard jumper ''J102'' in ''A2000''s and jumper ''J200'' in ''A3000''s. Note that a base PAL machine will have less memory free due to the larger display size.		Test all of your text input functions with high-ASCII characters (such as the character produced by pressing Alt-F then "A"). Note that RAWKEY codes can be different keyboard characters on national keyboards (higher levels of keyboard input are automatically translated to the proper characters).

	Write good code. Test it. Then make it great.		Write good code. Test it. Then make it great.

Steven Solie: /* General Debugging Techniques */

2012-09-11T18:32:46Z

General Debugging Techniques

← Older revision		Revision as of 18:32, 11 September 2012
Line 126:		Line 126:
	== General Debugging Techniques ==		== General Debugging Techniques ==

			=== Narrow the search ===
⚫	Use methodical testing procedures, and debugging messages if necessary, to locate the problem area. Low level code can be debugged using ~~kprintf~~() serial ~~(or dprintf() parallel)~~ messages. Check the initial values, allocation, use, and freeing of all pointers and structures used in the problem area. Check that all of your system and internal function calls pass correct initialized arguments, and that all possible error returns are checked for and handled.

		⚫	Use methodical testing procedures, and debugging messages if necessary, to locate the problem area. Low level code can be debugged using IExec->DebugPrintf() serial messages. Check the initial values, allocation, use, and freeing of all pointers and structures used in the problem area. Check that all of your system and internal function calls pass correct initialized arguments, and that all possible error returns are checked for and handled.

			=== Isolate the problem ===

	If errors cannot be found, simplify your code to the smallest possible example that still functions. Often you will find that this smallest example will not have the problem. If so, add back the other features of your code until the problem reappears, then debug that section.		If errors cannot be found, simplify your code to the smallest possible example that still functions. Often you will find that this smallest example will not have the problem. If so, add back the other features of your code until the problem reappears, then debug that section.

			=== Use debugging tools ===
⚫	A variety of debugging tools are available to help locate faulty code. Some of these are source level and other debuggers, crash interceptors, vital watchdog and memory invalidation tools like ''~~Enforcer'' and ''MungWall~~''.

		⚫	A variety of debugging tools are available to help locate faulty code. Some of these are source level and other debuggers, crash interceptors, vital watchdog and memory invalidation tools like ''MemGuard''.

	== A Final Word About Testing ==		== A Final Word About Testing ==

Steven Solie: /* Typical Problems */

2012-09-11T18:30:52Z

Typical Problems

Show changes

Steven Solie at 16:41, 2 May 2012

2012-05-02T16:41:13Z

← Older revision		Revision as of 16:41, 2 May 2012
Line 1:		Line 1:
			{{NeedUpdate}}
	== Troubleshooting Your Software ==		== Troubleshooting Your Software ==

Steven Solie: /* Typical Problems */

2012-05-02T03:30:39Z

Typical Problems

← Older revision		Revision as of 03:30, 2 May 2012
Line 63:		Line 63:
	If memory was actually lost, and your program can be run from CLI or Workbench, then try the above procedure with both methods of starting your program. Note that under 2.0, there will be a slight permanent (until reboot) memory usage of about 672 bytes when the audio.device or narrator.device is first opened. See "Memory Loss - CLI Only" and "Memory Loss - WB Only" if appropriate. If you lose memory from both WB and CLI, then check all of the open/alloc/get/create/lock type calls in your code, and make sure that there is a matching close/free/delete/unlock type call for each of them (note - there are a few system calls that have or require no corresponding free - check the Autodocs). Generally, the close/free/delete/unlock calls should be in opposite order of the allocations.		If memory was actually lost, and your program can be run from CLI or Workbench, then try the above procedure with both methods of starting your program. Note that under 2.0, there will be a slight permanent (until reboot) memory usage of about 672 bytes when the audio.device or narrator.device is first opened. See "Memory Loss - CLI Only" and "Memory Loss - WB Only" if appropriate. If you lose memory from both WB and CLI, then check all of the open/alloc/get/create/lock type calls in your code, and make sure that there is a matching close/free/delete/unlock type call for each of them (note - there are a few system calls that have or require no corresponding free - check the Autodocs). Generally, the close/free/delete/unlock calls should be in opposite order of the allocations.

	If you are losing a fixed small amount of memory, look for a structure of that size in the Structure Offsets listing in the ~~''Amiga ROM Kernel Reference Manual: Includes and Autodocs''~~. For example, a loss of exactly 24 bytes is probably a Lock() which has not been UnLocked(). If you are using ScrollRaster(), be aware that ScrollRaster() left or right in a Superbitmap window with no TmpRas will lose memory under 1.3 (workaround - attach a TmpRas). If you lose much more memory when started from Workbench, make sure your program is not using Exit(n). This would bypass startup code cleanups and prevent a Workbench-loaded program from being unloaded. Use exit(n) instead.		If you are losing a fixed small amount of memory, look for a structure of that size in the Structure Offsets listing in the SDK. For example, a loss of exactly 24 bytes is probably a Lock() which has not been UnLocked(). If you are using ScrollRaster(), be aware that ScrollRaster() left or right in a Superbitmap window with no TmpRas will lose memory under 1.3 (workaround - attach a TmpRas). If you lose much more memory when started from Workbench, make sure your program is not using Exit(n). This would bypass startup code cleanups and prevent a Workbench-loaded program from being unloaded. Use exit(n) instead.

	Make sure you are testing in a standard environment. Some third-party shells dynamically allocate history buffers, or cause other memory fluctuations. Also, if your program executes different code when started from CLI, check that code and its cleanup. And check your startup.asm if you wrote your own.		Make sure you are testing in a standard environment. Some third-party shells dynamically allocate history buffers, or cause other memory fluctuations. Also, if your program executes different code when started from CLI, check that code and its cleanup. And check your startup.asm if you wrote your own.

Steven Solie: /* Typical Problems */

2012-04-16T19:01:28Z

Typical Problems

Show changes