pyplugins.hyper.portal module

Portal Plugin

This module implements the Portal plugin for the Penguin hypervisor environment. It provides a mechanism for plugins to communicate with the hypervisor and each other using memory-mapped regions and hypercalls. The Portal plugin manages command and data transfer, interrupt handling, and memory region state for efficient and flexible plugin communication.

Usage

The Portal plugin is loaded by the Penguin framework and is not intended for direct invocation. It provides an API for other plugins to register interrupt handlers, queue interrupts, and send/receive commands via the portal mechanism.

Example

# Register an interrupt handler
portal.register_interrupt_handler("my_plugin", my_handler_fn)

# Queue an interrupt for a plugin
portal.queue_interrupt("my_plugin")

Classes

• PortalCmd: Encapsulates a command to be sent through the portal mechanism.

• Portal: Main plugin class for handling portal communication and interrupts.

Key Features

• Memory-mapped command and data transfer

• Plugin interrupt registration and handling

• Command construction and parsing utilities

class pyplugins.hyper.portal.Portal

Bases: Plugin

Portal is a plugin that manages communication and interrupts between plugins and the hypervisor.

It provides methods for registering interrupt handlers, queuing interrupts, and reading/writing commands and data to memory-mapped regions.

Attributes:

outdir (str): Output directory for plugin data. endian_format (str): Endianness format character for struct operations. portal_interrupt (Optional[int]): Address of the portal interrupt. _interrupt_handlers (dict): Mapping of plugin names to their interrupt handler functions. _pending_interrupts (set): Set of plugin names with pending interrupts. regions_size (int): Size of the memory region.

queue_interrupt(plugin_name)

Queue an interrupt for a plugin.

Parameters: - plugin_name (str): Name of the plugin.

Returns: - bool: True if queued successfully, False otherwise.

Parameters:

plugin_name (str)

Return type:

bool

register_interrupt_handler(plugin_name, handler_fn)

Register a plugin to handle portal interrupts.

Parameters: - plugin_name (str): Name of the plugin. - handler_fn (Callable[[], Iterator]): Function to handle interrupts for this plugin.

Must be a generator function that can be used with yield from.

Returns: None

Parameters:

• plugin_name (str)

• handler_fn (Callable[[], Iterator])

Return type:

None

uninit()

Clean up all interrupt handlers and pending interrupts on plugin unload.

Returns: None

Return type:

None

wrap(f)

Wrap a function to manage portal command iteration and state.

Parameters: - f (Callable): Function to wrap.

Returns: - Callable: Wrapped function.

Parameters:

f (Callable)

Return type:

Callable

class pyplugins.hyper.portal.PortalCmd(op, addr=0, size=0, pid=None, data=None)

Bases: object

Encapsulates a command to be sent through the portal mechanism.

This class centralizes the logic for constructing portal commands and reduces complexity in the _handle_output_cmd method.

Attributes:

op (int): Operation code from HYPER_OP constants. addr (int): Address field value. size (int): Size field value. pid (int): Process ID or CURRENT_PID_NUM for current process. data (Optional[bytes]): Optional data payload for the command.

Parameters:

• op (int | str)

• addr (int)

• size (int)

• pid (int | None)

• data (bytes | None)

addr

data

classmethod none()

Create a command representing no operation.

Returns: - PortalCmd: A command with HYPER_OP_NONE operation.

Return type:

PortalCmd

op

pid

size