ChipScoPy

https://xilinx.github.io/chipscopy/2026.1/
Admin
ChipScoPy is an open-source Python library from AMD Xilinx that enables high-level communication...
Tokens:161,633
Snippets:1,235
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Start Hardware and ChipScope Servers

Source: https://xilinx.github.io/chipscopy/2026.1/chipscopy_installation.html

Commands to initialize the hardware and chipscope servers required for running examples.

```bash
hw_server
```

```bash
cs_server
```

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

### Initialize MESA Example Design

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

Use resolve_example_design to abstract hardware setup. Set PROGRAMMING_FILE and PROBES_FILE to empty strings to enable MESA mode.

```python
import os
from chipscopy import create_session, delete_session
from chipscopy.examples.mesa import resolve_example_design

CS_URL = os.getenv("CS_SERVER_URL", "TCP:localhost:3042")
HW_URL = os.getenv("HW_SERVER_URL", "TCP:localhost:3121")
HW_PLATFORM = "vck190"
EXAMPLE_ID = "ila_and_vio"

PROGRAMMING_FILE = ""  # Direct mode: set to your own PDI to skip MESA
PROBES_FILE = ""

example_design = resolve_example_design(
    HW_PLATFORM,
    EXAMPLE_ID,
    programming_file=PROGRAMMING_FILE,
    probes_file=PROBES_FILE,
)
example_design.print_summary()

session = create_session(cs_server_url=CS_URL, hw_server_url=HW_URL)
device = session.devices.filter_by(family=example_design.device_family).get()

if not example_design.verify_device_idcode(device):
    raise RuntimeError("Device IDCODE does not match the manifest design.")

example_design.program_device(device)
device.discover_and_setup_cores(ltx_file=example_design.probes_file)

# ... your example logic here ...

delete_session(session)
```

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

### Check Example Support

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Determines if the manifest supports a specific example ID.

```python
def supports_example(self, example_id: str) -> bool:
    """Check if this manifest supports a specific example."""
    return example_id in self.supported_examples
```

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

### Update ChipScoPy Examples

Source: https://xilinx.github.io/chipscopy/2026.1/chipscopy_installation.html

Run this command within the virtual environment to extract the latest available examples.

```bash
(venv) > chipscopy-get-examples
```

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

### Extract ChipScoPy Examples

Source: https://xilinx.github.io/chipscopy/2026.1/chipscopy_installation.html

Command to extract example scripts and notebooks to a user-specified directory.

```bash
(venv) > chipscopy-get-examples

The following examples  will be delivered to `/home/user/chipscopy-examples`:
- ddr_example.ipynb
- ddr_example.py
- basic_detect.py
...
```

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

### Resolve Example Design with MESA

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Demonstrates how to resolve an example design using either the manifest-driven MESA mode or by providing direct file paths.

```python
from chipscopy.examples.mesa import resolve_example_design

# MESA mode (uses manifests):
example_design = resolve_example_design("vck190", "ddr_example")

# Direct mode (user-supplied files, no manifest required):
example_design = resolve_example_design(
    "vck190", "ddr_example",
    programming_file="/path/to/my.pdi",
    probes_file="/path/to/my.ltx",
)

if not example_design.verify_device_idcode(device):
    raise RuntimeError("Device IDCODE does not match the manifest design.")
example_design.program_device(device)
```

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

### Example manifest.json structure

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

A sample manifest file defining design information, debug cores, and supported examples.

```json
{
  "extends": "_base/versal_standard_cores.json",
  "design_info": {
    "design_name": "chipscopy_ced",
    "description": "ChipScoPy CED for VCK190",
    "hw_platform": "vck190",
    "programming_flow": "flat",
    "design_path": "vck190/production/chipscopy_ced",
    "family": "versal",
    "device": "xcvc1902",
    "board": "VCK190",
    "idcode": "0x14CA8093"
  },
  "debug_cores": {
    "ibert_gty": {
      "enabled": true,
      "quad_names": ["Quad_205", "Quad_204", "Quad_201", "Quad_105"]
    }
  },
  "supported_examples": [
    "ila_and_vio",
    "link_and_eye_scan",
    "ddr_example"
  ],
  "metadata": {
    "version": "1.0.0",
    "maintainer": "AMD ChipScoPy Team"
  }
}
```

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

