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 CGoto or CGP (CGoto Predereferenced)
  17
  18 =head2 What it is
  19
  20 "Computed goto" is a non-standard C feature that allows taking a pointer to an
  21 statement label (e.g. "LOOP:" ) using the unary && operator.  Certain Parrot
  22 runcores make use of this feature as an optimization.
  23
  24 =head2 How to help
  25
  26 If cgoto is not supported in Parrot by default on your platform, try to compile
  27 config/auto/cgoto/test_c.in with your C compiler and determine why it fails. If
  28 the compiler does not support the computed goto concept at all, this feature
  29 cannot be made to work (don't worry, there are other runcores).  However, if
  30 the compiler supports it but the test is inadequate, please submit a bug report
  31 describing how the implementation of this feature differs from what Parrot
  32 expects.
  33
  34 Note that gcc supports this feature out of the box, though it sometimes
  35 struggles with it in low-memory situations.  Failures during compilation of
  36 core_ops_cg.c are frequently caused by insufficient resources rather than bugs
  37 in gcc or Parrot.
  38
  39 =head2 References
  40
  41 =over 4
  42
  43 =item * F<config/auto/cgoto/test_c.in>
  44
  45 =item * I<make testC>
  46
  47 =back
  48
  49 =head1 Threads
  50
  51 =head2 What it is
  52
  53 Parrot abstracts parallel streams of execution (threads) using a small set of
  54 concurrency primitives that operate on thread objects with distinct code paths
  55 and private data.  Architecture-specific threading models are mapped onto to
  56 these primitives to provide Parrot threads with the most desirable features of
  57 native threads.  Native thread support is very important to the adoption of
  58 Parrot.
  59
  60 =head2 How to help
  61
  62 At present Parrot implements support only for POSIX threads (pthreads).  Most
  63 modern UNIX-like operating systems have a pthreads implementation, and allowing
  64 Parrot to use these is frequently just a matter of finding the right compiler
  65 and linker flags.  Non-POSIX architectures with substantially different
  66 threading models will require more implementation and debugging to work with
  67 Parrot.
  68
  69 To assist with enhancing threading support, compare the threading primitives
  70 required by Parrot in F<thread.h> to those provided by your platform's
  71 threading model(s) and implement Parrot threads in terms of native threads. See
  72 F<thr_pthread.h> for an example of this.
  73
  74 =head2 References
  75
  76 =over 4
  77
  78 =item * F<t/pmc/threads.t>
  79
  80 =item * F<config/gen/platform/*/threads.h>
  81
  82 =item * F<src/thread.c>
  83
  84 =item * F<include/parrot/thread.h>
  85
  86 =item * F<include/parrot/thr_pthread.h>
  87
  88 =back
  89
  90 =head1 Signals
  91
  92 =head2 What it is
  93
  94 Parrot must be able to receive asynchronous imperative and advisory messages
  95 from the operating system and other local processes in a safe manner. Typically
  96 this is done by registering message-specific callback functions, to which the
  97 operating system transfers control when signals are generated.
  98
  99 =head2 How to help
 100
 101 UNIX-like systems usually employ the signal() function for this purpose;
 102 Windows achieves similar functionality with message queues.  For now, Parrot
 103 assumes a mechanism like the former can be used.  Currently the signal handler
 104 test suite only operates under Linux, though the mechanism itself is intended
 105 to work wherever Parrot does.  Portable tests as well as fixes for failures
 106 thereof are greatly needed.
 107
 108 =head2 References
 109
 110 =over 4
 111
 112 =item * F<config/gen/platform/*/signal.[ch]>
 113
 114 =item * F<t/pmc/signal.t>
 115
 116 =back
 117
 118 =head1 Dynloading
 119
 120 =head2 What it is
 121
 122 Nearly all modern operating systems support runtime-specified importation of
 123 shared library object code, and Parrot must support this feature in order to
 124 use native libraries without relying on the system linker.  Notable APIs for
 125 this mechanism include C<dlopen()> on common *NIXes and LoadLibrary on Win32.
 126
 127 =head2 How to help
 128
 129 If not already supported, research the dynamic library loading API for your
 130 platform and implement it in the platform-specific sources.  Since Parrot
 131 substantially abstracts the dynload mechanism, adding support for a new
 132 platform should not require diving far into Parrot internals.
 133
 134 =head2 References
 135
 136 =over 4
 137
 138 =item * F<config/gen/platform/*/dl.[ch]>
 139
 140 =back
 141
 142 =head1 Memory protection
 143
 144 =head2 What it is
 145
 146 An ever-increasing number of operating systems support the enforcement of
 147 executable/non-executable flags on memory regions to prevent the improper
 148 execution of erroneous or malicious instructions.  When applied by default to
 149 regions that rarely need to contain executable code, this is a useful security
 150 measure.  However, since Parrot (specifically, the JIT subsystem) generates and
 151 executes native instructions in such regions, it must be able to safely
 152 circumvent these protections.
 153
 154 =head2 How to help
 155
 156 Determine what level of support for execute protection your architecture/OS
 157 combination has, and how to selectively disable it.  Documentation for features
 158 like PaX (Linux) and W^X (OpenBSD) are the best place to look for this
 159 information.  The platform-specific source files implement memory allocation
 160 wrappers that hide these details, so wading deep into Parrot is probably not a
 161 prerequisite for this task.
 162
 163 =head2 References
 164
 165 =over 4
 166
 167 =item * F<config/gen/platform/*/memexec.c>
 168
 169 =back
 170
 171 =cut