docs/porting_intro.pod

   1 # Copyright (C) 2001-2008, Parrot Foundation.
   2 # $Id$
   3
   4 =head1 NAME
   5
   6 docs/porting_intro.pod - Parrot Subsystem Porting Introduction
   7
   8 =head1 OVERVIEW
   9
  10 This document is an introduction to porting the optional subsystems of Parrot
  11 onto a new architecture once the core successfully builds.  It assumes passing
  12 familiarity with common VM techniques but relatively little knowledge of Parrot
  13 internals.  For each feature, a brief description of its purpose, hints on
  14 helping to port it, and pointers to more information are included.
  15
  16 =head1 Threads
  17
  18 =head2 What it is
  19
  20 Parrot abstracts parallel streams of execution (threads) using a small set of
  21 concurrency primitives that operate on thread objects with distinct code paths
  22 and private data.  Architecture-specific threading models are mapped onto to
  23 these primitives to provide Parrot threads with the most desirable features of
  24 native threads.  Native thread support is very important to the adoption of
  25 Parrot.
  26
  27 =head2 How to help
  28
  29 At present Parrot implements support only for POSIX threads (pthreads).  Most
  30 modern UNIX-like operating systems have a pthreads implementation, and allowing
  31 Parrot to use these is frequently just a matter of finding the right compiler
  32 and linker flags.  Non-POSIX architectures with substantially different
  33 threading models will require more implementation and debugging to work with
  34 Parrot.
  35
  36 To assist with enhancing threading support, compare the threading primitives
  37 required by Parrot in F<thread.h> to those provided by your platform's
  38 threading model(s) and implement Parrot threads in terms of native threads. See
  39 F<thr_pthread.h> for an example of this.
  40
  41 =head2 References
  42
  43 =over 4
  44
  45 =item * F<t/pmc/threads.t>
  46
  47 =item * F<config/gen/platform/*/threads.h>
  48
  49 =item * F<src/thread.c>
  50
  51 =item * F<include/parrot/thread.h>
  52
  53 =item * F<include/parrot/thr_pthread.h>
  54
  55 =back
  56
  57 =head1 Signals
  58
  59 =head2 What it is
  60
  61 Parrot must be able to receive asynchronous imperative and advisory messages
  62 from the operating system and other local processes in a safe manner. Typically
  63 this is done by registering message-specific callback functions, to which the
  64 operating system transfers control when signals are generated.
  65
  66 =head2 How to help
  67
  68 UNIX-like systems usually employ the signal() function for this purpose;
  69 Windows achieves similar functionality with message queues.  For now, Parrot
  70 assumes a mechanism like the former can be used.  Currently the signal handler
  71 test suite only operates under Linux, though the mechanism itself is intended
  72 to work wherever Parrot does.  Portable tests as well as fixes for failures
  73 thereof are greatly needed.
  74
  75 =head2 References
  76
  77 =over 4
  78
  79 =item * F<config/gen/platform/*/signal.[ch]>
  80
  81 =item * F<t/pmc/signal.t>
  82
  83 =back
  84
  85 =head1 Dynloading
  86
  87 =head2 What it is
  88
  89 Nearly all modern operating systems support runtime-specified importation of
  90 shared library object code, and Parrot must support this feature in order to
  91 use native libraries without relying on the system linker.  Notable APIs for
  92 this mechanism include C<dlopen()> on common *NIXes and LoadLibrary on Win32.
  93
  94 =head2 How to help
  95
  96 If not already supported, research the dynamic library loading API for your
  97 platform and implement it in the platform-specific sources.  Since Parrot
  98 substantially abstracts the dynload mechanism, adding support for a new
  99 platform should not require diving far into Parrot internals.
 100
 101 =head2 References
 102
 103 =over 4
 104
 105 =item * F<config/gen/platform/*/dl.[ch]>
 106
 107 =back
 108
 109 =head1 Memory protection
 110
 111 =head2 What it is
 112
 113 An ever-increasing number of operating systems support the enforcement of
 114 executable/non-executable flags on memory regions to prevent the improper
 115 execution of erroneous or malicious instructions.  When applied by default to
 116 regions that rarely need to contain executable code, this is a useful security
 117 measure.  However, since Parrot (specifically, the JIT subsystem) generates and
 118 executes native instructions in such regions, it must be able to safely
 119 circumvent these protections.
 120
 121 =head2 How to help
 122
 123 Determine what level of support for execute protection your architecture/OS
 124 combination has, and how to selectively disable it.  Documentation for features
 125 like PaX (Linux) and W^X (OpenBSD) are the best place to look for this
 126 information.  The platform-specific source files implement memory allocation
 127 wrappers that hide these details, so wading deep into Parrot is probably not a
 128 prerequisite for this task.
 129
 130 =head2 References
 131
 132 =over 4
 133
 134 =item * F<config/gen/platform/*/memexec.c>
 135
 136 =back
 137
 138 =cut