PYNQ Metadata

https://github.com/xilinx/pynq-metadata
Admin
PYNQ Metadata is an open-source library that provides an abstract description of reconfigurable...
Tokens:7,687
Snippets:66
Trust Score:9.3
License:BSD-3-Clause
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install PYNQ-Metadata

Source: https://github.com/xilinx/pynq-metadata/blob/main/README.md

Command to install the pynqmetadata package via pip.

```bash
python3 -m pip install pynqmetadata
```

--------------------------------

### Install jsonschema

Source: https://github.com/xilinx/pynq-metadata/blob/main/docs/temp.md

Install the jsonschema package, which is a requirement for the pynq-metadata validation tools.

```bash
pip install jsonschema
```

--------------------------------

### Parse Hardware Designs

Source: https://github.com/xilinx/pynq-metadata/blob/main/README.md

Initialize the Metadata object using different supported file formats.

```python
from pynqmetadata.frontends import Metadata
md = Metadata('xsa_file.xsa')
md = Metadata('hwh_file.hwh')
md = Metadata('pynq_metadata_json_file.json')
```

--------------------------------

### Access hierarchy by path

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Navigate design hierarchies and inspect cores, sub-hierarchies, and partial reconfiguration regions.

```python
hierarchy = md.hierarchy("processing_system/axi_interconnect")

# Explore cores in hierarchy
for core_ref in hierarchy.core_ref:
    print(f"Core in hierarchy: {core_ref}")

# Check for sub-hierarchies
for hier_ref in hierarchy.hierarchies_ref:
    print(f"Sub-hierarchy: {hier_ref}")

# Check if it's a PR region
if hierarchy.pr_region:
    print("This is a partial reconfiguration region")
```

--------------------------------

### Working with IP Core Parameters

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Access and inspect IP core configuration parameters. Custom parameters can be added, and their existence can be checked.

```python
from pynqmetadata.frontends import Metadata
from pynqmetadata.models import Parameter

md = Metadata('design.hwh')

# Access parameters of an IP core
dma = md.lookup("axi_dma_0[block]")

print(f"Parameters for {dma.name}:")
for param_name, param in dma.parameters.items():
    print(f"  {param_name} = {param.value}")

# Add a custom parameter
new_param = Parameter(name="CUSTOM_PARAM", value="custom_value")
dma.add(new_param)

# Check if parameter exists
if dma.exists(new_param):
    print(f"Parameter {new_param.name} added successfully")
```

--------------------------------

### HwhFrontend - Direct HWH File Parsing

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Specialized frontend for parsing Vivado HWH (Hardware Handoff) files directly. Provides lower-level access and additional parsing options.

```APIDOC
## HwhFrontend - Direct HWH File Parsing

### Description
Specialized frontend for parsing Vivado HWH (Hardware Handoff) files directly. Provides lower-level access and additional parsing options.

### Method
Instantiate the HwhFrontend class with the path to the HWH file.

### Endpoint
N/A (Python library)

### Parameters
#### Path Parameters
- **_hwhfile** (string) - Required - Path to the HWH file.

### Request Example
```python
from pynqmetadata.frontends import HwhFrontend

# Parse HWH file directly
md = HwhFrontend(_hwhfile="resizer.hwh")

# Access design name
print(f"System name: {md.name}")

# Iterate over all IP blocks
for block in md.blocks.values():
    print(f"IP: {block.name}")
    if hasattr(block, 'vlnv') and block.vlnv:
        print(f"  VLNV: {block.vlnv.vendor}:{block.vlnv.library}:{block.vlnv.name}")

    # List ports for each block
    for port_name, port in block.ports.items():
        print(f"  Port: {port_name} ({port.type})")
```

### Response
#### Success Response (MetadataObject)
- **name** (string) - The name of the system.
- **blocks** (dict) - A dictionary of IP blocks in the design.
  - **vlnv** (object) - Vendor, Library, Name, Version of the IP core.
  - **ports** (dict) - Dictionary of ports for the IP block.
    - **type** (string) - Type of the port (e.g., 'port-manager', 'slave', 'master').

#### Response Example
```
System name: resizer
IP: axi_gpio_0
  VLNV: xilinx.com:ip:axi_gpio:2.0
  Port: GPIO_0 (port-manager)
  Port: S_AXI (slave)
