void bx_dbg_exit(int code)
When there is a situation in the simulator, where you need to terminate due to an unrecoverable error (panic), call bx_dbg_exit(). Among other things, this function will call the at_exit callback function in each simulator, and ultimately call the system exit() function.
Bit8u bx_dbg_IAC(void)
The simulator's CPU code should call this function when it is acknowledging an interrupt from the PIC via the INTR line. The interrupt vector number from the PIC is returned.
Bit32u bx_dbg_inp(Bit16u addr, unsigned len)
To read data from an IO device, the simulator should call this function. Pass in the IO address addr, and the size of the IO operation len.
void bx_dbg_outp(Bit16u addr, Bit32u value, unsigned len)
To write data to an IO device, the simulator should call this function. Pass in the IO address addr, and the size of the IO operation len.
Bit8u bx_dbg_ucmem_read(Bit32u addr)
void bx_dbg_ucmem_write(Bit32u addr, Bit8u value)
For memory read/write accesses which fall in the range of 0xA0000 to 0xBFFFF, the accesses should not be to directed to the simulator's memory, since these are UnCacheable MEMory addresses. The VGA adapter maps it's memory to this range. Instead, call these functions to perform reads/writes to memory accesses in this range. For bx_dbg_ucmem_read(), pass the physical address addr, and the value of the read is returned. For bx_dbg_ucmem_write(), pass the physical address addr and value value of the write.
void bx_dbg_async_pin_ack(unsigned what, bool val)
In order for the master and slave simulators to accept changes in pins such as the A20 line, at the same point, the debugger provides a mechanism for pending the pin change, until it is acknowledged by the master simulator. The place where the change is ack'd, is recorded by the debugger. This information is used to run the slave simulator, forcing it to accept the changes at the same locale as did the master.
Initially, the IO devices call a function bx_dbg_async_pin_request(), not listed here, to record the pin change as pending. The pending status is recorded along with the guard information in bx_guard.async_changes_pending.which. This field contains a binary OR'd set of pending pin changes. Currently only A20 is supported, which is represented by the macro BX_DBG_ASYNC_PENDING_A20.
At a time prudent to your CPU simulator, check to see if there are any pending changes, that the CPU should acknowledge. If so, acknowledge them by calling bx_dbg_async_pin_ack(). The pending value of the A20 enable is stored in bx_guard.async_changes_pending.a20. Here is some sample code which performs this task, that you can insert into the appropriate place in your CPU simulator.
if (bx_guard.async_changes_pending.which) {
if (bx_guard.async_changes_pending.which & BX_DBG_ASYNC_PENDING_A20)
bx_dbg_async_pin_ack(BX_DBG_ASYNC_PENDING_A20,
bx_guard.async_changes_pending.a20);
// ...other checks here when they are supported
}
The bx_dbg_async_pin_ack() function will in turn, invoke
the set_A20() callback function in the master simulator, so you
don't have to deal with updating local A20 state in your simulator here,
as long as you handle it in set_A20(). Keep in mind, the slave
simulator will never see the code inside this sample code if-construct,
since changes are forced in the slave by the debugger at points where the master
simulator acknowledged them, not as a direct effect of the IO devices.
Guard information set by the debugger is stored in global structure bx_guard of type bx_guard_t. For reference, it's declaration is shown here, followed by an explanation of the purpose of each field. Information about the guard encountered by the simulator, and which caused control to return to the debugger is stored in the global structure bx_guard_found[] of type bx_guard_found_t. This is actually an array of structures, where bx_guard_found[0] is the first simulator with ID 0, and bx_guard_found[1] is the second simulator with ID 1. This structure is also declared below, and the text explains the information which should be returned in this structure based on the guard encountered.
typedef struct {
unsigned long guard_for;
// instruction address breakpoints
struct {
#if BX_DBG_SUPPORT_VIR_BPOINT
unsigned num_virtual;
struct {
Bit32u cs; // only use 16 bits
Bit32u eip;
unsigned bpoint_id;
} vir[BX_DBG_MAX_VIR_BPOINTS];
#endif
#if BX_DBG_SUPPORT_LIN_BPOINT
unsigned num_linear;
struct {
Bit32u addr;
unsigned bpoint_id;
} lin[BX_DBG_MAX_LIN_BPOINTS];
#endif
#if BX_DBG_SUPPORT_PHY_BPOINT
unsigned num_physical;
struct {
Bit32u addr;
unsigned bpoint_id;
} phy[BX_DBG_MAX_PHY_BPOINTS];
#endif
} iaddr;
bx_dbg_icount_t icount; // stop after completing this many instructions
// user typed Ctrl-C, requesting simulator stop at next convient spot
volatile bool interrupt_requested;
// booleans to control whether simulator should report events
// to debug controller
struct {
bool irq;
bool a20;
bool io;
bool ucmem;
bool dma;
} report;
struct {
bool irq; // should process IRQs asynchronously
bool dma; // should process DMAs asynchronously
} async;
#define BX_DBG_ASYNC_PENDING_A20 0x01
#define BX_DBG_ASYNC_PENDING_RESET 0x02
#define BX_DBG_ASYNC_PENDING_NMI 0x04
// Asynchronous changes which are pending. These are Q'd by
// the debugger, as the master simulator is notified of a pending
// async change. At the simulator's next point, where it checks for
// such events, it notifies the debugger with acknowlegement. This
// field contains a logically or'd list of all events which should
// be checked, and ack'd.
struct {
unsigned which; // logical OR of above constants
bool a20;
bool reset;
bool nmi;
} async_changes_pending;
} bx_guard_t;
typedef struct {
unsigned long guard_found;
unsigned iaddr_index;
bx_dbg_icount_t icount; // number of completed instructions
Bit32u cs; // cs:eip and linear addr of instruction at guard point
Bit32u eip;
Bit32u laddr;
bool is_32bit_code; // CS seg size at guard point
bool ctrl_c; // simulator stopped due to Ctrl-C request
} bx_guard_found_t;
extern bx_guard_t bx_guard;
extern bx_guard_found_t bx_guard_found[];
unsigned long guard_found; this should be filled in with the particular guard encountered, for example if an instruction count guard is hit, set this to BX_DBG_GUARD_ICOUNT.
unsigned iaddr_index; This field is updated, whenever a virtual/linear/physical instruction address guard is hit. It is the array index into the bx_guard.iaddr.vir[], bx_guard.iaddr.lin[], or bx_guard.iaddr.phy[] arrays, whichever is appropriate.
bx_dbg_icount_t icount; This contains the number of instructions which have been completely executed, when the guard was encountered.
Bit32u cs;
Bit32u eip;
Bit32u laddr;
bool is_32bit_code;
These all relate to the same instruction address. From the debugger's
point of view, instruction addresses can be only at the beginning of
the instruction. Once an instruction is completed, use the address
of the next instruction.
Set cs and eip to the instruction's address (CS:EIP).
Set laddr to the instruction's corresponding linear address.
Set is_32bit_code to the size (0=16bit, 1=32bit) of the code
segment when the guard is encountered. This is used for disassembly.
bool ctrl_c; To allow the user to interrupt a simulator from the debug prompt, the debugger traps Ctrl-C interrupts, and sets bx_guard.interrupt_requested. Your simulator can optionally look for this, provided that the BX_DBG_GUARD_CTRL_C bit is set in bx_guard.guard_for structure. If you chose to do so, you may look for this occurrance whenever is convenient. Set ctrl_c to 1 to signify this guard has occurred. Here' some sample code to demonstrate this:
// convenient point to see if user typed Ctrl-C
if (bx_guard.interrupt_requested && (bx_guard.guard_for & BX_DBG_GUARD_CTRL_C)) {
bx_guard_found[BX_SIM_ID].guard_found = BX_DBG_GUARD_CTRL_C;
return; // some mechanism to return control here
}
unsigned long guard_for;
This is a binary OR'd list of guards the debugger is requesting each simulator to stop on. Only if the corresponding bit is set in this field, should the simulator examine the rest of the criteria for that guard. Currently, each simulator must be capable of recognizing the following guards, and returning to the debugger when they occur:
struct { .. } iaddr;
This structure holds the guard information for instruction address guards (breakpoints). Depending upon your selections, after editing config.h in the main directory (generated by running ./configure), certain types of instruction address guards are supported. Which ones, are determined by the BX_DBG_SUPPORT_VIR_BPOINT, BX_DBG_SUPPORT_LIN_BPOINT, and BX_DBG_SUPPORT_PHY_BPOINT macros.
If the guard_for field contains a set bit represented by BX_DBG_GUARD_IADDR_VIR, then the iaddr.num_virtual field holds the number of virtual instruction address guards to examine and compare to the current address. For each, you must examine the CS:EIP values stored in iaddr.vir[n], in the cs and eip subfields. If there is a match, record this in the guard found structure, and return control to the debugger:
bx_guard_found[ID].guard_found = BX_DBG_GUARD_IADDR_VIR; bx_guard_found[ID].iaddr_index = n; // array index in bx_guard.iaddr.vir[] bx_guard_found[ID].icount = .. // number of completed instructions bx_guard_found[ID].cs = .. // CS selector value bx_guard_found[ID].eip = .. // EIP value bx_guard_found[ID].laddr = .. // linear address of CS:EIP bx_guard_found[ID].is_32bit_code = .. // 0=16bit code, 1=32bit code // return control here
If the guard_for field contains a set bit represented by BX_DBG_GUARD_IADDR_LIN, then the iaddr.num_linear field holds the number of linear instruction address guards to examine and compare to the current address. For each, you must examine the linear address values stored in iaddr.lin[n], in the addr subfield. If there is a match, record this in the guard found structure, and return control to the debugger:
bx_guard_found[ID].guard_found = BX_DBG_GUARD_IADDR_LIN; bx_guard_found[ID].iaddr_index = n; // array index in bx_guard.iaddr.lin[] bx_guard_found[ID].icount = .. // number of completed instructions bx_guard_found[ID].cs = .. // CS selector value bx_guard_found[ID].eip = .. // EIP value bx_guard_found[ID].laddr = .. // linear address of CS:EIP bx_guard_found[ID].is_32bit_code = .. // 0=16bit code, 1=32bit code // return control here
If the guard_for field contains a set bit represented by BX_DBG_GUARD_IADDR_PHY, then the iaddr.num_physical field holds the number of physical instruction address guards to examine and compare to the current address. For each, you must examine the physical address values stored in iaddr.phy[n], in the addr subfield. If there is a match, record this in the guard found structure, and return control to the debugger:
bx_guard_found[ID].guard_found = BX_DBG_GUARD_IADDR_PHY; bx_guard_found[ID].iaddr_index = n; // array index in bx_guard.iaddr.phy[] bx_guard_found[ID].icount = .. // number of completed instructions bx_guard_found[ID].cs = .. // CS selector value bx_guard_found[ID].eip = .. // EIP value bx_guard_found[ID].laddr = .. // linear address of CS:EIP bx_guard_found[ID].is_32bit_code = .. // 0=16bit code, 1=32bit code // return control here
volatile bool interrupt_requested;
If the debugger has turned on the guard for a user interrupt, and the user has indeed requested one (Ctrl-C), the debugger will set this field to 1. The simulator should record this in the guard found information, and return control back to the debugger. Look above at the explanation for the bx_guard.interrupt_requested field for some sample code on how to do this.
struct { .. } async;
struct { .. } async_changes_pending;