instrument/instrumentation.txt

   1 README-instrumentation\r
   2 \r
   3 To  use instrumentation features in bochs, you must compile in support for it.\r
   4 You  should  build a custom instrumentation library in a separate directory in\r
   5 the  "instrument/"  directory. To tell configure which instrumentation library\r
   6 you  want  to  use,  use  the  "--enable-instrumentation"  option. The default\r
   7 library consists of a set of stubs, and the following are equivalent:\r
   8 \r
   9   ./configure [...] --enable-instrumentation\r
  10   ./configure [...] --enable-instrumentation="instrument/stubs"\r
  11 \r
  12 You  could  make  a  separate  directory with your custom library, for example\r
  13 "instrument/myinstrument",   copy   the  contents  of  the  "instrument/stubs"\r
  14 directory to it, then customize it. Use:\r
  15 \r
  16  ./configure [...] --enable-instrumentation="instrument/myinstrument"\r
  17 \r
  18 -----------------------------------------------------------------------------\r
  19 BOCHS instrumentation callbacks\r
  20 \r
  21         void bx_instr_init(unsigned cpu);\r
  22 \r
  23 The  callback  is  called each time, when Bochs initializes the CPU object. It\r
  24 can  be  used for initialization of user's data, dynamic memory allocation and\r
  25 etc.\r
  26 \r
  27         void bx_instr_shutdown(unsigned cpu);\r
  28 \r
  29 The  callback is called each time, when Bochs destructs the CPU object. It can\r
  30 be used for destruction of user's data, allocated by bx_instr_init callback.\r
  31 \r
  32 \r
  33         void bx_instr_reset(unsigned cpu);\r
  34 \r
  35 The  callback  is called each time, when Bochs resets the CPU object. It would\r
  36 be  executed  once  at the start of simulation and each time that user presses\r
  37 RESET BUTTON on the simulator's control panel.\r
  38 \r
  39 \r
  40         void bx_instr_hlt(unsigned cpu);\r
  41 \r
  42 The  callback is called each time, when Bochs' emulated CPU enters to the HALT\r
  43 state. \r
  44 \r
  45         void bx_instr_new_instruction(unsigned cpu);\r
  46 \r
  47 The  callback  is  called  each  time,  when Bochs completes (commits) already\r
  48 finished instruction and starts a new one.\r
  49 \r
  50 \r
  51         void bx_instr_cnear_branch_taken(unsigned cpu, bx_address new_eip);\r
  52 \r
  53 The  callback  is  called  each time, when currently executed instruction is a\r
  54 conditional near branch and it is taken.\r
  55 \r
  56 \r
  57         void bx_instr_cnear_branch_not_taken(unsigned cpu);\r
  58 \r
  59 The  callback  is  called  each time, when currently executed instruction is a\r
  60 conditional near branch and it is not taken.\r
  61 \r
  62 \r
  63         void bx_instr_ucnear_branch(unsigned cpu, unsigned what, bx_address new_eip);\r
  64 \r
  65 The  callback  is  called each time, when currently executed instruction is an\r
  66 unconditional near branch (always taken).\r
  67 \r
  68 \r
  69         void bx_instr_far_branch(unsigned cpu, unsigned what, Bit16u new_cs, bx_address new_eip);\r
  70 \r
  71 The  callback  is  called each time, when currently executed instruction is an\r
  72 unconditional far branch (always taken).\r
  73 \r
  74 \r
  75         void bx_instr_opcode(unsigned cpu, Bit8u *opcode, unsigned len, bx_bool is32, bx_bool is64);\r
  76 \r
  77 The  callback  is  called  each  time,  when  Bochs  starts  to  decode  a new\r
  78 instruction.  Through  this callback function Bochs could provide an opcode of\r
  79 the instruction, opcode length and an execution mode (16/32/64).\r
  80 \r
  81 \r
  82         void bx_instr_fetch_decode_completed(unsigned cpu, const bxInstruction_c *i);\r
  83 \r
  84 The  callback  is  called  each  time,  when  Bochs  finishes  decoding of new\r
  85 instruction.  Through  this  callback  function  Bochs  could provide decoding\r
  86 information  of the instruction. The bxInstruction_c argument of the callbacks\r
  87 it  is  a  Bochs internal structure that holds all necessary information about\r
  88 currently executed instruction, such as sib/modrm bytes, execution pointer and\r
  89 etc.\r
  90 \r
  91         void bx_instr_prefix(unsigned cpu, Bit8u prefix);\r
  92 \r
  93 These  callback  functions  are called by Bochs decoding stage each time, when\r
  94 any prefix byte was decoded.\r
  95 \r
  96 \r
  97         void bx_instr_interrupt(unsigned cpu, unsigned vector);\r
  98 \r
  99 The  callback  is called each time, when Bochs simulator executes an interrupt\r
 100 (software interrupt, hardware interrupt or an exception).\r
 101 \r
 102 \r
 103         void bx_instr_exception(unsigned cpu, unsigned vector);\r
 104 \r
 105 The callback is called each time, when Bochs simulator executes an exception.\r
 106 \r
 107 \r
 108         void bx_instr_hwinterrupt(unsigned cpu, unsigned vector, Bit16u cs, bx_address eip);\r
 109 \r
 110 The  callback  is  called  each time, when Bochs simulator executes a hardware\r
 111 interrupt.\r
 112 \r
 113 \r
 114         void bx_instr_tlb_cntrl(unsigned cpu, unsigned what, Bit32u newval);\r
 115         void bx_instr_cache_cntrl(unsigned cpu, unsigned what);\r
 116 \r
 117 The  callback  is  called each time, when Bochs simulator executes a cache/tlb\r
 118 control instruction.\r
 119 \r
 120 Possible instruction types, passed through bx_instr_tlb_cntrl:\r
 121 \r
 122         #define BX_INSTR_MOV_CR3        10\r
 123         #define BX_INSTR_INVLPG         11\r
 124         #define BX_INSTR_TASKSWITCH     12\r
 125 \r
 126 Possible instruction types, passed through bx_instr_cache_cntrl:\r
 127 \r
 128         #define BX_INSTR_INVD           20\r
 129         #define BX_INSTR_WBINVD         21\r
 130 \r
 131 \r
 132         void bx_instr_prefetch_hint(unsigned cpu, unsigned what, unsigned seg, bx_address offset);\r
 133 \r
 134 The  callback  is  called  each time, when Bochs simulator executes a PREFETCH\r
 135 instruction.\r
 136 \r
 137 Possible PREFETCH types:\r
 138 \r
 139         #define BX_INSTR_PREFETCH_NTA   00\r
 140         #define BX_INSTR_PREFETCH_T0    01\r
 141         #define BX_INSTR_PREFETCH_T1    02\r
 142         #define BX_INSTR_PREFETCH_T2    03\r
 143 \r
 144 The seg/offset arguments indicate the address of the requested prefetch.\r
 145 \r
 146 \r
 147         void bx_instr_wrmsr(unsigned cpu, unsigned msr, Bit64u value);\r
 148 \r
 149 This callback is called each time when WRMSR instruction is executed.\r
 150 MSR number and written value passed as parameters to the callback function.\r
 151 \r
 152 \r
 153         void bx_instr_repeat_iteration(unsigned cpu, const bxInstruction_c *i);\r
 154 \r
 155 The  callback  is  called  each time, when Bochs simulator starts a new repeat\r
 156 iteration.\r
 157 \r
 158 \r
 159         void bx_instr_before_execution(unsigned cpu, const bxInstruction_c *i);\r
 160 \r
 161 The  callback  is  called  each time, when Bochs simulator starts a new\r
 162 instruction execution. In case of repeat instruction the callback will\r
 163 be called only once before the first iteration will be started. \r
 164 \r
 165 \r
 166         void bx_instr_after_execution(unsigned cpu, const bxInstruction_c *i);\r
 167 \r
 168 The  callback  is  called  each time, when Bochs simulator finishes any\r
 169 instruction execution. In case of repeat instruction the callback will\r
 170 be called only once after all repeat iterations. \r
 171 \r
 172 \r
 173         void bx_instr_mem_code(unsigned cpu, bx_address linear, unsigned len);\r
 174         void bx_instr_mem_data(unsigned cpu, bx_address linear, unsigned len, unsigned rw);\r
 175 \r
 176 The  callback  is called each time, when Bochs simulator executes code or data\r
 177 memory access. Possible access types are: BX_READ, BX_WRITE and BX_RW.\r
 178 \r
 179 \r
 180         void bx_instr_lin_read(unsigned cpu, bx_address lin, bx_address phy, unsigned len);\r
 181         void bx_instr_lin_write(unsigned cpu, bx_address lin, bx_address phy, unsigned len);\r
 182 \r
 183 The  callback  is  called  each  time,  when Bochs simulator executes a memory\r
 184 access.  Note  that  no  page  split  accesses will be generated because Bochs\r
 185 splits  page  split  accesses  to  two  different  memory  accesses during its\r
 186 execution flow.\r
 187 \r
 188 Currently the callbacks are not supported in case of guest-to-host-tlb feature\r
 189 enabled.\r
 190 \r
 191 \r
 192         void bx_instr_phy_read(unsigned cpu, bx_address addr, unsigned len);\r
 193         void bx_instr_phy_write(unsigned cpu, bx_address addr, unsigned len);\r
 194 \r
 195 These callback functions are a feedback from external memory system.\r
 196 \r
 197 \r
 198         void bx_instr_inp(Bit16u addr, unsigned len);\r
 199         void bx_instr_outp(Bit16u addr, unsigned len);\r
 200         void bx_instr_inp2(Bit16u addr, unsigned len, unsigned val);\r
 201         void bx_instr_outp2(Bit16u addr, unsigned len, unsigned val);\r
 202 \r
 203 These callback functions are a feedback from various system devices.\r
 204 \r
 205 -----------------------------------------------------------------------------\r
 206 Known problems:\r
 207 \r
 208 1. BX_INSTR_MEM_CODE never called from Bochs's code.\r
 209 2. BX_INSTR_LIN_READ doesn't work when Guest-To-Host-TLB feature is enabled.\r
 210 3. BX_INSTR_LIN_WRITE doesn't work when Guest-To-Host-TLB feature is enabled.\r
 211 4.\r
 212 \r
 213 While using Bochs as a reference model for simulations, the simulator needs\r
 214 information about what loads/stores are taking place with each instruction.\r
 215 Presumably,  that  is  what  the BX_INSTR_MEM_DATA() instrumentation macros\r
 216 cover (which is the place where our simulator hooks up).\r
 217 \r
 218 The RETnear_xxx() functions call access_linear() directly, rather than call\r
 219 read_virtual_xxx()  functions. This is a problem for code making use of the\r
 220 BX_INSTR_MEM_DATA()   hook  because  it  does  not  get  called  for  these\r
 221 instructions.  Should  this  be  changed along with some other instructions\r
 222 that exhibit this?\r
 223                                                         Brian Slechta\r
 224 \r
 225 Feature requests:\r
 226 \r
 227 1. BX_INSTR_CNEAR_BRANCH_NOT_TAKEN callback should have an additional \r
 228    'not taken' new_EIP parameter.\r
 229 \r
 230 2. X86-64 support\r
 231 \r
 232 3. BX_INSTR_SMI, BX_INSTR_NMI, BX_INSTR_SIPI and other external events\r
 233    callbacks\r