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 JIT
  50
  51 =head2 What it is
  52
  53 Parrot contains a just-in-time compilation subsystem that compiles Parrot
  54 bytecode into native processor instructions just prior to execution,
  55 eliminating much of the overhead of bytecode interpretation.
  56
  57 =head2 How to help
  58
  59 Each unique processor target requires its own JIT engine.  So far, engines have
  60 been implemented for DEC Alpha, ARM, Intel i386, SGI MIPS, PPC, and Sun4.  If
  61 you know that your architecture is substantially similar to one of these,
  62 adding support may be possible with relatively little effort.  Implementing a
  63 novel JIT core from scratch is a substantial undertaking.
  64
  65 Also note that some changes may be required based on OS as well. (e.g.:
  66 OS X/i386 vs. Linux/i386; OS X/i386 doesn't currently work.)
  67
  68 =head2 References
  69
  70 =over 4
  71
  72 =item * F<docs/jit.pod>
  73
  74 =item * F<src/jit/$arch/*>
  75
  76 =item * I<make testj>
  77
  78 =item * F<t/op/jit.t>
  79
  80 =back
  81
  82 =head1 Native Exec
  83
  84 =head2 What it is
  85
  86 Parrot's "native exec" feature allows the integration of the parrot runtime and
  87 a Parrot program into a single precompiled binary, reducing program start-up
  88 cost and negating the need to package Parrot distinctly from an application.
  89 It's perl2exe/PerlApp/PAR for the Parrot generation.
  90
  91 =head2 How to help
  92
  93 The exec feature makes use of the JIT subsystem, and requires supporting code
  94 with knowledge of the operating system's native object format.  This feature is
  95 only supported on JITable architectures (for now, just x86) running Linux,
  96 *BSD, or Darwin.  An interested Parrot hacker with an eligible platform can
  97 contribute by submitting patches which emit exec objects in the OS's native
  98 object format (e.g., ELF, a.out, XCOFF).
  99
 100 =head2 References
 101
 102 =over 4
 103
 104 =item * F<docs/native_exec.pod>
 105
 106 =item * F<src/exec*.c>
 107
 108 =item * F<include/parrot/exec*.h>
 109
 110 =item * F<config/auto/jit.pl>
 111
 112 =back
 113
 114 =head1 Threads
 115
 116 =head2 What it is
 117
 118 Parrot abstracts parallel streams of execution (threads) using a small set of
 119 concurrency primitives that operate on thread objects with distinct code paths
 120 and private data.  Architecture-specific threading models are mapped onto to
 121 these primitives to provide Parrot threads with the most desirable features of
 122 native threads.  Native thread support is very important to the adoption of
 123 Parrot.
 124
 125 =head2 How to help
 126
 127 At present Parrot implements support only for POSIX threads (pthreads).  Most
 128 modern UNIX-like operating systems have a pthreads implementation, and allowing
 129 Parrot to use these is frequently just a matter of finding the right compiler
 130 and linker flags.  Non-POSIX architectures with substantially different
 131 threading models will require more implementation and debugging to work with
 132 Parrot.
 133
 134 To assist with enhancing threading support, compare the threading primitives
 135 required by Parrot in F<thread.h> to those provided by your platform's
 136 threading model(s) and implement Parrot threads in terms of native threads. See
 137 F<thr_pthread.h> for an example of this.
 138
 139 =head2 References
 140
 141 =over 4
 142
 143 =item * F<t/pmc/threads.t>
 144
 145 =item * F<config/gen/platform/*/threads.h>
 146
 147 =item * F<src/thread.c>
 148
 149 =item * F<include/parrot/thread.h>
 150
 151 =item * F<include/parrot/thr_pthread.h>
 152
 153 =back
 154
 155 =head1 Signals
 156
 157 =head2 What it is
 158
 159 Parrot must be able to receive asynchronous imperative and advisory messages
 160 from the operating system and other local processes in a safe manner. Typically
 161 this is done by registering message-specific callback functions, to which the
 162 operating system transfers control when signals are generated.
 163
 164 =head2 How to help
 165
 166 UNIX-like systems usually employ the signal() function for this purpose;
 167 Windows achieves similar functionality with message queues.  For now, Parrot
 168 assumes a mechanism like the former can be used.  Currently the signal handler
 169 test suite only operates under Linux, though the mechanism itself is intended
 170 to work wherever Parrot does.  Portable tests as well as fixes for failures
 171 thereof are greatly needed.
 172
 173 =head2 References
 174
 175 =over 4
 176
 177 =item * F<config/gen/platform/*/signal.[ch]>
 178
 179 =item * F<t/pmc/signal.t>
 180
 181 =back
 182
 183 =head1 Dynloading
 184
 185 =head2 What it is
 186
 187 Nearly all modern operating systems support runtime-specified importation of
 188 shared library object code, and Parrot must support this feature in order to
 189 use native libraries without relying on the system linker.  Notable APIs for
 190 this mechanism include C<dlopen()> on common *NIXes and LoadLibrary on Win32.
 191
 192 =head2 How to help
 193
 194 If not already supported, research the dynamic library loading API for your
 195 platform and implement it in the platform-specific sources.  Since Parrot
 196 substantially abstracts the dynload mechanism, adding support for a new
 197 platform should not require diving far into Parrot internals.
 198
 199 =head2 References
 200
 201 =over 4
 202
 203 =item * F<config/gen/platform/*/dl.[ch]>
 204
 205 =back
 206
 207 =head1 Memory protection
 208
 209 =head2 What it is
 210
 211 An ever-increasing number of operating systems support the enforcement of
 212 executable/non-executable flags on memory regions to prevent the improper
 213 execution of erroneous or malicious instructions.  When applied by default to
 214 regions that rarely need to contain executable code, this is a useful security
 215 measure.  However, since Parrot (specifically, the JIT subsystem) generates and
 216 executes native instructions in such regions, it must be able to safely
 217 circumvent these protections.
 218
 219 =head2 How to help
 220
 221 Determine what level of support for execute protection your architecture/OS
 222 combination has, and how to selectively disable it.  Documentation for features
 223 like PaX (Linux) and W^X (OpenBSD) are the best place to look for this
 224 information.  The platform-specific source files implement memory allocation
 225 wrappers that hide these details, so wading deep into Parrot is probably not a
 226 prerequisite for this task.
 227
 228 =head2 References
 229
 230 =over 4
 231
 232 =item * F<config/gen/platform/*/memexec.c>
 233
 234 =back
 235
 236 =cut