### Install ChipScoPy Dependencies

Source: https://xilinx.github.io/chipscopy/2026.1/chipscopy_installation.html

Commands to install optional core-addons and Jupyter support packages.

```bash
(venv) > python -m pip install chipscopy[core-addons]
(venv) > python -m pip install chipscopy[jupyter]
```

```bash
(venv) > python -m pip install "chipscopy[core-addons]"
(venv) > python -m pip install "chipscopy[jupyter]"
```

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

### chipscopy.examples.mesa.get_manifest

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

Retrieves the MESA manifest for a specific platform and optional example ID.

```APIDOC
## chipscopy.examples.mesa.get_manifest(platform, example_id=None)

### Description
Get MESA manifest for platform and optional example ID.

### Parameters
- **platform** (str) - Required - The platform identifier.
- **example_id** (str) - Optional - The example ID.

### Returns
- **Optional[Manifest, None]** - The manifest object if found, otherwise None.
```

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

### Install ChipScoPy Package

Source: https://xilinx.github.io/chipscopy/2026.1/chipscopy_installation.html

Commands to install the latest version of ChipScoPy in an active virtual environment.

```bash
# installs latest version
(venv) > python -m pip install chipscopy
```

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

### Setup StimGen Support

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/session.html

Initializes StimGen support on the connected servers using provided parameters.

```python
def setup_stimgen(self, params: dict = None) -> stimgen.StimgenClient:
    """
    Sets up StimGen support on the cs_server
    :param params: Dict of arguments used for setting up StimGen support.
    +-------------------+----------------------+------------------------------------------+
    | Name              | Type                 | Description                              |
    +===================+======================+==========================================+
    | sg4db             |  str                 | Path to .sg4db file to use               |
    +-------------------+----------------------+------------------------------------------+
    :returns: StimgenClient instance
    """
    if params is None:
        params = {}
    return stimgen.setup(self.cs_server, self.hw_server, params)
```

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

### Device Filtering Example

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/device/device.html

Demonstrates how to filter devices using the session device list.

```python
report_devices(session.devices.get(dna=".*1234"))
```

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

### VIO Port Data Structure Example

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/vio.html

Example format of the dictionary returned by the read_ports method.

```python
port_data = {
                                   probe_in0: {'value': 3, 'activity': 'RR'},
                                   ... ,
                                   probe_out0: {'value': 456},
                                   ...
                                }
```

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

### Setup VIO from LTX

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/vio.html

Initializes the VIO core by clearing existing probe definitions and mapping probes from the provided LTX object.

```python
def _setup_vio_from_ltx(self, ltx: Ltx):
    # Clear out any old LTX leftovers
    self.instance_name = None
    self.core_tcf_node.undefine_probe(probe_name="All")
    self.ltx_core = None
    if ltx:
        ltx_core: LtxCore = ltx.get_core(core_type=self.core_type, uuid=self.uuid)
        self.ltx_core = ltx_core
        assert ltx_core is not None
        self.instance_name = ltx_core.cell_name
        self.name = ltx_core.cell_name
        probe_to_port_map = self._get_probe_to_port_map(ltx_core.probes)
        self._create_probes(probe_to_port_map)
```

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

### Define ILAProbeValues Examples

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/ila/ila_probe.html

Examples of valid compare value configurations for ILA probes, including range checks and don't-care values.

```python
['==',   'XXX0']
```

```python
['>=',   '0x3',   '<=',   '0x10']
```

```python
['>=',   3,   '<=',   10]
```

```python
['==',   '0011',   '==',   '0111',   '==',   '1111']
```

```python
['==',   'XXXX']
```

```python
[]
```

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

### EyeScan.start

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/references/scan.html

Starts the eye scan process in hardware.

