VIRTUTECH CONFIDENTIAL    Previous - Up - Next

3.3   Simics API Functions

3.3.1   Complete List

MM_FREEfree vtmem object
MM_MALIGNallocate aligned memory
MM_MALLOCallocate memory object
MM_REALLOCreallocate memory
MM_STRDUPduplicate a string
PCIE_send_messagesend a message to root complex
PCI_add_config_registeradd device specific configuration register
PCI_bridge_default_access_not_takendefault handling of unclaimed accesses
PCI_bridge_default_interrupt_lowereddefault handling of secondary interrupts
PCI_bridge_default_interrupt_raiseddefault handling of secondary interrupts
PCI_bridge_default_system_errordefault system error handling for bridges
PCI_bridge_initInitialize generic PCI bridge device
PCI_bridge_map_setupSet optional memory mapping attributes
PCI_config_register_namereturn name of a configuration register
PCI_config_register_sizereturn size of a configuration register
PCI_configuration_accessaccess the configuration space
PCI_data_from_memoryread/write raw data from memory space
PCI_data_to_memoryread/write raw data from memory space
PCI_default_configuration_read_accessdefault function for configuration register reads
PCI_default_configuration_write_accessdefault function for configuration register writes
PCI_default_device_resetdefault PCI device reset handling
PCI_device_initinitialize the generic PCI device
PCI_get_bus_addressget the bus address of a device
PCI_get_config_register_maskget write mask of a configuration register
PCI_get_map_always_onquery and modify base address mapping
PCI_get_map_basequery and modify base address mapping
PCI_get_map_enablequery and modify base address mapping
PCI_get_map_ignore_commandquery and modify base address mapping
PCI_get_map_offsetquery and modify base address mapping
PCI_get_map_sizequery and modify base address mapping
PCI_get_may_stallSpecifies if memory accesses are stallable
PCI_handle_mapping32handle base address register
PCI_handle_mapping64handle base address register
PCI_lower_interruptraise and lower a PCI interrupt
PCI_lower_interrupt_pinraise and lower a PCI interrupt
PCI_raise_interruptraise and lower a PCI interrupt
PCI_raise_interrupt_pinraise and lower a PCI interrupt
PCI_read_config_registerread a configuration register
PCI_read_sized_config_registerread a configuration register
PCI_register_bridge_attributesregister generic PCI bridge attributes
PCI_register_device_attributesregister generic PCI device attributes
PCI_set_config_register_maskset write mask of a configuration register
PCI_set_map_always_onquery and modify base address mapping
PCI_set_map_basequery and modify base address mapping
PCI_set_map_enablequery and modify base address mapping
PCI_set_map_ignore_commandquery and modify base address mapping
PCI_set_map_offsetquery and modify base address mapping
PCI_set_map_sizequery and modify base address mapping
PCI_set_may_stallSpecifies if memory accesses are stallable
PCI_system_errorassert system error
PCI_value_from_memoryread/write value from memory space
PCI_value_to_memoryread/write value from memory space
PCI_write_config_registerread a configuration register
PCI_write_sized_config_registerwrite a configuration register
SIM_STC_flush_cacheflush or remove entries in the STCs of a cpu
SIM_add_configurationset configuration from Python
SIM_add_directoryadd directory to search path
SIM_add_mode_counterobsolete API function
SIM_add_output_handlerregister output handler
SIM_all_classesobsolete API function
SIM_all_objectsobsolete API function
SIM_alloc_attr_dictcreate empty attribute dictionary
SIM_alloc_attr_listcreate empty attribute list
SIM_alloc_conf_objectallocate object
SIM_alpha_mem_trans_from_genericconvert generic transaction to CPU specific
SIM_arm_mem_trans_from_genericconvert generic transaction to CPU specific
SIM_ascanfparse list attribute values
SIM_attribute_errorspecify reason for attribute error
SIM_break_cycleinsert breakpoint in time queue
SIM_break_messagestop the simulation
SIM_break_simulationstop the simulation
SIM_break_stepset a step breakpoint
SIM_breakpointset breakpoint
SIM_breakpoint_actionobsolete API function
SIM_breakpoint_removedelete breakpoint range
SIM_c_frontend_exceptionobsolete API function
SIM_c_get_mem_op_value_bufget value for a memory operation
SIM_c_hap_occurredtrigger a hap occurrence
SIM_c_hap_occurred_alwaystrigger a hap occurrence
SIM_c_hap_occurred_always_varargtrigger a hap occurrence
SIM_c_hap_occurred_varargtrigger a hap occurrence
SIM_c_set_mem_op_value_bufset value for a memory operation
SIM_cancel_realtime_eventcancel callback in host time
SIM_change_attribute_attributechange requiredness of attribute
SIM_check_exceptionobsolete API function
SIM_class_has_attributecheck if class implements attribute
SIM_clear_atomic_reservation_bitobsolete API function
SIM_clear_directoriesclear the search path
SIM_clear_exceptionclear pending exception
SIM_command_clear_problemsignal error in command
SIM_command_has_problemsignal error in command
SIM_command_problem_statussignal error in command
SIM_continuecontinue the simulation
SIM_copyrightget version info about Simics
SIM_cpu_by_midobsolete API function
SIM_cpu_enabledobsolete API function
SIM_cpu_issue_cyclesobsolete API function
SIM_cpu_privilege_levelobsolete API function
SIM_create_objectcreate and initialise object
SIM_current_processorget current processor
SIM_cycle_countquery time queue for current time
SIM_delete_breakpointdelete breakpoint
SIM_delete_objectdelete object
SIM_device_logobsolete API function
SIM_disable_processorenable or disable a processor
SIM_disassembledisassemble instruction
SIM_disassemble_physicalobsolete API function
SIM_dump_cachesobsolete API function
SIM_enable_processorenable or disable a processor
SIM_ensure_partial_attr_orderensure attribute order
SIM_exception_has_occurredobsolete API function
SIM_flushtext output routines
SIM_flush_D_STC_logicalflush or remove entries in the STCs of a cpu
SIM_flush_D_STC_physicalflush or remove entries in the STCs of a cpu
SIM_flush_I_STC_logicalflush or remove entries in the STCs of a cpu
SIM_flush_I_STC_physicalflush or remove entries in the STCs of a cpu
SIM_flush_all_cachesclear Simics's internal caches
SIM_for_all_hap_typesobsolete API function
SIM_for_all_memory_pagesapply callback function to all memory pages
SIM_for_all_modulesobsolete API function
SIM_for_all_modules_failedobsolete API function
SIM_for_all_processorsobsolete API function
SIM_free_attributefree attribute
SIM_frontend_exceptionraise an exception
SIM_get_No_Exceptionobsolete API function
SIM_get_all_classesget list of all classes
SIM_get_all_exceptionsprocessor exception conversion utilities
SIM_get_all_failed_modulesreturn a list of all modules that failed to load
SIM_get_all_hap_typesget list of all hap types
SIM_get_all_modulesreturn a list of all modules
SIM_get_all_objectsget list of all objects
SIM_get_all_processorsget list of all processors
SIM_get_all_registersget all register numbers
SIM_get_attributeget attribute
SIM_get_attribute_attributesget attribute flags
SIM_get_attribute_idxget attribute
SIM_get_base_pointerobsolete API function
SIM_get_batch_modereturn setting of the batch-mode
SIM_get_classget class
SIM_get_class_attributeget attribute
SIM_get_class_attribute_idxget attribute
SIM_get_class_interfaceget interface
SIM_get_class_nameget class name
SIM_get_class_port_interfaceget interface
SIM_get_configuration_file_prefixget filename prefix
SIM_get_control_register_nameobsolete API function
SIM_get_control_register_numberobsolete API function
SIM_get_current_proc_noobsolete API function
SIM_get_directoriesget the current search path
SIM_get_exception_nameprocessor exception conversion utilities
SIM_get_exception_numberprocessor exception conversion utilities
SIM_get_file_sizeobsolete API function
SIM_get_history_matchobsolete API function
SIM_get_interfaceget interface
SIM_get_mem_op_typeget type of transaction
SIM_get_mem_op_type_nameget name of memory operation type
SIM_get_mem_op_value_beget value for a memory operation
SIM_get_mem_op_value_bufget value for a memory operation
SIM_get_mem_op_value_cpuget value for a memory operation
SIM_get_mem_op_value_leget value for a memory operation
SIM_get_mmu_dataobsolete API function
SIM_get_mode_counterobsolete API function
SIM_get_objectget object
SIM_get_pending_exceptionget current pending exception
SIM_get_port_interfaceget interface
SIM_get_proc_noobsolete API function
SIM_get_processorget processor pointer from number
SIM_get_processor_numberget the number of a processor
SIM_get_program_counterread/write program counter
SIM_get_quietreturn setting of the quiet flag
SIM_get_register_nameconvert between register name and register number
SIM_get_register_numberconvert between register name and register number
SIM_get_simics_homeobsolete API function
SIM_get_stack_pointerobsolete API function
SIM_get_trap_timeobsolete API function
SIM_get_unique_memory_transaction_idMicro-Architecture Interface functions
SIM_get_unique_memory_transaction_idget unique memory transaction ID
SIM_get_verboseget the verbose flag
SIM_hap_add_callbackinstall callback on a hap
SIM_hap_add_callback_indexinstall callback on a hap
SIM_hap_add_callback_objinstall callback on a hap
SIM_hap_add_callback_obj_indexinstall callback on a hap
SIM_hap_add_callback_obj_rangeinstall callback on a hap
SIM_hap_add_callback_rangeinstall callback on a hap
SIM_hap_add_typeregister a new hap type
SIM_hap_callback_existsget callback status
SIM_hap_delete_callbackdelete installed hap callback
SIM_hap_delete_callback_iddelete installed hap callback
SIM_hap_delete_callback_objdelete installed hap callback
SIM_hap_delete_callback_obj_iddelete installed hap callback
SIM_hap_get_nameget hap name by number
SIM_hap_get_numberget hap number by name
SIM_hap_install_callbackobsolete API function
SIM_hap_install_callback_idxobsolete API function
SIM_hap_install_callback_rangeobsolete API function
SIM_hap_is_activecheck if hap has callbacks
SIM_hap_new_typeobsolete API function
SIM_hap_occurredtrigger hap occurrence
SIM_hap_occurred_alwaystrigger hap occurrence
SIM_hap_register_callbackobsolete API function
SIM_hap_register_callback_idxobsolete API function
SIM_hap_register_callback_rangeobsolete API function
SIM_hap_remove_callbackobsolete API function
SIM_hap_remove_typeremove a hap type
SIM_hap_unregister_callbackobsolete API function
SIM_ia64_mem_trans_from_genericconvert generic transaction to CPU specific
SIM_inc_cur_mode_counterobsolete API function
SIM_inc_mode_counterobsolete API function
SIM_initial_configuration_okget configuration status
SIM_install_default_ASI_handlerobsolete API function
SIM_install_user_ASI_handlerobsolete API function
SIM_instruction_beginMicro-Architecture Interface functions
SIM_instruction_childMicro-Architecture Interface functions
SIM_instruction_commitMicro-Architecture Interface functions
SIM_instruction_cpuMicro-Architecture Interface functions
SIM_instruction_decodeMicro-Architecture Interface functions
SIM_instruction_endMicro-Architecture Interface functions
SIM_instruction_executeMicro-Architecture Interface functions
SIM_instruction_fetchMicro-Architecture Interface functions
SIM_instruction_force_correctMicro-Architecture Interface functions
SIM_instruction_get_field_valueMicro-Architecture Interface functions
SIM_instruction_get_reg_infoMicro-Architecture Interface functions
SIM_instruction_get_user_dataMicro-Architecture Interface functions
SIM_instruction_handle_exceptionMicro-Architecture Interface functions
SIM_instruction_handle_interruptMicro-Architecture Interface functions
SIM_instruction_id_from_mem_op_idMicro-Architecture Interface functions
SIM_instruction_infoobsolete API function
SIM_instruction_insertMicro-Architecture Interface functions
SIM_instruction_is_syncMicro-Architecture Interface functions
SIM_instruction_lengthMicro-Architecture Interface functions
SIM_instruction_nth_idMicro-Architecture Interface functions
SIM_instruction_opcodeMicro-Architecture Interface functions
SIM_instruction_parentMicro-Architecture Interface functions
SIM_instruction_phaseMicro-Architecture Interface functions
SIM_instruction_proceedMicro-Architecture Interface functions
SIM_instruction_read_input_regMicro-Architecture Interface functions
SIM_instruction_read_output_regMicro-Architecture Interface functions
SIM_instruction_remaining_stall_timeMicro-Architecture Interface functions
SIM_instruction_retireMicro-Architecture Interface functions
SIM_instruction_rewindMicro-Architecture Interface functions
SIM_instruction_set_stop_phaseMicro-Architecture Interface functions
SIM_instruction_set_user_dataMicro-Architecture Interface functions
SIM_instruction_speculativeMicro-Architecture Interface functions
SIM_instruction_squashMicro-Architecture Interface functions
SIM_instruction_stalling_mem_opMicro-Architecture Interface functions
SIM_instruction_statusMicro-Architecture Interface functions
SIM_instruction_store_queue_mem_opMicro-Architecture Interface functions
SIM_instruction_typeMicro-Architecture Interface functions
SIM_instruction_write_input_regMicro-Architecture Interface functions
SIM_instruction_write_output_regMicro-Architecture Interface functions
SIM_is_interactiverunning interactive command predicate
SIM_iter_addrIterate over address profile counters
SIM_iter_freeIterate over address profile counters
SIM_iter_nextIterate over address profile counters
SIM_last_errorget error message from last exception
SIM_licenseget version info about Simics
SIM_load_binaryread an executable file into memory
SIM_load_fileread a file into memory
SIM_load_moduleload/unload modules
SIM_log_constructorinitiate log class
SIM_log_erroroutput log message
SIM_log_infooutput log message
SIM_log_messageprint and log message
SIM_log_register_groupsregister names of log groups
SIM_log_spec_violationoutput log message
SIM_log_target_erroroutput log message
SIM_log_undefinedoutput log message
SIM_log_unimplementedoutput log message
SIM_logical_to_physicaltranslate logical to physical
SIM_lookup_filefind a file using simics-path
SIM_make_attr_booleanmake boolean attribute
SIM_make_attr_datacreate raw data attribute
SIM_make_attr_floatingmake floating point attribute
SIM_make_attr_integermake integer attribute
SIM_make_attr_invalidmake invalid attribute
SIM_make_attr_listmake list attribute
SIM_make_attr_list_varargmake list attribute
SIM_make_attr_nilmake empty attribute
SIM_make_attr_objectmake object attribute
SIM_make_attr_stringmake string attribute
SIM_mem_op_is_controltransaction control predicates
SIM_mem_op_is_datatransaction data/instruction predicates
SIM_mem_op_is_from_cacheCache initiated transaction
SIM_mem_op_is_from_cpuCPU initiated transaction
SIM_mem_op_is_from_cpu_archCPU initiated transaction
SIM_mem_op_is_from_deviceDevice initiated transaction
SIM_mem_op_is_instructiontransaction data/instruction predicates
SIM_mem_op_is_prefetchtransaction control predicates
SIM_mem_op_is_readtransaction read/write predicates
SIM_mem_op_is_writetransaction read/write predicates
SIM_mips_mem_trans_from_genericconvert generic transaction to CPU specific
SIM_module_list_refreshrefresh list of loadable modules
SIM_native_pathconvert path to its native form
SIM_new_objectcreate object
SIM_next_queueget next object that owns a queue
SIM_no_windowsobsolete API function
SIM_notify_on_descriptorregister notification on host I/O events
SIM_notify_on_objectregister notification on host I/O events
SIM_notify_on_socketregister notification on host I/O events
SIM_num_control_registersobsolete API function
SIM_number_processorsnumber of processors
SIM_object_by_idobsolete API function
SIM_object_constructorbase class constructor
SIM_object_is_processortest if object is a processor
SIM_pci_mem_trans_from_genericconvert generic transaction to CPU specific
SIM_post_commandpost callback to be run when simulation is stopped
SIM_postponing_continueask if continue will be postponed
SIM_ppc_mem_trans_from_genericconvert generic transaction to CPU specific
SIM_printftext output routines
SIM_printf_varargtext output routines
SIM_proc_no_2_ptrobsolete API function
SIM_processor_breakobsolete API function
SIM_processor_enabledcheck if processor is enabled
SIM_processor_privilege_levelreturn the current privilege level for a processor
SIM_putchartext output routines
SIM_putstext output routines
SIM_quitquit Simics
SIM_raise_general_exceptionobsolete API function
SIM_read_byteread/write byte from a memory space
SIM_read_configurationread configuration
SIM_read_control_registerobsolete API function
SIM_read_fp_registerobsolete API function
SIM_read_fp_register_dobsolete API function
SIM_read_fp_register_iobsolete API function
SIM_read_fp_register_sobsolete API function
SIM_read_fp_register_xobsolete API function
SIM_read_global_registerobsolete API function
SIM_read_phys_memoryread data from a physical address
SIM_read_phys_memory_tagsaccess auxiliary bits in physical memory
SIM_read_registerget register value
SIM_read_window_registerobsolete API function
SIM_readmeget version info about Simics
SIM_realtime_eventschedule callback in host time
SIM_register_arch_decoderinstall/uninstall instruction decoders
SIM_register_attributeregister attribute
SIM_register_classregister class
SIM_register_class_aliasregister class alias
SIM_register_class_attributeregister attribute
SIM_register_copyrightregister copyright information
SIM_register_decoderdeprecated install/uninstall user decoders
SIM_register_interfaceregister interface
SIM_register_port_interfaceregister interface
SIM_register_typed_attributeregister attribute
SIM_register_typed_class_attributeregister attribute
SIM_release_stallMicro-Architecture Interface functions
SIM_release_stallrelease stalling transaction
SIM_remove_output_handlerunregister output handler
SIM_reset_processorreset the processor
SIM_run_command_fileread CLI commands from file
SIM_set_attributeset attribute
SIM_set_attribute_idxset attribute
SIM_set_class_attributeset attribute
SIM_set_class_attribute_idxset attribute
SIM_set_configurationset configuration from data
SIM_set_mem_op_typeset type of transaction
SIM_set_mem_op_value_beset value for a memory operation
SIM_set_mem_op_value_bufset value for a memory operation
SIM_set_mem_op_value_cpuset value for a memory operation
SIM_set_mem_op_value_leset value for a memory operation
SIM_set_mode_counterobsolete API function
SIM_set_program_counterread/write program counter
SIM_set_promptchange prompt in Simics
SIM_set_quietenable/disable quiet mode
SIM_set_verboseset the verbose flag
SIM_simics_is_runningcheck if Simics is running
SIM_snapshot_dateget version info about Simics
SIM_source_pythonexecute Python source file
SIM_source_python_in_moduleexecute Python source file
SIM_sparc_ASI_infoobsolete API function
SIM_stacked_postinsert an event that runs as soon as possible
SIM_stallstall execution a specified number of cycles
SIM_stall_countget number of cycles a processor has been stalled
SIM_stall_cyclestall execution a specified number of cycles
SIM_stalled_untilquery how many cycles that remains of stall
SIM_step_cleanremove events from the step queue
SIM_step_countquery step queue count
SIM_step_next_occurrenceget number of steps until a step queue event occurs
SIM_step_postadd an event in step queue
SIM_thread_safe_callbackcall function synchronized with main thread
SIM_timequery time queue for current time
SIM_time_cleanremove all matching events from time queue
SIM_time_next_occurrenceget cycles to matching event
SIM_time_postadd event to time queue
SIM_time_post_cycleadd event to time queue
SIM_unload_moduleload/unload modules
SIM_unregister_arch_decoderinstall/uninstall instruction decoders
SIM_unregister_decoderdeprecated install/uninstall user decoders
SIM_v9_mem_trans_from_genericconvert generic transaction to CPU specific
SIM_versionget version info about Simics
SIM_version_subget version info about Simics
SIM_void_to_processor_tobsolete API function
SIM_writetext output routines
SIM_write_byteread/write byte from a memory space
SIM_write_configuration_to_filewrite configuration
SIM_write_control_registerobsolete API function
SIM_write_fp_registerobsolete API function
SIM_write_fp_register_dobsolete API function
SIM_write_fp_register_iobsolete API function
SIM_write_fp_register_sobsolete API function
SIM_write_fp_register_xobsolete API function
SIM_write_global_registerobsolete API function
SIM_write_phys_memorywrite data to a physical address
SIM_write_phys_memory_tagsaccess auxiliary bits in physical memory
SIM_write_registerset register value
SIM_write_window_registerobsolete API function
SIM_x86_mem_trans_from_genericconvert generic transaction to CPU specific
cli.argdefine a command argument
cli.eval_cli_lineevaluate a CLI command line
cli.get_available_object_namereturn a non-allocated object name
cli.new_commanddefine a new CLI command
cli.number_strreturn a ready-to-print representation of a number
cli.object_expanderStandard expander for an object argument
cli.quiet_run_commandRun a CLI command and return output
cli.run_commandRun a CLI command
dbuffer_appendAdd data to a dbuffer
dbuffer_append_external_dataAdd static data
dbuffer_append_valueAdd data with uniform content
dbuffer_cloneMake a full copy of another buffer
dbuffer_copy_appendCopy data from a dbuffer
dbuffer_copy_prependCopy data from a dbuffer
dbuffer_freeRelease a dbuffer
dbuffer_insertAdd data to a dbuffer
dbuffer_lenGet the size of a dbuffer
dbuffer_prependAdd data to a dbuffer
dbuffer_prepend_external_dataAdd static data
dbuffer_prepend_valueAdd data with uniform content
dbuffer_readExtract data for reading
dbuffer_read_allExtract data for reading
dbuffer_read_someExtract data for reading
dbuffer_removeRemove data from a dbuffer
dbuffer_remove_headRemove data from a dbuffer
dbuffer_remove_tailRemove data from a dbuffer
dbuffer_replaceReplace data
dbuffer_replace_allReplace data
dbuffer_replace_someReplace data
dbuffer_splitSplit a dbuffer
dbuffer_updateExtract data for updating
dbuffer_update_allExtract data for updating
dbuffer_update_someExtract data for updating
new_dbufferCreate a new dbuffer
sim_commands.new_info_commanddefine a new info command
sim_commands.new_status_commanddefine a new status command

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 charargument typeelement must be
iinteger_t *Sim_Val_Integer
bint *Sim_Val_Boolean
fdouble *Sim_Val_Floating
sconst char **Sim_Val_String
Sconst char **Sim_Val_String or Sim_Val_Nil
oconf_object_t **Sim_Val_Object
Oconf_object_t **Sim_Val_Object or Sim_Val_Nil
lattr_value_t **Sim_Val_List
dattr_value_t **Sim_Val_Data
aattr_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:

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:

