shrinkwrap-tool 2026.2.1__py3-none-any.whl

shrinkwrap/utils/process.py

@@ -0,0 +1,230 @@
+# Copyright (c) 2022, Arm Limited.
+# SPDX-License-Identifier: MIT
+
+import fcntl
+import io
+import os
+import pty
+import shlex
+import selectors
+import subprocess
+import sys
+import shrinkwrap.utils.runtime as runtime
+import shrinkwrap.utils.tty as tty
+
+
+STDOUT = 0
+STDERR = 1
+
+
+class Process:
+	"""
+	A wrapper to a process that should be managed by the ProcessManager.
+	"""
+	def __init__(self, args, interactive, data, run_to_end):
+		self.args = shlex.split(args)
+		self.interactive = interactive
+		self.data = data
+		self.run_to_end = run_to_end
+		self._popen = None
+		self._stdout = None
+		self._stdin = None
+		self._stderr = None
+		self._active = 0
+
+
+class ProcessManager:
+	"""
+	A ProcessManager can manage a set of processes running in parallel such
+	that it can capture all their (stdout + stderr) output and pass it to a
+	handler delegate.
+	"""
+	def __init__(self, handler=None, terminate_handler=None):
+		self._handler = handler
+		self._terminate_handler = terminate_handler
+		self._procs = []
+		self._active = 0
+		self._sel = None
+
+	def set_handler(self, handler):
+		self._handler = handler
+
+	def add(self, process):
+		self._procs.append(process)
+		if self._sel:
+			self._proc_activate(process)
+
+	def run(self, forward_stdin=False):
+		try:
+			self._sel = selectors.DefaultSelector()
+			self._active = 0
+
+			if forward_stdin:
+				self._stdin_activate()
+
+			for proc in self._procs:
+				self._proc_activate(proc)
+
+			while self._active > 0:
+				for key, mask in self._sel.select():
+					handler = key.data[0]
+					handler(key, mask)
+		finally:
+			for proc in self._procs:
+				try:
+					self._proc_deactivate(proc, force=True)
+				except:
+					pass
+
+			if forward_stdin:
+				self._stdin_deactivate()
+
+			self._sel.close()
+			self._sel = None
+
+	def _read_nonblock(self, fileobj):
+		# If stdin and stdout are both connected to a tty, setting stdin
+		# to nonblocking will also cause stdout to be set nonblocking
+		# and can cause errors when printing to stdout the output buffer
+		# is full. So work around that by only making fds nonblocking
+		# while we do the read.
+		fl = fcntl.fcntl(fileobj, fcntl.F_GETFL)
+		fcntl.fcntl(fileobj, fcntl.F_SETFL, fl | os.O_NONBLOCK)
+		data = fileobj.read()
+		fcntl.fcntl(fileobj, fcntl.F_SETFL, fl)
+		return data
+
+	def _proc_handle(self, key, mask):
+		proc = key.data[1]
+		streamid = key.data[2]
+		data = self._read_nonblock(key.fileobj)
+
+		if data == '':
+			self._proc_stream_deactivate(proc, key.fileobj, streamid)
+		elif self._handler:
+			self._handler(self, proc, data, streamid)
+
+	def _proc_activate(self, proc):
+		cmd = runtime.mkcmd(proc.args, proc.interactive)
+
+		if proc.interactive:
+			master, slave = pty.openpty()
+
+			proc._popen = subprocess.Popen(cmd,
+						       stdin=slave,
+						       stdout=slave,
+						       stderr=slave)
+
+			proc._stdin = io.open(master, 'wb', buffering=0)
+			proc._stdout = io.open(master, 'rb', -1, closefd=False)
+			# Don't attempt to translate newlines. We need the '\r's
+			# to correctly return the carriage for interactive
+			# terminals. Telnet sometimes gives '\r\r\n' too, which
+			# would be incorrectly translated to '\n\n'.
+			proc._stdout = io.TextIOWrapper(proc._stdout,
+							newline='',
+							errors='replace')
+			# stdout and stderr get merged into pty, so can't tell
+			# them apart. This isn't a problem for the emit build
+			# warnings use case.
+			proc._stderr = None
+			proc._active = 1
+		else:
+			proc._popen = subprocess.Popen(cmd,
+						       stdin=subprocess.DEVNULL,
+						       stdout=subprocess.PIPE,
+						       stderr=subprocess.PIPE,
+						       universal_newlines=True,
+						       errors='replace')
+
+			proc._stdin = None
+			proc._stdout = proc._popen.stdout
+			proc._stderr = proc._popen.stderr
+			proc._active = 2
+
+		if proc._stdout:
+			self._sel.register(proc._stdout,
+					   selectors.EVENT_READ,
+					   (self._proc_handle, proc, STDOUT))
+
+		if proc._stderr:
+			self._sel.register(proc._stderr,
+					   selectors.EVENT_READ,
+					   (self._proc_handle, proc, STDERR))
+
+		if proc.run_to_end:
+			self._active += 1
+
+	def _proc_stream_deactivate(self, proc, stream, streamid, force=False):
+		if not stream:
+			return
+
+		self._sel.unregister(stream)
+
+		if streamid == STDOUT:
+			proc._stdout = None
+		if streamid == STDERR:
+			proc._stderr = None
+
+		assert(proc._active > 0)
+		proc._active -= 1
+
+		if not force and proc._active == 0:
+			self._proc_deactivate(proc, force)
+
+	def _proc_deactivate(self, proc, force):
+		if not proc._popen:
+			return
+
+		if proc.run_to_end:
+			self._active -= 1
+
+		proc._stdin = None
+		self._proc_stream_deactivate(proc, proc._stdout, STDOUT, force)
+		self._proc_stream_deactivate(proc, proc._stderr, STDERR, force)
+
+		proc._popen.kill()
+		try:
+			proc._popen.communicate()
+		except:
+			pass
+		retcode = None if force else proc._popen.poll()
+		proc._popen = None
+
+		if self._terminate_handler:
+			self._terminate_handler(self, proc, retcode)
+
+	def _stdin_handle(self, key, mask):
+		data = self._read_nonblock(key.fileobj)
+		for proc in self._procs:
+			if proc._stdin:
+				proc._stdin.write(data)
+
+	def _stdin_activate(self):
+		# Replace stdin with unbuffered binary stream so we can pass
+		# input to the ptys without any modification.
+		self._stdin_orig = sys.stdin
+		sys.stdin = io.open(self._stdin_orig.fileno(),
+				    'rb',
+				    buffering=0,
+				    closefd=False)
+
+		# Set the terminal to raw input mode.
+		self._tty_orig = tty.configure(sys.stdin)
+
+		# Register stdin so we get notified when there is data.
+		self._sel.register(sys.stdin,
+				   selectors.EVENT_READ,
+				   (self._stdin_handle,))
+
+	def _stdin_deactivate(self):
+		# Unregister for notifications.
+		self._sel.unregister(sys.stdin)
+
+		# Restore terminal mode.
+		tty.restore(sys.stdin, self._tty_orig)
+
+		# Restore stdin to being buffered text.
+		sys.stdin.close()
+		sys.stdin = self._stdin_orig
+		self._stdin_orig = None

