INtime SDK Help
System Debug Monitor (SDM)

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:

  1. when at the monitor prompt (“.. “), NTX communications between Windows and the RTOS are suspended. This means that you cannot STOP the kernel from Windows until the monitor is exited.
  2. exiting the monitor may or may not be possible depending on the reason you entered it.

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.

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:

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:

Command-editing keys

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

To . . . Press these keys . . .
Tell SDM to read the command line and execute the instruction. Carriage Return
Delete the character you entered most recently. This deletes the character from both the command line and the display. If you attempt to rubout the prompt, the terminal issues a beep. Rubout or Backspace
Abort the current command and issue a prompt. However, if your application is running and it is in a loop, <Ctrl-C> has no effect. Ctrl+C
Suspend SDM's console output. SDM does not lose any output. Ctrl+S
Resume the console output suspended by Ctrl+S. Ctrl+Q
Delete the current command line. Ctrl+X

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:

To . . . Use this system call . . .
semicolon (;) A semicolon between commands lets you put more than one type of command on a single line.
n < command > A decimal number and angle brackets lets you specify n repetitions of a single command on one line.
comma (,) A comma at the end of a command line lets you repeat the command line indefinitely.

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:

To . . . Use this command . . .
Clear one or all previously set hardware or software breakpoints. bc
Set new software or hardware breakpoints, or display the current breakpoints. bs
Compare the block of memory that begins at the source address with the block of memory that begins at the destination address. c
Display either the contents of a specified block of memory (first syntax) or the contents of a descriptor table (second syntax). d
Search a specified block of memory to find a selected sequence of hexadecimal numbers. f
Execute your application program. g
Obtain and display a byte, 16-bit halfword, or 32-bit word from the port you specify. i
Copy the contents of a block of memory to a memory address you specify. m
Display single instructions in a disassembled form and then executes those instructions. n
Enter data from the first command form at the console and send it to a port. o
Display the physical base address of the page directory, which is the highest-level page table. pbdr
Display the page directory, which is a table that contains entries about the secondary page tables. pdd
Given a pointer (segmented address), display information about the physical address and indicate which page table and page in memory hold the address. pdp
Display one or more entries from a page table, which points to memory pages that hold a flat-model application's code and data. pdt
Display and change a field from a page directory entry. psd
Display change a field from a page table entry. pst
Display or change memory locations (first command form), or display or change the components of descriptor table entries (second and third command forms). s
Examine and optionally modify the contents of NPX and CPU registers such as the thread state segment. x
Display information for an INtime software system call. vc
Display the object directory for a process. vd
Display the number of free GDT slots available. vf
List the extended "v" commands with their parameters and descriptions. vh
Displays the handles in the process tree hierarchy beginning with a specified process handle. vj
Display the handles for ready and sleeping threads. vk
Display information about the objects in a process. vo
Display information about the PCI bus. vp
Display information about interrupt management. vq
Display current information about the stack and system calls on the stack. vs
Display information about an INtime kernel object. vt
Display the INtime software system calls in a thread's stack. vu

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:

number A hexadecimal or decimal number. Valid values range from 0000 to 0FFFFFFFFH. For a decimal number, enter a T suffix.
register An abbreviation for any CPU register. Registers and abbreviations for the Intel386, Intel486, and Pentium† microprocessors include:
Register name 32-bit 16-bit 8-bit
General registers EAX
EBX
ECX
EDX
EBP
ESI
EDI
AX
BS
CX
DX
BP
SI
DI
AH
BH
CH
DH
AL
BL
CL
DL
Stack pointer ESP SP
Segment register
Code
Data segment
Stack segment
Extra data segments
ESP

CS
DX
SS
ES
FS
GS
SP
Flag register EFL¹ FL¹
Instruction pointer EIP¹ IP¹
Control registers CR0¹
CR2
CR3¹
CR4¹‚²
MSW¹
¹ You canot use these registers as terms. They are included here because you can use them in commands that use registers as parameters.
² Available only on the Pentium microprocessor.

Expression parameters

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

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

Where:

term A number or a register.

Address parameters

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

segment-selector:offset

Where:

segment-selector Segment selector with a range from 0000H to 0FFFFH.
offset The offset into the selected segment with a range from 0000H to 0FFFFFFFFH.

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:

Register Name Abbreviation Register Name Abbreviation
NPX State N Status Word SW
Control Word CW Tag Word TW
Instruction Pointer IP Data Pointer DP
Instruction Opcode CP Stack Register 0 ST(0)
Stack Register 1 ST(1) Stack Register 2 ST(2)
Stack Register 3 ST(3) Stack Register 4 ST(4)
Stack Register 5 ST(5) Stack Register 6 ST(6)
Stack Register 7 ST(7)

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

Integer An integer type with three subtypes called word integer, short integer, and long integer.
Real A real type with three subtypes called short real, long real, and temporary real.
BCD Packed binary coded decimal.

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:

Data type Explicit suffix Bits Significant digits Approximate range
Word integer H 16 4 -32,768 < X < +32767
Short integer H 32 10 -2x109 < X < +2x109
Long integer H 64 19 -9x1018 < X <+9x1018
Short real R 32 6–7 8.43x10-37 < |X| < 3.37x1038
Long real R 64 15–16 4.19x10-307 < |X| < 1.67x10308
Temporary real R 80 19 3.4x10-4929 < |X| < 1.2x104929
Packed decimal (BCD) H 80 18 -99...99 < X < +99...99
(17 digits + sign digit)

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.

Data type Example
signed whole number 12, -124
hexadecimal E2H

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:

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.

Data type Example
signed decimal number 12.454, -12.454
scientific number 3E2 same as 300
hexadecimal 4E-3 same as .00403FF2R

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:

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.

Error Message Description
Bad Command You entered an invalid command.
Invalid NPX Number Format You entered an NPX value incorrectly.
Mismatched < > You entered an opening angle bracket (<) but omitted the closing angle bracket (>).
NPX Exponent is Out of Range The exponent of the NPX number you entered is not in the range of -4930 < exponent < 4930.
NPX Not Available You tried to access an NPX value when the system does not include a math coprocessor.
Syntax Error You entered a command incorrectly.
Too Many Digits in NPX Number You entered an NPX number (in decimal form) with more than 19 digits.
Illegal Selector An operation caused a reference to an invalid selector value. For example, an attempt was made to display registers with the TR register uninitialized.
No xxxx Component You specified a component in a register or descriptor table entry that is invalid.
Outside Segment An operation exceeded the limit of a segment. For example, an attempt was made to display a memory location that is beyond segment bounds or a program was executed with less than 12 bytes of level 0 stack available to SDM.