simics 0.2.6

Intel® Simics® Simulator bindings in high level, idiomatic Rust
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114

// Copyright (C) 2024 Intel Corporation
// SPDX-License-Identifier: Apache-2.0

//! Direct Python interface

#![allow(clippy::not_unsafe_ptr_arg_deref)]

use crate::{
    simics_exception,
    sys::{
        SIM_call_python_function, SIM_run_python, SIM_source_python, VT_call_python_module_function,
    },
    AttrValue, Error, Result,
};
use raw_cstr::raw_cstr;
use std::{any::type_name, path::Path};

#[simics_exception]
/// Source a python file of SIMICS python code
pub fn source_python<P>(file: P) -> Result<()>
where
    P: AsRef<Path>,
{
    unsafe {
        SIM_source_python(raw_cstr(
            file.as_ref().to_str().ok_or_else(|| Error::ToString)?,
        )?)
    };
    Ok(())
}

#[simics_exception]
/// Run (by eval-ing) python code in the simulator context. The result is returned as an
/// `AttrValue`, which is typed according to the python command run.
pub fn run_python<S>(line: S) -> Result<AttrValue>
where
    S: AsRef<str>,
{
    Ok(unsafe { SIM_run_python(raw_cstr(line)?) }.into())
}

#[simics_exception]
/// Call a python function with a set of arguments. The arguments must be
/// convertible to `AttrValue`.
///
/// # Examples
///
/// We can run python code like so:
///
/// ```rust,ignore
/// let res = call_python_function("print", ["a", "b", "c"])?;
/// ```
pub fn call_python_function<S, I, T>(function: S, args: I) -> Result<AttrValue>
where
    S: AsRef<str>,
    I: IntoIterator<Item = T>,
    T: TryInto<AttrValue>,
{
    let args: Vec<AttrValue> = args
        .into_iter()
        .map(|a| {
            a.try_into().map_err(|_| Error::ToAttrValueConversionError {
                ty: type_name::<T>().to_string(),
            })
        })
        .collect::<Result<Vec<_>>>()?;
    let args: AttrValue = args.try_into()?;
    let mut args = args.into();
    Ok(unsafe { SIM_call_python_function(raw_cstr(function)?, &mut args as *mut _) }.into())
}

#[simics_exception]
/// Call a python function with a set of arguments. The arguments must be
/// convertible to `AttrValue`.
///
/// # Examples
///
/// We can run python code like so. If you need to pass a heterogeneous list of
/// arguments, you need to convert them to `AttrValue`s before passing them to this
/// function because we cannot create a heterogeneous `Vec`. For homogeneous lists of
/// arguments, they can be passed directly as in `call_python_function`.
///
/// ```rust,ignore
/// let level: AttrValue = 1i32.into();
/// let sim: AttrValue = get_object("sim")?.into()?;
/// let group: AttrValue = 0i32.into();
/// let message: AttrValue = "Hello".into();
/// let res = call_python_module_function("simics", "SIM_log_info" [level, sim, group, message])?;
/// ```
pub fn call_python_module_function<S, I, T>(module: S, function: S, args: I) -> Result<AttrValue>
where
    S: AsRef<str>,
    I: IntoIterator<Item = T>,
    T: TryInto<AttrValue>,
{
    let args: Vec<AttrValue> = args
        .into_iter()
        .map(|a| {
            a.try_into().map_err(|_| Error::ToAttrValueConversionError {
                ty: type_name::<T>().to_string(),
            })
        })
        .collect::<Result<Vec<_>>>()?;
    let args: AttrValue = args.try_into()?;
    let mut args = args.into();
    Ok(unsafe {
        VT_call_python_module_function(
            raw_cstr(module.as_ref())?,
            raw_cstr(function.as_ref())?,
            &mut args as *mut _,
        )
    }
    .into())
}