Preparing to use SDM

Setting up SDM for debugging most situations requires an available COM port and a terminal emulator. In some circumstances SDM may be set up to use a Windows console, but only after the system has started and is successfully running.

There are the steps required to set up SDM using a serial console:

Reserve a COM port

To configure it in INtime go to Control Panel -> INtime -> Node Management.

Select your node

In the Kernel tab, change Debugger COM port to COM1 (assuming your port is COM1) and set Debugger Baud Rate to 9600. Set Start automatically to No. Save the settings.

Go to the Advanced tab. Find the section called SYSLOG and change the value of HEIMLICH from 0 to 1. This feature allows you to force entry into the monitor program.

Connect your terminal

Attach a serial terminal or terminal emulator to the COM port, with settings 9600 baud, 8 bits, 1 stop, no parity. PuTTY (http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html) is a suitable emulator if you do not already have one.

Test the connection by stopping the INtime kernel, starting the emulator on the INtime system and typing some characters.

Start the INtime kernel

Start the kernel manually from a Windows command prompt like this (assuming your node is called NodeA):

nodemgr start nodea -r

This should cause a ".." prompt to appear on the terminal. Type "g" and ENTER to continue. Continue until the hang occurs. If a fault occurred, you should see a short message on the console and a ".." prompt.

Basic debugging

When you see the prompt, here are some basic debugging commands you can use to investigate what caused the fault:

.. x

(this dumps the register contents)

.. 10 dx 

(this dumps the next 10 instructions)

.. vu 

(this attempts to unwind the stack and figure out which system call was made by the calling thread, if any)

See the following sections for details of futher commands in SDM.

Configuring SDM to use a Windows Console

This method may be useful when there is no COM port available, but it is less reliable than the COM port method. It cannot be used to debug some startup situations.

There are the steps to use a Windows console with SDM:

Go to Control Panel -> INtime -> Node Management.

Select your node

In the Kernel tab, change Debugger COM port to CONSOLE. Save the settings.

Go to the Advanced tab. Find the section called SYSLOG and change the value of HEIMLICH from 0 to 1. This feature allows you to force entry into the monitor program.

Start your application using the application loader and check the Debug checkbox in the dialog, or use a command line like this:

(where myapp.rta and "any command line arguments" should be suitably modified)

ldrta -debug -node nodea myapp.rta -a "any command line arguments"

You should see the Fault Manager dialog appear. Select the SDM Console option. After a couple of seconds another console window will appear with the SDM ".." prompt in it.

Forcing an entry to SDM

If the situation you are investigating was not caused by a fault, then it may be caused by a thread "spinning", i.e. running continuously and never allowing a lower-priority thread to run. In this situation you can press CTRL-D at the serial terminal to force an entry into SDM.

Having entered the debugger you will want to know which thread was running at the time. Here are some commands to help investigate that:

.. vk 

(this dumps the ready queue, the first value being the Heimlich thread, the second one being the thread which was running)

Make a note of the running thread handle (second in the list), and type:

.. vt WXYZ

(where WXYZ is the value of the thread handle)

This will dump the thread details in a display similar to that of INtime Explorer. The display should show a value called Owning Process, which is the handle for the process which owns this thread. Type:

.. vt PROC

(where PROC is the value of the owning process)

Again, see the following sections for more details of SDM commands.

Restrictions when using SDM

The SDM Debugger is a static debugger which means that when it is active, RTOS interrupts are disabled, which stops RTOS scheduling. If you use the SDM Debug Console, the following conditions will apply:

Given these restrictions, it is imperative that you not close the SDM Debug Console Window while in the monitor (i.e. at the monitor (“.. “) prompt). Doing so will break the Windows Debug Console interface with the kernel which will not be restored even if a new Debug Console is created. The only option in this case is to attempt a Windows Shutdown, and if this fails, to do a system power cycle.

Some useful commands

.. g 284:1c

.. o cf9, 6

Command syntax and overview

Command structure
Command line conventions
Command-editing keys
Command line history
Multiple commands on a single line
Combining commands
Repeating commands
Continuing commands

