introspection¶

Package name: jsl/design/introspection

Summary¶

PortInfo ¶

Port Info Object

Constructors¶

Function	Description
PortInfo	Constructor for `defstruct PortInfo`

Functions¶

Function	Description
connected-net
get-port-info	Extract Port Info from a port `JITXObject`

General Definitions¶

Function	Description
find-instance-by-ref	Find an instance by `Ref` by searching the design hierarchy.
get-component-by-ref	Retrieve a Component Instance from a particular context by Ref
is-component?	Check if the passed object is a `pcb-component` instance
get-pads-from-ports	Get pads for each port and combine them into a single list
port-to-pads	Retrieve a mapping of Ports to Pads
get-parent-ref	Get the parent ref for a particular object
get-element-ports	Retrieve the two ports of a 2-pin element device.
cathode-anode?	Get the Cathode / Anode Ports of a device if they exist
get-port-by-name	Retrieve a Port by its symbol name
get-pads-from-port (+ 1)	Retrieve the pads associated with a particular port
is-module?	Check if the passed object is a `pcb-module` instance
get-connected-nets	Get all net statements associated with a module or component port
get-symbpin-by-name	Retrieve a schematic symbol pin by name
get-parent-from-port	Retrieve the parent instance (component or module) for a port.
get-instantiable	Retrieve the `Instantiable` that generates the instances of the passed object.
get-parent-ref!
get-ref-name	Get the final name field for a ref
get-component-from-port	Get a component instance from a Port
get-instance-by-ref	Retrieve an Instance from a particular context by Ref

Definitions¶

PortInfo¶

Port Info Object

public defstruct PortInfo <: JITXValue & Equalable & Hashable :
    connected-nets: Tuple<JITXObject>
    pad-set: Tuple<PadInfo>

connected-nets: Tuple<JITXObject>
pad-set: Tuple<PadInfo>

This object is primarily a tool for working around limitations in the pcb-module / pcb-component hierarchy.

This object will make requests to retrieve data about a port then consolidate into a single pass-able object to various functions and generators.

Constructors¶

PortInfo¶

Constructor for defstruct PortInfo

public defn PortInfo (connected-nets:Tuple<JITXObject>, pad-set:Tuple<PadInfo>)

Functions¶

connected-net¶

public defn connected-net (p:PortInfo) -> JITXObject|False

Returns JITXObject|False

get-port-info¶

Extract Port Info from a port JITXObject

public defn get-port-info (pt:JITXObject) -> PortInfo

pt: JITXObject - Port referenced from an component object, typically using dot notation like MCU.RESET_n.
Returns PortInfo - Extracted port data for this port.

General Definitions¶

find-instance-by-ref¶

Find an instance by Ref by searching the design hierarchy.

public defn find-instance-by-ref (r:Ref, cxt:JITXObject = ?) -> Maybe<JITXObject>

r: Ref - Ref of the Instance object we wish to find. An instance can be either a pcb-module or pcb-component.
cxt: JITXObject - Parent scope to search in. By default this is self.
Returns Maybe<JITXObject> - If we find an instance by the pass Ref r in the cxt context, then we will return a JITXObject for that instance. Otherwise, None().

This function must be called from within a pcb-module context.

get-component-by-ref¶

Retrieve a Component Instance from a particular context by Ref

public defn get-component-by-ref (r:Ref, cxt:JITXObject = ?) -> Maybe<JITXObject>

r: Ref - Ref to an object in cxt - Note that the path must be referenced from the cxt. Any prefix in the ref before cxt will likely result in a failure to find the instance. Notice that for the self context, then we can just pass references without the self. prefix.
cxt: JITXObject - Context from which we will query the instances. By default this value is self.
Returns Maybe<JITXObject> - Instance of a pcb-component in the cxt context. Note that pcb-module instances will be filtered out.

This function must be called from within a pcb-module context.

This function is not recursive. If the caller passes some.obj from the cxt context, then that object will not be found because obj is within the some object context, not cxt. This function could find cxt.some if passed some.

is-component?¶

Check if the passed object is a pcb-component instance

public defn is-component? (obj:JITXObject) -> True|False

Returns True|False

get-pads-from-ports¶

Get pads for each port and combine them into a single list

public defn get-pads-from-ports (pts:Seqable<JITXObject>, cxt:JITXObject = ?) -> Seq<JITXObject>

