virtual_instruction_breakpoint

Description

Add and remove virtual-address (and, on x86, linear-address) instruction breakpoints. Every time the processor executes an instruction that intersects the breakpoint's interval, the callback function is called with the processor, and the address and size of the instruction. (The interval includes both endpoints; first must be less than or equal to last.)

The callback is called before the instruction is executed. If one or more breakpoint callbacks stop the simulation, the stop takes effect before the instruction is run. (This means that once the simulation starts again, the same breakpoints will trigger immediately again. The callback can use VT_step_stamp to detect re-triggering.) If more than one breakpoint is triggered by the same instruction, the implementation may call their callbacks in any order.

If the filter function is non-null and returns false, the callback is not called. The filter function is supplied with the instruction opcode (the raw bytes of the instruction) and a processor (which may not be the same processor that the breakpoint is set on, but is guaranteed to be of the same class). The filter may base its decision only on the opcode bytes and the string obtained by asking the processor to disassemble the instruction; this allows the implementation to cache the result and omit future calls to the filter function where the opcode and disassembly string would be the same.

On x86, the Virtual_Breakpoint_Flag_Linear flag causes the breakpoint to use linear rather than virtual addresses. Calling with unsupported flags is illegal.

Note: This interface is preliminary and may change without prior notice.

typedef enum {
        Virtual_Breakpoint_Flag_Linear = 1
} virtual_breakpoint_flags_t;

SIM_INTERFACE(virtual_instruction_breakpoint) {
        virtual_instr_bp_handle_t *NOTNULL (*add)(
                conf_object_t *NOTNULL obj,
                generic_address_t first, generic_address_t last,
                bool (*filter)(cbdata_call_t filter_data,
                               conf_object_t *NOTNULL cpu, bytes_t opcode),
                cbdata_register_t filter_data,
                void (*NOTNULL callback)(
                        cbdata_call_t callback_data, conf_object_t *NOTNULL cpu,
                        generic_address_t address, unsigned size),
                cbdata_register_t callback_data, uint32 flags);
        void (*remove)(conf_object_t *NOTNULL obj,
                       virtual_instr_bp_handle_t *NOTNULL bp_handle);
};
#define VIRTUAL_INSTRUCTION_BREAKPOINT_INTERFACE \
        "virtual_instruction_breakpoint"

Execution Context

Cell Context for all methods.