layir/
lib.rs

1#![allow(dead_code)]
2
3pub mod connectivity;
4pub mod id;
5
6use std::{
7    collections::{HashMap, HashSet, VecDeque},
8    ops::Deref,
9};
10
11use crate::id::Id;
12use arcstr::ArcStr;
13use enumify::enumify;
14use geometry::{
15    bbox::Bbox,
16    point::Point,
17    prelude::{Transform, Transformation},
18    rect::Rect,
19    transform::{TransformMut, TransformRef, Translate, TranslateMut, TranslateRef},
20    union::BoundingUnion,
21};
22use indexmap::{IndexMap, IndexSet};
23use serde::{Deserialize, Serialize};
24use thiserror::Error;
25use uniquify::Names;
26
27pub struct Cells;
28
29// The reason this uses [`Cells`] instead of [`Cell`]
30// is because `Cell` has a generic type parameter.
31pub type CellId = Id<Cells>;
32pub type InstanceId = Id<Instance>;
33
34#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
35pub struct LibraryBuilder<L> {
36    cell_id: CellId,
37    cells: IndexMap<CellId, Cell<L>>,
38    name_map: HashMap<ArcStr, CellId>,
39    names: Names<CellId>,
40}
41
42#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
43pub struct Library<L>(LibraryBuilder<L>);
44
45#[derive(Debug, Clone, Eq, PartialEq, Serialize, Deserialize)]
46pub struct Cell<L> {
47    name: ArcStr,
48    instance_id: InstanceId,
49    instances: IndexMap<InstanceId, Instance>,
50    instance_name_map: HashMap<ArcStr, InstanceId>,
51    elements: Vec<Element<L>>,
52    ports: IndexMap<ArcStr, Port<L>>,
53}
54
55/// A location at which this cell should be connected.
56#[derive(Debug, Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
57pub struct Port<L> {
58    direction: Direction,
59    elements: Vec<Element<L>>,
60}
61
62/// Port directions.
63#[derive(Debug, Copy, Clone, Hash, Eq, PartialEq, Default, Serialize, Deserialize)]
64pub enum Direction {
65    /// Input.
66    Input,
67    /// Output.
68    Output,
69    /// Input or output.
70    ///
71    /// Represents ports whose direction is not known
72    /// at generator elaboration time (e.g. the output of a tristate buffer).
73    #[default]
74    InOut,
75}
76
77/// A primitive layout element.
78#[derive(Debug, Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
79#[enumify]
80pub enum Element<L> {
81    /// A primitive layout shape.
82    Shape(Shape<L>),
83    /// A primitive text annotation.
84    Text(Text<L>),
85}
86
87/// A primitive layout shape consisting of a layer and a geometric shape.
88#[derive(Debug, Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
89pub struct Shape<L> {
90    layer: L,
91    shape: geometry::shape::Shape,
92}
93
94/// A primitive text annotation consisting of a layer, string, and location.
95#[derive(Debug, Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
96pub struct Text<L> {
97    layer: L,
98    text: ArcStr,
99    trans: Transformation,
100}
101
102#[derive(Debug, Clone, Hash, Eq, PartialEq, Serialize, Deserialize)]
103pub struct Instance {
104    child: CellId,
105    name: ArcStr,
106    trans: Transformation,
107}
108
109impl<L> Default for LibraryBuilder<L> {
110    fn default() -> Self {
111        Self {
112            cell_id: Id::new(),
113            names: Default::default(),
114            name_map: Default::default(),
115            cells: Default::default(),
116        }
117    }
118}
119
120impl<L> LibraryBuilder<L> {
121    pub fn new() -> Self {
122        Default::default()
123    }
124
125    pub fn add_cell(&mut self, mut cell: Cell<L>) -> CellId {
126        let id = self.cell_id.alloc();
127        cell.name = self.names.assign_name(id, &cell.name);
128        self.name_map.insert(cell.name.clone(), id);
129        assert!(self.cells.insert(id, cell).is_none());
130        id
131    }
132
133    pub fn cell(&self, id: CellId) -> &Cell<L> {
134        self.cells.get(&id).unwrap()
135    }
136
137    pub fn try_cell(&self, id: CellId) -> Option<&Cell<L>> {
138        self.cells.get(&id)
139    }
140
141    pub fn cell_named(&self, name: &str) -> &Cell<L> {
142        self.cell(*self.name_map.get(name).unwrap())
143    }
144
145    pub fn try_cell_named(&self, name: &str) -> Option<&Cell<L>> {
146        self.try_cell(*self.name_map.get(name)?)
147    }
148
149    /// Gets the cell ID corresponding to the given name.
150    ///
151    /// # Panics
152    ///
153    /// Panics if no cell has the given name.
154    /// For a non-panicking alternative, see [`try_cell_id_named`](LibraryBuilder::try_cell_id_named).
155    pub fn cell_id_named(&self, name: &str) -> CellId {
156        match self.name_map.get(name) {
157            Some(&cell) => cell,
158            None => {
159                tracing::error!("no cell named `{}`", name);
160                panic!("no cell named `{}`", name);
161            }
162        }
163    }
164
165    /// Gets the cell ID corresponding to the given name.
166    pub fn try_cell_id_named(&self, name: &str) -> Option<CellId> {
167        self.name_map.get(name).copied()
168    }
169
170    /// Iterates over the `(id, cell)` pairs in this library.
171    pub fn cells(&self) -> impl Iterator<Item = (CellId, &Cell<L>)> {
172        self.cells.iter().map(|(id, cell)| (*id, cell))
173    }
174
175    /// Returns cell IDs in topological order.
176    pub fn topological_order(&self) -> Vec<CellId> {
177        let mut state = IndexSet::new();
178        for (cell, _) in self.cells() {
179            self.dfs_postorder(cell, &mut state);
180        }
181        let ids = state.into_iter().collect::<Vec<_>>();
182        assert_eq!(ids.len(), self.cells.len());
183        ids
184    }
185
186    fn dfs_postorder(&self, id: CellId, state: &mut IndexSet<CellId>) {
187        if state.contains(&id) {
188            return;
189        }
190
191        let cell = self.cell(id);
192        for (_, inst) in cell.instances() {
193            self.dfs_postorder(inst.child(), state);
194        }
195        state.insert(id);
196    }
197
198    /// The list of cell IDs instantiated by the given root cells.
199    ///
200    /// The list returned will include the root cell IDs.
201    pub(crate) fn cells_used_by(&self, roots: impl IntoIterator<Item = CellId>) -> Vec<CellId> {
202        let mut stack = VecDeque::new();
203        let mut visited = HashSet::new();
204        for root in roots {
205            stack.push_back(root);
206        }
207
208        while let Some(id) = stack.pop_front() {
209            if visited.contains(&id) {
210                continue;
211            }
212            visited.insert(id);
213            let cell = self.cell(id);
214            for (_, inst) in cell.instances() {
215                stack.push_back(inst.child);
216            }
217        }
218
219        visited.drain().collect()
220    }
221
222    pub fn build(self) -> Result<Library<L>, BuildError> {
223        Ok(Library(self))
224    }
225}
226
227#[derive(Clone, Debug, Error)]
228#[error("error building LayIR library")]
229pub struct BuildError;
230
231impl<L> Deref for Library<L> {
232    type Target = LibraryBuilder<L>;
233    fn deref(&self) -> &Self::Target {
234        &self.0
235    }
236}
237
238impl<L> Cell<L> {
239    pub fn new(name: impl Into<ArcStr>) -> Self {
240        Self {
241            name: name.into(),
242            instance_id: Id::new(),
243            instances: Default::default(),
244            instance_name_map: Default::default(),
245            elements: Default::default(),
246            ports: Default::default(),
247        }
248    }
249
250    /// The name of the cell.
251    #[inline]
252    pub fn name(&self) -> &ArcStr {
253        &self.name
254    }
255
256    /// Iterate over the ports of this cell.
257    #[inline]
258    pub fn ports(&self) -> impl Iterator<Item = (&ArcStr, &Port<L>)> {
259        self.ports.iter()
260    }
261
262    pub fn add_port(&mut self, name: impl Into<ArcStr>, port: Port<L>) {
263        self.ports.insert(name.into(), port);
264    }
265
266    /// Get a port of this cell by name.
267    ///
268    /// # Panics
269    ///
270    /// Panics if the provided port does not exist.
271    #[inline]
272    pub fn port(&self, name: &str) -> &Port<L> {
273        self.try_port(name).unwrap()
274    }
275
276    /// Get a mutable reference to a port of this cell by name.
277    ///
278    /// # Panics
279    ///
280    /// Panics if the provided port does not exist.
281    #[inline]
282    pub fn port_mut(&mut self, name: &str) -> &mut Port<L> {
283        self.try_port_mut(name).unwrap()
284    }
285
286    /// Get a port of this cell by name.
287    #[inline]
288    pub fn try_port(&self, name: &str) -> Option<&Port<L>> {
289        self.ports.get(name)
290    }
291
292    /// Get a mutable reference to a port of this cell by name.
293    #[inline]
294    pub fn try_port_mut(&mut self, name: &str) -> Option<&mut Port<L>> {
295        self.ports.get_mut(name)
296    }
297
298    /// Get the instance associated with the given ID.
299    ///
300    /// # Panics
301    ///
302    /// Panics if no instance with the given ID exists.
303    #[inline]
304    pub fn instance(&self, id: InstanceId) -> &Instance {
305        self.instances.get(&id).unwrap()
306    }
307
308    /// Get the instance associated with the given ID.
309    #[inline]
310    pub fn try_instance(&self, id: InstanceId) -> Option<&Instance> {
311        self.instances.get(&id)
312    }
313
314    /// Gets the instance with the given name.
315    ///
316    /// # Panics
317    ///
318    /// Panics if no instance has the given name.
319    pub fn instance_named(&self, name: &str) -> &Instance {
320        self.instance(*self.instance_name_map.get(name).unwrap())
321    }
322
323    /// Gets the instance with the given name.
324    pub fn try_instance_named(&self, name: &str) -> Option<&Instance> {
325        self.try_instance(*self.instance_name_map.get(name)?)
326    }
327
328    /// Add the given instance to the cell.
329    #[inline]
330    pub fn add_instance(&mut self, instance: Instance) -> InstanceId {
331        let id = self.instance_id.alloc();
332        self.instance_name_map.insert(instance.name.clone(), id);
333        self.instances.insert(id, instance);
334        id
335    }
336
337    /// Iterate over the instances of this cell.
338    #[inline]
339    pub fn instances(&self) -> impl Iterator<Item = (InstanceId, &Instance)> {
340        self.instances.iter().map(|x| (*x.0, x.1))
341    }
342
343    pub fn add_element(&mut self, element: impl Into<Element<L>>) {
344        self.elements.push(element.into())
345    }
346
347    pub fn elements(&self) -> impl Iterator<Item = &Element<L>> {
348        self.elements.iter()
349    }
350}
351
352impl<L> Port<L> {
353    pub fn new(direction: Direction) -> Self {
354        Self {
355            direction,
356            elements: Default::default(),
357        }
358    }
359
360    pub fn direction(&self) -> Direction {
361        self.direction
362    }
363
364    pub fn elements(&self) -> impl Iterator<Item = &Element<L>> {
365        self.elements.iter()
366    }
367
368    pub fn add_element(&mut self, element: impl Into<Element<L>>) {
369        self.elements.push(element.into())
370    }
371
372    pub fn map_layer<L2, F>(&self, f: F) -> Port<L2>
373    where
374        F: Fn(&L) -> L2,
375    {
376        Port {
377            direction: self.direction,
378            elements: self.elements().map(|e| e.map_layer(&f)).collect(),
379        }
380    }
381}
382
383impl<L> Element<L> {
384    pub fn layer(&self) -> &L {
385        match self {
386            Self::Shape(s) => s.layer(),
387            Self::Text(t) => t.layer(),
388        }
389    }
390
391    pub fn with_layer<L2>(&self, layer: L2) -> Element<L2> {
392        match self {
393            Self::Shape(s) => Element::Shape(s.with_layer(layer)),
394            Self::Text(t) => Element::Text(t.with_layer(layer)),
395        }
396    }
397
398    pub fn map_layer<L2, F>(&self, f: F) -> Element<L2>
399    where
400        F: FnOnce(&L) -> L2,
401    {
402        match self {
403            Element::Shape(x) => Element::Shape(x.map_layer(f)),
404            Element::Text(x) => Element::Text(x.map_layer(f)),
405        }
406    }
407}
408
409impl<L> From<Shape<L>> for Element<L> {
410    fn from(value: Shape<L>) -> Self {
411        Self::Shape(value)
412    }
413}
414
415impl<L> From<Text<L>> for Element<L> {
416    fn from(value: Text<L>) -> Self {
417        Self::Text(value)
418    }
419}
420
421impl<L> Shape<L> {
422    #[inline]
423    pub fn new(layer: L, shape: impl Into<geometry::shape::Shape>) -> Self {
424        Self {
425            layer,
426            shape: shape.into(),
427        }
428    }
429
430    #[inline]
431    pub fn layer(&self) -> &L {
432        &self.layer
433    }
434
435    #[inline]
436    pub fn shape(&self) -> &geometry::shape::Shape {
437        &self.shape
438    }
439
440    pub fn with_layer<L2>(&self, layer: L2) -> Shape<L2> {
441        Shape {
442            layer,
443            shape: self.shape().clone(),
444        }
445    }
446
447    pub fn map_layer<L2>(&self, f: impl FnOnce(&L) -> L2) -> Shape<L2> {
448        Shape {
449            layer: f(&self.layer),
450            shape: self.shape().clone(),
451        }
452    }
453}
454
455impl<L> Text<L> {
456    #[inline]
457    pub fn new(layer: L, text: impl Into<ArcStr>) -> Self {
458        Self {
459            layer,
460            text: text.into(),
461            trans: Default::default(),
462        }
463    }
464
465    #[inline]
466    pub fn with_transformation(
467        layer: L,
468        text: impl Into<ArcStr>,
469        trans: impl Into<Transformation>,
470    ) -> Self {
471        Self {
472            layer,
473            text: text.into(),
474            trans: trans.into(),
475        }
476    }
477
478    #[inline]
479    pub fn layer(&self) -> &L {
480        &self.layer
481    }
482
483    #[inline]
484    pub fn text(&self) -> &ArcStr {
485        &self.text
486    }
487
488    #[inline]
489    pub fn transformation(&self) -> Transformation {
490        self.trans
491    }
492
493    pub fn with_layer<L2>(&self, layer: L2) -> Text<L2> {
494        Text {
495            layer,
496            trans: self.trans,
497            text: self.text.clone(),
498        }
499    }
500
501    pub fn map_layer<L2>(&self, f: impl FnOnce(&L) -> L2) -> Text<L2> {
502        Text {
503            layer: f(&self.layer),
504            trans: self.trans,
505            text: self.text.clone(),
506        }
507    }
508}
509
510impl Instance {
511    pub fn new(child: CellId, name: impl Into<ArcStr>) -> Self {
512        Self {
513            child,
514            name: name.into(),
515            trans: Default::default(),
516        }
517    }
518
519    pub fn with_transformation(
520        child: CellId,
521        name: impl Into<ArcStr>,
522        transformation: impl Into<Transformation>,
523    ) -> Self {
524        Self {
525            child,
526            name: name.into(),
527            trans: transformation.into(),
528        }
529    }
530
531    #[inline]
532    pub fn child(&self) -> CellId {
533        self.child
534    }
535
536    #[inline]
537    pub fn name(&self) -> &ArcStr {
538        &self.name
539    }
540
541    #[inline]
542    pub fn transformation(&self) -> Transformation {
543        self.trans
544    }
545}
546
547impl<L> Bbox for Shape<L> {
548    fn bbox(&self) -> Option<Rect> {
549        self.shape.bbox()
550    }
551}
552
553impl<L: PartialEq> LayerBbox<L> for Shape<L> {
554    fn layer_bbox(&self, layer: &L) -> Option<Rect> {
555        if self.layer.eq(layer) {
556            self.bbox()
557        } else {
558            None
559        }
560    }
561}
562
563impl<L, T: Bbox> BoundingUnion<T> for Shape<L> {
564    type Output = Rect;
565
566    fn bounding_union(&self, other: &T) -> Self::Output {
567        self.bbox().unwrap().bounding_union(&other.bbox())
568    }
569}
570
571impl<L: Clone> TransformRef for Shape<L> {
572    fn transform_ref(&self, trans: Transformation) -> Self {
573        Shape {
574            layer: self.layer.clone(),
575            shape: self.shape.transform_ref(trans),
576        }
577    }
578}
579
580impl<L: Clone> TranslateRef for Shape<L> {
581    fn translate_ref(&self, p: Point) -> Self {
582        Shape {
583            layer: self.layer.clone(),
584            shape: self.shape.translate_ref(p),
585        }
586    }
587}
588
589impl<L> TranslateMut for Shape<L> {
590    fn translate_mut(&mut self, p: Point) {
591        self.shape.translate_mut(p)
592    }
593}
594
595impl<L> TransformMut for Shape<L> {
596    fn transform_mut(&mut self, trans: Transformation) {
597        self.shape.transform_mut(trans)
598    }
599}
600
601/// A trait representing functions available for multi-layered objects with bounding boxes.
602pub trait LayerBbox<L>: Bbox {
603    /// Compute the bounding box considering only objects occupying the given layer.
604    fn layer_bbox(&self, layer: &L) -> Option<Rect>;
605}
606
607impl<L, T: LayerBbox<L>> LayerBbox<L> for Vec<T> {
608    fn layer_bbox(&self, layer: &L) -> Option<Rect> {
609        let mut bbox = None;
610        for item in self {
611            bbox = bbox.bounding_union(&item.layer_bbox(layer));
612        }
613        bbox
614    }
615}
616
617impl<L, T: LayerBbox<L>> LayerBbox<L> for &T {
618    fn layer_bbox(&self, layer: &L) -> Option<Rect> {
619        (*self).layer_bbox(layer)
620    }
621}
622
623impl<L: Clone> TranslateRef for Text<L> {
624    fn translate_ref(&self, p: Point) -> Self {
625        self.clone().translate(p)
626    }
627}
628
629impl<L: Clone> TransformRef for Text<L> {
630    fn transform_ref(&self, trans: Transformation) -> Self {
631        self.clone().transform(trans)
632    }
633}
634
635impl<L> TranslateMut for Text<L> {
636    fn translate_mut(&mut self, p: Point) {
637        self.transform_mut(Transformation::from_offset(p))
638    }
639}
640
641impl<L> TransformMut for Text<L> {
642    fn transform_mut(&mut self, trans: Transformation) {
643        self.trans = Transformation::cascade(trans, self.trans);
644    }
645}
layir/lib.rs

layir/
lib.rs
