What's New
V3.5 has a set of bug fixes.  No major new features.
 

Known Problems...

• The EiC interpreter has problems with error recovery with certain ?syntax? errors.  I'm looking for a simple example so I can work the EiC development community to solve the problem - if you create any simple C code that cause EiC to crash, please send it to me!

Introduction
CDBG is a hardware debugger designed for use on a x86 based PCI system. It includes an extensive set of debug commands as well as a C interpreter to allow flexible scripting and interactive diagnostic development.  CDBG is derrived from DBG - the major change is that instead of Forth, CDBG includes a C interpreter.

CDBG is a DOS based application designed to run in a variety of OS configurations. We’ve successfully used CDBG in:

• bare DOS configurations
• DOS with EMM386/HIMEM
• Windows 98 DOS box

CDBG is constantly in development - your feedback is welcome.  The revision history section can show you what's new.

*** BE CAREFUL - CDBG gives you low level access to h/w - you can easily trash memory and crash your system.

Terminology
Throughout this document, hex numbers are used unless otherwise noted. Note that CDBG (unlike its C interpreter) is case insensitive. We’ll frequently use the style $reg to emphasize that the parameter us a hex value.

Bytes are 8 bits, Words are 16 bits, Dwords are 32 bits.

Note that when specifying a memory address...

• the address is a byte offset from the base address register (BAR)
• the address is always a byte offset regardless of the operand size, i.e., byte, word, dword

Acknowledgments
Thanks to Ed Breen for the EiC interpreter source code.

Starting CDBG
CDBG is started from the DOS prompt by typing:

cdbg [options]

Command line options can be used to specify the desired target PCI device:

•  the -vpci_vendor_id and -dpci_device_id options cause CDBG to use the first PCI device found with the matching vendor and device values.  If a -n$function option is also given, the specified subfunction in the device is used.  Vendor_id, device_id, and function are all 16 bit hex values.

set DBG_VENDOR=1131
set DBG_DEVICE=8500
set DBG_FUNCTION=1

Using CDBG
CDBG can either operate in native mode or in C mode. Native mode presents a traditional user interface with a limited command set. C mode provides access to an interpreted inplementation of the C programming language that has several pre-defined C functions to allow low level access to H/W.

Core to CDBG is the concept of  Base Address Registers (BARs).  CDBG uses BARs to access the different memory spaces that many PCI devices utilize. For example, many graphics devices will use one BAR for registers and another BAR to access the video memory. CDBG’s BAR registers allow you to specify offsets into each BAR rather than having to specify an actual physical address for each command. This is very useful since the PCI BIOS is allowed to map these two BARs in different memory locations each time the system is booted. Thus, if you know that the FOO register is at offset $14 in BAR 1, you can access FOO by simply using the number $14 rather than an absolute physical address. CDBG treats BARs 7 and 9 specially. BAR 9 is pre-initialized to allow access to the bottom 1MB of PC address space - this allows easy access to peripherals (such as VGA) that use portions of the old DOS memory area. BAR 7 is used to allow access to other areas of physical memory as specified by the user - see the BAR7 command below.
 
 

'Native' CDBG Commands
CDBG has numerous 'native' commands.  These commands allow you to examine memory, IO, and configuration spaces, test memory, etc.  The commands can be broken into the following categories:

• Basic Access
• Tests
• Scripting/DOS Access
• Misc
• Prefixing

[0]cmd>

Sometimes, you want to access a memory location in a different BAR than the default for only one or two commands. CDBG allows you to do this by prepending the desired BAR to the command. For example:

[0]cmd> 1dmem 0

A command history feature has been added to allow previous commands to be recalled, edited, and re-executed.

The pci, io, and mem commands are used to access a single memory, I/O, or PCI configuration location. Each command is followed by an address and, optionally, a data value. If no data value is specified, the value at the specified address is displayed. If a data value is specified, it is written to the location.

The compare commands are used to compare memory to an expected value.  If the value does not match, an error message is printed.  If the halt flag is set, repeat_loops and scripts will also be aborted on an error.
 

After entering the command, CDBG displays the current value in the memory location, then waits for user input:

The dump command allows you to dump a range of memory locations. Again, bytes, words, and dwords variants are supported.

If no second address is specified, it is assumed to be 3Fh greater than addr1.

The fill command is used to fill a range of memory locations with a constant value. Again, bytes, words, and dwords variants are supported.

The test commands (byte, word, dword) provide rudimentary memory tests.

The memory tests operate in several phases:

• Phase 1 this portion of the test slides a 1 through the data bits in the first and last addresses to be tested. It is intended to find simple data bus open/short conditions.
• Phase 2 this portion of the test slides a 0 through the data bits in the first and last addresses to be tested. It is intended to find simple data bus open/short conditions.
• Phase 3 this section writes a pattern to all of the specified memory, then reads it back.
• Phase 4 this test writes data, then immediately reads it back. After all of the specified memory has been checked, it is re-read to re-verify the integrity.
• Phase 5 this portion slides a 1 through the address bits.

The crc command is provided to compute a 32 bit CRC of the specified memory range.

The csum command is used to compute a 16 bit checksum of the specified memory range.

Several of these commands deserve a little extra description.

BAR7 is used to access physical memory - it is very dangerous if you’re not careful. When working on devices that perform bus mastering, you frequently need to obtain access to a chunk of physical memory. BAR7 does not allocate memory - it simply lets you access it. You can do bad things to the system memory with this. The command takes two parameters: a physical address to access, and the size of the area to access. Once you have initialized BAR7, you can use normal CDBG commands to examine and change values in the physical memory. You cannot use BAR7 a second time to change the memory aperture - get it right the first time!