```APIDOC
## EyeScan.start(show_progress_bar=True)

### Description
Send command to cs_server to start the eye scan in the hardware.

### Parameters
- **show_progress_bar** (bool) - Optional - Set to true to show progress bar on stdout.
```

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

### Launch Jupyter Notebook Server

Source: https://xilinx.github.io/chipscopy/2026.1/chipscopy_installation.html

Starts the Jupyter notebook server within the virtual environment.

```bash
(venv) > jupyter notebook
```

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

### YKScan.start

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/references/yk_scan.html

Starts the YK scan process.

```APIDOC
## YKScan.start()

### Description
Initiates the YK scan process.
```

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

### Discover and Setup Cores

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/device/device.html

Scans the device for debug cores. Note that this operation may be time-consuming depending on the scan scope.

```python
def discover_and_setup_cores(
        self,
        *,
        hub_address_list: Optional[List[int]] = None,
        ltx_file: Union[Path, str] = None,
        **kwargs,
    ):
        """Scan device for debug cores. This may take some time depending on
        what gets scanned.

        Args:
            hub_address_list: List of debug hub addresses to scan
            ltx_file: LTX file (which contains debug hub addresses)
```

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

### Retrieve MESA Manifest

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Fetches a manifest for a specific platform, optionally filtered by an example ID.

```python
def get_manifest(platform: str, example_id: Optional[str] = None) -> Optional[Manifest]:
    """Get MESA manifest for platform and optional example ID."""
    return _registry.get_manifest(platform, example_id)
```

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

### Wait for Core Setup Completion

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/device/device.html

Polls the chipscope node readiness state with a timeout mechanism.

```python
cs_node.setup_cores(debug_hub_addrs=hub_address_list)
setup_timeout = kwargs.get("setup_timeout", 10)
deadline = None if setup_timeout is None else time.monotonic() + setup_timeout

while True:
    # setup_cores() tracks pending work on the sync node returned by the
    # view, so wait on that node's readiness while draining queued events.
    cs_view.run_events()
    if cs_node.is_ready:
        break
    if deadline is not None and time.monotonic() >= deadline:
        raise TimeoutError(f"Core setup did not complete within {setup_timeout}s")
    time.sleep(0.1)

cs_view.run_events()
logger.debug("Core setup completed and events processed")
```

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

### Configure ILAProbeValues

Source: https://xilinx.github.io/chipscopy/2026.1/ila.html

Examples of defining trigger and capture conditions using lists of operators and values.

```python
['==', 'XXX0']
```

```python
['>=', '0x3', '<=', '0x10']
```

```python
['>=', 3, '<=', 10]
```

```python
['==', '0011', '==', '0111', '==', '1111']
```

```python
['==', 'XXXX']
```

```python
[]
```

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

### Print Manifest Information

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Displays formatted design details, enabled debug cores, and supported examples from a manifest object.

```python
[docs]def print_manifest_info(manifest: Manifest, detailed: bool = False) -> None:
    """Print manifest information in a formatted way."""
    print("=" * 80)
    print(f"DESIGN: {manifest.design_info.design_name}")
    print("=" * 80)

    print(f"\nPlatform:     {manifest.design_info.hw_platform}")
    print(f"Device:       {manifest.design_info.device}")
    print(f"Family:       {manifest.design_info.family}")
    print(f"Board:        {manifest.design_info.board or 'N/A'}")

    if manifest.design_info.description:
        print(f"Description:  {manifest.design_info.description}")

    print("\nEnabled Debug Cores:")
    for core_name in manifest.get_enabled_cores():
        core = manifest.debug_cores[core_name]
        print(f"  - {core_name}: {core.description}")
        if detailed and core.features:
            print(f"    Features: {', '.join(core.features)}")

    print(f"\nSupported Examples ({len(manifest.supported_examples)}):")
    for i, example_id in enumerate(manifest.supported_examples, 1):
        print(f"  {i:2}. {example_id}")

    print("=" * 80)
```

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

### Start Eye Scan Command

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/ibert/eye_scan.html