Returns Seq<JITXObject>

port-to-pads¶

Retrieve a mapping of Ports to Pads

public defn port-to-pads (dev:JITXObject) -> Tuple<KeyValue<JITXObject, Tuple<JITXObject>>>

dev: JITXObject - Instance of a pcb-component. This function odes not work for pcb-module instances.
Returns Tuple<KeyValue<JITXObject, Tuple<JITXObject>>> - Tuple of KeyValue mappings between Pin and a Tuple of Pad objects.

This function will retrieve all of the

get-parent-ref¶

Get the parent ref for a particular object

public defn get-parent-ref (r:Ref) -> Maybe<Ref>

r: Ref - Ref to a child object of a parent - ie some.parent.child
Returns Maybe<Ref> - Ref to the parent of the child object - ie some.parent

This is useful to get the Ref of the parent component when passed a Ref to a port of that component.

get-element-ports¶

Retrieve the two ports of a 2-pin element device.

public defn get-element-ports (obj:JITXObject|SchematicSymbol) -> [JITXObject, JITXObject]

obj: JITXObject|SchematicSymbol - Two-Pin component/module instance or a SchematicSymbol
Returns [JITXObject, JITXObject] - Tuple of two ports of the object - They are returned either as:
[p[1], p[2]]
[c, a]

Depending on whether the passed device is polarized.

Two-pin lumped circuit element devices (like resistors, capacitors, etc) come typically in one of two forms:

The p[1] and p[2] form for non-polarized devices.
The c and a form for the cathode / anode of polarized devices.

This function interrogates an object and retrieves the ports in a known order for use in circuits.

cathode-anode?¶

Get the Cathode / Anode Ports of a device if they exist

public defn cathode-anode? (obj-symb:JITXObject|SchematicSymbol) -> Maybe<[JITXObject, JITXObject]>

obj-symb: JITXObject|SchematicSymbol - Two-pin component/module instance or SchematicSymbol that may or may not be a polarized device with cathode (c) and anode (a) ports.
Returns Maybe<[JITXObject, JITXObject]> - If the passed object is a polarized device, then this returns One<Tuple> of the ports in the order [c, a]. If not a polarized device, this function returns None()

get-port-by-name¶

Retrieve a Port by its symbol name

public defn get-port-by-name (obj:JITXObject, name:String) -> Maybe<JITXObject>

obj: JITXObject - Component or Module to interrogate for a port
name: String - Name of port to interrogate. This name can include dot-notation style introspection if needed.
Returns Maybe<JITXObject> - None() if no port by this name exists. One<JITXObject> if a port is found by the passed name.

This function retrieves a port on a component but doesn't throw an error if that port does not exist.

For PortArray ports, if the name contains the [] indexing argument, then this will find individual port array elements. If there is not [] indexing argument, then the PortArray port itself will be returned.

get-pads-from-port¶

Retrieve the pads associated with a particular port

public defn get-pads-from-port (p2p-map:Tuple<KeyValue<JITXObject, Tuple<JITXObject>>>, pt:JITXObject) -> Maybe<Tuple<JITXObject>>

p2p-map: Tuple<KeyValue<JITXObject, Tuple<JITXObject>>> - Previously computed port to pad mapping from a pcb-component instance
pt: JITXObject - Port of a component instance
Returns Maybe<Tuple<JITXObject>> - If port is found and has pads, a tuple of Pad objects for that port. Otherwise None().

get-pads-from-port¶

Retrieve the pads associated with a particular port

public defn get-pads-from-port (pt:JITXObject, cxt:JITXObject = ?) -> Maybe<Tuple<JITXObject>>

pt: JITXObject - Port on a component in the passed context.
cxt: JITXObject - Context to search for the component instance. The default is self.
Returns Maybe<Tuple<JITXObject>> - If component associated with pt is found in cxt and the port pt has pads, this function returns a tuple of Pad objects for that port. Otherwise None().

is-module?¶

Check if the passed object is a pcb-module instance

public defn is-module? (obj:JITXObject) -> True|False

Returns True|False

get-connected-nets¶

Get all net statements associated with a module or component port

public defn get-connected-nets (pt:JITXObject, cxt:JITXObject = ?) -> Tuple<JITXObject>

pt: JITXObject - Port of a component or module in this module context.
cxt: JITXObject - Optional context to search. The default value is self.
Returns Tuple<JITXObject> - If a connection is found - this function returns the Net as a JITXObject. If no connection is found - then None().