ian int
Ian integer_t (64 bit integer)
ean exception_type_t
oa script specific object; i.e., void * in C and any Python object in Python
sa string
ma memory transaction (generic_transaction_t * in C)
ca configuration object (conf_object_t * in C)
va 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.

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.

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 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 *NOTNULL 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:

modecondition
Sim_NM_ReadSocket is readable, closed, or incoming connection accepted
Sim_NM_WriteSocket 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
dbuffer_remove()

NAME
dbuffer_remove, dbuffer_remove_head, dbuffer_remove_tail — Remove data from a dbuffer

SYNOPSIS
void
dbuffer_remove(dbuffer_t *dbuffer, size_t offset, size_t remove_len);
void
dbuffer_remove_head(dbuffer_t *dbuffer, size_t remove_len);
void
dbuffer_remove_tail(dbuffer_t *dbuffer, size_t remove_len);

DESCRIPTION
These functions will remove remove_len bytes from dbuffer. The dbuffer will remove data starting at offset, while the other functions will remove data from the beginning or end of the buffer..

This usually doesn't involve moving any memory contents, and should be very efficient even if the buffer is large.

dbuffer_replace()

NAME
dbuffer_replace, dbuffer_replace_all, dbuffer_replace_some — Replace data

SYNOPSIS
uint8 *
dbuffer_replace(dbuffer_t *dbuffer, size_t offset, size_t len);
uint8 *
dbuffer_replace_all(dbuffer_t *dbuffer);
uint8 *
dbuffer_replace_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 write to. The returned pointer is guaranteed to point to a contiguous block of memory of size len, but is not guaranteed to contain the existing data in the buffer. Use these functions when completely replacing a region of the buffer with new data.

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

