holoscan 2.1.0__cp38-cp38-manylinux_2_35_aarch64.whl

holoscan-2.1.0.data/purelib/holoscan/cli/runner/__init__.py

@@ -0,0 +1,18 @@
+"""
+ SPDX-FileCopyrightText: Copyright (c) 2023-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ SPDX-License-Identifier: Apache-2.0
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+"""  # noqa: E501
+
+from .runner import execute_run_command  # noqa: F401

holoscan-2.1.0.data/purelib/holoscan/cli/runner/resources.py

@@ -0,0 +1,174 @@
+"""
+ SPDX-FileCopyrightText: Copyright (c) 2023-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ SPDX-License-Identifier: Apache-2.0
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+"""  # noqa: E501
+
+import logging
+import re
+from typing import Dict, Optional, Union
+
+from ..common.constants import Constants, DefaultValues
+from ..common.exceptions import InvalidSharedMemoryValueError
+
+logger = logging.getLogger("runner")
+
+
+def get_shared_memory_size(
+    pkg_info: dict, worker: bool, driver: bool, fragments: str, user_shm_size: Optional[str]
+) -> Optional[float]:
+    """Queries the pkg.json file for shared memory requirement of the application
+
+    Args:
+        pkg_info (dict): package manifest
+        worker (bool): start the application as App Worker
+        driver (bool): start the application as App Driver
+        fragments (str): comma-separated list of fragments
+        user_shm_size  (Optional[str]): user provided share memory size
+
+    Returns:
+        float: shared memory value in bytes
+    """
+
+    if user_shm_size == "config":
+        return _read_shm_size_from_config(pkg_info, worker, driver, fragments)
+    elif user_shm_size is not None:
+        return _convert_to_bytes(user_shm_size)
+    else:
+        return None
+
+
+def _read_shm_size_from_config(pkg_info: dict, worker: bool, driver: bool, fragments: str) -> float:
+    """Queries the pkg.json file for shared memory requirement of the application
+
+    Args:
+        pkg_info (dict): package manifest
+        worker (bool): start the application as App Worker
+        driver (bool): start the application as App Driver
+        fragments (str): comma-separated list of fragments
+
+    Returns:
+        float: shared memory value in bytes
+    """
+    resources = pkg_info.get("resources") if pkg_info is not None else None
+
+    if resources is None:
+        return DefaultValues.DEFAULT_SHM_SIZE
+
+    max_value: float = 0
+    global_shared_memory_size = _convert_to_bytes(
+        resources.get(Constants.RESOURCE_SHARED_MEMORY_KEY, DefaultValues.DEFAULT_SHM_SIZE)
+    )
+
+    resources_fragments = resources.get("fragments", {})
+    if worker:
+        if fragments is None or fragments.lower() == "all":
+            max_value = _find_maximum_shared_memory_value_from_all_fragments(resources_fragments)
+        else:
+            max_value = _find_maximum_shared_memory_value_from_matching_fragments(
+                resources_fragments, fragments
+            )
+        max_value = max(max_value, global_shared_memory_size)
+    else:
+        if driver:
+            max_value = global_shared_memory_size
+        else:
+            max_value = _find_maximum_shared_memory_value_from_all_fragments(resources_fragments)
+            max_value = max(max_value, global_shared_memory_size)
+
+    return max_value
+
+
+def _find_maximum_shared_memory_value_from_matching_fragments(
+    resources_fragments: Dict, fragments: str
+) -> Optional[float]:
+    """Scan matching fragments for the maximum shared memory value.
+
+    Args:
+        resources_fragments (Dict): fragment resources; resources->fragments
+        fragments (str): comma-separated list of fragments to match
+
+    Returns:
+        Optional[float]: maximum shred memory value or zero if no fragments found.
+    """
+    user_fragments = fragments.split(",")
+    fragment_values = [
+        _convert_to_bytes(val[Constants.RESOURCE_SHARED_MEMORY_KEY])
+        for key, val in resources_fragments.items()
+        if Constants.RESOURCE_SHARED_MEMORY_KEY in val and key in user_fragments
+    ]
+
+    if fragment_values:
+        return max(fragment_values)
+    else:
+        return 0
+
+
+def _find_maximum_shared_memory_value_from_all_fragments(
+    resources_fragments: Dict,
+) -> Optional[float]:
+    """Scan all fragments for the maximum shared memory value.
+
+    Args:
+        resources_fragments (Dict): fragment resources; resources->fragments
+
+    Returns:
+        Optional[float]: maximum shred memory value or zero if no fragments found.
+    """
+    fragment_values = [
+        _convert_to_bytes(val[Constants.RESOURCE_SHARED_MEMORY_KEY])
+        for _, val in resources_fragments.items()
+        if Constants.RESOURCE_SHARED_MEMORY_KEY in val
+    ]
+
+    if fragment_values:
+        return max(fragment_values)
+    else:
+        return 0
+
+
+def _convert_to_bytes(raw_value: Union[str, float, int]) -> float:
+    """Converts data measurements in string to float.
+
+    Supported units are Mi|MiB (mebibytes), Gi|GiB (gibibytes), MB|m (megabytes) and
+    GB|g (gigabytes)
+
+    Args:
+        raw_value (str): data measurement with a number and a supporting unit.
+
+    Returns:
+        float: number of bytes
+    """
+
+    if type(raw_value) in [float, int]:
+        return raw_value
+
+    result = re.search(r"([.\d]+)\s*(Mi|MiB|Gi|GiB|MB|GB|m|g)", raw_value)
+
+    if result is not None:
+        value = float(result.group(1))
+        if result.group(2) in ["Mi", "MiB"]:
+            return value * 1048576
+        if result.group(2) in ["Gi", "GiB"]:
+            return value * 1073741824
+        if result.group(2) == "MB":
+            return value * 1000000
+        if result.group(2) == "GB":
+            return value * 1000000000
+        if result.group(2) == "m":
+            return value * 1000000
+        if result.group(2) == "g":
+            return value * 1000000000
+
+    raise InvalidSharedMemoryValueError(f"Invalid/unsupported shared memory value: {raw_value}. ")