This function must be called from within a pcb-module context.

Note that this function will fail to find a net if the passed pt port is not part of a component or module in the local context. For example, if the design contains:

pcb-module wrapper:
  port GND
  inst C : some-component

  ; `INT` is defined only in the `wrapper`
  ;   context.
  net INT (C.internal-port, ...)

pcb-module top-level:

  port pwr : power
  inst W : wrapper
  net GND (W.GND)
  net (GND, pwr.V-)

  ; This will return two nets: one for each statement above
  val n1 = get-connected-nets(W.GND)

  ; This will return an empty tuple
  val n2 = get-connected-nets(W.C.internal-port)

n1 will be a tuple of two net objects, since there are two net statements defined in the pcb-module context.

The n2 invocation will fail to find INT as the net for W.C.internal-port and return an empty tuple

get-symbpin-by-name¶

Retrieve a schematic symbol pin by name

public defn get-symbpin-by-name (obj:SchematicSymbol, name:String) -> Maybe<JITXObject>

obj: SchematicSymbol - Schematic Symbol object
name: String - Potential name of a pin on the schematic symbol.
Returns Maybe<JITXObject> - If a pin with this name exists, return one. If not - return None().

Similar to get-port-by-name but works for SchematicSymbol objects.

get-parent-from-port¶

Retrieve the parent instance (component or module) for a port.

public defn get-parent-from-port (pt:JITXObject, cxt:JITXObject = ?) -> Maybe<JITXObject>

pt: JITXObject - Port on a component or module
Returns Maybe<JITXObject> - Reference to a pcb-module or pcb-component instance.

This function expects the caller to pass a port comp.GND and then this function will return a reference to comp as a JITXObject.

Be careful of child ports on bundle ports - these will give a ref to the parent bundle port - not the component.

This function expects to be called from pcb-module context.

get-instantiable¶

Retrieve the Instantiable that generates the instances of the passed object.

public defn get-instantiable (comps:JITXObject|InstantiableType) -> Instantiable

comps: JITXObject|InstantiableType - This is a instantiated component or module, or an array of instances (all of the same type).
Returns Instantiable - The originating instantiable of either the instance or the elements of the array.

NOTE: This function is recursive.

get-parent-ref!¶

public defn get-parent-ref! (r:Ref) -> Ref

Returns Ref

get-ref-name¶

Get the final name field for a ref

public defn get-ref-name (r:Ref) -> Ref

r: Ref - Ref object that we will interrogate
Returns Ref - The field field of the ref as either a VarRef or an IndexRef.

This function will return the final field in a ref.

Example #1¶

val A = #R(some.mod.C.GND[0])
val N = get-ref-name(A)
println("N: %_" % [N])

; Will Print:
; N: GND[0]

val B = #R(some.other.C.VDD)
val N2 = get-ref-name(B)
println("N2: %_" % [N2])

; Will Print:
; N2: VDD

get-component-from-port¶

Get a component instance from a Port

public defn get-component-from-port (pt:JITXObject, cxt:JITXObject = ?) -> Maybe<JITXObject>

pt: JITXObject - Port on a component instance.
cxt: JITXObject - Context to search for components in.
Returns Maybe<JITXObject> - If we successfully, determine the parent component, this returns a reference to that component as a JITXObject. If not, we return None().
Throws ValueError - If the user passes a port on a module or we can't determine if this is a component context.

This function can be called from a pcb-module context. Calling from a pcb-component context will likely result in an exception.

get-instance-by-ref¶

Retrieve an Instance from a particular context by Ref

public defn get-instance-by-ref (r:Ref, cxt:JITXObject = ?) -> Maybe<JITXObject>

r: Ref - Ref to an object in cxt - Note that the path must be referenced from the cxt. Any prefix in the ref before cxt will likely result in a failure to find the instance. Notice that for the self context, then we can just pass references without the self. prefix.
cxt: JITXObject - Context from which we will query the instances. By default this value is self.
Returns Maybe<JITXObject> - An instance from the cxt context. Note that this could be either a pcb-module or a pcb-component instance.

This function must be called from within a pcb-module context.

This function is not recursive. If the caller passes some.obj from the cxt context, then that object will not be found because obj is within the some object context, not cxt. This function could find cxt.some if passed some.