The dbuffer_replace_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 write all the requested data in the most efficient way. If NULL is passed for actual_len, it will return the full region.

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

SEE ALSO
dbuffer_read, dbuffer_update
dbuffer_split()

NAME
dbuffer_split — Split a dbuffer

SYNOPSIS
dbuffer_t *
dbuffer_split(dbuffer_t *dbuffer, size_t offset);

DESCRIPTION
This function returns a new dbuffer that contains the offset first bytes from dbuffer, and removes those bytes from dbuffer The effect is that the dbuffer is split in two halves, leaving the second half in the original dbuffer and returning the first half as a new dbuffer.

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

SEE ALSO
new_dbuffer, dbuffer_free
dbuffer_update()

NAME
dbuffer_update, dbuffer_update_all, dbuffer_update_some — Extract data for updating

SYNOPSIS
uint8 *
dbuffer_update(dbuffer_t *dbuffer, size_t offset, size_t len);
uint8 *
dbuffer_update_all(dbuffer_t *dbuffer);
uint8 *
dbuffer_update_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 access. The returned pointer is guaranteed to point to a contiguous block of memory of size len. The block can be used for reading and writing data to the dbuffer.

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

The dbuffer_update_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 access all the requested data in the most efficient way. If NULL is passed for actual_len, it will return the full region.

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