Initiates an eye scan on the hardware by sending parameters to the cs_server.

```python
    def start(self, *, show_progress_bar: bool = True):
        """
        Send command to cs_server to start the eye scan in the HW.

        Args:
            show_progress_bar: Set to true to show progress bar on stdout

        """
        self._clear_out_old_data()

        scan_params = dict()
        for param in self.params.values():
            if param.value is not None:
                if not param.modifiable:
                    printer(
                        f"Scan parameter '{param.name} is not modifiable! It will be ignored",
                        level="warning",
                    )
                    continue
                scan_params[param.name] = param.value

        self._handle_from_cs_server = self.rx.core_tcf_node.start_eye_scan(
            rx_name=self.rx.handle,
            scan_parameters=scan_params,
        )

        self._task_id = common_progress.add_task(
            description=f"{self.name} progress ",
            status=self._get_status(),
            visible=show_progress_bar,
        )
```

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

### chipscopy.examples.mesa.resolve_example_design

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

Resolves programming and probes files for an example notebook. Supports either direct mode (user-provided files) or MESA mode (manifest-driven lookup).

```APIDOC
## chipscopy.examples.mesa.resolve_example_design(hw_platform, example_id, *, programming_file='', probes_file='', device_family='versal')

### Description
Resolves programming and probes files for an example notebook. Two paths are supported: Direct mode (if programming_file is provided) or MESA mode (manifest lookup).

### Parameters
- **hw_platform** (str) - Required - The hardware platform identifier.
- **example_id** (str) - Required - The example ID to resolve.
- **programming_file** (str) - Optional - Path to the programming file (PDI).
- **probes_file** (str) - Optional - Path to the probes file (LTX).
- **device_family** (str) - Optional - The device family (default: 'versal').

### Returns
- **ExampleDesign** - The resolved design object.
```

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

### resolve_example_design

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Resolves an example design based on the platform and design name, either using a manifest or direct file paths.

```APIDOC
## resolve_example_design(hw_platform, design_name, programming_file=None, probes_file=None)

### Description
Resolves an example design configuration. If programming_file and probes_file are provided, it operates in direct mode; otherwise, it uses the MESA manifest system.

### Parameters
- **hw_platform** (str) - Required - The hardware platform name (e.g., "vck190").
- **design_name** (str) - Required - The name of the example design.
- **programming_file** (str) - Optional - Path to the programming file (PDI).
- **probes_file** (str) - Optional - Path to the probes file (LTX).

### Returns
- **example_design** (DesignInfo) - An object containing the resolved design information.
```

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

### Gate capabilities using ExampleDesign.manifest

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

Use the manifest attribute to check for core availability or features before accessing device resources.

```python
manifest = example_design.manifest

if manifest and manifest.has_core("memory"):
    memory = device.memory[0]

if manifest and manifest.has_all_cores("ila", "vio"):
    ila = device.ila_cores[0]

if manifest and manifest.has_feature("memory", "2d_eye_scan"):
    run_2d_eye_scan(device)
```

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

### Install Plotly dependencies

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/eye_scan.html

Install the necessary packages to enable eye scan plotting functionality.

```bash
pip install chipscopy[core-addons]
```

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

### Session.setup_stimgen

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/session.html

Sets up StimGen support on the cs_server.

```APIDOC
## Session.setup_stimgen(params=None)

### Description
Sets up StimGen support on the cs_server.

### Parameters
- **params** (dict) - Optional - Dict of arguments used for setting up StimGen support. Includes 'sg4db' (str) - Path to .sg4db file to use.

### Returns
- **StimgenClient** - A StimgenClient instance.
```

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

### Install Specific ChipScoPy Version

Source: https://xilinx.github.io/chipscopy/2026.1/chipscopy_installation.html

Commands to install a specific version of ChipScoPy on Linux and Windows platforms.

```bash
# installs 2026.1 version of chipscopy
(venv) > python -m pip install 'chipscopy==2026.1.*'
```

