celox 0.4.1

Celox HDL Simulator
Documentation 
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
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

use std::sync::Arc;

use crate::HashMap;

use veryl_metadata::ComponentManifest;

/// A value crossing the boundary of an in-process component callback.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum InjectedValue {
    Bits {
        words: Vec<u64>,
        mask_xz: Vec<u64>,
        width: u32,
    },
    String(String),
    Unit,
}

/// The lifecycle operation requested from an injected component.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum InjectedHook {
    Create,
    Init,
    Reset,
    Clock,
    Finish,
    Method {
        name: String,
        args: Vec<InjectedValue>,
    },
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct InjectedNamedValue {
    pub name: String,
    pub value: InjectedValue,
}

#[derive(Clone, Debug, PartialEq, Eq)]
pub struct InjectedPort {
    pub name: String,
    pub direction: String,
    pub role: Option<String>,
    pub width: u32,
}

/// One synchronous call into an injected component implementation.
#[derive(Clone, Debug)]
pub struct InjectedCall {
    pub instance: String,
    pub hook: InjectedHook,
    pub inputs: Vec<InjectedNamedValue>,
    pub params: Vec<InjectedNamedValue>,
    pub ports: Vec<InjectedPort>,
    pub cycle: u64,
    pub time: u64,
    pub seed: u64,
    pub fired_clock: Option<String>,
    pub four_state: bool,
}

/// Effects returned by an injected callback. Outputs are staged using the
/// same component/NBA path as compiled native and Wasm components.
#[derive(Clone, Debug, Default)]
pub struct InjectedResult {
    pub outputs: Vec<InjectedNamedValue>,
    pub return_value: Option<InjectedValue>,
    pub failures: Vec<String>,
    pub logs: Vec<String>,
    pub finish: bool,
}

/// Synchronous component implementation supplied by an embedding runtime.
pub trait InjectedComponentHandler: Send + Sync + 'static {
    fn call(&self, call: InjectedCall) -> Result<InjectedResult, String>;
}

#[derive(Clone)]
pub(crate) struct InjectedComponentDefinition {
    pub manifest: ComponentManifest,
    pub kind: u32,
    pub handler: Arc<dyn InjectedComponentHandler>,
}

/// Component definitions injected by an embedding API for one simulator.
#[derive(Clone, Default)]
pub struct InjectedComponents {
    pub(crate) definitions: HashMap<String, InjectedComponentDefinition>,
}

impl InjectedComponents {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn insert(
        &mut self,
        name: impl Into<String>,
        manifest_json: &str,
        handler: Arc<dyn InjectedComponentHandler>,
    ) -> Result<(), String> {
        let name = name.into();
        if name.is_empty() || name.contains("::") {
            return Err("injected component names must be non-empty identifiers".into());
        }
        let manifest = ComponentManifest::parse(manifest_json)
            .ok_or_else(|| format!("manifest of injected component `{name}` cannot be parsed"))?;
        let kind = match manifest.kind.as_deref() {
            Some("clocked") => veryl_component_sys::VRL_KIND_CLOCKED,
            Some("method_only") => veryl_component_sys::VRL_KIND_METHOD_ONLY,
            Some(kind) => return Err(format!("unsupported component kind `{kind}`")),
            None => {
                return Err(format!(
                    "manifest of injected component `{name}` has no kind"
                ));
            }
        };
        if self.definitions.contains_key(&name) {
            return Err(format!(
                "injected component `{name}` is defined more than once"
            ));
        }
        self.definitions.insert(
            name,
            InjectedComponentDefinition {
                manifest,
                kind,
                handler,
            },
        );
        Ok(())
    }

    pub(crate) fn get(&self, name: &str) -> Option<&InjectedComponentDefinition> {
        self.definitions.get(name)
    }

    pub(crate) fn manifests(&self) -> Vec<(String, ComponentManifest)> {
        self.definitions
            .iter()
            .map(|(name, definition)| (name.clone(), definition.manifest.clone()))
            .collect()
    }
}