Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

a bit more tidying up

git-svn-id: https://svn.parrot.org/parrot/trunk@5463 d31e2699-5ff4-0310-a27c-f18f2fbe73fe
  • Loading branch information...
commit 9d8cce435d485e7fdd60f7b43720b9bb91720ab4 1 parent 55a480f
Michael Scott authored
View
56 docs/debug.pod
@@ -1,16 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Debugging Parrot
+=head1 NAME
-=head1 HISTORY
-
-=over 4
-
-=item Version 1.0
-
-First version by Steve Fink <steve@fink.com>
-
-=back
+docs/debug.pod - Debugging Parrot
=head1 ABSTRACT
@@ -18,17 +11,17 @@ This document describes ways to debug various parts of Parrot.
=head1 THE PARROT AND IMCC BINARIES
-First, you'll want to use the --debugging flag with Configure.pl to
+First, you'll want to use the C<--debugging> flag with F<Configure.pl> to
generate debugging symbols for the parrot binary:
- shell> perl Configure.pl --debugging
- shell> make
+ % perl Configure.pl --debugging
+ % make
You can then run the parrot binary under gdb.
You could also run all the tests with valgrind, by running
- make test IMCC="valgrind -q languages/imcc/imcc"
+ % make test IMCC="valgrind -q languages/imcc/imcc"
=head2 MEMORY MANAGEMENT
@@ -37,25 +30,25 @@ memory management in general, and garbage collection in particular.
=head3 Infant mortality
-See L<dev/infant.dev> for details of one frequent problem: infant
+See F<docs/dev/infant.dev> for details of one frequent problem: infant
mortality. Infant mortality is when you create a Parrot object, but
the garbage collector runs before you put it into a Parrot register or
in something else that is itself within a Parrot register.
To help in resolving these issues, the parrot binary accepts a
---gc-debug flag that makes such problems much more likely to occur (it
+C<--gc-debug> flag that makes such problems much more likely to occur (it
makes garbage collection occur as frequently as possible, to maximize
the probability that any newborn objects will run afoul of the garbage
collector if they are improperly coded.)
-Within the --gc-debug mode, there is another tool to help narrow down
-the problem. If you edit F<dod.c> and #define the C<GC_VERBOSE> flag to
+Within the C<--gc-debug> mode, there is another tool to help narrow down
+the problem. If you edit F<src/dod.c> and C<#define> the C<GC_VERBOSE> flag to
1, then after the garbage collector has traced all objects to find which
ones are still alive, it will scan through all of the dead objects to see
if any of them believe they are alive (which will happen for infants, since
they come into existence marked live.) If it finds any, it will print them
out. You can then re-run the program with a breakpoint set on the routine
-that allocated the object (e.g. C<get_free_object> in F<smallobject.c>).
+that allocated the object (e.g. C<get_free_object> in F<src/smallobject.c>).
You'll probably want to make the breakpoint conditional on the object having
the version number that was reported, because the same memory location
will probably hold many different objects over the lifetime of the
@@ -68,8 +61,8 @@ It's not working. You'd like some help in figuring out why.
=head2 pdb
-One possible tool is C<pdb>, the Parrot Debugger. See L<debugger.pod>
-for details on it.
+One possible tool is F<pdb>, the Parrot Debugger. See
+F<docs/debugger.pod> for details on it.
=head2 stabs
@@ -86,15 +79,15 @@ will also work if you use C<test.imc> everywhere C<test.pasm> occurs.)
Step 1: Generate the .pbc file with extra debugging information.
- shell> imcc -d -o test.pbc test.pasm
+ % imcc -d -o test.pbc test.pasm
Step 2: Start up parrot under GDB
- shell> gdb parrot
+ % gdb parrot
or
- shell> emacs &
+ % emacs &
(in emacs) M-x gdb
(in emacs) type "parrot" so it says "gdb parrot"
@@ -145,4 +138,15 @@ better technique, please let the mailing list know
The C<imcc> binary has a bunch of debugging flags for spewing out
information about various aspects of its processing. See
-L<languages/imcc/docs/running.pod> for a list of flags.
+F<languages/imcc/docs/running.pod> for a list of flags.
+
+=head1 HISTORY
+
+=over 4
+
+=item Version 1.0
+
+First version by Steve Fink <steve@fink.com>
+
+=back
+
View
34 docs/debugger.pod
@@ -1,20 +1,13 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-pdb - The Parrot Debugger
+=head1 NAME
-=head1 HISTORY
-
-=over 4
-
-=item Version 1.0
-
-First version (CVS debug.c revision 1.24), authored by Aldo Calpini
-
-=back
+docs/debugger.pod - The Parrot Debugger
=head1 ABSTRACT
-This document describes the Parrot Debugger.
+This document describes F<pdb>, the Parrot Debugger.
=head1 DESCRIPTION
@@ -436,18 +429,18 @@ If C<COMMAND> is omitted, prints a list of the available commands.
=over 4
-=item pdb.c
+=item src/pdb.c
This is the file that will produce the executable.
Nothing fancy here, only the C<main> function.
-=item debug.c
+=item src/debug.c
Most of the debugger is implemented here.
You may want to start from the C<PDB_run_command>
function and go down from there for the real meat.
-=item embed.c
+=item src/embed.c
C<Parrot_debug>, the function which launches the debugger, is
implemented here.
@@ -458,3 +451,14 @@ This defines all the PDB structures, which hold
data used by the debugger.
=back
+
+=head1 HISTORY
+
+=over 4
+
+=item Version 1.0
+
+First version (CVS debug.c revision 1.24), authored by Aldo Calpini
+
+=back
+
View
7 docs/dev/byteorder.dev
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
- Byteorder conversion functions
+=head1 NAME
+
+docs/dev/byteorder.dev - Byteorder Conversion Functions
=head1 Overview
View
7 docs/dev/dod.dev
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Dead object detection (DOD)
+=head1 NAME
+
+docs/dev/dod.dev - Dead object detection (DOD)
=head1 Overview
View
7 docs/dev/events.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-events.c - design notes
+=head1 NAME
+
+docs/dev/events.pod - Design Notes for Events
=head1 VERSION
View
7 docs/dev/infant.dev
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Infant Mortality
+=head1 NAME
+
+docs/dev/infant.dev - Infant Mortality
=head1 Overview
View
22 docs/dev/jit_i386.dev
@@ -1,17 +1,9 @@
-#
-# This file is in POD format; if you're not used to reading POD,
-# you can run the file through "perldoc" for a plain text version.
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
+=head1 NAME
-=head1 TITLE
-
-Parrot JIT (i386/gcc)
-
-=head1 VERSION
-
-=head2 CURRENT
-
-14.02.2003 by Leopold Toetsch
+docs/dev/jit_i386.dev - Parrot JIT (i386/gcc)
=head1 ABSTRACT
@@ -297,3 +289,9 @@ pointer and don't use more the 4 floating point registers at once.
Leopold Toetsch <lt@toetsch.at>
+=head1 VERSION
+
+=head2 CURRENT
+
+14.02.2003 by Leopold Toetsch
+
View
7 docs/dev/longopt.dev
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
- Long option parsing
+=head1 NAME
+
+docs/dev/longopt.dev - Long option parsing
=head1 SUMMARY
View
7 docs/dev/pmc_freeze.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-pmc_freeze.c - design notes
+=head1 NAME
+
+docs/dev/pmc_freeze.pod - Freeze/Thaw Design Notes
=head1 VERSION
View
7 docs/dev/rx.dev
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-rx.c / rx.h
+=head1 NAME
+
+docs/dev/rx.dev - rx.c and rx.h
=head1 SUMMARY
View
47 docs/embed.pod
@@ -1,34 +1,37 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
+
+=head1 NAME
embed.pod - Parrot embedding system
=head1 SYNOPSIS
- #include "parrot/embed.h"
-
- int main(int argc, char *argv[]) {
- Parrot_Interp interp;
- Parrot_PackFile pf;
- char *bcfile="program.pbc";
+ #include "parrot/embed.h"
+
+ int main(int argc, char *argv[]) {
+ Parrot_Interp interp;
+ Parrot_PackFile pf;
+ char *bcfile="program.pbc";
- argc--; argv++; /* skip the program name */
-
- interp=Parrot_new();
- Parrot_init(interp);
+ argc--; argv++; /* skip the program name */
+
+ interp=Parrot_new();
+ Parrot_init(interp);
- if(PARROT_JIT_CAPABLE) {
- Parrot_setflags(interp, PARROT_JIT_FLAG, NULL); /* activate JIT */
- }
+ if(PARROT_JIT_CAPABLE) {
+ Parrot_setflags(interp, PARROT_JIT_FLAG, NULL); /* activate JIT */
+ }
- pf=Parrot_readbc(interp, bcfile);
- Parrot_loadbc(interp, pf);
+ pf=Parrot_readbc(interp, bcfile);
+ Parrot_loadbc(interp, pf);
- Parrot_runcode(interp, argc, argv); /* argc and argv as seen by the bytecode file */
+ Parrot_runcode(interp, argc, argv); /* argc and argv as seen by the bytecode file */
- Parrot_destroy(interp);
-
- return 0;
- }
+ Parrot_destroy(interp);
+
+ return 0;
+ }
=head1 FILES
@@ -212,6 +215,6 @@ B<XXX> At the moment, it just leaks most of it.
F<embed.c> and F<embed.h> for the implementation.
-F<test_main.c> for Parrot's use of the embedding system.
+F<src/test_main.c> for Parrot's use of the embedding system.
=cut
View
54 docs/faq.pod
@@ -1,30 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Parrot FAQ - Frequently Asked Questions
+=head1 NAME
-=head1 VERSION
-
-=over 4
-
-=item Revision 0.5 - 04 September 2002
-
-=item Revision 0.4 - 26 August 2002
-
-Fixed up the licensing bits
-
-=item Revision 0.3 - 13 March 2002
-
-Translated to POD and added "Why aren't we using external tool or library I<X>?"
-
-=item Revision 0.2 - 03 December 2001
-
-Added the "Parrot and Perl" section and "Why Re-implement Perl". Incorporated Dan's Q&A items.
-
-=item Revision 0.1 - 03 December 2001
-
-Adopted from Simon Cozens's article, "Parrot: A Cross-Language Virtual Machine Architecture".
-
-=back
+docs/faq.pod - Parrot FAQ
=head1 GENERAL QUESTIONS
@@ -439,3 +418,28 @@ be there: http://www.csse.monash.edu.au/~damian/papers/#Superpositions
Really.: http://developer.apple.com/techpubs/mac/PPCSoftware/PPCSoftware-13.html
=cut
+
+=head1 VERSION
+
+=over 4
+
+=item Revision 0.5 - 04 September 2002
+
+=item Revision 0.4 - 26 August 2002
+
+Fixed up the licensing bits
+
+=item Revision 0.3 - 13 March 2002
+
+Translated to POD and added "Why aren't we using external tool or library I<X>?"
+
+=item Revision 0.2 - 03 December 2001
+
+Added the "Parrot and Perl" section and "Why Re-implement Perl". Incorporated Dan's Q&A items.
+
+=item Revision 0.1 - 03 December 2001
+
+Adopted from Simon Cozens's article, "Parrot: A Cross-Language Virtual Machine Architecture".
+
+=back
+
View
41 docs/gettingstarted.pod
@@ -1,30 +1,18 @@
-=head1 NAME
-
-Parrot Developer FAQ - Getting started with Parrot? Learn the ins and outs of
-Parrot development.
-
-=head1 VERSION
-
-=over 4
-
-=item Revision 0.1 - 27 July 2002
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Written to prepare for the fallout from TPC 6.
+=head1 NAME
-=back
+docs/gettingstarted.pod - Parrot Developer FAQ
=head1 DEVELOPER FAQ
-
-
=head2 I'm interested in helping out. What should I do?
You're already on the right track. This FAQ should help you find everything
you need to become an active member of the Parrot community. Just look
through the questions below and read the ones that apply to you.
-
-
=head2 Where can I get Parrot?
=over 4
@@ -69,7 +57,6 @@ For the Parrot CVS website with the above instructions, check out:
http://cvs.perl.org/
-
=head2 Now that I've got Parrot, what do I do?
Now that you've downloaded Parrot, you probably want to try it out. All you
@@ -95,8 +82,6 @@ your system.
=back
-
-
=head2 Where's the Parrot documentation?
Well, Parrot documentation is a great place to contribute, should you be
@@ -105,6 +90,14 @@ either help us fix them, or let us know where we should fix them. Luckily,
all of the current Parrot documentation is included along with the Parrot
distribution, in the /docs/ directory.
+There is also some experimental auto-generated HTML documentation
+available by running the following command in the Parrot distribution's
+root directory:
+
+ % perl tools/docs/write_docs.pl -s -d
+
+To view the HTML documentation start with the page F<docs/html/index.html>.
+
There are a few categories of documentation, each with different intents.
It'll probably help to be aware of them before you go digging in. I highly
suggest you check out F</docs/pdds/pdd07_codingstd.pod> for guidelines on
@@ -349,5 +342,15 @@ http://tinderbox.perl.org/bonsai/rview.cgi?cvsroot=/home/tinder/perlcvs&dir=parr
=back
+=head1 VERSION
+
+=over 4
+
+=item Revision 0.1 - 27 July 2002
+
+Written to prepare for the fallout from TPC 6.
+
+=back
+
=cut
View
11 docs/glossary.pod
@@ -1,12 +1,9 @@
-=pod
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-=head1 TITLE
+=head1 NAME
-Parrot Glossary
-
-=head1 ID
-
-$Id$
+docs/glossary.pod - Parrot Glossary
=head1 SUMMARY
View
7 docs/intro.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-The Parrot Primer
+=head1 NAME
+
+docs/intro.pod - The Parrot Primer
=head1 Welcome to Parrot
View
185 docs/jit.pod
@@ -1,24 +1,9 @@
-#
-# This file is in POD format; if you're not used to reading POD,
-# you can run the file through "perldoc" for a plain text version.
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
+=head1 NAME
-=head1 TITLE
-
-Parrot JIT Subsystem
-
-=head1 VERSION
-
-=head2 CURRENT
-
- Maintainer: Daniel Grunblatt
- Class: Internals
- PDD Number: 8
- Version: 1.3
- Status: Developing
- Last Modified: 26 Nov 2002
- PDD Format: 1
- Language:English
+docs/jit.pod - Parrot JIT Subsystem
=head1 ABSTRACT
@@ -138,21 +123,21 @@ the file and the defines must therefore follow a specific syntax.
=head2 Overall structure
- #if JIT_EMIT
+ #if JIT_EMIT
- ... emit code
+ ... emit code
- #else
+ #else
- ... defines
+ ... defines
- #ifndef JIT_IMCC
+ #ifndef JIT_IMCC
- ... initialization of maps
- ... and possibly private static functions
+ ... initialization of maps
+ ... and possibly private static functions
- #endif
- #endif
+ #endif
+ #endif
=head2 Defines
@@ -205,21 +190,21 @@ for mapped registers and positive numbers for non mapped parrot
registers. To use this feature, the definition of mapped registers can
be redefined like so:
- #define MAP(i) OMAP(i)
- #undef MAP
- #define MAP(i) (i) >= 0 : 0 ? OMAP(i)
+ #define MAP(i) OMAP(i)
+ #undef MAP
+ #define MAP(i) (i) >= 0 : 0 ? OMAP(i)
=item EXTCALL
This macro, if defined can override, what is to be considered an
external function. The default definition is:
- # define EXTCALL(op) (op_jit[*(op)].extcall)
+ # define EXTCALL(op) (op_jit[*(op)].extcall)
JIT/i386 has jitted vtable functions, where extcall is the vtable
entry number and redefines B<EXTCALL> to:
- # define EXTCALL(op) (op_jit[*(op)].extcall == 1)
+ # define EXTCALL(op) (op_jit[*(op)].extcall == 1)
=back
@@ -335,20 +320,20 @@ for this jit function.
Example:
TEMPLATE Parrot_set_x_ic {
- if (MAP[1]) {
- jit_emit_mov_ri<_N>(NATIVECODE, MAP[1], <typ>_CONST[2]);
- }
- else {
- jit_emit_mov_mi<_N>(NATIVECODE, &INT_REG[1], <typ>_CONST[2]);
- }
+ if (MAP[1]) {
+ jit_emit_mov_ri<_N>(NATIVECODE, MAP[1], <typ>_CONST[2]);
+ }
+ else {
+ jit_emit_mov_mi<_N>(NATIVECODE, &INT_REG[1], <typ>_CONST[2]);
+ }
}
Parrot_set_i_ic {
- Parrot_set_x_ic s/<_N>/_i/ s/<typ>/*INT/
+ Parrot_set_x_ic s/<_N>/_i/ s/<typ>/*INT/
}
Parrot_set_n_ic {
- Parrot_set_x_ic s/<_N>/_ni/ s/<typ>/&INT/ s/INT_R/NUM_R/
+ Parrot_set_x_ic s/<_N>/_ni/ s/<typ>/&INT/ s/INT_R/NUM_R/
}
The jit function B<Parrot_set_i_ic> is based on the template
@@ -477,51 +462,51 @@ B<Intel x86 assembly version of the Parrot ops:>
B<Parrot_jit_begin>
- 0x817ddd0 <jit_func>: push %ebp
- 0x817ddd1 <jit_func+1>: mov %esp,%ebp
- 0x817ddd3 <jit_func+3>: push %ebx
- 0x817ddd4 <jit_func+4>: push %esi
- 0x817ddd5 <jit_func+5>: push %edi
+ 0x817ddd0 <jit_func>: push %ebp
+ 0x817ddd1 <jit_func+1>: mov %esp,%ebp
+ 0x817ddd3 <jit_func+3>: push %ebx
+ 0x817ddd4 <jit_func+4>: push %esi
+ 0x817ddd5 <jit_func+5>: push %edi
normal function header till here, now push interpreter
- 0x817ddd6 <jit_func+6>: push $0x8164420
+ 0x817ddd6 <jit_func+6>: push $0x8164420
get jit function table to %ebp and
jump to first instruction
- 0x817dddb <jit_func+11>: mov 0xc(%ebp),%eax
- 0x817ddde <jit_func+14>: mov $0x81773f0,%ebp
- 0x817dde3 <jit_func+19>: sub $0x81774a8,%eax
- 0x817dde9 <jit_func+25>: jmp *%ds:0x0(%ebp,%eax,1)
+ 0x817dddb <jit_func+11>: mov 0xc(%ebp),%eax
+ 0x817ddde <jit_func+14>: mov $0x81773f0,%ebp
+ 0x817dde3 <jit_func+19>: sub $0x81774a8,%eax
+ 0x817dde9 <jit_func+25>: jmp *%ds:0x0(%ebp,%eax,1)
B<set_i_ic>
- 0x817ddee <jit_func+30>: mov $0x8,%edi
+ 0x817ddee <jit_func+30>: mov $0x8,%edi
B<set_i_i>
- 0x817ddf3 <jit_func+35>: mov %edi,%ebx
+ 0x817ddf3 <jit_func+35>: mov %edi,%ebx
B<Parrot_jit_save_registers>
- 0x817ddf5 <jit_func+37>: mov %edi,0x8164420
- 0x817ddfb <jit_func+43>: mov %ebx,0x8164428
+ 0x817ddf5 <jit_func+37>: mov %edi,0x8164420
+ 0x817ddfb <jit_func+43>: mov %ebx,0x8164428
B<Parrot_jit_normal_op>
- 0x817de01 <jit_func+49>: push $0x81774c0
- 0x817de06 <jit_func+54>: call 0x804be00 <Parrot_print_i>
- 0x817de0b <jit_func+59>: add $0x4,%esp
+ 0x817de01 <jit_func+49>: push $0x81774c0
+ 0x817de06 <jit_func+54>: call 0x804be00 <Parrot_print_i>
+ 0x817de0b <jit_func+59>: add $0x4,%esp
B<Parrot_jit_end>
- 0x817de0e <jit_func+62>: add $0x4,%esp
- 0x817de14 <jit_func+68>: pop %edi
- 0x817de16 <jit_func+70>: pop %ebx
- 0x817de18 <jit_func+72>: pop %esi
- 0x817de1a <jit_func+74>: pop %ebp
- 0x817de1c <jit_func+76>: ret
+ 0x817de0e <jit_func+62>: add $0x4,%esp
+ 0x817de14 <jit_func+68>: pop %edi
+ 0x817de16 <jit_func+70>: pop %ebx
+ 0x817de18 <jit_func+72>: pop %esi
+ 0x817de1a <jit_func+74>: pop %ebp
+ 0x817de1c <jit_func+76>: ret
Please note the reverse argument direction. PASM and JIT notations use
I<dest,src,src>, while F<gdb> and the internal macros in F<jit_emit.h>
@@ -536,18 +521,18 @@ format, s. B<info stabs> for more (or less :-()
The following script calls F<ddd> (the graphic debugger fronted) and
attaches the symbol file, after it got built in F<build_asm>.
- # dddp
- # run ddd parrot with given file
- # gdb confirmations should be off
- parrot -o $1.pbc -d $1.pasm
- echo "b runops_jit
- r -d -j $1.pbc
- n
- add-symbol-file $1.o 0
- s
- " > .ddd
+ # dddp
+ # run ddd parrot with given file
+ # gdb confirmations should be off
+ parrot -o $1.pbc -d $1.pasm
+ echo "b runops_jit
+ r -d -j $1.pbc
+ n
+ add-symbol-file $1.o 0
+ s
+ " > .ddd
- ddd --command .ddd parrot &
+ ddd --command .ddd parrot &
Run this with e.g. I<dddp t/op/jit_2>, then turn on the register status,
I<step> or I<nexti> through the source, or set break points as with any
@@ -573,24 +558,24 @@ these tests.
(ddd shows above source code and assembly (startup code snipped):
- 0x815de46 <jit_func+30>: mov $0xa,%ebx
- 0x815de4b <jit_func+35>: fldl 0x81584c0
- 0x815de51 <jit_func+41>: fstp %st(2)
- 0x815de53 <jit_func+43>: mov %ebx,0x8158098
- 0x815de59 <jit_func+49>: fld %st(1)
- 0x815de5b <jit_func+51>: fstpl 0x8158120
- 0x815de61 <jit_func+57>: push $0x815cd90
- 0x815de66 <jit_func+62>: call 0x804db90 <Parrot_set_s_sc>
- 0x815de6b <jit_func+67>: add $0x4,%esp
- 0x815de6e <jit_func+70>: push $0x815cd9c
- 0x815de73 <jit_func+75>: call 0x804bcd0 <Parrot_print_sc>
- 0x815de78 <jit_func+80>: add $0x4,%esp
- 0x815de7b <jit_func+83>: add $0x4,%esp
- 0x815de81 <jit_func+89>: pop %edi
- 0x815de83 <jit_func+91>: pop %ebx
- 0x815de85 <jit_func+93>: pop %esi
- 0x815de87 <jit_func+95>: pop %ebp
- 0x815de89 <jit_func+97>: ret
+ 0x815de46 <jit_func+30>: mov $0xa,%ebx
+ 0x815de4b <jit_func+35>: fldl 0x81584c0
+ 0x815de51 <jit_func+41>: fstp %st(2)
+ 0x815de53 <jit_func+43>: mov %ebx,0x8158098
+ 0x815de59 <jit_func+49>: fld %st(1)
+ 0x815de5b <jit_func+51>: fstpl 0x8158120
+ 0x815de61 <jit_func+57>: push $0x815cd90
+ 0x815de66 <jit_func+62>: call 0x804db90 <Parrot_set_s_sc>
+ 0x815de6b <jit_func+67>: add $0x4,%esp
+ 0x815de6e <jit_func+70>: push $0x815cd9c
+ 0x815de73 <jit_func+75>: call 0x804bcd0 <Parrot_print_sc>
+ 0x815de78 <jit_func+80>: add $0x4,%esp
+ 0x815de7b <jit_func+83>: add $0x4,%esp
+ 0x815de81 <jit_func+89>: pop %edi
+ 0x815de83 <jit_func+91>: pop %ebx
+ 0x815de85 <jit_func+93>: pop %esi
+ 0x815de87 <jit_func+95>: pop %ebp
+ 0x815de89 <jit_func+97>: ret
(gdb) n
(gdb) n
(gdb) n
@@ -603,3 +588,17 @@ these tests.
3, strstart = 0x815ad30 "abc"}
(gdb) p &I0
$4 = (INTVAL *) 0x8158098
+
+=head1 VERSION
+
+=head2 CURRENT
+
+ Maintainer: Daniel Grunblatt
+ Class: Internals
+ PDD Number: 8
+ Version: 1.3
+ Status: Developing
+ Last Modified: 26 Nov 2002
+ PDD Format: 1
+ Language:English
+
View
113 docs/memory_internals.pod
@@ -1,10 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Parrot - Memory Internals
+=head1 NAME
-=head1 VERSION
-
-0.0.9 Dec 2002
+docs/memory_internals.pod - Memory Internals
=head1 ABSTRACT
@@ -34,9 +33,9 @@ all pools not alive are considered dead.
A overall layout of the interpreter's memory management looks like so:
typedef struct Parrot_Interp {
- ...
- struct Arenas *arena_base;
- ...
+ ...
+ struct Arenas *arena_base;
+ ...
} Interp;
All object-like things that get allocated during the execution of
@@ -44,36 +43,36 @@ parrot bytecode are managed here.
=head1 Arenas
-I<struct Arenas> holds pointers to different subkinds of managed memory.
+C<struct Arenas> holds pointers to different subkinds of managed memory.
A simplification looks similar to this:
struct Arenas {
- struct Memory_Pool *memory_pool;
- ...
- struct Small_Object_Pool * header_pool;
+ struct Memory_Pool *memory_pool;
+ ...
+ struct Small_Object_Pool * header_pool;
}
-I<Memory_pool> and I<header_pool> are variable and fixed sized pool
+C<Memory_pool> and C<header_pool> are variable and fixed sized pool
pointers respectively.
=head1 Memory_Pool
Here all variable sized items are allocated, managed in linked lists of
-I<Memory_Blocks> - but see below.
+C<Memory_Blocks> - but see below.
=head1 Small_Object_Pool
-This pool manages I<Small_Object_Arena>s, linked together, which provide
+This pool manages C<Small_Object_Arena>s, linked together, which provide
the space for the fixed sized objects.
=head1 Fixed sized items
-These items are either objects by themselves, like a I<PMC>, or are a
-header structure of a variable sized object like a I<STRING>. The
+These items are either objects by themselves, like a C<PMC>, or are a
+header structure of a variable sized object like a C<STRING>. The
general object of this kind is a buffer-like object, which consists of a
-I<Buffer> or a I<PObj> at the beginning and a variable but fixed sized
-part after the buffer structure. Examples of this are a I<STRING> or an
-I<IntList>.
+C<Buffer> or a C<PObj> at the beginning and a variable but fixed sized
+part after the buffer structure. Examples of this are a C<STRING> or an
+C<IntList>.
Buffer-like objects of the same size are maintained in the
I<sized_header_pools>, which manage objects of the same size in one slot.
@@ -93,19 +92,19 @@ interpreter, they just get reused or recycled.
=head2 General structure of a buffer-like item
struct parrot_object_t {
- struct {
- void *bufstart;
- size_t buflen;
- } b;
- unsigned flags;
- ...
+ struct {
+ void *bufstart;
+ size_t buflen;
+ } b;
+ unsigned flags;
+ ...
} PObj;
This does not totally reflect the current implementation, but is the
spirit of the abstraction of current objects. Above structure including
-I<flags> is the current I<Buffer>. With some additional fields like
-I<strstart> and I<bufused>, inserted at the ellipses, you get a I<STRING>.
-Adding a I<vtable> (and some other structure members) yields a I<PMC>.
+C<flags> is the current C<Buffer>. With some additional fields like
+C<strstart> and C<bufused>, inserted at the ellipses, you get a C<STRING>.
+Adding a I<vtable> (and some other structure members) yields a C<PMC>.
=head2 ARENA_DOD_FLAGS
@@ -116,7 +115,7 @@ C<PObj->flags>, meaning that each PMC must be accessed during the DOD run.
An alternative approach is to store the DOD-Flags in the Arenas as a packed
array of bits. This approach will be used if the preprocessor variable
-C<ARENA_DOD_FLAGS> is defined to 1. Here the I<struct Small_Object_Arena> is
+C<ARENA_DOD_FLAGS> is defined to 1. Here the C<struct Small_Object_Arena> is
extended with a pointer to the packed bitarray
struct Small_Object_Arena {
@@ -134,9 +133,9 @@ simply masking out the lower bits of the pointer to the object:
The macro C<GET_ARENA> does the exactly this, including the necessary type
casts to remove warnings. The dod_flags are accessed by getting the element
-number in the arena (this is possible because the object_size is fixed and
-stored in the I<struct Small_Object_Arena>), creating the appropriate
-bitmask by shifting and accessing the right element of dod_flags[].
+number in the arena (this is possible because the C<object_size> is fixed and
+stored in the C<struct Small_Object_Arena>), creating the appropriate
+bitmask by shifting and accessing the right element of C<dod_flags[]>.
n = (object - arena->start_objects) / arena->object_size;
arena->dod_flags[n >> ARENA_FLAG_SHIFT]
@@ -149,13 +148,13 @@ DOD flags.
=head1 Variable sized items
-These items never live alone, they are part of a I<Buffer> structure,
-described above. They are allocated at I<bufstart>. This is, for example,
-used to manage the buffer's free list, where I<bufstart> is used as a pointer
+These items never live alone, they are part of a C<Buffer> structure,
+described above. They are allocated at C<bufstart>. This is, for example,
+used to manage the buffer's free list, where C<bufstart> is used as a pointer
to the next object.
-These items are managed in two different pools: the I<memory_pool> and the
-I<constant_string_pool>. The former holds all variable sized items, while the
+These items are managed in two different pools: the C<memory_pool> and the
+C<constant_string_pool>. The former holds all variable sized items, while the
latter containing the word "string", holds constant strings only, as we
don't have other variable sized constant items to store.
@@ -163,7 +162,7 @@ Here, different memory allocation schemes jump in:
=head2 Copying GC
-A I<memory_pool> gets allocated in big blocks, namely a I<Memory_Block>.
+A C<memory_pool> gets allocated in big blocks, namely a C<Memory_Block>.
When some part is needed, e.g. to store a string, this part is carved out of
the memory block, until this block is used up. If no more space is available in
@@ -186,34 +185,34 @@ C<string_compare()>.
=head2 Defragmentating allocator
An alternative to the above is to use a memory allocator, which is as fast
-as the above and does reuse free()ed items in a memory conserving way.
-Actually, the malloc implementations in some systems' I<libc> efficiently
+as the above and does reuse C<free()>ed items in a memory conserving way.
+Actually, the malloc implementations in some systems' F<libc> efficiently
provide this, such as the glibc malloc based on Doug Lea's allocator.
Using this allocator, all variable sized items are just allocated via a
-plain malloc() call, or resized with realloc(), and after they lose
+plain C<malloc()> call, or resized with C<realloc()>, and after they lose
their existence (ie when DOD detects that the managing buffer
-header is no longer in use) they are free()ed. That's all. The underlying
+header is no longer in use) they are C<free()>ed. That's all. The underlying
allocator collects these pieces, coalesces them if possible to form bigger
pieces, and then puts them on free lists, sorted by size. Eventually, when
a new allocation request arrives, it may give them back to Parrot.
-So here, the variable length I<memory_pool> is unused. You can consider this
+So here, the variable length C<memory_pool> is unused. You can consider this
pool to live inside the allocator.
Buffers allocated this way don't move around, except when reallocated of
course.
-The B<Configure> option I<--gc> allows one to use either method.
+The F<Configure.pl> option C<--gc> allows one to use either method.
=head2 Buffer_Tail and COW
-Both implementations have the same problem to solve: I<STRING>s that get
+Both implementations have the same problem to solve: C<STRING>s that get
copied, or parts of strings as the result of a substr() call, do not
allocate new space in the memory pool to hold this string or part of
-string. They just use a new_string_header() and set up a pointer
-(I<strstart>) pointing somewhere into the original string and remember the
-used length there in I<bufused>.
+string. They just use a C<new_string_header()> and set up a pointer
+(C<strstart>) pointing somewhere into the original string and remember the
+used length there in C<bufused>.
This is all OK, as long as the original and the lazy copy of the string
are not modified. So that's well-known and called COW (copy on write).
@@ -226,12 +225,12 @@ string more then once (your debugger will tell you why...).
Both allocation schemes therefore use a part of the allocated string to
do this bookkeeping.
-Copying GC uses a I<Buffer_Tail> after the end of the actual variable
-length string and marks such COW strings with I<TAIL_moved> and stores
+Copying GC uses a C<Buffer_Tail> after the end of the actual variable
+length string and marks such COW strings with C<TAIL_moved> and stores
the new address in the buffer header, so other users of this string can
be updated to reuse the same string (XXX one or all other users?).
-The malloc()/free() approach stores a refcount at I<bufstart>. During
+The C<malloc()>/C<free()> approach stores a refcount at C<bufstart>. During
DOD all dead users increment the refcount, living users set it to an
huge value. When freeing the buffer, the string is only freed if the
refcount reaches zero.
@@ -259,9 +258,9 @@ refcount reaches zero.
+----------+
Buffer Memory Block
-Now consider, that the I<Interpreter> shall be a I<PMC> living in
-I<Buffer X> of the underlying interpreter and is currently running
-B<perldoc docs/memory_internals.pod>, and then redo this figure, with
+Now consider, that the I<Interpreter> shall be a C<PMC> living in
+C<Buffer X> of the underlying interpreter and is currently running
+F<perldoc docs/memory_internals.pod>, and then redo this figure, with
all the blanks filled in ;-)
=head1 FILES
@@ -281,3 +280,7 @@ up to date - thanks.
=head1 AUTHOR
Leopold Tötsch <lt@toetsch.at>
+
+=head1 VERSION
+
+0.0.9 Dec 2002
View
7 docs/mmd.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Multimethod dispatch for binary opcode functions
+=head1 NAME
+
+docs/mmd.pod - Multimethod dispatch for binary opcode functions
=head1 SYNOPSIS
View
7 docs/native_exec.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Parrot Native Object Execution Subsystem
+=head1 NAME
+
+docs/native_exec.pod - Parrot Native Object Execution Subsystem
=head1 Overview
View
13 docs/overview.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-A Parrot Overview
+=head1 NAME
+
+docs/overview.pod - A Parrot Overview
=head1 The Parrot Interpreter
@@ -68,7 +71,7 @@ of the bytecode can define a set of custom operations that it will use.
These areas will roughly map to compilation units of the original
source; each precompiled module will have its own opcode table.
-For a closer look at Parrot ops, see L<parrot_assembly>.
+For a closer look at Parrot ops, see F<docs/pdds/pdd06_pasm.pod>.
=head1 PMCs
@@ -150,7 +153,7 @@ offset of a given character in a string, and so on. They will, of
course, provide a transcoding function either to the other encodings or
just to Unicode for use as a pivot.
-The string handling API is explained in L<strings>.
+The string handling API is explained in F<docs/strings.pod>.
=head1 Bytecode format
@@ -176,4 +179,4 @@ As we know, the opcode segment is next. This is optionally followed by a
code segment for debugging purposes, which contains a munged form of the
original program file.
-The bytecode format is fully documented in L<parrotbyte>.
+The bytecode format is fully documented in F<docs/parrotbyte.pod>.
View
13 docs/parrot.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Parrot
+=head1 NAME
+
+docs/parrot.pod - Parrot
=head1 The Parrot Bytecode Interpreter
@@ -152,11 +155,11 @@ See:
=over 4
-=item * L<http://dev.perl.org/>
+=item * http://dev.perl.org/
-=item * L<http://cvs.perl.org/>
+=item * http://cvs.perl.org/
-=item * L<http://www.parrotcode.org/>
+=item * http://www.parrotcode.org/
=back
View
23 docs/parrotbyte.pod
@@ -1,10 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-The Parrot Bytecode (PBC) Format
+=head1 NAME
-=head1 VERSION
-
-2003.11.22
+docs/parrotbyte.pod - The Parrot Bytecode (PBC) Format
=head1 Format of the Parrot bytecode
@@ -13,10 +12,11 @@ The Parrot Bytecode (PBC) Format
| Wordsize | Byteorder| Major | Minor |
+----------+----------+----------+----------+
-The wordsize (or opcode_t size) must be 4 (32-bit) or 8 (64 bit).
-The bytecode loader is responsible for transforming the file into the
-VM native wordsize on the fly. For performance, a utility F<pdump> is
-provided to convert PBCs on disk if they cannot be recompiled.
+The wordsize (or C<opcode_t> size) must be 4 (32-bit) or 8 (64 bit). The
+bytecode loader is responsible for transforming the file into the VM
+native wordsize on the fly. For performance, a utility F<pdump> is
+provided to convert PBCs on disk if they cannot be recompiled. See
+F<src/pdump.c> for more information.
Byteorder currently supports two values:
(0-Little Endian, 1-Big Endian)
@@ -296,3 +296,8 @@ B<pdump> utility F<pdump.c>.
Gregor N. Purdy E<lt>gregor@focusresearch.comE<gt>
Format 1 description by Leopold Toetsch E<lt>lt@toetsch.atE<gt>
+
+=head1 VERSION
+
+2003.11.22
+
View
5 docs/porting_intro.pod
@@ -1,6 +1,9 @@
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
+
=head1 NAME
-Parrot Subsystem Porting Introduction
+docs/porting_intro.pod - Parrot Subsystem Porting Introduction
=head1 OVERVIEW
View
7 docs/practical_notes.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Practical Parrot Notes
+=head1 NAME
+
+docs/practical_notes.pod - Practical Parrot Notes
=head1 PURPOSE
View
7 docs/running.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Running Parrot
+=head1 NAME
+
+docs/running.pod - Running Parrot
=head1 Running Parrot code
View
47 docs/strings.pod
@@ -1,26 +1,15 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Parrot Strings
+=head1 NAME
-=head1 HISTORY
-
-=over
-
-=item 4 October 2003
-
-Revised to reflect changes since Buffer/PMC unification.
-
-=back
+docs/strings.pod - Parrot Strings
=head1 ABSTRACT
This document describes how Parrot abstracts the programmer's interface
to string types.
-=head1 ABSTRACT
-
-Parrot Strings are chunked international strings.
-
=head1 OVERVIEW
For various reasons, some of which relate to the sequence-of-integer
@@ -314,18 +303,16 @@ frequent use. The C<transcoders> array is currently not used.
Fill this in later; if anyone wants to implement new encodings at this
stage they must be mad.
-=head1 Work In Progress
-
-Should the following functions be mentioned?
-C<string_append>,
-C<string_from_cstring>,
-C<string_from_int>,
-C<string_from_num>,
-C<string_index>,
-C<string_replace>,
-C<string_set>,
-C<string_str_index>,
-C<string_to_cstring>,
-C<string_to_int>,
-C<string_to_num>,
-C<string_transcode>.
+=head1 SEE ALSO
+
+F<src/string.c>, F<include/parrot/string.h>, F<include/parrot/string_funcs.h>.
+
+=head1 HISTORY
+
+=over
+
+=item 4 October 2003
+
+Revised to reflect changes since Buffer/PMC unification.
+
+=back
View
15 docs/tests.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2003 The Perl Foundation. All Rights Reserved.
+# $Id$
-Testing Parrot
+=head1 NAME
+
+docs/tests.pod - Testing Parrot
=head1 A basic guide to writing tests for Parrot
@@ -47,7 +50,7 @@ in the test code:
output_is(<<'CODE', <<'OUTPUT', "name for test");
##PIR##
$P0 = new Integer
- ...
+ ...
=head2 C source tests
@@ -63,18 +66,18 @@ in the test code:
interpreter = Parrot_new();
if (!interpreter)
- return 1;
+ return 1;
Parrot_init(interpreter);
Parrot_run_native(interpreter, the_test);
printf("done\n");
- fflush(stdout);
+ fflush(stdout);
return 0;
}
static opcode_t*
the_test(Parrot_Interp interpreter,
- opcode_t *cur_op, opcode_t *start)
+ opcode_t *cur_op, opcode_t *start)
{
/* Your test goes here. */
View
37 docs/vtables.pod
@@ -1,6 +1,9 @@
-=head1 TITLE
+# Copyright: 2001-2004 The Perl Foundation. All Rights Reserved.
+# $Id$
-Parrot Vtables
+=head1 NAME
+
+docs/vtables.pod - Parrot Vtables
=head1 Implementing Variable Types with Vtables
@@ -70,30 +73,30 @@ now look at how one is supposed to do this.
=head2 Starting out
-If you're adding data types to the core of Parrot, (and you've
-checked with Dan and/or Steve that you're supposed to be doing so)
-you should be creating a file in the F<classes/> subdirectory; this is
-where all the built-in PMC classes live. (And a good source of examples
-to plunder even if you're not writing a core data type.)
+If you're adding data types to the core of Parrot, (and you've checked
+with Dan that you're supposed to be doing so) you should be creating a
+file in the F<classes/> subdirectory; this is where all the built-in PMC
+classes live. (And a good source of examples to plunder even if you're
+not writing a core data type.)
-You should almost always start by running F<genclass.pl> found in the
-F<classes/> subdirectory to generate a skeleton for the class. Let's
-generate a number type for the beautifully non-existent Fooby language:
+You should almost always start by running F<classes/genclass.pl> to
+generate a skeleton for the class. Let's generate a number type for the
+beautifully non-existent Fooby language:
- perl -I../lib genclass.pl FoobyNumber > foobynumber.pmc
+ % perl -I../lib genclass.pl FoobyNumber > foobynumber.pmc
This will produce a skeleton C file (to be preprocessed by the
-F<pmc2c.pl> program) with stubs for all the methods you need to fill in.
+F<pmc2c2.pl> program) with stubs for all the methods you need to fill in.
The function C<init> allows you to set up anything you need to set up.
Now you'll have to do something a little different depending on whether
you're writing a built-in class or an extension class. If you're writing
a built-in class, then you'll see a reference to
C<enum_class_FoobyNumber> in the C<init> function. For built-in classes,
-this is automatically defined in F<pmc.h> when you run Configure.pl.
+this is automatically defined in F<pmc.h> when you run F<Configure.pl>.
If you're not writing a built-in class, you need to indicate this by
using the 'extension' keyword after the 'pmclass YOURCLASS' declaration
-in classes/YOURCLASS.pmc. Then, change the
+in F<classes/YOURCLASS.pmc>. Then, change the
type of the C<init> function to return C<struct _vtable>, and then
return C<temp_base_vtable> instead of assigning to the
C<Parrot_base_vtables> array.
@@ -108,7 +111,7 @@ Add classes/YOURCLASS.pmc to the MANIFEST
=item 2.
-Rerun Configure.pl to add your new PMC to the set of built-in PMCs.
+Rerun F<Configure.pl> to add your new PMC to the set of built-in PMCs.
=back
@@ -307,6 +310,6 @@ example:
pmclass PackedArray extends Array { ...
-See the POD documentation in classes/pmc2c.pl for a list of useful
+See the POD documentation in F<classes/pmc2c2.pl> for a list of useful
keywords that you may use in the .pmc file. (Run
-C<perldoc -F pmc2c.pl> to view the POD.)
+C<perldoc -F pmc2c2.pl> to view the POD.)
Please sign in to comment.
Something went wrong with that request. Please try again.