syntax = "proto3";

/// Package - A Collection of Circuit-Modules
message Package {
  string domain = 1;
  repeated Module modules = 2;
  repeated ExternalModule ext_modules = 3;
  repeated ExternalSource ext_sources = 4;
}

/// Domain-qualified name, referring outside its own Library 
message QualifiedName {
  string domain = 1;
  string name = 2;
}

/// Reference to another Module, 
/// either defined in this Library (local) or another (external)
message Reference {
  oneof to {
    string local = 1;
    QualifiedName external = 2;
  }
}

/// Parameter Enumeration 
/// 
/// Supports the common param-types supported in legacy HDLs 
/// such as Verilog and SPICE. 
/// Both `string` and `literal` variants are stored as Protobuf strings,
/// but are handled materially 
message Parameter {
  oneof value {
    int64 integer = 2;  // Int 
    double double = 3;  // Float 
    string string = 4;  // String-valued parameter 
    string literal = 5; // Literal expressions, e.g. "my_param1 * 5 + sin(your_param3)"
  }
}

message Port {
  enum Direction {
    INPUT = 0;
    OUTPUT = 1;
    INOUT = 2;
    NONE = 3;
  }
  Signal signal = 1;
  Direction direction = 2;
}

message Signal {
  // Signal Name
  string name = 1;
  // Bus Width 
  int64 width = 2;
}

// Signal Slice
message Slice {
  // Parent Signal Name
  string signal = 1;
  // Top Index
  int64 top = 2;
  // Bottom Index
  int64 bot = 3;
}

// Signal Concatenation 
message Concat {
  repeated Connection parts = 1;
}

// Connection Union
// Enumerates all types that can be 
// (a) Connected to Ports, and 
// (b) Concatenated 
message Connection {
  oneof stype {
    Signal sig = 1;
    Slice slice = 2;
    Concat concat = 3;
  }
}
/// Module Instance 
message Instance {
  // Instance Name 
  string name = 1;
  // Reference to Module instantiated
  Reference module = 2;
  // Parameter Values 
  map<string, Parameter> parameters = 3;
  // Map internal to external signals by name.
  map<string, Connection> connections = 4;
}

/// Module - the primary unit of hardware re-use
message Module {
  // Module Name 
  string name = 1;
  // Port Definitions 
  repeated Port ports = 2;
  // Internal Signals
  repeated Signal signals = 3;
  // Module Instances
  repeated Instance instances = 4;
  // Parameters and Default Values 
  map<string, Parameter> default_parameters = 5;
}

/// # Externally Defined Module 
/// Primarily for sake of port-ordering, 
/// for translation with by-position formats. 
message ExternalModule {
  // (Qualified) Module Name 
  QualifiedName name = 1;
  // Port Definitions 
  repeated Port ports = 2;
  // Description
  string desc = 3;
}

/// # External Source
/// Primarily for sake of port-ordering, 
/// for translation with by-position formats. 
message ExternalSource {
  oneof src {
    string path = 1; // File-path on (some) filesystem
    string url = 2; // URL to module definitions 
  }
}

