Browse files

remove some references to PASM in the docs

  • Loading branch information...
coke committed May 1, 2012
1 parent 62008a2 commit eb1015f17871471a4698d2034ba61ab981ce268e
@@ -284,10 +284,7 @@ Preprocess source file (expand macros) and print result to C<stdout>:
=over 11
-unless the B<-r> is supplied as well. If 'outputfile' ends with F<.pbc>,
-'parrot' will write a PBC file. If it ends with F<.pasm>, 'parrot' will output
-a PASM file, even from PASM input. This can be useful when needing to check
-various optimizations, including C<-Op>.
+unless the B<-r> is supplied as well.
@@ -156,8 +156,8 @@ L<>
=item IMCC
-Intermediate Code Compiler: the component of parrot that compiles PASM
-and PIR into bytecode.
+Intermediate Code Compiler: the component of parrot that compiles PIR into
See also L<"PIR">.
@@ -193,7 +193,7 @@ See also L<"PCT">.
=item PBC
Parrot Bytecode. The name for the "executable" files that can be passed to the
-Parrot interpreter for immediate execution (although PASM and IMC files can be
+Parrot interpreter for immediate execution (although PIR files can be
executed directly, too).
See also L<"Packfile">.
@@ -293,19 +293,6 @@ You now know everything you need to know about PIR. Everything else you
read or learn about PIR will use one of these fundamental language
structures. The rest is vocabulary.
-=begin sidebar Parrot Assembly Language
-Parrot Assembly Language (PASM) is another low-level language native to the
-virtual machine. PASM is a pure assembly language, with none of the syntactic
-sugar that makes PIR friendly for library development. PASM's primary purpose
-is to act as a plain English representation of the bytecode format. Its
-typical use is for debugging, rather than for writing libraries. Use PIR or a
-higher-level language for development tasks.
-PASM files use the F<.pasm> file extension.
-=end sidebar
# Local variables:
@@ -766,7 +766,7 @@ Create a new C<Env> PMC and access it like a hash.
-See F<config_lib.pasm> for all the keys in the config hash - or iterate over
+See F<config_lib.pir> for all the keys in the config hash - or iterate over
the config hash.
@@ -58,7 +58,7 @@ garbage collector.
-Let's say you have written (or generated) a huge .pasm or .pir file. It's not
+Let's say you have written (or generated) a huge PIR file. It's not
working. You'd like some help in figuring out why.
=head2 parrot_debugger
@@ -37,7 +37,7 @@ To start the debugger type:
parrot_debugger file.pbc
That is, F<parrot_debugger> takes exactly one argument, which is the Parrot file that
-you're going to debug. This file may be Parrot bytecode (*.pbc), PASM source code (*.pasm)
+you're going to debug. This file may be Parrot bytecode (*.pbc)
or PIR (*.pir). F<parrot_debugger> will automatically load and disassemble the
bytecode file for you.
@@ -23,7 +23,7 @@ and means the same thing as IMC. PIR files use the extension C<.pir>.
PIR is an intermediate language that compiles either directly to Parrot Byte
code. It is a possible target language for compilers targeting
the Parrot Virtual Machine. PIR is halfway between
-a High Level Language (HLL) and Parrot Assembly (PASM).
+a High Level Language (HLL) and Parrot Bytecode.
IMCC is the current implementation of the PIR language.
@@ -65,65 +65,13 @@ of Parrot's ops are polymorphic, IMCC punts most of the type checking and
method dispatch to runtime. This allows extremely fast compile times, which
is what scripters need.
-=head2 How Is PIR different than Parrot Assembly language?
-PASM is an assembly language, raw and low-level. PASM does exactly what you
-say, and each PASM instruction represents a single VM opcode. Assembly
-language can be tough to debug, simply due to the amount of instructions that
-a high-level compiler generates for a given construct. Assembly language
-typically has no concept of basic blocks, namespaces, variable tracking, etc.
-You must track your register usage and take care of saving/restoring values
-in cases where you run out of registers. This is called spilling.
-PIR is medium level and a bit more friendly to write or debug. IMCC also has
-a builtin register allocator and spiller. PIR has the concept of a
-"subroutine" unit, complete with local variables and high-level sub call
-syntax. PIR also allows unlimited symbolic registers. It will take care of
-assigning the appropriate register to your variables and will usually find the
-most efficient mapping so as to use as few registers as possible for a given
-piece of code. If you use more registers than are currently available, IMCC
-will generate instructions to save/restore (spill) the registers for you.
-This is a significant piece of every compiler.
-While it is possible to write more efficient code by hand directly in PASM,
-it is rare. PIR is still very close to PASM as far as granularity. It is also
-common for IMCC to generate instructions that use less registers than
-handwritten PASM. This is good for cache performance.
-=head2 Why should I target PIR instead of PASM?
-Several reasons. PIR is so much easier to read, understand and debug. When
-passing snippets back and forth on the Parrot internals list, IMC is preferred
-since the code is much shorter than the equivalent PASM. In some cases it is
-necessary to debug the PASM code as bugs in IMCC are found.
-Hand writing and debugging of code aside, most PIR code will be mostly
-compiler generated. In this respect, the most important technical reason to
-use PIR is the amount of abstraction it provides. PIR now completely hides
-the Parrot calling conventions. This allows Parrot to change somewhat without
-impacting existing compilers. The workload is balanced between the IMCC
-team and the compiler authors. The term "modular" springs to mind.
-Since development on the old assembler has stopped, IMCC will be the best way
-to compile bytecode classes complete with metadata and externally linkable
-symbols. It will still be possible to construct classes on the fly with PASM,
-but PIR's higher level directives allow it to do compile time construction of
-certain things and pack them into the bytecode in a way that does not have an
-equivalent set of Parrot instructions. The PASM assembler may or may not ever
-catch up with these features.
-=head2 Shouldn't I rather target PAST?
+=head2 Shouldn't I rather target PAST than PIR?
Yes, preferably using the PCT, the Parrot Compiler Toolkit.
=head2 Can I use IMCC without Parrot?
-Not yet. IMCC is currently tightly integrated to the Parrot bytecode format.
-An old idea is to rework IMCC's modularity to make it easy to run separately, but
-this is not a top priority since IMCC currently only targets Parrot.
-Eventually IMCC will contain a config option to build without linking the
-Parrot VM, but IMCC must be able to do lookups of opcodes so it will require
-some sort of static opcode metadata.
+No. IMCC is currently tightly integrated to the Parrot bytecode format.
@@ -148,37 +96,13 @@ For more examples see the PIR tutorial in F<examples/tutorial>.
=head2 How do I compile and run a PIR module?
Parrot uses the filename extension to detect whether the file is a PIR file
-(.pir), a Parrot Assembly file (.pasm) or a pre-compiled
-bytecode file (.pbc).
+(.pir) or a pre-compiled bytecode file (.pbc).
parrot hello.pir
=head2 How do I see the assembly code that PIR generates?
-Use the -o option for Parrot. You can provide an output filename, or the -
-character which indicates standard output. If the filename has a .pbc
-extension, IMCC will compile the module and assemble it to bytecode.
-Beware that compiling to PASM is not well supported and might produce broken PASM.
-=over 4
-=item Create the PASM source from PIR.
- parrot -o hello.pasm hello.pir
-=item Compile to bytecode from PIR.
- parrot -o hello.pbc hello.pir
-=item Dump PASM to screen
- parrot -o - hello.pir
+Use the C<pbc_disassemble> executable.
=head2 Does IMCC do variable interpolation in strings?
@@ -62,16 +62,14 @@ languages.
=head2 Instruction formats
-Parrot can currently accept instructions to execute in four forms. PIR (Parrot
+Parrot can currently accept instructions to execute in three forms. PIR (Parrot
Intermediate Representation) is designed to be written by people and generated
by compilers. It hides away some low-level details, such as the way parameters
-are passed to functions. PASM (Parrot Assembly) is a level below PIR - it is
-still human readable/writable and can be generated by a compiler, but the
-author has to take care of details such as calling conventions and register
-allocation. PAST (Parrot Abstract Syntax Tree) enables Parrot to accept an
-abstract syntax tree style input - useful for those writing compilers.
+are passed to functions. PAST (Parrot Abstract Syntax Tree) enables Parrot to
+accept an abstract syntax tree style input - useful for those writing
-All of the above forms of input are automatically converted inside Parrot to
+Both of the above forms of input are automatically converted inside Parrot to
PBC (Parrot Bytecode). This is much like machine code, but understood by the
Parrot interpreter. It is not intended to be human-readable or human-writable,
but unlike the other forms execution can start immediately, without the need
@@ -226,12 +224,6 @@ C<.local> is a type. This can be C<int> (for I registers), C<float> (for N
registers), C<string> (for S registers), C<pmc> (for P registers) or the name
of a PMC type.
-=head2 PIR vs. PASM
-PASM does not handle register allocation or provide support for named
-registers. It also does not have the C<.sub> and C<.end> directives, instead
-replacing them with a label at the start of the instructions.
=head2 Summing squares
This example introduces some more instructions and PIR syntax. Lines starting
@@ -395,7 +387,7 @@ reading:
-The last line of PIR actually represents a few lines of PASM. The assembler
+The last line of PIR actually represents several opcodes. The assembler
builds a PMC that describes the signature, including which register the
arguments are held in. A similar process happens for providing the registers
that the return values should be placed in. Finally, the C<factorial> sub is
@@ -738,7 +738,7 @@ string filename or an integer argument of a UNIX file descriptor [or an
already opened stream object?], and an integer flag for the type of
information requested. It returns an integer containing the requested
information. The following constants are defined for the type of
-information requested (see F<runtime/parrot/include/stat.pasm>):
+information requested (see F<runtime/parrot/include/stat.pir>):
Whether the file exists.
@@ -135,7 +135,7 @@ packaging by installing into a separate install tree and creating a tarball
from that tree.
The B<configuration hash> is the return value of the global function
-C<_config()>, generated in F<config_lib.pasm>, and either defined in
+C<_config()>, generated in F<config_lib.pir>, and either defined in
F<library/config.pir>, or as frozen PMC embedded in the test executable
(F<config.fpmc>), the installable executable (F<install_config.fpmc>) or empty
for miniparrot (F<null_config.fpmc>).
@@ -21,7 +21,8 @@ initializer or with the B<assign> opcode to define the struct elements.
=item Datatype
-The datatype is defined by constants declared in F<datatypes.pasm>.
+The datatype is defined by constants declared in
=item Array Size
@@ -209,7 +209,7 @@ backwards-incompatible change requires deprecation:
=item * C<PARROT_API> function changes
-=item * PIR or PASM syntax changes
+=item * PIR syntax changes
=item * API changes in the compiler tools
@@ -68,9 +68,7 @@ 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. This can be handy to check
-various optimizations, including C<-Op>.
+outputfile ends with F<.pbc>, a PBC file is written.
=item --output-pbc

0 comments on commit eb1015f

Please sign in to comment.