Command structure

This is the general structure of SDM commands:

[count] command [parameters]

Some commands have one or more parameters to indicate:

• Addresses
• Data
• Register names
• Punctuation symbols
• Numeric expressions
• Count

Though most parameters follow the command, the count parameters prefix the command character. Count indicates how many times you want SDM to repeat the command or how many consecutive bytes, halfwords, or words you want SDM to access. In some commands you can use count to control how many instructions SDM is to single step (go through line-by-line), which allows you to check your application for problems in each instruction.

Command line conventions

When entering SDM commands, follow these conventions:

• Enter commands in either upper- or lowercase characters.
• Include spaces anywhere in the command line except within terms.
• Enter command lines up to 128 characters long. If you exceed this limit, the terminal beeps and the command does not execute.

Command-editing keys

You can use these keys to edit the SDM command line:

Command line history

To repeat an earlier command without retyping it, enter Ctrl+B repeatedly to scroll back through previous commands. Enter Ctrl+F to scroll forward in the list. On a PC keyboard attached to a Remote INtime system, you can also use the up and down arrow keys for this purpose.

Once you have displayed an earlier command in this way, you can edit it if you choose. Then execute the command by pressing Return.

Multiple commands on a single line

You can designate multiple commands on a single line using these methods:

You can use one or a combination of these methods on a command line. In addition, you can do the following:

Combine commands
Repeat commands
Continue commands

Combining commands

Execute multiple commands on a single command line by separating them with semicolons (;). For example:

..g cs:3b7 ; d ds:4a

This executes the g command followed by the d command.

Repeating commands

Repeat a command by preceding the command with a decimal number and enclosing the command in angle brackets. For example:

..12 <g, cs:3b7>

This executes the g command 12 times.

You can nest brackets up to three levels. By combining brackets with semicolons you can repeatedly execute multiple commands. For example:

..5 <12 <g, cs:3b7> ; d ds:4a>

This repeats the g command 60 times and the d command 5 times. The order of the commands is twelve g commands followed by one d command, then twelve more g commands and one d command, and so on.

SDM interprets repeat factors (those entered at the beginning of a command) as decimal numbers. This is the only case where you do not use a T suffix after a decimal number.

Continuing commands

To execute a command or group of commands more than once, include a comma after the command or after the closing angle bracket in the command line. For example:

..10 <5 dw>,

SDM executes the d command 50 times and then displays the command followed by a dash prompt (-):

..10 <5 dw> -

If you enter another comma, the command line is executed again. If you do not want to execute the command line again, enter a carriage return.

SDM Commands

This table lists common operations available in the System Debug Monitor:

Using SDM to debug INtime software interrupt handlers

Note:   Although the above steps describe how to use SDM to debug an interrupt handler, you can use SDM to debug any INtime application. To debug an INtime application, follow the steps listed below, replacing the interrupt handler references with references to the procedure you want to debug.

To debug INtime software Interrupt Handlers using SDM:

1. Code your application, including the interrupt handler.
2. Debug your application as much as possible without setting up the interrupt, thus without executing your interrupt handler.
3. Make sure a Serial Terminal or a PC with a Terminal Emulator program is attached to the Serial Port you have configured using the Configuration utility to be your SDM Debug Terminal, or configure the CONSOLE debug port in the INtime Control Panel Local Kernel applet.
4. Determine the offset of your interrupt handler using either the map file from Visual Studio or using a debugger.
5. Load your application using the RT Application Loader, selecting the Debug button on the dialog.
6. After loading, the following message should appear on the SDM Debug Terminal:

   Break At <CS>:00401001
   ..
   

   where <CS> is your application's Virtual Segment which varies each time you load the application.

   Note also that the offset address will be different from application to application.

7. Go to the beginning of your Interrupt Handler by typing the following on the Debug Terminal keyboard:

   g,<Int Handler Address><CR>
   

   where <Int Handler Address> is the address recorded in Step 4 above.

