### 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)
```

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

### 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.*
```

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

### 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
[]
```

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

### 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]
```

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

### 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)
```

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

### 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.
```

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

### 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.
```

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

### 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)
```

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

### 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()
```

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

### 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
```

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

### 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.
```

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

### Resolve Example Design Function

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

Resolves programming and probe files for a notebook, choosing between direct mode or MESA manifest mode based on provided arguments.

```python
[docs]def resolve_example_design(
    hw_platform: str,
    example_id: str,
    *,
    programming_file: str = "",
    probes_file: str = "",
    device_family: str = "versal",
) -> ExampleDesign:
    """Resolve programming and probes files for an example notebook.

    Two paths are supported, in this order:

    1. **Direct mode**: if ``programming_file`` is non-empty the MESA manifest
       lookup is skipped entirely. The notebook can run with any user-provided
       PDI/LTX combination - no manifest is required.

    2. **MESA mode**: otherwise the design is resolved from the MESA manifest
       for ``hw_platform`` and ``example_id``. The platform's ``design_path``
       is converted into actual file paths via
       :func:`chipscopy.get_design_files`, and ``device_family`` is taken from
       the manifest.

    Raises:
        RuntimeError: In MESA mode when no compatible manifest is found.
    """
    if programming_file:
        return ExampleDesign(
            manifest=None,
            design_files=None,
            programming_file=programming_file,
            probes_file=probes_file,
            programming_files=[programming_file],
            probes_files=[probes_file] if probes_file else [],
            device_family=device_family,
            hw_platform=hw_platform,
            example_id=example_id,
        )
```

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

### 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})
```

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

### 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)
```

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

### 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.
```

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

### 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, ""])
```

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

### 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()
```

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

### 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.
```

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

### 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):
```

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

### 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)
```

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

### Access Low-Level Server Parameters

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

Methods to get or set parameters on the ChipScope server using the ChipScope service.

```python
    def set_param(self, params: Dict[str, Any]):
        """Generic parameter get and set for low level chipscope server params"""
        if not isinstance(params, dict):
            message = "Please provide the params to set as a dictionary!"
            logger.error(message)
            raise TypeError(message)
        cs_service = self.cs_server.get_sync_service("ChipScope")
        cs_service.set_css_param(params)
```

```python
    def get_param(self, params: Union[str, List[str]]) -> Dict[str, str]:
        """Generic parameter get and set for low level chipscope server params"""
        if isinstance(params, str):
            params = [params]
        cs_service = self.cs_server.get_sync_service("ChipScope")
        return cs_service.get_css_param(params).get()
```

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

### Device Discovery Logic

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

Scans for hardware devices and initializes or rebinds Device wrappers based on server information.

```python
def discover_devices(
    hw_server: ServerInfo,
    cs_server: ServerInfo = None,
    disable_core_scan: bool = False,
    cable_ctx: Optional[str] = None,
    disable_cache: bool = False,
    enable_experimental_protocol_decode: bool = False,
) -> QueryList[Device]:
    logger.debug(
        f"discover_devices: hw_server={hw_server}, cs_server={cs_server}, disable_core_scan={disable_core_scan}, cable_ctx={cable_ctx}, disable_cache={disable_cache}"
    )
    include_dna = True
    devices: QueryList[Device] = QueryList()
    idx = 0
    for key, device_record_list in scan_all_views(hw_server, cs_server, include_dna).items():
        device_spec = DeviceSpec.create_from_device_records(
            hw_server, cs_server, device_record_list
        )
        if not device_spec.is_valid:
            # This can happen when a chipscope server is serving multiple sessions.
            # The cs_server reports back connection information for the
            # other sessions which should be ignored.
            logger.debug(f"discover_devices: No device_node for dna key: {key} --> ignored.\n")
            continue

        if cable_ctx is None or device_spec.jtag_cable_ctx == cable_ctx:
            device_node = device_spec.get_device_node()
            assert device_node is not None
            if device_node.device_wrapper is None:
                device_node.device_wrapper = Device(
                    hw_server=hw_server,
                    cs_server=cs_server,
                    device_spec=device_spec,
                    disable_core_scan=disable_core_scan,
                    disable_cache=disable_cache,
                    enable_experimental_protocol_decode=enable_experimental_protocol_decode,
                )
                logger.debug(f"discover_devices: created new device: {device_node.device_wrapper}")
            else:
                device_node.device_wrapper._rebind_device_spec(device_spec)
                logger.debug(
                    f"discover_devices: reusing device wrapper: {device_node.device_wrapper}"
                )
            devices.append(device_node.device_wrapper)
            logger.info(f"discover_devices: {idx}: {device_node.device_wrapper}")
            idx += 1
    return devices