```bash
# installs 2026.1 version of chipscopy
(venv) > python -m pip install chipscopy==2026.1.*
```

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

### Session.setup_stimgen

Source: https://xilinx.github.io/chipscopy/2026.1/session/references.html

Sets up StimGen support on the ChipScope server.

```APIDOC
## Method: setup_stimgen

### Description
Sets up StimGen support on the cs_server.

### Parameters
- **params** (dict) - Optional - Dict of arguments used for setting up StimGen support (e.g., sg4db: Path to .sg4db file).

### Return Type
StimgenClient
```

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

### chipscopy.examples.mesa.get_all_platforms

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

Returns a list of all available platforms.

```APIDOC
## chipscopy.examples.mesa.get_all_platforms()

### Description
Get list of all available platforms.

### Returns
- **List[str]** - A list of platform names.
```

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

### Start YK Scan

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/yk_scan.html

Initiates a YK scan in a non-blocking manner.

```python
yk_scan_0.start()
```

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

### Create links with unknown TX/RX

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/link.html

Shows how to create links for unsupported GT architectures by passing an empty string instead of a TX/RX object.

```python
# Create link with unknown TX
link_0 = one(create_links(rxs=ch_0.rx, txs=""))

# Create multiple links
remaining_3_links = create_links(rxs=["", ch_2.rx, ch_3.rx], txs=[ch_1.tx, ch_2.tx, ""])
```

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

### Start an eye scan

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/eye_scan.html

Initiates an eye scan using default parameters.

```python
eye_scan_0.start()
```

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

### Discover IBERT Cores

Source: https://xilinx.github.io/chipscopy/2026.1/ibert.html

Initialize a session and discover IBERT cores on a device by setting the ibert_scan argument to true.

```python
from chipscopy import create_session

CS_URL = "TCP:localhost:3042"
HW_URL = "TCP:localhost:3121"

session = create_session(cs_server_url=CS_URL, hw_server_url=HW_URL)

device = session.devices.at(index=0)

device.discover_and_setup_cores(ibert_scan=True)
```

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

### Device.discover_and_setup_cores

Source: https://xilinx.github.io/chipscopy/2026.1/device.html

Scans the device for debug cores. This operation may take time depending on the scope of the scan.

```APIDOC
## discover_and_setup_cores(hub_address_list=None, ltx_file=None, **kwargs)

### Description
Scans the device for debug cores. This may take some time depending on what gets scanned.

### Parameters
- **hub_address_list** (Optional[List[int]]) - Optional - List of debug hub addresses to scan
- **ltx_file** (Union[Path, str, None]) - Optional - LTX file (which contains debug hub addresses)

### Keyword Arguments
- **ila_scan** (bool) - Optional - True=Scan Device for ILAs
- **vio_scan** (bool) - Optional - True=Scan Device for VIOs
- **ibert_scan** (bool) - Optional - True=Scan Device for IBERTs
- **pcie_scan** (bool) - Optional - True=Scan Device for PCIEs
- **noc_scan** (bool) - Optional - True=Scan Device for NOC
- **ddr_scan** (bool) - Optional - True=Scan Device for DDRs
- **hbm_scan** (bool) - Optional - True=Scan Device for HBMs
- **sysmon_scan** (bool) - Optional - True=Scan Device for System Monitor
- **setup_timeout** (int) - Optional - Maximum time in seconds to wait for core setup (default=10)
```

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

### Get Core Instance

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Retrieves a specific core instance by name and index.

```python
def get_core_instance(self, core_name: str, index: int = 0) -> Optional[Dict]:
    """Get a specific core instance by name and index.

```

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

### List Available Platforms

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Returns a sorted list of all hardware platforms available across all registered manifests.

```python
def get_all_platforms() -> List[str]:
    """Get list of all available platforms."""
    return _registry.get_all_platforms()
```

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

### Get Core Configuration

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Retrieves platform-specific configuration values from a debug core.

