Releasing Simulator-Bindings

List Simics-Base package versions in simics-api-sys/build.rs by running:

ispm packages --list-available --json \
    | awk '/\{/,EOF' \
    | jq -r '.availablePackages[] | select(.pkgNumber == 1000) | .version' \
    | tac \
    | grep -v pre \
    | sed -ne '/6.0.163/,$ p'

Update command at bottom of simics-api-sys/build.rs with any missing versions from the list
Install all supported Simics-Base package versions (update command with latest versions, here 6.0.207 and 7.0.20)

kinit; ispm packages -i 1000-6.0.{163..207} 1000-7.{0..20}.0

Run the gen-api-items.rs script using the command in simics-api-sys/build.rs like:

./scripts/gen-simics-api-items.rs \
    -s ~/simics/simics-6.0.163 \
    -s ~/simics/simics-6.0.164 \
    -s ~/simics/simics-6.0.165 \
    -s ~/simics/simics-6.0.166 \
    -s ~/simics/simics-6.0.167 \
    -s ~/simics/simics-6.0.168 \
    -s ~/simics/simics-6.0.169 \
    -s ~/simics/simics-6.0.170 \
    -s ~/simics/simics-6.0.171 \
    -s ~/simics/simics-6.0.172 \
    -s ~/simics/simics-6.0.173 \
    -s ~/simics/simics-6.0.174 \
    -s ~/simics/simics-6.0.175 \
    -s ~/simics/simics-6.0.176 \
    -s ~/simics/simics-6.0.177 \
    -s ~/simics/simics-6.0.178 \
    -s ~/simics/simics-6.0.179 \
    -s ~/simics/simics-6.0.180 \
    -s ~/simics/simics-6.0.181 \
    -s ~/simics/simics-6.0.182 \
    -s ~/simics/simics-6.0.183 \
    -s ~/simics/simics-6.0.184 \
    -s ~/simics/simics-6.0.185 \
    -s ~/simics/simics-6.0.186 \
    -s ~/simics/simics-6.0.187 \
    -s ~/simics/simics-6.0.188 \
    -s ~/simics/simics-6.0.189 \
    -s ~/simics/simics-6.0.190 \
    -s ~/simics/simics-6.0.191 \
    -s ~/simics/simics-6.0.192 \
    -s ~/simics/simics-6.0.193 \
    -s ~/simics/simics-6.0.194 \
    -s ~/simics/simics-6.0.195 \
    -s ~/simics/simics-6.0.196 \
    -s ~/simics/simics-6.0.197 \
    -s ~/simics/simics-6.0.198 \
    -s ~/simics/simics-6.0.199 \
    -s ~/simics/simics-6.0.200 \
    -s ~/simics/simics-6.0.201 \
    -s ~/simics/simics-6.0.202 \
    -s ~/simics/simics-6.0.203 \
    -s ~/simics/simics-6.0.204 \
    -s ~/simics/simics-6.0.205 \
    -s ~/simics/simics-6.0.206 \
    -s ~/simics/simics-6.0.207 \
    -s ~/simics/simics-7.0.0 \
    -s ~/simics/simics-7.1.0 \
    -s ~/simics/simics-7.2.0 \
    -s ~/simics/simics-7.3.0 \
    -s ~/simics/simics-7.4.0 \
    -s ~/simics/simics-7.5.0 \
    -s ~/simics/simics-7.6.0 \
    -s ~/simics/simics-7.7.0 \
    -s ~/simics/simics-7.8.0 \
    -s ~/simics/simics-7.9.0 \
    -s ~/simics/simics-7.10.0 \
    -s ~/simics/simics-7.11.0 \
    -s ~/simics/simics-7.12.0 \
    -s ~/simics/simics-7.13.0 \
    -s ~/simics/simics-7.14.0 \
    -s ~/simics/simics-7.15.0 \
    -s ~/simics/simics-7.16.0 \
    -s ~/simics/simics-7.17.0 \
    -s ~/simics/simics-7.18.0 \
    -s ~/simics/simics-7.19.0 \
    -s ~/simics/simics-7.20.0 \
    -o simics-api-sys/simics_api_items.rs

Build high-level bindings for any new features that merit inclusion. Not all features have high-level bindings, but most do. These high level bindings should utilize the versioned cfg() directives.
Run check script: ./check.sh
- This will report issues with formatting (C and Python formatting can be ignored for releases, markdown and Rust issues should be fixed)
- This will perform most checks done in CI including dependencies
- Any dependencies that are outdated or flag vulnerabilities in audits should be updated
- Any code which has breaking changes (very rare) should be fixed

