DFBlock

DFBlock describes a hardware module within a system with the ports, children, registers, address map, and interconnectivity all captured. Blocks are completely instantiated within the description - while different instances can refer to a common type, no work needs to be done to elaborate the design at runtime. This choice of making the stored design more verbose was deliberate, as it makes the JSON description easier for a human to read and modify without constantly referencing inherited descriptions.

As with every tag, DFBlock inherits from DFBase, so has support for all of the core attributes (id, description, and attributes).

{
    "id": "my_block",
    "description": "Free-form description",
    "attributes": { },
    "path": "the_root.child_a.my_block",
    "parent": "the_root.child_a",
    "type": "an_engine",
    "ports": {
        "input": [ ],
        "output": [ ],
        "inout": [ ]
    },
    "children": [ ],
    "connections": [ ],
    "registers": [ ],
    "address_map": { }
}

Property	Usage
path	Hierarchical path to where this block is located in the design
parent	Hierarchical path to the parent block, resolved during reload to a pointer
type	Type of the block, this is just a string
ports.input	A list of this block's input DFPort objects
ports.output	A list of this block's output DFPort objects
ports.inout	A list of this block's bidirectional DFPort objects
children	A list of the this block's children as DFBlock objects
connections	A list of DFConnection objects describing interconnectivity
registers	A list of DFRegisterGroup objects describing this block's registers
address_map	An instance of DFAddressMap describing address relationship between boundary IO ports

DesignFormat has a concept of ‘principal’ ports, which allows one input port of a certain type to be nominated as the default connection point. One example use case for this is nominating the main clock and reset ports of a block, which can then be used by other tools to determine the main clocking structure. Only one input port of each type (e.g. where type is set to ‘clock’, or ‘reset’, etc.) can be nominated as a principal at any time - but you can have as many different principal types active as required.

Principal ports are identified by having an attribute of PRINCIPAL set to true in their attributes dictionary - for example (see DFPort for further details):

{
    "id": "my_block",
    "ports": {
        "input": [
            {
                "id": "my_block[clk]",
                "name": "clk",
                "type": "clock",
                "attributes": { "PRINCIPAL": true }
            }
        ]
    }
}

Python API

class designformat.block.DFBlock(id=None, type=None, parent=None, description=None, address_map=None)

DesignFormat representation of a system block

__getattribute__(key)

By overriding __getattribute__ we can expose any child blocks or registers as if they were first class attributes of this object. Note that the code prioritises true class properties.

Parameters

key – The key to resolve

__init__(id=None, type=None, parent=None, description=None, address_map=None)

Construct the block instance

Parameters

• id – Instance identifier for this block

• type – The module type (i.e. not the instantiation name)

• parent – Pointer to the parent node of this block either a DFBlock or a DFProject

• description – Human-readable description of the object

• address_map – Address map to associate

addChild(child)

Attach a DFBlock to this block as a child node

Parameters

child – The child to attach

addConnection(start_port, start_index, end_port, end_index)

Create a connection between two ports - specifying which signal within each port is part of the connection (for ports with count > 1).

Parameters

• start_port – The port driving the connection

• start_index – Signal index within the driver port

• end_port – The port being driven by the connection

• end_index – Signal index within the driven port

addPort(port)

Attach a new port to this block (can be input, output, or bidirectional)

Parameters

port – The port to attach

addRegister(register)

Attach a DFRegisterGroup to this block

Parameters

register – The register group to attach

addTieOff(port, signal_index, constant)

Create a connection between a port and a constant, specifying which signal within the port is part of the connection (for ports with count > 1)

Parameters

• port – The port to drive

• signal_index – The signal index within the port to drive

• constant – The constant value to drive onto the port

dumpObject(project)

Dump out this node so that it can be reloaded

Parameters

project – Project definition used to calculate references

getAllPorts()

Return a concatenated list of all of the ports on the block

getChildTypes(depth=None)

Return a list of all of the types of the child modules. You can limit the depth of the query using the ‘depth’ parameter, not passing the value will return unlimited depth.

Parameters

depth – How deep to retrieve (whether to query children)

getInterconnectTypes(depth=None)

Return a list of all of the connection types used in this hierarchy. You can limit the depth of the query using the ‘depth’ parameter, not passing the value will return unlimited depth.

Parameters

- How deep to retrieve (depth) –

getPrincipalSignal(intc_type)

Get the principal signal (input port or child output port) for a particular interconnect type.

Parameters

intc_type – The interconnect to resolve

getProject()

Resolves the root block of the design, and then gets its parent DFProject

getRelativeAddress(remote, remote_index=0)

Use the ports and address map of this block to work out the relative address needed to access a specified remote point. If the remote point is a port, we just need to iterate through our outputs. If the remote point is a block then we need to iterate through our outputs and their inputs.

Parameters

• remote – Either a DFBlock or a DFPort to find the address of

• remote_index – If the remote is a DFPort, this is used as the signal index.

getRootBlock()

