Module Level Statements

A pcb-module statement defines a circuit made up of component instances and the connections between the ports of each instance. The pcb-module can be thought of as the circuit organization tool for building hierarchical circuits. In addition to defining the circuit net list, the pcb-module can also define physical geometry and the positioning of instances in the board view with respect to the module's kinematic frame.

The pcb-module is similar to the module in Verilog. If you are coming from VHDL, you will find that it is similar in ways to the entity concept except there is no way to provide multiple architecture bodies for a JITX pcb-module.

The pcb-module statement is valid in all contexts of a JITX design.

Signature

pcb-module mod-name (arg1:Type1, ...) :
  name = <String>
  description = <String|False>

  ; Other module statements here

The expression name mod-name uniquely identifies this module definition in the current context.

The argument list (arg1:Type1, ...) is optional and provides a means of constructing parameterized module definitions. The arguments in this list must be of type JITXValue.

There are many statements associated with the pcb-module definition. See the Statements section below for a detailed listing.

Minimal pcb-module Definition

All statements for a pcb-module are optional. Here is an example of the most minimal pcb-module definition:

pcb-module minimal:
  false

This is clearly not very useful - but demonstrates the point and it will compile.

One thing to notice is that indentation for the module definition's statements is required. Here the only statement is a value expression of false.

The indentation must be in the form of [spaces]. A tab character will cause a syntax error.

Usage

The pcb-module definition is quite versatile. It is typically used in the following conditions:

1. Defining the top-level for a circuit design. See Design Hierarchy for more info.
2. Defining reusable or one-off sub-circuits in a design.
3. Constructing a wrapper around a pcb-component instance.

Example Top-Level Design

val board-shape = RoundedRectangle(60.0, 40.0, 1.6)

pcb-module top-level :

  inst MCU : RP2040

  require bus:i2c from MCU

  inst accelerometer : MMA8451Q
  inst temp-sensor : TMP116

  net GND (MCU.GND, accelerometer.rail.V-, temp-sensor.rail.V-)
  net I2C (bus, accelerometer.bus, temp-sensor.bus)

  ...

  geom(GND):
    copper-pour(LayerIndex(1), isolate = 0.125, rank = 1) = board-shape
    copper-pour(LayerIndex(4), isolate = 0.125, rank = 1) = board-shape

Common Traits:

• For top-level design modules, you will often find multiple inst statements constructing the sub-circuit and components of a design.
• Top-level modules typically don't have port definitions. They can but it often isn't useful because the off-board interfaces are typically through connectors.
• It is very common to see many require statements that construct the pin assignment problem for the circuit.
• Top-level modules typically have geom statements to contruct large-scale features of a design, like ground planes and keepout regions.

Example Reusable Circuit

pcb-module LDO (comp:Instantiable, Vin:Double, Vout:Double) :
  port vin : power
  port vout : power

  inst ldo : comp

  net (vin.V+, ldo.VIN)
  net (vin.V-, vout.V-, ldo.GND)
  net (vout.V+, ldo.VOUT)

  bypass-cap-strap(ldo.VIN, ldo.GND, 1.0e-6)
  bypass-cap-strap(ldo.VOUT, ldo.GND, 1.0e-6)

  ; Construct Voltage divider here.
  inst div : voltage-divider(typ(Vin), typ(Vout))

  net (div.in, ldo.VOUT)
  net (div.out, ldo.FB)
  net (div.lo, ldo.GND)

Common Traits:

• Reusable pcb-module definitions are typically parametric
• Arguments are used to configure how those circuits behave - eg, what voltage to output.
• Some arguments might provide an Instantiable - meaning a component or module definition that will be instantiated inside this module.
• They will typically have standardized port interfaces using bundles.
• They will typically use other lower level primitives to build up more complex features.

Example Component Wrappers

pcb-module MMA8451Q :

  port bus : i2c
  port rail : power

  public inst comp : MMA8451Q-component

  bypass-cap-strap(comp.VDD, comp.GND, 4.7e-6)
  bypass-cap-strap(comp.BYP, comp.GND, 0.1e-6)
  bypass-cap-strap(comp.VDDIO, comp.GND, 0.1e-6)

  ...

Common Traits:

• Module wrappers around components are typically useful to encapsulate component specific features.
• For example, specific bypass capacitor specs per the components datasheets.
• Configuration resistor strapping, which may require parametric arguments.
• Module wrappers are typically very specific to a particular component.
• It is common to make the wrapped component public as a way to interrogate it from the parent context.
• These wrappers are often useful for using language features that are not present in the pcb-component definition context.

Statements

Here is the list of all of the statements you can use in a pcb-module :

Statement	Description
#CHECK	Assertion Checks
description	Description
do-not-populate	Do not Populate
eval-when	Eval When
geom	Custom copper geometry
insertion-loss	Add a Timing Difference Constraint - Topology
inst	Instantiate a component or module
instance-status	Instance Status
layer	Layer
layout-group	Layout Group
name	Name
net	Create an electrical connection
no-connect	Set a port as "Not Connected"
node	Node
pin-properties	Pin Properties Table
place	Set a component or module's pose
ports	Ports
reference-designator	Reference Designator Assignment
require	Require - Pin Assignemnt
restrict	Restrict - Pin Assignemnt
ref-label	Ref Label Assignment
schematic-group	Schematic Group
short-trace	Short Trace
structure	Structure - Topology
supports	Supports - Pin Assignemnt
symbol	Net Symbol Assignment
timing	Add a Timing Constraint - Topology
timing-difference	Add a Timing Difference Constraint - Topology
topology-segment	Construct an SI route - Topology
value-label	Value Label Assignment
variant	BOM Variant Definitions