# Welcome to the Bochs x86 PC Emulation Software Home Page!

### Debugger Functions:

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.

### Guards:

Guards are a mechanism by which the debugger requests each simulator to stop execution and return control back to the debugger. The debugger runs each simulator for a particular number of instructions, or until certain events occur. Guards are set by the debugger, and it is up to each simulator to examine them upon and during execution of the execute() callback, and return control back to the debugger when the guard criteria are met.

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[];

### bx_guard_found[]:

It is the task of each simulator to update the bx_guard_found structure. There are some fields which are specific to the type of guard in question, and you should update those when a particular guard is encountered. Those fields are explained in more detail in the section relating to the specific guard. There are some fields which are updated for every case, no matter what the guard is. Below is a list and explanation of the usage of each field.

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
          }

### bx_guard:

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:

- BX_DBG_GUARD_ICOUNT: Instruction count.
- BX_DBG_GUARD_CTRL_C: User requested interrupt via Ctrl-C
- BX_DBG_GUARD_IADDR_VIR: Stop on this virtual instruction address
- BX_DBG_GUARD_IADDR_LIN: Stop on this linear instruction address
- BX_DBG_GUARD_IADDR_PHY: Stop on this physical instruction address

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;