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