//! 
//! # vlsir "Tetris" Gridded Layout Schema 
//! 
//! 

syntax = "proto3";
package vlsir.tetris;

import "utils.proto";
import "layout/raw.proto";
import "circuit.proto";


// # Library 
// 
// A collection of `Cells` and asssociated metadata. 
// Primary data in the `cells` field is valid only if stored in dependency order, 
// i.e. that each cell-definition must follow all cells that it depends upon. 
// 
message Library {
  // Library Name / Domain 
  string domain = 1; 

  // Cell Definitions
  repeated Cell cells = 10; 

  // Author Information 
  vlsir.utils.AuthorMetadata author = 20;
}

// # Cell 
// A multi-view representation of a piece of hardware.
message Cell {
  // Cell Name
  string name = 1;

  // IO Interface
  vlsir.circuit.Interface interface = 10;
  // Circuit Module Definition 
  vlsir.circuit.Module module = 11;
  // Physical Abstract
  Abstract abstract = 12;
  // Physical Layout Implementation
  Layout layout = 13;
}

// # Layout 
// 
// Physical implementation of a `Cell`. Tetris layouts consist of: 
// * `Instances` of other `Cells`, 
// * Net-assignments at grid crossings, and 
// * Cuts of the grid 
// (That's all.) 
// 
// `Layouts` have an explicit `Outline`, in which all their attributes must fit, 
// and into which no other `Layout` can encroach. 
// This operates similarly to "blockage" on all layers in legacy layout systems. 
// 
message Layout {
  // Cell Name
  string name = 1;
  // Outline 
  Outline outline = 10;
  // Layout Instances
  repeated Instance instances = 20;
  // Net-to-track assignments
  repeated Assign assignments = 21;
  // Track cuts
  repeated TrackCross cuts = 22;
}

// # Assignment 
// 
// Assigns signal `net` to the two tracks crossing in location `at`. 
// Tetris signal-assignments are to track-crosses. 
// This operates much like assigning to a via, plus the tracks above and below. 
message Assign {
  // Net Name
  string net = 1;
  // Location
  TrackCross at = 2;
}

// # Track Cross
// Crossing between two `TrackRefs`
message TrackCross {
  // "Primary" Track
  TrackRef track = 1;
  // Intersection location, on an orthogonal layer
  TrackRef cross = 2;
}

// # Track Reference
// Integer-pair pointer to a layer-index and track-index 
message TrackRef {
  // Layer Index
  int64 layer = 1;
  // Track Index
  int64 track = 2;
}

// # Cell Outlines
// ## "Tetris Shaped" rectilinear polygons
//
// These boundaries are closed, consist solely of 90-degree rectangular turns,
// and are specified by a counter-clockwise set of points.
// "Holes" such as the shapes "O" and "8" and "divots" such as the shapes "U" and "H" are not supported.
// The z-axis top is uniform and specified by a single layer-index `top_layer`. 
//
// Two equal-length vectors `x` and `y` describe an Outline's (x, y) points.
// Counter-clockwise-ness and divot-free-ness requires that:
// * (a) `x` values are monotonically non-increasing, and
// * (b) `y` values are monotonically non-decreasing
//
// In point-space terms, such an outline has vertices at:
// `[(0,0), (x[0], 0), (x[0], y[0]), (x[1], y[0]), ... , (0, y[-1]), (0,0)]`
// With the final point at (0, y[-1]), and its connection back to the origin both implied.
//
// Example: a rectangular Outline would require a single entry for each of `x` and `y`,
// at the rectangle's vertex opposite the origin in both axes.
//
message Outline {
  // X Coordinates
  repeated int64 x = 1;
  // Y Coordinates
  repeated int64 y = 2;
  // Number of metal layers used 
  int64 metals = 3;
}

// # Abstract Layout 
// 
// Defines the physical interface to a [Cell], including ports and internal blockages, 
// omitting internal implementation details.
message Abstract {
  // Cell Name
  string name = 1;
  // Outline 
  Outline outline = 10;
  // Ports 
  repeated AbstractPort ports = 20; 
}

// # Abstract Port
// Combination of a net and set of shapes
message AbstractPort {
  // Port Name
  string net = 1;

  // Enumerated port types
  oneof kind {
    // Edge 
    EdgePort edge = 10;
    // Z-Top, at Edge 
    ZTopEdgePort ztop_edge = 11;
    // Z-Top, inside Outline 
    ZTopInner ztop_inner = 12;
  }
  
  // # Edge Port
  // On a layer less than `top_layer`. Only connectable on its `track` and `side`.
  message EdgePort { 
    TrackRef track = 1;
    PortSide side = 2;
  }
  // # Z-Top, on Edge Port
  // Can be connected from either `top_layer+1`, or the edge on `top_layer`. 
  message ZTopEdgePort { 
    // Track index
    int64 track = 1;
    // Side
    PortSide side = 2;
    // Extent into the cell. 
    // Must be a location which intersects with (track, Side) inside the Outline.
    TrackRef into = 3;
  }
  // # Z-Top, inside Outline Port
  message ZTopInner { 
    // Locations. All must be on layers adjacent to the top-layer.
    repeated TrackCross locs = 1;
  }
  
  // # Abstract Port Side 
  // 
  // A two-value enum, as each layer either runs horizontally or vertically. 
  // Ports on the nearer-origin (bottom or left) sides use variant `BOTTOM_OR_LEFT`, 
  // while ports on the opposite sides use `TOP_OR_RIGHT`. 
  enum PortSide {
    BOTTOM_OR_LEFT = 0;
    TOP_OR_RIGHT = 1;
  }
}