shrinkwrap/utils/runtime.py

@@ -0,0 +1,192 @@
+# Copyright (c) 2022, Arm Limited.
+# SPDX-License-Identifier: MIT
+
+import os
+import subprocess
+import sys
+import tuxmake.runtime
+import types
+import shrinkwrap.utils.ssh_agent as ssh_agent_lib
+
+_SSH_AUTH_SOCK = '/run/host-services/ssh-auth.sock'
+"""Path to ssh-agent socket."""
+
+
+_instance = None
+
+
+def get_null_user_opts(self):
+	return []
+
+
+class Runtime:
+	"""
+	Wraps tuxmake.runtime to provide an interface for executing commands in
+	an abstracted runtime. Multiple runtimes are supported, identified by a
+	`name`. The 'null' runtime simply executes the commands on the native
+	host. The 'docker', 'docker-local', 'podman' and 'podman-local' runtimes
+	execute the commands in a container. `timeout`, if provided, is an
+	integer number of days after which the container will be shutdown if
+	still running. If None, the default timeout is used.
+	"""
+	def __init__(self, *, name, image=None, ssh_agent_keys=None, timeout=None):
+		self._rt = None
+		self._mountpoints = set()
+
+		ssh_agent_keys = ssh_agent_keys	or []
+
+		self._rt = tuxmake.runtime.Runtime.get(name)
+		self._rt.set_image(image)
+		self._rt.network = "host"
+
+		is_mac = sys.platform.startswith('darwin')
+		is_docker = name.startswith('docker')
+		is_container = is_docker or name.startswith('podman')
+
+		# MacOS uses GIDs that overlap with already defined GIDs in the
+		# container so we can't just bind the macos host UID/GID to the
+		# shrinkwrap user in the container. This concept doesn't really
+		# work anyway, because on MacOS the container is running on a
+		# completely separate (linux) kernel in a VM. Fortunately docker
+		# maps the VM to the current MacOS user when touching mapped
+		# volumes so it all works out. So on MacOS run as root.
+		# Unfortunately, tuxmake tries to be too clever (it assumes a
+		# linux host) and tries to map the in-container user to the host
+		# UID/GID. This fails when the in-container user is root. So we
+		# have this ugly workaround to override the user-opts with
+		# nothing. By passing nothing, we implicitly run as root and
+		# tuxmake doesn't try to run usermod.
+		if is_mac and is_docker:
+			self._rt.get_user_opts = \
+				types.MethodType(get_null_user_opts, self._rt)
+		else:
+			self._rt.set_user('shrinkwrap')
+			self._rt.set_group('shrinkwrap')
+
+		# Tuxmake always starts the container with "sleep 1d" so that it
+		# automatically shuts down after 1 day if it ends up dangling.
+		# This is problematic for some long running FVP test cases, so
+		# we allow overriding it on the command line. We add a filter
+		# for spawn_container() which modifies the sleep argument which
+		# is the last element in the cmd list. Avoid hooking unless the
+		# user explicitly specified a timeout that is different from the
+		# expected default.
+		if is_container and timeout and timeout != 1:
+			spawn_container_orig = self._rt.spawn_container
+			def spawn_container_new(self, cmd):
+				if (cmd[-1] == '1d'):
+					cmd[-1] = f'{timeout}d'
+				return spawn_container_orig(cmd)
+			self._rt.spawn_container = \
+				types.MethodType(spawn_container_new, self._rt)
+
+		for key in ssh_agent_keys:
+			ssh_agent_lib.add(key)
+
+		socket = ssh_agent_lib.socket()
+
+		if name != 'null' and socket is not None:
+			if is_mac:
+				socket = _SSH_AUTH_SOCK
+
+			self._rt.add_volume(socket, _SSH_AUTH_SOCK)
+
+	def start(self):
+		for mp in self._mountpoints:
+			self._rt.add_volume(mp)
+
+		self._rt.prepare()
+
+	def add_volume(self, src):
+		# Podman can't deal with duplicate mount points, so filter out
+		# duplicates here, including mount-points that are children of
+		# other mount points. Then defer registering the actual final
+		# volumes until start() time.
+
+		if not src:
+			return
+
+		mountpoints = set()
+
+		for mp in self._mountpoints:
+			common = os.path.commonpath([src, mp])
+			if common == mp:
+				# mp is parent (or duplicate) of src, so src
+				# already covered.
+				return
+			elif common != src:
+				# src is not a parent of mp. So include mp in
+				# filtered set of mount points.
+				mountpoints.add(mp)
+
+		# If we got here, then src is a unique mountpoint. Add it, and
+		# commit the filtered set.
+		mountpoints.add(src)
+		self._mountpoints = mountpoints
+
+	def mkcmd(self, cmd, interactive=False):
+		return self._rt.get_command_line(cmd, interactive, False)
+
+	def ip_address(self):
+		"""
+		Returns the primary ip address of the runtime.
+		"""
+
+		script = """
+import socket
+s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
+s.settimeout(0)
+try:
+	s.connect(('10.254.254.254', 1))
+	ip = s.getsockname()[0]
+except Exception:
+	ip = '127.0.0.1'
+finally:
+	s.close()
+print(ip)
+""".replace('\n', '\\n').replace('\t', '\\t')
+
+		cmd = ['python3', '-c', f'exec("{script}")']
+		res = subprocess.run(self.mkcmd(cmd),
+				     universal_newlines=True,
+				     stdout=subprocess.PIPE,
+				     stderr=subprocess.PIPE)
+		if res.returncode == 0:
+			return res.stdout.strip()
+		return '127.0.0.1'
+
+	def __enter__(self):
+		global _instance
+		assert _instance is None
+		_instance = self
+		return self
+
+	def __exit__(self, exc_type, exc_val, exc_tb):
+		global _instance
+		assert _instance == self
+		_instance = None
+		if self._rt:
+			# Horrible hack alert; I've observed that docker can
+			# take over 10 seconds to stop the container on at least
+			# 1 system running Ubuntu 24.04. Let's cleanup the
+			# container asynchonously in a child process.
+			if os.fork() == 0:
+				self._rt.cleanup()
+				exit()
+			self._rt = None
+
+
+def get():
+	"""
+	Returns the current Runtime instance.
+	"""
+	global _instance
+	assert _instance is not None
+	return _instance
+
+
+def mkcmd(cmd, interactive=False):
+	"""
+	Shorthand for get().mkcmd().
+	"""
+	return get().mkcmd(cmd, interactive)

