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:
(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.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:
(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.
If you choose to use a Windows console to connect to SDM, take account of additional restrictions:
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:
- 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.
- exiting the monitor may or may not be possible depending on the reason you entered it.
- If the entry reason is a breakpoint or int 3 embedded in the application, you can type “g
” to exit. If you don’t immediately reenter the monitor because of some other fault or int 3, then you can STOP the kernel from Windows.
- If the entry reason is a hardware fault, you must clear the hardware fault before leaving the monitor via a “g
” command. This may or may not be possible depending on the code with the fault.
- If the entry reason is a hardware fault and you are unable to clear the hardware fault, then you can possibly kill the application by typing “g284:1c
”. If you don’t immediately reenter the monitor because of some other fault or int 3 and the application you are attempting to kill does not hold a region, then you can STOP the kernel from Windows. You won’t know until you try. If the application holds a region, then it is possible that the system will hang at that point and require a power cycle to reboot.
- If the entry reason is a hardware fault and you are unable kill the application by typing “g284:1c
”, then you must reset the system. If you are still at the “.. “ monitor prompt, you can type “ocf9,6 ” which will do a hardware reset. Or you can power cycle the system.
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:
- Register names
- Punctuation symbols
- Numeric expressions
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:
- 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.
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 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 and 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:
- Code your application, including the interrupt handler.
- Debug your application as much as possible without setting up the interrupt, thus without executing your interrupt handler.
- 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.
- Determine the offset of your interrupt handler using either the map file from Visual Studio or using a debugger.
- Load your application using the RT Application Loader, selecting the Debug button on the dialog.
- 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.
- 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.
- 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>
- 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.
- Once your Interrupt Handler is functioning properly, return to source-level debugging:
- Load the Spider debugger.
- Select Advanced>dh.
- You application is again debuggable with the standard debuggers.
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:
- 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.
|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:
- The memory address of the data type
- The data type in hexadecimal
- The decimal equivalent of the data type, if it has one
For example, SDM displays the long integer 11223344 as:
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.
- 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
- 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
- Decimal numbers with a magnitude greater than or equal to 0.1 and less than 1012 are displayed in the form XXXX.XXXX
- A sample of this type of display:
0080:00000000 40FE240CA0275254R 123456.7891
- 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
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:
- 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.
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.|