SEE ALSO
dbuffer_read, dbuffer_replace
new_dbuffer()

NAME
new_dbuffer — Create a new dbuffer

SYNOPSIS
dbuffer_t *
new_dbuffer(void);

DESCRIPTION
This function returns an empty dbuffer. Use it when you need a new dbuffer, and call dbuffer_free when it isn't needed anymore.

SEE ALSO
dbuffer_free, dbuffer_clone

3.3.6   VTMEM

3.3.6.1   VTmem Overview
The "VTmem" (Virtutech Memory Management) module provides a generic mechanism for creating and managing dynamic objects in C, as a replacement for the standard malloc(). This support is designed to support various forms of debugging, performance tuning, leak detection, etc. The facilities as a whole are called "VTmem"; most functions have the prefix mm_, and most macros have the prefix MM_.
3.3.6.2   Creating and Deleting Objects
To create an VTmem object, you use macros such as MM_MALLOC(), which replace calls to malloc(). For example, to allocate 13 objects of type device_t, use

    device_t *d = MM_MALLOC(13, device_t);

The specified type is used for keeping track of the total amount of memory used for each kind of object, and for knowing the size of the allocation (and being able to return a correctly casted pointer). This means that it must be possible to get a pointer to the type by appending an asterisk to the type name; so struct foo * is acceptable, but int (*)(void) is not. Use a typedef in these cases.