shrinkwrap/utils/ssh_agent.py

@@ -0,0 +1,98 @@
+# Copyright (c) 2024, Arm Limited.
+# SPDX-License-Identifier: MIT
+
+import atexit
+import os
+import re
+import subprocess
+from typing import Optional
+
+import shrinkwrap.utils.logger as logger
+
+
+_logger = logger.Logger(27)
+"""Logger used within this module."""
+
+
+def _log(msg):
+        """Print a message to the console."""
+        _logger.print(msg, tag='ssh-agent', cont=False)
+
+
+_proc = None
+"""ssh-agent process started by this module."""
+
+
+def _start():
+        """Start an ssh-agent process."""
+        global _proc
+
+        assert _proc is None
+        _proc = subprocess.run(
+                ['ssh-agent', '-s'], stdout=subprocess.PIPE, text=True)
+
+        # Extract socket path and PID from ssh-agent output
+        output = _proc.stdout
+        match = re.search(
+                r'SSH_AUTH_SOCK=(?P<sock>[^;]+).*SSH_AGENT_PID=(?P<pid>[^;]+)',
+                output,
+                re.DOTALL | re.MULTILINE)
+
+        if not match:
+                raise Exception(f'Failed to parse ssh-agent output: {output}')
+
+        values = match.groupdict()
+
+        os.environ['SSH_AUTH_SOCK'] = values['sock']
+        os.environ['SSH_AGENT_PID'] = values['pid']
+
+        _log(f'Started ssh-agent pid {values["pid"]}')
+
+        # Register a handler to kill the ssh-agent process
+        atexit.register(_stop)
+
+
+def _stop():
+        """Stop the ssh-agent process."""
+        global _proc
+
+        assert _proc is not None
+
+        _log('Stopping ssh-agent')
+
+        subprocess.check_call(['ssh-agent', '-k'], stdout=subprocess.DEVNULL)
+
+        del os.environ['SSH_AUTH_SOCK']
+        del os.environ['SSH_AGENT_PID']
+
+        _proc = None
+
+
+def socket() -> Optional[str]:
+        """Return path to socket."""
+        return os.environ.get('SSH_AUTH_SOCK')
+
+
+def add(key: Optional[str]=None) -> None:
+        """
+        Add specified key, or add default keys if key is None.
+
+        If no ssh-agent process is running, one is started.
+        """
+        if socket() is None:
+                _start()
+        else:
+                global _proc
+                if _proc is None:
+                        raise Exception('Adding a key to an ssh-agent not owned by shrinkwrap is not supported.')
+
+        if key is None:
+                _log('Adding default keys')
+        else:
+                _log(f'Adding key {key}')
+
+        args = ['ssh-add']
+        if key is not None:
+                args.append(key)
+
+        subprocess.check_call(args)

