Skip to content

jitx/ref

Package name: jitx/ref

Summary

Data Types

FieldRef

Constructors

Function Description
FieldRef Constructor for defstruct FieldRef

IndexRef

Constructors

Function Description
IndexRef Constructor for defstruct IndexRef

Ref

Functions

Function Description
ref-length Count the length of a Ref.
tail Return the tail of some reference by removing
base Extract the first l components of some Ref
Ref Convenience Ref constructor. Only generates VarRef objects; cannot
get get enables the construction of Ref values via array-access syntax.
dot (+ 1) dot enables the construction of Ref values via "dot" syntax.
remove-base Removes the "base" of a Ref
prefix? A predicate for checking whether or not a Ref r has

VarRef

Constructors

Function Description
VarRef Constructor for defstruct VarRef

Definitions

FieldRef

public defstruct FieldRef <: Ref :
    field: VarRef
    ref: Ref

  • field: VarRef - A VarRef containing the name of the field.

  • ref: Ref - The base Ref of the JITX object.

Constructors

FieldRef

Constructor for defstruct FieldRef

public defn FieldRef (ref:Ref, field:VarRef)

IndexRef

public defstruct IndexRef <: Ref :
    index: Int
    ref: Ref

  • index: Int - An integer array index.

  • ref: Ref - The base Ref of the array of JITX objects.

Constructors

IndexRef

Constructor for defstruct IndexRef

public defn IndexRef (ref:Ref, index:Int)

Ref

public deftype Ref <: Hashable & Equalable & Comparable<Ref>

The Ref data structure represents a reference to a JITX object in a hierarchical design.

Ports, instances, pads, and nets can all have a Ref, which represents the object's location within the design hierarchy. Note that its possible to create nameless nets, in which case the net object will not have an associated Ref.

There are three kinds of Ref corresponding to the three ways to reference an object in a design: * VarRef: a named object * FieldRef: a named field in another object. For example hdmi.clk * IndexRef: a member of an array of objects, referenced by its index. For example, p[2].

The syntax #R(cpu.p[50]) constructs Ref values via the usual "dot" and "bracket" syntax for accessing JITX objects. Ref values correspond directly with accesses to an object within the hierarchy of pins, bundles, and instances.

pcb-component cpu :
  port p : pin[50]

pcb-component capacitor :
  port a
  port b

pcb-module my-module :
  inst proc : cpu
  inst cap : capacitor

  ; Prints "proc" -- This is a `VarRef` value
  println(ref(proc))

  ; Prints "cap.p" -- This is a `FieldRef` value
  println(ref(cap.a))

  ; Prints "proc.p[0]", "proc.p[1]", ...
  ; Each one is an `IndexRef` value
  for p in pins(proc) :
    println(ref(p))

Functions

ref-length

Count the length of a Ref.

public defn ref-length (r:Ref)

The length of a Ref is the number of "accesses".

public pcb-bundle wide-spi (width:Int):
  port sck
  port data : pin[width]

pcb-component demo :
  port spi : wide-spi(4)
  ; Prints 3
  println(ref-length(ref(spi.data[0])))

tail

Return the tail of some reference by removing

public defn tail (r:Ref, l:Int)

  • r: Ref - a Ref
  • l: Int - an integer, with l < ref-length®

the first l components.

public pcb-bundle wide-spi (width:Int):
  port sck
  port data : pin[width]

pcb-component demo :
  port spi : wide-spi(4)
  ; Prints "data[3]"
  println(tail(ref(spi.data[3]), 1))

base

Extract the first l components of some Ref

public defn base (r:Ref, l:Int)

  • r: Ref - any Ref
  • l: Int - an integer, with l <= ref-length®
public pcb-bundle wide-spi (width:Int):
  port sck
  port data : pin[width]

pcb-component demo :
  port spi : wide-spi(4)
  ; Prints "spi.data" 
  println(base(ref(spi.data[3]), 2))

Ref

Convenience Ref constructor. Only generates VarRef objects; cannot

public defn Ref (x)

be used to construct references to arrays or object members.

pcb-component cpu :
  port p[50]

  ; This returns false:
  ; `Ref(x)` can only produce `VarRef` objects 
  any?(fn (x) : ref(x) == Ref("p[30]"), pins(self))

  ; This returns true:
  ; We compare the `Ref` of each pin against a custom `IndexRef`
  any?(fn (x) : ref(x) == #R(p[30]), pins(self))

get

get enables the construction of Ref values via array-access syntax. 

public defn get (r1:Ref, i:Int)

  • r1: Ref - the "base" Ref
  • i: Int - the integer index

get(r, i) constructs an IndexRef at index i.

dot

dot enables the construction of Ref values via "dot" syntax.

public defn dot (r1:Ref, r2:Ref)

  • r1: Ref - the "base" Ref
  • r2: Ref - the "field" Ref

dot(r1, r2) essentially appends r2 to r1. For example, dot(#R(mod.cpu), #R(p[50])) yields #R(mod.cpu.p[50])

dot

public defn dot (f:False, r:Ref)

remove-base

Removes the "base" of a Ref

public defn remove-base (r:Ref, b:Ref)

  • r: Ref - any Ref
  • b: Ref - another Ref, where b is a prefix of r
public pcb-bundle wide-spi (width:Int):
  port sck
  port data : pin[width]

pcb-component demo :
  port spi : wide-spi(4)
  ; Prints "data[3]" 
  println(remove-base(ref(spi.data[3]), #R(spi)))

prefix?

A predicate for checking whether or not a Ref r has

public defn prefix? (r:Ref, prefix:Ref) -> True|False

  • r: Ref - a Ref
  • prefix: Ref - the possible prefix
  • Returns True|False

a given prefix.

; returns true
prefix?(#R(cpu.p[5]), #R(cpu.p))

; returns false
prefix?(#R(cpu.p[5]), #R(p[5]))

VarRef

public defstruct VarRef <: Ref :
    name: Symbol

  • name: Symbol - The name of the JITX Object.

Constructors

VarRef

Constructor for defstruct VarRef

public defn VarRef (name:Symbol)

Related Packages

Forwarded by package: jitx