// # Cell Instance
message Instance {
  // Instance Name
  string name = 1;
  // Cell Reference
  vlsir.utils.Reference cell = 3;
  
  // Location of the defined Cell's origin 
  // this location holds regardless of reflection settings.
  Place loc = 4; 
  // Horizontal reflection about y-axis
  bool reflect_horiz = 6;
  // Vertical reflection about x-axis
  bool reflect_vert = 7;
}

// # Place 
// An absolute or relative placement description
message Place {
  oneof place {
    // Absolute 
    vlsir.raw.Point abs = 1;
    // Relative 
    RelPlace rel = 2;
  }
}

// # Relative Place
message RelPlace { } 



// # Stack
//
// The z-stack, primarily including metal, via, and primitive layers
message Stack {
    // Measurement units
    vlsir.raw.Units units = 1;
    // Primitive Layer
    PrimitiveLayer prim = 2;
    // Set of metal layers
    repeated MetalLayer metals = 3;
    // Set of via layers
    repeated ViaLayer vias = 4;

    // [raw::Layer] Mappings
    // vlsir.raw.Layers rawlayers = 1;
    // Layer used for cell outlines/ boundaries
    vlsir.raw.Layer boundary_layer = 11;
}

// # LayerEnum 
// 
// Type and index of a layer.
// 
message LayerEnum {
  enum LayerType {
    PRIMITIVE = 0;
    METAL = 1;
    VIA = 2;
  }

  // Layer Type
  LayerType type = 1;
  // Index into the associated `LayerType` set 
  int64 index = 2;
}

// # MetalLayer
//
// Metal layer in a [Stack]
// Each layer is effectively infinite-spanning in one dimension, and periodic in the other.
// Layers with `dir=Dir::Horiz` extend to infinity in x, and repeat in y, and vice-versa.
//
message MetalLayer {
  // Direction Enumeration 
  enum Dir {
    HORIZ = 0;
    VERT = 1;
  }
  // Ownership split of a layer between Primitives and the Stack. 
  enum PrimitiveMode {
    PRIM = 0;   // Owned by Primitives 
    SPLIT = 1;  // Split between Primitives and the Stack 
    STACK = 2;  // Owned by the Stack 
  }
    // Layer Name
    string name = 1;
    // Direction Enumeration (Horizontal/ Vertical)
    Dir dir = 2;
    // Default size of wire-cuts
    int64 cutsize = 3;
    // Track Size & Type Entries
    repeated TrackSpec entries = 4;
    // Offset, in our periodic dimension
    int64 offset = 5;
    // Overlap between periods
    int64 overlap = 6;
    // Setting for period-by-period flipping
    bool flip = 7;
    // Primitive-layer relationship
    PrimitiveMode prim = 8;
    // Raw Layer
    vlsir.raw.Layer raw = 11;
}


// # ViaLayer
// 
// Insulator and connector Layer Between `MetalLayers`
message ViaLayer {
    // Layer name
    string name = 1;
    // Top of the two layers connected by this layer
    LayerEnum top = 2;
    // Bottom of the two layers connected by this layer
    LayerEnum bot = 3;
    // Via size
    Xy size = 4;
    // Raw Layer
    vlsir.raw.Layer raw = 11;
}

// # Primitive Layer
// 
// Encapsulates all layout information "below" an associated `Stack`.
// In typical process technologies this primarily includes "base layers", 
// such as those used in primitive transistors and logic cells. 
message PrimitiveLayer {
  // Pitches, in Database Units
  Xy pitches = 1;
}

// # Track Specification 
// 
// Includes definitions for the single `TrackEntry`
// and repitition thereof (`Repeat`). 
// Sole field `spec` is one of the two. 
// 
message TrackSpec {
  message TrackEntry {
    enum TrackType {
      GAP = 0; // Insulator Gap
      SIGNAL = 1; // Signal Track
      RAIL = 2; // Rail Track. FIXME: Add rail type. 
    }
    // TrackType
    TrackType ttype = 1;
    // Entry width 
    int64 width = 2;
  }

  // Repeated Pattern of Track Entries
  message Repeat {
    // List of entries
    repeated TrackEntry entries = 1;
    // Number of repetitions 
    int64 nrep = 2;
}

  // Sole internal field: either an entry or repetition thereof 
  oneof spec {
    // Single Entry 
    TrackEntry entry = 1;
    // Repetition 
    Repeat repeat = 2; 
  }
}

// # Xy 
// 
// Two-dimensional (x,y) pair. 
// While similar in content to `vlsir.raw.Point`, `Xy` data does not semantically 
// (necessarily) refer to a single point in Cartesian space. 
// More general use-cases include the size of blocks, or the pitch of a grid.
message Xy {
  int64 x = 1;
  int64 y = 2;
}