holoscan-2.1.0.data/purelib/holoscan/cli/runner/run_command.py

@@ -0,0 +1,204 @@
+"""
+ SPDX-FileCopyrightText: Copyright (c) 2023-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ SPDX-License-Identifier: Apache-2.0
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+"""  # noqa: E501
+
+import logging
+import os
+from argparse import ArgumentParser, HelpFormatter, _SubParsersAction
+from typing import List
+
+from ..common import argparse_types
+from ..common.argparse_types import valid_existing_path
+
+logger = logging.getLogger("runner")
+
+
+def create_run_parser(
+    subparser: _SubParsersAction, command: str, parents: List[ArgumentParser]
+) -> ArgumentParser:
+    parser: ArgumentParser = subparser.add_parser(
+        command, formatter_class=HelpFormatter, parents=parents, add_help=False
+    )
+
+    parser.add_argument("map", metavar="<image[:tag]>", help="HAP/MAP image name.")
+
+    parser.add_argument(
+        "--address",
+        dest="address",
+        help="address ('[<IP or hostname>][:<port>]') of the App Driver. If not specified, "
+        "the App Driver uses the default host address ('0.0.0.0') with the default port "
+        "number ('8765').",
+    )
+
+    parser.add_argument(
+        "--driver",
+        dest="driver",
+        action="store_true",
+        default=False,
+        help="run the App Driver on the current machine. Can be used together with the "
+        "'--worker' option "
+        "to run both the App Driver and the App Worker on the same machine.",
+    )
+
+    parser.add_argument(
+        "-i",
+        "--input",
+        metavar="<input>",
+        type=argparse_types.valid_dir_path,
+        help="input data directory path.",
+        required=False,
+    )
+
+    parser.add_argument(
+        "-o",
+        "--output",
+        metavar="<output>",
+        type=argparse_types.valid_dir_path,
+        help="output data directory path.",
+        required=False,
+    )
+
+    parser.add_argument(
+        "-f",
+        "--fragments",
+        dest="fragments",
+        help="comma-separated names of the fragments to be executed by the App Worker. "
+        "If not specified, only one fragment (selected by the App Driver) will be executed. "
+        "'all' can be used to run all the fragments.",
+    )
+
+    parser.add_argument(
+        "--worker",
+        dest="worker",
+        action="store_true",
+        default=False,
+        help="run the App Worker.",
+    )
+
+    parser.add_argument(
+        "--worker-address",
+        dest="worker_address",
+        help="address (`[<IP or hostname>][:<port>]`) of the App Worker. If not specified, the App "
+        "Worker uses the default host address ('0.0.0.0') with a randomly chosen port number "
+        "between 10000 and 32767 that is not currently in use.",
+    )
+
+    advanced_group = parser.add_argument_group(title="advanced run options")
+
+    advanced_group.add_argument(
+        "--config",
+        dest="config",
+        type=valid_existing_path,
+        help="path to the configuration file. This will override the configuration file embedded "
+        "in the application.",
+    )
+
+    advanced_group.add_argument(
+        "--name",
+        dest="name",
+        help="name and hostname of the container to create.",
+    )
+    advanced_group.add_argument(
+        "-n",
+        "--network",
+        dest="network",
+        default="host",
+        help="name of the Docker network this application will be connected to.  (default: host)",
+    )
+    advanced_group.add_argument(
+        "--nic",
+        dest="nic",
+        help="name of the network interface to use with a distributed multi-fragment application. "
+        "This option sets UCX_NET_DEVICES environment variable with the value specified.",
+    )
+    advanced_group.add_argument(
+        "--use-all-nics",
+        dest="use_all_nics",
+        action="store_true",
+        default=False,
+        help="allow UCX to control the selection of network interface cards for data "
+        "transfer. Otherwise, the network interface card specified with '--nic' is used. "
+        "This option sets UCX_CM_USE_ALL_DEVICES to 'y'. (default: False)",
+    )
+    advanced_group.add_argument(
+        "-r",
+        "--render",
+        dest="render",
+        action="store_true",
+        default=False,
+        help="enable rendering (default: False); runs the container with required flags to enable "
+        "rendering of graphics.",
+    )
+    advanced_group.add_argument(
+        "-q",
+        "--quiet",
+        dest="quiet",
+        action="store_true",
+        default=False,
+        help="suppress the STDOUT and print only STDERR from the application. (default: False)",
+    )
+    advanced_group.add_argument(
+        "--shm-size",
+        dest="shm_size",
+        help="set the size of /dev/shm. The format is "
+        "<number(int,float)>[MB|m|GB|g|Mi|MiB|Gi|GiB]. "
+        "Use 'config' to read the shared memory value defined in the app.json manifest. "
+        "If not specified, the container is launched using '--ipc=host' with host system's "
+        "/dev/shm mounted.",
+    )
+    advanced_group.add_argument(
+        "--terminal",
+        dest="terminal",
+        action="store_true",
+        default=False,
+        help="enter terminal with all configured volume mappings and environment variables. "
+        "(default: False)",
+    )
+    advanced_group.add_argument(
+        "--device",
+        dest="device",
+        nargs="+",
+        action="extend",
+        help="""Mount additional devices.
+        For example:
+        --device ajantv* to mount all AJA capture cards.
+        --device ajantv0 ajantv1 to mount AJA capture card 0 and 1.
+        --device video1 to mount V4L2 video device 1. """,
+    )
+    advanced_group.add_argument(
+        "--gpus",
+        dest="gpus",
+        help="""Override the value of NVIDIA_VISIBLE_DEVICES environment variable.
+        default: the value specified in the package manifest file or 'all' if not specified.
+        Refer to https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/docker-specialized.html#gpu-enumeration
+        for all available options.""",
+    )
+
+    user_group = parser.add_argument_group(title="security options")
+    user_group.add_argument(
+        "--uid",
+        type=str,
+        default=os.getuid(),
+        help=f"run the container with the UID. (default:{os.getuid()})",
+    )
+    user_group.add_argument(
+        "--gid",
+        type=str,
+        default=os.getgid(),
+        help=f"run the container with the GID. (default:{os.getgid()})",
+    )
+
+    return parser