Environment Variables

There are several environment variables which can be used for various purposes.

Build Flags

SIMICS_BASE: Specify the directory containing the Simics base package to build against e.g. SIMICS_BASE=/home/me/simics/simics-6.0.195
SIMICS_BINDINGS_NOCLEAN: Specify that the bindings should not have unknown items stripped. This results in messier and larger bindings files, but can be used if targeting a version of Simics which the bindings have not yet been explicitly updated to target. Also speeds up compilation, so this can be used in .cargo/config.toml to speed up rust-analyzer runs.

[env]
SIMICS_BINDINGS_NOCLEAN = "1"

Metadata Overrides

SIMICS_PACKAGE_PACKAGE_NAME: Override the package-name field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_PACKAGE_NUMBER: Override the package-number field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_NAME: Override the name field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_DESCRIPTION: Override the description field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_HOST: Override the host field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_VERSION: Override the version field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_BUILD_ID: Override the build-id field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_BUILD_ID_NAMESPACE: Override the build-id-namespace field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_CONFIDENTIALITY: Override the confidentiality field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_TYPE: Override the type field of the package.metadata.simics Cargo.toml table
SIMICS_PACKAGE_DOC_TITLE: Override the doc-title field of the package.metadata.simics Cargo.toml table

Testing Flags

SIMICS_TEST_LOCAL_PACKAGES_ONLY: Do not download new package versions for test environments and only copy locally installed packages instead. Tests which explicitly depend on non-installed packages will fail.
SIMICS_TEST_CLEANUP_EACH: Clean up after each test instead of leaving the package installation directory. Use if the package versions used in the test change, but there is no need to use if only the code under test has changed (and not the test environment configuration).

Build Directives

The Simics bindings have some version-dependence on the underlying C API. The emit_build_directives function from the simics-build-utils crate emits configuration directives used in the build process to conditionally enable features that aren't compatible with all supported SIMICS versions, based on the SIMICS version of the low level bindings. This is not needed for all consumers of the API, but is useful for consumers which need to remain compatible with a wide range of SIMICS base versions.

If your consumer of the Simics API needs to conditionally enable/disable its own functionality depending on the version compiled against, you can call emit_build_directives in your build.rs script and use the directives like:

#![allow(unused)]
fn main() {
#[cfg(any(simics_version = "6.0.191", simics_version = "7"))]
}

Changelog

The following is an abbreviated changelog for reference purposes. It is determined by running ./scripts/simics-changes.sh and examining the diffs.

6.0.163->6.0.164:

Add:
- telnet_connection_v2_interface_t
- vnc_server_v2_interface_t

6.0.166->6.0.167:

Add probe_notification_context_interface_t

6.0.167->6.0.168:

Add:
- bool VT_attr_values_equal(attr_value_t a1, attr_value_t a2)
- interrupt_subscriber_interface_t
- interrupt_source_t

6.0.169->6.0.170:

Add:
- riscv_imsic_interface_t
- riscv_imsic_file_it_t

6.0.170->6.0.171:

Add:
- Sim_Global_Notify_Message variant to global_notifier_type_t

6.0.172->6.0.173:

Add:
- riscv_signal_sgeip_interface_t
- Sim_Atom_Id_pcie_destination_segment variant to atom_id_t
  - void VT_save_snapshot(const char *name);
  - bool VT_restore_snapshot(int index);
  - bool VT_delete_snapshot(int index);
  - attr_value_t VT_snapshot_size_used();
  - attr_value_t VT_list_snapshots();
  - void VT_snapshots_ignore_class(const char *class_name);
  - vhdx_params_t
  - vhdx_file_t *vhdx_creat(const char *fname, uint64 size, craff_error_t *ce, vhdx_params_t *params);