There are also macros for specifying the size in bytes, and variants that return memory initialised with zero bytes. It is also possible to specify a desired address alignment.

Since the allocation sites are tracked by file and line number, it is a good idea to avoid having more than one allocation call in a single source line.

3.3.6.3   Exported Interface
This is the entire interface to the VTmem facility.
VTMEM Macros
MM_FREE()

NAME
MM_FREE — free vtmem object

SYNOPSIS
MM_FREE(p);

DESCRIPTION
MM_FREE frees a vtmem object. It is legal to pass a null pointer, in which case it does nothing.

MM_MALIGN()

NAME
MM_MALIGN, MM_ZALIGN — allocate aligned memory

SYNOPSIS
MM_MALIGN(align, nelems, type);
MM_ZALIGN(align, nelems, type);

DESCRIPTION
MM_MALIGN allocates memory aligned to the nearest align-byte boundary. The align parameter must be an even power of 2.

MM_ZALIGN does the same thing but in addition zeroes out the allocated memory.

Allocated aligned memory imposes a slightly higher space overhead than ordinary memory as handed out by MM_MALLOC. The overhead is of the order of align bytes per allocation.

RETURN VALUE
Pointer to the allocated object.
MM_MALLOC()

NAME
MM_MALLOC, MM_MALLOC_SZ, MM_ZALLOC, MM_ZALLOC_SZ — allocate memory object