```

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

### Get Probe Enum Definition

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

Retrieves the enum class associated with a specific probe. Requires the ILA to be initialized.

```python
@ensure_ila_init
def get_probe_enum(self, name: str) -> Optional[enum.EnumMeta]:
    """Get enum class, which defines valid enum values for the probe.

    Args:
       name (str): Probe name.

    Returns:
        Enum class defining the enum values or None.
    """
    probe = self.probes.get(name, None)
    values: ILAProbeValues = self.probe_values.get(name, None)
    if not probe or not values:
        raise KeyError(f"Probe {name} is not a defined probe.")
    return values.enum_def
```

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

### ILA Class Initialization

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

The constructor initializes the ILA core, sets up data structures, and links the core to the LTX file if provided.

```python
    def __init__(self, tcf_ila: TCF_AxisIlaCoreClient, device, ltx: Ltx):
        DebugCore.__init__(self, core_type=CoreType.AXIS_ILA, core_tcf_node=tcf_ila)
        ltx_core = ltx.get_core(CoreType.AXIS_ILA, self.core_info.uuid) if ltx else None
        if ltx and not ltx_core:
            raise IndexError(
                f"Unable to find ILA core with uuid:{self.core_info.uuid} in LTX file."
            )

        self.name = ltx_core.cell_name if ltx_core else f"hw_ila_{ILA.__next_ila_number}"
        ILA.__next_ila_number += 1
        self._device = device
        self.waveform = None
        # Data members to be initialized later.
        self._static_info: ILAStaticInfo = None
        self._status: ILAStatus = None
        self._control: ILAControl = None
        self._ports: [ILAPort] = None
        self._probes: {str, ILAProbe} = None
        self._probe_values: {str, ILAProbeValues} = None
        self._bus_probe_mappings: [] = None
        self._probe_to_port_seqs: {str, [ILABitRange]} = None
        self._downstreams_refs: [LtxStreamRef] = None
        self._tsm_state_names: Dict[int, str] = {}

        # This is used by the filter_by method in QueryList
        self.filter_by = {"name": self.name, "uuid": self.core_info.uuid}
        self._initialize_complete = False
```

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

### Get PCIe LTSSM Graph

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

Generates a matplotlib figure representing the PCIe LTSSM graph using networkx.

```python
    def get_plt(self):
        """
        Returns a matplotlib figure to plot, showing the PCIe LTSSM graph.  States will be
        colored green if they have been visited, orange if it's the last state visited, and
        grey if not visited.  The edge labels represent the number of times that state
        transition has be traversed.

        Args:
            None

        Returns:
            A matplotlib.pyplot that can be titled and shown later (can use plt.title
            or plt.show()

        """
        import networkx as nx
        import matplotlib.pyplot as plt

        d = self.get_property([])

        graph = nx.MultiDiGraph()
        graph.add_edges_from(
            [("Detect", "Polling"), ("Polling", "Configuration"), ("Configuration", "L0")],
            label="1",
        )
        graph.add_edges_from(
            [
                ("Polling", "Detect"),
                ("Configuration", "Detect"),
                ("Configuration", "Loopback"),
                ("Configuration", "R.Lock"),
                ("Configuration", "Disabled"),
                ("L0", "L0s"),
                ("L0", "R.Lock"),
                ("L0", "L1"),
                ("L1", "R.Lock"),
                ("L0s", "R.Lock"),
                ("L0s", "L0"),
                ("R.Lock", "Configuration"),
                ("R.Lock", "R.Cfg"),
                ("R.Lock", "R.Eq"),
                ("R.Lock", "Detect"),
                ("R.Cfg", "R.Speed"),
                ("R.Cfg", "R.Idle"),
                ("R.Cfg", "Configuration"),
                ("R.Cfg", "Detect"),
                ("R.Eq", "R.Lock"),
                ("R.Eq", "R.Speed"),
                ("R.Speed", "Detect"),
                #  ("R.Idle", "R.Lock"),
                ("R.Idle", "Loopback"),
                ("R.Idle", "L0"),
                ("R.Idle", "Detect"),
                ("R.Idle", "Hot reset"),
                ("R.Idle", "Disabled"),
                ("Loopback", "Detect"),
                ("Hot reset", "Detect"),
                ("Disabled", "Detect"),
            ],
            weight=2,
            label="999",
        )
