AmiWest 2013 Lesson 1 - Revision history

Costel Mincea: Text replacement - "" to ""

2025-01-26T19:07:28Z

Text replacement - "<syntaxhighlight>" to "<syntaxhighlight lang="C" line>"

← Older revision		Revision as of 19:07, 26 January 2025
Line 90:		Line 90:
	Type in the following program in CodeBench or whatever environment you feel comfortable with:		Type in the following program in CodeBench or whatever environment you feel comfortable with:

	<syntaxhighlight>		<syntaxhighlight lang="C" line>
	int main()		int main()
	{		{

Steven Solie: /* Crash Test */

2013-10-12T23:13:35Z

Crash Test

← Older revision		Revision as of 23:13, 12 October 2013
Line 106:		Line 106:

	Almost instantly you should see output in the Sashimi window (that's Reaper) and the Grim Reaper should have popped up on your Workbench.		Almost instantly you should see output in the Sashimi window (that's Reaper) and the Grim Reaper should have popped up on your Workbench.

			=== Step 4: Recovery ===

			With the Grim Reaper open you can press "More..." and then "Ignore DSI Errors" to allow the program to execute.

			Now normally this is a bad idea. The reason is that you don't know where data is being written in memory and it could cause anything to happen including lost data. However, in AmigaOS the address 0 is protected with hardware and is guaranteed never to be written to. That is why it is "safe" to ignore the crash in this case.

Steven Solie: /* Capturing Debug Output */

2013-10-12T22:57:44Z

Capturing Debug Output

@@ Line 73: / Line 73: @@
 It is important to remember that this window will not survive a reboot or system crash. If you want to save the output then you need to save it to a file using CTRL-F.
  Run >NIL: Sashimi CONSOLE BUFK=1024 NOPROMPT ASKEXIT ASKSAVE
-See the Sashimi documentation for what all the options mean.
+{{Note|See the Sashimi documentation for what all the options mean.}}

Steven Solie: /* Sashimi */

2013-10-12T22:14:33Z

Sashimi

← Older revision		Revision as of 22:14, 12 October 2013
Line 65:		Line 65:

	The Sashimi tool can be used to redirect the kernel console output to a window which can be very convenient when a serial link is not available.		The Sashimi tool can be used to redirect the kernel console output to a window which can be very convenient when a serial link is not available.

			To use Sashimi right now type the following into a shell:
			Run >NIL: Sashimi CONSOLE

			This will immediately open a window where the output will be going from now on.

			It is important to remember that this window will not survive a reboot or system crash. If you want to save the output then you need to save it to a file using CTRL-F.


			Then edit your S:User-Startup file and add the following line:
			Run >NIL: Sashimi CONSOLE BUFK=1024 NOPROMPT ASKEXIT ASKSAVE

			See the Sashimi documentation for what all the options mean.

Steven Solie: /* Prerequisites */

2013-10-12T22:11:14Z

Prerequisites

← Older revision		Revision as of 22:11, 12 October 2013
Line 5:		Line 5:
	== Prerequisites ==		== Prerequisites ==

	Install the [http://www.os4depot.net/index.php?function=showfile&file=development/debug/sashimi.lha Sashimi] tool somewhere in your system path. ~~Then edit your S:User-Startup file and add the following line:~~		Install the [http://www.os4depot.net/index.php?function=showfile&file=development/debug/sashimi.lha Sashimi] tool somewhere in your system path.
	Run >NIL: Sashimi CONSOLE BUFK=1024 NOPROMPT ASKEXIT ASKSAVE

	See the Sashimi documentation for what all the options mean.

	== Meet the Reapers ==		== Meet the Reapers ==

Steven Solie: /* Changing the Kernel Console Output */

2013-10-12T22:10:42Z

Changing the Kernel Console Output

← Older revision		Revision as of 22:10, 12 October 2013
Line 64:		Line 64:
	To switch back to using the private memory buffer use:		To switch back to using the private memory buffer use:
	KDebug console memory		KDebug console memory

			=== Sashimi ===

			The Sashimi tool can be used to redirect the kernel console output to a window which can be very convenient when a serial link is not available.

Steven Solie: /* Changing the Kernel Console Output */

2013-10-12T22:09:10Z

Changing the Kernel Console Output

← Older revision		Revision as of 22:09, 12 October 2013
Line 61:		Line 61:
	You may also change the kernel console output default using the KDebug command. The following will change the console to the default serial port:		You may also change the kernel console output default using the KDebug command. The following will change the console to the default serial port:
	KDebug console serial		KDebug console serial

			To switch back to using the private memory buffer use:
			KDebug console memory

Steven Solie: /* Capturing Debug Output */

2013-10-12T22:08:38Z

Capturing Debug Output

← Older revision		Revision as of 22:08, 12 October 2013
Line 51:		Line 51:
	We won't be using actual serial ports at AmiWest due to the complexity involved with having another computer to capture the output. When debugging low level things like device drivers, etc. another computer to capture serial output is absolutely essential.		We won't be using actual serial ports at AmiWest due to the complexity involved with having another computer to capture the output. When debugging low level things like device drivers, etc. another computer to capture serial output is absolutely essential.

	=== Changing the Kernel Console ===		=== Changing the Kernel Console Output ===

			There are two ways to change the kernel's default console output:
	The kernel console defaults to writing into a debug buffer.
			# Using the firmware to pass the ''serial'' parameter to the kernel.
			# Using the KDebug command from a shell.

			Each Amiga's firmware has a different method for setting firmware variables and that will not be covered here. What is important is that you pass the ''serial'' parameter to the kernel. Usually the ''os4_commandline'' variable is the correct one to use.

			You may also change the kernel console output default using the KDebug command. The following will change the console to the default serial port:

			KDebug console serial


	Interpreting the debug output of the Grim Reaper can be rather daunting and that is what we will be exploring.

	Here is an example program from which we will start working:
	<syntaxhighlight>
	#include <exec/types.h>

	int main()
	{
	uint32 *zero = 0;
	*zero = 0;
	return 0;
	}
	</syntaxhighlight>

	Although simple, this program will enable us to explore how to read the Reaper (serial port) and Grim Reaper (GUI) output. We will show you how to turn debugging symbols on and off. The stack trace will be our first stop on the road to figuring out just what happened and why.

	There is also the [[Debug_Kernel\|Exec Debug Kernel]] which will be using to help us with debugging our programs.

Steven Solie: /* Capturing Debug Output */

2013-10-12T21:55:48Z

Capturing Debug Output

← Older revision		Revision as of 21:55, 12 October 2013
Line 43:		Line 43:
	DumpDebugBuffer		DumpDebugBuffer

			If an Amiga programmer has nothing else he has this debug memory buffer to work with. The buffer is designed to survive a warm reboot.






	=== Serial ===		=== Serial ===

	The absolute best way to capture debug output is via the serial port. Ideally, that means a serial port to serial port connection~~. USB to serial port converters are also available but they are not always reliable~~. See the [[Advanced_Serial_Debugging_Guide\|Advanced Serial Debugging Guide]] for all the gory details.		The absolute best way to capture debug output is via the serial port. Ideally, that means a direct serial port to serial port connection. See the [[Advanced_Serial_Debugging_Guide\|Advanced Serial Debugging Guide]] for all the gory details.

	We won't be using actual serial ports at AmiWest due to the complexity involved with having another computer to capture the output. When debugging low level things like device drivers, etc. another computer to capture serial output is absolutely essential.		We won't be using actual serial ports at AmiWest due to the complexity involved with having another computer to capture the output. When debugging low level things like device drivers, etc. another computer to capture serial output is absolutely essential.

	=== ~~Debug~~ ~~Buffer~~ ===		=== Changing the Kernel Console ===

			The kernel console defaults to writing into a debug buffer.

Steven Solie at 21:36, 12 October 2013

2013-10-12T21:36:03Z

← Older revision		Revision as of 21:36, 12 October 2013
Line 8:		Line 8:
	Run >NIL: Sashimi CONSOLE BUFK=1024 NOPROMPT ASKEXIT ASKSAVE		Run >NIL: Sashimi CONSOLE BUFK=1024 NOPROMPT ASKEXIT ASKSAVE

	See the Sashimi documentation for what all the options ~~means~~.		See the Sashimi documentation for what all the options mean.

	== Meet the Reapers ==		== Meet the Reapers ==
Line 20:		Line 20:
	The '''Reaper''' is always running in the background and is waiting for something to do. It is launched by the Exec kernel. When Exec runs into a problem it notifies Reaper which is then responsible for handling the crash. Reaper has no GUI but it does have some limited amount of control via DOS environment variables. More information about this can be found in the [[Exec_Debug\|Exec Debug]] section.		The '''Reaper''' is always running in the background and is waiting for something to do. It is launched by the Exec kernel. When Exec runs into a problem it notifies Reaper which is then responsible for handling the crash. Reaper has no GUI but it does have some limited amount of control via DOS environment variables. More information about this can be found in the [[Exec_Debug\|Exec Debug]] section.

	Output from Reaper is to the default ~~serial~~ ~~port~~. Normally, this means the output is invisible unless you know to look for it.		Output from Reaper is directed to the default kernel console. Normally, this means the output is invisible unless you know to look for it.

	It is important to know about the Reaper because sometimes the Grim Reaper may not be able to be launched. This can happen when working with GUI applications which crash badly for example.		It is important to know about the Reaper because sometimes the Grim Reaper may not be able to be launched. This can happen when working with GUI applications which crash badly for example.
Line 28:		Line 28:
	The '''Grim Reaper''' is the tool most Amiga users get a visit from sooner or later. It is launched by the '''Reaper''' which is built into the kernel. The Grim Reaper is an application that resides in the SYS:System directory. As such, it requires many more system resources to function like DOS, BOOPSI, input.device and usually USB. If you have a crash which causes a total system freeze or the GUI is not usable you must resort back to the Reaper for assistance.		The '''Grim Reaper''' is the tool most Amiga users get a visit from sooner or later. It is launched by the '''Reaper''' which is built into the kernel. The Grim Reaper is an application that resides in the SYS:System directory. As such, it requires many more system resources to function like DOS, BOOPSI, input.device and usually USB. If you have a crash which causes a total system freeze or the GUI is not usable you must resort back to the Reaper for assistance.

	When the Grim Reaper opens up it displays a nice GUI with plenty of information about the crash site. Output can be to the default ~~serial~~ ~~port~~ and a file.		When the Grim Reaper opens up it displays a nice GUI with plenty of information about the crash site. Output can be to the default kernel console and/or a file.

	{{Note\|title=Underneath The Covers\|text=Both Reaper and the Grim Reaper utilize debugging functions provided by Exec to perform a stack trace and interpret debug symbols. See exec.doc in your SDK and look for StackTrace(), ObtainDebugSymbol(), ReleaseDebugSymbol(), ReadTaskContext() and WriteTaskContext().}}		{{Note\|title=Underneath The Covers\|text=Both Reaper and the Grim Reaper utilize debugging functions provided by Exec to perform a stack trace and interpret debug symbols. See exec.doc in your SDK and look for StackTrace(), ObtainDebugSymbol(), ReleaseDebugSymbol(), ReadTaskContext() and WriteTaskContext().}}

	== Capturing Debug Output ==		== Capturing Debug Output ==

			It can be very frustrating when you have a crash but no way to capture the crash output. We will now explore your options to make sure you get something to work from.

			=== Kernel Console ===

			Since kernel 51.44, all debug output is placed into a special private memory buffer. That means Reaper and Grim Reaper and any other output from the kernel does not appear to go anywhere. You can dump the contents of this private memory buffer using the DumpDebugBuffer command.

			Open a shell and type
			DumpDebugBuffer







			=== Serial ===

			The absolute best way to capture debug output is via the serial port. Ideally, that means a serial port to serial port connection. USB to serial port converters are also available but they are not always reliable. See the [[Advanced_Serial_Debugging_Guide\|Advanced Serial Debugging Guide]] for all the gory details.

			We won't be using actual serial ports at AmiWest due to the complexity involved with having another computer to capture the output. When debugging low level things like device drivers, etc. another computer to capture serial output is absolutely essential.

			=== Debug Buffer ===