IP: axi_timer_0
  VLNV: xilinx.com:ip:axi_timer:2.0
  Port: S_AXI (slave)
  Port: SLAVE0 (slave)
...
```
```

--------------------------------

### Parsing Hardware Designs with Metadata

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

The primary entry point for parsing hardware designs. Accepts HWH, XSA, or JSON files and returns a MetadataObject representing the complete system design.

```APIDOC
## Parsing Hardware Designs with Metadata

### Description
The primary entry point for parsing hardware designs. Accepts HWH, XSA, or JSON files and returns a MetadataObject representing the complete system design.

### Method
Instantiate the Metadata class with the path to the hardware design file.

### Endpoint
N/A (Python library)

### Parameters
#### Path Parameters
- **file_path** (string) - Required - Path to the HWH, XSA, or JSON metadata file.

### Request Example
```python
from pynqmetadata.frontends import Metadata

# Parse from HWH file (Vivado hardware handoff)
md = Metadata('design.hwh')

# Parse from XSA file (Vitis/Vivado export archive)
md = Metadata('design.xsa')

# Parse from previously exported JSON metadata
md = Metadata('design_metadata.json')

# Access basic design properties
print(f"Design name: {md.name}")
print(f"Number of blocks: {len(md.blocks)}")

# List all IP cores in the design
for block_name, block in md.blocks.items():
    print(f"Block: {block_name}, Type: {block.type}")
```

### Response
#### Success Response (MetadataObject)
- **name** (string) - The name of the design.
- **blocks** (dict) - A dictionary of IP blocks in the design.

#### Response Example
```python
# Example output from print statements in the code example
Design name: design_name
Number of blocks: 15
Block: axi_gpio_0, Type: ip
Block: axi_timer_0, Type: ip
...
```
```

--------------------------------

### Generate PYNQ runtime metadata views

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Create runtime-compatible views for IP dictionaries, GPIO, and interrupts using the RuntimeMetadataParser.

```python
from pynqmetadata.frontends import Metadata
from pynqmetadata.views.runtime import RuntimeMetadataParser

md = Metadata('design.hwh')

# Create runtime parser
runtime = RuntimeMetadataParser(md)

# Access IP dictionary (memory-mapped peripherals)
print("IP Dictionary:")
for ip_name, ip_info in runtime.ip_dict.items():
    print(f"  {ip_name}:")
    print(f"    Physical Address: 0x{ip_info.get('phys_addr', 0):08X}")
    print(f"    Address Range: 0x{ip_info.get('addr_range', 0):X}")

# Access GPIO dictionary
print("\nGPIO Dictionary:")
for gpio_name, gpio_info in runtime.gpio_dict.items():
    print(f"  {gpio_name}: pins={gpio_info['pins']}")

# Access interrupt controllers
print("\nInterrupt Controllers:")
for ctrl_name, ctrl_info in runtime.interrupt_controllers.items():
    print(f"  {ctrl_name}")
```

--------------------------------

### Search Metadata with Lookup

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Navigate the metadata tree using colon-separated reference paths for blocks, ports, and signals.

```python
from pynqmetadata.frontends import Metadata

md = Metadata('design.hwh')

# Lookup an IP block by name
dma = md.lookup("axi_dma_0[block]")
print(f"Found DMA core: {dma.name}")

# Lookup a port within a block
saxi_port = md.lookup("axi_dma_0[block]:S_AXI_LITE[port]")
print(f"Port base address: {saxi_port.baseaddr}")

# Lookup a signal within a port
bvalid_signal = md.lookup("axi_dma_0[block]:S_AXI_LITE[port]:BVALID[signal]")
print(f"Signal width: {bvalid_signal.width}")
print(f"Signal is driver: {bvalid_signal.driver}")

# Chain lookups from intermediate objects
port = dma.lookup("S_AXI_LITE[port]")
signal = port.lookup("BVALID[signal]")

# Get signal connections
for ref, connected_signal in signal.connections().items():
    print(f"Connected to: {ref}")
```

--------------------------------

### Working with Processing Systems

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Access the Zynq/Ultrascale+ processing system blocks in a design, which serve as the primary manager for memory-mapped peripherals.

```APIDOC
## Working with Processing Systems

### Description
Access the Zynq/Ultrascale+ processing system blocks in a design, which serve as the primary manager for memory-mapped peripherals.

### Method
Use the `get_processing_systems()` method on a MetadataObject.

### Endpoint
N/A (Python library)

### Parameters
None

### Request Example
```python
from pynqmetadata.frontends import Metadata