```python
def get_core_config(self, core_name: str, config_key: str, default=None):
    """Get a platform-specific configuration value from a debug core.

    For platform-specific hardware details like quad names, node names,
    and core instances. Algorithm parameters (scan patterns, step sizes,
    thresholds) should remain visible in notebooks for learning.
    """
    if not self.has_core(core_name):
        return default
    return getattr(self.debug_cores[core_name], config_key, default)
```

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

### chipscopy.examples.mesa.print_manifest_info

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

Prints manifest information in a formatted way.

```APIDOC
## chipscopy.examples.mesa.print_manifest_info(manifest, detailed=False)

### Description
Print manifest information in a formatted way.

### Parameters
- **manifest** (Manifest) - Required - The manifest object to print.
- **detailed** (bool) - Optional - Whether to print detailed information.
```

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

### Get Devices

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/session.html

Returns the list of connected devices, using cache if enabled.

```python
@property
def devices(self) -> QueryList[Device]:
    """Returns a list of devices connected to this hw_server and cable.
    Devices may span multiple jtag chains. No ordering is guaranteed.
    Devices are cached after scanning until an event changes state and
    requires a re-scan if caching is enabled.
    """
    if self._disable_cache or self._need_to_scan_devices:
        # Force scan from hardware (slow)
        devices = self.scan_devices()
    else:
        # Use the cached device list (fast)
        devices = self._get_devices_with_lock()
    return devices
```

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

### get_manifest(platform, example_id=None)

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Retrieves the MESA manifest for a specified hardware platform. Optionally filters by an example ID to ensure the manifest supports the requested design.

```APIDOC
## get_manifest(platform: str, example_id: Optional[str] = None) -> Optional[Manifest]

### Description
Get MESA manifest for a given platform and optional example ID. Returns the first matching manifest that supports the example, or None if no match is found.

### Parameters
- **platform** (str) - Required - The hardware platform identifier.
- **example_id** (str) - Optional - The specific example identifier to filter by.

### Returns
- **Manifest** (Optional) - The matching manifest object or None.
```

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

### Create IBERT links

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/link.html

Demonstrates creating single and multiple links using the create_links factory function.

```python
"""
Other imports
"""
from chipscopy.api.ibert import create_links

"""
Boilerplate stuff - Create a session, get the IBERT core etc etc
"""

quad_204 = one(ibert.gt_groups.filter_by(name="Quad_204"))

ch_0 = one(quad_204.gts.filter_by(name="CH_0"))
ch_1 = one(quad_204.gts.filter_by(name="CH_1"))
ch_2 = one(quad_204.gts.filter_by(name="CH_2"))
ch_3 = one(quad_204.gts.filter_by(name="CH_3"))

# Create single link
link_0 = one(create_links(rxs=ch_0.rx, txs=ch_0.tx))

# Create multiple links in one shot
remaining_3_links = create_links(rxs=[ch_1.rx, ch_2.rx, ch_3.rx], txs=[ch_1.tx, ch_2.tx, ch_3.tx])
```

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

### Check Plotting Dependencies

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/ddr/ddr.html

Verifies if required plotting packages are installed before attempting to generate visualizations.

```python
if (not get_margin_only) and (not _plotting_pkgs_available):
    raise ImportError(
        f"Plotting packages not installed! Please run ",
        "'pip install chipscopy[core-addons,jupyter]'",
    )
```

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

### Create Session

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/session.html

Factory methods for creating a new session with hardware and ChipScope server URLs.

```python
my_session = create_session(hw_server_url="TCP:localhost:3121",
                            cs_server_url="TCP:localhost:3042")
```

```python
my_session = create_session(hw_server_url="TCP:localhost:3121",
                            cs_server_url="TCP:localhost:3042",
                            disable_core_scan=True,
                            bypass_version_check=True)
```

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

### LTSSM Trace Loop Entry

Source: https://xilinx.github.io/chipscopy/2026.1/pcie/pcie.html

Example of a trace entry representing a repeated loop of states with a count.

```text
Loop (20) [r.lock (0x0b), r.cfg (0x0d), r.idle (0x0e), l0 (0x10)]
```

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

