Skip to main content

prjunnamed_netlist/
metadata.rs

1//! Metadata storage.
2use std::{
3    borrow::Cow,
4    fmt::{Debug, Display},
5    hash::Hash,
6};
7use prjcombine_entity::{EntityId, EntitySet};
8
9use crate::{Design, ParamValue};
10
11/// Position within a source file.
12#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash)]
13pub struct SourcePosition {
14    /// Zero-based line number.
15    pub line: u32,
16    /// Zero-based column number.
17    pub column: u32,
18}
19
20/// Metadata item.
21///
22/// Metadata items represent information about cells that does not affect computational semantics. Some metadata items
23/// only carry information about the source code, and other metadata items affect how the netlist is transformed.
24#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
25pub enum MetaItem {
26    /// Absence of a metadata item.
27    /// The purpose of this variant is to make metadata indices take less memory.
28    #[default]
29    None,
30    /// Multiple metadata items.
31    /// The purpose of this variant is to make collections of metadata indices take less memory.
32    /// A metadata set cannot contain less than two metadata items.
33    Set(Vec<MetaItemId>),
34    /// Source location.
35    Source {
36        /// Filename.  Must not be empty.
37        file: MetaStringId,
38        /// Start of the range (inclusive).
39        start: SourcePosition,
40        /// End of the range (exclusive).
41        end: SourcePosition,
42    },
43    /// Scope identified by a name.
44    /// A top-level named scope could be a module declaration. A named scope with a parent could be a block within
45    /// a module.
46    NamedScope {
47        /// Name.  Must not be empty.
48        name: MetaStringId,
49        /// Source location.  Must reference [`MetaItem::None`] or [`MetaItem::Source`].
50        source: MetaItemId,
51        /// Parent scope.  Must reference [`MetaItem::None`], [`MetaItem::NamedScope`], or [`MetaItem::IndexedScope`].
52        parent: MetaItemId,
53    },
54    /// Scope identified by an index.
55    /// A top-level named scope could be a module declaration. A named scope with a parent could be a named instance
56    /// of a module within another module.
57    IndexedScope {
58        index: i32,
59        /// Source location.  Must reference [`MetaItem::None`] or [`MetaItem::Source`].
60        source: MetaItemId,
61        /// Parent scope.  Must reference [`MetaItem::None`], [`MetaItem::NamedScope`], or [`MetaItem::IndexedScope`].
62        parent: MetaItemId,
63    },
64    /// Identifier within source code.
65    Ident {
66        /// Name.  Must not be empty.
67        name: MetaStringId,
68        /// Containing scope.
69        /// Must reference a [`MetaItem::NamedScope`], or [`MetaItem::IndexedScope`].
70        scope: MetaItemId,
71    },
72    Attr {
73        /// Name.  Must not be empty.
74        name: MetaStringId,
75        /// Value.
76        value: ParamValue,
77    },
78    // to be added:
79    // - MemoryKind
80    // - EnumEncoding
81}
82
83#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
84pub struct MetaStringId(u32);
85
86#[derive(Clone, Copy, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
87pub struct MetaItemId(u32);
88
89#[derive(Clone, Debug)]
90pub struct MetadataStore {
91    strings: EntitySet<MetaStringId, String>,
92    items: EntitySet<MetaItemId, MetaItem>,
93}
94
95pub struct MetaItemIterator<'a> {
96    design: &'a Design,
97    item: MetaItemId,
98    offset: usize,
99}
100
101impl MetaItem {
102    pub fn validate(&self, design: &Design) {
103        match self {
104            MetaItem::None => (),
105            MetaItem::Set(items) => {
106                assert!(items.len() > 1, "MetaItem::Set must contain more than one element");
107                for &item in items {
108                    assert!(
109                        !matches!(*design.ref_metadata_item(item), MetaItem::None | MetaItem::Set(..)),
110                        "MetaItem::Set item must not be MetaItem::None or another MetaItem::Set"
111                    )
112                }
113            }
114            MetaItem::Source { file, start, end } => {
115                assert!(!file.is_empty(), "MetaItem::Source must have a file");
116                assert!(
117                    end.line > start.line || (end.line == start.line && end.column >= start.column),
118                    "MetaItem::Source must specify a range in non-descending order"
119                );
120            }
121            MetaItem::NamedScope { name: _, source, parent } | MetaItem::IndexedScope { index: _, source, parent } => {
122                if let MetaItem::NamedScope { name, .. } = self {
123                    assert!(!name.is_empty(), "MetaItem::NamedScope must have a name");
124                }
125                assert!(
126                    matches!(*design.ref_metadata_item(*source), MetaItem::None | MetaItem::Source { .. }),
127                    concat!(
128                        "source of a MetaItem::NamedScope or MetaItem::IndexedScope must be ",
129                        "MetaItem::None or MetaItem::Source"
130                    )
131                );
132                assert!(
133                    matches!(
134                        *design.ref_metadata_item(*parent),
135                        MetaItem::None | MetaItem::NamedScope { .. } | MetaItem::IndexedScope { .. }
136                    ),
137                    concat!(
138                        "parent of a MetaItem::NamedScope or MetaItem::IndexedScope must be ",
139                        "MetaItem::None, MetaItem::NamedScope, or MetaItem::IndexedScope"
140                    )
141                );
142            }
143            MetaItem::Ident { name, scope } => {
144                assert!(!name.is_empty(), "MetaItem::Ident must have a name");
145                assert!(
146                    matches!(
147                        *design.ref_metadata_item(*scope),
148                        MetaItem::NamedScope { .. } | MetaItem::IndexedScope { .. }
149                    ),
150                    "scope of a MetaItem::Ident must be MetaItem::NamedScope or MetaItem::IndexedScope"
151                );
152            }
153            MetaItem::Attr { name, value: _ } => {
154                assert!(!name.is_empty(), "MetaItem::Attr must have a name");
155            }
156        }
157    }
158}
159
160impl MetaStringId {
161    pub const EMPTY: MetaStringId = MetaStringId(0);
162
163    pub fn is_empty(self) -> bool {
164        self == Self::EMPTY
165    }
166}
167
168impl EntityId for MetaStringId {
169    fn from_idx(idx: usize) -> Self {
170        Self(idx.try_into().unwrap())
171    }
172
173    fn to_idx(self) -> usize {
174        self.0.try_into().unwrap()
175    }
176}
177
178impl MetaItemId {
179    pub const NONE: MetaItemId = MetaItemId(0);
180
181    pub fn is_none(self) -> bool {
182        self == Self::NONE
183    }
184}
185
186impl EntityId for MetaItemId {
187    fn from_idx(idx: usize) -> Self {
188        Self(idx.try_into().unwrap())
189    }
190
191    fn to_idx(self) -> usize {
192        self.0.try_into().unwrap()
193    }
194}
195
196impl MetadataStore {
197    pub(crate) fn new() -> Self {
198        Self { strings: EntitySet::from_iter(["".to_owned()]), items: EntitySet::from_iter([MetaItem::None]) }
199    }
200
201    pub(crate) fn add_string<'a>(&mut self, string: impl Into<Cow<'a, str>>) -> MetaStringId {
202        let string = string.into();
203        self.strings.get_or_insert(string.as_ref())
204    }
205
206    pub(crate) fn add_item(&mut self, item: &MetaItem) -> MetaItemId {
207        self.items.get_or_insert(item)
208    }
209
210    pub(crate) fn iter_items(&self) -> impl Iterator<Item = MetaItemId> {
211        self.items.ids().into_iter()
212    }
213
214    pub fn iter_item<'a>(&self, design: &'a Design, item: MetaItemId) -> impl Iterator<Item = MetaItemId> + use<'a> {
215        MetaItemIterator { design, item, offset: 0 }
216    }
217}
218
219impl core::ops::Index<MetaStringId> for MetadataStore {
220    type Output = str;
221
222    fn index(&self, index: MetaStringId) -> &Self::Output {
223        self.strings[index].as_str()
224    }
225}
226
227impl core::ops::Index<MetaItemId> for MetadataStore {
228    type Output = MetaItem;
229
230    fn index(&self, index: MetaItemId) -> &Self::Output {
231        &self.items[index]
232    }
233}
234
235impl<'a> Iterator for MetaItemIterator<'a> {
236    type Item = MetaItemId;
237
238    fn next(&mut self) -> Option<Self::Item> {
239        let repr = self.design.ref_metadata_item(self.item);
240        let slice = match *repr {
241            MetaItem::None => &[][..],
242            MetaItem::Set(ref items) => &items[..],
243            _ => std::slice::from_ref(&self.item),
244        };
245        if self.offset < slice.len() {
246            let item = slice[self.offset];
247            self.offset += 1;
248            Some(item)
249        } else {
250            None
251        }
252    }
253}
254
255impl Display for MetaItemId {
256    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
257        let index = self.0;
258        assert!(index > 0);
259        write!(f, "!{}", index - 1)
260    }
261}