8. Your application will run until your interrupt handler is activated, at which time the following message should appear on your SDM Debug Terminal:

   Break at <Ring 0 CS>:<Interrupt Handler Offset>
   ..
   

9. Use SDM commands to step through and debug your interrupt handler. Since this is an interrupt handler, until it works properly and calls either SignalEndOfRtInterrupt or SignalRtInterruptThread before returning, your system will be in a kernel-inconsistent state and may need rebooting.
10. Once your Interrupt Handler is functioning properly, return to source-level debugging:
    1. Load the Spider debugger.
    2. Select Advanced>dh.
    3. You application is again debuggable with the standard debuggers.

Parameters

Byte, halfword and word parameters
Term parameters
Expression parameters
Address parameters
Numeric parameters

Byte, halfword and word parameters

Byte parameters are 8-bit parameters, halfword parameters are 16-bit parameters, and word parameters are 32-bit parameters. These parameters can be hexadecimal numbers, decimal numbers, terms, expressions, registers, or ranges. SDM assumes that all byte, halfword and word values are hexadecimal. Omit the H suffix from hexadecimal values. To specify a decimal value, enter a T suffix immediately following the number.

Byte values range from 00H to 0FFH. Halfword values range from 0000H to 0FFFFH. Word values range from 00000000H to 0FFFFFFFFH. For halfword or word parameter values, enter the high byte first, then the low byte. For halfword and word value displays, the high byte value appears first followed by the low byte value. However, the system stores halfword and word values in memory with the low byte followed by the high byte.

These examples show how SDM displays byte, halfword, and word values. For example, the byte values C4, 26, F2, and 3D are in consecutive locations beginning at the address 2468:26. SDM displays these locations in bytes:

2468:00000026  C4  26  F2  3D

SDM displays these same locations in halfwords:

2468:00000026  26C4  3DF2

SDM displays these same locations in words:

2468:00000026  3DF226C4

Term parameters

A term parameter is either a number or a register. Where:

Expression parameters

An expression is a combination of terms that includes one or more signed or unsigned values.

expression term [+ | - term] [...]

Where:

Address parameters

An address parameter consists of a segment selector (base) and an offset:

segment-selector:offset

Where:

If you do not include an address in a command that requires one, SDM usually uses the contents of the data segment register (DS) as the selector and 0 as the offset.

Numeric parameters

You can use SDM to access the NPX. You can access eight NPX stack registers, the status word, the control word, the tag word, the instruction pointer, the data pointer, and the instruction opcode. Use these abbreviations to reference an NPX register in a command:

Numeric parameters are data types that the NPX supports. Numeric parameters include:

The suffixes that you use when you enter NPX data types are different from the suffixes for byte, 16-bit halfword and 32-bit word parameters. If you do not enter a suffix after an NPX data type, SDM assumes the number is decimal.

NPX data types include:

See also:

The Programmer's Reference Manual or User's Guide for your math coprocessor or floating-point unit.
NPX integers
NPX real numbers
Packed binary coded decimal (BCD) numbers
NPX number format
Decimal values
Non-numeric values
Special-case numeric values

NPX

NPX integers
NPX real numbers
Packed binary coded decimal (BCD) numbers
NPX number format

NPX integers

An NPX integer is either a signed whole number or a hexadecimal number followed by an H suffix that SDM can interpret as an integer. The following 5 lists the NPX integer types.

The numbers 1.375, -4.6, and 9.2E3 are not valid NPX integers.

If you enter a hexadecimal number with the trailing H, SDM places the number into memory exactly as you entered it at the console.

SDM recognizes three types of integers: word, short, and long.

NPX real numbers

SDM recognizes three types of real numbers: short, long, and temporary. The differences between these real number types are:

• The number of bits
• The number of significant decimal digits
• The range of decimal numbers

An NPX real number can be represented as a signed decimal number, a scientific number, or a hexadecimal followed by an R suffix. The following lists the NPX real number types.

A scientific number consists of a signed decimal number's significant digits times base 10 raised to an exponential power. Exponents range from -4930 to 4930. For example, the decimal number 300 in scientific notation is 3.0x102. Enter this number as 3E2 where E stands for exponent. Another example is the number .0040. Enter this number as 4E-3.