One trick we’ve used when working with bus mastering devices is to use a PC with a reasonable amount of memory, say 32MB. We can guess that DOS will probably not be using the upper 16MB, so, big_gulp, we assume that we can use this area as a scratch-pad for bus mastering experiments using BAR 7 to peek and poke the locations. You can get in big trouble doing this, so good luck! Remember, BAR7 just provides a way to access physical memory, it doesn’t allocate it.

ALIAS is a way to create text short-cuts. For example, if you are repeatedly typing:

ddmp 13478 134ff

alias foo ddmp 13478 134ff

HALT allows a ‘halt on error’ flag to be set or cleared. This will terminate commands that have been invoked with the ‘!’ prefix.

LAST_READ is a variable set during the execution of several of the commands. It is useful in aborting scripts, but has been largely supplanted by the flexibility provided by the C interpreter. The following commands set last_read:

If you're at all interested in using the C interpreter built into CDBG, I encourage you to visit the EiC web site to learn more about it.  Not a steep learning curve, but the site does describe the extensions, limitations, etc. of EiC.
 

• you can enter a command to the C interpreter
• you can invoke a currently defined C function, ie, printf("%x\n", 1234) ;
• you can scan through the command history buffer and execute previous commands
• you can read a file containing C routines into the intepreter using the #include directive
• you can return to the core debugger via :dbg

• As with standard C, include files allow access to predefined subroutines and operating system calls.  A special file, starteic.h, is automatically read into EiC during startup.  This file may be used to 'bring in' include files that you always want to use such as <stdio.h>.  After this file is processed during startup, cdbg automatically performs a :reset here operation to insure that the files are not erased by a :reset command.  This 'protection' of the starteic.h files is not currently in the standard EiC distribution - it is is an extension provided in cdbg.
• The #include directive or the :load command is used to read files into the C interpreter.
• When running under Windows, I frequently do development with an editor running in one window and cdbg running in another window.  As you iterate through the development cycle, you will typically read a file into the C interpreter, find errors, correct the errors with an editor, then wish to read the file into the interpreter again.  Before re-reading the file into the interpreter with the #include directive, be sure to perform a :reset operation to clear the previous contents.

 

 
 






---

----------------------------------------------------------------
EiC-COMMAND          SUMMARY DESCRIPTION
----------------------------------------------------------------
:-I path       Append path to the include-file search list.
:-L            List search paths.
:clear fname   Removes the contents of file fname from EiC.
:dbg           Return to core CDBG debugger.
:exit          Terminates an EiC session.
:files         Display the names of all included files.
:files fname   Summarize the contents of the included file `fname'.
:help          Display summary of EiC commands.
:history [N]   List the history of (N or all) input commands.
:load fname    reset the interpreter, then load the specified file.
:reset         Reset EiC back to its start state.
:reset here    Set the `reset' state to EiC's current state.
:show name     Show information about item called 'name'

Remember to use #include "filename" or :load filename to read files into the C interpreter!
 

The Command History mechanism has been extended in several ways:

• the file EiChist.lst is read into CDBG at  startup.
• the '!' prefix is used to recall previous commands
• several new 'arrow key' actions are defined

The ':show' command has been extended to list similar command names if an exact match is not found.

The ':load' command has been added as a shortcut to reset the interpreter and then load a file.  This is similar to the sequence
  :reset
  #include fname

Note that several of these history buffer control keys are extensions to EiC.
 

As defined in dbg.h, the following words have been added as extensions to C to aid in accessing hardware.

// Declarations of builtin C Functions exposed to EiC to allow
// interpreted C code access to h/w resources...

// our std shortcuts for bytes, words, dwords
#define UCHAR unsigned char
#define USHORT unsigned short
#define ULONG unsigned int
 

// print to terminal and log file
void log_print(char *msg) ;

// PCI config reg write access...
void WrCfg8(UCHAR regnum, UCHAR value) ;
void WrCfg16(UCHAR regnum, USHORT value) ;
void WrCfg32(UCHAR regnum, ULONG value) ;

// PCI config reg read access...
UCHAR RdCfg8(UCHAR regnum) ;
USHORT RdCfg16(UCHAR regnum) ;
ULONG RdCfg32(UCHAR regnum) ;

// x86 i/o routines
UCHAR inb (int port) ;
USHORT inw (int port) ;
ULONG ind (int port) ;
void outb (int port, UCHAR data) ;
void outw (int port, USHORT data) ;
void outd (int port, ULONG data) ;

// Provide a 'pointer' to access the specified the memory region
// allocated to the specified BAR.  Since CDBG works in a DPMI
// memory management environment, the pointers is NOT the same
// as the physical address specified in the BAR!
char *BarPtr(int bar) ;

// size of the current bar
int BarSize(int bar) ;

// core debug function calling...
int dbg(char *cmd_string) ;

// keyboard i/f extensions to EiC
int kbhit(void) ;
int getch(void) ;

When the native debugger receives a command, it first checks to see if a C routine has been defined with a dbg_ pre-pended to the command name.  If so, the C interpreter is called to execute the command.  If the dbg_command has not been defined, CDBG tries to execute the command from it's native command set.  This allows 'native' debugger commands to be re-defined in interpreted C.  For example:

As CDBG starts up, it tries to load the file dbg_ext.c to automatically add any extensions that you may have defined.  It first looks in the current directory, then, if needed, it scans through its default include search path.

1. If you have a sequence of EiC commands that you type frequently, you can use #define and add the commands into starteic.h file. For example:

#define QT :quit #define HI :history

Shortcut for quitting Shortcut for printing history

2. The interpreter automatically defines 2 names to help C code recognize when it's running under CDBG/EiC:

_CDBG _EiC

Bug Reports & Comments

Please email bug reports or comments to johnp (@t) probo dot com