Returns the root block of the design (stopping before the DFProject)

getUnconnectedChildPorts()

Return a list of all ports on child modules that are not connected within this block

getUnconnectedPorts()

Return a list of all ports on this block that are not internally connected

hierarchicalPath()

Returns the full hierarchical path to this block from the root

loadObject(obj, root=None)

Reload this node from passed in object.

Parameters

• obj – Description of this node

• root – Root object in the tree

• types – Map from class name to class definition

resolvePath(path)

Return a DFPort or DFBlock definition based on a hierarchical path

Parameters

path – The path to resolve

setAddressMap(map)

Set the address map for this block. The address map models how initiator and target ports on the block are linked.

Parameters

map – The address map

setPrincipalSignal(port)

Nominate an input port or child output port as the principal signal for a particular interconnect type (e.g. the main clock signal for a block is the ‘principal’ clock).

Parameters

port – The port to nominate as principal

Javascript API

class DFBlock(id, type, parent, description, address_map)

DesignFormat representation of a system block

Construct the block instance

Arguments

• id (string) – Instance identifier for this block

• type (string) – The module type (i.e. not the instantiation name)

• parent (DFBase) – Pointer to the parent node of this block either a DFBlock or a DFProject

• description (string) – Human-readable description of the object

• address_map (DFAddressMap) – Address map to associate

DFBlock.addChild(child)

Attach a DFBlock to this block as a child node

Arguments

• child (DFBlock) – The child to attach

DFBlock.addConnection(start_port, start_index, end_port, end_index)

Create a connection between two ports - specifying which signal within each port is part of the connection (for ports with count > 1).

Arguments

• start_port (DFPort) – The port driving the connection

• start_index (DFPort) – Signal index within the driver port

• end_port (integer) – The port being driven by the connection

• end_index (integer) – Signal index within the driven port

DFBlock.addPort(port)

Attach a new port to this block (can be input, output, or bidirectional)

Arguments

• port (DFPort) – The port to attach

DFBlock.addRegister(register)

Attach a DFRegisterGroup to this block

Arguments

• register (DFRegisterGroup) – The register group to attach

DFBlock.addTieOff(port, signal_index, constant)

Create a connection between a port and a constant, specifying which signal within the port is part of the connection (for ports with count > 1)

Arguments

• port (DFPort) – The port to drive

• signal_index (integer) – The signal index within the port to drive

• constant (DFConstantTie) – The constant value to drive onto the port

DFBlock.dumpObject(project)

Dump out this node so that it can be reloaded

Arguments

• project (DFProject) – Project definition used to calculate references

DFBlock.getAllPorts()

Return a concatenated list of all of the ports on the block

DFBlock.getChildTypes(depth)

Return a list of all of the types of the child modules. You can limit the depth of the query using the ‘depth’ parameter, not passing the value will return unlimited depth.

Arguments

• depth (integer) – How deep to retrieve (whether to query children)

DFBlock.getInterconnectTypes(depth)

Return a list of all of the connection types used in this hierarchy. You can limit the depth of the query using the ‘depth’ parameter, not passing the value will return unlimited depth.

Arguments

• depth (integer) – How deep to retrieve (whether to query children)

DFBlock.getPrincipalSignal(intc_type)

Get the principal signal (input port or child output port) for a particular interconnect type.

Arguments

• intc_type (DFInterconnect) – The interconnect to resolve

DFBlock.getProject()

Resolves the root block of the design, and then gets its parent DFProject

DFBlock.getRelativeAddress(remote, remote_index)

Use the ports and address map of this block to work out the relative address needed to access a specified remote point. If the remote point is a port, we just need to iterate through our outputs. If the remote point is a block then we need to iterate through our outputs and their inputs.

Arguments

• remote (DFBase) – Either a DFBlock or a DFPort to find the address of

• remote_index (integer) – If the remote is a DFPort, this is used as the signal index.

DFBlock.getRootBlock()

Returns the root block of the design (stopping before the DFProject)

DFBlock.getUnconnectedChildPorts()

Return a list of all ports on child modules that are not connected within this block

DFBlock.getUnconnectedPorts()

Return a list of all ports on this block that are not internally connected

DFBlock.hierarchicalPath()

Returns the full hierarchical path to this block from the root

DFBlock.loadObject(obj, root, types)

Reload this node from passed in object.

Arguments

• obj (object) – Description of this node

• root (DFBase) – Root object in the tree

• types (object) – Map from class name to class definition

DFBlock.resolvePath(path)

Return a DFPort or DFBlock definition based on a hierarchical path

Arguments

• path (*) – The path to resolve

DFBlock.setAddressMap(map)

Set the address map for this block. The address map models how initiator and target ports on the block are linked.

Arguments

• map (DFAddressMap) – The address map

DFBlock.setPrincipalSignal(port)

Nominate an input port or child output port as the principal signal for a particular interconnect type (e.g. the main clock signal for a block is the ‘principal’ clock).

Arguments

• port (DFPort) – The port to nominate as principal