instrument/instrumentation.txt

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