md = Metadata('design.hwh')

# Get all processing system blocks
ps_blocks = md.get_processing_systems()

for ps_name, ps in ps_blocks.items():
    print(f"Processing System: {ps_name}")
    print(f"  Type: {ps.type}")
    print(f"  Hierarchy: {ps.hierarchy_name}")

    # Access PS ports (manager ports for memory-mapped access)
    for port_name, port in ps.ports.items():
        if port.type == "port-manager":
            print(f"  Manager Port: {port_name}")
            # List address mappings
            for target_ref, addr_info in port.addrmap.items():
                print(f"    -> {addr_info['subord_port']}")
```

### Response
#### Success Response (dict)
A dictionary where keys are processing system names and values are ProcessingSystem objects.
- **name** (string) - The name of the processing system.
- **type** (string) - The type of the processing system (e.g., 'ps7', 'psu').
- **hierarchy_name** (string) - The hierarchical name of the processing system.
- **ports** (dict) - Dictionary of ports for the processing system.
  - **type** (string) - Type of the port.
  - **addrmap** (dict) - Address mapping information for manager ports.

#### Response Example
```
Processing System: ps7_0
  Type: ps7
  Hierarchy: ps7_0
  Manager Port: S_AXI_HP0
    -> S_AXI_HP0
  Manager Port: S_AXI_GP0
    -> S_AXI_GP0
...
```
```

--------------------------------

### Parse Hardware Designs with Metadata

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

The primary entry point for loading hardware designs from HWH, XSA, or JSON files into a MetadataObject.

```python
from pynqmetadata.frontends import Metadata

# Parse from HWH file (Vivado hardware handoff)
md = Metadata('design.hwh')

# Parse from XSA file (Vitis/Vivado export archive)
md = Metadata('design.xsa')

# Parse from previously exported JSON metadata
md = Metadata('design_metadata.json')

# Access basic design properties
print(f"Design name: {md.name}")
print(f"Number of blocks: {len(md.blocks)}")

# List all IP cores in the design
for block_name, block in md.blocks.items():
    print(f"Block: {block_name}, Type: {block.type}")
```

--------------------------------

### Serialize Metadata with JSON

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Export hardware design metadata to JSON files or strings, and reimport them for persistence.

```python
from pynqmetadata.frontends import Metadata
import json

# Load hardware design
md = Metadata('design.hwh')

# Export to JSON file
md.export(path='design_metadata.json')

# Get JSON string representation
json_str = md.json()

# Get dictionary representation
design_dict = md.dict()
print(json.dumps(design_dict, indent=2))

# Later, reimport from the exported JSON
md_reloaded = Metadata('design_metadata.json')

# Verify equivalence
assert md.dict() == md_reloaded.dict()
```

--------------------------------

### Hierarchy Navigation

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Navigate and inspect the hierarchical organization of IP cores in the design.

```APIDOC
## Hierarchy Navigation

### Description
Navigate and inspect the hierarchical organization of IP cores in the design.

### Method
Use the `refresh()` method to ensure hierarchies are populated, then navigate using object attributes and the `lookup()` method.

### Endpoint
N/A (Python library)

### Parameters
None

### Request Example
```python
from pynqmetadata.frontends import Metadata

md = Metadata('design.hwh')

# Refresh to ensure hierarchies are populated
md.refresh()

# Example: Accessing a block within a hierarchy (assuming a hierarchical structure)
# If 'my_pmod' is a hierarchical block containing 'axi_gpio_1'
# You might access it like this:
# hierarchical_block = md.lookup('my_pmod[block]')
# gpio_instance = hierarchical_block.lookup('axi_gpio_1[block]')
# print(f"Found GPIO in hierarchy: {gpio_instance.name}")

# The structure of hierarchy is reflected in the 'blocks' dictionary and can be traversed.
# For detailed hierarchy inspection, refer to the object model documentation.
```

### Response
#### Success Response (Object Navigation)
Allows traversal of the design's hierarchical structure.

#### Response Example
```
# Example output if the hierarchy navigation is successful
Found GPIO in hierarchy: axi_gpio_1
```
```

--------------------------------

### Run All Python Tests

