From b1de450257b0fce66a9429133322029ecf463068 Mon Sep 17 00:00:00 2001 From: Reini Urban Date: Sat, 8 Mar 2014 14:32:13 -0600 Subject: [PATCH] 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). --- docs/running.pod | 152 ++++++++++++-------------------------------- src/embed/api.c | 25 +++++--- src/runcore/cores.c | 39 ++++++------ src/runcore/main.c | 2 +- 4 files changed, 78 insertions(+), 140 deletions(-) diff --git a/docs/running.pod b/docs/running.pod index 98ff4a97a2..3d23349f13 100644 --- a/docs/running.pod +++ b/docs/running.pod @@ -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] [arguments ...] + parrot -R, --runcore -O -D -d -t -=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/F. +Turn on yydebug in F/F. Same as -d0004 =item -v, --verbose @@ -106,23 +80,12 @@ Turn on compiler verbosity. Turn on compiler debug flags. I C 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 for details. +debugging. See L for details. =over 4 @@ -136,17 +99,31 @@ 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 + profiling Rudimentary profiling support. + See L - subprof subroutine-level profiler - (see POD in F) + subprof Better subroutine-level profilers + subprof_sub + subprof_hll + subprof_ops + See POD in F -The C, C, and C options are currently aliases for the -C, C, and C 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 runcore is used by debugger frontends. + +See F for details. =item -p, --profile @@ -154,8 +131,8 @@ Run with the slow core and print an execution profile. =item -t, --trace -Run with the slow core and print trace information to B. See C for available flag bits. +Run with the trace core and print trace information to B. +See C for available flag bits. =back @@ -172,11 +149,6 @@ Turn on warnings. See C for available flag bits. Turn on interpreter debug flag. See C for available flag bits. -=item --hash-seed - -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 to the library search path - -=item --numthreads - -Overrides the automatically detected number of CPU cores to set the -number of OS threads. Minimum number: 2 - - =back -=head2 - -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 is a single dash, input from C 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 - =cut diff --git a/src/embed/api.c b/src/embed/api.c index 5108a34757..06e5e9ec8f 100644 --- a/src/embed/api.c +++ b/src/embed/api.c @@ -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); } diff --git a/src/runcore/cores.c b/src/runcore/cores.c index cbebd95005..f160bcf7fe 100644 --- a/src/runcore/cores.c +++ b/src/runcore/cores.c @@ -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 are optimized for speed and don't perform -many tasks beyond finding and dispatching opcodes. Other runcores, -such as the I, I and I 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, I, I and I 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 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 -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 diff --git a/src/runcore/main.c b/src/runcore/main.c index e380d1245f..695429a016 100644 --- a/src/runcore/main.c +++ b/src/runcore/main.c @@ -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);