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:
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.
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 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.
When you see the prompt, here are some basic debugging commands you can use to investigate what caused the fault:
(this dumps the register contents)
.. 10 dx
(this dumps the next 10 instructions)
(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.
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.
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:
(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.
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.
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.
When entering SDM commands, follow these conventions:
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|
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.
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:
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.
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.
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.
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|
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:
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.
g,<Int Handler Address><CR>
where <Int Handler Address> is the address recorded in Step 4 above.
Break at <Ring 0 CS>:<Interrupt Handler Offset>
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:
A term parameter is either a number or a register. Where:
||A hexadecimal or decimal number. Valid values range from 0000 to 0FFFFFFFFH. For a decimal number, enter a |
||An abbreviation for any CPU register. Registers and abbreviations for the Intel386, Intel486, and Pentium† microprocessors include:
² Available only on the Pentium microprocessor.
An expression is a combination of terms that includes one or more signed or unsigned values.
expression term [+ | - term] [...]
|term||A number or a register.|
An address parameter consists of a segment selector (base) and an offset:
|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.
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)
The Programmer's Reference Manual or User's Guide for your math coprocessor or floating-point unit.
NPX real numbers
Packed binary coded decimal (BCD) numbers
NPX number format
Special-case numeric values
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.
|signed whole number||12, -124|
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.
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.
|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.
An NPX BCD number is either a signed decimal number or a hexadecimal number followed by an
SDM displays NPX data types by showing, in this order:
1111:0 0000000000AB4130H 11223344The long real number 11223344 is displayed as:
1111:0 4165682600000000R 11223344The 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.
SDM displays decimal values in four different ways depending on the number's range and value.
0080:00000000 4206FEE0E1A80000R 12345678901
0080:00000000 41D26580B4CCCCCDR 1234567891.0
0080:00000000 40FE240CA0275254R 123456.7891
0080:00000000 492C2916217B84B7R 3.14E+44
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
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.
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.
|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.|