VIRTUTECH CONFIDENTIAL    Previous - Up - Next

3.3   Simics API Functions

3.3.1   Complete List

3.3.2   Core

Attribute Values

SIM_alloc_attr_dict()

NAME

SIM_alloc_attr_dict — create empty attribute dictionary

SYNOPSIS

attr_value_t
SIM_alloc_attr_dict(int length);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Dict with size len. The dictionary elements are initialized to Sim_Val_Invalid.

SEE ALSO

SIM_alloc_attr_list

SIM_alloc_attr_list()

NAME

SIM_alloc_attr_list — create empty attribute list

SYNOPSIS

attr_value_t
SIM_alloc_attr_list(int length);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_List with size len. The list elements are initialized to Sim_Val_Invalid.

SEE ALSO

SIM_make_attr_list

SIM_ascanf()

NAME

SIM_ascanf — parse list attribute values

SYNOPSIS

int
SIM_ascanf(attr_value_t *list, const char *fmt, ...);

DESCRIPTION

Reads and converts entries in list according to the format string fmt. Returns 1 if all elements were successfully converted, 0 otherwise.

The characters in the format string mean:

format char	argument	element must be
i	integer_t *	Sim_Val_Integer
f	double *	Sim_Val_Floating
s	const char **	Sim_Val_String
S	const char **	Sim_Val_String or Sim_Val_Nil
o	conf_object_t **	Sim_Val_Object
O	conf_object_t **	Sim_Val_Object or Sim_Val_Nil
l	attr_value_t **	Sim_Val_List
d	attr_value_t **	Sim_Val_Data
a	attr_value_t **	any except Sim_Val_Invalid

The fmt string may also include a period (.) at the end, taken to mean that more elements may follow. If the period is not present, the length of the list must equal the number of specified elements.

SIM_make_attr_boolean()

NAME

SIM_make_attr_boolean — make boolean attribute

SYNOPSIS

attr_value_t
SIM_make_attr_boolean(integer_t b);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Boolean.

SIM_make_attr_data()

NAME

SIM_make_attr_data — create raw data attribute

SYNOPSIS

attr_value_t
SIM_make_attr_data(integer_t size, void *data);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Data using size and data for the binary data. No copy is made of data.

SIM_make_attr_floating()

NAME

SIM_make_attr_floating — make floating point attribute

SYNOPSIS

attr_value_t
SIM_make_attr_floating(double d);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Floating with value d.

SIM_make_attr_integer()

NAME

SIM_make_attr_integer — make integer attribute

SYNOPSIS

attr_value_t
SIM_make_attr_integer(integer_t i);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Integer with value i.

SIM_make_attr_invalid()

NAME

SIM_make_attr_invalid — make invalid attribute

SYNOPSIS

attr_value_t
SIM_make_attr_invalid(void);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Invalid.

SIM_make_attr_list()

NAME

SIM_make_attr_list, SIM_make_attr_list_vararg — make list attribute

SYNOPSIS

attr_value_t
SIM_make_attr_list(int length, ...);

attr_value_t
SIM_make_attr_list_vararg(int length, va_list va);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_List with size length. The list is filled with data from the arguments following, which should be of type attr_value_t.

SEE ALSO

SIM_alloc_attr_list

SIM_make_attr_nil()

NAME

SIM_make_attr_nil — make empty attribute

SYNOPSIS

attr_value_t
SIM_make_attr_nil(void);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Nil.

SIM_make_attr_object()

NAME

SIM_make_attr_object — make object attribute

SYNOPSIS

attr_value_t
SIM_make_attr_object(conf_object_t *obj);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_Object with value obj. Returns a Sim_Val_Nil if obj is NULL.

SIM_make_attr_string()

NAME

SIM_make_attr_string — make string attribute

SYNOPSIS

attr_value_t
SIM_make_attr_string(const char *str);

DESCRIPTION

Returns an attr_value_t of type Sim_Val_String with value str. Returns a Sim_Val_Nil if str is NULL.

Breakpoints

SIM_break_cycle()

NAME

SIM_break_cycle — insert breakpoint in time queue

SYNOPSIS

void
SIM_break_cycle(conf_object_t *obj, integer_t cycles);

DESCRIPTION

SIM_break_cycle inserts a breakpoint event at cycles clock cycles from now causing simulation to stop and returning to prompt. Useful in conjunction with a stalling timing model where there no longer is a one to one correspondence between cycles and steps.

EXCEPTIONS

General Thrown if obj is NULL.
General Thrown if clock_cycles is negative.

SIM_break_step()

NAME

SIM_break_step — set a step breakpoint

SYNOPSIS

void
SIM_break_step(conf_object_t *obj, integer_t steps);

DESCRIPTION

Sets a step breakpoint on a processor. The steps argument is the number of instructions until the break occurs.

EXCEPTIONS

General If obj is NULL, or the time specified is illegal.

SIM_breakpoint()

NAME

SIM_breakpoint — set breakpoint

SYNOPSIS

breakpoint_id_t
SIM_breakpoint(conf_object_t *obj,
               breakpoint_kind_t kind,
               access_t access,
               uint64 address,
               uint64 length,
               unsigned flags);

DESCRIPTION

Add breakpoint on an object implementing the breakpoint interface. This is typically a memory space object such as physical memory.

The kind argument sets what type of address to break on:

typedef enum {
        Sim_Break_Physical = 0,
        Sim_Break_Virtual  = 1,
        Sim_Break_Linear   = 2      /* x86 only */
} breakpoint_kind_t;