shrinkwrap/utils/tty.py

@@ -0,0 +1,46 @@
+# Copyright (c) 2022, Arm Limited.
+# SPDX-License-Identifier: MIT
+
+from termios import *
+import copy
+
+IFLAG = 0
+OFLAG = 1
+CFLAG = 2
+LFLAG = 3
+ISPEED = 4
+OSPEED = 5
+CC = 6
+
+def configure(fd, when=TCSAFLUSH):
+	try:
+		orig = tcgetattr(fd)
+		mode = copy.deepcopy(orig)
+
+		# Don't remove/convert line feeds to new lines on input. EDK2
+		# can't handle only receiving newlines.
+		mode[IFLAG] = mode[IFLAG] & ~(INLCR | IGNCR | ICRNL)
+
+		# Disable input echo and use non-canonical input mode (no
+		# buffering).
+		mode[LFLAG] = mode[LFLAG] & ~(ECHO | ICANON)
+		mode[CC][VMIN] = 1
+		mode[CC][VTIME] = 0
+
+		# Use ^] as the interrupt (instead of ^C), and remove key
+		# bindings for quit and suspend signals. This means the usual
+		# key bindings are passed through to the child.
+		mode[CC][VINTR] = b'\x1d'
+		mode[CC][VQUIT] = b'\x00'
+		mode[CC][VSUSP] = b'\x00'
+
+		tcsetattr(fd, when, mode)
+		return orig
+
+	except error as e:
+		# Expect failure if we are not connected to a tty. Non-fatal.
+		pass
+
+def restore(fd, mode, when=TCSAFLUSH):
+	if mode:
+		tcsetattr(fd, when, mode)

