Contents |
SmartProbe acts as a "GDB Stub". As such, its API is GDB compliant.
The following is a summary of GDB 7.1 commands that the SmartProbe firmware supports. See the GDB documentation for more details on any of these commands. The text here is meant to serve as a supplement to the GDB documentation without trying to replicate it. The GDB documentation can be found at http://www.gnu.org/software/gdb/documentation/. Note that Sage Electronic Engineering is not responsible for any content on the www.gnu.org website.
Purpose
Continue command. Used to sequence x86 program by releasing control of the target.
Probe Actions Taken
Probe releases the target to run freely.
Note: If no breakpoints are configured, the probe will not regain control of the target. The user can regain control via sending a Ctrl-C (0x03) to the probe.
Involves target
Yes
Example Usage via GDB
Send: (gdb) c
Response: Continuing.
Example Usage via API
Send: $c#63
Response: +
Purpose
Single-step commands. Used to sequence an x86 program by executing one, and only one, opcode.
Note that the GDB command "step" sequences the program by one source-line. For source written in assembly language, step and stepi are the same. For higher levels languages one "step" command may comprise one or more "stepi" commands. It also may comprise NO stepi commands but instead use the "c" command with a breakpoint. GDB makes the determination as how to translate "step" into probe commands.
Probe Actions Taken
Probe sequences the target one x86 opcode.
Involves target
Yes
Example Usage via GDB
Send: (gdb) stepi
Response: (gdb)
Purpose
Set (Z) or clear (z) a breakpoint or watchpoint
Probe Actions Taken
Breakpoint or watchpoint is set according to passed parameters
Involves target
Yes.
Set a software breakpoint via GDB
Send: (gdb) break *0x100000
Response: Breakpoint 1 at 0x100000
Clear a software breakpoint via GDB
Send: N/A for probe. The GDB command is "delete" but this sends no commands to the probe. Note that GDB sets all configured breakpoints when the user types "c" (continue) and removes all configured breakpoints when a breakpoint is hit or the user presses Ctrl-C (abort).
Set a HARDWARE breakpoint via GDB
Send: (gdb) hbreak main (note in this example a symbol is used. This requires that a symbol file was loaded into GDB)
Response: Hardware assisted breakpoint 2 at main
Clear a HARDWARE breakpoint via GDB
Send: N/A for probe. The GDB command is "delete" but this sends no commands to the probe. Note that GDB sets all configured breakpoints when the user types "c" (continue) and removes all configured breakpoints when a breakpoint is hit or the user presses Ctrl-C (abort).
Purpose
Terminate the current debug session
Probe Actions Taken
ACK response sent to GDB
After ACK is sent:
Target is released; execution resumes at cs:eip. Target state is as the user left it therefore proper target behavior is not guaranteed.
Involves target
Yes
Example Usage via GDB
Send: (gdb) k
Response: Kill the program being debugged? (y or n)
Purpose
Return all of the processor registers.
Probe Actions Taken
Read current values from target and return them to the caller. Also cache the values internally.
Involves target
Yes
Example Usage via GDB
Send: (gdb) flush
Response: Register cache flushed.
Purpose
Set the value of a single processor register.
Probe Actions Taken
Updates one processor register
Involves target
Yes
Example Usage via GDB
Send: (gdb) set $pc=0x100000
Response: (gdb)
Purpose
Get the value of one processor register
Probe Actions Taken
Returns current value of requested processor register
Involves target
Yes
Example Usage via GDB
Send: (gdb) print $pc
Response: $1 = (void (*)()) 0x100000 <_entry>
This formatting requires that symbols are loaded.
Purpose
Unconditionally resets the target system.
Requires that the SmartProbe reset cable be attached to the target.
This command causes the probe to disconnect from the target. It is necessary to execute "monitor halt" to regain control of the target after executing this command.
Probe Actions Taken
Probe pulses the reset line via the reset cable.
Response packet is returned AFTER completion of the reset event
Involves target
Yes
Example Usage via GDB
Send: (gdb) monitor reset
Response: (gdb)
Purpose
Unconditionally releases the target. Target starts executing code at current CS:EIP
If breakpoints or watchpoints are configured and the target hits them, control will be returned to the probe and user.
Probe Actions Taken
Probe issues appropriate command to release the target.
ACK is returned immediately
If no breakpoints or watchpoints are hit, this is all the probe returns.
If a breakpoint or watchpoint is hit, the probe returns S05 when the event occurs.
The probe will return an E64 error if the target is already running (re: not halted).
Involves target
Yes
Example Usage via GDB
Send: (gdb) monitor run
Response: (gdb)
Purpose
Unconditionally halts the target. All cores on all nodes are halted.
Probe Actions Taken
Probe issues appropriate signal (DBREQ#) to the target.
Involves target
Yes
Example Usage via GDB
Send: (gdb) monitor halt
Response: (gdb)
Purpose
Generate a delay and return control
Probe Actions Taken
Probe delays for 1us and then returns control. This command is implemented to be GDB compliant.
Involves target
NO
Purpose
Returns a list of all commands support by the GDB monitor command
Probe Actions Taken
Returns a NULL terminated list of monitor commands support by the current version of firmware.
Note: Commands are returned case-sensitive; SmartProbe treats commands as case-sensitive.
If a command returns an error, check the case.
Involves target
No
Example Usage via GDB
Send: (gdb) monitor help
Response:
reset
run
halt
delay
help
MSRread
MSRwrite
IOread
IOwrite
Power
PCIread
PCIwrite
RegisterRead
RegisterWrite
JTAGXCV
Target
Version
HaltOnReset
Probe
Node
Update
NVStorage
UserRegs
Features
CarOnReset
Purpose
Read target memory
Probe Actions Taken
Probe reads memory from target and returns it to caller in binary format
Involves target
Yes
Example Usage via GDB
Send: (gdb) x/20xb 0x100000
Read 20 bytes from 0x100000 and display in hex. See the GDB documentation for other ways to use this command.
Response: When GDB displays this data is appears as follows. This formatting is added by GDB.
0x100000: 0xe8 0x23 0x00 0x00 0x00 0xc3 0x66 0x90
0x100008: 0x02 0xb0 0xad 0x1b 0x03 0x00 0x01 0x00
0x100010: 0xfb 0x4f 0x51 0xe4
Purpose
Write to target memory; data sent in binary format with escape characters.
Syntax
$X<mem addr>,<length>:<binary data>#<checksum>
NOTE: The mem addr, length, and checksum are understood to be hex values
NOTE: The binary data must escape special characters such as '$' and '#'
Probe Actions Taken
Probe removes escape characters and then writes data to memory.
If address is in range of the SPI ROM, probe automatically switches to programming in flash mode.
Involves target
Yes
Example Usage via GDB
See either the "load" (for ELF files) or the "restore" (for binary files) command in the GDB documentation for proper usage
Purpose
Read from an I/O port. User can specify port size (1 byte, 2 bytes (1 word), 4 bytes (1 double-word (dword)).
Syntax
monitor IOread,<offset>,<size>
NOTE: Offset and size are hex values
NOTE: Size must be 1, 2, or 4 (bytes)
Probe Actions Taken
Probe reads the specified port and returns the value
The string is terminated with a carriage-return ('\n', hex 0x0A).
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb) monitor IOread,cf8,4
Response: 8000c3e8
Purpose
Write to an I/O port. User can specify port size (1 byte, 2 bytes (1 word), 4 bytes (1 double-word (dword)).
Syntax
monitor IOwrite,<offset>,<size>,<value>
NOTE: Offset, size, and value are hex values
NOTE: Size must be 1, 2, or 4 (bytes)
Probe Actions Taken
Probe writes data value to the target
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb) monitor IOwrite,cf8,4,80000000
Response: (gdb)
Purpose
Read a MSR (Machine Specific Register). These registers are defined in AMD documentation.
Syntax
monitor MSRread,<register>[,<node>,<core>]
The return value is in ASCII format and expressed as <upper 32-bits>-<lower 32-bits>
Note that a dash "-" separates the upper and lower 32-bits
NOTE: Node and core are optional - if the node/core parameters are not provided the MSR read will be automatically directed to node0:core0
Probe Actions Taken
Probe reads MSR from target and returns the result
The string is terminated with a carriage-return ('\n', hex 0x0A).
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb) monitor MSRread,C0010030
Response: 6c687441-20444d41
Purpose
Write a MSR (Machine Specific Register). These registers are defined in AMD documentation.
Syntax
monitor MSRwrite,<register>,<upper 32-bits>,<lower 32-bits>[,<node>,<core>]
The data fields are in ASCII format and expressed as <address>,<upper 32-bits>,<lower 32-bits>
Note that a comma (",") separates each data field
NOTE: Node and core are optional - if the node/core parameters are not provided the MSR write will be automatically directed to node0:core0
Probe Actions Taken
Probe updates MSR on target with new value
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb) monitor MSRwrite,C0010030,3030303030303030,3131313131313131
Response: (gdb)
Purpose
Performs an atomic PCI read from the specified address.
Syntax
monitor PCIread,<PCI addr>
NOTE: PCI addr is understood to be a hex value - do NOT put "0x" in front of the addr
Probe Actions Taken
Probe atomically reads the specified PCI address and returns the result
The string is terminated with a carriage-return ('\n', hex 0x0A).
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb) monitor PCIread,80000000
Response: 96001022
Purpose
Performs an atomic write to the specified PCI address
Syntax
monitor PCIwrite,<PCI addr>,<value>
NOTE: PCI addr and value are understood to be hex values - do NOT put "0x" in front of any value
Probe Actions Taken
Probe atomically writes to the specified PCI address
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb) monitor PCIwrite,80000010,12345678
Response: (gdb)
Purpose
Reads registers from a specific Node:Core
Syntax
monitor RegisterRead,<node>,<core>[,<register>]
NOTE: Node, core, and register are all understood to be hex values - do NOT put "0x" in front of any value
NOTE: Register is optional, if the register is omitted then all the registers will be returned (equivalent to gdb 'g' command)
Probe Actions Taken
Probe reads the requested register if present otherwise returns all registers
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb) monitor RegisterRead,0,0,8
Response: 0000fff0
Purpose
Writes one register on a specific Node:Core with the specified value
Syntax
monitor RegisterWrite,<node>,<core>,<register>=<value>
NOTE: Node, core, register, and value are all understood to be hex values - do NOT put "0x" in front of any value
Probe Actions Taken
Probe atomically writes to the specified register
Involves target
Yes. If not already halted, the target is left in a halted state after this command completes.
Example Usage via GDB
Send: (gdb)monitor RegisterWrite,0,0,8=00100000
Response: (gdb)
Purpose
Allows direct control of the JTAG scan chain though SmartProbe.
The data fields are in ASCII encoded hex format with the fields separated by commas. The outbound data is formatted as:
<TMS-pre>,<TMS-post>[,<data bit count>,<data out>]
1) TMS-pre - an 8-bit field representing a TMS bit stream to be shifted out. This field in normally used to transition to the SHIFT-IR or SHIFT-DR state. Bits are shifted out LSB first.
2) TMS-post - an 8-bit field representing a TMS bit stream to be shifted out. This field in normally used to transition from the SHIFT-IR or SHIFT-DR state back to the idle state. Bits are shifted out LSB first.
3) data bit count - an 8-bit value that allows from 1 to 256 data bits to be shifted out during the SHIFT-IR or SHIFT-DR state. The SmartProbe will always shift out data bit count + 1 bits whenever entering the SHIFT-IR or SHIFT-DR state. This field must be set to a value of zero if the SHIFT-DR or SHIFT-IR state will not be entered during this JTAGXCV command cycle.
4) data out - up to a 32-byte field containing the data to be shifted out during the SHIFT-IR or SHIFT-DR state. This field should be empty if SHIFT-DR or SHIFT-IR state will not be entered during this JTAGXCV command cycle. Less than a full 32-byte field may be sent, but results are unpredictable if less than the specified number of bits are supplied. Bits are shifted out LSB first.
Note: data bit count and out data should be omitted if the JTAG TAP controller state machine will not enter SHIFT-IR or SHIFT-DR state after the TMS-pre sequence is executed.
The inbound data will be returned formatted as:
<data in>
1) data in - up to a 32-byte field containing the data shifted in during the SHIFT-IR or SHIFT-DR state. This field is empty if SHIFT-DR or SHIFT-IR state was not entered during this JTAGXCV command cycle. Return values are always returned byte aligned, LSB first and unused MSB places will be set to zero.
Note: The JTAGXCV command should be used cautiously, as it may impact system stability. The TAP controller should always be reset and returned to the IDLE state before resuming processor control.
Probe Actions Taken
The Probe manipulates the TAP state using TMS-pre, then simultaneously shifts data out and in from the JTAG device chain, and finally manipulates the TAP state again using TMS-post.
Involves target
Yes, but processor debug state is not altered by this command.
Example Usage via GDB
Send: (gdb) monitor JTAGXCV,20,01,10,1E5FA
Response: 003F15
Sample sequence steps
1. Reset target and halt at the first instruction
2. Put JTAG TAP controller state machine into Reset state
3. Put Processor into "HDT Mode" (Enter Shift IR, shift out USE_HDT command, return to Idle state)
4. Request EIP register from Node[0], Core[0] on a single-socket platform (Enter Shift DR, shift out HDT Register Read command, return to Idle state)
5. Read back EIP register value (Enter Shift DR, shift out NULL command, return to Idle state)
Sample sequence via GDB
Send: (gdb) monitor HaltOnReset
Response: (gdb)
Send: (gdb) monitor JTAGXCV,1F,00
Response: (gdb)
Send: (gdb) monitor JTAGXCV,30,1,7,06
Response: 01
Send: (gdb) monitor JTAGXCV,20,1,4d,0a440200000000000000
Response: 01c0ffffff3f00000000
Send: (gdb) monitor JTAGXCV,20,1,4d,00000000000000000000
Response: 0100fc3f000000000000
Notes on JTAGXCV commands
1. The out data value should always be a power-of-two characters. i.e. "6" != "06" - Firmware will read "6" as "60"
2. The out data bytes are left-to-right least significant to most significant. i.e. data[0] = 0x0a, data[1] = 0x44, data[2] = 0x02, etc.
3. The in data bytes are left-to-right least significant to most significant. i.e. data[0] = 0x01, data[1] = 0x00, data[2] = 0xfc, data[3] = 0x3f, etc.
Repeat the same sequence as above, except change the data length on step #3 to 5-bits instead of 8-bits
Send: (gdb) monitor JTAGXCV,30,1,4,06
Purpose
Prepare for loading loading L1 cache with code for execution.
Requires SmartProbe reset cable to be attached to the target.
Required argument - reset type
CarOnReset,c - reset step uses cold reset (hardware cable)
CarOnReset,w - reset step uses warm reset (I/O write of 06 to port CF9)
Probe Actions Taken
Probe resets target and halts execution prior to the first opcode fetch. Reads of memory location FFFFFFF0 done by the southbridge hunt are diverted to cache so that no flash chip is required.
Example Usage via GDB
Send: (gdb) monitor CarOnReset,c
Response: (gdb)
Purpose
To request the halted state of all cores on an HDT node (aka processor)
Command Syntax
monitor HaltedCores[,<node index>]
NOTE
1. The node index is optional, the default is to query the node at position "0" in the JTAG scan chain
2. The node index is 0-based
3. The maximum supported number of nodes is 8
4. The probe will respond with "E06" if an invalid node index is requested
Response Syntax
<number of cores>:<bitmask of halted cores>
NOTE:
1. The number of cores and the bitmask of halted cores are to be interpreted as hex values
2. The string is terminated with a carriage-return ('\n', hex 0x0A).
3. The number of cores is the total count of cores on the indexed HDT node
4. The bitmask of halted cores returns 1=halted, 0=not halted for each core (core[0] = bit[0], etc.)
Probe Actions Taken
Probe scans internal data structures to determine the cores currently known state
Involves target
No
Example Usage via GDB
Send: (gdb) monitor HaltedCores
Response: 04:0000000f
Purpose
To allow debugging starting at the reset vector
Requires SmartProbe reset cable to be attached to the target.
Special: The user should issue a 'g' command ("flush" in GDB) after this command returns. This ensures that GDB or the user application has correct processor data.
Probe Actions Taken
Probe resets target and halts execution at the reset vector
Involves target
Yes
Example Usage via GDB
Send: (gdb) monitor HaltOnReset
Response: (gdb)
Purpose
Enables and configures virtual port capture
Virtual port capture allows the SmartProbe to trap I/O writes to the specified port and to return the value to the host. Possible uses are:
Get post codes without requiring additional hardware to trap values written to port 0x80
Get serial console output without requiring a serial port connection on the target system
Command Syntax
monitor Port,<I/O port addr>[,<enable flag>]
NOTE:
1. The I/O port addr is always interpreted as a hex value
2. The enable flag is optional, the default is to enable virtual port capture (1=enable, 0=disable)
3. The enable command should only be set once during a debug session
Multiple enable commands will result in hitting "phantom breakpoints" every time a virtual port event occurs
4. The disable command should be sent at the end of a debug session, or the target system should be reset, to remove the virtual port capture
Virtual Port Data Syntax
$O<data>#<checksum>
NOTE:
1. All virtual port data is transmitted in encoded ASCII - For example: "c" is converted via an 'itoa' operation to the string "63" before transmitting
2. Binary data is NOT encoded to be printable on the gdb command line console - a binary value of 1 is converted to "01" before transmitting
Probe Actions Taken
Probe configures an I/O trap and will automatically transmit characters written to that I/O port address to the host when the target system is executing
Involves target
Yes
Example Usage via GDB
Send: (gdb) monitor Port,3f8
Response: (gdb)
Virtual Port Data: coreboot
Purpose
Sets the target power state to either ON or OFF
There are three sub-commands available
on - Turn on target power
off - Turn off target power (non ACPI mode)
acpi - Turn off target power (ACPI mode)
IMPORTANT: This command returns an "OK" status immediately. This simply means the command was received and processed. It does NOT mean the power state has finished changing state.
For example, in ACPI mode it takes 4-seconds before the power goes off. The user of this command must poll the target data structure (see monitor Target) and wait for the power state indicator to change state.
Probe Actions Taken
Probe sets the target power state.
For each of these commands, the target is not halted after completion. If user wants to control the target, they must manually halt the target (if power was just applied). Target can't be halted if not powered.
Requires the SmartProbe power cable to be attached to the target.
Involves target
Yes
Example Usage via GDB
Power ON
Send: (gdb) monitor Power,on
Response: (gdb)
Power OFF with no ACPI
Send: (gdb) monitor Power,off
Response: (gdb)
Power OFF via ACPI
Send: (gdb) monitor Power,acpi
Response: (gdb)
Purpose
Return the SmartProbe firmware version string
Probe Actions Taken
Probe returns its version string.
The string is terminated with a carriage-return ('\n', hex 0x0A).
Involves target
No
Example Usage via GDB
Send: (gdb) monitor Version
Response: SmartProbe: 1.04.00
The following codes may be displayed by GDB in the form of "Remote failure reply: Exx" where 'xx' is one of the following below
NOTE: GDB will display "Protocol error with Rcmd" if any of the error codes below are returned in response to a monitor command
E01 - Unspecified Error Condition
E02 - Bad Parameter found while processing the command
E06 - The node index received in the host request is invalid
User specified an invalid node (must be 0 to 7, inclusive)
E07 - The command received from the host is not supported
User tried to invoke a deprecated command that is no longer supported
User tried to invoke a command that is not valid for the processor family detected on the target system
E60 - HDT Send Error - Probe could not send an HDT command to a node:core
E61 - HDT Receive Error - Probe sent an HDT command to the target but the node:core did not respond
The HDT command was sent to a core that is not halted
The HDT command was sent to a core that has experienced and unrecoverable error and has shutdown
E63 - Probe could not send an HDT command to a non-HDT device
The HDT command is targeting a node that is not a recognized AMD processor supported by SmartProbe
E64 - Probe could not send an HDT command to a node that is not halted
The HDT command is targeting a node that is not currently halted and in HDT mode
E66 - Core has experienced an unrecoverable error and has shutdown
The core executed a command that led to a GP fault or similar, the core must be reset before resuming
E80 - Target is not powered
E81 - The HDT cable is not plugged in
E82 - Communication with the target failed, the command timed out with no response