holoscan-2.1.0.data/purelib/holoscan/cli/runner/runner.py

@@ -0,0 +1,306 @@
+"""
+ SPDX-FileCopyrightText: Copyright (c) 2023-2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ SPDX-License-Identifier: Apache-2.0
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+"""  # noqa: E501
+
+import json
+import logging
+import os
+import re
+import shutil
+import sys
+import tempfile
+from argparse import Namespace
+from glob import glob
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from ..common.dockerutils import create_or_use_network, docker_run, image_exists
+from ..common.exceptions import ManifestReadError, UnmatchedDeviceError
+from ..common.utils import (
+    compare_versions,
+    get_requested_gpus,
+    print_manifest_json,
+    run_cmd,
+    run_cmd_output,
+)
+from .resources import get_shared_memory_size
+
+logger = logging.getLogger("runner")
+
+
+def _fetch_map_manifest(map_name: str) -> Tuple[dict, dict]:
+    """
+    Execute HAP/MAP and fetch the manifest files.
+
+    Args:
+        map_name: HAP/MAP image name.
+
+    Returns:
+        app_info: application manifest as a python dict
+        pkg_info: package manifest as a python dict
+        returncode: command return code
+    """
+    logger.info("Reading HAP/MAP manifest...")
+
+    with tempfile.TemporaryDirectory() as info_dir:
+        cmd = f"""docker_id=$(docker create {map_name})
+docker cp $docker_id:/etc/holoscan/app.json "{info_dir}/app.json"
+docker cp $docker_id:/etc/holoscan/pkg.json "{info_dir}/pkg.json"
+docker rm -v $docker_id > /dev/null
+"""
+        returncode = run_cmd(cmd)
+        if returncode != 0:
+            raise ManifestReadError("Error reading manifest file form the package.")
+
+        app_json = Path(f"{info_dir}/app.json")
+        pkg_json = Path(f"{info_dir}/pkg.json")
+
+        app_info = json.loads(app_json.read_text())
+        pkg_info = json.loads(pkg_json.read_text())
+
+        print_manifest_json(app_info, "app.json")
+        print_manifest_json(pkg_info, "pkg.json")
+
+        return app_info, pkg_info
+
+
+def _run_app(args: Namespace, app_info: dict, pkg_info: dict):
+    """
+    Executes the Holoscan Application.
+
+    Args:
+        args: user arguments
+        app_info: application manifest dictionary
+        pkg_info: package manifest dictionary
+
+    Returns:
+        returncode: command returncode
+    """
+
+    map_name: str = args.map
+    input_path: Path = args.input
+    output_path: Path = args.output
+    quiet: bool = args.quiet
+    driver: bool = args.driver
+    worker: bool = args.worker
+    fragments: str = args.fragments if args.fragments else None
+    network: str = create_or_use_network(args.network, map_name)
+    nic: str = args.nic if args.nic else None
+    use_all_nics: bool = args.use_all_nics
+    gpus: str = args.gpus if args.gpus else None
+    config: Path = args.config if args.config else None
+    address: str = args.address if args.address else None
+    worker_address: str = args.worker_address if args.worker_address else None
+    render: bool = args.render
+    user: str = f"{args.uid}:{args.gid}"
+    hostname: str = None
+    terminal: bool = args.terminal
+    platform_config: str = pkg_info["platformConfig"] if "platformConfig" in pkg_info else None
+    shared_memory_size: Optional[str] = (
+        get_shared_memory_size(pkg_info, worker, driver, fragments, args.shm_size)
+        if args.shm_size
+        else None
+    )
+
+    commands = []
+    devices = _lookup_devices(args.device) if args.device else []
+
+    if driver:
+        commands.append("--driver")
+        logger.info("Application running in Driver mode")
+    if worker:
+        commands.append("--worker")
+        logger.info("Application running in Worker mode")
+    if fragments:
+        commands.append("--fragments")
+        commands.append(fragments)
+        logger.info(f"Configured fragments: {fragments}")
+    if address:
+        commands.append("--address")
+        commands.append(address)
+        logger.info(f"App Driver address and port: {address}")
+    if worker_address:
+        commands.append("--worker_address")
+        commands.append(worker_address)
+        logger.info(f"App Worker address and port: {worker_address}")
+
+    if driver:
+        hostname = "driver"
+
+    docker_run(
+        hostname,
+        map_name,
+        input_path,
+        output_path,
+        app_info,
+        pkg_info,
+        quiet,
+        commands,
+        network,
+        nic,
+        use_all_nics,
+        gpus,
+        config,
+        render,
+        user,
+        terminal,
+        devices,
+        platform_config,
+        shared_memory_size,
+        args.uid == 0,
+    )
+
+
+def _lookup_devices(devices: List[str]) -> List[str]:
+    """
+    Looks up matching devices in /dev and returns a list
+    of fully qualified device paths.
+
+    Raises exception if any devices cannot be found.
+    """
+    matched_devices = []
+    unmatched_devices = []
+
+    for dev in devices:
+        pattern = dev
+        if not pattern.startswith("/"):
+            pattern = "/dev/" + pattern
+        found_devices = glob(pattern)
+        if len(found_devices) == 0:
+            unmatched_devices.append(dev)
+        else:
+            matched_devices.extend(found_devices)
+
+    if len(unmatched_devices) > 0:
+        raise UnmatchedDeviceError(unmatched_devices)
+
+    return matched_devices
+
+
+def _dependency_verification(map_name: str) -> bool:
+    """Check if all the dependencies are installed or not.
+
+    Args:
+        map_name: HAP/MAP name
+
+    Returns:
+        True if all dependencies are satisfied, otherwise False.
+    """
+    logger.info("Checking dependencies...")
+
+    # check for docker
+    prog = "docker"
+    logger.info('--> Verifying if "%s" is installed...\n', prog)
+    if not shutil.which(prog):
+        logger.error(
+            '"%s" not installed, please install it from https://docs.docker.com/engine/install/.',
+            prog,
+        )
+        return False
+
+    buildx_paths = [
+        os.path.expandvars("$HOME/.docker/cli-plugins"),
+        "/usr/local/lib/docker/cli-plugins",
+        "/usr/local/libexec/docker/cli-plugins",
+        "/usr/lib/docker/cli-plugins",
+        "/usr/libexec/docker/cli-plugins",
+    ]
+    prog = "docker-buildx"
+    logger.info('--> Verifying if "%s" is installed...\n', prog)
+    buildx_found = False
+    for path in buildx_paths:
+        if shutil.which(os.path.join(path, prog)):
+            buildx_found = True
+
+    if not buildx_found:
+        logger.error(
+            '"%s" not installed, please install it from https://docs.docker.com/engine/install/.',
+            prog,
+        )
+        return False
+
+    # check for map image
+    logger.info('--> Verifying if "%s" is available...\n', map_name)
+    if not image_exists(map_name):
+        logger.error("Unable to fetch required image.")
+        return False
+
+    return True
+
+
+def _pkg_specific_dependency_verification(pkg_info: dict) -> bool:
+    """Checks for any package specific dependencies.
+
+    Currently it verifies the following dependencies:
+    * If gpu has been requested by the application, verify that nvidia-ctk is installed.
+    Note: when running inside a Docker container, always assume nvidia-ctk is installed.
+    Args:
+        pkg_info: package manifest as a python dict
+
+    Returns:
+        True if all dependencies are satisfied, otherwise False.
+    """
+    if os.path.exists("/.dockerenv"):
+        logger.info("--> Skipping nvidia-ctk check inside Docker...\n")
+        return True
+
+    requested_gpus = get_requested_gpus(pkg_info)
+    if requested_gpus > 0:
+        # check for NVIDIA Container TOolkit
+        prog = "nvidia-ctk"
+        logger.info('--> Verifying if "%s" is installed...\n', prog)
+        if not shutil.which(prog):
+            logger.error('"%s" not installed, please install NVIDIA Container Toolkit.', prog)
+            return False
+
+        logger.info('--> Verifying "%s" version...\n', prog)
+        output = run_cmd_output("nvidia-ctk --version | grep version")
+        match = re.search(r"([0-9]+\.[0-9]+\.[0-9]+)", output)
+        min_ctk_version = "1.12.0"
+        recommended_ctk_version = "1.14.1"
+        if compare_versions(min_ctk_version, match.group()) > 0:
+            logger.error(
+                f"Found '{prog}' Version {match.group()}. "
+                f"Version {min_ctk_version}+ is required ({recommended_ctk_version}+ recommended)."
+            )
+            return False
+
+    return True
+
+
+def execute_run_command(args: Namespace):
+    if not _dependency_verification(args.map):
+        logger.error("Execution Aborted")
+        sys.exit(1)
+
+    try:
+        # Fetch application manifest from MAP
+        app_info, pkg_info = _fetch_map_manifest(args.map)
+    except Exception as e:
+        logger.error(f"Failed to fetch MAP manifest: {e}")
+        sys.exit(1)
+
+    if not _pkg_specific_dependency_verification(pkg_info):
+        logger.error("Execution Aborted")
+        sys.exit(1)
+
+    try:
+        # Run Holoscan Application
+        _run_app(args, app_info, pkg_info)
+    except Exception as ex:
+        logger.debug(ex, exc_info=True)
+        logger.error(f"Error executing {args.map}: {ex}")
+        sys.exit(1)