Permalink
Browse files

runcores: fix docs, match docs with implementation and vice versa

use docs/running.pod as description for the runcore, debugging and
optimization options.
add missing docs for the runcores.

we already have a new parrot manpage for the rest.  allow the old runcores
in the implementation as described in the docs.
but disable the exec runcore, as it is different from the jit runcore.
there is now side-effect of producing a native executable (as of now).
  • Loading branch information...
Reini Urban
Reini Urban committed Mar 8, 2014
1 parent 8e19822 commit b1de450257b0fce66a9429133322029ecf463068
Showing with 78 additions and 140 deletions.
  1. +42 −110 docs/running.pod
  2. +17 −8 src/embed/api.c
  3. +18 −21 src/runcore/cores.c
  4. +1 −1 src/runcore/main.c
@@ -1,22 +1,27 @@
# Copyright (C) 2001-2012, Parrot Foundation.
# Copyright (C) 2001-2014, Parrot Foundation.
=pod
=head1 NAME
docs/running.pod - Running
docs/running.pod - Parrot runcore, debugging and optimizer options
=head1 SYNOPSIS
parrot [-options] <file> [arguments ...]
parrot -R, --runcore <CORE> -O<level> -D<flags> -d<flags> -t<flags>
=head1 DESCRIPTION
This document describes Parrot's command line options.
parrot -R fast
parrot -R slow
parrot -R trace | -t
parrot -R profiling
parrot -R subprof
parrot --gc-debug
parrot -R jit I<(currently disabled)>
parrot -R exec I<(currently disabled)>
=head1 VERSION
=head1 DESCRIPTION
$Revision$
This document describes Parrot's runcore, debugging and optimizer options.
=head1 ENVIRONMENT
@@ -39,13 +44,9 @@ Turn on the I<--gc-debug> flag.
=over 4
=item -O[level]
Valid optimizer levels: C<-O>, C<-O1>, C<-O2>, C<-Op>, C<-Oc>
=item B<-O>[level]
Valid optimizer levels: C<-O>, C<-O1>, C<-O2>
Valid optimizer levels: C<-O>, C<-O1>, C<-O2>, C<-Op>, C<-Oc>
C<-O1> enables the pre_optimizer, runs before control flow graph (CFG) is built.
It includes strength reduction and rewrites certain if/branch/label constructs.
@@ -55,46 +56,19 @@ removal of unused labels and dead code.
C<-Op> applies C<-O2> to pasm files also.
C<-Oc> does tailcall optimizations.
The old options C<-Oc> and C<-Oj> are currently ineffective.
C<-O> defaults to C<-O1>.
=item -a, --pasm
Assume PASM input on stdin.
=item -c, --pbc
Assume PBC file on stdin, run it.
=item -h, --help
Print command line option summary.
=item --help-debug
Print debugging and tracing flag bits summary.
=item -o outputfile, --output=outputfile
Act like an assembler. Don't run code, unless B<-r> is given too. If the
outputfile ends with F<.pbc>, a PBC file is written. If it ends with F<.pasm>,
a PASM output is generated, even from PASM input.
=item --output-pbc
Act like an assembler, but always output bytecode, even if the output file does
not end in F<.pbc>
=item -r, --run-pbc
Only useful after C<-o> or C<--output-pbc>. Run the program from the compiled
in-memory image. If two C<-r> options are given, the F<.pbc> file is read from
disc and run. This is mainly needed for tests.
=item -y, --yydebug
Turn on yydebug in F<yacc>/F<bison>.
Turn on yydebug in F<yacc>/F<bison>. Same as -d0004
=item -v, --verbose
@@ -106,23 +80,12 @@ Turn on compiler verbosity.
Turn on compiler debug flags. I<See> C<parrot --help-debug> for available flag bits.
=item -V, --version
Print version information and exit.
=item -E, --pre-process-only
Preprocess source file (expand macros) and print result to stdout:
$ parrot -E t/op/macro_10.pasm
$ parrot -E t/op/macro_10.pasm | parrot -- -
=back
=head2 Runcore Options
These options select the runcore, which is useful for performance tuning and
debugging. See L<About runcores> for details.
debugging. See L<ABOUT RUNCORES> for details.
=over 4
@@ -136,26 +99,40 @@ may be available on your system:
slow, bounds bounds checking core
trace bounds checking core w/ trace info (see 'parrot --help-debug')
trace bounds checking core with trace info
profiling see F<docs/dev/profilling.pod>
profiling Rudimentary profiling support.
See L<docs/dev/profiling.pod>
subprof subroutine-level profiler
(see POD in F<src/runcore/subprof.c>)
subprof Better subroutine-level profilers
subprof_sub
subprof_hll
subprof_ops
See POD in F<src/runcore/subprof.c>
The C<jit>, C<switch-jit>, and C<cgp-jit> options are currently aliases for the
C<fast>, C<switch>, and C<cgp> options, respectively. We do not recommend
their use in new code; they will continue working for existing code per our
deprecation policy.
gc_debug Does a full GC on each op.
Older currently ignored options include:
jit, switch-jit, cgp-jit, switch, cgp, function, exec
We do not recommend their use in new code; they will continue working
for existing code per our deprecation policy. The options function,
cgp, switch, and jit, switch-jit, cgp-jit are currently aliases for
fast.
The additional internal C<debugger> runcore is used by debugger frontends.
See F<src/runcore/cores.c> for details.
=item -p, --profile
Run with the slow core and print an execution profile.
=item -t, --trace
Run with the slow core and print trace information to B<stderr>. See C<parrot
--help-debug> for available flag bits.
Run with the trace core and print trace information to B<stderr>.
See C<parrot --help-debug> for available flag bits.
=back
@@ -172,11 +149,6 @@ Turn on warnings. See C<parrot --help-debug> for available flag bits.
Turn on interpreter debug flag. See C<parrot --help-debug> for available flag
bits.
=item --hash-seed <hexnum>
Sets the hash seed to the provided value. Only useful for debugging
intermittent failures, and harmful in production.
=item --gc-debug
Turn on GC (Garbage Collection) debugging. This imposes some stress on the GC
@@ -193,44 +165,8 @@ quickly become exhausted.
Free all memory of the last interpreter. This is useful when running leak
checkers.
=item -., --wait
Read a keystroke before starting. This is useful when you want to attach a
debugger on platforms such as Windows.
=item --runtime-prefix
Print the runtime prefix path and exit.
=item -L path
Add C<path> to the library search path
=item --numthreads <number>
Overrides the automatically detected number of CPU cores to set the
number of OS threads. Minimum number: 2
=back
=head2 <file>
If the file ends in F<.pbc> it will be interpreted immediately.
If the file ends in F<.pasm>, then it is parsed as PASM code. Otherwise, it is
parsed as PIR code. In both cases, it will then be run, unless the C<-o> flag
was given.
If the C<file> is a single dash, input from C<stdin> is read.
=head2 [arguments ...]
Optional arguments passed to the running program as ARGV. The program is
assumed to know what to do with these.
=head1 GENERATED FILES
=head1 ABOUT RUNCORES
The runcore (or runloop) tells Parrot how to find the C code that implements
@@ -284,8 +220,4 @@ full bounds checking, and also printing runtime information to stderr.
ass ... assemble sourcefile
obj .. produce native (ELF) object file for the EXEC subsystem
=head1 FILES
F<frontend/parrot/main.c>
=cut
@@ -187,22 +187,31 @@ Parrot_api_set_runcore(Parrot_PMC interp_pmc, ARGIN(const char * corename),
else {
if (STREQ(corename, "slow") || STREQ(corename, "bounds"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "slow"));
else if (STREQ(corename, "fast") || STREQ(corename, "jit") || STREQ(corename, "function"))
else if (STREQ(corename, "fast")
|| STREQ(corename, "function")
|| STREQ(corename, "cgp")
|| STREQ(corename, "switch"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "fast"));
else if (STREQ(corename, "subprof_sub"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "subprof_sub"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "subprof_hll") || STREQ(corename, "subprof"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "subprof_hll"));
else if (STREQ(corename, "subprof_ops"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "subprof_ops"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
#if 0
else if (STREQ(corename, "exec"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "exec"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
#endif
else if (STREQ(corename, "trace"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "slow"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "profiling"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "profiling"));
else if (STREQ(corename, "gcdebug"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "gcdebug"));
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "gc_debug"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, corename));
else if (STREQ(corename, "jit")
|| STREQ(corename, "cgp-jit")
|| STREQ(corename, "switch-jit"))
Parrot_runcore_switch(interp, Parrot_str_new_constant(interp, "fast"));
else
Parrot_ex_throw_from_c_args(interp, NULL, 1, "Invalid runcore type %s", corename);
}
@@ -11,10 +11,10 @@ During execution, the runcore is like the heart of Parrot. The runcore
controls calling the various opcodes with the correct data, and making
sure that program flow moves properly. Some runcores, such as the
I<precomputed C goto runcore> are optimized for speed and don't perform
many tasks beyond finding and dispatching opcodes. Other runcores,
such as the I<GC-Debug>, I<debug> and I<profiling> runcores help with
typical software maintenance and analysis tasks. We'll talk about all
of these throughout the chapter.
many tasks beyond finding and dispatching opcodes. Other runcores, such as
the I<trace>, I<gc_debug>, I<debugger> and I<profiling> runcores help with
typical software maintenance and analysis tasks. We'll talk about all of
these throughout the chapter.
Runcores must pass execution to each opcode in the incoming bytecode
stream. This is called I<dispatching> the opcodes. Because the different
@@ -211,24 +211,20 @@ printed to the STDERR output for later analysis.
=head2 GC Debug Core
Parrot's garbage collector has been known as a weakness in the system
for several years. In fact, the garbage collector and memory management
subsystem was one of the last systems to be improved and rewritten before
the release of version 1.0. It's not that garbage collection isn't
important, but instead that it was so hard to do earlier in the project.
The older Parrot's garbage collectors has been known as weakness in the
system for several years. Early on when the GC was such a weakness, and
later when the GC was under active development, it was useful to have an
operational mode that would really exercise the GC and find bugs that
otherwise could hide by sheer chance. The GC debug runcore was this
tool. The core executes a complete collection iteration between every
single opcode. The throughput performance is terrible, but that's not the
point: it's almost guaranteed to find problems in the memory system if
they exist.
Early on when the GC was such a weakness, and later when the GC was under
active development, it was useful to have an operational mode that would
really exercise the GC and find bugs that otherwise could hide by sheer
chance. The GC debug runcore was this tool. The core executes a complete
collection iteration between every single opcode. The throughput
performance is terrible, but that's not the point: it's almost guaranteed
to find problems in the memory system if they exist.
=head2 Debugger Core
=head2 Debug Core
The debug core works like a normal software debugger, such as GDB. The
debug core executes each opcode, and then prompts the user to enter a
The debugger core works like a normal software debugger, such as GDB. The
debugger core executes each opcode, and then prompts the user to enter a
command. These commands can be used to continue execution, step to the
next opcode, or examine and manipulate data from the executing program.
@@ -678,7 +674,7 @@ runops_gc_debug_core(PARROT_INTERP, SHIM(Parrot_runcore_t *runcore), ARGIN(opcod
=item C<static opcode_t * runops_debugger_core(PARROT_INTERP, Parrot_runcore_t
*runcore, opcode_t *pc)>
Used by the debugger, under construction
Used by the debugger, under construction.
=cut
@@ -762,6 +758,7 @@ get_core_op_lib_init(SHIM_INTERP, ARGIN(Parrot_runcore_t *runcore))
*runcore, opcode_t *pc)>
Runs the native executable version of the specified opcode.
Currently disabled.
=cut
@@ -70,7 +70,7 @@ Parrot_runcore_init(PARROT_INTERP)
Parrot_runcore_fast_init(interp);
Parrot_runcore_subprof_init(interp);
Parrot_runcore_exec_init(interp);
/* Parrot_runcore_exec_init(interp); */
Parrot_runcore_gc_debug_init(interp);
Parrot_runcore_debugger_init(interp);

0 comments on commit b1de450

Please sign in to comment.