Source: https://github.com/xilinx/pynq-metadata/blob/main/docs/temp.md

Execute all Python tests for the pynq-metadata project using pytest. This command should be run from the project's root directory.

```bash
python3 -m pytest
```

--------------------------------

### Inspect signal connectivity

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Trace signal-level connections between IP core ports.

```python
from pynqmetadata.frontends import Metadata

md = Metadata('design.hwh')

# Get a block and examine signal connections
dma = md.lookup("axi_dma_0[block]")

for port_name, port in dma.ports.items():
    print(f"Port: {port_name}")

    # Get port-level destinations
    destinations = port.destinations()
    for dest_name, dest_port in destinations.items():
        print(f"  Connected to port: {dest_name}")

    # Examine individual signals
    for sig_name, signal in port.signals.items():
        if signal.connections():
            print(f"  Signal {sig_name} (width={signal.width}, driver={signal.driver}):")
            for conn_ref, conn_signal in signal.connections().items():
                print(f"    -> {conn_ref}")
```

--------------------------------

### Parse HWH Files with HwhFrontend

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Specialized frontend for direct HWH file parsing, offering lower-level access to IP blocks and their ports.

```python
from pynqmetadata.frontends import HwhFrontend

# Parse HWH file directly
md = HwhFrontend(_hwhfile="resizer.hwh")

# Access design name
print(f"System name: {md.name}")

# Iterate over all IP blocks
for block in md.blocks.values():
    print(f"IP: {block.name}")
    if hasattr(block, 'vlnv') and block.vlnv:
        print(f"  VLNV: {block.vlnv.vendor}:{block.vlnv.library}:{block.vlnv.name}")

    # List ports for each block
    for port_name, port in block.ports.items():
        print(f"  Port: {port_name} ({port.type})")
```

--------------------------------

### Dynamically add and remove cores

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Modify the design structure by instantiating new IP cores and removing existing ones.

```python
from pynqmetadata.frontends import Metadata
from pynqmetadata.models import IPCore, Port, Signal
from pynqmetadata.models.vlnv import Vlnv

md = Metadata('design.hwh')

# Create a new IP core
vlnv = Vlnv(vendor="xilinx.com", library="ip", name="axi_gpio", version=(2, 0))
new_core = IPCore(name="my_gpio", vlnv=vlnv, hierarchy_name="my_gpio")

# Add a port to the core
gpio_port = Port(name="GPIO")
gpio_port.add(Signal(name="gpio_io", width=32, driver=True))
new_core.add(gpio_port)

# Add the core to the design
md.add(new_core)
md.refresh()

print(f"Added core: {new_core.name}")

# Remove a core from the design
core_to_remove = md.lookup("my_gpio[block]")
core_to_remove.remove()

print("Core removed")
```

--------------------------------

### Deep Copy and Comparison of Metadata Objects

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Create independent deep copies of metadata objects and compare designs or specific components. Modifications to a copy do not affect the original.

```python
from pynqmetadata.frontends import Metadata

md1 = Metadata('design.hwh')

# Create a deep copy
md2 = md1.copy()

# Modify the copy
block = md2.lookup("axi_dma_0[block]")
block.remove()

# Compare designs
if md1.dict() != md2.dict():
    print("Designs are different after modification")

# Compare specific objects
block1 = md1.lookup("axi_gpio_0[block]")
block1_copy = block1.copy()

if block1 == block1_copy:
    print("Block copies are equal")
```

--------------------------------

### Navigate Design Hierarchies

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Refresh the metadata object to ensure hierarchical structures are correctly populated for inspection.

```python
from pynqmetadata.frontends import Metadata

md = Metadata('design.hwh')

# Refresh to ensure hierarchies are populated
md.refresh()
```

--------------------------------

### Access Processing Systems

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Retrieve and inspect processing system blocks and their memory-mapped peripheral address mappings.

```python
from pynqmetadata.frontends import Metadata

md = Metadata('design.hwh')

# Get all processing system blocks
ps_blocks = md.get_processing_systems()

for ps_name, ps in ps_blocks.items():
    print(f"Processing System: {ps_name}")
    print(f"  Type: {ps.type}")
    print(f"  Hierarchy: {ps.hierarchy_name}")

    # Access PS ports (manager ports for memory-mapped access)
    for port_name, port in ps.ports.items():
        if port.type == "port-manager":
            print(f"  Manager Port: {port_name}")
            # List address mappings
            for target_ref, addr_info in port.addrmap.items():
                print(f"    -> {addr_info['subord_port']}")
```