SYNOPSIS
MM_MALLOC(nelems, type);
MM_MALLOC_SZ(size, type);
MM_ZALLOC(nelems, type);
MM_ZALLOC_SZ(size, type);

DESCRIPTION
MM_MALLOC allocates nelems objects of type.

MM_MALLOC_SZ specifies the allocation in bytes, which can be occasionally useful.

MM_ZALLOC and MM_ZALLOC_SZ do the same thing as their Z-less counterparts but in addition zero out the allocated memory.

If nelems or size are zero, a null pointer is returned.

RETURN VALUE
Pointer to the allocated object.
MM_REALLOC()

NAME
MM_REALLOC, MM_REALLOC_SZ, MM_ZREALLOC, MM_ZREALLOC_SZ — reallocate memory

SYNOPSIS
MM_REALLOC(p, nelems, type);
MM_REALLOC_SZ(p, size, type);
MM_ZREALLOC(p, nelems, type);
MM_ZREALLOC_SZ(p, size, type);

DESCRIPTION
MM_REALLOC changes the size of an allocated memory block to nelems elements.

MM_REALLOC_SZ specifies the new size in bytes.

MM_ZREALLOC and MM_ZREALLOC_SZ do the same thing as their Z-less counterparts, but in addition zero out the extended part of the allocation.

