break_strings_v2 interface facilitates management of
string breakpoints. It is implemented by the text console and the graphics
console (but will only function when in text mode).
The text console tries to match each break string on the stream of
characters coming from the attached serial device, and if a match occurs,
the given callback function will be called. If no callback is given, the
simulation will be stopped. The graphics console behaves in the same way,
but in this case the character stream is defined by what is sent to the
console via the vga_text_update interface. Break strings
only lives during a single Simics session, they are not checkpointed.
The add method registers a breakpoint string str, and
returns a breakpoint ID, unique during the Simics session, which is also
passed to cb when the breakpoint matches. If cb is not
NULL, then this function will be called on breakpoint match,
otherwise a match stops the simulation.
The add_single method is similar to add, but the breakpoint is removed automatically after the first match.
The add_regexp method is similar to add, but the given string is interpreted as a regular expression. The support regular expression syntax is that of the Hyperscan library https://hyperscan.io.
The remove method deactivates a previously activated breakpoint.
The get_state and set_state functions can be used to
serialize and deserialize string matchers: For instance, consider a
breakpoint on the string ABC, where the characters A and
B have already been matched. If you call get_state to
retrieve the current state, then you can later call set_state
with this state on any active breakpoint that waits for ABC, which
will put that breakpoint in a state where its callback is triggered by the
character C.
The get_state function returns an attribute value of
data kind. It is only allowed to call set_state with a
value returned by get_state, for a breakpoint waiting for the
same string or regexp. The set_state function returns
NULL on success, and an error message if the state cannot be
restored. The caller is responsible for deallocating the error message
using MM_FREE.
The methods get_state and set_state were both added in
version 6.0.250 of the Simics Base package; any code that uses it will break
if used with older base packages.
SIM_INTERFACE(break_strings_v2) {
int64 (*add)(conf_object_t *NOTNULL obj, const char *str,
break_string_cb_t cb, lang_void *arg);
int64 (*add_single)(conf_object_t *NOTNULL obj, const char *str,
break_string_cb_t cb, lang_void *arg);
int64 (*add_regexp)(conf_object_t *NOTNULL obj, const char *str,
break_string_cb_t cb, lang_void *arg);
void (*remove)(conf_object_t *NOTNULL obj, int64 bp_id);
attr_value_t (*get_state)(conf_object_t *NOTNULL obj, int64 bp_id);
char *(*set_state)(conf_object_t *NOTNULL obj, int64 bp_id, attr_value_t data);
};
#define BREAK_STRINGS_V2_INTERFACE "break_strings_v2"