### Create a Session Object

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/session.html

Initializes a new session with specified server URLs and configuration options.

```python
    disable_core_scan = kwargs.get("disable_core_scan", False)
    bypass_version_check = kwargs.get("bypass_version_check", True)
    xvc_mm_server_url = kwargs.get("xvc_mm_server_url", None)
    cable_timeout = kwargs.get("cable_timeout", 4)
    initial_device_scan = kwargs.get("initial_device_scan", True)
    pre_device_scan_delay = kwargs.get("pre_device_scan_delay", 0)
    disable_cache = kwargs.get("disable_cache", False)
    auto_connect = kwargs.get("auto_connect", True)
    cs_server_sharing = kwargs.get("cs_server_sharing", False)
    enable_experimental_protocol_decode = kwargs.get("enable_experimental_protocol_decode", False)
    # Create session even if there already exists a session with the same cs_server and hw_server
    # It *should* be safe.
    session = Session(
        cs_server_url=cs_server_url,
        hw_server_url=hw_server_url,
        xvc_mm_server_url=xvc_mm_server_url,
        disable_core_scan=disable_core_scan,
        bypass_version_check=bypass_version_check,
        cable_timeout=cable_timeout,
        disable_cache=disable_cache,
        initial_device_scan=initial_device_scan,
        pre_device_scan_delay=pre_device_scan_delay,
        cs_server_sharing=cs_server_sharing,
        enable_experimental_protocol_decode=enable_experimental_protocol_decode,
    )
    if auto_connect:
        session.connect()
    return session
```

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

### ExampleDesign.program_device

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/examples/mesa/mesa.html

Programs the device using the resolved design files.

```APIDOC
## ExampleDesign.program_device(device, **program_options)

### Description
Programs the device using the resolved design files. In MESA mode, it delegates to the manifest; in direct mode, it uses the provided programming file.

### Parameters
- **device** (object) - Required - The device instance to program.
- **program_options** (dict) - Optional - Additional options passed to the programming routine.
```

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

### Define YK Scan Completion Callback

Source: https://xilinx.github.io/chipscopy/2026.1/ibert/references/yk_scan.html

Example of a callback function triggered when a YK scan stops.

```python
def done_callback(scan: YKScan, error: str or Exception):
```

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

### Writing VIO probe values

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/vio.html

Example usage of the write_probes method to set output probe values.

```python
write_probes({'foo': 1000,
                                    'bar': 0x100})
```

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

### Initialize the Device Class

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/device/device.html

The base Device class constructor, mapping core types to their respective client classes.

```python
class Device:
    """The Device class represents a single device. It is the base class for other
    Xilinx or Generic devices. Depending on the device type, some features may be available or unavailable.

    Device has the kitchen sink of properties functions to make documentation and type hints easy.
    Child classes raise FeatureNotAvailable for functions they do not support.
    """

    _CORE_TYPE_TO_CLASS_MAP = {
        "vio": AxisVIOCoreClient,
        "ila": AxisIlaCoreClient,
        "trace": AxisTraceClient,
        # todo: remove after hw_server is updated.
        "Core": AxisTraceClient,
        "pcie": AxisPCIeCoreClient,
        "npi_nir": NoCPerfMonCoreClient,
        "ibert": IBERTCoreClient,
        "sysmon": SysMonCoreClient,
        "ddrmc_main": DDRMCClient,
        "hbm": HBMClient,
    }

    def __init__(
        self,
        *,
        hw_server: ServerInfo,
        cs_server: Optional[ServerInfo],
        device_spec: DeviceSpec,
        disable_core_scan: bool,
        disable_cache: bool,
        enable_experimental_protocol_decode: bool,
    ):
        self.state = DeviceState.NEEDS_REFRESH
        self.cached_props = {}

        self.hw_server = hw_server
        self.cs_server = cs_server
```

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

### Retrieve platform-specific configurations

Source: https://xilinx.github.io/chipscopy/2026.1/mesa.html

Access core configurations and instance details from the manifest to avoid hard-coding values in notebooks.