If the passed pointer is NULL, then these macros are equivalent to an allocation of the desired amount. If nelems or size are zero, a null pointer is returned and the original allocation is freed.

RETURN VALUE
Pointer to the reallocated object.
MM_STRDUP()

NAME
MM_STRDUP — duplicate a string

SYNOPSIS
MM_STRDUP(str);

DESCRIPTION
Corresponds to the traditional strdup() function, but uses the instrumentation of the Simics memory allocator.

RETURN VALUE
Pointer to the newly allocated string.

3.3.7   Python-specific Functions

This list describes the Python-specific functions that are available for writing commands, scripts and Python modules in Simics.

Function List
cli.arg()

NAME
arg — define a command argument

NAMESPACE
cli

SYNOPSIS
arg(handler, name = "", spec = "1", default = None, data = None,
        doc = "", expander = None, pars = [], is_a = None)

DESCRIPTION
Define a CLI command argument when using new_command(). A complete explanation of new_command() and arg() is available in the Simics Programming Guide.

cli.eval_cli_line()

NAME
eval_cli_line — evaluate a CLI command line

NAMESPACE
cli

SYNOPSIS
eval_cli_line(text, user_typed = 0)

DESCRIPTION
Evaluate a CLI command line as if it has been entered at the prompt. This is useful to re-use existing command code when writing Python scripts. Command errors are printed on the console, and not reported back to Python. Note that the ! and @ modifiers are not supported when using eval_cli_line().