--------------------------------

### Check Metadata File with pmdcheck

Source: https://github.com/xilinx/pynq-metadata/blob/main/docs/temp.md

Use the pmdcheck tool to validate a .pmd metadata file against its schema. This can be done by piping the file content to the tool or by specifying the input file directly.

```bash
cat metadata_file.pmd | pmdcheck
```

```bash
pmdcheck --input metadata_file.pmd
```

--------------------------------

### Access ManagerPort address mapping

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Inspect master ports to determine their address mappings to subordinate peripherals.

```python
from pynqmetadata.frontends import Metadata
from pynqmetadata.models import ManagerPort

md = Metadata('design.hwh')

# Access manager ports and their address maps
for block in md.blocks.values():
    for port_name, port in block.ports.items():
        if isinstance(port, ManagerPort):
            print(f"Manager Port: {block.name}/{port_name}")

            # List all addressable targets
            for subord_ref, mapping in port.addrmap.items():
                print(f"  Target: {mapping['subord_port']}")
                print(f"    Block: {mapping['block']}")
                print(f"    Memory Type: {mapping['memtype']}")
```

--------------------------------

### Accessing Runtime Metadata

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Iterate through interrupt pins, clock dictionaries, memory regions, and hierarchy dictionaries available in the runtime metadata.

```python
print("\nInterrupt Pins:")
for pin_name, pin_info in runtime.interrupt_pins.items():
    print(f"  {pin_name}: controller={pin_info.get('controller')}")

# Access clock dictionary
print("\nClock Dictionary:")
for clk_name, clk_info in runtime.clock_dict.items():
    print(f"  {clk_name}: {clk_info}")

# Access memory regions
print("\nMemory Dictionary:")
for mem_name, mem_info in runtime.mem_dict.items():
    print(f"  {mem_name}")

# Access hierarchy dictionary
print("\nHierarchy Dictionary:")
for hier_name, hier_info in runtime.hierarchy_dict.items():
    print(f"  {hier_name}")
```

--------------------------------

### Export and Import - JSON Serialization

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Export metadata to JSON format for persistence or modification, and reimport from JSON files or strings.

```APIDOC
## Export and Import - JSON Serialization

### Description
Export metadata to JSON format for persistence or modification, and reimport from JSON files or strings.

### Method
Use the `export()` method to save to a file, `json()` to get a JSON string, `dict()` to get a dictionary representation, and instantiate `Metadata` with a JSON file path to reimport.

### Endpoint
N/A (Python library)

### Parameters
#### Path Parameters
- **path** (string) - Optional - Path to the JSON file for export.

### Request Example
```python
from pynqmetadata.frontends import Metadata
import json

# Load hardware design
md = Metadata('design.hwh')

# Export to JSON file
md.export(path='design_metadata.json')

# Get JSON string representation
json_str = md.json()

# Get dictionary representation
design_dict = md.dict()
print(json.dumps(design_dict, indent=2))

# Later, reimport from the exported JSON
md_reloaded = Metadata('design_metadata.json')

# Verify equivalence
assert md.dict() == md_reloaded.dict()
```

### Response
#### Success Response (JSON/Dictionary/File)
- **export()**: Saves the metadata to a JSON file.
- **json()**: Returns a JSON string representation of the metadata.
- **dict()**: Returns a Python dictionary representation of the metadata.
- **Metadata(json_file_path)**: Loads metadata from a JSON file.

#### Response Example
```json
{
  "name": "design_name",
  "blocks": {
    "axi_gpio_0": {
      "name": "axi_gpio_0",
      "type": "ip",
      "ports": { ... }
    },
    ...
  }
}
```
```

--------------------------------

### Run Python Metadata Object Tests

Source: https://github.com/xilinx/pynq-metadata/blob/main/docs/temp.md

Execute only the tests for the Python metadata object classes using pytest. This command targets the python directory within the tests.

```bash
python3 -m pytest pynqmetadata/tests/python
```

--------------------------------

### Run Python Metadata Validation Tests

Source: https://github.com/xilinx/pynq-metadata/blob/main/docs/temp.md

Run only the tests related to metadata validation with the schema using pytest. This command targets the validation directory within the tests.

