NAME

docs/porting_intro.pod - Parrot Subsystem Porting Introduction

DESCRIPTION

This document is an introduction to porting the optional subsystems of Parrot onto a new architecture once the core successfully builds. It assumes passing familiarity with common VM techniques but relatively little knowledge of Parrot internals. For each feature, a brief description of its purpose, hints on helping to port it, and pointers to more information are included.

THREADS

What it is

Parrot abstracts parallel streams of execution (threads) using a small set of concurrency primitives that operate on thread objects with distinct code paths and private data. Architecture-specific threading models are mapped onto to these primitives to provide Parrot threads with the most desirable features of native threads. Native thread support is very important to the adoption of Parrot.

How to help

At present Parrot has full native threads support, pthreads and windows threads. But running garbage collection together with allocation of memory in threaded code might lead to races or access violations, esp. on darwin, but also on linux.

See https://github.com/parrot/parrot/issues?milestone=2&state=open

References

Signals

What it is

Parrot must be able to receive asynchronous imperative and advisory messages from the operating system and other local processes in a safe manner. Typically this is done by registering message-specific callback functions, to which the operating system transfers control when signals are generated.

How to help

UNIX-like systems usually employ the signal() function for this purpose; Windows achieves similar functionality with message queues. For now, Parrot assumes a mechanism like the former can be used. Currently the signal handler test suite only operates under Linux, though the mechanism itself is intended to work wherever Parrot does. Portable tests as well as fixes for failures thereof are greatly needed.

References

DYNLOADING

What it is

Nearly all modern operating systems support runtime-specified importation of shared library object code, and Parrot must support this feature in order to use native libraries without relying on the system linker. Notable APIs for this mechanism include dlopen() on common *NIXes and LoadLibrary on Win32.

How to help

If not already supported, research the dynamic library loading API for your platform and implement it in the platform-specific sources. Since Parrot substantially abstracts the dynload mechanism, adding support for a new platform should not require diving far into Parrot internals.

References

Memory protection

What it is

An ever-increasing number of operating systems support the enforcement of executable/non-executable flags on memory regions to prevent the improper execution of erroneous or malicious instructions. When applied by default to regions that rarely need to contain executable code, this is a useful security measure. However, since Parrot (specifically, the JIT subsystem) generates and executes native instructions in such regions, it must be able to safely circumvent these protections.

How to help

Determine what level of support for execute protection your architecture/OS combination has, and how to selectively disable it. Documentation for features like PaX (Linux) and W^X (OpenBSD) are the best place to look for this information. The platform-specific source files implement memory allocation wrappers that hide these details, so wading deep into Parrot is probably not a prerequisite for this task.

REFERENCES