shrinkwrap/utils/vars.py

@@ -0,0 +1,14 @@
+# Copyright (c) 2022, Arm Limited.
+# SPDX-License-Identifier: MIT
+
+def parse(args, type):
+	vars = {}
+
+	for pair in args:
+		try:
+			key, value = pair.split('=', maxsplit=1)
+			vars[key] = value
+		except ValueError:
+			raise Exception(f'Invalid {type}var {pair}')
+
+	return vars

shrinkwrap/utils/workspace.py

@@ -0,0 +1,59 @@
+# Copyright (c) 2022, Arm Limited.
+# SPDX-License-Identifier: MIT
+
+import os
+
+_code_root = os.path.dirname(os.path.dirname(__file__))
+_data_root = os.path.expanduser('~/.shrinkwrap')
+
+def _get_loc(var, default=None):
+	path = os.environ.get(var, default)
+	if not path:
+		return None
+	path = os.path.abspath(path)
+	os.makedirs(path, exist_ok=True)
+	return path
+
+build = _get_loc('SHRINKWRAP_BUILD', os.path.join(_data_root, 'build'))
+package = _get_loc('SHRINKWRAP_PACKAGE', os.path.join(_data_root, 'package'))
+project_cache = _get_loc("SHRINKWRAP_PROJECT_CACHE")
+
+_configs = None
+
+def configs():
+	global _configs
+
+	if _configs is None:
+		value = os.environ.get('SHRINKWRAP_CONFIG')
+
+		# Set of paths that we will search for configs in, in priority
+		# order. Prefer any user-supplied paths, then fall back to
+		# ~/.shrinkwrap/config (which is the "installed" location of the
+		# standard config store), then fall back to the in-repo location
+		# for the uninstalled case. Then filter out any paths that don't
+		# exist.
+		paths = value.split(':') if value else []
+		paths += [os.path.realpath(os.path.join(_data_root, 'config'))]
+		paths += [os.path.realpath(os.path.join(_code_root, 'config'))]
+		paths += [os.path.realpath(os.path.join(_code_root, '../../config'))]
+		_configs = [p for p in paths if os.path.exists(p)]
+
+	return _configs
+
+def config(path, join=True):
+	for config in configs():
+		p = os.path.join(config, path) if join else f'{config}{path}'
+		if os.path.exists(p):
+			return config
+	return None
+
+def dump():
+	print(f'workspace.project_cache:')
+	print(f'  {project_cache}')
+	print(f'workspace.build:')
+	print(f'  {build}')
+	print(f'workspace.package:')
+	print(f'  {package}')
+	print(f'workspace.config:')
+	for path in configs():
+		print(f'  {path}')