```bash
python3 -m pytest pynqmetadata/tests/validation
```

--------------------------------

### Lookup - Hierarchical Object Search

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Navigate through the metadata object tree using colon-separated reference paths. Supports case-insensitive lookups for blocks, ports, and signals.

```APIDOC
## Lookup - Hierarchical Object Search

### Description
Navigate through the metadata object tree using colon-separated reference paths. Supports case-insensitive lookups for blocks, ports, and signals.

### Method
Use the `lookup()` method on a MetadataObject, Block, Port, or Signal object.

### Endpoint
N/A (Python library)

### Parameters
#### Path Parameters
- **reference_path** (string) - Required - A colon-separated path to the desired object (e.g., "axi_dma_0[block]:S_AXI_LITE[port]:BVALID[signal]").

### Request Example
```python
from pynqmetadata.frontends import Metadata

md = Metadata('design.hwh')

# Lookup an IP block by name
dma = md.lookup("axi_dma_0[block]")
print(f"Found DMA core: {dma.name}")

# Lookup a port within a block
saxi_port = md.lookup("axi_dma_0[block]:S_AXI_LITE[port]")
print(f"Port base address: {saxi_port.baseaddr}")

# Lookup a signal within a port
bvalid_signal = md.lookup("axi_dma_0[block]:S_AXI_LITE[port]:BVALID[signal]")
print(f"Signal width: {bvalid_signal.width}")
print(f"Signal is driver: {bvalid_signal.driver}")

# Chain lookups from intermediate objects
port = dma.lookup("S_AXI_LITE[port]")
signal = port.lookup("BVALID[signal]")

# Get signal connections
for ref, connected_signal in signal.connections().items():
    print(f"Connected to: {ref}")
```

### Response
#### Success Response (Object)
Returns the requested object (Block, Port, or Signal) based on the reference path.
- **name** (string) - The name of the object.
- **baseaddr** (integer) - The base address (for ports).
- **width** (integer) - The width of the signal.
- **driver** (boolean) - Indicates if the signal is a driver.
- **connections** (dict) - A dictionary of connected signals.

#### Response Example
```
Found DMA core: axi_dma_0
Port base address: 0x40400000
Signal width: 1
Signal is driver: True
Connected to: axi_dma_0[block]:S_AXI_LITE[port]:BVALID[signal]
```
```

--------------------------------

### Access SubordinatePort memory-mapped peripherals

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Retrieve base addresses, address ranges, register maps, and bitfield definitions for slave ports.

```python
from pynqmetadata.frontends import Metadata
from pynqmetadata.models import SubordinatePort

md = Metadata('design.hwh')

# Find all subordinate ports in the design
for block in md.blocks.values():
    for port_name, port in block.ports.items():
        if isinstance(port, SubordinatePort):
            print(f"Subordinate Port: {block.name}/{port_name}")
            print(f"  Base Address: 0x{port.baseaddr:08X}")
            print(f"  Range: 0x{port.range:X} bytes")

            # Access register map
            for reg_name, register in port.registers.items():
                print(f"  Register: {reg_name}")
                print(f"    Offset: 0x{register.offset:X}")
                print(f"    Width: {register.width} bits")
                print(f"    Access: {register.access}")

                # Access bitfields
                for field_name, bitfield in register.bitfields.items():
                    print(f"    Field: {field_name} [{bitfield.MSB}:{bitfield.LSB}]")
```

--------------------------------

### Merging Metadata Objects

Source: https://context7.com/xilinx/pynq-metadata/llms.txt

Merge multiple metadata objects, useful for combining partial designs or BDC contents. Options are available to skip external port checks, inherit signal widths, and inherit address information.

```python
from pynqmetadata.frontends import Metadata, HwhFrontend

# Load main design
md_main = Metadata('main_design.hwh')

# Load secondary design to merge
md_secondary = HwhFrontend(_hwhfile='partial_design.hwh')

# Find matching block to merge into
for block_name, block in md_main.blocks.items():
    if block.name == md_secondary.name:
        # Merge with options
        block.merge(
            md_secondary,
            skip_external=True,        # Skip external port conflict checks
            inherit_signal_width=True, # Use incoming signal widths
            inherit_addr_info=True     # Use incoming address info
        )
        break

# Refresh the design after merge
md_main.refresh()

print("Designs merged successfully")
```
Tokens:
Raw