```python
quad_names = manifest.get_core_config("ibert_gty", "quad_names", [])
node_names = manifest.get_core_config("noc_perfmon", "node_names", [])

ila_instance = manifest.get_core_instance("ila", index=0)
if ila_instance:
    ila_name = ila_instance["name"]
    probe_prefix = ila_instance.get("probe_prefix", "")
```

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

### Example of VIO probe data structure

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/vio.html

The structure returned by read_probes containing values and activity indicators.

```python
port_data = {
                                   foo_probe: {'value': 3, 'activity': 'RR'},
                                   ... ,
                                   bar_probe: {'value': 456},
                                   ...
                                }
```

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

### Perform Memory Operations

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/memory.html

Examples of reading and writing memory using device or session-based memory objects.

```python
some_values = device.memory_read(address=0xF2010000, num=2, target="DPC")
rpu = session.memory.filter_by(name="RPU").at(0)
some_values = rpu.memory_read(0xF2010000, 2)
dpc = device.memory.get(name="DPC")
dpc.memory_write(0xF2010000, [0x12345678, 0xDEADC0FE])
```

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

### Create a Session

Source: https://xilinx.github.io/chipscopy/2026.1/session.html

Use the create_session factory method to initialize a connection to the CS and HW servers.

```python
from chipscopy import create_session

CS_URL = "TCP:localhost:3042"
HW_URL = "TCP:localhost:3121"

session = create_session(cs_server_url=CS_URL, hw_server_url=HW_URL)
```

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

### Define YKScan Callback Functions

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/ibert/yk_scan.html

Example signatures for update and completion callbacks used with YKScan objects.

```python
def update_callback(scan: YKScan):

```

```python
def done_callback(scan: YKScan, error: str or Exception):

```

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

### initialize

Source: https://xilinx.github.io/chipscopy/2026.1/noc-perfmon/references/noc.html

Initializes the NOC service by collecting clocking information and refreshing the client's view of root node properties.

```APIDOC
## initialize(done)

### Description
This method collects the clocking information for client use later in the configuration of this service. It also refreshes the client’s view of specific properties for the root node ONLY. This call must be invoked before clocking information is requested from the device.

### Parameters
- **done** (Optional[DoneHWCommand, None]) - Optional - Optional command callback that will be invoked when the response is received.

### Response
- **Return Type** (None) - No data is returned directly from this method.
```

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

### reset_core()

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/pcie.html

Resets the PCIe debug core, instructing the IP to start collecting a new state trace.

```APIDOC
## reset_core()

### Description
Resets the PCIe debug core, telling the IP to start collecting a new state trace.

### Returns
- **None**
```

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

### LTSSM Trace Single State Entry

Source: https://xilinx.github.io/chipscopy/2026.1/pcie/pcie.html

Example of a single state entry in the state.trace array with its hex encoding.

```text
r.lock [(0x0b)]
```

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

### Environment Dependency Checks

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/ibert/eye_scan/plotter.html

Utility functions to ensure that Plotly and Jupyter dependencies are installed before attempting to generate plots.

```python
def check_for_plotly():
    if not _plotly_available:
        raise ImportError(
            f"Plotting packages not installed! Please run 'pip install chipscopy[core-addons]'"
        )


def check_for_jupyter():
    if not _jupyter_available:
        raise ImportError(
            f"Jupyter packages not installed! Please run 'pip install chipscopy[jupyter]'"
        )


def is_running_notebook():
    try:
        check_for_jupyter()
        shell = get_ipython().__class__.__name__
    except ImportError:
        shell = None
    except NameError:
        shell = None
    if shell == "ZMQInteractiveShell":
        return True
    else:
        return False
```

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

### Get ILA Window Count

Source: https://xilinx.github.io/chipscopy/2026.1/_modules/chipscopy/api/ila/ila_waveform.html

Returns the total number of windows currently stored in the trigger position buffer.

```python
def get_window_count(self) -> int:
        return len(self.trigger_position)
```
Tokens:
Raw