```

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

### NocPerfmon.initialize()

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

Initializes the NocPerfmon instance.

```APIDOC
## NocPerfmon.initialize()

### Description
Performs the necessary initialization steps for the NocPerfmon object.
```

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

### Registering a NodeListener for Sysmon Data Streaming

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

Required setup to process incoming data when using the stream_sensor_data method.

```python
node_listener = dm.NodeListener(sysmon)
session.chipscope_view.add_node_listener(node_listener)
```

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

### SerialObjectBase Property Accessors

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

Standard property accessors for aliases, children, and property commands, ensuring setup is performed.

```python
    # Explicitly use property from builtins here, since this class has instance var with same name
    @builtins.property
    def aliases(self) -> Set[str]:
        """All available aliases"""
        return set(self.property_for_alias.keys())

    @builtins.property
    def children(self) -> QueryList[child_type]:
        """Direct children of this object"""
        self.setup()
        return self._children

    @builtins.property
    def modifiable_aliases(self) -> Set[str]:
        """Aliases that support value modification"""
        self.setup()
        return self._modifiable_aliases

    @builtins.property
    def property(self) -> IBERTPropertyCommands:
        self.setup()
        return self._property

    @builtins.property
    def property_for_alias(self) -> Dict[str, str]:
        """Alias to property name mapping"""
        self.setup()
        return self._property_for_alias
```

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

### Session.devices

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

Returns a list of devices connected to the hardware server and cable.

```APIDOC
## Property: devices

### Description
Returns a list of devices connected to this hw_server and cable. Devices may span multiple jtag chains. No ordering is guaranteed.

### Return Type
QueryList[Device]
```

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

### LTSSM Trace Sub-state Transition Entry

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

Example of a trace entry showing sub-state traversals within the Detect state.

```text
detect [detect.quiet (0x00), detect.active (0x01), detect.quiet (0x00)]
```

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

### Create Probes from Ports and LTX

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

Initializes probe structures from TCF and LTX metadata, determining data and trigger capabilities.

```python
def create_probes_from_ports_and_ltx(
    tcf_ila: TCF_AxisIlaCoreClient, ports: [ILAPort], ltx: Ltx, uuid: str
) -> ({}, {}, str, {}):
    """Returns:  probes, map_to_port_seqs, probe enum defs"""

    def process_one_tcf_probe(attrs: {str, Any}) -> {}:
        res = {
            key: value
            for key, value in attrs.items()
            if key in {"bit_width", "mu_count", "map", "name"}
        }
        port_type = TCF_ILAPortType(attrs.get("port_type", 0))
        res["is_data"] = TCF_ILAPortType.IS_DATA in port_type
        res["is_trigger"] = TCF_ILAPortType.IS_TRIGGER in port_type
        return res
```

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

### Define YK Scan Update Callback

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

Example of a callback function triggered when a YK scan receives new data.

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

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

### Start an eye scan without progress bar

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

Initiates an eye scan while disabling the default stdout progress bar.

```python
eye_scan_0.start(show_progress_bar=False)
```

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

### Get ILA Probe Capture Value

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

Retrieves the current basic capture mode compare value for a specified probe.

```python
@ensure_ila_init
def get_probe_capture_value(self, name: str) -> []:
    """Get basic capture mode compare value for a probe.

    Args:
       name (str): Probe name.
```

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

### Create Virtual Environment

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

Creates a new virtual environment directory named venv.

```bash
> python -m venv venv
```