shrinkwrap_tool-2026.2.1.dist-info/METADATA

@@ -0,0 +1,63 @@
+Metadata-Version: 2.4
+Name: shrinkwrap-tool
+Version: 2026.2.1
+Summary: Shrinkwrap tool for building and running Arm FVPs
+Author-email: Ryan Roberts <ryan.roberts@arm.com>, Saul Romero D <saul.romerodominguez@arm.com>
+License-Expression: MIT
+Project-URL: Homepage, https://git.gitlab.arm.com/tooling/shrinkwrap
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: license.rst
+Requires-Dist: PyYAML>=6.0.3
+Requires-Dist: tuxmake>=1.34.0
+Requires-Dist: termcolor<3.0,>=2.4.0; python_version < "3.10"
+Requires-Dist: termcolor>=3.2.0; python_version >= "3.10"
+Requires-Dist: graphlib-backport; python_version < "3.9"
+Provides-Extra: dev
+Requires-Dist: cffi>=2.0.0; extra == "dev"
+Requires-Dist: cryptography>=46.0.3; extra == "dev"
+Requires-Dist: cmake>=3.31.6; extra == "dev"
+Requires-Dist: pycparser>=2.23; extra == "dev"
+Requires-Dist: fdt>=0.3.3; extra == "dev"
+Requires-Dist: pyelftools>=0.32; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: Sphinx<10,>=8.2; extra == "docs"
+Requires-Dist: sphinx-rtd-theme<4,>=3.1.0; extra == "docs"
+Requires-Dist: sphinx-copybutton>=0.5.2; extra == "docs"
+Dynamic: license-file
+
+# Shrinkwrap
+
+Shrinkwrap is a tool to simplify the process of building and running firmware on
+Arm Fixed Virtual Platforms (FVP). Users simply invoke the tool to build the
+required config, then pass their own kernel and rootfs to the tool to boot the
+full system on FVP.
+
+- Documentation is available at: [ReadTheDocs](https://shrinkwrap.docs.arm.com)
+- Source Code is available at: [GitLab](https://gitlab.arm.com/tooling/shrinkwrap)
+- Shrinkwrap Container Images are available at: [DockerHub](https://hub.docker.com/u/shrinkwraptool)
+
+The documentation (linked above) contains a
+[QuickStart](https://shrinkwrap.docs.arm.com/en/latest/userguide/quickstart.html)
+section, which details how to install and use the tool. However, if you are in a
+hurry, here are the minimal steps:
+
+> **NOTE:** This assumes you have Python >=3.9.0 and docker installed. If this
+> is not the case, please refer to the documentation.
+
+```
+  sudo apt-get install git netcat-openbsd python3 python3-pip telnet
+  python3 -m venv .venv
+  source .venv/bin/activate
+  python -m pip install --upgrade pip
+  python -m pip install shrinkwrap
+```
+
+```
+  shrinkwrap --help
+```