Change:
- void VT_load_target_preset_yml(const char *target, const char *ns, const char *preset, const char *preset_yml); (was void VT_load_target_preset_yml(const char *target, const char *ns, const char *preset_yml);

6.0.173->6.0.174:

Change:
- bool VT_save_snapshot(const char *name); (was void VT_save_snapshot(const char *name);)

6.0.174->6.0.175:

Add:
- Sim_Global_Notify_Snapshot_Will_Load and Sim_Global_Notify_Snapshot_Did_Load variants to global_notifier_type_t
- void *VT_save_and_release_python_lock();
- void VT_obtain_and_restore_python_lock(void *saved);
Change:
- attr_value_t SIM_load_target(const char *target, const char *ns, attr_value_t presets, attr_value_t cmdline_args); (was void SIM_load_target(const char *target, const char *ns, attr_value_t presets, attr_value_t cmdline_args);)

6.0.176->6.0.177:

Add:
- pcie_adapter_compat_interface_t
- bool VT_is_loading_snapshot();
Remove:
- probe_notification_context_interface_t

6.0.177->6.0.178:

Add:
- void VT_snapshots_skip_class_resotre(conf_class_t *cls);
- void VT_snapshots_skip_attr_restore(conf_class_t *cls, const char *attr_name);
- attr_value_t VT_dump_snapshot(const char *name);

6.0.179->6.0.180:

Add:
- snapshot_error_t
- attr_value_t VT_get_snapshot_info(const char *name);
Change:
- bool VT_is_restoring_snapshot(); (was bool VT_is_loading_snapshot();)
- snapshot_error_t VT_take_snapshot(const char *name); (was bool VT_save_snapshot(const char *name);)
- snapshot_error_t VT_restore_snapshot(const char *name); (was bool VT_restore_snapshot(int index);)
- snapshot_error_t VT_delete_snapshot(const char *name); (was bool VT_delete_snapshot(int index);)

6.0.180->6.0.181:

Change:
- void VT_load_target_preset_yml(const char *target, const char *ns, attr_value_t presets, const char *preset_yml); (was void VT_load_target_preset_yml(const char *target, const char *ns, cosnt char *preset, const char *preset_yml);)

6.0.183->6.0.184:

Add
- pcie_hotplug_events_interface_t
- pcie_hotplug_pd_t
- pcie_hotplug_mrl_t
- probe_array_interface_t
Remove:
- probe_cache_interface_t

6.0.184->6.0.185:

Add:
- pcie_link_training_interface_t
- pcie_link_speed_t
- pcie_link_width_t
- pcie_link_negotiation_t

6.0.188->6.0.189:

Add:
- Sim_Log_Warning variant to log_type_t
- void VT_log_warning(conf_object_t *dev, uint64 grp, const char *str, ...);

6.0.190->6.0.191:

Add:
- attr_value_t VT_list_registered_atoms(void)

6.0.191->6.0.192:

Add:
- riscv_instruction_action_interface_t
- riscv_custom_csr_interface_t

6.0.192->6.0.193:

Add:
- transaction_trace_atom_access_t
- cxl_map_interface_t

6.0.193->6.0.194:

Add:
- xtensa_wwdt_config_interface_t
- xtensa_wwdt_faultinfo_interface_t

6.0.194->6.0.195:

Add:
- SIM_PYOBJECT *CORE_object_iterator(conf_object_t *obj);
- SIM_PYOBJECT *CORE_shallow_object_iterator(conf_object_t *obj, bool expand_arrays);
- SIM_PYOBJECT *CORE_object_iterator_for_class(conf_object_t *obj);
- SIM_PYOBJECT *CORE_object_iterator_for_interface(attr_value_t ifaces);
Remove:
- SIM_object_iterator
- SIM_shallow_object_iterator

6.0.198->6.0.199:

Add:
- xtensa_internal_memories_interface_t
- xtensa_mpu_lookup_interface_t
- int VT_log_always_count(void);
- cxl_non_device_decoder_handling_interface_t
- cxl_mem_downstream_port_managing_interface_t
- transaction_subscribe_interface_t

6.0.204->6.0.205:

Add:
- void VT_set_prompt_customizer(prompt_customizer_t NOTNULL cb);

6.X.X->7.0.0:

Remove:
- bool VT_is_reversing();
- bool SIM_is_loading_micro_checkpoint(cont_object_t *obj);
- Sim_Attr_Session and Sim_Attr_Doc variants from attr_type_t
- i2c_device_state_t
- i2c_device_flag_t
- i2c_bus_interface_t
- i2c_device_interface_t
- i2c_status_t
- i2c_link_interface_t
- i2c_slave_interface_t
- i2c_master_interface_t
- i2c_bridge_interface_t
- device_interrupt_t
- device_interrupt_clear_t
- interrupt_query_register_t
- interrupt_query_enabled_t
- map_func_t
- operation_func_t
- mil-std-1553 device
- rapidio device
- VT_register_py_interface
- VT_get_py_interface
- breakpoint_query_interface_t
- pool_protect_interface_t
- gui_mode_t
- cpu_variant_t
- workspace, gui_mode, cpu_mode, license_file, expire_time, alt_settings_dir, allow_license_gui, eclipse_params from init_prefs_t
- hap_flags_t
- int VT_write_rev(const void *src, int length)
- int pr_rev(const char *format, ...);
- bool VT_revexec_available();
- bool VT_revexec_active();
- bool VT_in_the_past();
- revexec_pos_t
- VT_revexec_steps
- VT_revexec_cycles
- VT_get_rewind_overhead
- VT_reverse
- VT_reverse_cpu
- VT_skipto_step
- VT_skipto_cycle
- VT_skipto_bookmark
- VT_rewind
- micro_checkpoint_flags_t
- VT_save_micro_checkpoint
- VT_restore_micro_checkpoint
- VT_delete_micro_checkpoint
- VT_in_time_order
- time_ordered_handler_t
- VT_c_in_time_order
- VT_revexec_ignore_class
- VT_revexec_barrier
- slave_time_t
- slave_time_as_sec
- slave_time_from_sec
- slave_time_from_ps
- slave_time_as_ps_hi
- slave_time_as_ps_lo
- slave_time_from_ps_int128
- slave_time_eq
- slave_time_lt
- slave_time_gt
- slave_time_le
- slave_time_ge
- telnet_connection_interface_t
- vnc_server_interface_t
- link_endpoint_interface_t
- probe_array_interface_t
- recorder_interface_t
- slave_agent_interface_t
- slaver_agent_interface_t
- mm_malloc_low
Add:
- VT_get_py_popaque_conf_object
- VT_python_wrap_conf_class
- VT_get_conf_class
- VT_get_py_opaque_transaction
- VT_python_wrap_transaction
- VT_get_py_opaque_generic_transaction
- VT_python_wrap_generic_transaction
- VT_get_py_opaque_x86_transaction_upcast
- VT_python_wrap_x86_transaction_upcast
- VT_get_py_opaque_ppc_transaction_upcast
- VT_python_wrap_ppc_transaction_upcast
- VT_get_py_opaque_pci_transaction_upcast
- VT_python_wrap_pci_transaction_upcast
- VT_get_py_opaque_mips_transaction_upcast
- VT_python_wrap_mips_transaction_upcast
- VT_get_py_opaque_arm_transaction_upcast
- VT_python_wrap_arm_transaction_upcast
- VT_get_exception_type
- void pr_warn(const char *str, ...);
- Add void SIM_printf_error(const char *str, ...);
- Add void SIM_printf_warning(const char *str, ...);
Change:
- void pr_err_vararg(const char *prefix, bool is_error, const char *format, va_list ap); (was void pr_err_vararg(const char *str, va_list ap);)
Rename:
- VT_is_restoring_snapshot to SIM_is_restoring_snapshot
- VT_take_snapshot to SIM_take_snapshot
- VT_restore_snapshot to SIM_restore_snapshot
- VT_delete_snapshot to SIM_delete_snapshot
- VT_list_snapshots to SIM_list_snapshots
- VT_get_snapshot_info to SIM_get_snapshot_info 7.0.0->7.1.0:
Add:
- pcie_hotplug_pd_t
- pcie_hotplug_mrl_t
- pcie_hotplug_events_interface_t
- pcie_link_training_interface_t
- pcie_link_speed_t
- flags to save_flags_t
- probe_array_interface_t
- void SIM_write_persistent_state(const char *file, conf_object_t *root, save_flags_t flags);
- VT_set_frontend_server
- VT_send_startup_complete_message
- VT_remove_control
- frontend_server_interface_t
Remove:
- attribute_monitor_interface_t
- probe_cache_interface_t

7.2.0->7.3.0:

Add:
- void SIM_printf_error_vararg(const char *format, va_list ap);
- void SIM_printf_warning_vararg(const char *format, va_list ap);
Remove:
- pr_err_vararg

7.7.0->7.8.0:

Add:
- riscv_instruction_action_interface_t
- riscv_custom_csr_interface_t
- attr_value_t VT_list_registered_atoms
- xtensa_wwdt_config_interface_t
- xtensa_wwdt_faultinfo_interface_t

7.9.0->7.10.0:

Remove:
- SIM_object_iterator
- SIM_shallow_object_iterator

7.13.0->7.14.0:

Add:
- xtensa_internal_memories_interface_t
- xtensa_mpu_lookup_interface_t
- int VT_log_always_count(void);
- cxl_non_device_decoder_handling_interface_t
- cxl_mem_downstream_port_managing_interface_t
- transaction_subscribe_interface_t

7.16.0->7.17.0:

Rename:
- VT_simics_to_filename -> simics_to_filename

7.18.0->7.19.0:

Add:
- void VT_set_prompt_customizer(prompt_customizer_t NOTNULL cb);

simulator-bindings