Packed binary coded decimal (BCD) numbers

An NPX BCD number is either a signed decimal number or a hexadecimal number followed by an H suffix.

NPX number format

SDM displays NPX data types by showing, in this order:

1. The memory address of the data type
2. The data type in hexadecimal
3. The decimal equivalent of the data type, if it has one
   For example, SDM displays the long integer 11223344 as:
   

   1111:0  0000000000AB4130H     11223344
   

   The long real number 11223344 is displayed as:
   

   1111:0  4165682600000000R     11223344
   

   The BCD number 11223344 is displayed as:
   

   1111:0  00000000000011223344T     11223344
   

When SDM displays data types, the contents of the most significant byte of the numeric memory location is in the left-most position of the hexadecimal display. The rest of the bytes follow in order of decreasing significance. SDM displays the least significant byte in the right-most position of the hexadecimal display.

When you enter NPX data types, in either hexadecimal or decimal form, enter the most significant digit first and the rest of the digits in order of decreasing significance. If you enter a number that has a smaller number of significant digits than that of the NPX data type's, SDM appends leading zeroes.

Values

Decimal values
Non-numeric values
Special-case numeric values

Decimal values

SDM displays decimal values in four different ways depending on the number's range and value.

1. Decimal numbers that are exact integers and under 12 digits long are displayed as integers with no trailing decimal point or additional zeroes. A sample long real-number display:
   

   0080:00000000 4206FEE0E1A80000R       12345678901
   

2. Decimal values that are within the field size and not exact integers, but close to an integer, are displayed in the form XXXXX.0. The suffix .0 indicates the value is close to but not exactly an integer. An example of this type of display is:
   

   0080:00000000  41D26580B4CCCCCDR      1234567891.0
   

3. Decimal numbers with a magnitude greater than or equal to 0.1 and less than 1012 are displayed in the form XXXX.XXXX
4. A sample of this type of display:
   

   0080:00000000  40FE240CA0275254R     123456.7891
   

5. Very large and very small decimal numbers are displayed in scientific notation. This format is X.XXXXEY where X.XXXX are the significant digits in the number, E is a notation that means the number which follows (Y) is an exponent. An example:
   

   0080:00000000  492C2916217B84B7R     3.14E+44
   

Non-numeric values

If the value in memory is not numeric, SDM displays the memory address followed by the hexadecimal form of the value, the sign of the number (+ or -), and either NAN (Not-A-Number) or Infinity. These nonnumeric values appear in place of a decimal equivalent of the value. Examples follow:

0080:00000000  FFFF000000000000R    -NAN
0080:00000008  7FF0000000000000R    +Infinity

Special-case numeric values

SDM identifies these special-case numeric values:

• Pseudo-zero values such as negative zeroes and zero fractions with non-zero exponents.
• Unnormalized numbers, which are numbers containing a 0 in the integer bit. The integer bit is the most significant bit of the significand, and serves as the implicit decimal point.

SDM displays pseudo-zero values as -0 (negative zero) and in the form 0Eexp where exp is the base 10 power equivalent of the binary exponent in the number.

SDM displays unnormalized numbers in NPX number format with a bit value rather than a decimal equivalent. An unnormalized number has a 0 in the integer bit. The NPX normalizes a number by converting it to scientific notation. This shifts the most significant bit to the left until a 1 is in the integer bit, and decrements the exponent by 1 for each shift left. After the number is normalized, the integer bit is implicit and is not actually stored. This is an example of a display using an unnormalized number:

0080:00000000  3FFF199999999999999AR     .2 UNNORM 3 BITS

The 3 BITS field indicates that the unnormalized number must be shifted three bits to the left to normalize it. The .2 field is the decimal value of the number if it were normalized.

Error messages

SDM displays error messages if the command is invalid or impossible to execute. If the command line that contains the errors consists of multiple commands, SDM executes any valid commands prior to the command that caused the error.