cli.get_available_object_name()

NAME
get_available_object_name — return a non-allocated object name

NAMESPACE
cli

SYNOPSIS
get_available_object_name(prefix)

DESCRIPTION
Return an object name suitable for creating a new object (i.e., that has not been used yet) based on the prefix passed as argument.

cli.new_command()

NAME
new_command — define a new CLI command

NAMESPACE
cli

SYNOPSIS
new_command(name, fun, args = [], doc = "", type = "misc commands",
                pri = 0, infix = 0, left = 1,
                short = "", group_short = "", alias = [], doc_with = "",
                check_args = 2,
                doc_items = [], see_also = [], namespace = "",
                method = "", namespace_copy = (), internal = 0,
                filename = "", linenumber = "", module = "",
                object = None, repeat = None, deprecated = None)

DESCRIPTION
Define a new CLI command. A complete explanation of new_command() is available in the Simics Programming Guide.

cli.number_str()

NAME
number_str — return a ready-to-print representation of a number

NAMESPACE
cli

SYNOPSIS
number_str(val, radix = -1)

DESCRIPTION
Return a ready-to-print representation of the number val in a given base (radix) or the current base by default—following the current settings for number representation.

RETURN VALUE
A string representing the number.
cli.object_expander()

NAME
object_expander — Standard expander for an object argument

NAMESPACE
cli

SYNOPSIS
object_expander(kind)

DESCRIPTION
For command writing: standard expander that can be use to provide argument completion on all objects of a given class or matching a given interface (kind). For example, to expand a string with the list of processor available in the machine, you would write:
 arg(str_t, "cpu", expander =  object_expander("processor")) 
To expand a string to all gcache objects:
 arg(str_t, "cache", expander = object_expander("gcache")) 

cli.quiet_run_command()

NAME
quiet_run_command — Run a CLI command and return output

NAMESPACE
cli

SYNOPSIS
quiet_run_command(text)

DESCRIPTION
Runs a CLI command, or a CLI expression, as if it has been entered at the prompt. Errors are reported using CliError exception. The quiet_run_command() is similar to run_command() but returns a tuple with the command return value as first entry, and the text output as the second. Note that the ! and @ modifiers are not supported when using quiet_run_command().

cli.run_command()

NAME
run_command — Run a CLI command

NAMESPACE
cli

SYNOPSIS
run_command(text)

DESCRIPTION
Runs a CLI command, or a CLI expression, as if it has been entered at the prompt. Errors are reported using CliError exception, and any return value from the command is returned by this function to Python. Note that the ! and @ modifiers are not supported when using run_command().

sim_commands.new_info_command()

NAME
new_info_command — define a new info command

NAMESPACE
sim_commands

SYNOPSIS
new_info_command(cls, get_info, ctype = None)

DESCRIPTION
Define a new info command for a given device. cls is the class for which the info command should be registered. get_info is a function returning the information to be printed. get_info() should return a data structure of the following kind: [(SectionName1, [(DataName1.1, DataValue1.1), (DataName1.2, DataValue1.2), ...]), (SectionName2, [(DataName2.1, DataValue2.1), (DataName2.2, DataValue2.2), ...]), ...] Each section will be printed separately. Each piece of data will be printed on one line. If no sections are necessary, just provide None as the only section's name, followed by the list of data.

sim_commands.new_status_command()

NAME
new_status_command — define a new status command

NAMESPACE
sim_commands

SYNOPSIS
new_status_command(cls, get_status, ctype = None)

DESCRIPTION
Define a new status command for a given device. cls is the class for which the status command should be registered. get_status is a function returning the information to be printed. get_status() should return a data structure of the same kind as in new_info_command().

SEE ALSO
sim_commands.new_info_command

VIRTUTECH CONFIDENTIAL    Previous - Up - Next