The access argument is a bit-field setting the type of access. Any combination of the tree alternatives can be given (or'ed together).

typedef enum {
        Sim_Access_Read = 1,
        Sim_Access_Write = 2,
        Sim_Access_Execute = 4
} access_t;

The address is the start of the breakpoint range and length is its length in bytes. This range will be truncated as necessary to fit in the address space. An access intersecting the given range will trigger the breakpoint. If length is zero, the breakpoint range will be the entire address space.

The flags argument should be passed a bitwise or of zero or more enumeration constants from enum breakpoint_flag:

enum breakpoint_flag {
        Sim_Breakpoint_Temporary = 1,
        Sim_Breakpoint_Simulation = 2,
        Sim_Breakpoint_Private = 4
};

If the Sim_Breakpoint_Temporary bit is set, the breakpoint is automatically disabled when triggered the first time.

If the Sim_Breakpoint_Simulation bit is set, the breakpoint will not show up in the list-breakpoints command, nor can it be removed by the unbreak command. Also, there will be no message printed on the Simics console when this breakpoint is triggered. This bit should be set when using breakpoints to simulate the target system; it will prevent Simics from temporarily disabling the breakpoint as an optimization measure. This could otherwise happen during certain reverse execution operations.

If the Sim_Breakpoint_Private bit is set, the breakpoint will not show up in the list-breakpoints command, nor can it be removed by the unbreak command. Also, there will be no message printed on the Simics console when this breakpoint is triggered.

The default action for a triggered breakpoint is to return to the frontend (this can be changed by using haps). On execution breakpoints Simics will return to the frontend before the instructions is executed, while instructions triggering read or write breakpoints will complete before control is returned to the frontend.

Several breakpoints can be set on the same address and Simics will break on them in turn. If hap handlers are connected to the breakpoints they will also be executed in turn. Hap handlers are called before the access is performed, allowing the user to read a memory value that may be overwritten by the access. See the Simics Reference Manual for a description of hap handlers.

Several attributes can be set for a breakpoint for breaking only when some conditions are true. See the breakpoints attribute in the sim class.

This function returns the breakpoint id which is used for further reference to the breakpoint:

typedef int breakpoint_id_t;

Breakpoints can be removed using SIM_delete_breakpoint().

EXCEPTIONS

General Thrown if the type or access arguments are illegal.

RETURN VALUE

Breakpoint id, -1 on exception.

SEE ALSO

SIM_breakpoint_remove, SIM_delete_breakpoint

SIM_breakpoint_remove()

NAME

SIM_breakpoint_remove — delete breakpoint range

SYNOPSIS

void
SIM_breakpoint_remove(int id,
                      access_t access,
                      generic_address_t address,
                      generic_address_t length);

DESCRIPTION

Deletes a breakpoint range from an existing breakpoint. Can thus be used to create holes in the breakpoint range. id is the breakpoint to operate on, as returned by SIM_breakpoint(). A value of zero will operate on all breakpoints that were not set using the Sim_Breakpoint_Simulation flag.

access is a bitfield describing the type of breakpoint to remove using the enumeration constants of the access_t enum.

start is the start address of the range and length is the length of the range in bytes.

EXCEPTIONS

Index Thrown if illegal breakpoint

SEE ALSO

SIM_breakpoint, SIM_delete_breakpoint

SIM_delete_breakpoint()

NAME

SIM_delete_breakpoint — delete breakpoint

SYNOPSIS

void
SIM_delete_breakpoint(breakpoint_id_t id);

DESCRIPTION

Deletes breakpoint id as returned by SIM_breakpoint(). A value of zero will delete all breakpoints that were set without the Sim_Breakpoint_Simulation flag.

EXCEPTIONS

Index Thrown if no breakpoint with the id is found.

Configuration

SIM_add_configuration()

NAME

SIM_add_configuration — set configuration from Python

SYNOPSIS

void
SIM_add_configuration(pre_conf_object_set_t *set, const char *file);

DESCRIPTION

This function is an alternative to reading the configuration from a file. A configuration is a sequence (list or tuple) of pre_conf_object Python objects, or a dictionary of the form {name : pre_conf_object}.

The file argument in the name of the file that a configuration was read from, and should be set to None/NULL if not used.

EXCEPTIONS

General Thrown if Simics fails to initialize all objects.

SEE ALSO

SIM_create_object

SIM_alloc_conf_object()

NAME

SIM_alloc_conf_object — allocate object

SYNOPSIS

conf_object_t *
SIM_alloc_conf_object(parse_object_t *pa);

DESCRIPTION

Allocate a new "bare" configuration object with no data members. This function is mainly for implementing classes in script languages.

RETURN VALUE

Returns the newly constructed object.

SIM_attribute_error()

NAME

SIM_attribute_error — specify reason for attribute error

SYNOPSIS

void
SIM_attribute_error(const char *msg);

DESCRIPTION

When used inside an attribute set_attr/get_attr method, indicates why it failed to set or retrieve the attribute. This function only serves to give an informative message to the user. The object or attribute names need not be mentioned in the msg argument; Simics will supply this automatically.

SEE ALSO

SIM_register_typed_attribute

SIM_change_attribute_attribute()

NAME

SIM_change_attribute_attribute — change requiredness of attribute

SYNOPSIS

int
SIM_change_attribute_attribute(conf_class_t *cls,
                               const char *name,
                               attr_attr_t attr);

DESCRIPTION

This function sets the attributes of an earlier registered attribute name in class class_struct to attr.

typedef enum {
        Sim_Attr_Required         = 0,
        Sim_Attr_Optional         = 1,

        Sim_Attr_Session          = 3,
        Sim_Attr_Pseudo           = 4,

        Sim_Attr_Flag_Mask        = 0xff,

        Sim_Init_Phase_Shift      = 8,
        Sim_Init_Phase_0          = 0 << Sim_Init_Phase_Shift,
        Sim_Init_Phase_1          = 1 << Sim_Init_Phase_Shift,

        Sim_Attr_Integer_Indexed  = 0x1000,
        Sim_Attr_String_Indexed   = 0x2000,
        Sim_Attr_List_Indexed     = 0x4000,
        
        Sim_Attr_Persistent       = 0x20000,

        /* set by SIM_register_*_attribute() */
        Sim_Attr_Read_Only        = 0x40000,
        Sim_Attr_Write_Only       = 0x80000

} attr_attr_t;

RETURN VALUE

Returns zero if successful, and non-zero otherwise.

EXCEPTIONS

General Thrown if at least one argument is NULL or if the attribute name is not a valid attribute for the class with class structure class_struct.

SEE ALSO

SIM_register_typed_attribute

SIM_class_has_attribute()

NAME

SIM_class_has_attribute — check if class implements attribute

SYNOPSIS

int
SIM_class_has_attribute(conf_class_t *cls, const char *attr);

DESCRIPTION

Returns 1 if the class cl implements an attribute with the name attr

SEE ALSO

SIM_register_typed_attribute, SIM_get_attribute

SIM_create_object()

NAME

SIM_create_object — create and initialise object

SYNOPSIS

conf_object_t *
SIM_create_object(conf_class_t *cls, const char *name, attr_value_t attrs);

DESCRIPTION

Creates a new instance of the configuration class cls. name must consist of a letter followed by letters, digits, hyphens (-) or underscores (_). Hyphens and underscores are equivalent, so ben_hur and ben-hur refer to the same object.

The new object is initialised with attributes from attrs, which must be a list of (attribute-name, value) pairs as two-element lists. All required attributes for the class cl must be present in attrs.

RETURN VALUE

The new object, or NULL on error (in which case an exception is raised).

EXCEPTIONS

General Thrown if either argument is NULL, the name is not well-formed, if an object named name already exists, or if the initialisation failed.

SEE ALSO

SIM_set_configuration

SIM_delete_object()

NAME

SIM_delete_object — delete object

SYNOPSIS

int
SIM_delete_object(conf_object_t *obj);

DESCRIPTION

Deletes an object. The caller should make sure that there are no references to the object being deleted, and that there are no pending events associated with the object (all such events will be removed from the event queue automatically).

RETURN VALUE

Returns zero if successful. Throws an exception and returns non-zero otherwise.

EXCEPTIONS

General Thrown if the associated class does not support object deletion (has no destructor).

SIM_ensure_partial_attr_order()

NAME

SIM_ensure_partial_attr_order — ensure attribute order

SYNOPSIS

void
SIM_ensure_partial_attr_order(conf_class_t *cls, const char *attr1,
                              const char *attr2);

DESCRIPTION

Attribute initialization order is guaranteed to be identical to the order in which the attributes were registered. In some cases a particular order is required in order for a model to work correctly.

This function checks the registration order of attr1 and attr2 in the class cls. If attr1 is not registered before attr2, or if at least one of the two are not registered at all, an ASSERT is triggered.

Use this function to ensure that e.g. code refactoring does not break a required attribute order.

SEE ALSO

SIM_register_typed_attribute

SIM_free_attribute()

NAME

SIM_free_attribute — free attribute

SYNOPSIS

void
SIM_free_attribute(attr_value_t value);

DESCRIPTION

Attributes returned by SIM_get_attribute() should be freed using this function. It doesn't actually do anything for values of a different kind than Sim_Val_List or Sim_Val_Dict.

When called with a Sim_Val_List argument, it calls SIM_free_attribute() on each element of the list before freeing the list itself.

SIM_get_all_classes()

NAME

SIM_get_all_classes — get list of all classes

SYNOPSIS

attr_value_t
SIM_get_all_classes(void);

DESCRIPTION

Return a list of the names of all configuration classes.

RETURN VALUE

List of class names.

SIM_get_all_objects()

NAME

SIM_get_all_objects — get list of all objects

SYNOPSIS

attr_value_t
SIM_get_all_objects(void);

DESCRIPTION

Return a list of all configuration objects.

RETURN VALUE

List of objects.

SIM_get_attribute()

NAME

SIM_get_attribute, SIM_get_class_attribute, SIM_get_attribute_idx, SIM_get_class_attribute_idx — get attribute

SYNOPSIS

attr_value_t
SIM_get_attribute(conf_object_t *obj, const char *name);

attr_value_t
SIM_get_class_attribute(conf_class_t *cls, const char *name);

attr_value_t
SIM_get_attribute_idx(conf_object_t *obj, const char *name,
                      attr_value_t *index);

attr_value_t
SIM_get_class_attribute_idx(conf_class_t *cls, const char *name,
                            attr_value_t *index);

DESCRIPTION

Extracts the attribute specified by the name parameter from obj. When the caller has finished using the attribute value, it should be freed using free_attribute. If an error occurs, or if the attribute is not defined for the given object, then the returned value will be of type Sim_Val_Invalid. The _idx version of the function can be used to get a single entry in a list or data attribute. The attribute must support indexing, for this to work.

Return values of kind Sim_Val_List or Sim_Val_Dict have to be freed using SIM_free_attribute().

RETURN VALUE

Attribute value. The kind field in the returned structure is Sim_Val_Invalid if the attribute could not be found.

EXCEPTIONS

General If either argument is NULL.

SEE ALSO

SIM_free_attribute, SIM_set_attribute

SIM_get_attribute_attributes()

NAME

SIM_get_attribute_attributes — get attribute flags

SYNOPSIS

attr_attr_t
SIM_get_attribute_attributes(conf_class_t *cls, const char *attr);

DESCRIPTION

Returns the attribute flags of the attr attribute of the configuration object obj.

SIM_get_attribute_attributes() with an object as parameter is deprecated since Simics 3.0.

SEE ALSO

SIM_register_typed_attribute, SIM_change_attribute_attribute

SIM_get_class()

NAME

SIM_get_class — get class

SYNOPSIS

conf_class_t *
SIM_get_class(const char *name);

DESCRIPTION

Returns the configuration class called name.

RETURN VALUE

Opaque pointer referencing the class, or NULL if not found.

EXCEPTIONS

General Thrown if the class has not been registered or if name is NULL.

SEE ALSO

SIM_get_class_name

SIM_get_class_name()

NAME

SIM_get_class_name — get class name

SYNOPSIS

const char *
SIM_get_class_name(const conf_class_t *class_data);

DESCRIPTION

Returns the name of the class

SEE ALSO

SIM_get_class

SIM_get_configuration_file_prefix()

NAME

SIM_get_configuration_file_prefix — get filename prefix

SYNOPSIS

const char *
SIM_get_configuration_file_prefix(void);

DESCRIPTION

An object that wants to create a file as part of an attribute value should request a filename prefix using this function. The image class uses this feature to store memory in a separate file.

RETURN VALUE

Null-terminated prefix string, or NULL if called outside a configuration.

SIM_get_interface()

NAME

SIM_get_interface, SIM_get_class_interface, SIM_get_port_interface, SIM_get_class_port_interface — get interface

SYNOPSIS

void *
SIM_get_interface(const conf_object_t *obj, const char *name);

void *
SIM_get_class_interface(const conf_class_t *cls, const char *name);

void *
SIM_get_port_interface(const conf_object_t *obj, const char *name,
                       const char *portname);

void *
SIM_get_class_port_interface(const conf_class_t *cls,
                              const char *name, const char *portname);

DESCRIPTION

Get the interface with name name from object obj. Returns NULL, and raises an exception if obj does not implement the interface.

SIM_get_port_interface() returns an port interface instance as registered with SIM_register_port_interface(). The portname selects a particular implementation of the interface by obj's class. If no instance name is supplied, the function behaves as SIM_get_interface().

If a class only defines a single port interface, it may be looked up using SIM_get_interface() as well.

SIM_get_class_interface and SIM_get_class_port_interface are similar but return the interface for a class instead of an object.

RETURN VALUE

Pointer to interface, or NULL if not found.

EXCEPTIONS

Lookup Thrown if the interface is not implemented by obj's class.
General Thrown if the interface name is illegal.

SEE ALSO

SIM_register_interface, SIM_register_port_interface

SIM_get_object()

NAME

SIM_get_object — get object

SYNOPSIS

conf_object_t *
SIM_get_object(const char *name);

DESCRIPTION

Returns the object with name name.

struct conf_object {
        conf_class_t *class_data;  /* class data */
        const char *name;          /* instance name */
        struct conf_object *queue; /* queue */
        lang_void *object_data;    /* internal to class implementation */
        int object_id;             /* deprecated, do not use */
        int configured;            /* set when configuration ready */
};

typedef struct conf_object conf_object_t;

RETURN VALUE

Pointer to object, or NULL if not found.

EXCEPTIONS

GeneralThrown if the object can not be found or if name is NULL.

SIM_initial_configuration_ok()

NAME

SIM_initial_configuration_ok — get configuration status

SYNOPSIS

int
SIM_initial_configuration_ok(void);

DESCRIPTION

Returns non-zero if a configuration has been loaded into Simics (e.g., using read-configuration), or zero otherwise.

SIM_new_object()

NAME

SIM_new_object — create object

SYNOPSIS

conf_object_t *
SIM_new_object(conf_class_t *cls, const char *name);

DESCRIPTION

Creates a new instance of the configuration class the_class. name must consist of a letter followed by letters, digits, hyphens (-) or underscores (_). Hyphens and underscores are equivalent, so ben_hur and ben-hur refer to the same object.

---

Note: This function is deprecated. It can only safely be used to create objects that have no required attributes or no finalisation method. In other cases, SIM_create_object or SIM_set_configuration must be used.

---

RETURN VALUE

Pointer to new object, or NULL on error (in which case an exception is raised).

EXCEPTIONS

General Thrown if either argument is NULL, if no configuration has been loaded, or if an object with name name already exists.

SEE ALSO

SIM_create_object, SIM_set_configuration

SIM_object_constructor()

NAME

SIM_object_constructor — base class constructor

SYNOPSIS

void
SIM_object_constructor(conf_object_t *obj, parse_object_t *pobj);

DESCRIPTION

This constructor should be called by new_instance functions (see the class_data_t structure) to initialize a new object. If the new object is a log_object_t, the SIM_log_constructor() function should be used instead.

SIM_object_is_processor()

NAME

SIM_object_is_processor — test if object is a processor

SYNOPSIS

int
SIM_object_is_processor(conf_object_t *obj);

DESCRIPTION

Returns non-zero if obj is a processor.

SIM_read_configuration()

NAME

SIM_read_configuration — read configuration

SYNOPSIS

void
SIM_read_configuration(const char *file);

DESCRIPTION

Read configuration from filename and create a machine accordingly. Can only be issued once per session. This function will exit the simulator on certain error conditions (such as license violations).

EXCEPTIONS

General Thrown if the file could not be opened, the machine was already initialized, or if an error in the configuration file was detected.

SIM_register_attribute()

NAME

SIM_register_attribute, SIM_register_class_attribute — register attribute

SYNOPSIS

int
SIM_register_attribute(
        conf_class_t *cls, const char *name,
        attr_value_t (*get_attr)(lang_void *user_data,
                                 conf_object_t *obj,
                                 attr_value_t *idx),
        lang_void *user_data_get,
        set_error_t (*set_attr)(lang_void *user_data,
                                conf_object_t *obj,
                                attr_value_t *val, attr_value_t *idx),
        lang_void *user_data_set,
        attr_attr_t attr,
        const char *desc);

int
SIM_register_class_attribute(
        conf_class_t *cls, const char *name,
        attr_value_t (*get_attr)(lang_void *ptr,
                                 conf_class_t *c,
                                 attr_value_t *idx),
        lang_void *user_data_get,
        set_error_t (*set_attr)(lang_void *ptr,
                                conf_class_t *c,
                                attr_value_t *val, attr_value_t *idx),
        lang_void *user_data_set,
        attr_attr_t attr,
        const char *desc);

DESCRIPTION

These functions are deprecated, use SIM_register_typed_attribute() and SIM_register_typed_class_attribute() instead.

SIM_register_class()

NAME

SIM_register_class — register class

SYNOPSIS

conf_class_t *
SIM_register_class(const char *name,
                   class_data_t *class_data);

DESCRIPTION

This function registers a new class that can be instantiated by calling the SIM_create_object function.

class_data may be freed when the function has returned.

typedef enum {
        Sim_Class_Kind_Vanilla, /* object is saved at checkpoints */
        Sim_Class_Kind_Session, /* object is saved as part of a
                                 * session only */
        Sim_Class_Kind_Pseudo   /* object is never saved */
} class_kind_t;

typedef struct class_data {
        conf_object_t *(*new_instance)(parse_object_t *parse_obj);
        int (*delete_instance)(conf_object_t *obj);
        void (*finalize_instance)(conf_object_t *obj);
        attr_value_t (*default_get_attr)(const char *name,
                                         conf_object_t *obj,
                                         attr_value_t *idx);
        set_error_t (*default_set_attr)(const char *name,
                                        conf_object_t *obj,
                                        attr_value_t *val,
                                        attr_value_t *idx);
        conf_class_t         *parent;
        const char           *description;
        class_kind_t          kind;
} class_data_t;

The new_instance function should return a newly allocated object. The object must begin with a conf_object_t structure which should be initialized with the object_constructor function.

delete_instance must be NULL if the class does not support object deletion.

RETURN VALUE

Class structure, or NULL on error.

EXCEPTIONS

General Thrown if either the name or the class_data argument is NULL.

Attribute If the class_data structure does not include a new_instance function.

SEE ALSO

SIM_object_constructor, SIM_register_class_alias

SIM_register_class_alias()

NAME

SIM_register_class_alias — register class alias

SYNOPSIS

void
SIM_register_class_alias(const char *alias,
                         const char *name);

DESCRIPTION

Register a new class alias alias for the already registered class class_name. Using aliases allows the read-configuration command to read configuration files that define objects of type alias, while the write-configuration command always uses class_name.

Aliases are used to support compatibility with old class names if a class is renamed. They can also be used to allow different modules, which define different specific implementations of the same generic base class, to read the same configuration files.

SEE ALSO

SIM_register_class

SIM_register_interface()

NAME

SIM_register_interface, SIM_register_port_interface — register interface

SYNOPSIS

int
SIM_register_interface(conf_class_t *cls, const char *name, void *iface);

int
SIM_register_port_interface(conf_class_t *cls, const char *name,
                            void *iface, const char *portname,
                            const char *desc);

DESCRIPTION

Register that cl implements the name interface. The interface itself should be supplied in the iface argument.

SIM_register_port_interface() registers a port instance of an interface that must be looked up using SIM_get_port_interface. The port name may not be the same as any attribute name used by the class.

RETURN VALUE

Returns non-zero on failure, 0 otherwise.

EXCEPTIONS

General Thrown if the interface name is illegal.

SEE ALSO

SIM_get_interface, SIM_get_port_interface

SIM_register_typed_attribute()

NAME

SIM_register_typed_attribute, SIM_register_typed_class_attribute — register attribute

SYNOPSIS

int
SIM_register_typed_attribute(
        conf_class_t *cls, const char *name,
        attr_value_t (*get_attr)(lang_void *user_data,
                                 conf_object_t *obj,
                                 attr_value_t *idx),
        lang_void *user_data_get,
        set_error_t (*set_attr)(lang_void *user_data,
                                conf_object_t *obj,
                                attr_value_t *val, attr_value_t *idx),
        lang_void *user_data_set,
        attr_attr_t attr, const char *type, const char *idx_type,
        const char *desc);

int
SIM_register_typed_class_attribute(
        conf_class_t *cls, const char *name,
        attr_value_t (*get_attr)(lang_void *ptr,
                                 conf_class_t *c,
                                 attr_value_t *idx),
        lang_void *user_data_get,
        set_error_t (*set_attr)(lang_void *ptr,
                                conf_class_t *c,
                                attr_value_t *val,
                                attr_value_t *idx),
        lang_void *user_data_set,
        attr_attr_t attr, const char *type, const char *idx_type,
        const char *desc);

DESCRIPTION

Add the attribute name to the set of attributes understood by the cls class.

The function get_attr is called with the object and the supplied data in user_data_get as arguments, and returns the current value of the attribute. It may return a value of type Sim_Val_Invalid if the argument has no sensible value. Lists and other compound data structures should be allocated dynamically by get_attr. If get_attr is a null pointer, the attribute will be write-only.

After the initial configuration, set_attr may be called at any time to change the value of an attribute. Compound data structures should be copied if set_attr wants to keep them. If set_attr is a null pointer, the attribute will be read-only.

All attributes that are marked Sim_Attr_Required must be present in all configurations.

typedef enum {
        Sim_Attr_Required         = 0,
        Sim_Attr_Optional         = 1,

        Sim_Attr_Session          = 3,
        Sim_Attr_Pseudo           = 4,

        Sim_Attr_Flag_Mask        = 0xff,

        Sim_Init_Phase_Shift      = 8,
        Sim_Init_Phase_0          = 0 << Sim_Init_Phase_Shift,
        Sim_Init_Phase_1          = 1 << Sim_Init_Phase_Shift,

        Sim_Attr_Integer_Indexed  = 0x1000,
        Sim_Attr_String_Indexed   = 0x2000,
        Sim_Attr_List_Indexed     = 0x4000,
        
        Sim_Attr_Persistent       = 0x20000,

        /* set by SIM_register_*_attribute() */
        Sim_Attr_Read_Only        = 0x40000,
        Sim_Attr_Write_Only       = 0x80000

} attr_attr_t;

To make the set_attr function easier to write, Simics provides a simple type system for attributes. You can provide typing information for both simple and indexed access to the attribute via the type and idx_type attributes (note that, in the latter case, you specify the type of the attribute for indexed access, not the type of the index). Setting either parameter to NULL will prevent typechecking for that access mode (normal or indexed).

A type is described by a string composed with the following rules:

• A simple type is represented by a single letter: i (integer), f (floating), s (string), d (data), o (object), b (boolean), D (dictionary), n (nil) or a (all).
• You can match several types by using the operator '|' like in s|o (string OR object). Note that if you provide a string when an object is expected, Simics will call SIM_get_object() to try to translate the string into a valid object.
• Lists are defined by square brackets: [ and ]. Lists can be specified in two ways:

  • Lists with a fixed amount of arguments: [iffsf] matches (integer, floating, floating, string, floating).
  • lists with a size specifier: [i*] matches any list containing only integers (even []); [i+] matches any list containing only integers (but not []); [i{1:4}] matches lists of integers with 1 to 4 elements; [i{4}] is the same as [i{4:4}], i.e. a list of four integers. When you specify a size, the list definition can have only one element.

• | has higher precedence than concatenation in list description, i.e, [i|si|s] should be read [i|s,i|s] which matches any two-element list with integer or string elements. For clarity you can use ',' wherever you want in the type definition, it will be ignored.

RETURN VALUE

Returns zero if successful, and non-zero otherwise.

NOTE

During initial configuration (with the read-configuration command), attribute values will be set in the same order as they are registered.

SIM_set_attribute()

NAME

SIM_set_attribute, SIM_set_class_attribute, SIM_set_attribute_idx, SIM_set_class_attribute_idx — set attribute

SYNOPSIS

set_error_t
SIM_set_attribute(conf_object_t *obj,
                  const char *name,
                  attr_value_t *value);

set_error_t
SIM_set_class_attribute(conf_class_t *cls,
                        const char *name,
                        attr_value_t *value);

set_error_t
SIM_set_attribute_idx(conf_object_t *obj,
                      const char *name,
                      attr_value_t *index,
                      attr_value_t *value);

set_error_t
SIM_set_class_attribute_idx(conf_class_t *cls,
                            const char *name,
                            attr_value_t *index,
                            attr_value_t *value);

DESCRIPTION

Set the name attribute in obj to value.

The _idx version of the function can be used to get a single entry in a list or data attribute. For this to work, the attribute must support indexing.

RETURN VALUE

The return value is from the set_error_t enum, with Sim_Set_Ok indicating success.

SEE ALSO

SIM_get_attribute, set_error_t

SIM_set_configuration()

NAME

SIM_set_configuration — set configuration from data

SYNOPSIS

void
SIM_set_configuration(attr_value_t conf);

DESCRIPTION

---

Note: It is recommended that the SIM_add_configuration function is used instead of SIM_set_configuration.

---

This function is an alternative to reading the configuration from a file. A configuration is an attr_value_t which should have the following structure.

  (("name", "class",  ("attr_name", attr_val) ... ), ... )
  

That is a list of object specifiers containing name, class, and a list of attribute specifiers. An attribute specifier is a list of length 2 containing the attribute name and its value. SIM_set_configuration() allows an easy way of parameterizing the configuration, especially if called from Python.

EXAMPLE

The following is an Python example:

  from configuration import *

  SIM_set_configuration([
   ["cpu0", "x86",
    ["queue", OBJ("cpu0")],
    ["freq_mhz", 20],
    ["physical_memory", OBJ("phys_mem0")]],

   ["phys_mem0", "memory-space",
    ["map",  [[0xa0000,    OBJ("vga0"),    1, 0, 0x20000],
              [0x00000,    OBJ("mem0"),    0, 0x00000, 0xA0000],
              [0xc0000,    OBJ("mem0"),    0, 0xc0000, 0x8000],
              [0xc8000,    OBJ("setmem0"), 0, 0, 0x28000],
              [0xf0000,    OBJ("mem0"),    0, 0xf0000, 0x10000],
              [0x100000,   OBJ("mem0"),    0, 0x100000, 0x3ff00000],
              [0xfee00000, OBJ("apic0"),   0, 0, 0x4000]]]],
      ... ])
  

EXCEPTIONS

Attribute Thrown if malformed configuration list.
General Thrown if Simics fails to initialize all objects.

SEE ALSO

SIM_add_configuration, SIM_create_object

SIM_write_configuration_to_file()

NAME

SIM_write_configuration_to_file — write configuration

SYNOPSIS

int
SIM_write_configuration_to_file(const char *file);

DESCRIPTION

Saves all objects to the configuration file filename. Objects whose class_kind_t is equal to Sim_Class_Kind_Session or Sim_Class_Kind_Pseudo are not saved. This also holds for attributes (in all objects) of types Sim_Attr_Session and Sim_Attr_Pseudo.

Classes that wish to create additional files can use the SIM_get_configuration_file_prefix call to get a suitable filename prefix.

RETURN VALUE

0 if successful, 1 otherwise.

Documentation

SIM_register_copyright()

NAME

SIM_register_copyright — register copyright information

SYNOPSIS

void
SIM_register_copyright(const char *str);

DESCRIPTION

This registers specific copyright information related to an extension module or similar component of Simics. The Simics front-end command "copyright" will list, in addition to Simics copyright notices, any registered notices from libraries or plug-ins that have added a string using this function.

The string should contain only standard ASCII characters, be pre-formatted for at most 80-character width terminal, be non-indented, and have no spurious new-line characters before or after the last line (except for the new-line that marks the end of the last line).

The string will not be copied so needs to be either static or a copy generated by the callee (preferably static).

SIM_version()

NAME

SIM_version, SIM_version_sub, SIM_readme, SIM_snapshot_date, SIM_license, SIM_copyright — get version info about Simics

SYNOPSIS

const char *
SIM_version(void);

const char *
SIM_version_sub(void);

const char *
SIM_readme(void);

const char *
SIM_snapshot_date(void);

void
SIM_license(void);

void
SIM_copyright(void);

DESCRIPTION

Return strings describing the version of Simics, compile date, expiry date, license and a general readme.

Errors and Exceptions

SIM_clear_exception()

NAME

SIM_clear_exception — clear pending exception

SYNOPSIS

sim_exception_t
SIM_clear_exception(void);

DESCRIPTION

Clears the current pending exception.

SimExc_No_Exception if none available.

RETURN VALUE

Returns the exception that was pending before the call, or SimExc_No_Exception if none.

SEE ALSO

SIM_frontend_exception, SIM_get_pending_exception

SIM_command_has_problem()

NAME

SIM_command_has_problem, SIM_command_clear_problem, SIM_command_problem_status — signal error in command

SYNOPSIS

void
SIM_command_has_problem(void);

void
SIM_command_clear_problem(void);

int
SIM_command_problem_status(void);

DESCRIPTION

Call this function if the currently executing command, created with the python function new_command(), is having a problem. Examples of problems are illegal parameters, syntax error, serious error in carrying out command, etc. One of the effects is to stop any enclosing structure, such as a script file, from continuing.

The current problem status can be queried with SIM_command_problem_status where a return value of zero means no problem. The status can be cleared by calling SIM_command_clear_problem(), allowing script files to continue executing.

SIM_frontend_exception()

NAME

SIM_frontend_exception — raise an exception

SYNOPSIS

void
SIM_frontend_exception(sim_exception_t exc_type, const char *str);

DESCRIPTION

This function raises an exception of type exc_type and message str.

The state of the pending exception can be read with SIM_get_pending_exception() and cleared with SIM_clear_exception().

SIM_get_pending_exception()

NAME

SIM_get_pending_exception — get current pending exception

SYNOPSIS

sim_exception_t
SIM_get_pending_exception(void);

DESCRIPTION

This function returns the exception type of the current pending exception, or SimExc_No_Exception if none available.

SEE ALSO

SIM_frontend_exception, SIM_clear_exception, SIM_last_error

SIM_last_error()

NAME

SIM_last_error — get error message from last exception

SYNOPSIS

const char *
SIM_last_error(void);

DESCRIPTION

Returns the error message attached to the last exception raised.

SEE ALSO

SIM_frontend_exception

Haps

SIM_c_hap_occurred()

NAME

SIM_c_hap_occurred, SIM_c_hap_occurred_vararg, SIM_c_hap_occurred_always, SIM_c_hap_occurred_always_vararg — trigger a hap occurrence

SYNOPSIS

int
SIM_c_hap_occurred(hap_type_t hap, conf_object_t *obj,
                   integer_t value, ...);

int
SIM_c_hap_occurred_vararg(hap_type_t hap, conf_object_t *obj,
                          integer_t value, va_list ap);

int
SIM_c_hap_occurred_always(hap_type_t hap, conf_object_t *obj,
                          integer_t value, ...);

int
SIM_c_hap_occurred_always_vararg(hap_type_t hap, conf_object_t *obj,
                                 integer_t value, va_list ap);

DESCRIPTION

These functions are used to cause a hap of type hap. The value argument is used for checking ranges. The hap-specific data is passed as the first parameter to the callback function (see SIM_hap_add_callback()). These functions return the number of callbacks that were called.

SIM_hap_occurred() will only run callback functions for a specific hap once per simulated cycle. The SIM_hap_occurred_always() function will always run the callbacks.

The functions SIM_c_hap_occurred_vararg() and SIM_c_hap_occurred_always_vararg() are vararg versions of these functions.

EXCEPTIONS

Break Thrown if a callback requested the simulation to stop. This exception will be removed in a future Simics version. Do not write new code relying on it.

RETURN VALUE

The number of callback functions called.

SEE ALSO

SIM_break_simulation

SIM_get_all_hap_types()

NAME

SIM_get_all_hap_types — get list of all hap types

SYNOPSIS

attr_value_t
SIM_get_all_hap_types(void);

DESCRIPTION

Get data structure with the names of all hap types.

RETURN VALUE

List with strings.

SIM_hap_add_callback()

NAME

SIM_hap_add_callback, SIM_hap_add_callback_index, SIM_hap_add_callback_range, SIM_hap_add_callback_obj, SIM_hap_add_callback_obj_index, SIM_hap_add_callback_obj_range — install callback on a hap

SYNOPSIS

hap_handle_t
SIM_hap_add_callback(const char *hap,
                     obj_hap_func_t func,
                     typed_lang_void *user_data);

hap_handle_t
SIM_hap_add_callback_index(const char *hap,
                           obj_hap_func_t func,
                           typed_lang_void *user_data,
                           integer_t index);

hap_handle_t
SIM_hap_add_callback_range(const char *hap,
                           obj_hap_func_t func,
                           typed_lang_void *user_data,
                           integer_t start,
                           integer_t end);

hap_handle_t
SIM_hap_add_callback_obj(const char *hap,
                         conf_object_t *obj,
                         hap_flags_t flags,
                         obj_hap_func_t func,
                         typed_lang_void *user_data);

hap_handle_t
SIM_hap_add_callback_obj_index(const char *hap,
                               conf_object_t *obj,
                               hap_flags_t flags,
                               obj_hap_func_t func,
                               typed_lang_void *user_data,
                               integer_t index);

hap_handle_t
SIM_hap_add_callback_obj_range(const char *hap,
                               conf_object_t *obj,
                               hap_flags_t flags,
                               obj_hap_func_t func,
                               typed_lang_void *user_data,
                               integer_t start,
                               integer_t end);

DESCRIPTION

Registers a function, pointed to by func, to be called when hap occurs for object obj. If obj is NULL (None in Python), or a hap add function that does not have the obj argument is used, then the callback function will be called regardless of what object that triggers the hap. The user_data argument is the callback-specific data, and it will be passed as first argument to the installed callback function.

Some hap add functions also take a flags argument. This flag is currently Simics internal and should be set to 0.

The hap callback functions should not return any data. In C, the functions are declared to have a void return type and in Python, any return value is ignored. Since callback functions with different arguments may be installed using the same API function, the compiler may warn about a type mismatch. The solution is to cast the callback function pointer to the obj_hap_func_t type.

In hap functions, the execution can be interrupted by calling SIM_break_simulation. If a frontend or Python exception is raised, an error message will be printed incuding a stack trace if the callback is written in Python.

The _index_ and _range_ versions will install callbacks that only trigger for a specified index, or range of indices. The index is specific for each hap type, see the hap documentation.

typedef int hap_handle_t;

RETURN VALUE

The return value is a hap callback handle (identifier) of the type hap_handle_t. This handle can be used to remove the installed callback with SIM_hap_delete_callback_id.

EXCEPTIONS

Lookup Thrown if the hap does not exist.
Attribute Thrown if the callback is not valid.

SIM_hap_add_type()

NAME

SIM_hap_add_type — register a new hap type

SYNOPSIS

hap_type_t
SIM_hap_add_type(const char *hap,
                 const char *params,
                 const char *param_desc,
                 const char *index,
                 const char *desc,
                 int old_had_obj);

DESCRIPTION

Creates a run-time defined hap type.

The params parameter specifies the argument that callbacks for this hap is called with, e.g., "s" or "II". The first two arguments are always lang_void * and conf_object_t * respectively, and should not be included in that string. The table below shows which characters may be used, and what their meaning is:

i	an int
I	an integer_t (64 bit integer)
e	an exception_type_t
o	a script specific object; i.e., void * in C and any Python object in Python
s	a string
m	a memory transaction (generic_transaction_t * in C)
c	a configuration object (conf_object_t * in C)
v	a void *; a pointer to a C structure within Simics

parm_desc should be a string of space-separated words describing these parameters, or NULL if params is the empty string.

index is a string describing the index value for this hap, or NULL if there is no index value.

Hap types that used to have a conf_object_t pointer as first argument (before all haps were associated with an object) should set the old_had_obj argument to 1. This tells Simics to call old-style callbacks with a conf_object_t argument although the hap doesn't include any 'c' first in the parameter list anymore. Old style callbacks are functions installed with the now obsolete SIM_hap_register_callback... and SIM_hap_install_callback... functions.

desc is a description string for the hap.

EXCEPTIONS

General Thrown if hap is already defined. However, consequent calls with the same parameters will be successful, and return the same hap type number each time.

RETURN VALUE

The hap type number or a number <= 0 on error.

SIM_hap_callback_exists()

NAME

SIM_hap_callback_exists — get callback status

SYNOPSIS

int
SIM_hap_callback_exists(const char *hap,
                        obj_hap_func_t func,
                        typed_lang_void *user_data);

DESCRIPTION

Checks if there is an installed callback func with associated user_data for hap hap.

EXCEPTIONS

Lookup Thrown if no hap is associated with name id.

RETURN VALUE

1 if such a callback exists, 0 otherwise.

SIM_hap_delete_callback()

NAME

SIM_hap_delete_callback, SIM_hap_delete_callback_obj, SIM_hap_delete_callback_id, SIM_hap_delete_callback_obj_id — delete installed hap callback

SYNOPSIS

void
SIM_hap_delete_callback(const char *hap,
                        obj_hap_func_t func, typed_lang_void *user_data);

void
SIM_hap_delete_callback_obj(const char *hap,
                            conf_object_t *obj,
                            obj_hap_func_t func, typed_lang_void *user_data);

void
SIM_hap_delete_callback_id(const char *hap, hap_handle_t handle);

void
SIM_hap_delete_callback_obj_id(const char *hap,
                               conf_object_t *obj, hap_handle_t handle);

DESCRIPTION

Removes a callback for a hap type specified by the hap argument.

The SIM_hap_delete_callback_obj...() functions will remove a callback that is installed on the specified object obj.

SIM_hap_delete_callback() removes any callbacks with the callback function func and the same user_data. The SIM_hap_delete_callback_..._id() functions take a hap handle argument instead, as returned by the SIM_hap_add_callback...() functions.

These function will trigger the Core_Hap_Callback_Removed hap for each removed callback. NOTE: Callbacks registered to be called on Core_Hap_Callback_Removed, are not allowed to make recursive calls to remove or unregister any callbacks on the same hap.

EXCEPTIONS

Lookup Thrown if the specified hap does not exist.

SIM_hap_get_name()

NAME

SIM_hap_get_name — get hap name by number

SYNOPSIS

const char *
SIM_hap_get_name(hap_type_t hap);

DESCRIPTION

Returns the name of hap, or NULL for no such hap.

SIM_hap_get_number()

NAME

SIM_hap_get_number — get hap number by name

SYNOPSIS

hap_type_t
SIM_hap_get_number(const char *hap);

DESCRIPTION

Return the runtime number associated with a hap identifier. All haps are listed in section 8.

EXCEPTIONS

Lookup Thrown if no hap is associated with name id.

RETURN VALUE

The hap type number, or 0 on failure.

SIM_hap_is_active()

NAME

SIM_hap_is_active — check if hap has callbacks

SYNOPSIS

int
SIM_hap_is_active(hap_type_t hap);

DESCRIPTION

Returns 1 if the hap has any callback functions installed, and 0 if not.

SIM_hap_occurred()

NAME

SIM_hap_occurred, SIM_hap_occurred_always — trigger hap occurrence

SYNOPSIS

int
SIM_hap_occurred(hap_type_t hap, conf_object_t *obj,
                 integer_t value, attr_value_t *list);

int
SIM_hap_occurred_always(hap_type_t hap, conf_object_t *obj,
                        integer_t value, attr_value_t *list);

DESCRIPTION

Used to notify that a particular hap has occurred. All callbacks installed for the hap will be called. The value is used to check range. The hap specific data is passed as the first parameter to the callback function (see SIM_hap_add_callback()) A positive return indicates the number of callback that was installed and run.

SIM_hap_occurred() will only call the callbacks once in a simulated cycle; i.e., it is safe to call SIM_hap_occurred() and request the simulation to stop every time. The SIM_hap_occurred_always() function will always call the hap functions every time.

NOTES

There are also versions of these functions that only can be called from C (with var-args), SIM_c_hap_occurred(), and SIM_c_hap_occurred_always().

EXCEPTIONS

An exception is thrown upon errors or if a callback requested the simulation to stop. The kind of exception depends on the callback.

RETURN VALUE

The number of callbacks installed on the hap.

SIM_hap_remove_type()

NAME

SIM_hap_remove_type — remove a hap type

SYNOPSIS

void
SIM_hap_remove_type(const char *hap);

DESCRIPTION

Remove a run-time defined hap type.

Logging

SIM_get_quiet()

NAME

SIM_get_quiet — return setting of the quiet flag

SYNOPSIS

int
SIM_get_quiet(void);

DESCRIPTION

This function returns the current value of Simics's quiet flag.

SIM_get_verbose()

NAME

SIM_get_verbose — get the verbose flag

SYNOPSIS

int
SIM_get_verbose(void);

DESCRIPTION

This function returns the value of Simics's verbosity flag (corresponding to the -verbose command-line argument).

SIM_log_constructor()

NAME

SIM_log_constructor — initiate log class

SYNOPSIS

void
SIM_log_constructor(log_object_t *log_obj, parse_object_t *parse_obj);

DESCRIPTION

This constructor should be called by new_instance functions to initialize a new log object.

SEE ALSO

log_object_t, SIM_log_message, SIM_log_register_groups

SIM_log_info()

NAME

SIM_log_info, SIM_log_error, SIM_log_undefined, SIM_log_spec_violation, SIM_log_target_error, SIM_log_unimplemented — output log message

SYNOPSIS

static void
SIM_log_info(int lvl, log_object_t *dev, int grp,
             const char *str, ...);

static void
SIM_log_error(log_object_t *dev, int grp,
              const char *str, ...);

static void
SIM_log_undefined(int lvl, log_object_t *dev, int grp,
                  const char *str, ...);

static void
SIM_log_spec_violation(int lvl, log_object_t *dev, int grp,
                       const char *str, ...);

static void
SIM_log_target_error(int lvl, log_object_t *dev, int grp,
                     const char *str, ...);

static void
SIM_log_unimplemented(int lvl, log_object_t *dev, int grp,
                      const char *str, ...);

DESCRIPTION

SIM_log_info() etc are C macros that should be used by devices and extensions which are based on a log_object_t to print information and error messages. For more information, see the SIM_log_message function. Each macros represents a log type.

SEE ALSO

SIM_log_message, SIM_log_constructor

SIM_log_message()

NAME

SIM_log_message — print and log message

SYNOPSIS

void
SIM_log_message(conf_object_t *obj,
                int level,
                int group_ids,
                log_type_t log_type,
                const char *message);

DESCRIPTION

Prints and logs a message associated with a log_object_t object. Objects written in C/C++ should use the SIM_log_<log-type>() macros instead.

level should be between 1 and 4:

1. important messages printed by default
2. "high-level" informative messages
3. standard debug messages
4. detailed information, such as register accesses

Messages of the Sim_Log_Error type are always printed on level 1. The group_ids should have a bit set for each log group that the message corresponds to, as defined by the SIM_log_register_groups(). The log_type argument is documented with the log_type_t type.

SEE ALSO

SIM_log_constructor, SIM_log_register_groups, log_type_t

SIM_log_register_groups()

NAME

SIM_log_register_groups — register names of log groups

SYNOPSIS

void
SIM_log_register_groups(conf_class_t *cls, const char **names);

DESCRIPTION

Register a list of log groups that a log_object_t object can use to separate messages. The order of the groups in the list defines the group ids that should be used in the call to SIM_log_message(). The group_ids argument to that function should have a bit set corresponding to the group; i.e., a value of 1 for the first group, 2 for the second, 4 for the third, etc. names should be a NULL-terminated array.

SEE ALSO

SIM_log_constructor, SIM_log_register_groups

SIM_set_quiet()

NAME

SIM_set_quiet — enable/disable quiet mode

SYNOPSIS

void
SIM_set_quiet(int mode);

DESCRIPTION

Calling this function with an argument of 1 will enable the quiet mode, whereas an argument of 0 will disable it. Any other arguments will cause a frontend exception. Please note that enabling the quiet mode will disable verbose mode.

SIM_set_verbose()

NAME

SIM_set_verbose — set the verbose flag

SYNOPSIS

void
SIM_set_verbose(int mode);

DESCRIPTION

This function sets Simics's internal verbosity flag (corresponding to the -verbose command-line argument). The mode argument can be either 0 or 1. Note that setting this flag will disable quiet mode.

Memory

SIM_for_all_memory_pages()

NAME

SIM_for_all_memory_pages — apply callback function to all memory pages

SYNOPSIS

void
SIM_for_all_memory_pages(void (*func)(integer_t addr), int i_or_d);

DESCRIPTION

Iterate through all known pages of memory and call a function for every page.

The callback func is passed the physical address of the first byte on the page. Each page is S_PSIZE bytes large.

If i_or_d is 0, then func is only applied to pages that have had code executed on them (i.e. intermediate code has been allocated at some time).

EXCEPTIONS

General Thrown if func is NULL.

NOTE

The memory pages are internal Simics pages. The size of a page may be different than the logical page size of the target architecture.

SIM_load_binary()

NAME

SIM_load_binary — read an executable file into memory

SYNOPSIS

physical_address_t
SIM_load_binary(conf_object_t *obj, const char *file,
                physical_address_t offset, int use_pa, int verbose);

DESCRIPTION

Read a binary file (ELF, PE32, or PE32+ format) into memory and return the code entry point.

The file will be loaded at the address formed by adding the virtual load address from the file, with the offset offset. If the flag use_pa is set, the ELF physical load address is used instead. The verbose flag will cause Simics to print info about the binary to the console.

The memory space to load into is given in the obj parameter. If the given space is a CPU object, its current virtual address space will be used, and addresses will be translated before writing to the physical memory space attached to the CPU.

If the file is not found in the current directory, the search path (see add-directory) is used to find the file.

EXCEPTIONS

IOError Thrown if there was a problem reading the file.
Memory Thrown if binary cannot be read into memory.

RETURN VALUE

The code entry address.

SIM_load_file()

NAME

SIM_load_file — read a file into memory

SYNOPSIS

void
SIM_load_file(conf_object_t *obj, const char *file,
              physical_address_t base_address, int verbose);

DESCRIPTION

Reads a file straight into memory starting at physical address 'base_address'. The flag 'verbose' will cause Simics to print info about the file to the console.

EXCEPTIONS

Attribute Thrown if no file is specified.
IOError Thrown if there was a problem reading the file.
Memory Thrown if file cannot be read into memory.

SIM_logical_to_physical()

NAME

SIM_logical_to_physical — translate logical to physical

SYNOPSIS

physical_address_t
SIM_logical_to_physical(conf_object_t *cpu,
                        data_or_instr_t data_or_instr, 
                        logical_address_t vaddr);

DESCRIPTION

Translates logical to physical address, assumes a 'word read' operation in supervisor mode to the address using supplied processor.

EXCEPTIONS

Memory Thrown if no translation exists.

RETURN VALUE

The physical address.

SIM_read_byte()

NAME

SIM_read_byte, SIM_write_byte — read/write byte from a memory space

SYNOPSIS

uint8
SIM_read_byte(conf_object_t *obj, generic_address_t paddr);

void
SIM_write_byte(conf_object_t *obj, generic_address_t paddr, uint8 value);

DESCRIPTION

Read or write a byte from a given address in the memory space obj.

EXCEPTIONS

Memory Thrown if the memory space threw an exception
General Thrown if the object does not implement the memory space interface, or if obj is NULL.

RETURN VALUE

The byte read.

SIM_read_phys_memory()

NAME

SIM_read_phys_memory — read data from a physical address

SYNOPSIS

uinteger_t
SIM_read_phys_memory(conf_object_t *cpu,
                     physical_address_t paddr,
                     int length);

DESCRIPTION

Reads length bytes from address paddr in the physical memory space associated with the processor cpu.

Up to 8 bytes can be read in one call. The memory access will be of inquiry type, i.e. no timing-model or snoop device will be called.

EXCEPTIONS

Memory Thrown if no memory defined at paddr.
Attribute Thrown if length is out of range.

RETURN VALUE

The read data, zero-extended.

SIM_read_phys_memory_tags()

NAME

SIM_read_phys_memory_tags, SIM_write_phys_memory_tags — access auxiliary bits in physical memory

SYNOPSIS

uint64
SIM_read_phys_memory_tags(conf_object_t *mem_space, physical_address_t paddr,
                          unsigned ntags);

void
SIM_write_phys_memory_tags(conf_object_t *mem_space, physical_address_t paddr,
                           uint64 tag_bits, unsigned ntags);

DESCRIPTION

Reads or writes ntags auxiliary bits starting at paddr in the physical memory space mem_space. Up to 64 bits can be accessed at once. The bits are specified and returned right-aligned, least significant bit corresponding to the lowest address.

SIM_write_phys_memory()

NAME

SIM_write_phys_memory — write data to a physical address

SYNOPSIS

void
SIM_write_phys_memory(conf_object_t *cpu,
                      physical_address_t paddr,
                      uinteger_t value, int length);

DESCRIPTION

Writes length bytes to address paddr in the physical memory space associated with the processor cpu.

Up to 8 bytes can be written in one call. The memory access will be of inquiry type, i.e. no timing-model or snoop device will be called.

EXCEPTIONS

Memory Thrown if no memory defined at paddr.
Attribute Thrown if length is out of range.

Memory Transactions

SIM_alpha_mem_trans_from_generic()

NAME

SIM_alpha_mem_trans_from_generic, SIM_arm_mem_trans_from_generic, SIM_ia64_mem_trans_from_generic, SIM_mips_mem_trans_from_generic, SIM_ppc_mem_trans_from_generic, SIM_v9_mem_trans_from_generic, SIM_x86_mem_trans_from_generic, SIM_pci_mem_trans_from_generic — convert generic transaction to CPU specific

SYNOPSIS

struct alpha_memory_transaction *
SIM_alpha_mem_trans_from_generic(generic_transaction_t *mop);

struct arm_memory_transaction *
SIM_arm_mem_trans_from_generic(generic_transaction_t *mop);

struct ia64_memory_transaction *
SIM_ia64_mem_trans_from_generic(generic_transaction_t *mop);

struct mips_memory_transaction *
SIM_mips_mem_trans_from_generic(generic_transaction_t *mop);

struct ppc_memory_transaction *
SIM_ppc_mem_trans_from_generic(generic_transaction_t *mop);

struct v9_memory_transaction *
SIM_v9_mem_trans_from_generic(generic_transaction_t *mop);

struct x86_memory_transaction *
SIM_x86_mem_trans_from_generic(generic_transaction_t *mop);

struct pci_memory_transaction *
SIM_pci_mem_trans_from_generic(generic_transaction_t *mop);

DESCRIPTION

Converts a pointer to a generic memory transaction into a pointer to a CPU specific memory transaction. The generic memory transaction must be part of a CPU specific one for this function to succeed. The pointer returned will be the same the input pointer if conversion is allowed, and NULL on failure.

EXCEPTIONS

Type Thrown if the generic transaction is not part of a CPU specific transaction.

RETURN VALUE

New memory transaction pointer, or NULL on error.

SIM_c_get_mem_op_value_buf()

NAME

SIM_c_get_mem_op_value_buf, SIM_get_mem_op_value_buf, SIM_get_mem_op_value_cpu, SIM_get_mem_op_value_le, SIM_get_mem_op_value_be — get value for a memory operation

SYNOPSIS

void
SIM_c_get_mem_op_value_buf(generic_transaction_t *mop, char *dst);

attr_value_t
SIM_get_mem_op_value_buf(generic_transaction_t *mop);

uinteger_t
SIM_get_mem_op_value_cpu(generic_transaction_t *mop);

uinteger_t
SIM_get_mem_op_value_le(generic_transaction_t *mop);

uinteger_t
SIM_get_mem_op_value_be(generic_transaction_t *mop);

DESCRIPTION

Returns load or store value for a memory transaction. If the data size is 8 bytes or less the SIM_get_mem_op_value_be() and SIM_get_mem_op_value_le() functions can be used. For reads/writes larger than 8 bytes, the functions SIM_c_get_mem_op_value_buf() or SIM_get_mem_op_value_buf() should be used to get the data.

The SIM_c_get_mem_op_value_buf() function is only available from C/C++. It places the data into the buffer pointed to by dst. No endian conversion is performed, i.e. data is returned in target endianness. There is no alignment requirement on the dst parameter.

WARNING

When called from a memory-hierarchy (timing-model) only store values can be retrieved, since the load has not yet performed. To get the load value, a snoop-device should be used.

RETURN VALUE

SIM_c_get_mem_op_value_buf() returns nothing. The out parameter dst is filled with the data buffer of the memory transaction. SIM_get_mem_op_value_buf() returns an attr_value_t containing the the data buffer (type Sim_Val_Data) of the memory transaction. SIM_get_mem_op_value_be() returns the zero-extended value in host endian order (interpreted as big endian) for the memory transaction. SIM_get_mem_op_value_le() returns the zero-extended value in host endian order (interpreted as little endian). SIM_get_mem_op_value_cpu() interprets the data in the default endian order for the initiating processor.

EXCEPTIONS

Memory Thrown if the size of the operation is illegal.

SIM_c_set_mem_op_value_buf()

NAME

SIM_c_set_mem_op_value_buf, SIM_set_mem_op_value_buf, SIM_set_mem_op_value_cpu, SIM_set_mem_op_value_le, SIM_set_mem_op_value_be — set value for a memory operation

SYNOPSIS

void
SIM_c_set_mem_op_value_buf(generic_transaction_t *mop, char *src);

void
SIM_set_mem_op_value_buf(generic_transaction_t *mop, attr_value_t value);

void
SIM_set_mem_op_value_cpu(generic_transaction_t *mop, uinteger_t value);

void
SIM_set_mem_op_value_le(generic_transaction_t *mop, uinteger_t value);

void
SIM_set_mem_op_value_be(generic_transaction_t *mop, uinteger_t value);

DESCRIPTION

Set the value returned to the requester of a memory operation. If the data size is 8 bytes or less the SIM_set_mem_op_value_be() and SIM_set_mem_op_value_le functions can be used. For sizes larger than 8 bytes, the functions SIM_c_set_mem_op_value_buf() or SIM_set_mem_op_value_buf() should be used to set the data.

SIM_c_set_mem_op_value_buf() is only available from C/C++, it operates on data in target endian order. There is no alignment requirement on the buf parameter.

SIM_set_mem_op_value_be() takes data in host endian order and sets it in big-endian.

SIM_set_mem_op_value_le() takes data in host endian order and sets it in little-endian.

SIM_set_mem_op_value_cpu() takes data in host endian order and sets it in the default endian order for the initiating processor.

WARNING

These functions cannot be called from a timing-model since the real operation will overwrite the value set. They should instead be used from a snoop-device.

SIM_get_mem_op_type()

NAME

SIM_get_mem_op_type — get type of transaction

SYNOPSIS

FORCE_INLINE mem_op_type_t
SIM_get_mem_op_type(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

This function returns the type of the memory transaction.

SIM_get_mem_op_type_name()

NAME

SIM_get_mem_op_type_name — get name of memory operation type

SYNOPSIS

const char *
SIM_get_mem_op_type_name(mem_op_type_t type);

DESCRIPTION

Returns a string describing type or NULL if unknown.

SIM_get_unique_memory_transaction_id()

NAME

SIM_get_unique_memory_transaction_id — get unique memory transaction ID

SYNOPSIS

int
SIM_get_unique_memory_transaction_id(conf_object_t *obj);

DESCRIPTION

Returns a number which is unique for all currently outstanding memory operations of the specified CPU obj. You can read the last value returned by this function by calling SIM_get_current_memory_transaction_id().

SIM_mem_op_is_control()

NAME

SIM_mem_op_is_control — transaction control predicates

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_control(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is control transaction.

SIM_mem_op_is_data()

NAME

SIM_mem_op_is_data, SIM_mem_op_is_instruction — transaction data/instruction predicates

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_data(const generic_transaction_t *NOTNULL mop);

FORCE_INLINE int
SIM_mem_op_is_instruction(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

These functions check whether mem_op is a data or an instruction transaction. Currently, the only transactions that are instruction transactions are instruction fetches.

SIM_mem_op_is_from_cache()

NAME

SIM_mem_op_is_from_cache — Cache initiated transaction

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_from_cache(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is sent from a cache timing model.

SIM_mem_op_is_from_cpu()

NAME

SIM_mem_op_is_from_cpu — CPU initiated transaction

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_from_cpu(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is sent from a processor.

SIM_mem_op_is_from_cpu_arch()

NAME

SIM_mem_op_is_from_cpu_arch — CPU initiated transaction

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_from_cpu_arch(const generic_transaction_t *NOTNULL mop,
                            ini_type_t arch);

DESCRIPTION

Checks whether mem_op is sent from a processor of a specific architecture.

SIM_mem_op_is_from_device()

NAME

SIM_mem_op_is_from_device — Device initiated transaction

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_from_device(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is sent from a device.

SIM_mem_op_is_prefetch()

NAME

SIM_mem_op_is_prefetch — transaction control predicates

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_prefetch(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

Checks whether mem_op is prefetch transaction.

SIM_mem_op_is_read()

NAME

SIM_mem_op_is_read, SIM_mem_op_is_write — transaction read/write predicates

SYNOPSIS

FORCE_INLINE int
SIM_mem_op_is_read(const generic_transaction_t *NOTNULL mop);

FORCE_INLINE int
SIM_mem_op_is_write(const generic_transaction_t *NOTNULL mop);

DESCRIPTION

These functions check whether mem_op is a read or a write transaction.

SIM_set_mem_op_type()

NAME

SIM_set_mem_op_type — set type of transaction

SYNOPSIS

FORCE_INLINE void
SIM_set_mem_op_type(generic_transaction_t *NOTNULL mop, mem_op_type_t type);

DESCRIPTION

Modules

SIM_get_all_failed_modules()

NAME

SIM_get_all_failed_modules — return a list of all modules that failed to load

SYNOPSIS

attr_value_t
SIM_get_all_failed_modules(void);

DESCRIPTION

A failed module is a module that is not loadable by the current version of Simics. The list returned contains information about why the module failed. Each list entry is another list with module specific information. The layout of this sub-list is described below. The list may grow in future Simics version, but the currently defined fields will not change.

• name - Module name (Sim_Val_String).
• path - File system path to the module (Sim_Val_String).
• duplicate - Flag indicating a duplicate module (Sim_Val_Boolean).
• linker - Flag indicating a linker error. (Sim_Val_Boolean).
• version - Simics ABI version that the module is build for (Sim_Val_Integer).
• user version - User version of the module (Sim_Val_String).
• error - Error message, typically from the linker (Sim_Val_String or Sim_Val_Nil).

SEE ALSO

SIM_get_all_modules

SIM_get_all_modules()

NAME

SIM_get_all_modules — return a list of all modules

SYNOPSIS

attr_value_t
SIM_get_all_modules(void);

DESCRIPTION

The list returned contains information about all modules that can be loaded into Simics. Each list entry is another list with module specific information. The layout of this sub-list is described below. The list may grow in future Simics version, but the currently defined fields will not change.

• name - Module name (Sim_Val_String).
• path - File system path to the module (Sim_Val_String).
• loaded - Flag indicating that the module is already loaded (Sim_Val_Boolean).
• version - Simics ABI version that the module is build for (Sim_Val_Integer).
• user version - User version of the module (Sim_Val_String).

SEE ALSO

SIM_get_all_failed_modules

SIM_load_module()

NAME

SIM_load_module, SIM_unload_module — load/unload modules

SYNOPSIS

void
SIM_load_module(const char *module);

void
SIM_unload_module(const char *module);

DESCRIPTION

Load a module (Simics extension). Simics supports dynamically loadable modules. Anything linked as dynamic can be loaded. SIM_load_module takes the module name module as argument and tries to link in the corresponding library file. Under Unix lib<module>.so will be used and under Windows <module>.dll. Python modules (.py) can also be loaded with this function. SIM_unload_module unloads a module if the module supports it.

Modules should be placed in the simics lib directory or in a directory present in the SIMICS_EXTRA_LIB environment variable.

SIM_module_list_refresh()

NAME

SIM_module_list_refresh — refresh list of loadable modules

SYNOPSIS

void
SIM_module_list_refresh(void);

DESCRIPTION

Simics maintains a list of all modules that can be loaded successfully. If a module is changed or added, the list has to be refreshed before Simics can load this module.

Output

SIM_add_output_handler()

NAME

SIM_add_output_handler — register output handler

SYNOPSIS

void
SIM_add_output_handler(output_handler_t func, lang_void *user_data);

DESCRIPTION

This function registers func(user_data, buf, count) to be called whenever there is text output from Simics, where data is the pointer in the call to SIM_remove_output_handler(), buf is a pointer to the output data, and count is the number of bytes to be written.

This is the definition of output_handler_t:

typedef void (*output_handler_t)(lang_void *data,
                                 const char *src, size_t length);

SEE ALSO

SIM_remove_output_handler, SIM_write

SIM_remove_output_handler()

NAME

SIM_remove_output_handler — unregister output handler

SYNOPSIS

void
SIM_remove_output_handler(output_handler_t func, typed_lang_void *user_data);

DESCRIPTION

This function removes func as an output recipient. If data is NULL, all previously added output handlers (by a call to SIM_add_output_handler()) will be removed; otherwise, only those with equal data pointers will be removed.

SEE ALSO

SIM_add_output_handler, SIM_write

SIM_write()

NAME

SIM_write, SIM_flush, SIM_putchar, SIM_puts, SIM_printf, SIM_printf_vararg — text output routines

SYNOPSIS

int
SIM_write(const void *src, int length);

int
SIM_flush(void);

int
SIM_putchar(int c);

int
SIM_puts(const char *s);

int
SIM_printf(const char *format, ...);

int
SIM_printf_vararg(const char *format, va_list ap);

DESCRIPTION

These are the Simics versions of the write(), putchar(), puts(), printf(), vprintf(), and fflush() C library functions. The arguments and return values are the same as for the library functions, except for SIM_write() which does not take any file argument.

The output will be sent to stdout, but more output recipients can be added using the SIM_add_output_handler() function. Output is line buffered. SIM_flush() will force output of an unterminated line.

By default, simics_api.h will define a number of macros, changing calls to the abovementioned C library functions to call the Simics versions instead:

#undef printf

#if defined(HAVE_VARARG_MACROS)
#define printf(...) SIM_printf(__VA_ARGS__)
#else
#define printf SIM_printf
#endif

#undef vprintf
#define vprintf(str, ap) SIM_printf_vararg(str, ap)

#undef puts
#define puts(str) SIM_puts(str)

#undef putchar
#define putchar(c) SIM_putchar(c)

#undef fwrite
#define fwrite(ptr, size, nmemb, stream)                \
        ((stream) == stdout                             \
         ? (size_t)SIM_write((ptr), (size) * (nmemb))   \
         : fwrite(ptr, size, nmemb, stream))

#undef fputs
#define fputs(str, stream)                      \
        ((stream) == stdout                     \
         ? SIM_write((str), strlen(str))        \
         : fputs((str), (stream)))

#undef fflush
#define fflush(stream) ((stream) == stdout ? SIM_flush() : fflush(stream))

This behavior can be overridden, see the information about the SIM_BC_NO_STDOUT_REDEFINE macro in section 3.4.1.

SEE ALSO

SIM_add_output_handler

Path

SIM_add_directory()

NAME

SIM_add_directory — add directory to search path

SYNOPSIS

void
SIM_add_directory(const char *directory, int prepend);

DESCRIPTION

Adds a directory to Simics's search-path. This is a list of directory which Simics uses when searching for files such as disk-dumps, kernel images, etc.

The directory argument is first converted using SIM_native_path, to yield a path on host native form. If the path does not exist, a warning is printed and the path is ignored.

If prepend is set, the directory is inserted first in the list of directories.

This list of directories is saved as the attribute simics-path when doing write-configuration. Each directory is first converted to absolute form if relative.

This function replaces the obsolete function SIM_set_simics_path().

SEE ALSO

SIM_lookup_file

SIM_clear_directories()

NAME

SIM_clear_directories — clear the search path

SYNOPSIS

void
SIM_clear_directories(void);

DESCRIPTION

Deletes all directories from the search path.

SIM_get_directories()

NAME

SIM_get_directories — get the current search path

SYNOPSIS

attr_value_t
SIM_get_directories(void);

DESCRIPTION

Returns the current value of the directory search path.

SIM_lookup_file()

NAME

SIM_lookup_file — find a file using simics-path

SYNOPSIS

const char *
SIM_lookup_file(const char *file);

DESCRIPTION

Searches for a file in the Simics search path as given to SIM_add_directory().

The returned path will always be in host native format, so the returned path will not need to be converted. See SIM_native_path for more details on what "host native format" means.

The search algorithm is as follows.

• If file is NULL, the function fails.
• If file is an absolute path, it is converted to host native form and returned. If the file does not exist, the function fails.
• If file exists in or relative to the current directory, it is returned without using the directory list. This is more or less equivalent of always having "." first in the list.
• For each directory in the search path: The directory and the file is concatenated and converted to host native format. If the resulting file exists, it is returned.

If the function fails, NULL is returned.

If the file was found, a pointer to the full path to the file is returned. The returned string should not be modified.

SIM_native_path()

NAME

SIM_native_path — convert path to its native form

SYNOPSIS

char *
SIM_native_path(const char *path);

DESCRIPTION

Translates a path to its host native form. The only platform for which this function is not a no-op is Windows. The translation can be disabled using the -no-use-cygpath command line flag.

On Windows, this function translates Cygwin style paths into Windows native form. This is implemented internally, the cygpath utility is not invoked. If the path contains a colon (:) or a backslash, the path is assumed to be on native form already, and no translation will be performed.

Translating a Cygwin paths is done by looking up Cygwin mount prefixes in the registry, and replacing any matching prefixes with their native counterpart. Also, Cygwin symlinks are resolved and followed. Finally, any slashes in the path is converted to backslash. The path is not normalized, i.e. the resulting path may contain "..".

Note: the symlink lookup mechanism does not handle the case when nowinsymlink is set in the CYGWIN environment-variable.

The function uses a static buffer to store its result, which will be overwritten at the next call.

Processor

SIM_current_processor()

NAME

SIM_current_processor — get current processor

SYNOPSIS

conf_object_t *
SIM_current_processor(void);

DESCRIPTION

Returns a pointer to the current processor. The returned processor pointer can be used in calls to other API functions, or as a reference to the processor in Python.
The current processor is the processor that Simics currently simulating. See the user manual for further explanation of Simics's simulation model.

EXCEPTIONS

Lookup Thrown if no processor exists.

RETURN VALUE

Processor pointer.

SIM_disassemble()

NAME

SIM_disassemble — disassemble instruction

SYNOPSIS

tuple_int_string_t *
SIM_disassemble(conf_object_t *cpu, generic_address_t addr, int type);

DESCRIPTION

This function disassembles the instruction at the given address. Address is either a physical address (type == 0) or a logical address (type == 1). A pointer to a tuple_int_string_t is returned which contains the disassembly string as well as the length of the instruction (bytes). tuple_int_string_t is defined like this:

typedef struct {
        int integer;
        const char *string;
} tuple_int_string_t;

For the Sparc, Alpha, and PowerPC targets the length is always 4 bytes. On IA-64, the length is undefined.

EXCEPTIONS

General Thrown if arguments are invalid.
Memory Thrown if the address is undefined or not mapped in the MMU (for logical addresses).

SIM_enable_processor()

NAME

SIM_enable_processor, SIM_disable_processor — enable or disable a processor

SYNOPSIS

void
SIM_enable_processor(conf_object_t *cpu);

void
SIM_disable_processor(conf_object_t *cpu);

DESCRIPTION

These functions disables (deactivates) or enables (reactivates) the specified processor. Processors that are disabled simply stall indefinitely. Make sure at least one processor is enabled at any given time.

This function can not be called during the execution of an instruction, for example, in a device or a timing-model. If you wish to call them in these situations, use SIM_stacked_post() to post a callback that will be run as soon as possible after the instruction finished.

EXCEPTIONS

General Thrown if the processor already is enabled/disabled.

SEE ALSO

SIM_processor_enabled

SIM_get_all_processors()

NAME

SIM_get_all_processors — get list of all processors

SYNOPSIS

attr_value_t
SIM_get_all_processors(void);

DESCRIPTION

Return a list of all processor objects.

RETURN VALUE

List of processors.

SIM_get_all_registers()

NAME

SIM_get_all_registers — get all register numbers

SYNOPSIS

attr_value_t
SIM_get_all_registers(conf_object_t *cpu);

DESCRIPTION

Returns a list of all register numbers for a processor. The register numbers can for example be used in calls to SIM_read_register and SIM_write_register.

RETURN VALUE

List of register numbers.

SIM_get_exception_name()

NAME

SIM_get_exception_name, SIM_get_exception_number, SIM_get_all_exceptions — processor exception conversion utilities

SYNOPSIS

const char *
SIM_get_exception_name(conf_object_t *cpu, int exc);

int
SIM_get_exception_number(conf_object_t *cpu, const char *name);

attr_value_t
SIM_get_all_exceptions(conf_object_t *cpu);

DESCRIPTION

These functions convert from a processor exception number to the associated exception name and vice versa. The SIM_get_all_exceptions function can be used to get a list of all exceptions.

EXCEPTIONS

General Thrown if exception cannot be found.

SIM_get_processor()

NAME

SIM_get_processor — get processor pointer from number

SYNOPSIS

conf_object_t *
SIM_get_processor(int proc_no);

DESCRIPTION

Converts processor id number to processor pointer. Note that processors are numbered from 0 to (number_processors - 1). This function cannot be used until a configuration had been loaded succcessfully.

EXCEPTIONS

Index Thrown if no processor with number proc_no exists.

RETURN VALUE

The processor pointer, NULL on failure.

SIM_get_processor_number()

NAME

SIM_get_processor_number — get the number of a processor

SYNOPSIS

int
SIM_get_processor_number(const conf_object_t *cpu);

DESCRIPTION

Returns the global processor number for a processor in Simics.

RETURN VALUE

The processor number

SIM_get_program_counter()

NAME

SIM_get_program_counter, SIM_set_program_counter — read/write program counter

SYNOPSIS

logical_address_t
SIM_get_program_counter(conf_object_t *cpu);

void
SIM_set_program_counter(conf_object_t *cpu, logical_address_t pc);

DESCRIPTION

These functions provide a portable way to examine and update the program counter and stack pointer of a processor.

The actual registers that are read/written depend on the target architecture. For example on the x86-64 architecture the program counter is the RIP register and the stack pointer is the RSP register.

For IA-64, the program counter is the ip register, with the current slot number added to the lowest two bits of the address.

SIM_get_register_number()

NAME

SIM_get_register_number, SIM_get_register_name — convert between register name and register number

SYNOPSIS

int
SIM_get_register_number(conf_object_t *cpu, const char *name);

const char *
SIM_get_register_name(conf_object_t *cpu, int reg);

DESCRIPTION

These functions convert a given register number to the register name or vice versa. Name to number conversion functions are not case sensitive.

EXCEPTIONS

General If the register name is not found. Index If reg index is out of range

RETURN VALUE

Register index or string pointer to name.

SIM_number_processors()

NAME

SIM_number_processors — number of processors

SYNOPSIS

int
SIM_number_processors(void);

DESCRIPTION

Returns the current total number of processors in the system.

RETURN VALUE

Number of processors.

SIM_processor_enabled()

NAME

SIM_processor_enabled — check if processor is enabled

SYNOPSIS

int
SIM_processor_enabled(conf_object_t *cpu);

DESCRIPTION

Returns 1 if the processor is enabled, or 0 if it is disabled.

RETURN VALUE

1 if enabled, else 0.

SEE ALSO

SIM_enable_processor

SIM_processor_privilege_level()

NAME

SIM_processor_privilege_level — return the current privilege level for a processor

SYNOPSIS

int
SIM_processor_privilege_level(conf_object_t *cpu);

DESCRIPTION

Return the current privilege level for a processor. The definition of privilege levels depends on the processor type.

RETURN VALUE

For SPARC, and PowerPC, and ARM processors: 0 for User mode, and 1 for Supervisor mode.
For x86 and IA-64 processors: 0-3, where 0 is the most privileged.
For Alpha processors: 0 for kernel mode, 1 for executive mode, and 3 for user mode.
For MIPS processors: 0

SIM_read_register()

NAME

SIM_read_register — get register value

SYNOPSIS

uinteger_t
SIM_read_register(conf_object_t *cpu, int reg);

DESCRIPTION

Returns the value of the specified processor register.

For the ARM target, this function returns the value of the register in the bank corresponding to the current mode. To access copies of the register in other banks, use the read_register_mode function in the arm interface.

EXCEPTIONS

Index Thrown if reg is out of range.

RETURN VALUE

Value from the register.

SIM_register_arch_decoder()

NAME

SIM_register_arch_decoder, SIM_unregister_arch_decoder — install/uninstall instruction decoders

SYNOPSIS

void
SIM_register_arch_decoder(decoder_t *decoder,
                          const char *arch, int arch_mode);

void
SIM_unregister_arch_decoder(decoder_t *decoder,
                            const char *arch, int arch_mode);

DESCRIPTION

SIM_register_arch_decoder makes it possible to install instruction decoders in Simics. This allows adding instructions, or replacing existing instructions with new implementations.

SIM_unregister_arch_decoder unregisters decoders registered with SIM_register_arch_decoder. SIM_unregister_arch_decoder must not be called while an instruction is executing. This is the case the decode and service routine functions of instruction decoders, in the operate function of the timing-model interface, and in the operation function of the io-memory interface. It is also the case for callbacks for some haps. In these cases, post an event using SIM_stacked_post and unregister the decoder from the event handler.

When Simics decodes an instruction, it will first see if any instruction decoders are registered for the current architecture. For any decoders it finds, Simics will let it try to decode the instruction. The decoders are called in order, starting with the last registered decoder, and if one decoder accepts the instruction, the rest of the decoders will not be called.

When a decoder accepts an instruction, it creates a structure describing the decoded instruction, including a pointer to a function that Simics will call each time the instruction is executed.

decoder is the decoder to register

arch is the target architecture that the decoder can decode instruction for. It is matched against the architecture attribute on CPU objects to determine whether the decoder applies. It can also be given as NULL, which means that the decoders will be used for all CPU architectures. The simplest way to find the value to use is to load a configuration into Simics and check the value of the architecture attribute in the CPU object.

arch_mode is the instruction mode of the architecture. This should always be 0.

The decoder_t type is a structure providing the functions used to invoke the decoder.

typedef struct {
        void *user_data;
        int (*NOTNULL decode)(unsigned char *code,
                              int valid_bytes,
                              conf_object_t *cpu,
                              instruction_info_t *ii,
                              void *user_data);
        int (*NOTNULL disassemble)(unsigned char *code,
                                   int valid_bytes,
                                   conf_object_t *cpu,
                                   char *buffer,
                                   void *user_data);
        int (*NOTNULL flush)(conf_object_t *cpu,
                             instruction_info_t *ii,
                             void *user_data);
} decoder_t;

The decode function is called to decode an instruction pointed to by code. The first byte represents the lowest address of the instruction in the simulated memory. valid_bytes tells how many bytes can be read. The current CPU is given in the cpu parameter. When the decoder has successfully decoded the instruction, it fills in the ii structure, and returns the number of bytes used in the decoding. If it does not apply to the given instruction, it should return zero. If the decoder needs more data it should return a negative number corresponding to the total number of bytes needed. Simics will then call the decoder again with more available bytes. This process is repeated until the decoder accepts or rejects the instruction.

Note that in a shared memory multiprocessor, the cpu used in decoding may differ from the CPU that executes the instruction, since the decoded instructions are cached by Simics.

The disassemble function is called to disassemble an instruction. It uses the same code, valid_bytes, and cpu parameters as the decode function. In addition, it takes a pointer to a string buffer, buffer. The disassembly should be written to this buffer as a null-terminated string with a maximum length of 256 characters, including the null terminator. The return value is handled identically to the that of the decode function.

The flush function is called to free any memory allocated when decoding an instruction, including the register info array. Just like the other functions, it should return zero if it doesn't recognize the instruction, and non-zero if it has handled it. Usually, the way to recognize if a decoded instruction is the right one is to compare ii->ii_ServiceRoutine with what is set in the decode function. Note that the cpu parameter is the processor that caused the flush. It is more or less an arbitrary processor and should be ignored.

In addition to the function pointers, the structure contains a user_data pointer that is passed to all the functions. This can be used for passing any data to the decoder functions.

The instruction_info_t is defined like this.

typedef struct instruction_info {
        service_routine_t  ii_ServiceRoutine;
        unsigned int       ii_Arg;
        unsigned int       ii_Type;
        reg_info_t        *ii_RegInfo;
        lang_void         *ii_UserData;
        logical_address_t  ii_LogicalAddress;
        physical_address_t ii_PhysicalAddress;
} instruction_info_t;

ii_ServiceRoutine is a pointer to a service routine to be called by Simics every time the instruction is executed. It has the following prototype:

typedef exception_type_t (*service_routine_t)(conf_object_t *cpu, 
                                              unsigned int arg, 
                                              lang_void *user_data);

ii_Arg is the argument that will be passed on to the service routine. It typically contains a bit-field of parameters to the instruction such as register numbers or intermediate values. It can also be a pointer to a structure if more appropriate.

ii_Type is either UD_IT_SEQUENTIAL or UD_IT_CONTROL_FLOW. A sequential type means that the instruction does not perform any branches and the update of the program counter(s) is handled by Simics. In a control flow instruction on the other hand it is up to the user to set the program counter(s).

ii_RegInfo should be used if Simics is running in out of order mode. An array of reg_info_t should be allocated that describes the registers the instruction uses and if they are used as input and/or output. The array should be terminated with a dummy register (id equal to 0) which is neither input nor output (in and out both zero).

struct reg_info {
        register_type_t type;   /* register type */
        register_id_t id;       /* register id */
        unsigned input:1;       /* used as input */
        unsigned output:1;      /* used as output */
};

typedef struct reg_info reg_info_t;

The register_id of the PC(s) should not be filled in, Simics handles that automatically. If the instruction manipulates a register not listed the value Sim_RI_Sync should be used, this will disallow the instruction to run out of order.

The array needs to be deallocated when the instruction is flushed, see below.

ii_UserData can be filled in with other data.

The service routine function should return an exception when it is finished to signal its status. If no exception occurs Sim_PE_No_Exception should be returned.

See exception_type_t in core/types.h for the different exceptions available.

A special return value, Sim_PE_Default_Semantics, can be returned; this signals Simics to run the default semantics for the instruction. This is useful if the semantics of an instruction should be changed but the user routine does not want to handle it all the time.

EXAMPLE

See the source code for the example extension sample-user-decoder in [simics]/src/extensions.

EXCEPTIONS

General Thrown if the same decoder is registered twice for the same architecture.

IllegalValue Thrown if the decoder doesn't have all function pointers set.

SEE ALSO

register_id_t

SIM_register_decoder()

NAME

SIM_register_decoder, SIM_unregister_decoder — deprecated install/uninstall user decoders

SYNOPSIS

void
SIM_register_decoder(user_decoder_t decoder);

void
SIM_unregister_decoder(user_decoder_t decoder);

DESCRIPTION

These functions are obsolete, use the SIM_register_arch_decoder and SIM_unregister_arch_decoder functions instead.

SIM_register_decoder makes it possible to install user decoders in Simics. This gives the user an interface to the instruction set allowing changes to the instructions semantics, adding new instructions or removing implemented ones.

When simics decodes an instructions it will first see if any user decoder is supplied and in that case call it first. Several decoders can be installed and Simics will call them in the reverse order they were registered; i.e., the last one first. Every decoder has the option of either accepting the opcode given or pass it on to the next decoder.

If a decoder accepts the instruction it fills in an information structure which contains a function pointer that Simics will call each time the instruction should be executed.

user_decoder is the decoder to register, it is defined like this:

typedef int (*NOTNULL user_decoder_t)(unsigned char *code,
                                      int valid_bytes,
                                      conf_object_t *cpu,
                                      instruction_info_t *ii,
                                      int action,
                                      char *string_buffer);

code is a pointer to the instruction to decode. The first byte represents the lowest address of the instruction in the simulated memory. valid_bytes tells how many bytes can be read. If the decoder needs more data it should return a negative number corresponding to the total number of bytes needed. Simics will then call the decoder again with more available bytes. This process is repeated until the decoder accepts or rejects the instruction. If the instruction is accepted its length in bytes should be returned, otherwise zero.

cpu is the cpu decoding the instruction. Note that in a shared memory multiprocessor, this may differ from the one executing the instruction since decoded instructions are cached.

action is whether Simics wants to decode, disassemble or flush a previously decoded instruction. For decoding, the value is UD_ACTION_DECODE and the instruction_info_t structure ii should be filled in. The structure has the following fields:

typedef struct instruction_info {
        service_routine_t  ii_ServiceRoutine;
        unsigned int       ii_Arg;
        unsigned int       ii_Type;
        reg_info_t        *ii_RegInfo;
        lang_void         *ii_UserData;
        logical_address_t  ii_LogicalAddress;
        physical_address_t ii_PhysicalAddress;
} instruction_info_t;

ii_ServiceRoutine is a pointer to a service routine to be called by Simics every time the instruction is executed. It has the following prototype:

typedef exception_type_t (*service_routine_t)(conf_object_t *cpu, 
                                              unsigned int arg, 
                                              lang_void *user_data);

ii_Arg is the argument that will be passed on to the service routine. It typically contains a bit-field of parameters to the instruction such as register numbers or intermediate values. It can also be a pointer to a structure if more appropriate.

ii_Type is either UD_IT_SEQUENTIAL or UD_IT_CONTROL_FLOW. A sequential type means that the instruction does not perform any branches and the update of the program counter(s) is handled by Simics. In a control flow instruction on the other hand it is up to the user to set the program counter(s).

ii_RegInfo should be used if Simics is running in out of order mode. An array of reg_info_t should be allocated that describes the registers the instruction uses and if they are used as input and/or output. The array should be terminated with a dummy register (id equal to 0) which is neither input nor output (in and out both zero).

struct reg_info {
        register_type_t type;   /* register type */
        register_id_t id;       /* register id */
        unsigned input:1;       /* used as input */
        unsigned output:1;      /* used as output */
};

typedef struct reg_info reg_info_t;

The register_id of the PC(s) should not be filled in, Simics handles that automatically. If the instruction manipulates a register not listed the value Sim_RI_Sync should be used, this will disallow the instruction to run out of order.

The array needs to be deallocated when the instruction is flushed, see below.

ii_UserData can be filled in with other data.

The service routine function should return an exception when it is finished to signal its status. If no exception occurs Sim_PE_No_Exception should be returned.

See exception_type_t in core/types.h for the different exceptions available.

A special return value, Sim_PE_Default_Semantics, can be returned; this signals Simics to run the default semantics for the instruction. This is useful if the semantics of an instruction should be changed but the user routine does not want to handle it all the time.

If Simics wants to disassemble the instruction the action value will be UD_ACTION_DISASS and the string_buffer should be filled with the disassembled instruction (max length is 256 characters). The ii structure should be ignored.

A value of UD_ACTION_FLUSH (code and string_buffer will be null, valid_bytes zero) means that Simics wants to flush a cached decoded instruction. The instruction_info_t structure ii will then hold the values previously stored there. If the user-decoder recognizes the ii->ii_ServiceRoutine function as its own it should now free all allocated user data including the register info array, if allocated, and return a non-zero value to indicate success. Otherwise zero should be returned letting other user-decoders have a shot.

Use SIM_unregister_decoder to remove a user-decoder.

EXAMPLE

See the source code for the example extension decoder.

SEE ALSO

SIM_register_arch_decoder

SIM_reset_processor()

NAME

SIM_reset_processor — reset the processor

SYNOPSIS

void
SIM_reset_processor(conf_object_t *cpu, int hard_reset);

DESCRIPTION

Performs a reset on the processor, causing a System Reset exception to be taken when execution continues. cpu is the processor that should be reset. hard_reset indicates if a soft (0) or hard (1) (power-on type) reset should be performed. If a hard reset is requested, a number of register are initiated with default values.

EXCEPTIONS

General Thrown if cpu does not implement reset.

SIM_write_register()

NAME

SIM_write_register — set register value

SYNOPSIS

void
SIM_write_register(conf_object_t *cpu, int reg, uinteger_t value);

DESCRIPTION

Sets the value of the specified processor register.

For the ARM target, this function sets the value of the register in the bank corresponding to the current mode. To access copies of the register in other banks, use the write_register_mode function in the arm interface.

EXCEPTIONS

Index Thrown if reg is out of range.

Profiling

SIM_iter_next()

NAME

SIM_iter_next, SIM_iter_addr, SIM_iter_free — Iterate over address profile counters

SYNOPSIS

FORCE_INLINE uint64
SIM_iter_next(addr_prof_iter_t *iter);

FORCE_INLINE generic_address_t
SIM_iter_addr(addr_prof_iter_t *iter);

FORCE_INLINE void
SIM_iter_free(addr_prof_iter_t *iter);

DESCRIPTION

EXPERIMENTAL. While this functionality is expected to be retained in future releases, the interface is likely to change.

An address profile iterator visits some of the counters of an address profiler in some order. It is obtained from the iter function of the address_profiler interface.

SIM_iter_next advances the address profile iterator iter to the next nonzero counter and returns the count. It will return 0 when there are no more counters to visit. Note that the order in which the counters are visited is unspecified.

SIM_iter_addr returns the address of the counter returned by the most recent call to iter_next.

When you are done with the iterator, deallocate it with SIM_iter_free.

Simulation Control

SIM_break_message()

NAME

SIM_break_message — stop the simulation

SYNOPSIS

void
SIM_break_message(const char *msg);

DESCRIPTION

Display the reason why Simics will stop simulation.

This is similar to SIM_break_simulation, with the difference that it doesn't actually break the simulation. It can be used by code that wants to display a break message and stop the simulation by some other means.

SEE ALSO

SIM_break_simulation

SIM_break_simulation()

NAME

SIM_break_simulation — stop the simulation

SYNOPSIS

void
SIM_break_simulation(const char *msg);

DESCRIPTION

Ask Simics to stop the simulation as soon as possible, displaying the supplied message.

Simics will normally stop before the next instruction is executed. If this function is called when an instruction has started executing, and the instruction can be aborted, it will rewind to before the instruction. This might leave the simulation is a state where some repeatable part of the instruction is already executed.

SEE ALSO

SIM_break_message

SIM_continue()

NAME

SIM_continue — continue the simulation

SYNOPSIS

pc_step_t
SIM_continue(integer_t steps);

DESCRIPTION

Runs the simulation the specified number of steps on the current CPU. Since Simics is scheduling the processors in a round-robin fashion, other CPUs may run as well. This happens if steps is greater than what is left of the current CPU's time quantum. Simics will then run the other CPUs for their time quanta and then return to to the first CPU executing the remaining steps. This can happen several times if steps cover several time quanta.

The function may return before completing steps steps if a breakpoint is reached, user code requests the simulation to be interrupted, or execution is interrupted via the user interface. In such cases the current CPU may have changed (see SIM_current_processor()) since Simics may have been executing in another processor's time quantum.

If steps is 0, Simics will run forever or until it is interrupted as described above.

If this function is called from a context where simulation cannot continue, e.g., from a callback function passed to SIM_post_command(), SIM_continue() will return immediately with return value 0 but the simulation will not be started until the calling function has exited. If this is the case, any exceptions returned from the simulation core will be discarded but the return value from the simulation can be read as an argument to the Core_Simulation_Stopped hap. You can query whether the current state will result in such a postponed continuation by calling the SIM_postponing_continue() function.

RETURN VALUE

The number of steps actually executed

EXCEPTIONS

General Thrown if steps has illegal value, a breakpoint is reached, or Simics already was running.

SEE ALSO

SIM_post_command, SIM_postponing_continue, Core_Simulation_Stopped

SIM_postponing_continue()

NAME

SIM_postponing_continue — ask if continue will be postponed

SYNOPSIS

int
SIM_postponing_continue(void);

DESCRIPTION

This function returns non-zero if calls to SIM_continue() would return immediately, postponing the actual call to the Simics core.

SIM_simics_is_running()

NAME

SIM_simics_is_running — check if Simics is running

SYNOPSIS

int
SIM_simics_is_running(void);

DESCRIPTION

Returns 1 if simics is running, i.e., executing target instructions, or 0 otherwise.

Simulation Independent Services

SIM_cancel_realtime_event()

NAME

SIM_cancel_realtime_event — cancel callback in host time

SYNOPSIS

int
SIM_cancel_realtime_event(integer_t id);

DESCRIPTION

Cancel a callback registered by SIM_realtime_event, whose return value is specified as id.

Returns 0 if the callback existed and was cancelled, or -1 if no callback with that identifier existed. (No exception is raised.)

SEE ALSO

SIM_realtime_event

SIM_notify_on_socket()

NAME

SIM_notify_on_socket, SIM_notify_on_object, SIM_notify_on_descriptor — register notification on host I/O events

SYNOPSIS

void
SIM_notify_on_socket(int sock, notify_mode_t mode, int run_in_thread,
                     void (*callback)(lang_void *data), lang_void *data);

void
SIM_notify_on_object(HANDLE obj, int run_in_thread,
                     void (*callback)(lang_void *data), lang_void *data);

void
SIM_notify_on_descriptor(int fd, notify_mode_t mode, int run_in_thread,
                         void (*callback)(lang_void *data),
                         lang_void *data);

DESCRIPTION

These functions allows the function callback to be called with argument data whenever a specific I/O event occurs on the host machine. If callback is a null function pointer, a previously installed notification is removed.

If run_in_thread is nonzero, the callback function may be run in a thread where it cannot access or call anything in Simics except for these functions and SIM_thread_safe_callback. If run_in_thread is zero, the callback function is always run in the main thread. This may incur a small penalty in latency (time between the occurrence of the host event and execution of callback).

Notification on a specific event will be blocked during the execution of its callback function.

SIM_notify_on_socket will call a registered callback depending on mode:

mode	condition
Sim_NM_Read	Socket is readable, closed, or incoming connection accepted
Sim_NM_Write	Socket is writeable, or outgoing connection has completed

Unix only: SIM_notify_on_descriptor will call a registered callback depending on mode for a given file descriptor in a way similar to SIM_notify_on_socket.

Windows only: SIM_notify_on_object will call a registered callback when object (which must be a waitable object) is in signalled state. The signalling object is modified in the same way as the Windows wait functions (WaitForMultipleObjects etc).

---

Note: A notification should be removed before its socket or descriptor is closed.

---

SEE ALSO

SIM_thread_safe_callback

SIM_realtime_event()

NAME

SIM_realtime_event — schedule callback in host time

SYNOPSIS

integer_t
SIM_realtime_event(unsigned delay, void (*callback)(lang_void *data),
                   lang_void *data, int run_in_thread, const char *desc);

DESCRIPTION

Register callback to be run in delay ms, with argument data. The delay is in real time (on the host machine), and the actual delay may be somewhat larger because of host scheduling.

If run_in_thread is nonzero, the callback may be run in a thread where it cannot access or call anything in Simics except for SIM_thread_safe_callback. If run_in_thread is zero, the callback function is always run in the main thread. This may cause the call to occur slightly later than requested, depending on what Simics is doing at the time.

The desc parameter is only present for debugging and has no other effect; it should be a static string describing the callback but may also be left NULL if desired.

The callback is only called once.

The return value is a non-zero identifier that can be used to cancel the callback using SIM_cancel_realtime_event.

SEE ALSO

SIM_cancel_realtime_event, SIM_thread_safe_callback

SIM_thread_safe_callback()

NAME

SIM_thread_safe_callback — call function synchronized with main thread

SYNOPSIS

void
SIM_thread_safe_callback(void (*f)(lang_void *data), lang_void *data);

DESCRIPTION

This is the only function in the Simics API that can be called from threads other than the main simics thread. Failure to abide by this rule will result in undefined behavior. The user should not make any assumptions about when the supplied function is called. It may be called immediately, but it may also be called after this function has returned.

Simulator Translation Caches

SIM_STC_flush_cache()

NAME

SIM_STC_flush_cache, SIM_flush_I_STC_logical, SIM_flush_D_STC_logical, SIM_flush_I_STC_physical, SIM_flush_D_STC_physical — flush or remove entries in the STCs of a cpu

SYNOPSIS

void
SIM_STC_flush_cache(conf_object_t *cpu);

void
SIM_flush_I_STC_logical(conf_object_t *cpu,
                        logical_address_t vaddr,
                        logical_address_t length);

void
SIM_flush_D_STC_logical(conf_object_t *cpu,
                        logical_address_t vaddr,
                        logical_address_t length);

void
SIM_flush_I_STC_physical(conf_object_t *cpu,
                         physical_address_t paddr,
                         physical_address_t length);

void
SIM_flush_D_STC_physical(conf_object_t *cpu,
                         physical_address_t paddr,
                         physical_address_t length,
                         read_or_write_t read_or_write);

DESCRIPTION

These functions remove entries from the Simics internal caches (STCs) or completely flushes the STCs contents. Memory mappings which have been cached in the STCs will be faster for Simics to execute. Simics extensions such as a cache model will need to flush entries in the STC when a cache line is replaced, in order to be called when a cache line is used again.

SIM_STC_flush_cache() flushes the entire contents of the STCs (both instruction and data) from the specified cpu.

The SIM_flush_xxx functions removes specified memory ranges in the instruction or data STC. The address range is either the logical or the physical address. The read_or_write parameter specifies whether the read or the write D-STC should be flushed. If the function doesn't have such a parameter, both read and write D-STCs are flushed. The flushed address range is at least [ vaddr ... (vaddr + length − 1) ], but may be larger. SIM_flush_D_STC_logical() currently always flushes an entire page.

SIM_flush_all_caches()

NAME

SIM_flush_all_caches — clear Simics's internal caches

SYNOPSIS

void
SIM_flush_all_caches(void);

DESCRIPTION

Clears Simics's internal caches such as STC contents and intermediate code. This function is mainly for Virtutech internal use (for debugging purposes) and may be removed in the future.

Stalling

SIM_release_stall()

NAME

SIM_release_stall — release stalling transaction

SYNOPSIS

void
SIM_release_stall(conf_object_t *obj, int id);

DESCRIPTION

Sometimes the stalling period of an memory transaction is not known by the timing model. This can happen for example if the transaction is blocked by another transaction. In such case a very long stall-time can be returned to block the transaction. As soon as the timing model finds out when the stalling is over the memory transaction needs to be released.

This function changes the stalling period for a memory transaction with id id on CPU cpu to zero. This means that the memory transaction may be issued the second time in the next cycle.

NOTE

Only useful if Simics is running in out of order mode.

SIM_stall_count()

NAME

SIM_stall_count — get number of cycles a processor has been stalled

SYNOPSIS

cycles_t
SIM_stall_count(conf_object_t *obj);

DESCRIPTION

SIM_stall_count returns the total number of cycles the processor associated to obj has been stalled.

EXCEPTIONS

General Thrown if obj is NULL.

RETURN VALUE

Returns the total number of cycles the processor associated with obj has been stalled.

SIM_stall_cycle()

NAME

SIM_stall_cycle, SIM_stall — stall execution a specified number of cycles

SYNOPSIS

void
SIM_stall_cycle(conf_object_t *obj, cycles_t cycles);

void
SIM_stall(conf_object_t *obj, double seconds);

DESCRIPTION

SIM_stall_cycle sets the stall time at obj. cycles is the number of clock cycles the processor will stall. A call to this function will overwrite the current time left to stall at obj. No compensation is made if time differs between obj and where the function is called from.

SIM_stall does the same thing as SIM_stall_cycle but the stall time is given in seconds.

EXCEPTIONS

General Thrown if obj is NULL.
General Thrown if cycles or seconds is negative.

SIM_stalled_until()

NAME

SIM_stalled_until — query how many cycles that remains of stall

SYNOPSIS

cycles_t
SIM_stalled_until(conf_object_t *obj);

DESCRIPTION

SIM_stalled_until returns how many more cycles the processor will stall before the associated processor starts to execute instructions again.

EXCEPTIONS

General Thrown if obj is NULL.

RETURN VALUE

Number of cycles remaining of stall.

Step and Time Events

SIM_cycle_count()

NAME

SIM_cycle_count, SIM_time — query time queue for current time

SYNOPSIS

cycles_t  
SIM_cycle_count(conf_object_t *obj);

double
SIM_time(conf_object_t *obj);

DESCRIPTION

SIM_cycle_count returns current simulated clock cycle count at obj. Note that if processors are running at different frequency, the number will differ between processors, regardless of simulation quantum effects.

SIM_time returns current time at obj. Time is counted in seconds and has a maximum resolution of one clock cycle.

EXCEPTIONS

General Thrown if obj is NULL.

RETURN VALUE

SIM_cycle_count returns the current time in number of cycles. SIM_time returns the current time in seconds as a floating point value.

SIM_next_queue()

NAME

SIM_next_queue — get next object that owns a queue

SYNOPSIS

conf_object_t* 
SIM_next_queue(conf_object_t *obj);

DESCRIPTION

Returns the next object that owns an event queue. This function can be used to iterate over all step and time queues. Passing a NULL argument will return the first object. When given the last object it will return NULL.

EXCEPTIONS

General Object does not own an event queue.

RETURN VALUE

Next object that owns an event queue or NULL if last.

BUGS

There is no check that obj owns a queue, which it must.

SIM_stacked_post()

NAME

SIM_stacked_post — insert an event that runs as soon as possible

SYNOPSIS

void 
SIM_stacked_post(conf_object_t *obj,
                 event_handler_t func,
                 lang_void *user_data);

DESCRIPTION

The func function will be called with obj and user_data as arguments as soon as the current instruction has completed. SIM_stacked_post will call the function after the current instruction or event handler has returned.

Time is undefined when the function is called. If several functions are registered this way before any of them has had a chance to run, the last registered will run first.

This call is mainly useful for actions that for various reasons cannot be done inside an instruction.

EXCEPTIONS

General Thrown if obj or func is NULL.

SIM_step_clean()

NAME

SIM_step_clean — remove events from the step queue

SYNOPSIS

void 
SIM_step_clean(conf_object_t *obj, 
               event_handler_t func,
               typed_lang_void *user_data);

DESCRIPTION

SIM_step_clean removes all events in the step queue associated with obj that match func and user_data. If user_data is NULL it will match any parameter thus removing all matching handlers regardless of their parameter.

EXCEPTIONS

General Thrown if obj or func is NULL.

SIM_step_count()

NAME

SIM_step_count — query step queue count

SYNOPSIS

pc_step_t
SIM_step_count(conf_object_t *obj);

DESCRIPTION

SIM_step_count returns the number of executed program counter steps at obj. The number of steps equal completed instructions + instructions getting exception + interrupts.

EXCEPTIONS

General Thrown if obj is NULL.

RETURN VALUE

number of pc steps, or zero if given a NULL pointer.

SIM_step_next_occurrence()

NAME

SIM_step_next_occurrence — get number of steps until a step queue event occurs

SYNOPSIS

pc_step_t 
SIM_step_next_occurrence(conf_object_t *obj, 
                         event_handler_t func,
                         typed_lang_void *user_data);

DESCRIPTION

SIM_step_next_occurrence finds first event in objs associated step queue that matches func and user_arg. If user_arg is NULL it will match any parameter. Returns steps to occurrence + 1, or zero if there is no match.

EXCEPTIONS

General Thrown if obj or func is NULL.

RETURN VALUE

steps to event + 1, or 0 if no such event is in the queue.

SIM_step_post()

NAME

SIM_step_post — add an event in step queue

SYNOPSIS

void
SIM_step_post(conf_object_t *obj, pc_step_t steps,
              event_handler_t func, lang_void *user_data);

DESCRIPTION

SIM_step_post enqueues an event in the step queue. After steps steps at the processor associated to obj, the event will occur, i.e. func will be called with obj and user_data as arguments.

EXCEPTIONS

General Thrown if obj or func is NULL.

SIM_time_clean()

NAME

SIM_time_clean — remove all matching events from time queue

SYNOPSIS

void 
SIM_time_clean(conf_object_t *obj, 
               sync_t sync,
               event_handler_t func,
               typed_lang_void *user_data);

DESCRIPTION

SIM_time_clean removes all events in obj's associated time queue that matches sync, func and user_data. If user_data is NULL it will match any parameter, thus removing all installed functions that match regardless of the argument to handler.

EXCEPTIONS

General Thrown if obj or func is NULL.

SIM_time_next_occurrence()

NAME

SIM_time_next_occurrence — get cycles to matching event

SYNOPSIS

cycles_t 
SIM_time_next_occurrence(conf_object_t *obj,
                         event_handler_t func,
                         typed_lang_void *user_data);

DESCRIPTION

SIM_time_next_occurrence finds first event in the time queue associated to obj that matches func and user_data. If the user_data argument is NULL it will match any parameter. Returns time to occurrence + 1, or zero if there is no match.

EXCEPTIONS

General Thrown if obj or func is NULL.

RETURN VALUE

SIM_time_next_occurrence returns cycles to event + 1, 0 if no match.

SIM_time_post()

NAME

SIM_time_post, SIM_time_post_cycle — add event to time queue

SYNOPSIS

void 
SIM_time_post(conf_object_t *obj,
              double seconds,
              sync_t sync,
              event_handler_t func,
              lang_void *user_data);

void 
SIM_time_post_cycle(conf_object_t *obj,
                    cycles_t cycles,
                    sync_t sync,
                    event_handler_t func,
                    lang_void *user_data);

DESCRIPTION

SIM_time_post will schedule an event that will occur after delta_seconds counted from local current time at obj. The time is rounded down to the nearest clock cycle, except between zero (inclusive) up to one where it will be rounded up to one. At that time func() will be called with obj and user_data as arguments.

typedef enum {
        Sim_Sync_Processor = 0,
        /* Sim_Sync_Node = 1,            not supported yet */
        Sim_Sync_Machine = 2
} sync_t;

If sync is set to Sim_Sync_Machine, all other objects will have the same local time when the event occurs. This requires that the delta is larger than the simulation time quantum if the simulation is not currently synchronized. If the delta is smaller than the quantum and time is not synchronized, it will be set to the quantum before the event is inserted.

SIM_time_post_cycle does the same as SIM_time_post but time is specified as a number of clock cycles, not in seconds. zero cycles is not rounded up to one cycle. Note that the clock cycle length is typically set in the simics configuration and may differ between processors.

SIM_time_next_occurrence finds first event in the time queue associated with obj that matches func and user_data. If the user_data argument is NULL, it will match any parameter. Returns the time to occurrence + 1, or zero if there is no match.

SIM_time_clean removes all events in objs associated time queue that matches func and user_data. If user_data is NULL, it will match any parameter, thus removing all functions that match regardless of the argument to func. Note that the older version of SIM_time_clean() without the sync parameter is deprecated since Simics 1.6.

SIM_cycle_count returns current simulated clock cycle count at obj. Note that if processors are running at different frequency, the number will differ between processors, regardless of simulation quantum effects.

SIM_time returns current time at obj. Time is counted in seconds and has a maximum resolution of a clock cycle.

SIM_stall_cycle set the stall time at obj. cycle is the number of clock cycles the processor will stall. A call to this function will overwrite the current time left to stall at obj. No compensation is made if time differs between obj and where the function is called from.

SIM_stall does the same thing as SIM_stall_cycle but the stall time is given in seconds.

SIM_stalled_until returns how may more cycles the processor will stall.

SIM_stall_count returns the total number of cycles the processor has been stalled.

EXCEPTIONS

Index Thrown if sync has an illegal value.
General Thrown if obj or func is NULL.
General Thrown if seconds violates the minimum time quantum for a synchronizing event or if it is negative.

User Interface

SIM_get_batch_mode()

NAME

SIM_get_batch_mode — return setting of the batch-mode

SYNOPSIS

int
SIM_get_batch_mode(void);

DESCRIPTION

This function returns the current value of Simics's batch-mode flag.

SIM_is_interactive()

NAME

SIM_is_interactive — running interactive command predicate

SYNOPSIS

int
SIM_is_interactive(void);

DESCRIPTION

Returns true if Simics is running commands from the Simics prompt, as opposed to running commands from a file via the -x command line option, the run-command-file CLI command, or the SIM_run_command_file() API function.

SIM_post_command()

NAME

SIM_post_command — post callback to be run when simulation is stopped

SYNOPSIS

void
SIM_post_command(void (*f)(lang_void *data), lang_void *data);

DESCRIPTION

This function posts f(data) to be called from a "stable" state in Simics. This means that Simics will stop the simulation, if it is in progress (causing a Core_Simulation_Stopped hap), finish running any event-handlers, hap-handlers, or commands, and then do the call.

Note that the simulation will be stopped when f returns, but any call to SIM_continue() from within f will cause the simulation to restart immediately after.

---

Note: This function is deprecated, and may disappear in a future release.

---

SEE ALSO

SIM_continue

SIM_quit()

NAME

SIM_quit — quit Simics

SYNOPSIS

void
SIM_quit(int exit_code);

DESCRIPTION

Quit Simics in orderly fashion. The Simics process will return the value exit_code.

SIM_run_command_file()

NAME

SIM_run_command_file — read CLI commands from file

SYNOPSIS

void
SIM_run_command_file(const char *file);

DESCRIPTION

Read and execute the script-file file; i.e., execute each line in the file as if it was typed at the Simics prompt.

This function is functionally equivalent to the -x command line option.

SEE ALSO

run-command-file

SIM_set_prompt()

NAME

SIM_set_prompt — change prompt in Simics

SYNOPSIS

void
SIM_set_prompt(const char *new_prompt);

DESCRIPTION

Change the current command-line prompt in Simics.

SIM_source_python()

NAME

SIM_source_python, SIM_source_python_in_module — execute Python source file

SYNOPSIS

void
SIM_source_python(const char *file);

void
SIM_source_python_in_module(const char *file, const char *module);

DESCRIPTION

SIM_source_python() will execute a Python source file as specified by the file name file. Note that this assumes that the Python frontend has been loaded (this is the default frontend in Simics). SIM_source_python_in_module() is similar but imports the file in a named Python module.

EXCEPTIONS

General Thrown if there was an error when executing the Python script.

3.3.3   PCI

The PCI Device API is a set of functions that simplifies the work of writing PCI devices in Simics. The functions are implemented in the file src/devices/pci-device/pci-device.c. This file has to be included as a source file in modules using the API. The Simics User Guide contain descriptions of PCI in Simics, and how to write own PCI devices.

Function List

PCIE_send_message()

NAME

PCIE_send_message — send a message to root complex

SYNOPSIS

void
PCIE_send_message(pci_device_t *pci, pcie_message_type_t type, 
                  byte_string_t payload);

DESCRIPTION

Send a PCI Express message to the root complex, of a given type with a possibly empty payload. This function is only available to PCI Express devices.

The pcie_message_type_t has the following definition:

typedef enum {
        /* INTx emulation */
        PCIE_Msg_Assert_INTA       = 0x20,
        PCIE_Msg_Assert_INTB       = 0x21,
        PCIE_Msg_Assert_INTC       = 0x22,
        PCIE_Msg_Assert_INTD       = 0x23,
        PCIE_Msg_Deassert_INTA     = 0x24,
        PCIE_Msg_Deassert_INTB     = 0x25,
        PCIE_Msg_Deassert_INTC     = 0x26,
        PCIE_Msg_Deassert_INTD     = 0x27,

        /* Power Management */
        PCIE_PM_Active_State_Nak   = 0x14,
        PCIE_PM_PME                = 0x18,
        PCIE_PM_Turn_Off           = 0x19,
        PCIE_PM_PME_TO_Ack         = 0x1B,

        /* Error Messages */
        PCIE_ERR_COR               = 0x30,
        PCIE_ERR_NONFATAL          = 0x31,
        PCIE_ERR_FATAL             = 0x33,

        /* Locked Transaction */
        PCIE_Locked_Transaction    = 0x00,

        /* Slot Power Limit */
        PCIE_Set_Slot_Power_Limit  = 0x90,

        /* Hot Plug Messages */
        PCIE_HP_Power_Indicator_On        = 0x45,
        PCIE_HP_Power_Indicator_Blink     = 0x47,
        PCIE_HP_Power_Indicator_Off       = 0x44,
        PCIE_HP_Attention_Button_Pressed  = 0x48,
        PCIE_HP_Attention_Indicator_On    = 0x41,
        PCIE_HP_Attention_Indicator_Blink = 0x43,
        PCIE_HP_Attention_Indicator_Off   = 0x40
} pcie_message_type_t;

PCI_add_config_register()

NAME

PCI_add_config_register — add device specific configuration register

SYNOPSIS

void
PCI_add_config_register(pci_device_t *pci, uint32 offset,
                        const char *name, int size, uint32 mask,
                        uint32 initial_value);

DESCRIPTION

Adds a device specific configuration register to the generic PCI device. When the generic PCI code knows the size of the register, it can handle overlapping register accesses. This means that the conf_write_func function (registered with PCI_device_init) always will be called with an offset that is the start of a register. It is not possible to override the standard configuration registers using this function. The mask argument is the write mask. Only bits set in this mask will be writable in the register. Note that register names and sizes are not checkpointed and always has to be initialized when a device is instantiated. The mask, however, is checkpointed since it may be changed at run-time.

The newly created config register will contain initial_value.

PCI_bridge_default_access_not_taken()

NAME

PCI_bridge_default_access_not_taken — default handling of unclaimed accesses

SYNOPSIS

exception_type_t
PCI_bridge_default_access_not_taken(
        conf_object_t *obj,
        conf_object_t *src_space, conf_object_t *dst_space,
        exception_type_t ex,
        generic_transaction_t *mem_op,
        map_info_t mapinfo);

DESCRIPTION

If no callback is installed to handle accesses to unmapped addresses for type 1 devices, then this function is called. It set the master abort flag in the Secondary Status register, and return a value with all ones. Master abort mode 1, where a target abort on the primary bus is signalled instead, is currently not implemented.

PCI_bridge_default_interrupt_lowered()

NAME

PCI_bridge_default_interrupt_lowered — default handling of secondary interrupts

SYNOPSIS

static void
PCI_bridge_default_interrupt_lowered(conf_object_t *obj, 
                                     conf_object_t *irq_obj,
                                     int dev, int pin);

DESCRIPTION

Performs the default handling of lowered interrupts on the secondary PCI bus that should be routed to the primary bus. The interrupt line is changed in the following way: pin = (pin + device) % 4. It is possible to override this function using PCI_bridge_init.

PCI_bridge_default_interrupt_raised()

NAME

PCI_bridge_default_interrupt_raised — default handling of secondary interrupts

SYNOPSIS

static void
PCI_bridge_default_interrupt_raised(conf_object_t *obj, 
                                    conf_object_t *irq_obj,
                                    int dev, int pin);

DESCRIPTION

Performs the default handling of raised interrupts received on the secondary PCI bus that should be routed to the primary bus. The interrupt line is changed in the following way: pin = (pin + device) % 4. It is possible to override this function using PCI_bridge_init.

PCI_bridge_default_system_error()

NAME

PCI_bridge_default_system_error — default system error handling for bridges

SYNOPSIS

void
PCI_bridge_default_system_error(conf_object_t *obj);

DESCRIPTION

If no callback is installed to handle system errors for type 1 devices, then this function is called. It will set the system error received bit in the Secondary Status register, and signal system error on the primary bus.

PCI_bridge_init()

NAME

PCI_bridge_init — Initialize generic PCI bridge device

SYNOPSIS

void
PCI_bridge_init(pci_device_t *pci,
                void (*system_error)(conf_object_t *obj),
                exception_type_t (*access_not_taken)(
                        conf_object_t *obj,
                        conf_object_t *src_space,
                        conf_object_t *dst_space,
                        exception_type_t ex,
                        generic_transaction_t *mem_op,
                        map_info_t mapinfo),
                void (*interrupt_raised)(
                        conf_object_t *obj, 
                        conf_object_t *dev_obj,
                        int device, int pin),
                void (*interrupt_lowered)(
                        conf_object_t *obj, 
                        conf_object_t *dev_obj,
                        int device, int pin),
                int forward_io, int forward_io32,
                int forward_mem,
                int forward_prefetchable, 
                int forward_prefetchable64);

DESCRIPTION

Initializes a generic PCI-to-PCI (type 1) device. This function should be called directly after PCI_device_init. The system_error callback can be set to receive system errors on the secondary bus. If none is given, the PCI_bridge_default_system_error function is used as default. Similarly for the access_not_taken argument, that defaults to PCI_bridge_default_access_not_taken. The interrupt_raised and interrupt_lowered functions can be used to override PCI_bridge_default_interrupt_raised and PCI_bridge_default_interrupt_lowered. The next arguments specify what kind of transactions that the bridge supports. 16-bit I/O, 32-bit I/O operations, memory, prefetchable memory and 64-bit prefetchable memory operations.

PCI_bridge_map_setup()

NAME

PCI_bridge_map_setup — Set optional memory mapping attributes

SYNOPSIS

void
PCI_bridge_map_setup(
        pci_device_t *pci,
        int io_down_priority, int io_down_align_size, int io_down_endian,
        int mem_down_priority, int mem_down_align_size, int mem_down_endian,
        int pref_down_priority, int pref_down_align_size, int pref_down_endian,
        int io_up_priority, int io_up_align_size, int io_up_endian,
        int mem_up_priority, int mem_up_align_size, int mem_up_endian);

DESCRIPTION

Configures the bridge's memory mappings. The priority, align_size boundary and a reverse-endian flag can be set for each mapping. These values are described in the map attribute of the memory-space class. Default is 0 for all values. The mappings that can be modified are IO downstream, memory downstream, prefetchable memory downstream, IO upstream and memory upstream.

PCI_config_register_name()

NAME

PCI_config_register_name — return name of a configuration register

SYNOPSIS

const char *
PCI_config_register_name(pci_device_t *pci, uint32 offset);

DESCRIPTION

Returns the name of a configuration register, specified by a byte offset into the configuration header. Only standard configuration registers, i.e. as defined in the PCI specification, are handled. The header type of the PCI device affects the result.

RETURN VALUE

The name of the configuration register is returned if the offset corresponds to a valid configuration register. If not, NULL is returned.

PCI_config_register_size()

NAME

PCI_config_register_size — return size of a configuration register

SYNOPSIS

uint32
PCI_config_register_size(pci_device_t *pci, uint32 offset);

DESCRIPTION

Returns the size of a configuration register, specified by a byte offset into the configuration header. Only standard configuration registers, i.e. as defined in the PCI specification, are handled. The header type of the PCI device affects the result.

RETURN VALUE

The size (in bytes) of the configuration register is returned if the offset corresponds to a valid configuration register. If not, 0 is returned.

PCI_configuration_access()

NAME

PCI_configuration_access — access the configuration space

SYNOPSIS

exception_type_t
PCI_configuration_access(pci_device_t *pci, 
                         generic_transaction_t *mop);

DESCRIPTION

The PCI_configuration_access function performs an access to the configuration header registers. It handles overlapping accesses and both reads and writes. This function is typically only needed for PCI device that map the configuration space in the I/O and/or memory space mappings. The PCI device can then call this function. Accesses using the configuration space it handled by the generic PCI device itself (by calling this function).

RETURN VALUE

The returned value is always Sim_PE_No_Exception.

PCI_data_from_memory()

NAME

PCI_data_from_memory, PCI_data_to_memory — read/write raw data from memory space

SYNOPSIS

exception_type_t
PCI_data_from_memory(pci_device_t *pci, addr_space_t space,
                     uint8 *buffer, uint64 address, uint64 size);

exception_type_t
PCI_data_to_memory(pci_device_t *pci, addr_space_t space,
                   uint8 *buffer, uint64 address, uint64 size);

DESCRIPTION

PCI_data_from_memory reads data from a memory-space specified by space, and places it in a buffer pointed to by buffer. No endian conversion is performed. PCI_data_to_memory writes data to the memory space.

RETURN VALUE

The pseudo exception from the memory-space is returned.

PCI_default_configuration_read_access()

NAME

PCI_default_configuration_read_access — default function for configuration register reads

SYNOPSIS

uint32
PCI_default_configuration_read_access(conf_object_t *obj, 
                                      uint32 offset, uint32 size);

DESCRIPTION

A PCI device can override this default configuration read function with a function specified in the PCI_device_init call. The overriding function can then call this default function for configuration registers that it does not handle itself.

RETURN VALUE

The value of the configuration register is returned.

PCI_default_configuration_write_access()

NAME

PCI_default_configuration_write_access — default function for configuration register writes

SYNOPSIS

void
PCI_default_configuration_write_access(conf_object_t *obj, 
                                       uint32 offset, uint32 size, 
                                       uint32 value);

DESCRIPTION

A PCI device can override this default configuration wite function with a function specified in the PCI_device_init call. The overriding function can then call this default function for configuration registers that it does not handle itself. Side-effects for the Command, Status, Base Address, Secondary Status and Expansion ROM Base registers are handled.

PCI_default_device_reset()

NAME

PCI_default_device_reset — default PCI device reset handling

SYNOPSIS

void
PCI_default_device_reset(conf_object_t *obj);

DESCRIPTION

A PCI device can override this default reset function with a function specified in the PCI_device_init call. The overriding function can then call this default function to get the default behavior as well. All memory mappings are disabled, and the following registers are cleared: Command, Status, Cache Line Size, Latency Timer, BIST, Interrupt Line and all base address registers.

PCI_device_init()

NAME

PCI_device_init — initialize the generic PCI device

SYNOPSIS

void
PCI_device_init(log_object_t *log, int log_group,
                pci_device_t *pci,
                pci_device_t *(*unused)(conf_object_t *), /* call with NULL */
                void (*pci_bus_reset)(conf_object_t *obj),
                uint32 (*conf_read_func)(conf_object_t *obj, 
                                         uint32 offset, 
                                         uint32 size),
                void (*conf_write_func)(conf_object_t *obj, 
                                        uint32 offset, 
                                        uint32 size, 
                                        uint32 value),
                exception_type_t (*pci_operation)(
                        conf_object_t *obj,
                        generic_transaction_t *mem_op,
                        map_info_t map_info));

DESCRIPTION

Initializes the generic PCI device and optionally overrides some default functions. The arguments log and pci are pointers within the device structure, and log_group is the log group (as defined by SIM_log_register_groups) that the generic PCI device should use for configuration related logging. Use 0 if no log groups are defined. The unused function should be NULL. PCI bus resets are delivered to each PCI device by calling the installed pci_bus_reset function. The conf_read_func and conf_write_func functions are optional, they can be used to override the default behavior on accesses to the device's configuration registers. When called, the offset and size arguments corresponds to a complete configuration register if it is known. It is therefore recommended that device specific registers are added with PCI_add_config_register. I.e. partial and overlapping accesses are handled by the generic PCI device code before these callbacks are called. Accesses that do not correspond to known registers are handled byte by byte. The pci_irq_ack function is also optional, it is only used if the device responds to Interrupt Acknowledge cycles on the PCI bus. The last argument, pci_operation, is required. This function is called for all accesses to the memory and I/O mappings of the device. Memory and I/O space mappings can be created with PCI_handle_mapping32 and PCI_handle_mapping64.

The generic PCI device code will use the object_data field of the conf_object_t struct, it should not be modified by the code implementing a specific device.

PCI_get_bus_address()

NAME

PCI_get_bus_address — get the bus address of a device

SYNOPSIS

int
PCI_get_bus_address(pci_device_t *pci);

DESCRIPTION

Returns the PCI bus address for the device.

RETURN VALUE

The PCI bus address, in PCI Type 1 address format. I.e. bus << 16 | device << 11 | function << 8. On error, if the device isn't found on the bus, -1 is returned.

PCI_get_config_register_mask()

NAME

PCI_get_config_register_mask — get write mask of a configuration register

SYNOPSIS

uint32
PCI_get_config_register_mask(pci_device_t *pci, uint32 offset);

DESCRIPTION

Returns the write mask for a configuration register.

RETURN VALUE

Configuration register write mask.

PCI_handle_mapping32()

NAME

PCI_handle_mapping32, PCI_handle_mapping64 — handle base address register

SYNOPSIS

void
PCI_handle_mapping32(pci_device_t *pci, int reg,
                     addr_space_t space,
                     uint32 size, int function, int priority,
                     uint64 target_offset,
                     conf_object_t *target,
                     int alignment, int inverse_endian);

void
PCI_handle_mapping64(pci_device_t *pci, int reg,
                     uint64 size, int function, int priority,
                     uint64 target_offset,
                     conf_object_t *target,
                     int alignment, int inverse_endian);

DESCRIPTION

Tells the generic PCI device code to handle the memory mapping associated with the base address at configuration header offset reg. All read and write accesses to the base address will be handled, and the mappings will be enabled and disabled according to the enable bits in the PCI command register, and for expansion ROM also the enable bit in the base address register itself. The lowest bits in the base address register will be set to indicate space type and if the device is 32 or 64 bit addressable. 64 bit mappings are registered with PCI_handle_mapping64, and 32 bit ones with PCI_handle_mapping32.

The space argument specifies if the memory or I/O space is used. The size argument is the size of the memory mappings, and function a function number used to identify the mapping. The priority should be 0, unless the device can have mappings that overlap, in that case each mapping must have unique priority. By default the device itself is mapped at the base address, but in some cases another object should be the target. In that case, the target argument can be set, and target_offset to the byte offset into the target. It is also possible to set an alignment boundary size, and an inverse endian flags. These are documented with the map attribute in the memory-space class.

There are also functions in the PCI Device API that can be used to modify the mapping in run-time. This is not needed for standard PCI devices.

PCI_raise_interrupt()

NAME

PCI_raise_interrupt, PCI_lower_interrupt, PCI_raise_interrupt_pin, PCI_lower_interrupt_pin — raise and lower a PCI interrupt

SYNOPSIS

void
PCI_raise_interrupt(pci_device_t *pci);

void
PCI_lower_interrupt(pci_device_t *pci);

void
PCI_raise_interrupt_pin(pci_device_t *pci, int pin);

void
PCI_lower_interrupt_pin(pci_device_t *pci, int pin);

DESCRIPTION

PCI_raise_interrupt raises an interrupt on the pin defined by the PCI_INTERRUPT_PIN configuration register. If an interrupt is already asserted, the call has no effect. Similarly for PCI_lower_interrupt that lowers the interrupt level if it already is raised. The PCI_raise_interrupt_pin and PCI_lower_interrupt_pin functions take an extra argument that is the interrupt pin. These two functions should not be used by most PCI devices, but bridges may need them.

NOTE

A raise triggers an interrupt, and refers to the logical signal. It does not reflect the actual physical signal level on the PCI bus where interrupt lines are active low.

PCI_read_sized_config_register()

NAME

PCI_read_sized_config_register, PCI_read_config_register, PCI_write_config_register — read a configuration register

SYNOPSIS

uint32
PCI_read_sized_config_register(pci_device_t *pci, uint32 offset, 
                               uint32 size);

uint32
PCI_read_config_register(pci_device_t *pci, uint32 offset);

void
PCI_write_config_register(pci_device_t *pci, uint32 offset, 
                          uint32 value);

DESCRIPTION

Returns the value of a configuration register specified by a byte offset into the configuration header. The PCI_read_config_register function can only be used to read standard configuration registers, i.e. as defined in the PCI specification, and registers that are added with PCI_add_config_register. For other configuration registers the PCI_read_sized_config_register should be used, since the sizes of those registers are not known to the generic PCI device.

RETURN VALUE

The value, in host endian order, of the configuration register.

PCI_register_bridge_attributes()

NAME

PCI_register_bridge_attributes — register generic PCI bridge attributes

SYNOPSIS

void
PCI_register_bridge_attributes(conf_class_t *pci_class);

DESCRIPTION

Registers the generic PCI bridge device attributes, and performs some early initialization. This function should be called directly after PCI_register_device_attributes.

PCI_register_device_attributes()

NAME

PCI_register_device_attributes — register generic PCI device attributes

SYNOPSIS

void
PCI_register_device_attributes(
        conf_class_t *pci_class,
        int (*interrupt_ack)(conf_object_t *obj),
        void (*special_cycle)(conf_object_t *obj, uint32 value),
        void (*system_error)(conf_object_t *obj),
        void (*interrupt_raised)(conf_object_t *obj, int pin),
        void (*interrupt_lowered)(conf_object_t *obj, int pin));

DESCRIPTION

Registers the generic PCI device attributes, and performs some early initialization. The PCI_register_device_attributes function should be called as early as possible, typically from the module's init_local function. The first argument is the configuration class for the PCI device. The following arguments are optional functions with callbacks for events on the PCI bus. They should only be supplied by devices that respond to Interrupt Acknowledge Cycles, listens to Special Cycle data, listens to the system error line (SERR#), or receives peer-to-peer interrupts.

PCI_set_config_register_mask()

NAME

PCI_set_config_register_mask — set write mask of a configuration register

SYNOPSIS

void
PCI_set_config_register_mask(pci_device_t *pci, uint32 offset, uint32 mask);

DESCRIPTION

This function sets the write mask of a configuration register. Only bits set to 1 in mask are writable. Many PCI devices do not implement all bits in their configuration registers. By setting a write mask for such registers, the default access handling in the generic PCI device code can still be used.

PCI_set_map_base()

NAME

PCI_set_map_base, PCI_get_map_base, PCI_set_map_size, PCI_get_map_size, PCI_set_map_enable, PCI_get_map_enable, PCI_set_map_offset, PCI_get_map_offset, PCI_set_map_ignore_command, PCI_get_map_ignore_command, PCI_set_map_always_on, PCI_get_map_always_on — query and modify base address mapping

SYNOPSIS

void
PCI_set_map_base(pci_device_t *pci, int reg, uint64 base);

uint64
PCI_get_map_base(pci_device_t *pci, int reg);

void
PCI_set_map_size(pci_device_t *pci, int reg, uint64 size);

uint64
PCI_get_map_size(pci_device_t *pci, int reg);

void
PCI_set_map_enable(pci_device_t *pci, int reg, int enable);

int
PCI_get_map_enable(pci_device_t *pci, int reg);

void
PCI_set_map_offset(pci_device_t *pci, int reg, uint64 target_offset);

uint64
PCI_get_map_offset(pci_device_t *pci, int reg);

void
PCI_set_map_ignore_command(pci_device_t *pci, int reg, int map_ignore_command);

int
PCI_get_map_ignore_command(pci_device_t *pci, int reg);

void
PCI_set_map_always_on(pci_device_t *pci, int reg, int always_on);

int
PCI_get_map_always_on(pci_device_t *pci, int reg);

DESCRIPTION

The following functions can be used to modify base address mappings that have been registered with PCI_handle_mapping32 and PCI_handle_mapping64. Standard PCI devices typically doesn't have to modify the mappings, but some bridges and special devices have alternative registers to modify the memory mappings. PCI_set_map_base changes the base address, and also the contents of the base address register. PCI_set_map_size changes the size of the memory mapping. The size should be changed with care, since it may create an non-sized aligned mapping. The PCI_set_map_enable function can be used to enable and disable a mapping, this enable is in addition to the standard PCI enable/disable. Finally the PCI_set_map_offset changes the target offset of the mapping. The _get_ functions can be used to query the current state of a mapping.

PCI_set_may_stall()

NAME

PCI_set_may_stall, PCI_get_may_stall — Specifies if memory accesses are stallable

SYNOPSIS

void
PCI_set_may_stall(pci_device_t *pci, int may_stall);

int
PCI_get_may_stall(pci_device_t *pci);

DESCRIPTION

The PCI_set_may_stall function can be used to enable and disable stallable memory accesses. By default all accesses initiated by the device are not stallable. PCI_get_may_stall is used to query if stallable accesses are enabled or not.

PCI_system_error()

NAME

PCI_system_error — assert system error

SYNOPSIS

void
PCI_system_error(pci_device_t *pci);

DESCRIPTION

Triggers a system error on the PCI bus, i.e asserts the SERR# line. System Errors are used for asynchronous signalling of unrecoverable errors, and are usually handled by the host-to-PCI bridge.

PCI_value_from_memory()

NAME

PCI_value_from_memory, PCI_value_to_memory — read/write value from memory space

SYNOPSIS

uint64
PCI_value_from_memory(pci_device_t *pci, addr_space_t space,
                      exception_type_t *ex,
                      uint64 address, uint32 size);

exception_type_t
PCI_value_to_memory(pci_device_t *pci, addr_space_t space,
                      uint64 value,
                      uint64 address, uint32 size);

DESCRIPTION

PCI_value_from_memory reads data from a memory-space specified by space, and returns it in the endian byte-order of the host, i.e. as a value. PCI_value_to_memory writes value to the memory space.

RETURN VALUE

The pseudo exception from the memory-space is returned.

PCI_write_sized_config_register()

NAME

PCI_write_sized_config_register — write a configuration register

SYNOPSIS

void
PCI_write_sized_config_register(pci_device_t *pci, uint32 offset, 
                                uint32 value, uint32 size);

DESCRIPTION

Writes a value, in host endian order, to a configuration register specified by a byte offset into the configuration header. The PCI_write_config_register function can only be used to write standard configuration registers, i.e. as defined in the PCI specification. PCI_write_sized_config_register is typically used to write device specific configuration registers since the sizes of those registers are not known to the generic PCI device.

NOTE

No side effects are triggered by writing configuration registers with these functions. PCI_default_configuration_write_access can be used to get the side effects handled by the generic PCI device.

3.3.4   Micro-Architecture Interface

The Micro-Architecture Interface is described in the Simics MAI Guide.

Function List

SIM_instruction_begin()

NAME

SIM_instruction_begin, SIM_instruction_end, SIM_instruction_insert, SIM_instruction_child, SIM_instruction_parent, SIM_instruction_cpu, SIM_instruction_proceed, SIM_instruction_fetch, SIM_instruction_decode, SIM_instruction_execute, SIM_instruction_retire, SIM_instruction_commit, SIM_instruction_squash, SIM_instruction_rewind, SIM_instruction_handle_exception, SIM_instruction_handle_interrupt, SIM_instruction_nth_id, SIM_instruction_set_stop_phase, SIM_instruction_phase, SIM_instruction_speculative, SIM_instruction_force_correct, SIM_instruction_type, SIM_instruction_length, SIM_instruction_status, SIM_instruction_get_reg_info, SIM_instruction_read_input_reg, SIM_instruction_read_output_reg, SIM_instruction_write_input_reg, SIM_instruction_write_output_reg, SIM_instruction_is_sync, SIM_instruction_get_user_data, SIM_instruction_set_user_data, SIM_instruction_id_from_mem_op_id, SIM_instruction_stalling_mem_op, SIM_instruction_store_queue_mem_op, SIM_instruction_remaining_stall_time, SIM_instruction_get_field_value, SIM_instruction_opcode, SIM_release_stall, SIM_get_unique_memory_transaction_id — Micro-Architecture Interface functions

SYNOPSIS

instruction_id_t
SIM_instruction_begin(conf_object_t *obj);

instruction_error_t
SIM_instruction_end(instruction_id_t ii);

void
SIM_instruction_insert(instruction_id_t parent_ii,
                       instruction_id_t ii);

instruction_id_t
SIM_instruction_child(instruction_id_t ii, int n);

instruction_id_t
SIM_instruction_parent(instruction_id_t ii);

conf_object_t *
SIM_instruction_cpu(instruction_id_t ii)
/*   */
instruction_error_t
SIM_instruction_proceed(instruction_id_t ii);

instruction_error_t
SIM_instruction_proceed(instruction_id_t ii);

instruction_error_t
SIM_instruction_fetch(instruction_id_t ii);

instruction_error_t
SIM_instruction_decode(instruction_id_t ii);

instruction_error_t
SIM_instruction_execute(instruction_id_t ii);

instruction_error_t
SIM_instruction_retire(instruction_id_t ii);

instruction_error_t
SIM_instruction_commit(instruction_id_t ii);

instruction_error_t
SIM_instruction_squash(instruction_id_t ii);

instruction_error_t 
SIM_instruction_rewind(instruction_id_t ii, instruction_phase_t phase)
/*   */
instruction_error_t
SIM_instruction_handle_exception(instruction_id_t ii);

instruction_error_t
SIM_instruction_handle_exception(instruction_id_t ii);

instruction_error_t
SIM_instruction_handle_interrupt(conf_object_t *cpu,
                                 exception_type_t vector);

instruction_id_t
SIM_instruction_nth_id(int n);

void
SIM_instruction_set_stop_phase(conf_object_t *obj,
                               instruction_phase_t phase,
                               int on);

instruction_phase_t
SIM_instruction_phase(instruction_id_t ii);

int
SIM_instruction_speculative(instruction_id_t ii);

void
SIM_instruction_force_correct(instruction_id_t ii);

instr_type_t
SIM_instruction_type(instruction_id_t ii);

int
SIM_instruction_length(instruction_id_t ii);

instruction_status_t
SIM_instruction_status(instruction_id_t ii);

reg_info_t *
SIM_instruction_get_reg_info(instruction_id_t ii,
                             int n);

attr_value_t
SIM_instruction_read_input_reg(instruction_id_t ii,
                               register_id_t ri);

attr_value_t
SIM_instruction_read_output_reg(instruction_id_t ii,
                                register_id_t ri);

void
SIM_instruction_write_input_reg(instruction_id_t ii,
                                register_id_t ri,
                                attr_value_t value);

instruction_error_t
SIM_instruction_write_output_reg(instruction_id_t ii, 
                                 register_id_t ri,
                                 attr_value_t val);

int
SIM_instruction_is_sync(instruction_id_t ii);

lang_void *
SIM_instruction_get_user_data(instruction_id_t ii);

void
SIM_instruction_set_user_data(instruction_id_t ii,
                              lang_void *);

instruction_id_t
SIM_instruction_id_from_mem_op_id(conf_object_t *cpu, int id);

generic_transaction_t *
SIM_instruction_stalling_mem_op(conf_object_t *obj,
                                instruction_id_t entry);

generic_transaction_t *
SIM_instruction_store_queue_mem_op(instruction_id_t ii, int i);

cycles_t
SIM_instruction_remaining_stall_time(conf_object_t *obj,
                                     instruction_id_t ii);

integer_t
SIM_instruction_get_field_value(instruction_id_t ii,
                                const char *field_name);

attr_value_t
SIM_instruction_opcode(instruction_id_t ii);

void
SIM_release_stall(conf_object_t *obj, int id);

int
SIM_get_unique_memory_transaction_id(conf_object_t *obj);

DESCRIPTION

These functions constitute the Simics Micro-Architecture Interface, and are only available in the Micro-Architecture versions of Simics. If you have this version of Simics, you can find the documentation of these functions in the Simics Out of Order Processor Models document.

3.3.5   DBuffer Interface

The DBuffer library is part of the Simics API. It is used to efficiently transfer data blocks, such as network packets, inside the simulation. See the Simics Programming Guide for an introduction to programming with DBuffers.

Function List

dbuffer_append()

NAME

dbuffer_append, dbuffer_prepend, dbuffer_insert — Add data to a dbuffer

SYNOPSIS

uint8 *
dbuffer_append(dbuffer_t *dbuffer, size_t len);

uint8 *
dbuffer_prepend(dbuffer_t *dbuffer, size_t len);

uint8 *
dbuffer_insert(dbuffer_t *dbuffer, size_t offset, size_t len);

DESCRIPTION

These functions will extend the dbuffer with len bytes and return a pointer to the added bytes. The dbuffer_insert function adds the new data at offset in the buffer, while the dbuffer_prepend and dbuffer_append functions add it at the the beginning and end, respectively.

The returned pointer points to a memory area that is only guaranteed to contain valid data for the newly added bytes, and it is illegal to reference data before it or more than len-1 bytes ahead.

The returned pointer is also only valid until the next operation on the dbuffer function, except for calling dbuffer_len.

dbuffer_append_external_data()

NAME

dbuffer_append_external_data, dbuffer_prepend_external_data — Add static data

SYNOPSIS

uint8 *
dbuffer_append_external_data(dbuffer_t *dbuffer, void *data,
                             size_t len, int adopt);

uint8 *
dbuffer_prepend_external_data(dbuffer_t *dbuffer, void *data,
                              size_t len, int adopt);

DESCRIPTION

These functions work similar to dbuffer_append and dbuffer_prepend, but with the difference that the data isn't copied. Instead, the buffer will reference the data pointed to directly.

If the adopt flag is true, the control of the data block is transferred to the dbuffer. It is assumed to be a block allocated with MM_MALLOC, and will be freed with MM_FREE when the dbuffer is released.

If the adopt flag is false, the dbuffer will not free the memory. Instead it is up to the caller to free the memory, but it must not do so before the dbuffer is freed. Actually, this reference could be copied to other dbuffers, so great care has to be taken. This should only be used for buffers that will only be read, since it hard to know if a write operation will actually write to the buffer or to a copy.

SEE ALSO

dbuffer_append, dbuffer_prepend

dbuffer_append_value()

NAME

dbuffer_append_value, dbuffer_prepend_value — Add data with uniform content

SYNOPSIS

uint8 *
dbuffer_append_value(dbuffer_t *dbuffer, int value, size_t len);

uint8 *
dbuffer_prepend_value(dbuffer_t *dbuffer, int value, size_t len);

DESCRIPTION

This adds data to a dbuffer and sets all the added bytes to value. It has the same effect as using dbuffer_append or dbuffer_append and calling memset to set the contents.

The return value is a pointer to the data just added.

SEE ALSO

dbuffer_append, dbuffer_prepend

dbuffer_clone()

NAME

dbuffer_clone — Make a full copy of another buffer

SYNOPSIS

dbuffer_t *
dbuffer_clone(dbuffer_t *dbuffer);

DESCRIPTION

This function returns a new dbuffer that contains the same data as the buffer given in the dbuffer parameter. This doesn't involve copying any memory, since they can share the same storage initially. However, they are still completely independent, and operations on one buffer has no effect on the other.

The returned dbuffer should be released with dbuffer_free when it is no longer needed.

SEE ALSO

new_dbuffer, dbuffer_free

dbuffer_copy_append()

NAME

dbuffer_copy_append, dbuffer_copy_prepend — Copy data from a dbuffer

SYNOPSIS

void
dbuffer_copy_append(dbuffer_t *dst, dbuffer_t *src,
                    size_t offset, size_t len);

void
dbuffer_copy_prepend(dbuffer_t *dst, dbuffer_t *src,
                     size_t offset, size_t len);

DESCRIPTION

These functions copies len bytes from the dbuffer src, at offset offset, and adds it to the beginning or end of the dbuffer dst.

This can often be done without actually copying any memory, so it is usually very efficient.

SEE ALSO

dbuffer_append, dbuffer_prepend

dbuffer_free()

NAME

dbuffer_free — Release a dbuffer

SYNOPSIS

void
dbuffer_free(dbuffer_t *dbuffer);

DESCRIPTION

Release a dbuffer that will not be used anymore. This will also free any data in the buffer that isn't also used by other buffers. After calling this function, the dbuffer must not be used anymore.

SEE ALSO

new_dbuffer

dbuffer_len()

NAME

dbuffer_len — Get the size of a dbuffer

SYNOPSIS

size_t
dbuffer_len(dbuffer_t *dbuffer);

DESCRIPTION

This function returns the amount of data stored in a dbuffer. This is the number of bytes that will be returned by dbuffer_read_all.

dbuffer_read()

NAME

dbuffer_read, dbuffer_read_all, dbuffer_read_some — Extract data for reading

SYNOPSIS

uint8 *
dbuffer_read(dbuffer_t *dbuffer, size_t offset, size_t len);

uint8 *
dbuffer_read_all(dbuffer_t *dbuffer);

uint8 *
dbuffer_read_some(dbuffer_t *dbuffer, size_t offset, size_t len,
                  size_t *actual_len);

DESCRIPTION

The offset and len parameters specify a region of the buffer to read from. The returned pointer is guaranteed to point to a contiguous block of memory of size len. It is illegal to write to the block return by these functions, since they may be shared by other dbuffers. Use the dbuffer_update functions if you need to both read and write to the dbuffer.

The returned pointer is only valid until the next operation on the dbuffer, except for calling dbuffer_len.

The dbuffer_read_some function takes an actual_len parameter, and may return a smaller buffer than requested. The actual number of valid bytes in the returned buffer is stored in *actual_len. It will return a smaller buffer if it would have had to copy memory to return a pointer to the whole region. This means that you can use this function repeatedly to extract all the requested data in the most efficient way. If NULL is passed for actual_len, it will return the full region.

The dbuffer_read_all function assumes 0 for offset, and buffer_len(dbuffer) for len.

SEE ALSO

dbuffer_update, dbuffer_replace